HCS-18 Standard: Flora Discovery Protocol
HCS-18 Standard: Flora Discovery ProtocolDirect link to HCS-18 Standard: Flora Discovery Protocol
Status: DraftDirect link to status-draft
Version: 1.0Direct link to version-10
Table of ContentsDirect link to Table of Contents
- Authors
- Abstract
- Motivation
- Terminology
- Specification
5.1. Discovery Broadcast Topic
5.2. Message Protocol
5.3. Discovery Lifecycle
5.4. Formation States
5.5. Conflict Resolution
5.6. Privacy Considerations - Security Model
- Implementation Requirements
- Examples
- References
- Change Log
AuthorsDirect link to Authors
- Kantorcodes https://twitter.com/kantorcodes
AbstractDirect link to Abstract
HCS-18 extends the HCS-2 topic registry standard to enable decentralized discovery of Petals and pre‑formation coordination for Floras. It establishes a permissionless broadcast mechanism where Petal accounts can advertise their availability, discover compatible partners, and coordinate initial acceptance.
Scope
- Discovery‑layer only:
announce/propose/respond/withdrawhappen on a public discovery topic. - Formation and ongoing governance are defined by HCS‑16. The
completeevent here is a discovery‑layer closure that references the formed Flora.
MotivationDirect link to Motivation
Multi-party collaborative systems typically assume participants already know each other's communication endpoints and have agreed on parameters. In practice, autonomous accounts need:
- Discovery - Finding other Petals with compatible goals and capabilities
- Formation - Coordinating Flora creation without prior relationships
- Membership - Managing Flora composition over time
Without a standardized discovery mechanism, Flora formation requires out-of-band coordination, limiting the potential for autonomous, permissionless networks.
TerminologyDirect link to Terminology
- Discovery Topic: A publicly readable HCS topic for discovery messages
- Announcement: A Petal's declaration of availability and capabilities
- Proposal Sequence: The HCS sequence number of a proposal message, used as a unique identifier
- Priority: A Petal's preference value (0-1000) for Flora coordination, inspired by MongoDB replica set priorities. Higher values indicate preference for leading Flora formation
SpecificationDirect link to Specification
Discovery TopicDirect link to Discovery Topic
Implementations MAY use a canonical Discovery Topic per network, listed in an HCS‑2 registry; otherwise, application‑specific discovery topics can be used for testing or private deployments.
| Network | Topic ID | Status |
|---|---|---|
| Mainnet | 0.0.XXXXX | Pending DAO vote |
| Testnet | 0.0.XXXXX | Pending deployment |
Topic Configuration (recommended):
- Submit Key: None (open submission)
- Admin Key: DAO multisig (for emergency suspension only)
- Auto-renew Account: DAO treasury
- Memo Format:
hcs-18:0:300
Memo ConfigurationDirect link to Memo Configuration
The discovery topic uses a standardized memo format:
hcs-18:<indexed>[:ttl]
| Field | Description | Example Value |
|---|---|---|
protocol_standard | Protocol identifier for this standard | hcs-18 |
indexed | Topic is indexed - all messages should be read | 0 |
ttl | Optional time-to-live in seconds for caching | 300 |
Example Topic Memo: hcs-18:0:300
OperationsDirect link to Operations
The following operations are available for discovery:
| Operation | Description | Required Fields |
|---|---|---|
announce | Petal advertises availability and capabilities | petal, capabilities |
propose | Proposes Flora formation to specific Petals | members, config |
respond | Response to a Flora proposal | proposal_seq, decision |
complete | Announces successful Flora formation | proposal_seq, flora_account_id |
withdraw | Petal withdraws from discovery | announce_seq |
Message ProtocolDirect link to Message Protocol
All messages SHALL be valid UTF-8 JSON with the following structure:
Base Message StructureDirect link to Base Message Structure
{
"p": "hcs-18", // Protocol
"op": "operation_type", // Operation
"data": {} // Operation-specific data
}
Transaction memo (recommended analytics):
hcs-18:op:<operationEnum>
Operation enum values
| Operation | Enum |
|---|---|
announce | 0 |
propose | 1 |
respond | 2 |
complete | 3 |
withdraw | 4 |
Operation: announceDirect link to operation-announce
Petal advertises its availability and capabilities.
Field BreakdownDirect link to Field Breakdown
| Field | Type | Required | Description |
|---|---|---|---|
petal | object | Yes | Petal identification and metadata |
petal.account | string | Yes | Hedera account ID of the Petal |
petal.name | string | Yes | Human-readable name for the Petal |
petal.priority | number | Yes | Priority value (0-1000) for Flora coordination preference |
uaid | string | No | Optional UAID (HCS‑14) for resolvable identity |
capabilities | object | Yes | Technical and operational capabilities |
capabilities.protocols | array | Yes | List of supported protocols for Flora operations |
capabilities.resources | object | No | Available computational resources |
capabilities.resources.compute | string | No | Compute capacity: "high", "medium", or "low" |
capabilities.resources.storage | string | No | Storage capacity: "high", "medium", or "low" |
capabilities.resources.bandwidth | string | No | Network capacity: "high", "medium", or "low" |
capabilities.group_preferences | object | No | Preferred group configurations |
capabilities.group_preferences.sizes | array | No | Acceptable group member counts (e.g., [3, 5, 7]) |
capabilities.group_preferences.threshold_ratios | array | No | Acceptable consensus threshold ratios (e.g., [0.67, 0.75]) |
valid_for | number | No | Number of HCS messages this announcement remains valid (default: 10000) |
Example:
{
"p": "hcs-18",
"op": "announce",
"data": {
"petal": {
"account": "0.0.123456",
"name": "Node-Alpha-1",
"priority": 750 // 0-1000, higher = preferred for Flora coordination
},
"uaid": "uaid:aid:z...", // Optional: HCS‑14 universal agent id
"capabilities": {
"protocols": ["hcs-11", "custom-consensus-v1"], // Any protocols the participant supports
"resources": {
"compute": "high|medium|low",
"storage": "high|medium|low",
"bandwidth": "high|medium|low"
},
"group_preferences": {
"sizes": [3, 5, 7],
"threshold_ratios": [0.67, 0.75]
}
},
"valid_for": 10000 // Announcement valid for next 10k messages
}
}
Transaction Memo: hcs-18:op:0
Operation: proposeDirect link to operation-propose
Proposes Flora formation to specific Petals. The HCS sequence number of this message becomes the proposal identifier.
Field BreakdownDirect link to Field Breakdown
| Field | Type | Required | Description |
|---|---|---|---|
members | array | Yes | List of proposed Flora members |
members[].account | string | Yes | Hedera account ID of the member |
members[].announce_seq | number | Conditional | Sequence number of member's announcement (required for new members) |
members[].priority | number | Yes | Member's priority value from their announcement |
members[].status | string | No | "existing" or "proposed" (for replacements) |
config | object | Yes | Flora configuration parameters |
config.name | string | Yes | Human-readable Flora name |
config.threshold | number | Yes | Number of signatures required for Flora operations |
config.purpose | string | No | Description of Flora's intended use |
config.reason | string | No | Reason for proposal (e.g., for replacements) |
existing_flora | string | No | Account ID of existing Flora (for member replacement) |
Example (New Flora):
{
"p": "hcs-18",
"op": "propose",
"data": {
"members": [
{ "account": "0.0.234567", "announce_seq": 12340, "priority": 500 },
{ "account": "0.0.345678", "announce_seq": 12342, "priority": 750 },
{ "account": "0.0.456789", "announce_seq": 12344, "priority": 1000 }
],
"config": {
"name": "ConsensusFlora-Beta",
"threshold": 2, // 2 of 3 required for decisions
"purpose": "Distributed ML training"
}
}
}
// This message gets sequence number 12345, which becomes the proposal ID
Transaction Memo: hcs-18:op:1
Example (Member Replacement):
{
"p": "hcs-18",
"op": "propose",
"data": {
"existing_flora": "0.0.789012", // Optional: indicates this is for an existing Flora
"members": [
{ "account": "0.0.234567", "priority": 500, "status": "existing" },
{ "account": "0.0.345678", "priority": 750, "status": "existing" },
{
"account": "0.0.999999",
"announce_seq": 12350,
"priority": 600,
"status": "proposed"
}
],
"config": {
"threshold": 2,
"reason": "replacing_0.0.456789"
}
}
}
Operation: respondDirect link to operation-respond
Response to a Flora proposal, referencing it by HCS sequence number.
Field BreakdownDirect link to Field Breakdown
| Field | Type | Required | Description |
|---|---|---|---|
proposal_seq | number | Yes | HCS sequence number of the proposal being responded to |
decision | string | Yes | "accept" or "reject" |
reason | string | No | Explanation for rejection (recommended for "reject") |
accepted_seq | number | No | Sequence number of accepted proposal (when rejecting due to conflict) |
Example:
{
"p": "hcs-18",
"op": "respond",
"data": {
"proposal_seq": 12345, // Sequence number of the proposal message
"decision": "accept" // or "reject"
}
}
Transaction Memo: hcs-18:op:2
Operation: completeDirect link to operation-complete
Announces successful Flora formation, referencing the original proposal.
Field BreakdownDirect link to Field Breakdown
| Field | Type | Required | Description |
|---|---|---|---|
proposal_seq | number | Yes | HCS sequence number of the original proposal |
flora_account_id | string | Yes | Newly created Flora account ID |
topics | object | Yes | HCS topic IDs for Flora operations |
topics.communication | string | Yes | Communication topic ID for the Flora |
topics.transaction | string | Yes | Transaction coordination topic ID |
topics.state | string | Yes | State synchronization topic ID |
Example:
{
"p": "hcs-18",
"op": "complete",
"data": {
"proposal_seq": 12345, // Original proposal sequence number
"flora_account_id": "0.0.789012",
"topics": {
"communication": "0.0.890123",
"transaction": "0.0.901234",
"state": "0.0.912345"
}
}
}
Transaction Memo: hcs-18:op:3