HCS Audit Trail

​

Overview

• Every message gets a sequence number, a consensus timestamp and a running hash from the network. A missing message shows up as a gap; an edited one cannot exist.
• A topic created with a submit key accepts messages only from the holders of that key. Anyone else is rejected by the network.
• Anyone can read the topic through the public mirror node, with no account and no access to your systems.

• Issuer: the operator account the app runs with. Creates the audit topic and a security token, performs token actions, and publishes an audit entry for each one
• Compliance officer (optional): a HashPack account the Issuer authorises as a publisher. Signs and submits the audit entries instead of the Issuer
• Regulator: reads the trail from the mirror node. Holds no keys and needs no account

1. The Issuer creates the audit topic with a submit key, and a security token with KYC and freeze keys
2. The Issuer performs token actions on a target account: grant KYC, transfer, freeze, unfreeze
3. Each action is logged as an audit entry carrying the action’s transaction id, its result, and the hash of the previous entry
4. The Regulator’s feed reads the topic from the mirror node and verifies it: no sequence gaps, an unbroken hash chain, every referenced transaction real with the logged result
5. Anyone else who tries to publish is rejected by the network

Issuer / Compliance officer          Hedera network                     Regulator (mirror node only)
        |                                  |                                       |
        |-- TokenGrantKyc ---------------->|  txId, result                         |
        |-- TopicMessageSubmit(            |                                       |
        |     event, txId, result, prev) ->|  seq N, consensus time, running hash  |
        |                                  |<-------- GET /topics/{id}/messages ---|
        |                                  |   verify: sequence, hash chain, txId  |
Outsider -- TopicMessageSubmit ----------->|  INVALID_SIGNATURE (rejected)         |

​

Prerequisites

• Node.js 20.18 or later, and Yarn
• A Hedera testnet account from the Hedera Portal. It becomes the Issuer. Its key can be a raw ECDSA key in hex, or a DER-encoded ECDSA or ED25519 key.
• Testnet HBAR on that account. Setting up an audit trail costs about 14 HBAR, almost all of it the network fee for creating the token; each action and its entry cost a fraction of an HBAR.
• Optional, for Sign entries with HashPack: the HashPack browser extension with a testnet account other than the Issuer, and a WalletConnect project id from the Reown dashboard

​

Project structure

packages/nextjs/
  app/page.tsx                            the issuer's desk: setup, actions, forgery attempt, trail
  app/regulator/page.tsx                  the regulator's feed; reads only the mirror node
  app/api/hedera/audit/                   server routes; all Issuer signing happens here
    setup/route.ts                        topic, token, holder account, first entry
    action/route.ts                       perform an action and publish its entry
    action/prepare/route.ts               build an entry for HashPack to sign
    action/confirm/route.ts               confirm HashPack's submission, then advance the chain
    authorize/route.ts                    add a wallet to the topic's submit key
    forge/route.ts                        an outsider's submission, to show the rejection
  services/hcsAudit/entry.ts              entry format and hashing, shared by publisher and verifier
  services/hcsAudit/verify.ts             the regulator's checks

​

Configuration

# The Issuer. Server-side only, never sent to the browser.
HEDERA_OPERATOR_ID=0.0.1234
HEDERA_OPERATOR_KEY=<ECDSA hex key, or a DER-encoded ECDSA/ED25519 key>

# Optional: enables Sign entries with HashPack
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=<your Reown project id>

yarn install
yarn next:dev   # http://localhost:3000

​

Set up the audit topic

​

Step 1: Create the topic with a submit key

const response = await new TopicCreateTransaction()
  .setAdminKey(operatorKey.publicKey)
  .setSubmitKey(operatorKey.publicKey)
  .setTopicMemo("HCS audit trail")
  .execute(client);
const topicId = (await response.getReceipt(client)).topicId;

​

Step 2: Create the security token and a holder

​

Log a token action

​

Step 1: Perform the action

​

Step 2: Queue and publish the audit entry

export function serializeEntry(entry: AuditEntry): Uint8Array {
  const ordered = {
    v: entry.v, event: entry.event, token: entry.token, account: entry.account,
    amount: entry.amount, tx: entry.tx, result: entry.result, prev: entry.prev,
  };
  return new TextEncoder().encode(JSON.stringify(ordered));
}

// The action has run; its entry joins the queue and the chain has not moved yet.
queueEntry(desk, { event: "grant_kyc", token, account, amount: null, tx, result });

// One flush at a time, oldest entry first.
while (desk.entries.length > 0) {
  const queued = desk.entries[0];
  const bytes = serializeEntry({ v: 1, prev: desk.lastHash, ...queued.fields }); // prev read here, not earlier
  queued.transactionId ??= TransactionId.generate(operatorId).toString();        // same id on every retry
  await submit(bytes, queued.transactionId);
  desk.lastHash = await sha256Hex(bytes);                                        // only after it landed
  desk.entries.shift();
}

• prev is read when an entry is published, not when it is built. Two actions in flight therefore cannot be chained onto the same prev — which would land two messages claiming the same position and show BROKEN.
• A submission keeps one transaction id across retries. A response lost after the network accepted it would otherwise publish the entry twice; the resubmission is refused as a duplicate instead, and the receipt is queried to find out what happened.
• Nothing discards a queued entry. A failed submission, a declined signature or an unreachable mirror node are retried until the entry is on the topic.

​

Read and verify the regulator feed

• Sequence: sequence numbers run 1, 2, 3… with no gap, so nothing was deleted
• Chain: the entry’s prev equals the SHA-256 of the previous message’s exact bytes, so nothing was edited or reordered
• Transaction: the referenced transaction exists on the mirror node with the result the entry claims, and is the kind of transaction the event implies, against the entry’s own token and account — a freeze entry must point at a TOKENFREEZE of that token, a successful transfer at a CRYPTOTRANSFER whose legs credit that amount of that token to that account. Checking the result code alone would let an authorised publisher log freeze / SUCCESS against any successful transaction on the network

for (let i = 0; i < messages.length; i++) {
  const bytes = base64ToBytes(messages[i].message);
  const entry = parseEntryBytes(bytes);
  const sequenceOk = messages[i].sequence_number === i + 1;
  const chainOk = entry !== null && entry.prev === (prevBytes ? await sha256Hex(prevBytes) : ZERO_HASH);
  const mirrorTx = entry && (await fetchMirrorTransaction(entry.tx));
  const txOk = entry !== null && transactionMismatch(entry, mirrorTx) === null; // result, kind, token, account
  prevBytes = bytes;
}

​

What the network refuses

​

Sign entries as a compliance officer with HashPack

1. Authorise as publisher. The Issuer reads the wallet’s public key from the mirror node and changes the topic’s submit key to a key list that accepts either key, signing with the topic’s admin key:
   // Cumulative: every wallet authorised so far, so the list on the page and the key on
   // the topic cannot disagree about who may publish.
   const submitKey = new KeyList([operatorKey.publicKey, ...walletKeys], 1); // threshold 1: any one of them
   await (await new TopicUpdateTransaction().setTopicId(topicId).setSubmitKey(submitKey).execute(client)).getReceipt(client);
   
2. Perform an action. The Issuer still performs the token action on the server and builds the entry with the correct prev. HashPack signs and submits the topic message as the payer.
3. Confirmation. The prepared entry is bound to the exact transaction id frozen into the transaction the wallet was handed, and only that id can confirm it. The server then checks, from the mirror node, that the transaction was a message submit to this topic, paid by that wallet, and succeeded — and that the bytes now on the topic are the bytes it prepared. Only then does the chain advance. A successful transaction from that account is not enough on its own. An older or different message from the same wallet would otherwise advance the chain to the hash of bytes that are not on the topic at all, and every entry after it would fail its prev check.
4. If the wallet does not publish it, the Issuer does. A declined signature, a submission the network refuses, a mirror node that never shows the transaction: the entry stays queued and the Issuer — always an authorised publisher — publishes it instead. The action happened, so its entry is not optional. Before taking an entry back, the server checks the topic for the prepared bytes, because a confirmation that failed on a slow mirror node must not become a second copy of an entry that did land.

​

Going to production

• The queue lives in memory: a server restart with entries still queued loses them, though everything that reached the topic stays verifiable. A real desk persists the queue, or derives what is missing by comparing the chain against its own records.
• Private payloads: the topic is public. For sensitive data, publish only a hash of each record and keep the record off-chain, or encrypt entries to the regulator’s key.
• Admin key: hold the topic’s admin key in a threshold key, so no single person can change who may publish.
• Lower latency: subscribe to the topic over gRPC, or run your own mirror node, instead of polling the REST API.
• Shared plumbing: log the other Finance Workflows to the same topic, such as each DvP settlement or coupon payment.
• Custody: sign with a custody provider or HSM rather than a key in an environment variable.

​

Next steps