Skip to content

docs: add HCS audit trail page under Solutions Finance Workflows - #807

Open
web3buidlerz wants to merge 5 commits into
hashgraph:mainfrom
web3buidlerz:docs/solutions-hcs-audit-trail
Open

web3buidlerz wants to merge 5 commits into
hashgraph:mainfrom
web3buidlerz:docs/solutions-hcs-audit-trail

Conversation

@web3buidlerz

@web3buidlerz web3buidlerz commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

What this adds

A second Solutions → Finance Workflows page, paired with a scaffold-hbar template that runs on testnet.

Publish a tamper-evident audit trail and regulator feed with HCS logs every compliance action on a security token (issuance, KYC, transfers, freezes) to a Hedera Consensus Service topic with a submit key. A regulator page reads the topic straight from the mirror node and verifies it itself: no sequence gaps, an unbroken hash chain across entries, and every referenced transaction real with the logged result. An outsider's submission is rejected with INVALID_SIGNATURE.

Section Covers
Overview Why a database log needs trust and an HCS topic does not; actors, lifecycle diagram, stack
Set up the audit topic Topic with admin and submit keys; a KYC- and freeze-gated token; the first issue entry
Log a token action Real HTS actions on a chosen target account, refused actions logged too, the entry format and hash chain
Read and verify the regulator feed The three checks and how they are computed from mirror node data only
What the network refuses The forgery attempt, and what HCS does and does not guarantee
Sign entries as a compliance officer with HashPack Adding a wallet to the submit key with a 1-of-2 key list; the wallet signs entries
Going to production Private payloads, admin key custody, gRPC, logging the other workflows

The paired template installs with:

npx create-scaffold-hbar@latest --template web3buidlerz/hedera-finance-templates#templates/hcs-audit-trail

Validation

  • mint broken-links — no broken links
  • .github/scripts/check-mdx-compiles.js — page compiles
  • .github/scripts/check-terminology.sh — no retired terms
  • docs.json parses as valid JSON

@mintlify

mintlify Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 073dfa0.

Approve preview

@web3buidlerz
web3buidlerz force-pushed the docs/solutions-hcs-audit-trail branch from 21f7e5f to eaccff1 Compare October 22, 2026 16:48
@web3buidlerz
web3buidlerz marked this pull request as ready for review October 27, 2026 13:31
@web3buidlerz
web3buidlerz requested review from a team as code owners October 27, 2026 13:31
@web3buidlerz
web3buidlerz marked this pull request as draft October 27, 2026 13:40
@web3buidlerz
web3buidlerz marked this pull request as ready for review October 27, 2026 14:09
Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
… one

The page's own checks had moved on. Four of its claims described the template
before it was hardened, and a page whose subject is why a trail cannot skip an
entry has to be right about how.

- Publishing is a queue, so the section now says why an entry cannot be written
  before its action, and what the queue buys: `prev` read at publish time, one
  transaction id across retries, nothing discarded.
- The regulator's Transaction check covers the kind of transaction, its token
  and its account, not only the result code — which on its own would verify a
  `freeze` entry against any successful transaction on the network. The snippet
  matches the code again.
- Confirming a wallet entry is bound to the exact prepared transaction id and
  to the bytes on the topic, and a wallet that does not publish hands the entry
  back to the Issuer rather than losing it.
- Authorising is cumulative, so the publishers list and the topic's submit key
  cannot disagree.

Also the two action buttons the spec names, and a production note that the queue
lives in memory.

Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
The template now lives in the Hedera org repo, with every branch pushed and
the name no longer carrying its capital I. The card and the install command
point there rather than at a personal fork.

Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
…ions pages

Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
@web3buidlerz
web3buidlerz force-pushed the docs/solutions-hcs-audit-trail branch 2 times, most recently from a5562af to 073dfa0 Compare October 27, 2026 15:06

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant