Quantum-resistant private payments

HEGEMON (HGN) establishes a unified, privacy-preserving settlement layer that remains secure even in the presence of large-scale quantum adversaries. The project combines a post-quantum shielded pool, manifest-driven protocol evolution, and settlement-grade consensus into a single monetary primitive that can serve both retail and interbank use cases. This whitepaper summarizes the core principles guiding the repo and connects them to the implementation artifacts contained in this monorepo.

HGN is a post-quantum, Zcash-inspired settlement layer focused entirely on shielded transactions. The motivation comes from two converging pressures. First, Shor/Grover-class adversaries threaten to rewind the privacy guarantees of legacy shielded pools that still rely on elliptic curves or pairings. Second, the most commercially interesting private-payment applications still need instant settlement, programmability, and selective disclosure without surrendering supply controls. HGN combines PQ cryptography, MASP-style circuits, and explicit protocol-release schedules to deliver that blend. Privacy is a first-order commercial requirement because merchants, suppliers, and consumers routinely expose strategic information—such as inventory positions, negotiated discounts, or sensitive purchase histories—when forced to transact on transparent ledgers. Once adversaries or competitors can scrape that data, they can front-run contracts, profile customers for coercive price discrimination, or deanonymize activists, making private commerce practically impossible. The motivating use cases are:

1. Digital bearer instrument – Users custody notes locally via the wallet/ client and transact without revealing balances, ownership, or memo data.
2. Cross-border settlement rail – Miners running the PoW consensus/ stack deliver eventual finality for interbank transfers and bridge interfaces while preserving the privacy pool semantics.
3. Programmable safety net – Protocol manifests and version schedules can enact capped issuance, capital controls, or demurrage in response to macro shocks, while remaining auditable.

The HGN protocol consists of four tightly-coupled subsystems:

1. Shielded pool and cryptography (crypto/, circuits/, wallet/) – The pool is modeled as a sparse Merkle accumulator proven via STARKs. ML-DSA/SLH-DSA signature primitives, ML-KEM key encapsulation, and hash-based commitments (Blake3/SHA3, no Pedersen or ECC) underpin the spend authorization flow. Notes transition between states through the circuits defined in circuits/, and users interface with them via the wallet note-management APIs.
2. Consensus and networking (consensus/, network/) - A PoW protocol seals batches of shielded transactions. The Go netbench tooling simulates adversarial bandwidth conditions, while the Rust consensus service validates blocks by checking a commitment proof plus parallel transaction-proof verification and performing per-node randomized data-availability sampling of erasure-coded chunks.
3. State and execution (state/, protocol/) – Mining nodes maintain on-disk Merkle forests, apply deterministic fee burning, and expose programmable hooks for sidecar applications. The protocol/ crate codifies transaction formats, serialization, and proof verification limits.
4. Protocol release artifacts and runbooks (governance/, runbooks/) – Version schedules define monetary policy, allowed proof bindings, and emergency upgrade paths. Operational runbooks document incident response, upgrade ceremonies, and regulator disclosures for PoW operators; see runbooks/miner_wallet_quickstart.md for the end-to-end node + wallet pairing walkthrough referenced throughout this whitepaper.

flowchart TB
    subgraph User["User Layer"]
        W[wallet/]
        UI[hegemon-app/]
    end

    subgraph Proving["Proving Layer"]
        CT[circuits/transaction]
        CB[circuits/block]
    end

    subgraph Crypto["PQ Cryptography"]
        CR[crypto/]
    end

    subgraph Consensus["Consensus"]
        CON[consensus/]
        NET[network/]
    end

    subgraph State["State & Runtime"]
        SM[state/merkle]
        RT[runtime/]
    end

    W -->|craft tx| CT
    CT -->|proof| CB
    CB -->|block proof| CON
    CON -->|seal| RT
    CT --> CR
    CB --> SM

Blocks carry a commitment proof that binds the list of canonical transaction statement hashes via a Poseidon sponge (tx_statements_commitment) and exposes the starting/ending state roots, nullifier root, DA root, plus the transaction-ordered and sorted nullifier lists as public inputs. In the Substrate node, block-level proof material is carried on-chain via an unsigned ShieldedPool::submit_proven_batch payload (BlockProofBundle), with ShieldedPool::enable_aggregation_mode marking aggregation-required blocks. Validators accept a block by (1) verifying the commitment proof against public inputs derived from the block’s shielded transfers, (2) recomputing tx_statements_commitment, and (3) validating either the bundled aggregation mode payload (FlatBatches or MergeRoot) or per-transaction proofs (inline mode). In ProofAvailabilityPolicy::SelfContained aggregation mode, proofless transfers require a same-block submit_proven_batch, and validators do not fetch proof-DA manifests/entries.

DESIGN.md §6 and METHODS.md §5 describe how the state/merkle, circuits/block, and protocol-versioning crates collaborate to keep the chain coherent as primitives evolve. Miners append transactions to the Poseidon-based forests in state/merkle, then call CommitmentBlockProver locally before broadcasting a PoW solution. Every transaction carries a VersionBinding { circuit, crypto }, and block producers batch those into a VersionMatrix whose hash becomes the header’s version_commitment. The protocol-versioning crate exposes helpers for encoding that matrix plus the per-block VersionBinding counts so the network can attest exactly which circuit/crypto combinations were accepted in a slot. On ingest, PoW nodes query VersionSchedule::first_unsupported before finalizing state; if a block references a binding that the active protocol manifest does not schedule, consensus raises ConsensusError::UnsupportedVersion and refuses to advance the Merkle roots even if the hashpower majority momentarily disagrees.

The block circuit now emits CommitmentBlockProof payloads, making tx_statements_commitment the canonical commitment-proof binding. Consensus verifies the commitment proof, then verifies aggregation proof validity (or transaction proofs in parallel when aggregation is absent) and updates state roots locally.

Protocol releases roll new bindings through the flow in governance/VERSIONING.md: authors publish a VersionProposal, operators stage verifying keys and commitment-proof parameters, and each release ships the resulting VersionSchedule inside the canonical protocol manifest. Proposals can include UpgradeDirectives that mandate a dedicated migration circuit, and both the base binding and upgrade circuit appear in the block’s version_commitment so operators can measure uptake via the per-block version counts. The consensus crate enforces these policies by matching each observed binding against the live schedule, surfacing errors for unsanctioned bindings, and honoring retirement heights so deprecated circuits fall out automatically.

Operational touchpoints anchor the theory to daily practice. consensus/bench replays the ML-DSA/STARK payload sizes described in DESIGN.md §6 so operators can benchmark PQ-era throughput before activating new bindings. During an emergency swap, runbooks/emergency_version_swap.md walks operators through drafting the VersionProposal, enabling the mandated UpgradeDirective, and monitoring version uptake until the VersionSchedule retires the compromised binding. The current deployment path starts from the live InlineTx architecture: one public authoring node, proof-ready transactions produced at the edge, and full nodes verifying inline tx proofs plus the commitment proof. Future topology growth is tracked in docs/SCALABILITY_PATH.md. Together, the commitment proofs, version commitments, and protocol-release artifacts keep consensus, state, and operations synchronized without cloning the privacy pool.

sequenceDiagram
    participant W as Wallet
    participant C as Circuit
    participant M as Merkle Tree
    participant N as Network

    W->>W: Select notes, derive nullifiers
    W->>W: Create outputs, compute commitments
    W->>C: Submit witness + Merkle paths
    C->>C: Verify membership, nullifiers, balance
    C-->>W: STARK proof
    W->>N: nullifiers + commitments + proof
    N->>M: Check nullifiers, append commitments
    N-->>W: Confirmed

Each note in the MASP-style pool carries (value, asset_id, pk_recipient, rho, r) as described in METHODS.md §1, and the wallet logic in wallet/ maintains those fields while deriving commitments via cm = Hc("note" || enc(value) || asset_id || pk_recipient || rho || r) before inserting them into the STARK-proven Merkle forest in state/. The circuits/transaction crate enforces that every published commitment matches an in-circuit re-computation, while the note handling API exposes the corresponding secrets so a sender can prove knowledge without leaking them on-chain.

Spend authorization follows the hash-based nullifier scheme from METHODS.md §1.2 and DESIGN.md §1: the wallet derives sk_nf = H("view_nf" || sk_view) and the crypto/ primitives derive nk = H("nk" || sk_nf) then nf = H("nf" || nk || rho || pos) per note, and the STARK constraints in circuits/transaction bind each public nullifier to its witness data so the state/ nullifier set catches double-spends. Proof witnesses also include Merkle paths for inputs, and the verifier logic wired through protocol/ only accepts transactions whose STARK proofs simultaneously demonstrate membership, note opening correctness, and adherence to the MASP value equations.

Multi-asset conservation is implemented exactly as METHODS.md §2 prescribes: the circuit forms a permutation-checked multiset of (asset_id, signed_delta) pairs, sorts and compresses them, and emits a balance_tag commitment that nodes in consensus/ compare against fee and issuance rules. By constraining the integer ranges in-field and collapsing per-asset totals, the prover shows that every input and output balances out, and wallet/ surfaces the same accounting so users can audit multi-asset flows locally.

Post-quantum security hinges on the primitives cataloged in DESIGN.md §1: ML-DSA handles miner and protocol-authenticated envelope signatures, SLH-DSA anchors long-lived trust roots, and ML-KEM drives note/viewing key encryption, all exposed via the unified crypto/ crate. Because the STARK proving stack in circuits/transaction and the note authorization flow rely only on hash-based commitments and lattice primitives, the pool stays quantum-safe—no elliptic curves or pairing-based assumptions remain for Shor’s algorithm to break, and Grover/BHT reductions are already absorbed by 48-byte (384-bit) digests on commitments and Merkle roots.

Runtime extrinsics and PoW seals now share the same PQ signing surface: runtime/src/lib.rs defines PqSignature/PqPublic backed by ML-DSA (3,293-byte signatures, 1,952-byte public keys) and SLH-DSA, derives AccountId32 via BLAKE2 over the PQ public key for SS58-prefix-42 compatibility, and wires the off-chain AppCrypto path through the same primitives the PoW engine validates. This keeps address encoding stable while aligning transaction signing with the miner verification path.

These guarantees are not just prose: circuits/formal captures the nullifier uniqueness and MASP balance invariants in TLA+, and circuits-bench plus the wallet-bench suite publish the prover and client performance envelopes so reviewers can correlate the whitepaper claims with reproducible benchmarking and formal artifacts.

HGN deliberately removes every discrete-log or factoring dependency that Shor’s algorithm could exploit. The crypto/ crate standardizes on lattice- and hash-based primitives—ML-DSA (Dilithium-like) for miner and protocol-authenticated signatures, SLH-DSA (SPHINCS+) for long-lived trust roots, and ML-KEM (Kyber-like) for encrypting note/viewing keys—so there are no RSA or elliptic-curve targets to collapse. Hash commitments use 48-byte digests (BLAKE3-384/SHA3-384 externally, Poseidon2-384 in-circuit), so Grover/BHT reductions are already absorbed into the security margin. The STARK proving system is fully transparent and anchored in hash collision resistance, so its soundness does not rely on pairings or number-theoretic assumptions either. Finally, the threat model assumes adversaries already possess Shor/Grover-class hardware, which is why the protocol bans downgrades to classical primitives and enforces PQ-safe key sizes. Together, these design choices provide a high degree of resistance to Shor’s algorithm across the entire stack—from note commitments and proofs to networking, release artifacts, and operational guardrails.

The privacy layer is engineered as a single, MASP-style shielded pool from genesis with no transparent escape hatches: commitments, nullifiers, balance conservation, and diversified address derivation all stay inside transparent STARK proofs built on hash- and lattice-only primitives (ML-DSA/SLH-DSA signatures, ML-KEM note encryption, and hash-based commitments). Selective disclosure relies on incoming/outgoing/full viewing keys rather than transparent outputs, preserving address privacy while enabling audits. In contrast to Zcash’s elliptic-curve commitments and trusted-setup SNARKs (Sapling/Orchard), HGN eliminates discrete-log assumptions and trusted setups entirely, accepting larger proof payloads to gain post-quantum resilience. Zcash’s history of launching new pools (Sprout → Sapling → Orchard) is replaced here by versioned circuits and commitment proofs that keep the shielded pool intact during upgrades, ensuring quantum-era safety without fragmenting privacy sets.

Quantitative privacy assessment (in bits):

Anonymity set: All notes share a single shielded pool—the anonymity set equals the total note count (currently 2³²–2⁴⁰ capacity). Unlike Zcash's fragmented pools (Sprout/Sapling/Orchard), version upgrades do not partition users.

Information leakage: Transaction timing and proof size are observable; sender, recipient, amounts, and asset types remain hidden. Viewing keys enable selective disclosure without breaking pool-wide privacy.

HGN targets a basket-pegged unit of account. Key levers include:

• Supply management – Mining nodes enforce capped issuance defined in DESIGN.md, and surplus fees route to a stabilization reserve to dampen volatility.
• Liquidity incentives – Wallet and miner clients expose hooks for automated market makers to provide cross-asset liquidity while preserving shielded ownership.
• Stability metrics – Oracles feed transparent macro indicators (CPI baskets, FX indices) into protocol-validated policy updates to automatically adjust collateral ratios.

Stablecoin mint and burn happen inside the shielded pool rather than through transparent balances. Issuers submit proof-native shielded transfers whose proofs bind to a protocol policy hash plus the current oracle and attestation commitments from the active manifest. The verifier rejects stale or disputed inputs before state transition, so issuance remains private while policy compliance stays deterministic.

In the live system, these levers become explicit mining duties wired through protocol manifests and state/. Issuance limits are encoded in VersionProposals that describe the capped schedule alongside any reserve-ratio tweaks; once published they are shipped inside the consensus VersionSchedule, so every block producer rejects mint transactions whose proofs exceed the supply cap recorded in protocol metadata. Fees and demurrage routed into the stabilization reserve are audited inside the same ledger trees, and any rebalancing logic must remain protocol-defined rather than admin-defined.

Liquidity hooks live in protocol/ where transaction structs expose sidecar commitments for AMM routers, and miners enforce that those hooks only net out if they reference bindings blessed by the active VersionSchedule. The wallet/ glue code simply passes through the hook payload so shielded ownership never leaves the MASP. Because the same versioning apparatus backs these hooks, rolling out a new liquidity primitive is as simple as drafting a VersionProposal with an UpgradeDirective that migrates existing liquidity notes without fragmenting the pool.

Stability oracles are modeled as miners consuming commitments produced by adapters implemented in protocol/ and then anchoring the values into the Merkle forests maintained under state/. Protocol schedules define which CPI/FX feeds are valid and how deviations drive collateral-ratio changes. Miners must attest that each oracle update references a VersionSchedule-approved binding; otherwise the block is rejected, ensuring that a rogue oracle cannot silently erode the supply controls or liquidity programs.

Policy changes and primitive upgrades therefore share the same lifecycle: a VersionProposal describes the new cap, reserve policy, oracle feed, or liquidity hook; a VersionSchedule entry sets the activation/retirement heights; and an optional UpgradeDirective codifies how in-flight notes migrate (e.g., swapping to a patched stabilization reserve circuit). This keeps monetary policy atomic—operators only need to track the schedule rather than bespoke forks—and the relevant code paths stay discoverable in protocol-release artifacts, protocol/, and state/.

Emergency actions reuse the checklist in runbooks/emergency_version_swap.md. If the stabilization reserve circuit or an oracle binding is compromised, operators follow that runbook to draft a fast-track VersionProposal, regenerate the required proving/verifying keys, and push the updated VersionSchedule to all miners. The runbook’s upgrade circuit requirements ensure that reserve balances or oracle attestations can be rolled forward without losing assets, while the staged miner rollout (keys → binaries → monitoring) keeps the monetary safety net intact: consensus refuses unsupported bindings, upgrade transactions prove reserve/oracle continuity, and the final retirement step prunes the vulnerable path once all miners attest to the new schedule.

The architecture prioritizes defense-in-depth:

• Post-quantum guarantees – All signatures and key exchanges default to PQ-safe primitives maintained in crypto/.
• Soundness and correctness – Every critical path change must update DESIGN.md, METHODS.md, and any relevant specification artifacts to keep the implementation auditable.
• Selective disclosure – View keys allow auditors or regulators to inspect specific flows without deanonymizing the entire ledger, aligning with multi-jurisdiction privacy requirements.

docs/THREAT_MODEL.md documents the baseline adversary: Shor/Grover-era attackers can compromise miners on demand, replay malformed traffic, and attempt to bias randomness. This is why every primitive in crypto/ sticks to ML-DSA/SLH-DSA signatures, ML-KEM key exchange, ≥256-bit symmetric hashes, and 48-byte digests for commitments, why the STARK proving system avoids trusted setups entirely, and why adaptive compromise controls (view-key rotation, nullifier privacy, parameter pinning) must survive even when an attacker briefly controls wallets or consensus nodes.

DESIGN.md §8 outlines the feedback loops that keep those assumptions observable. External cryptanalysis and third-party audits—tracked in docs/SECURITY_REVIEWS.md—tie concrete findings back to functions and commits so the PQ parameter set never drifts silently. The TLA+ models under circuits/formal/ and consensus/spec/formal/ make witness layouts, balance invariants, and consensus safety reviewable at every release gate, giving reviewers a mechanical view of each subsystem's state. Continuous integration runs the security-adversarial workflow plus dedicated fuzz/property tests for transactions, network handshakes, wallet address derivations, and the root-level tests/security_pipeline.rs, so regressions surface as blocking signals with attached artifacts. Together, audits, formal specs, and CI logs ensure every subsystem—from proofs to networking—emits evidence that the live system still matches the whitepaper.

Operators follow runbooks/security_testing.md whenever the adversarial suite fails, before releases, or after touching witnesses, networking, or wallet encodings. The runbook pins PROPTEST_MAX_CASES, executes the four adversarial cargo test commands (transaction circuit fuzzing, network handshake mutations, wallet address fuzzing, and the cross-component pipeline), and, when necessary, re-runs the TLA+/Apalache jobs for circuit balance and consensus safety. Findings, seeds, and transcripts are captured and logged into docs/SECURITY_REVIEWS.md, which enforces that mitigation PRs add regression tests plus design updates. This workflow closes the loop between operator playbooks and the canonical review ledger so the assurance process remains enforceable rather than aspirational.

1. Alpha – Deliver end-to-end shielded transfers with synthetic test assets, benchmarked via circuits-bench and wallet-bench.
2. Beta – Harden the PoW consensus path, finalize protocol-manifest operations, and document how external miners can sync, mine, and upgrade safely.
3. Launch – Freeze the monetary policy smart contracts, publish third-party audits, and release reproducible builds for wallet and mining node binaries.

| docs/ | Contributor docs (CONTRIBUTING.md), threat model, and API references that stay in sync with DESIGN.md/METHODS.md. | | governance/ | Protocol versioning and release-policy documentation. | | hegemon-app/ | Electron desktop app for node + wallet control. | | network/ | P2P networking stack and connectivity logic. | | node/ | Substrate-based node binary (hegemon-node) and custom RPC endpoints. | | protocol/ | Protocol definitions, transaction formats, and versioning logic. | | runbooks/ | Operational guides for miners, emergency procedures, and security testing. | | scripts/ | Shell scripts for dev setup and automation. | | state/ | Merkle tree storage and state management. | | tests/ | Integration tests and the security pipeline suite. | | wallet/ | CLI wallet plus the wallet-bench binary for note/key performance measurements. |

1. Install toolchains:

   make setup

   This runs scripts/dev-setup.sh to install Rust, Go, and other dependencies.

2. Build the node:

   make node

3. Run a development node with mining:

   HEGEMON_MINE=1 ./target/release/hegemon-node --dev --tmp

   The node starts with a temporary database, mining enabled, and RPC on port 9944.

4. Query the node via RPC:

   curl -s -H "Content-Type: application/json" \
     -d '{"id":1, "jsonrpc":"2.0", "method": "system_health"}' \
     http://127.0.0.1:9944

For multi-node setups, see runbooks/two_node_remote_setup.md. For VPS deployments, follow runbooks/p2p_node_vps.md.

./target/release/hegemon-node --help

Key options:

• --dev - Run in development mode with relaxed local settings and a fresh ephemeral chain
• --tmp - Use a temporary database (cleaned on exit)
• --base-path <PATH> - Persistent database location
• --rpc-port <PORT> - JSON-RPC port (default: 9944)
• --port <PORT> - P2P port (default: 30333)
• --bootnodes <MULTIADDR> - Bootstrap peers

Environment variables:

• HEGEMON_MINE=1 - Enable mining
• HEGEMON_MINE_THREADS=N - Mining thread count
• HEGEMON_MINER_ADDRESS=<shielded_addr> - Shielded address for coinbase rewards

Use this when you want to run two nodes that peer with each other:

1. Build the binary:

   make node

2. Start the first node (mining):

   HEGEMON_MINE=1 ./target/release/hegemon-node --dev \
     --base-path /tmp/node1 \
     --port 30333 \
     --rpc-port 9944

3. Start the second node (peering with first):

   ./target/release/hegemon-node --dev \
     --base-path /tmp/node2 \
     --port 30334 \
     --rpc-port 9945 \
     --bootnodes /ip4/127.0.0.1/tcp/30333

4. Verify connectivity:

   # Check peer count via system_health (system_peers returns empty in PQ network)
   curl -s -H "Content-Type: application/json" \
     -d '{"id":1, "jsonrpc":"2.0", "method": "system_health"}' \
     http://127.0.0.1:9944
   # Expected: {"peers":1,"isSyncing":false,"shouldHavePeers":true}

• Toolchains – Run ./scripts/dev-setup.sh (or make setup) to install Rust/Go/jq/clang-format.
• Tests – make check mirrors the fmt/lint/test CI combo.
• Benchmarks – make bench exercises prover, wallet, and network smoke benches.

Hegemon currently prioritizes privacy and post-quantum security over general-purpose programmability. Unlike Ethereum or Polkadot, there is no EVM or user-deployed WASM contract layer—all logic lives in fixed Substrate pallets. This section outlines how user-deployed code could be introduced while preserving the shielded pool's privacy guarantees.

Option A: Predicate Notes — Notes carry a spending predicate hash, and the STARK circuit proves predicate satisfaction. A small DSL covers common cases (timelocks, M-of-N multisig, hash preimages). Privacy is preserved because the predicate itself stays off-chain; only H(predicate) appears in the note commitment.

Option B: zkVM Execution Traces — Users deploy WASM or RISC-V programs whose execution traces are proven in a recursive STARK. The chain sees only code_hash, nullifiers consumed, and new commitments—never the program logic or inputs. This mirrors Aleo/RISC Zero but uses PQ-safe hashing and transparent proofs.

Option C: Private State Channels — Keep L1 simple; push complex logic to off-chain channels with ML-DSA-signed state updates. Disputes submit STARK proofs of protocol violations. This scales well but requires liveness from channel participants.

All three options integrate with Hegemon's VersionBinding and VersionSchedule infrastructure:

VersionBinding { circuit: 1, crypto: 1 }  // Current: simple spend
VersionBinding { circuit: 2, crypto: 1 }  // Future: + predicate interpreter
VersionBinding { circuit: 3, crypto: 1 }  // Future: + zkVM trace verifier

New circuit versions are proposed via VersionProposal, activated at scheduled heights, and can coexist with older versions indefinitely. Notes created today could be spent with a future predicate circuit without migration—the pool stays unified.

1. Private state: How do contracts maintain encrypted state across transactions? Options include encrypted blobs in note memos or dedicated "state notes" consumed and recreated each transaction.
2. Composability: Can shielded contracts call each other atomically? Requires proving multiple execution traces in one STARK or cross-contract commitment schemes.
3. Prover delegation: Heavy proofs may require delegated provers, introducing privacy/trust tradeoffs. TEE-assisted proving or prover markets are possible mitigations.

This design space—PQ + STARK + privacy + programmability—remains largely unexplored. Hegemon's architecture is positioned to experiment with these extensions without fragmenting the privacy pool.