Hkchain

Hkchain — Architecture

Layering

Hkchain is a Cosmos SDK blockchain composed of four custom modules alongside an EVM execution layer, served through standard Cosmos RPC/REST and Ethereum JSON-RPC endpoints. Off-chain services consume these endpoints to present role-tailored interfaces. Network fees, staking and governance use the native token HKC (base denomination ahkc), which is deliberately separate from the regulated HKD stablecoins and sits outside the compliance perimeter.

┌──────────────────────────────────────────────────────────────────────────┐
│  OFF-CHAIN                                                               │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐         │
│  │ Dashboard   │ │ Explorer    │ │ Onboarding  │ │ payx402     │         │
│  │ /dashboard  │ │ /explorer   │ │ portal      │ │ HTTP 402    │         │
│  │ (Next.js)   │ │ (Next.js)   │ │ (Go)        │ │ demo (Go)   │         │
│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘         │
└─────────┼───────────────┼───────────────┼───────────────┼────────────────┘
          ▼               ▼               ▼               ▼                 
┌──────────────────────────────────────────────────────────────────────────┐
│  ON-CHAIN  (hkchaind)                                                    │
│  ┌──────────────────────── Application Layer ─────────────────────────┐  │
│  │  AnteHandler decorator chain, run on supported HKD transfers:      │  │
│  │  KycGate -> Sanctions -> TravelRule -> Threshold -> Velocity ->    │  │
│  │  RoleGate -> AgentPolicy                                           │  │
│  │                                                                    │  │
│  │  x/stablecoin  hkd.* supply: mint, distribute, burn, pause, freeze │  │
│  │  x/compliance  gates, audit log, Travel Rule registry,             │  │
│  │                sub-roles, agent policies, flag workflow            │  │
│  │  x/reserve     attestations, auditors, daily statements            │  │
│  │  x/kyc         identity registry (six levels), blacklisting        │  │
│  │                                                                    │  │
│  │  cross-module interaction is via keeper calls only                 │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ┌──────────────────────────── EVM Layer ─────────────────────────────┐  │
│  │  cosmos/evm v0.6.0                                                 │  │
│  │  └─ one extended ERC-20 precompile per hkd.<issuer> denom          │  │
│  │     (app.HKDTokenPairs). Vanilla transfer / transferFrom           │  │
│  │     revert; transferWithTravelRule runs the same compliance        │  │
│  │     decorators, then the upstream bank-send path.                  │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ┌──────────────────────────── Consensus ─────────────────────────────┐  │
│  │  CometBFT, permissioned validators -> Algorand Pure-PoS (roadmap)  │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ┌───────────────────────────── Network ──────────────────────────────┐  │
│  │  P2P    JSON-RPC (EVM)    gRPC + REST (Cosmos)    WebSocket        │  │
│  └────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘

Why native modules, not smart contracts

Three reasons:

  1. Chain-level enforcement: a rule in an AnteHandler decorator runs before a transaction takes effect, whichever application submitted it. It applies on every supported HKD transfer path, native and EVM; Compliance model states the exact perimeter and its current limits. A smart contract's checks, by contrast, can be bypassed by any path that does not call the contract.
  2. Inter-module efficiency: modules call each other via typed keeper interfaces. No cross-contract gas or reentrancy.
  3. Role primitives: AnteHandler integration with role and KYC lookups is cleaner in module code than in Solidity.

ERC-20 compatibility comes from a Go precompile, not a Solidity contract. Each issuer denomination (for example hkd.hsbc and hkd.anch) is served at its own deterministic EVM address through an extended ERC-20 interface. The list of denominations with an EVM address is fixed in the node software (app.HKDTokenPairs), so giving a new issuer an EVM representation requires a software release. Read methods and approve behave as in any ERC-20, so wallets such as MetaMask show balances normally. The standard transfer and transferFrom revert with a message pointing to the extended methods, because they cannot carry Travel Rule evidence. transferWithTravelRule and transferFromWithTravelRule take a Travel Rule payload, build the equivalent native MsgSend, run the same compliance decorator slice as the native path, and only then delegate to the upstream bank-send path. On the EVM path the gates run during execution, so a compliance failure is a revert inside a mined transaction rather than a rejection at admission.

The AnteHandler decorator chain

Each Cosmos transaction passes the standard checks (well-formedness, fee floor, fee deduction, signature verification) and then an ordered chain of compliance decorators. The chain runs when the transaction enters a node's pool of pending transactions and again when its block executes, so a transaction whose parties changed status in between fails at execution. The decorators act on the transfers they recognise: an hkd.* coin carried by MsgSend, MsgDistribute or MsgBurn, plus the send built by the extended ERC-20 methods. Native ahkc transfers and other message types produce no compliance fact and pass through; Compliance model states the perimeter.

  1. KycGateDecorator (blocking): reject if the sender (resolved to its principal when it is a delegated key) or the recipient is blacklisted.
  2. SanctionsDecorator (blocking): reject if either party's registered institution (VASP) identifier is on the sanctioned-institution list. Address-level sanctions are applied as blacklisting and caught by gate 1.
  3. TravelRuleDecorator (blocking): for a transfer with a counterparty, require a Travel Rule payload whose declared tier matches the sender's registered tier and suffices for the amount, and whose institution identifiers (full tier) or record hashes (minimal tier) match the registry. At or above HKD 8,000 the full tier is required. One payload covers one transfer.
  4. ThresholdDecorator (advisory): flag transfers at or above the enhanced-information threshold (HKD 8,000, a rule parameter set by the compliance authority) for review. Never rejects.
  5. VelocityDecorator (advisory): flag a sender that reaches the configured number of transfers within the rolling window. Never rejects.
  6. RoleGateDecorator (blocking): if the signer is a delegated sub-key, verify the message type is within its role. It inspects MsgSend and the compliance administrative messages; other message types fall through to the authority checks in their own handlers (a mint, for example, must be signed by the issuer itself).
  7. AgentPolicyDecorator (blocking): for an hkd.* transfer signed by an agent sub-key, enforce the principal's policy envelope (per_tx_cap, daily_cap, revoked). The daily cap applies to a fixed 24-hour window that starts at the agent's first spend. This is the chain-level primitive behind must-show #9.

Gates 1 to 4 resolve delegated keys to their principals before any identity lookup, so a delegate never exceeds its principal's level.

A trace recorder wraps the chain and stores, for each evaluated transaction, every gate's result, a regulator-legible reason and the gas it consumed. The trace is held in a node-local ring buffer: it is not consensus state, its retention is bounded, and it exists only on nodes that processed the transaction. It is queryable by transaction hash (TxTrace), and SimulateTrace evaluates candidate transaction bytes against the gates without changing state. The explorer's transaction page renders the trace, so a reviewer can see what was checked and why a recent transaction passed or failed. The durable record of admitted transfers is the audit log, the Travel Rule registry and the flag queue.

Module responsibilities

x/stablecoin

Owns the HKD denom namespace (hkd.<issuer>). Issuance takes two steps: mint into the issuer's treasury (L5 issuer only, gated on a fresh reserve attestation), then distribute from the treasury into circulation. Burn opens a redemption request, and the issuer's acknowledgement (confirming the off-chain fiat payment) destroys the units. Pause is scoped: an issuer can pause its own denomination, and a global pause requires governance. A per-account freeze, signed by the compliance authority, currently blocks redemption only; the primitive that stops an address transacting is blacklisting in x/kyc. No other module changes supply.

x/compliance

Hosts the AnteHandler decorators and the trace recorder. Owns the sanctioned-institution list, rule parameters, the append-only audit log, the Travel Rule registry, delegated sub-role bindings and agent policy envelopes, and the reviewer/officer flag workflow. Sanctions updates and rule changes are signed by the compliance authority, an address that governance appoints through this module's parameters.

x/reserve

Manages the Proof of Reserve multi-sig lifecycle. Issuer submits an attestation hash with period metadata; a registered auditor co-signs; the attestation finalizes. At the first block of each UTC day, a statement per issuer records circulation, the reserve market value from the issuer's latest attestation, and that attestation's id. Supports public per-address reserve lookups.

x/kyc

Address-to-identity registry. Six levels: blacklisted, unverified, retail-basic, retail-enhanced, institutional, licensed-issuer. Each identity carries an institution (VASP) identifier, defined as an LEI or equivalent and currently a free-form field, and a hash reference to the off-chain IVMS 101 record held by the KYC provider. No PII on chain. KYC providers authorised in the module's parameters enrol and upgrade identities, governance grants level 5, and the compliance authority blacklists. One blacklisting primitive serves all three routes to level 0: a direct blacklisting, a sanctions-list update and a block decision on a flag. Delegated sub-key bindings live in x/compliance, and each identity-dependent gate resolves a bound sub-key to its principal's record.

Data flow — key operations

Transfer with Travel Rule enforcement: the sender constructs a transaction carrying a Travel Rule payload as a transaction extension option. Each AnteHandler decorator validates one aspect. If every blocking gate passes, the transfer executes, the payload is stored against the transaction hash, an audit-log entry is written and structured events are emitted. The same gates run for a transfer made through an issuer's extended ERC-20 precompile, where a failure reverts the call.

Reserve attestation: the issuer signs MsgSubmitAttestation with period, circulation, reserve market value, and an attestation hash (pointing to an off-chain PDF). State becomes PENDING_AUDIT. A registered auditor signs MsgCoSignAttestation; state becomes ATTESTED. The issuer's next MsgMint is accepted only while its latest attested attestation is within the freshness window set by governance.

Flagged transaction review: if an advisory decorator raises a flag (e.g., a threshold flag on a large transfer), the flag enters the on-chain flag queue and an EventFlagEmitted event is emitted. The issuer's reviewer sub-role picks up the flag in their queue and signs MsgReviewFlag to approve or block it, or escalates it. An escalated flag reaches the officer sub-role, who signs MsgCloseFlag with a final approve or block decision. A block decision by either role blacklists the subject. The full chain of decisions is audit-queryable.

Public reserve lookup: given an address, the system returns, for each HKD denomination the address holds, the balance and the issuer's latest ATTESTED attestation. The user can then see the attestation's signers, its random-day snapshot and the hash that binds it to the issuer's published assurance report.

Off-chain services

hkchain web app (Next.js)

Single Next.js application served at one origin, exposing four route families:

  • /: the project homepage.
  • /dashboard: read-only compliance views for the supervisor, issuer operations, issuer compliance, auditor and public reserve lookup, chosen with a demo role switcher. Views refresh from chain events over WebSocket and read history over REST. The dashboard signs no transactions.
  • /explorer: live block feed (CometBFT WebSocket bump → REST refetch), block detail, transaction detail, and address detail. The tx-detail page renders, on one screen: header (height/time/gas/fee/signer + ACCEPTED/REJECTED chip), AnteHandler decorator trace, flags emitted on this tx, the Travel Rule extension-option payload, the audit-log entries tied to the tx, decoded messages, and a simulate-trace fallback for ring-buffer-evicted hashes. The address-detail page renders KYC identity (with sanctions-blacklist cross-check), sub-role context in both directions (delegated-by + delegated-from), denom balances, and a recent-transactions scan over Tendermint bank events.
  • /docs: Markdown rendering of docs/ as the public documentation site.

Onboarding portal (Go)

The test network's onboarding service: a native-token faucet, an identity-gated HKD faucet, and a test KYC flow that issues test identities. Applicants prove control of their address with a wallet signature; level 2 is enrolled automatically, and levels 3 and 4 wait for an operator's approval. Applicant data stays off chain. The chain records only the outcome, through MsgEnroll signed by an authorised KYC provider key.

payx402 service (Go)

HTTP server implementing x402 pay-per-request semantics. Returns 402 Payment Required with an HKD payment envelope; verifies on-chain settlement before releasing the resource. Supports multiple client agents for demo variety.

Deployment

Two deployments exist:

  • Single-node development network. scripts/localnet.sh starts one node from a fresh genesis, and scripts/demo-seed.sh wraps it to seed pre-KYC'd identities, sub-role bindings, an attested reserve attestation and a small circulation. The web app and other off-chain services run alongside as local processes or containers.
  • Five-validator permissioned test network. Validators accept peer-to-peer connections only. Clients reach the ledger through a public full node that serves the Cosmos REST, CometBFT RPC and EVM JSON-RPC endpoints behind TLS. The test network carries two test issuer denominations, the web dashboard and block explorer, and the onboarding portal.

On the test network, privileged keys (issuers, the compliance authority, KYC providers, faucets) are software keys. Hardware security modules, maker-checker controls, high-availability topology and a formal infrastructure security review are production requirements, and mainnet deployment is out of current scope.