feat(evm): share browser payment APIs and durable payment recovery - #17
Draft
mickvandijke wants to merge 9 commits into
Draft
mickvandijke wants to merge 9 commits into
mickvandijke wants to merge 9 commits into
Conversation
This was referenced Sep 15, 2026
Draft
Measured on DEV-03 run 589 (2026-09-16) against sepolia-rollup.arbitrum.io: 26 of 938 native uploads failed at the payment step, none of them for a network reason, all in the journal path introduced by a5f3d61: - `observe_payment` reported `Finalizing` when a `latest` nonce read was higher than the nonce just signed from a `pending` read. The two reads are separate HTTP requests and the endpoint's replicas lag each other (reproduced: `pending=98` then `latest=99`, 1 pair in 150), and finality on Arbitrum Sepolia trails by ~28 nonces, so every stale read became "awaiting chain finality" on bytes that were never broadcast. - Every read in `prepare_payment`/`observe_payment` and the broadcast itself were single-shot, where the legacy `send_transaction_with_retries` path retried three times. One `429` or `-32000 context deadline exceeded` on any of ~9 calls per wave failed the upload, after earlier waves had paid. Now: - `prepare_payment` takes the higher of a `pending` and a `latest` read, so one lagging replica cannot sign a consumed nonce, and sets the chain id explicitly so `fill` makes no RPC call. - Reads go through `retry()`. Reads made while a caller polls use a 500ms base (the native client observes inside a 30s window). - A consumed-but-unfinalised nonce with no receipt reads as `Pending`, not `Finalizing`: it is indistinguishable from a stale read, re-sending the journaled bytes is refused by the node rather than paid twice, and finality still resolves a real replacement into `Replaced`. `Finalizing` is kept for a mined revert that is not yet final. - `broadcast_payment` retries the same bytes on transport-level failures (HTTP status, connection loss, timeouts, backend-deadline responses) and treats "already known" as success. Definitive rejections return at once. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
finalizedtag; 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
Proposed for human review: changes payment submission and recovery behavior.
Compatibility
Consumers of the draft journal API must handle
PaymentStatus::FinalizingandPaymentStatus::Replaced. The storedSignedPaymentrepresentation is unchanged.Semver impact
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-timefor portable clocks and WASM-targetgloo-timers,futures-util, and JavaScript-enabledgetrandom. 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
Current stack revisions
All PRs link to V2-803. Immutable Git revisions used by the validated stack:
29a2b272cf424c046f0b1f620df7853ecdae7d1926f5fb79f1303e1aEVM 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.