---
# System prepended metadata

title: Quantus “Cypherpunk” Testnet Roadmap

---

# Quantus “Cypherpunk” Testnet Roadmap
**Repository target:** fork of [`Quantus-Network/chain`](https://github.com/Quantus-Network/chain)  
**Objective:** add Quantus ZK-bridge support primitives and launch a new public PoW testnet named **`cypherpunk`**, with the minimum infrastructure to demonstrate feasibility and validity of trustless bridging (zk light clients, Poseidon bridge commitments).

---

## 0) High-Level Scope & Principles

- **Trust model:** ZK light clients (no trusted multisig).  
- **Header commitment:** Per-block **Poseidon Bridge Commitments Root** (lane-fanout design) reusable by other bridges (e.g., Ethereum, Solana).  
- **Minimal viable demo:** ETH↔Quantus one-way and return path demo using zk proofs; rate-limited caps.  
- **Compatibility:** Runtime changes are versioned and non-breaking for state; header spec is frozen for the testnet.  
- **Observability-first:** Prometheus + Grafana; detailed logs for relayer/prover; public telemetry.

---

## 1) Workstreams & Ordered Implementation List

### 1.1 Runtime & Header Commitments (Poseidon)
1. **Freeze header spec changes.**
   - Add `DigestItem::BridgeCommitmentsV1` fields:
     - `version: u8 = 1`
     - `algo: u8 = 1 /*(Poseidon2, BN254 field)*/`
     - `arity: u8 = 8`
     - `lanes_root: H256`
     - `meta_commit: H256(Poseidon(domain || spec_version || chain_id || algo || arity))`
   - Document exact byte layout & hashing order.
   - Acceptance: test vectors match off-chain calculators.

2. **Implement `pallet-bridge-commitments`.**
   - Build **Poseidon(arity=8) Merkle** over per-lane message leaves.
   - Lane registry (simple map `lane_id → metadata`).
   - End-of-block hook: compute per-lane root → `lanes_root`; inject digest item.
   - Config constants: `MAX_MSGS_PER_BLOCK`, `MAX_LANES_PER_BLOCK`.
   - Acceptance: unit tests for tree building; snapshot root is deterministic.

3. **Leaf format (canonical).**
   - Preimage: `domain || chain_id_src || chain_id_dst || lane_id || asset_namespace || asset_id(32) || recipient_type || recipient(32) || amount(u256) || nonce(u64) || msg_version`
   - Poseidon packing rules documented; unit tests (Rust + fixtures).
   - Acceptance: fixtures reusable by Solidity/Solana/Rust circuits.

4. **Runtime wiring.**
   - Expose RPC to query: `lanes_root`, per-lane roots, and leaves for a block.
   - Add runtime `bridge::events()` indexing for explorers.
   - Acceptance: RPC returns correct values; integration test covers finalization window.

---

### 1.2 Cryptography Verifier Pallet
1. **`pallet-groth16-verifier` (BN254).**
   - Runtime pallet wrapping a host function for pairings (arkworks or bn254 precompile equivalent).
   - Extrinsic: `verify(proof, public_inputs) -> Result<bool>` (weight metering).
   - Acceptance: known Groth16 test vectors pass; weight ≤ target budget.

2. **Poseidon gadget parity (no_std).**
   - Provide a `no_std` Poseidon2 library matching circuit params for leaf/path checks in tests (not for on-chain verification).
   - Acceptance: vector consistency with circuits.

---

### 1.3 ETH Bridge Gateway Pallet
1. **`pallet-eth-bridge-gateway`.**
   - Call `mint_with_proof(proof, public_inputs)`:
     - Internally calls `pallet-groth16-verifier`.
     - On success → mints via `pallet-assets` or `orml-tokens`.
     - Replay protection via `(lane_id, nonce)` map.
     - Rate limits & caps per asset.
   - Events: `Minted(asset_id, to, amount, nonce)`; `ProofRejected(..)`.
   - Acceptance: end-to-end unit + integration tests with mocked verifier (always true/false).

2. **Assets mapping.**
   - Storage map `<eth_token: H160> ↔ <AssetId>`; governance-controlled.
   - Acceptance: non-admin cannot rebind; emitted events audited by tests.

---

### 1.4 PoW / DAA Finality Spec Freeze
1. **Document DAA & cumulative work.**
   - Exact target computation per block.
   - Cumulative work definition and reorg rules (window `R`, e.g., 100 blocks).
   - Acceptance: golden tests for DAA; reorg simulator runs in CI.

2. **Header serialization.**
   - Freeze header struct & SCALE encoding (including `bridge commitments` digest).
   - Acceptance: circuit parser spec matches runtime; fuzz differential tests.

---

### 1.5 Chainspec: `cypherpunk`
1. **Create new chainspec.**
   - ID: `cypherpunk`
   - Properties:
     - `tokenSymbol`, `tokenDecimals`, `addressFormat` for AccountId32.
     - `chainId_src/dst` assignments for bridge leaves (`QNT_TESTNET = 42`, `ETH_SEPOLIA = 11155111`, etc.).
   - Bootnodes (multiaddr), telemetry endpoints, protocol ID.
   - Acceptance: `./target/release/quantus-node build-spec --chain cypherpunk.json --raw` runs; network boots.

2. **Genesis & endowed accounts.**
   - Faucet, treasury, technical committee multisig.
   - Asset registry seeding (bridged sample token mapping).

3. **Feature gates & runtime versioning.**
   - Feature `bridge_commitments_v1` on by default in `cypherpunk` only.

---

### 1.6 Tooling & DevEx
1. **CLI utilities.**
   - `qnt-bridge-tools`: build leaves, lanes, trees; dump proofs; verify off-chain.
   - Acceptance: roundtrip test with runtime RPC.

2. **Types for Polkadot.js/API.**
   - Publish `types.json` for custom digest + pallets.
   - Acceptance: apps UI displays commitments & events.

3. **CI/CD.**
   - Format, lint, tests; wasm builds; runtime size & weight checks.
   - Chainspec build job outputs artifacts.

---

### 1.7 ZK Circuits & Provers (Off-chain)
1. **ETH→QNT circuit.**
   - Proves: beacon finality → MPT log inclusion → `Locked(...)` parameters.
   - Public inputs: `H_exe`, `token_vault`, `recipient_quantus`, `amount`, `nonce`.
   - Output consumed by `pallet-eth-bridge-gateway`.
   - Acceptance: vectors on Sepolia block/logs pass; Groth16 setup MPC artifacts archived.

2. **QNT→ETH circuit.**
   - Proves: valid Quantus PoW chain segment finalizes header `k` with `lanes_root_k`; Poseidon inclusion of `Burn` leaf.
   - Public inputs: `bridge_root_k`, `quantus_asset_id`, `eth_recipient`, `amount`, `nonce`.
   - Acceptance: vectors from local devnet; run-time configurable R/work threshold embedded as constants/domain.

3. **Recursive aggregation (optional in MVP).**
   - Fold many headers → single Groth16 wrapper proof.
   - Acceptance: same public input shape; smaller proof verification gas/time stable.

4. **Prover service (Rust).**
   - Watchers (ETH Sepolia, QNT `cypherpunk`), witness gen, GPU-accelerated MSM/FFT.
   - REST: `POST /prove/eth_to_qnt` / `qnt_to_eth` returns proof+pubInputs.
   - Acceptance: reproducible proofs for fixtures; Prometheus metrics.

---

### 1.8 Ethereum Contracts (Sepolia)
1. **`QuantusVerifier` (Groth16).**
   - Deployed verifying key for QNT→ETH circuit.
   - Acceptance: unit tests pass on-chain (Foundry).

2. **`BridgeGateway` (Ethereum).**
   - `releaseWithProof(proof, publicInputs)` verifies proof & nonces; calls `TokenVault.release`.
   - Rate limits; pausable; role for asset mapping.
   - Acceptance: Foundry e2e tests with mocked proofs, real gas snapshots.

3. **`TokenVault` (escrow).**
   - Locks, releases ERC-20; emits `Locked` events with canonical fields.
   - Acceptance: emits logs matching circuit expectations.

---

## 2) Infrastructure Plan (to Demonstrate Feasibility & Validity)

### 2.1 Quantus Network Topology (Cypherpunk)
- **Bootnodes (2x):** public IPs; stable peers; maintained keys.
- **Sentry nodes (3–5x):** protect archive & authority nodes; NAT traversal; public ports open.
- **Full nodes (≥5x):** community-operated; target geodiversity.
- **Archive nodes (2x):** full state for explorers/indexers.
- **Miners (PoW) (≥3x):** GPU miners connected; varied hashrates to test DAA.
- **Telemetry:** substrate-telemetry endpoint; custom label `cypherpunk`.

**Minimum viable footprint**  
- 2 bootnodes, 2 sentries, 2 full nodes, 1 archive, 3 miners.

**Specs (guidance)**  
- Full/sentry: 8 vCPU, 32 GB RAM, fast SSD, 1 Gbps.  
- Archive: 16 vCPU, 64 GB RAM, NVMe, large SSD.  
- Bootnodes: 4–8 vCPU, 16–32 GB RAM.

### 2.2 Bridge & Prover Infrastructure
- **Relayer/Prover cluster (2x replicas):**
  - Region A/B; GPU-enabled runners (e.g., 1× mid/high-end NVIDIA).
  - Access to both ETH Sepolia and QNT RPC endpoints.
  - Expose REST for proof generation; private queue; retry & backoff.
- **ETH Sepolia endpoints:** primary + fallback (Alchemy/Infura + self-hosted if desired).
- **QNT RPC endpoints:** at least 2 public RPCs (sentry & archive).

### 2.3 Observability & Ops
- **Prometheus + Grafana:** dashboards for:
  - Node health, peers, block times, orphan/reorg rates.
  - Bridge pallets events, proof verify counts, failures.
  - Prover queue size, witness gen timings, GPU utilization.
- **Log aggregation:** Loki/Graylog; structured logs from relayers & nodes.
- **Alerting:** reorg depth > threshold, verifier failure spike, bootnode offline.

### 2.4 Public Services
- **Faucet:** rate-limited; Discord/HTTP gated.
- **Explorer:** Subscan-like (or custom) for `cypherpunk`.
- **Block visualizer for commitments:** page to show per-block `lanes_root`, lanes, and leaves.

---

## 3) Launch Procedure (Checklist)

1. **Repo prep**
   - [ ] Fork repo `Quantus-Network/chain` → `quantus-cypherpunk`.
   - [ ] Create workspace crates: `pallet-bridge-commitments`, `pallet-groth16-verifier`, `pallet-eth-bridge-gateway`, `qnt-bridge-tools`.
   - [ ] Wire pallets into runtime; add digest injection.

2. **Chainspec**
   - [ ] Create `cypherpunk.json`, set bootnodes, protocol ID, properties.
   - [ ] Generate raw spec; commit to repo `networks/cypherpunk/`.

3. **Build & test**
   - [ ] `cargo build --release` node & runtime.
   - [ ] Run local devnet; confirm commitments, events, RPC.
   - [ ] CI green: unit/integration/weight checks.

4. **Infra**
   - [ ] Provision bootnodes, sentries, archive; open ports; systemd services.
   - [ ] Start miners; verify DAA & hashrate reading.
   - [ ] Add telemetry URLs.

5. **Provers & Contracts**
   - [ ] Deploy Sepolia `TokenVault`, `BridgeGateway`, `QuantusVerifier`.
   - [ ] Bring up prover cluster; run smoke proofs with fixtures.
   - [ ] Fund relayer with ETH test funds and QNT gas.

6. **Genesis & faucet**
   - [ ] Distribute endowed balances; publish faucet URL.

7. **Go-live**
   - [ ] Announce `cypherpunk`; publish chain metadata & types.
   - [ ] Monitor dashboards; enforce low caps initially.

8. **Bridge demo**
   - [ ] ETH→QNT: lock ERC-20 on Sepolia → zk proof → mint on QNT.
   - [ ] QNT→ETH: burn on QNT → zk proof → release on Sepolia.
   - [ ] Record tx hashes and proofs as an appendix in repo.

---

## 4) Acceptance Criteria (Feasibility & Validity)

- **Header roots:** per-block `lanes_root` reproducible from fixtures; explorer displays lanes & leaves.  
- **ZK verification on-chain:** at least 5 successful `mint_with_proof` and 5 `releaseWithProof` calls over 24h; failure rate < 5% with clear error modes.  
- **Reorg resilience:** simulated reorg ≥ R blocks does not allow an old proof to pass; tests verified.  
- **Observability:** dashboards show prover timings, verification counts, and node health.  
- **Docs:** “Bridge Commitments Spec v1”, circuit pub inputs layout, and chainspec docs published.

---

## 5) Risk Register & Mitigations

- **Circuit complexity (Keccak/MPT, SHA/PoW):** leverage mature Halo2 gadgets; start with per-tx proof, add recursion later.  
- **Runtime weight spikes:** cap proof verifies per block; set fees accordingly.  
- **Trusted setup (Groth16):** public MPC ceremony; versioned verifying keys with withdrawal grace.  
- **DAA edge cases:** fuzz/sim tests; parameterize R and targets; telemetry alerts on abnormal orphan rates.  
- **Dev ergonomics:** provide `qnt-bridge-tools` & test vectors; Polkadot.js types for quick UIs.

---

## 6) Milestones & Artifacts

- **M1 — Commitments MVP (2–3 weeks):** pallets integrated; `lanes_root` visible; CLI tools.  
  - Artifacts: pallet crates, doc/spec, fixtures.  
- **M2 — Verifier & Gateway (2–3 weeks):** Groth16 pallet, ETH gateway pallet, assets mapping.  
  - Artifacts: runtime release `vX.Y.0-cypherpunk`.  
- **M3 — Circuits & Contracts MVP (3–5 weeks):** two circuits, Sepolia contracts, prover service.  
  - Artifacts: verifying keys, contract addresses, prover binaries.  
- **M4 — Testnet Launch (1–2 weeks):** infra online, faucet, explorer, telemetry, public docs.  
- **M5 — Bridge Demo & Report (≤1 week):** both directions executed; publish tx links & proof files.

*(Timelines are indicative; parallelize where possible.)*

---

## 7) Command Snippets & File Map

### 7.1 Chainspec
```bash
# build
cargo build --release -p quantus-node

# export default spec, edit, then raw
./target/release/quantus-node build-spec --disable-default-bootnode > cypherpunk.json
# edit cypherpunk.json (name, id, protocolId, properties, bootNodes, telemetryEndpoints)
./target/release/quantus-node build-spec --chain cypherpunk.json --raw > cypherpunk-raw.json

# launch a node
./target/release/quantus-node \
  --chain ./cypherpunk-raw.json \
  --base-path /var/lib/quantus/cypherpunk \
  --name qnt-cp-sentry-1 \
  --port 30333 --rpc-port 9933 --ws-port 9944
```

---

## 8) Appendix: Lane IDs (Reserved)
- `1` — ETH↔QNT ERC-20 bridge (Sepolia↔Cypherpunk)  
- `2` — Future: SPL↔QNT (Solana devnet)  
- `10+` — Internal testing lanes

---
