ArchitectureHedera Consensus Service (HCS)
Hedera Consensus Service topic design, from keys to an independent verifier
Most HCS design mistakes start with the submission code. This reference starts instead from the verifier, the party who must later check a message without your help, and works back through topic layout, keys, message envelopes, size limits, submission, replay and the verification routine itself. Each section names the trade-off and the limits to confirm against current Hedera documentation.
On this page
- Start from what a third party must be able to check
- Topic layout: one per workflow, per tenant or per asset class
- Keys, fees and other topic settings
- Fields in a versioned message envelope
- Message size, chunking and keeping content off-ledger
- A submission path that survives retries
- One evidence message, from event source to verifier
- What the independent verifier checks
- Reading and replay: conditions every reader must handle
- Questions and answers
- Sources
Start from what a third party must be able to check
An HCS message is only useful as evidence if someone outside your system can confirm three things: that a specific record produced the digest in the message, that the message was accepted on a named topic at a particular consensus time and position, and that nothing is missing around it. Write those checks down before choosing a topic layout.
The written checks become a contract: which data the verifier receives from you (the record and its salt), which it reads from the network (the message, consensus timestamp, sequence number and running hash), and what it reports when the two disagree. Every decision below either makes those checks possible or makes them harder.
Topic layout: one per workflow, per tenant or per asset class
| Consideration | Topic per workflow | Topic per tenant | Topic per asset class |
|---|---|---|---|
| Typical fit | One process shared by its participants, such as proof of delivery on a trade lane | A platform serving customers who must not see each other's activity patterns | A registry where each product line or asset family keeps its own history |
| Privacy of activity | Participants see each other's message timing and volume | One tenant's activity is never mixed with another's | Reveals which asset families are active and when |
| Write access | One submit-key policy covering all participants | A submit key scoped to each tenant | A submit key per issuing team or system |
| Ordering you get | One sequence across everyone in the workflow | Order only within each tenant | Order only within each asset family |
| Operating load | Few topics to monitor | Topic count grows with customers, so automate creation and key rotation | Moderate; topics follow product changes |
Sequence numbers are per topic. If two events must be ordered against each other, put them on the same topic; consensus timestamps let you compare messages across topics, but sequence continuity checks work only within one.
Keys, fees and other topic settings
Hedera keys can be single keys, key lists or threshold keys, so authority over a topic can be split between people or organisations1.
- Admin key
- Authorises updating and deleting the topic. Without one, nobody can delete the topic or change its keys, which suits evidence logs whose rules should never move2.
- Submit key
- If set, every message must be signed with it; if absent, anyone may submit2. For multi-party evidence, a threshold key or a key list makes explicit who may write, while reading stays open through mirror nodes.
- Fee schedule key and custom fees
- Under HIP-991 a topic can charge a fixed fee per message in HBAR or an HTS fungible token, with fee-exempt keys for chosen submitters3. The fee schedule key must be set when the topic is created and cannot be added later2, so decide at creation whether fees might ever be needed.
- Auto-renew account
- The account that would fund extending the topic's lifetime at expiry. Hedera's documentation notes that rent is not currently enforced for topics2, but naming an owner now avoids surprises if that changes.
Fields in a versioned message envelope
Keep every message to a small, versioned envelope, in JSON or Protocol Buffers. These fields cover most evidence workflows.
Message size, chunking and keeping content off-ledger
A single HCS message is limited to 1,024 bytes, and the SDKs can split a larger payload into chunks, by default up to twenty of them4. Chunking exists, but evidence designs rarely need it: each chunk is a separate transaction with its own consensus timestamp, readers must reassemble the parts, and one missing chunk leaves the whole payload unusable.
If content does not fit in an envelope, store it off-ledger behind a hash pointer, or batch many records into a Merkle tree and submit only the root, as Hedera's own anchoring tutorial does5. Encrypting payloads onto a topic is a different bargain: the ciphertext is public and permanent, so its protection lasts only as long as the encryption does. Digest-only messages avoid that exposure.
A submission path that survives retries
Canonicalise and hash
Serialise the record by a documented rule, such as sorted keys and a fixed encoding, and compute the digest. Store record, salt and digest together before anything touches the network.
Derive the correlation ID from the event
Base the identifier on the business event rather than on the attempt, so a retried submission is recognisable as the same fact.
Submit and keep the receipt
Submit the envelope and record the transaction ID. A successful receipt returns the topic's new sequence number and running hash; store both beside the record.
Resolve uncertain outcomes before resubmitting
When a submission times out, look up the transaction ID first. Resubmit only if the network has no record of it, and reuse the same correlation ID either way.
Reconcile on a schedule
Compare stored receipts with messages read back from a mirror node, flagging any business event without a message and any message without a business event.
One evidence message, from event source to verifier
- Event source
The authoritative system where the business event is recorded and hashed.
- Submission service
Signs envelopes with the submit key and talks to the network.
- HCS topic
Assigns the consensus timestamp, sequence number and running hash.
- Mirror node
Serves topic history to readers; chosen by each verifier.
- Evidence store
Holds records, salts and receipts under your retention rules.
- Independent verifier
Recomputes digests and checks continuity without trusting the submitter.
- Event source to Evidence storeRecord, salt, digest
- Event source to Submission serviceEnvelope to submit
- Submission service to HCS topicSubmit message
- HCS topic to Submission serviceReceipt: seq and hash
- Submission service to Evidence storeStore receipt
- HCS topic to Mirror nodeRecord stream
- Independent verifier to Evidence storeFetch record and salt
- Independent verifier to Mirror nodeRead message
What the independent verifier checks
The verifier is a small program that any participant, auditor or regulator can run. Given a record and its salt, it recomputes the digest using the rules for the schema version named in the envelope, fetches the message by topic and sequence number from a mirror node of the verifier's choosing, and confirms the digests match.
It then checks continuity: neighbouring sequence numbers are contiguous, the consensus timestamp falls within the window the business process allows, and the running hash a mirror node reports matches the one stored from the original receipt. Because each message is folded into the topic's running hash, a mirror node serving altered history would show up as a mismatch.
Any mismatch is reported, never repaired, with the expected and observed values and the mirror node queried, so it can be investigated with the evidence intact.
Reading and replay: conditions every reader must handle
Mirror nodes serve topic messages over a REST API, which Hedera's anchoring tutorial queries directly5, and the SDKs offer a streaming subscription over gRPC.
Gaps in what a reader has seen
Early signalAfter a reconnect, the next sequence number is higher than the last one processed.
MitigationTrack the last sequence number per topic and backfill through the REST API before resuming the stream.
Duplicate business events
Early signalTwo messages carry the same correlation ID after a retry.
MitigationTreat the earlier message by consensus timestamp as authoritative and report the later one as a duplicate, not a new fact.
Ordering by arrival
Early signalDownstream records follow the order in which a reader happened to receive messages.
MitigationOrder by sequence number within a topic and by consensus timestamp across topics.
Production reads from the free public mirror node
Early signalReaders call a shared endpoint that has no service agreement.
MitigationHedera describes its free public mirror node as meant for testing and development5; use a commercial provider or your own node, and keep copies of messages and receipts.
Questions and answers
Can an HCS topic be private?
A submit key restricts who can write, and Hedera's documentation calls such a topic private, but messages on mainnet remain readable by anyone through mirror nodes2. Confidentiality therefore comes from what you submit: digests, salted hashes or, with care, ciphertext. If participants must not even see each other's message timing, use separate topics or consider a permissioned network such as HashSphere.
How long do mirror nodes keep topic messages?
Retention is set by whoever operates the mirror node, so there is no single answer. Hedera's free public mirror node is meant for testing and development, and commercial providers publish their own terms. For evidence that must outlive any provider, keep every message and receipt in your own store, or run a mirror node configured to retain the topics you depend on.
Should we run our own mirror node?
Run one when verification is business-critical, when you need history on your own retention terms, or when rate limits on shared services would slow replay. Anyone can run the mirror node software, and Hedera charges nothing for doing so, although hardware and hosting costs apply6. Many teams start with a commercial provider and add their own node once volumes and retention needs are clear.
Can we change the message schema after launch?
Yes, provided the envelope carried a schema version from the first message. Publish each version's parsing and hashing rules alongside the verifier, never reinterpret old messages under new rules, and have readers reject versions they do not recognise rather than guessing.
Sources
- For EVM developers migrating to Hedera (key types: ED25519, ECDSA, key lists and threshold keys) — Hedera documentation · checked 10 October 2026
- Create a topic — Hedera documentation · checked 10 October 2026
- HIP-991: Permissionless revenue-generating Topic Ids for Topic Operators — Hiero Improvement Proposals · checked 10 October 2026
- Submit a message — Hedera documentation · checked 10 October 2026
- Batch anchoring and verification with HCS — Hedera documentation · checked 10 October 2026
- Mirror nodes — Hedera documentation · checked 10 October 2026