docs: treasury settlement release — peg, Mint/Burn, chain_id, fee model

[MehranMazhar]

Documents the breaking release across clutchprotocol/clutch-node#9, clutch-hub-api#3, clutch-hub-sdk-js#4, clutch-explorer#5, clutch-deploy#1 and clutch-hub-demo-app#1.

Merge this before those merges publish the new APIs — otherwise docs.clutchprotocol.io describes a protocol that no longer exists.

What the release changed, and why the docs had to move with it

CLT became a fully-reserved, redeemable claim: every unit in circulation must be backed 1:1 by off-chain reserve. Peg is 1 USD = 1,000,000 CLT, so CLT is an integer micro-dollar with no decimals. That one decision drove everything else, and several pages documented the previous economic model as fact.

• Block rewards are gone. clt-economics.md presented per-block emission as the model; minting unbacked CLT permanently breaks the reserve invariant, so validator income is now a flat tx_fee credited to the block author — which also gives the chain its first spam cost, since transactions used to be free.
• Mint (tag 6) and Burn (tag 7) are the on- and off-ramps, and the only operations that change supply. Mint is authority-gated with an exactly-once credit_ref; Burn is permissionless with an optional redemption_ref.
• ChainInit (tag 9) carries consensus parameters into genesis state, so they are committed to by the genesis hash — and a node configured differently is refused at the p2p handshake rather than silently diverging.
• chain_id is inside the signed payload, so a testnet transaction cannot be replayed on another network.
• Referrer fees are basis points with floor rounding; the old ceiling rule turned 2% of a 3-unit fare into 33%.
• Fares cross the GraphQL boundary as String — Int is 32-bit and overflows at roughly a $2,147 fare at this peg.
• SDK v3 uses bigint amounts and verifies the hub-returned transaction before signing.

Scope

21 files — the 17 that referenced changed surfaces, plus json-rpc.md and both subscriptions.md pages found stale while grepping.

Highest-consequence page is reference/signing-and-encoding.md, since anyone writing a client implementation follows it byte-for-byte: it now carries the 4-item preimage, the 8-item wire layout with chain_id at index 2 encoded minimal big-endian, and the full non-contiguous RLP tag table.

Accuracy

Ground truth came from reading the actual source on each repo's treasury-break branch rather than from the change description, which caught two errors in my own brief:

• There is no createUnsignedMint. Mint is node-only — it is signed by the treasury authority, never built by the hub. Documenting a hub mutation for it would have sent integrators looking for an endpoint that does not exist.
• The SDK implements 7 of the 10 RLP tags, not all of them: Transfer is faucet-only (server-side), Mint is treasury-side, ChainInit is genesis-only.

One boundary is stated explicitly rather than glossed: the chain enforces mint authority and exact supply accounting, but it cannot verify that off-chain reserve exists. That is enforced by process and reconciliation, not consensus, and the docs no longer imply otherwise.

Verification

npm run build passes. Docusaurus fails the build on broken internal links, which surfaced one stale self-anchor — fixed.

Two items flagged for a human decision

1. faucet_amount_clt was $0.001 — exactly one tx_fee — so a funded test account could send one zero-value transaction and reach zero without ever affording a ride. Confirmed on a live stack. Raised to $100 in clutch-hub-api#3 and clutch-deploy#1.
2. The hub's chainInfo omits latest_block_index, which the node's get_chain_info RPC does return. Documented as-is rather than adding a field with no consumer; worth deciding whether the hub should expose it.

🤖 Generated with Claude Code