feat!: treasury settlement layer — Mint/Burn, chain_id, tx fees, consensus params in genesis

[MehranMazhar]

Turns clutch-node into the settlement layer for a fully-reserved, redeemable token. Breaking: state format, transaction wire format, and node config all change. Testnet only; DBs must be wiped.

Peg: 1 USD = 1,000,000 CLT, so CLT is an integer micro-dollar. Balances stay u64, deltas i64 — no i128 migration (see Decision 1).

What lands

#	Change	Why
1	Referrer fees → basis points, floor rounding	2% of a fare of 3 previously ceiling-rounded to 33%
2	ChainInit transaction (tag 9, genesis-only)	Carries consensus params into state
3	Params read from state; block rewards removed; faucet testnet-gated	Unbacked minting breaks the reserve invariant
4	chain_id in the hash preimage and wire format	A testnet Mint can no longer replay elsewhere
5	Flat tx_fee to the block author	Restores validator pay as backed value moving, and gives the chain its first spam cost
6	Mint (tag 6) — authority-gated, exactly-once credit_ref	The on-ramp
7	Burn (tag 7) — permissionless, optional redemption_ref	The off-ramp
8	get_chain_info RPC	Treasury reconciliation reads total_supply; faucet reads is_testnet
9	Docs, state-key registry, 3-node smoke	—

Consensus params now ride in the genesis ChainInit transaction, whose hash feeds the genesis block hash, which peers compare at handshake. A node configured differently cannot peer — previously block_reward_amount was per-node config, so a misconfigured validator silently computed different state.

Verification

• 118 tests, 0 failures across 15 binaries (docker; no host cargo).
• Per-task review on every task + a whole-branch review; every finding fixed.
• 3-node docker smoke: get_chain_info checked over a real WebSocket from a JS client (total_supply arrives as a string — it is the one field that can pass 2^53). Divergent chain_id on one node → both sides refused the handshake naming both hashes, and the odd node never synced.
• The three money-path guards are mutation-tested: disabling each one makes its regression test fail.

Bugs this found and fixed (all would have shipped silently)

All are instances of one hazard: a block's writes commit as one deferred RocksDB batch, and every state_transaction reads pre-block state — so two writes to the same key collapse to the last one staged.

1. Minted CLT — the author's fee credit was appended after the tx loop, so a validator transacting in its own block had its debit overwritten while the recipient kept the funds.
2. Destroyed CLT — RidePay took a standalone fee debit while also crediting driver/referrers; nothing stops a passenger being their own driver or referrer, so the credit was erased after the fare had already been escrowed.
3. Reserve drain (attacker-profitable) — Burn from B plus Transfer{to: B, value: 1} from an accomplice at a higher nonce: B keeps the burned amount, yet total_supply still falls and redemption_ref commits, so the treasury pays out USDT against a burn that never debited. Cost: two fees. Fixed by a fail-closed guard rejecting blocks whose transactions write intersecting accounts (Decision 2).
4. Exactly-once hole — Mint's same-block protection relied on every Mint sharing one authorised sender; permissionless Burn broke that premise, letting two senders claim one ref. Fixed with a block-level ref-uniqueness guard.
5. Genesis-hash enforcement was missing entirely — the hash committed to the params but nothing compared it at handshake.

Decisions needing your sign-off

1. 0 decimals — CLT is the micro-dollar. Overrides spec §4a's locked "6 decimals + i128". At this peg both produce byte-identical integers, so the decimal layer and the whole i128 migration were pure cost. Also gives USDT parity (both 6dp): 1 USDT base unit = 1 CLT.
2. Fail-closed guard over merging writes. Rejecting a block is auditable; computing a merged state on a consensus path is not. Real cost: the default config points every ride at one referrer address, so two RidePays can no longer share a block. Strictly better than today, which silently destroys one of the two fees. Merging is documented in-code as the upgrade path.
3. chain_id = 2077, tx_fee = 1000 ($0.001), mint_authority = the node1 dev key (testnet only).
4. No test pins node hashing against real SDK bytes. The old fixture predated chain_id and was deleted rather than left asserting something untrue — TODO(sdk-v3) marks where to restore it.

Known / follow-ups

• Merging this breaks clutch-hub-api, clutch-explorer, clutch-hub-sdk-js, clutch-deploy and the demo app until Plan D lands. Recommend landing them together.
• Nonce tie-break makes account conflicts weaponisable for censorship (~$0.001/block, liveness only, authoring-policy-local, not consensus).
• Pre-existing, untouched: seq.rs:104 unwraps the log-ship result, so an unreachable Seq panics a task on every log line — and this repo's standalone compose has no seq service; and an idle chain produces no blocks past genesis (validate_transactions rejects an empty tx list).
• Cross-transaction credits to a third-party account still collapse; the new guard rejects those blocks rather than mis-applying them.

🤖 Generated with Claude Code