feat(evm): share browser payment APIs and durable payment recovery

[mickvandijke]

Summary

Allows browser clients to use the same EVM payment types, quote hashing, pricing, Merkle algorithms, and vault encodings as native clients. The portable layer excludes native process and environment facilities; optional RPC uses browser Fetch and timers, while the default native feature retains Anvil and native wallet support.

Merkle checkpoints preserve the original salts and random padding so recovery reconstructs the same payment intent. Native wallets can prepare and sign a payment without broadcasting, persist its exact transaction bytes, then submit or observe that same transaction after interruption. Journal validation binds the transaction to its wallet, chain, vault, and intended calldata.

Recovery distinguishes pending transactions, unfinalized failures, finalized reverts, and finalized nonce replacements. A same-intent fee replacement returns its successful receipt and settlement hash; a different finalized nonce consumer permits a fresh attempt. Missing history, RPC errors, and unexplained nonce advances retain the journal. Failed-payment retry decisions use canonical receipts and the RPC finalized tag; successful payments keep the existing optimistic canonical-inclusion semantics. See PAYMENT_RECOVERY.md for finality and historical-RPC requirements.

Native-only tests are feature-gated, and CI covers both portable and RPC-only test configurations.

Linear issue

Closes V2-803 — Linear issue

Risk tier

• T0 — docs / tooling / CI / pure UX-output. Repo CI only.
• T1 — client-only, no network-facing behavior change. CI + prod compat smoke.
• T2 — node/client logic with behavioral surface, no protocol/format/economics change. Dev testnet + ADR.
• T3 — protocol / storage format / payments / routing. T2 evidence + adversarial testing.

Proposed for human review: changes payment submission and recovery behavior.

Compatibility

• Wire: Existing quote hashes, vault ABI, payment proofs, and native serialization remain shared and unchanged. External signers reuse the native Merkle call encoder and event decoder.
• Storage: Adds serializable Merkle checkpoints preserving salts and random padding; no on-chain storage change. Native signed-payment journals retain exact transaction bytes.
• API: Default native wallet APIs remain available. Adds portable/RPC feature selection, shared encoding helpers, Merkle checkpoint serialization, and native prepare/broadcast/observe payment APIs.

Consumers of the draft journal API must handle PaymentStatus::Finalizing and PaymentStatus::Replaced. The stored SignedPayment representation is unchanged.

Semver impact

• breaking
• feature
• fix

Test evidence

Validated on the current revision during this refresh:

• cargo test --test wallet journaled: 7 passed, covering canonical success, Merkle winner recovery, reverted transactions across a reorg, finality before retry, finalized nonce replacement, successful fee replacement, and unexplained nonce consumption.
• cargo test --no-default-features: 10 tests passed; native-only integration targets are gated out.
• cargo test --lib --test cryptography --no-default-features --features rpc,external-signer: 19 passed.
• cargo clippy --all-targets --all-features -- -D warnings: passed.
• cargo check --lib --no-default-features --features rpc,external-signer --target wasm32-unknown-unknown: passed.

The coordinated ant-client recovery suite also exercises the native caller's handling of finalized replacements. Local results do not replace CI or production RPC validation.

New dependency

Adds web-time for portable clocks and WASM-target gloo-timers, futures-util, and JavaScript-enabled getrandom. Existing Alloy and Tokio dependencies use explicit feature gates. No new standalone crate or parallel browser payment implementation is introduced.

ADR

ant-client ADR-0004: Direct browser immutable-data client documents shared payment preparation, journals, and recovery across native/browser adapters. Saorsa Core ADR-019 covers the shared portable dependency architecture.

Mitigation / rollback

Keep consumers on the default native feature or revert the coordinated client/EVM revisions together. Preserve unresolved transaction journals; a missing receipt is not proof that another payment is safe.

Coordinated consumers

• ant-protocol#29 exposes the shared EVM types and native journal API.
• ant-client#186 uses native/browser payment preparation and recovery.
• ant-node#220 retains the shared payment verification path.

Current stack revisions

All PRs link to V2-803. Immutable Git pins are aligned with these pushed branch heads:

PR	Revision
evmlib#17	cf424c04
ant-protocol#29	d557f5e1
saorsa-core#158	dc00a2c1
saorsa-transport#160	bc6dcd80
ant-node#220	4c1509dd
ant-client#186	2b0aa662
saorsa-pqc#7	29a2b272

EVM recovery now retains ambiguous journals until finalized failure/replacement evidence is available. The protocol and native client include the matching consumer changes. Existing browser wire and payment formats are retained.