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.

Reviewed 7 min read

On this page
  1. Seven layers between a business process and the Hedera network
  2. Accounts, keys and why signing gets its own service
  3. One business event, from submission to a reconciled record
  4. Receipts, records and retries that never double-submit
  5. Where HCS, HTS, contracts and off-ledger storage each fit
  6. Reading state: mirror nodes in production
  7. Promoting a build from a local network to mainnet
  8. Failure modes to design for, and the control for each
  9. Questions and answers
  10. 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 application01Ledger orchestration02Signing service03SDK submission04Hedera network05Mirror node read path06Internal ledger store07
  1. Business application

    The system of record users already work in: ERP, order management, registry or customer portal.

  2. Ledger orchestration

    Turns business events into Hedera transactions, tracks their state and owns retries and exceptions.

  3. Signing service

    Holds or brokers keys through an HSM or cloud KMS, applies policy and logs every signature.

  4. SDK submission

    Builds transactions with the Hedera SDK, sends them to consensus nodes and collects receipts.

  5. Hedera network

    Consensus nodes order transactions and apply HTS, HCS and smart contract state changes.

  6. Mirror node read path

    REST and gRPC queries for balances, history, topic messages and transaction outcomes.

  7. Internal ledger store

    Off-chain records, documents, hashes and the reconciliation state that ties them to network data.

Conceptual layering of an enterprise Hedera application. It illustrates responsibilities, not a specific deployment or product.

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

assign transaction IDsign requestsigned bytessubmitreceipt: statusquery by IDrecord and timestampmark settled01Orchestration02Signing service03Consensus node04Mirror node05Internal store
  1. Orchestration

    Creates the transaction and stores its ID before sending.

  2. Signing service

    Checks policy and signs.

  3. Consensus node

    Pre-checks, submits to consensus and returns a receipt.

  4. Mirror node

    Serves the confirmed outcome and record.

  5. Internal store

    Marks the event settled after matching.

  1. Orchestration to Orchestrationassign transaction ID
  2. Orchestration to Signing servicesign request
  3. Signing service to Orchestrationsigned bytes
  4. Orchestration to Consensus nodesubmit
  5. Consensus node to Orchestrationreceipt: status
  6. Orchestration to Mirror nodequery by ID
  7. Mirror node to Orchestrationrecord and timestamp
  8. Orchestration to Internal storemark settled
Conceptual message order for a single transaction. Real systems batch and parallelize these calls; the order of responsibilities stays the same.

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 needHedera serviceWhat stays off-ledger
Proof that an event happened, in orderConsensus Service topic messageThe event's full content; submit a hash or minimal envelope
A transferable entitlement or balanceToken Service fungible token or NFTCustomer identity and the legal terms behind the token
Conditional settlement or escrow rulesSmart Contract Service, calling HTS where neededInputs that require judgement, and any personal data
Approvals from several parties over timeScheduled transactions that collect signatures8The approval workflow, reminders and evidence
Documents, images and certificatesNone directly; anchor a hash through HCS or token metadataThe 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

  1. 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.

    Output
    Automated test suite
  2. 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.

    Output
    Repeatable environment scripts
  3. 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.

  4. 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.

    Output
    Signed-off runbooks
    Owner
    Operations lead
  5. 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.

    Output
    Fee budget and alert thresholds

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

  1. Transactions and queries — Hedera documentation · checked 10 October 2026
  2. Mirror nodes — Hedera documentation · checked 10 October 2026
  3. Connecting to mirror nodes — Hedera documentation · checked 10 October 2026
  4. Testnets — Hedera documentation · checked 10 October 2026
  5. Fee model — Hedera documentation · checked 10 October 2026
  6. Keys and signatures — Hedera documentation · checked 10 October 2026
  7. Governance FAQ: network throttling — Hedera documentation · checked 10 October 2026
  8. Schedule transaction — Hedera documentation · checked 10 October 2026
  9. Our Hedera Hashgraph practice — ColdAI

More in Our Hedera Hashgraph Practice

Back to Our Hedera Hashgraph Practice

Next step

Have your Hedera integration design reviewed

Send a diagram or description of the workflow, the services you plan to use and how keys are held today. We will mark up the design against this reference and list the gaps to close before mainnet.

Request an architecture review