MESH2/PROJECT_CONSTITUTION.md

Project: MESH

Repository: https://gitea.reset.org/tony/mesh (TBC) Language: Rust (edition 2024, toolchain 1.85.0) License: Apache 2.0 Created: 2026-03-23 Status: Constitution Phase

Overview

MESH (Minimal-Exchange Settlement Hypergraph) is a decentralised payment protocol that settles retail transactions in under 300ms using Byzantine Consistent Broadcast — without a blockchain, without a native token, and with confidential amounts via Pedersen commitments and Bulletproofs+ range proofs. This constitution covers the Tier 1 MVP: a 4-validator local testnet with a CLI wallet that can send and receive confidential payments.

Constraints

• Single model: All agents run the same LLM backend. No role-to-model mapping is available.
• MVP scope only: Tier 1 (consensusless settlement) only. No Tier 2 DAG-BFT, no Tier 3 aBFT, no multi-currency routing, no connectors, no stealth addresses. These are specified but deferred.
• No external network: Agents work against a local Gitea repo. No public APIs, no npm/PyPI fetches during agent sessions.
• Deterministic serialisation: No serde. All encode/decode is hand-written per SPEC-002 §2.8. This is a hard constraint from the spec — agents must not introduce serde-based serialisation.
• Constant-time crypto: All secret-dependent operations must use constant-time implementations. Agents must use the dalek crate family, not roll their own.
• Pinned dependencies: Exact crate versions are specified in the Dev Environment Specification. Agents must not upgrade or substitute crates without a gate approval.

Councils

Council: types

Scope: Core data structures and deterministic binary serialisation (SPEC-002) Agents: 2 builders, 1 reviewer File area: crates/mesh-types/** Depends on: none Spec refs: SPEC-002 §2.2–2.8 (primitive types, AccountState, Transition, Recipient, SettlementCertificate, ValidatorVote, EquivocationProof, Value Semiring, serialisation rules)

Task: Define primitive types and enums

Implement all primitive types from SPEC-002 §2.2: u8, u32, u64, u128, Hash (32-byte SHA3-256 output), PublicKey (32-byte Ed25519), Signature (64-byte Ed25519), Commitment (32-byte compressed Edwards point), AssetID (32-byte hash). Define enums: TransitionType (Send, Receive, Exchange, OnRamp, OffRamp), NodeType (Validator, Client, Connector). File area: crates/mesh-types/src/primitives.rs

• All types defined with correct byte sizes
• AssetID computed as SHA3-256(asset_name || issuer_pubkey || precision)
• No floating-point types anywhere in the crate

Task: Implement AccountState and Transition structures

Define AccountState (owner, sequence, balances map, state_hash, last_cert, created_at) and Transition (version, type, sender, sequence, recipients, asset_id, amount, range_proof, fee, fee_proof, causal_deps, expiry, memo, signature) per SPEC-002 §2.3–2.4. File area: crates/mesh-types/src/structures.rs

• AccountState struct with Map<AssetID, Commitment> for balances
• Transition struct with all 14 fields from SPEC-002 §2.4.1
• Recipient struct (address, amount commitment, range_proof)
• SettlementCertificate struct (transition_hash, epoch, votes)
• ValidatorVote struct (validator_id, signature)
• EquivocationProof struct (two conflicting transitions + votes)

Task: Deterministic binary serialisation

Hand-write encode/decode functions for every type. Rules per SPEC-002 §2.8: little-endian integers, length-prefixed Vec, presence-flag optionals, declaration-order struct fields, sorted-key maps. No serde. File area: crates/mesh-types/src/codec.rs

• encode() and decode() for every struct
• Round-trip property tests (encode then decode = identity) for every type
• Canonical form: identical data always produces identical bytes
• Malformed input returns errors, never panics

Task: Value Semiring implementation

Implement the Value Semiring from SPEC-002 §2.7: aggregation (⊕) for same-asset addition, exchange (⊗) for currency conversion with floor-division and remainder per Security Addendum AV-005. All arithmetic in u128, no floating point. File area: crates/mesh-types/src/value.rs

• ⊕ aggregation for same-AssetID values
• ⊗ exchange with floor division, remainder returned to sender
• Overflow checked: ERR_OVERFLOW on u128 overflow in multiplication
• ValueSet type for multi-asset aggregation

Council: crypto

Scope: Cryptographic operations — keys, signatures, commitments, range proofs (SPEC-006, SPEC-007) Agents: 2 builders, 1 reviewer File area: crates/mesh-crypto/** Depends on: types Spec refs: SPEC-006 §6.4.1 (key derivation), SPEC-007 §7.2–7.3 (Pedersen commitments, Bulletproofs+), Security Addendum AV-002 (fee range proofs), AV-007 (ephemeral key handling)

Task: Key generation and domain-separated hashing

Ed25519 key pair generation via ed25519-dalek. Derive view key per SPEC-006 §6.4.1. Domain-separated SHA3-256 hashing (each usage context gets a unique prefix to prevent cross-domain collisions). File area: crates/mesh-crypto/src/keys.rs

• generate_keypair() from CSPRNG
• derive_view_key() per SPEC-006 §6.4.1
• Domain-separated hash function with context tags
• All secret keys implement Zeroize on drop

Task: Pedersen commitments

Implement Commit(value, blinding) = value·G + blinding·H using curve25519-dalek Ristretto operations. Generator H from nothing-up-my-sleeve construction per SPEC-007 §7.2. Homomorphic verification: Σ(C_recipient_i) + C_fee = C_amount. File area: crates/mesh-crypto/src/pedersen.rs

• commit(value, blinding) returns Commitment
• Generator H derived from hash-to-point (nothing-up-my-sleeve)
• verify_conservation(inputs, outputs) using point arithmetic
• Blinding factor addition/subtraction for balance updates

Task: Bulletproofs+ range proofs

Generate and verify range proofs for values in [0, 2^64) using dalek bulletproofs with Merlin transcripts. Proofs must bind to transaction hash per SPEC-007 §7.3.2. Fee commitments MUST have range proofs per Security Addendum AV-002. File area: crates/mesh-crypto/src/rangeproof.rs

• prove_range(value, blinding, transcript) returns RangeProof
• verify_range(commitment, proof, transcript) returns bool
• Proof bound to transaction hash via Merlin transcript
• Zero-value commitments produce valid range proofs
• Negative/overflow values produce proofs that fail verification

Task: Transaction construction and validation

Build complete Transition with committed amounts and range proofs. Implement all 9 validation rules from SPEC-002 §2.4.3 with Security Addendum amendments (AV-002 fee range proofs, AV-003 causal dependency relevance check). File area: crates/mesh-crypto/src/validation.rs

• build_transition() constructs a fully signed Transition
• All 9 validation rules implemented in order
• Each rule returns the specified error code on failure
• AV-002: fee range proof required (including zero-fee)
• AV-003: causal deps checked for existence AND relevance
• Test vectors for each validation rule (valid + each failure mode)

Gate: Cryptographic implementation review — verify Pedersen generator derivation, Bulletproofs+ transcript binding, and constant-time properties before downstream councils consume mesh-crypto.

Council: network

Scope: QUIC transport layer, message framing, handshake protocol (SPEC-009) Agents: 2 builders, 1 reviewer File area: crates/mesh-network/** Depends on: types Spec refs: SPEC-009 §9.2–9.5, §9.8–9.9 (QUIC transport, framing, handshake, stream multiplexing, rate limiting, keepalive)

Task: QUIC server and client

QUIC transport using quinn with TLS 1.3 via rustls. Self-signed certificates for testnet. Server accepts connections on configurable address. Client connects with ALPN identifier "mesh/0". File area: crates/mesh-network/src/transport.rs

• QUIC server binds and accepts connections
• QUIC client connects with ALPN "mesh/0"
• TLS 1.3 with self-signed certs (via rcgen)
• Connection errors handled gracefully (no panics)

Task: Message framing and dispatch

Length-prefixed message framing: [length: u32][type: u8][payload] per SPEC-009 §9.4. Maximum frame size 4MB. Message type dispatch to handlers. Implement all message type IDs from SPEC-009 §9.4.1 (MVP subset: 0x01–0x04, 0x40–0x42, 0xF0–0xF1, 0xFF). File area: crates/mesh-network/src/framing.rs

• Encode/decode framed messages
• Reject frames exceeding 4MB
• Dispatch by message type to handler callbacks
• Malformed frames rejected (tested with fuzzy input)

Task: Handshake protocol

MESH HandshakeMessage exchange per SPEC-009 §9.3: protocol version, cipher suites, node type, public key, epoch, signature proof of key ownership. Verify remote node's identity. File area: crates/mesh-network/src/handshake.rs

• HandshakeMessage struct with all fields from SPEC-009 §9.3.2
• Signature verification of remote node's public key
• Validator nodes checked against current epoch's validator set
• Connection closed on any handshake failure

Task: Stream multiplexing and keepalive

Dedicated QUIC streams per message category per SPEC-009 §9.5: streams 0–3 for handshake/keepalive, 4–7 for Tier 1, 20–23 for queries. PING/PONG keepalive every 30s per SPEC-009 §9.9. File area: crates/mesh-network/src/streams.rs

• Stream ID ranges assigned per SPEC-009 §9.5
• PING sent every 30s if no other traffic
• PONG response within 5s
• Connection closed after 3 missed PINGs

Council: validator

Scope: Validator node binary — state store, vote handling, equivocation detection, certificate processing (SPEC-003) Agents: 3 builders, 1 reviewer File area: crates/mesh-validator/** Depends on: types, crypto, network Spec refs: SPEC-003 §3.3 (vote/certificate protocol), SPEC-002 §2.4.3 (validation rules), Security Addendum AV-003 (causal deps), AV-004 (sharding), AV-006 (epoch boundary)

Task: Account state store

Embedded key-value store using sled for AccountState keyed by PublicKey. CRUD operations. Certificate store keyed by transition hash. Equivocation record store keyed by (sender, sequence). File area: crates/mesh-validator/src/store.rs

• get_account(pubkey) returns Option
• put_account(pubkey, state) persists atomically
• get_certificate(hash) for causal dependency lookups
• put_equivocation(sender, seq, proof) for detection records

Task: VOTE_REQUEST handler

Receive a Transition, run all 9 validation rules from SPEC-002 §2.4.3 (with Security Addendum amendments). If valid, sign a vote per SPEC-003 §3.3.1. If invalid, return VOTE_REJECT with error code. Record (sender, sequence, hash) for equivocation detection. File area: crates/mesh-validator/src/vote.rs

• All 9 validation rules applied in order
• Vote signature: Sign(validator_key, transition_hash || epoch)
• VOTE_RESPONSE sent on success, VOTE_REJECT on failure
• Equivocation lock: reject second transition for same (sender, seq)

Task: Equivocation detection and proof

Maintain map of (sender, sequence) → transition_hash. On conflict, produce EquivocationProof containing both conflicting transitions and their votes. Broadcast proof to all connected validators. File area: crates/mesh-validator/src/equivocation.rs

• Detect conflicting transitions for same (sender, sequence)
• Produce EquivocationProof with both transitions
• Broadcast proof to peers
• Reject both transitions once equivocation detected

Task: SETTLEMENT_CERTIFICATE handler

Receive a certificate. Verify ≥ 2f+1 valid votes from current epoch's validator set (with one-epoch grace period per Security Addendum AV-006). Apply state transition: debit sender, credit recipients. Store certificate. File area: crates/mesh-validator/src/certificate.rs

• Verify vote count ≥ 2f+1
• Verify all vote signatures against correct epoch's validator set
• AV-006: accept current epoch and epoch-1, reject epoch-2 and future
• Apply state transition atomically (debit + credit + sequence bump)
• Store certificate in permanent record

Task: Account query handler and validator config

Respond to QUERY_ACCOUNT with current account state. TOML configuration file for validator: listen address, peer addresses, validator set (public keys), epoch number, shard assignment. File area: crates/mesh-validator/src/query.rs, crates/mesh-validator/src/config.rs

• QUERY_ACCOUNT returns current AccountState
• TOML config loaded at startup
• Validator key loaded from file (generated on first run)

Council: wallet

Scope: CLI wallet binary — key management, payment flow, balance tracking (SPEC-003 client side) Agents: 2 builders, 1 reviewer File area: crates/mesh-wallet/** Depends on: types, crypto, network Spec refs: SPEC-003 §3.3 (client-side protocol), SPEC-007 §7.2 (balance decryption via blinding factors), MVP Roadmap §Milestone 4

Task: Key management

mesh-wallet keygen generates Ed25519 key pair + derives view key. Saves to encrypted file. mesh-wallet show-address prints public key. Blinding factor store (sled DB keyed by transaction hash) — this is the wallet's most sensitive data. File area: crates/mesh-wallet/src/keys.rs

• keygen command generates and saves key pair
• show-address prints public key in hex
• Blinding factors stored locally per transaction
• Secret keys zeroized on drop

Task: Send payment flow

mesh-wallet send --to <pubkey> --amount <value> --asset <id>. Constructs a Transition with Pedersen-committed amount and Bulletproofs+ range proof. Broadcasts VOTE_REQUEST to all configured validators. Collects 2f+1 votes. Assembles SettlementCertificate. Broadcasts certificate. Prints certificate hash. File area: crates/mesh-wallet/src/send.rs

• Constructs valid Transition with committed amounts
• Sends VOTE_REQUEST to all validators
• Collects 2f+1 votes (tolerates slow/failed validators)
• Assembles and broadcasts SettlementCertificate
• Stores blinding factors for sent transaction

Task: Receive and balance commands

mesh-wallet receive --cert <hash> submits a Receive transition referencing the certificate. mesh-wallet balance queries a validator and decrypts committed balance using stored blinding factors. mesh-wallet history lists all settlements with certificate hashes. File area: crates/mesh-wallet/src/receive.rs, crates/mesh-wallet/src/balance.rs

• receive command submits Receive transition with causal dep
• balance command queries validator, decrypts locally
• history lists sent and received settlements
• Handles case where blinding factors are missing (display "encrypted")

Council: testnet

Scope: 4-validator testnet orchestration, crash recovery, end-to-end integration (MVP Roadmap §Milestone 5) Agents: 1 builder, 1 reviewer File area: config/, docker-compose.yml, Dockerfile, tests/integration/ Depends on: validator, wallet Spec refs: MVP Roadmap §Milestone 5, Dev Environment Specification §5

Task: Docker Compose testnet

docker-compose.yml starting 4 validators on a bridge network. Per-validator TOML config. Shared volume for validator key distribution. Genesis validator credits initial test accounts. File area: docker-compose.yml, Dockerfile, config/**

• docker compose up starts 4 validators
• Each validator has unique config (listen addr, peers, keys)
• Genesis mechanism credits initial accounts with test tokens
• docker compose down -v cleanly wipes all state

Task: End-to-end integration test

Automated test: Alice creates account, receives genesis credit, sends 500 tokens to Bob, Bob receives, both check balances. Confidential amounts throughout — validators never see plaintext. Run as cargo test in the workspace root. File area: tests/integration/**

• Alice→Bob send/receive completes successfully
• Balances correct after transfer (Alice: 9500, Bob: 500)
• All amounts are Pedersen-committed (no plaintext in validator logs)
• Test passes against 4-validator docker testnet

Task: Crash recovery test

Kill one validator. Verify system continues (3/4 = 2f+1). Restart killed validator. It catches up by requesting missed certificates. All 4 validators converge to identical state. File area: tests/integration/**

• Transactions succeed with 3/4 validators
• Restarted validator syncs missed certificates
• All 4 validators have identical account state after sync

Council: infra

Scope: Project scaffolding, CI pipeline, build configuration, benchmarks (MVP Roadmap §Milestone 0, §Milestone 6) Agents: 1 builder, 1 reviewer File area: Cargo.toml, .cargo/, .github/, rust-toolchain.toml, benches/**, deny.toml Depends on: none Spec refs: Dev Environment Specification §2.3–2.4 (Rust toolchain, cargo config), §6 (CI pipeline), §7 (crate dependencies)

Task: Workspace scaffolding

Cargo workspace with crates: mesh-types, mesh-crypto, mesh-network, mesh-validator, mesh-wallet. Root Cargo.toml. rust-toolchain.toml pinned to 1.85.0. .cargo/config.toml with mold linker. deny.toml for license compliance (Apache 2.0 compatible only, no GPL). File area: Cargo.toml, .cargo/config.toml, rust-toolchain.toml, deny.toml

• cargo build succeeds on empty workspace
• Rust 1.85.0 pinned via rust-toolchain.toml
• mold linker configured in .cargo/config.toml
• cargo deny check licenses passes

Task: CI pipeline

GitHub Actions workflow: format check (rustfmt), lint (clippy -D warnings), build all targets, test all targets, audit dependencies (cargo-audit), license compliance (cargo-deny). Runs on push and PR. File area: .github/workflows/ci.yml

• CI runs on every push and PR
• rustfmt, clippy, build, test, audit, deny all pass
• Uses rust:1.85.0-bookworm container image
• Cargo registry cached across runs

Task: Benchmarks

Criterion benchmarks for: Bulletproofs+ prove/verify time, Ed25519 sign/verify, Pedersen commit, serialisation round-trips, end-to-end Tier 1 latency. File area: benches/**

• cargo bench runs all benchmarks
• Range proof generation and verification benchmarked
• Signature operations benchmarked
• Results written to stdout in criterion format

Cross-Cutting Concerns

Coding standards:

• cargo fmt --all enforced. Unformatted code is rejected by CI.
• cargo clippy -- -D warnings enforced. All warnings are errors.
• No unsafe code without a // SAFETY: comment explaining why.
• No unwrap() or expect() in library code. Use Result types.
• All public functions have doc comments.

Error handling:

• Every validation failure returns the specific error code from SPEC-002 §2.4.3 (ERR_UNSUPPORTED_VERSION, ERR_INVALID_SIGNATURE, etc.).
• Network errors are logged and retried with backoff, never panicked.

Security:

• All secret key material uses zeroize crate for secure erasure.
• Constant-time operations for all secret-dependent code paths (use subtle crate for comparisons where needed).
• No logging of secret keys, blinding factors, or plaintext amounts.
• Security Addendum amendments (AV-001 through AV-007) are mandatory for all relevant code paths.

Testing:

• Property-based tests via proptest for serialisation round-trips.
• Every validation rule has a positive test and a negative test.
• Integration tests run against the 4-validator docker testnet.

Acceptance Criteria

The coordinator evaluates these as exit triggers via ov coordinator check-complete:

• All 5 crates compile with zero warnings (cargo clippy -- -D warnings)
• All unit tests pass (cargo test --all-targets)
• Serialisation round-trip property tests pass for every type
• Cryptographic test vectors pass (key gen, sign/verify, commit, range proof)
• 4-validator testnet starts via docker compose up
• End-to-end confidential payment: Alice sends 500 tokens to Bob through 4 validators, both balances correct
• Crash recovery: kill 1 validator, transact, restart, state converges
• Benchmarks run and produce results (range proof < 500ms, verify < 10ms target)
• cargo audit reports no known vulnerabilities
• cargo deny check licenses passes (Apache 2.0 compatible only)