feat!: v3 — chain_id in signing, bigint amounts, unsigned-tx verification, Burn

[MehranMazhar]

Companion to clutchprotocol/clutch-node#9 and clutchprotocol/clutch-hub-api#3. Merge last — merging this to main publishes v3.0.0 to npm via semantic-release, so the node and hub should be in place first.

Wire format

The node moved its hash preimage to the 4-item RLP list [from (no 0x), nonce, chain_id, data] and its signed payload to the 8-item list [from, nonce, chain_id, r, s, v, hash, data], chain_id at index 2.

chain_id is encoded as minimal big-endian to match Rust's u64 append — 2077 is 82 08 1d, byte-verified in the self-check rather than merely round-tripped, because a round-trip would pass even if both sides were wrong together.

Amounts become bigint

fare, farePaid, amount and balances are bigint; GraphQL variables are String.

JSON.parse silently rounds integers above 2^53. At the peg of 1 USD = 1,000,000 CLT a number fare was already lossy before signing — the user would sign one amount and believe they had approved another. GraphQL's Int compounded it by being 32-bit, overflowing at roughly a $2,147 fare.

rlp accepts bigint directly, so values pass through unconverted — RLP-encoding a decimal string would encode its UTF-8 text rather than the integer.

Also adds formatUsd(microUsd) (integer math, no floats) so UIs can show $5.00 instead of 5000000.

The security fix: stop signing blindly

signTransaction previously signed whatever blob the hub returned, checking nothing. The hub is the untrusted party in this design — the key never leaves the client because the hub isn't trusted — yet it could alter the fare, swap the referrer, or hand back another chain's id, and this SDK would sign it. Client-side signing protected the key but not the user.

verifyUnsignedTransaction(unsignedTx, expected) now checks from, function_call_type, fare/amount (BigInt-parsed), tx-hash references, and the chain id — throwing before anything is signed.

Two details that matter more than they look:

• The chain id is pinned client-side, from app config — never from the hub's chainInfo. Asking the untrusted party which chain it is defeats the check entirely.
• Verification fails closed with no pinned chain. An earlier revision skipped the chain check when no chainId was configured, reasoning that nothing had been pinned. That quietly recreated the exact hole chain_id was added to close: every check runs except the one that stops a cross-chain replay, while the caller believes the transaction was validated. It now throws. (Nearly unreachable anyway, since ensureAuth needs the real chain id for the chain-bound challenge — so this mostly turns a confusing downstream auth failure into a precise message.)

The hub-injected referrer cannot be verified without the signed-quote flow a later plan adds, so verification returns it for the UI to display before signing. That display is the interim mitigation, not a fix.

Also

• Burn (RLP tag 7) with its optional redemption_ref, empty-string convention included, plus createUnsignedBurn.
• Auth challenge is chain-bound: clutch-auth:{chainId}:{publicKey}:{timestamp}, matched byte-for-byte against the hub's committed Rust fixtures. Previously a challenge signed on testnet authenticated the same key against any other Clutch hub inside the ±120s window.
• dist is loadable under Node ESM again — relative imports gained .js extensions. tsc emits extensionless specifiers and there is no "type": "module", so import './dist/index.js' failed with ERR_MODULE_NOT_FOUND; the repo's own ad-hoc check scripts had rotted for this reason.

Verification

npm run build && node test_wire_v3.mjs → wire v3 self-check OK. It asserts the 8-item layout, the chain_id bytes, Burn tag 7 with and without a ref, a tampered fare throwing, a mismatched chain id throwing, fail-closed on an unpinned chain, and formatUsd cases.

Not covered here: a live cross-check against a running node/hub, which needs a funded faucet on a running stack — that happens in the full-stack smoke. The auth fixtures are a real cross-language match against the hub's Rust, which is the strongest check available without the stack.

Known, deliberately not changed

dist still emits a MODULE_TYPELESS_PACKAGE_JSON warning. Adding "type": "module" would change module resolution for every consumer of a published package (breaking CJS require), which deserves its own decision rather than riding along here.

🤖 Generated with Claude Code

[MehranMazhar]

🎉 This PR is included in version 3.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀