ArchitectureOur Hedera Hashgraph Practice
A reference architecture for enterprise applications on Hedera
An enterprise application on Hedera is mostly ordinary software: a business system, a signing service, a submission component, a read path through mirror nodes and an internal store that reconciles against the network. The ledger-specific design work sits in four places: who holds keys, how transactions are retried without duplication, where state is read from, and which Hedera service carries each part of the workflow.
On this page
- Seven layers between a business process and the Hedera network
- Accounts, keys and why signing gets its own service
- One business event, from submission to a reconciled record
- Receipts, records and retries that never double-submit
- Where HCS, HTS, contracts and off-ledger storage each fit
- Reading state: mirror nodes in production
- Promoting a build from a local network to mainnet
- Failure modes to design for, and the control for each
- Questions and answers
- Sources
Seven layers between a business process and the Hedera network
This is the shape ColdAI starts from at the integrate-the-workflow stage, where account management, signing and network receipts are connected to the business application9.
- Business application
The system of record users already work in: ERP, order management, registry or customer portal.
- Ledger orchestration
Turns business events into Hedera transactions, tracks their state and owns retries and exceptions.
- Signing service
Holds or brokers keys through an HSM or cloud KMS, applies policy and logs every signature.
- SDK submission
Builds transactions with the Hedera SDK, sends them to consensus nodes and collects receipts.
- Hedera network
Consensus nodes order transactions and apply HTS, HCS and smart contract state changes.
- Mirror node read path
REST and gRPC queries for balances, history, topic messages and transaction outcomes.
- Internal ledger store
Off-chain records, documents, hashes and the reconciliation state that ties them to network data.
Accounts, keys and why signing gets its own service
Every Hedera transaction is paid for by an account and authorized by signatures that satisfy the keys involved: the payer, and any account, token or topic key the transaction touches. Keys can be single keys, key lists or nested threshold structures, and ECDSA secp256k1 is the recommended type for new accounts6.
Separate the signing service from the business application for three reasons. Policy lives in one place, so the rule that a mint above a threshold needs a second approver is enforced before any signature exists. Key material stays inside an HSM or KMS boundary that the application never sees. And every signature produces an audit event that can later be matched with the network's own record.
Use different payer accounts for different workloads. A dedicated fee account per application, funded by treasury with alerts on low balance, keeps one runaway integration from draining the HBAR that every other flow depends on.
One business event, from submission to a reconciled record
- Orchestration
Creates the transaction and stores its ID before sending.
- Signing service
Checks policy and signs.
- Consensus node
Pre-checks, submits to consensus and returns a receipt.
- Mirror node
Serves the confirmed outcome and record.
- Internal store
Marks the event settled after matching.
Receipts, records and retries that never double-submit
A Hedera transaction ID combines the paying account with the transaction's valid start time, and the network uses it to detect duplicate submissions1. That makes it a natural idempotency key: generate it once, persist it with the business event before submitting, and resubmit the same signed bytes when a call times out. A fresh ID on retry is how one payment becomes two.
Transactions are valid for a window of up to 180 seconds from their valid start; if consensus is not reached inside it, the transaction expires and must be rebuilt and re-signed1. Receipts are free and records carry the fuller outcome, but the network keeps both for only a short period, so long-term evidence should come from mirror nodes12. Retry logic therefore has three branches: resubmit unchanged while the window is open, rebuild after expiry, and stop for a person when the status is a business failure rather than a transport one.
All network services are throttled, on previewnet, testnet and mainnet alike7. Treat a throttling response as back-pressure: back off, keep the queue in the orchestration layer and alert when it grows, rather than letting each caller retry independently.
Where HCS, HTS, contracts and off-ledger storage each fit
| Application need | Hedera service | What stays off-ledger |
|---|---|---|
| Proof that an event happened, in order | Consensus Service topic message | The event's full content; submit a hash or minimal envelope |
| A transferable entitlement or balance | Token Service fungible token or NFT | Customer identity and the legal terms behind the token |
| Conditional settlement or escrow rules | Smart Contract Service, calling HTS where needed | Inputs that require judgement, and any personal data |
| Approvals from several parties over time | Scheduled transactions that collect signatures8 | The approval workflow, reminders and evidence |
| Documents, images and certificates | None directly; anchor a hash through HCS or token metadata | The files themselves, under your retention policy |
A single application commonly uses two or three of these. The deeper design for each service is on its own page in the Hedera practice.
Reading state: mirror nodes in production
Consensus nodes process transactions; mirror nodes store history and answer queries, without taking part in consensus, and anyone can run one2. Hedera hosts public REST and gRPC mirror endpoints, but describes the mainnet one as non-production and rate-limits it per IP address, pointing production users to commercial providers or their own deployment3.
For most enterprises the choice is between a commercial mirror provider and a self-run node. A provider is faster to adopt; a self-run node gives you control over retention, query patterns and data residency, at the cost of storage and operations. Either way, abstract the read path behind your own interface so you can switch, and reconcile network state against the internal store on a schedule. The accounting side of that reconciliation is covered in reconciling Hedera transactions with your ERP.
Promoting a build from a local network to mainnet
Develop against a local network
Run a local Hedera network for unit and integration tests. It does not reset or throttle like the shared networks, so tests stay repeatable4.
Validate on testnet
Testnet is the shared, production-equivalent environment. It is reset periodically, after which account IDs change while keys persist, so script account and token setup instead of recording IDs by hand4.
Check upcoming changes on previewnet
Use previewnet only to test features that are not yet on mainnet. It runs code under development, so do not rely on it for stable acceptance testing4.
Rehearse operations
Before mainnet, rehearse key rotation, a payer account running low, a throttled period and a mirror provider outage, and confirm each runbook works.
Go live with budgets and alerts
Fees are set in USD and charged in HBAR at the network exchange rate5. Budget per workload in USD, hold an HBAR buffer in each payer account and alert on both balance and spend rate.
Failure modes to design for, and the control for each
Duplicate business effects after a timeout
Early signalTwo transactions on the network for one internal event.
MitigationPersist the transaction ID first and resubmit the same signed bytes; never regenerate on retry.
Expired transactions during an outage or queue backlog
Early signalExpiry statuses cluster after a spike in latency.
MitigationSign as late as possible, keep valid start times close to submission and rebuild expired items automatically.
Reads lag behind writes
Early signalUsers see an old balance just after a confirmed transfer.
MitigationShow the receipt status immediately and let the mirror-based view catch up, labeling pending items clearly.
Network maintenance or upgrades
Early signalA scheduled upgrade window on the status page overlaps a business deadline.
MitigationSubscribe to network status notices and let the orchestration queue absorb the window instead of failing user actions.
Questions and answers
Do we need to run our own Hedera mirror node?
Not necessarily. Many teams start with a commercial mirror node provider. Running your own makes sense when you need long retention under your control, heavy or unusual query patterns, or specific data residency. Avoid building production systems on Hedera's public mainnet mirror endpoint, which Hedera describes as non-production and rate-limits per IP address.
How do we rotate keys on a Hedera account without downtime?
Add the new key alongside the old one first, for example by moving to a threshold or key list that accepts either, update the signing service to use the new key, confirm transactions succeed, and only then remove the old key. The account update needs signatures that satisfy both the current key and the new one, so plan the ceremony in advance.
Can a Hedera integration run across several cloud regions?
Yes. Hedera itself is a global network, so the regional design is about your own components. Run orchestration and signing in more than one region, keep a single source of truth for transaction IDs so two regions never submit the same event differently, and make sure each region can reach both consensus nodes and your mirror provider.
Sources
- Transactions and queries — Hedera documentation · checked 10 October 2026
- Mirror nodes — Hedera documentation · checked 10 October 2026
- Connecting to mirror nodes — Hedera documentation · checked 10 October 2026
- Testnets — Hedera documentation · checked 10 October 2026
- Fee model — Hedera documentation · checked 10 October 2026
- Keys and signatures — Hedera documentation · checked 10 October 2026
- Governance FAQ: network throttling — Hedera documentation · checked 10 October 2026
- Schedule transaction — Hedera documentation · checked 10 October 2026
- Our Hedera Hashgraph practice — ColdAI