# 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
---
Sign in with Wallet
Connect another wallet