Repository navigation
feat(stake): gasless owner deposit via USDC EIP-3009, default off (R3) - #1558
Conversation
…_MODE, default off) A newcomer has testnet USDC and no ETH. The owner signs a transferWithAuthorization (owner -> stake escrow) in their wallet; POST /api/v1/stake/deposit/gasless checks it, the escrow submits it and pays the gas, and depositStake's verified path credits it. Nothing new verifies a signature: verifyEip3009Local (the x402 path) checks it against USDC's name/version read from the chain and matched to its DOMAIN_SEPARATOR (resolveAndVerifyDomain). The send is the escrow's guarded path: realSender's body is now escrowCall, shared by the refund, the stake payout and the relay, and the relay joins the same one-at-a-time queue (one nonce). Refused before the escrow spends gas: wrong recipient, zero amount, expired or expiring within 120 s, bad signature, no account for the payer, nonce already used on chain (replay), balance too low, any unreadable read. A concurrent second submission of one authorization is serialized and refused. off: refused without reading. shadow: every check, nothing sent. on: submit, credit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…x hash (Grok r1 lead on #1558) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Strix Security Review✅ No open security findings. All previously reported findings have been resolved. PR summary: Adds an opt-in, default-off keyless route where a stake owner signs a USDC EIP-3009 transferWithAuthorization, the escrow submits it and pays the gas, and the stake is credited through the existing verified deposit path, behind a 1 USDC floor plus global and per-payer admission limits, and refactors the escrow's send helper so refunds, payouts and the new relay share one guarded path. Review summaryReviewed the keyless gasless stake deposit end to end: the new Nothing was confirmed as a vulnerability. Funds can only move from the signer's wallet to the escrow (the recipient check and the token's own signed struct both bind it), the signature is bound to all six authorization fields and to the chain-read USDC domain, replay is refused both before and inside the lock, a duplicate credit is blocked by the on-chain nonce plus the per-tx-hash unique index, and a broadcast that cannot succeed fails at gas estimation before gas is spent. The default-off mode, the Base-SEPOLIA-only send path, the 1 USDC floor, the per-payer and global admission limits, and the global per-IP limiter in front of the route all hold up. Worth passing to the author as optional hardening, not as findings: the route's outer catch-all still reflects 3 resolved findings
Ruled out (5)
Review history (5)
Review 5 on this PR · Reviewed by Strix |
…of the escrow queue (Strix on #1558) The keyless route refused only value <= 0, so a 1-micro-USDC authorization made the escrow pay a full transaction; and the per-authorization lock never makes two different authorizations wait, so a caller could queue more escrow sends than one signer drains, ahead of refunds and agent payouts. - MIN_GASLESS_DEPOSIT = 1 USDC, refused before any send. - createGaslessAdmission(4/min), process-wide, injected as deps.admit: past it, 429 escrow_busy and nothing is queued. Shadow mode and refused deposits use no admission. Not changed: depositStake and the owner-signed withdraw have no floor of their own; withdrawal needs the owner's signature, so it is not this keyless path. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sion after the in-lock re-check - No chain, DB, relay or credit error text reaches a gasless answer; it is logged server-side. ethers puts the request URL in its messages and a provider URL can carry an API key (the class Strix found on #1559). depositStake's error can carry verifyDeposit's raw RPC text too, so it is logged. - The admission slot is now taken after the in-lock authorizationState re-check, just before the relay, so a concurrent replay refused there uses no slot (Grok r3 on #1558). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…f the global cap (Strix on #1558) One wallet could take all 4 global slots with concurrent deposits the escrow then refused, keeping the keyless route at 429 for everyone else. createGaslessAdmission(4, 1) now also bounds each payer (case-insensitive) to 1 a minute; rotating wallets still meets the global cap, and each wallet needs an account and the USDC it signs for. Tests fail on the previous source. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Reviewed the keyless EIP-3009 gasless-deposit route, its reuse of verifyEip3009Local/resolveAndVerifyDomain, the new escrowCall/escrowRelayAuthorization send path, and the credit it performs through depositStake. No new security vulnerability is confirmed. Both findings from the previous review are fixed at their locations: gasless answers no longer carry chain, relay or credit error text (every chain, relay and credit failure is logged and replaced with a fixed string, and checked.reason can only contain the caller's own values), and the admission budget is now taken after every refusal and after the in-lock nonce re-check, so refused deposits consume no slot. The authorization tuple is bound end to end — signer equals from, exact amount, recipient equals the escrow, 120 s minimum remaining window, unused nonce read on chain before and inside the lock — and USDC itself re-verifies signature, window and nonce, so a gap off-chain can only cost the escrow gas, never move unauthorized funds. The credit cannot be steered: the route accepts no account identifier, and verifyDeposit pins the on-chain Transfer's sender to the credited wallet, recipient to the escrow, token, chain and exact amount, with a partial unique index on the tx hash and a per-hash lock behind it. The refactor of realSender into escrowCall is behaviour-preserving for refunds, agent payouts and the relay (same chain, signer-equals-escrow, hash-before-broadcast and proof-only settlement), the ABI addition leaves the transfer selector unchanged, and the auth bypass is a literal method-plus-path compare that fails closed. Two LOW issues remain worth fixing as hardening rather than as exploitable vulnerabilities: the EIP-712 digest chainId is read from NETWORK instead of the chain that was verified, so a mistyped network silently breaks the feature, and a deposit whose relay then fails at gas estimation still spends an admission slot.
Reviewed by Strix
Configure security review settings
…a wallet), not 'key' credential-safety-architecture flagged `r.payer === key` as a secret comparison. It compares wallet addresses, so the variable is renamed rather than allowlisted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Reviewed the new keyless EIP-3009 gasless-deposit path end to end, including the latest commit's per-payer admission bound, and found no security issue in the changed code.
The signature check is bound to every value the escrow later submits (the same parsed authorization object is verified and encoded, with the recipient checked in the service, in the local verifier and again in the relay), the escrow send is pinned to Base Sepolia and to the escrow payee and cannot be redirected in callee, token, amount or native value, and the credit re-derives the payer, token, recipient and exact amount from the on-chain Transfer log through the existing verified deposit path, so nothing can be credited that did not arrive.
The auth change is an exact-path, POST-only bypass, and no router or catch-all mounted ahead of the v1 router intercepts that path.
The admission changes hold up: the per-payer key is alias-safe (address spellings collapse to one lowercased key), the sliding window fails closed, and the 4/min global cap still paces the escrow's shared send queue below its drain rate at the repo's documented single-replica deployment and default confirmation count.
The only residual items are robustness rather than security — the local verifier takes its EIP-712 chainId from the NETWORK env instead of the chain the relay is pinned to, and the route-level catch still echoes exception text (no attacker-reachable throw carries a secret on a correctly configured deployment) — and the credit-target squatting path exists identically on the pre-existing keyless deposit route, so it is not introduced here.
Reviewed by Strix
Configure security review settings
There was a problem hiding this comment.
Reviewed the keyless gasless stake deposit end to end: the new POST /api/v1/stake/deposit/gasless route and its auth-bypass entry, the gaslessDeposit ordering and refusals, the EIP-3009 signature and domain verification reuse, the escrowCall refactor plus escrowRelayAuthorization, the credit through depositStake, the admission budget, the flag wiring and the accompanying tests.
Nothing was confirmed as a vulnerability. Funds can only move from the signer's wallet to the escrow (the recipient check and the token's own signed struct both bind it), the signature is bound to all six authorization fields and to the chain-read USDC domain, replay is refused both before and inside the lock, a duplicate credit is blocked by the on-chain nonce plus the per-tx-hash unique index, and a broadcast that cannot succeed fails at gas estimation before gas is spent. The default-off mode, the Base-SEPOLIA-only send path, the 1 USDC floor, the per-payer and global admission limits, and the global per-IP limiter in front of the route all hold up.
Worth passing to the author as optional hardening, not as findings: the route's outer catch-all still reflects e?.message (the in-service paths already log and return fixed text, so this only surfaces operator-config text), and having verifyEIP3009Local take the chain id from the already-verified domain read rather than the process-wide network setting would keep the two halves of the domain check from disagreeing if NETWORK is ever set to base.
Reviewed by Strix
Configure security review settings
Grok review (fenced lane) round 4 on
|
Owner action
You decide (MAJOR: money path; the escrow submits on-chain transactions and pays their gas). Draft. Do not auto-merge. Merging changes nothing until you set
GASLESS_DEPOSIT_MODEon therepid-engineservice (Railway projectrepid-engine). The default isoff. Suggested order:shadowfirst (every check runs, nothing is sent), thenon.Why
A newcomer has testnet USDC and no ETH, and a plain ERC-20 transfer needs gas (onboarding friction log, stop 4). With EIP-3009 the owner signs a USDC
transferWithAuthorization(from: their wallet, to: the stake escrow). That is a signature, not a transaction. The escrow submits it and pays the gas, and the stake is credited. The owner needs zero ETH.Base Sepolia USDC supports this [V on chain, read-only
eth_call, 2026-11-16]name()=USDC,version()=2,DOMAIN_SEPARATOR()equals the one computed for chain 84532.authorizationState(address, bytes32)answers. The v,r,stransferWithAuthorizationexists: a static call reverted at the signature check ("ECRecover: invalid signature 's' value"), not at an unknown function.Nothing here is a second verifier
verifyEip3009Local(x402-resilient.ts, the x402 path)resolveAndVerifyDomain(x402-outbound-client.ts): name/version read from the chain and matched toDOMAIN_SEPARATORrealSender's body is nowescrowCall, shared by refund, stake payout and relay (Base Sepolia only, signer == escrow, signed before broadcast, unknown outcome reported as unconfirmed). The relay also joins the escrow's one-at-a-time queue, so there is one nonce.depositStake's verified path: the on-chain Transfer check from that wallet to the escrow, the exact-amount rule, and one credit per tx hashsrc/services/gasless-deposit.tsadds only the order, and the refusals that must come before the escrow spends gas.Refused before anything is sent
wrong recipient · zero amount · expired · expiring within 120 s (it could revert after the escrow paid gas) · not yet valid · signature by anyone but
from, or over a different amount · no account for the payer (the USDC would arrive with nobody to credit) · nonce already used on chain (replay) · balance below the amount · any unreadable chain or DB read (503, "not checked").A second submission of the same authorization is refused 409
authorization_used. Two at once are serialized: one is sent, the other is refused.Outcomes after a send
201: sent and credited (tx hash, Basescan link).202 sent_unconfirmed: broadcast, outcome unknown. Tx hash given; nothing credited.202 sent_not_credited: the USDC reached the escrow and the credit refused (for example, too few confirmations). Tx hash given, to claim through the existingPOST /stake/deposit. It is never reported as credited.Route
POST /api/v1/stake/deposit/gasless { authorization, signature }. It is keyless on purpose, added to the auth bypass list for that exact method and path: the owner's signature is the authorization, and a newcomer has no API key. The global rate limiter still applies.Tests
tests/gasless-deposit.test.ts, 26 tests with real EIP-712 signatures from a throwaway in-test wallet. The fake chain keeps a used-nonce set the way the USDC contract does, so replay is tested against "used on chain", not a flag. Replay (sequential, concurrent, already used on chain), expiry (past, too soon, boundary), not-yet-valid, wrong signer, tampered amount, wrong recipient, no account, low balance, unreadable chain, shadow, off, unconfirmed broadcast, sent-not-credited, malformed input, mode parsing.tests/escrow-relay-authorization.test.ts: no signer key → refused; a payee that is not the escrow → refused before any send; the relay waits behind an in-flight refund (shared queue).tests/gasless-deposit-auth.test.ts: the bypass is POST-only and exact-path.tsc --noEmitclean.Grok review (fenced lane, v4)
76d1ed8d: NOT_CHECKED. It timed out after nine files with no final answer, so it is not a pass. Its unfinished reasoning raised three leads, which I checked myself:94443820: ifdepositStakethrew after the escrow had sent, the route answered 500 with no tx hash. It now answers 202credit_not_checkedwith the hash. Test added; it fails on the previous source.depositStakeignores its duplicate-read error, but the unique indexstake_deposits_real_tx_hash_uniqis applied in prod [V SQL] and refuses a second credit of one transfer.94443820(narrower: this file plus the relay): NO_FINDINGS.Strix (LOW finding, fixed in
d5d0e498)Strix found that the keyless route refused only
value <= 0. A 1-micro-USDC authorization made the escrow pay a full transaction. And because the per-authorization lock never makes two different authorizations wait, a caller could queue more escrow sends than one signer drains, ahead of refunds and agent payouts. Confirmed. The fix:MIN_GASLESS_DEPOSIT= 1 USDC, refused before any send.createGaslessAdmission(4/min), injected asdeps.admit. Past it, the answer is 429escrow_busyand nothing is queued. Shadow mode and refused deposits use no admission.Not changed:
depositStakeand the owner-signed withdraw have no floor of their own. A withdrawal needs the owner's signature, so it is not this keyless path.Grok r3 on
d5d0e498: CHALLENGED, 1 finding, confirmed. The admission slot was taken before the in-lock re-check, so a concurrent replay refused there still used a slot. Fixed in2f900680: admission now comes after that re-check, just before the relay.Same commit, the class Strix found on #1559: no chain, DB, relay or credit error text reaches a gasless answer; it is logged on the server. ethers puts the request URL in its messages, and a provider URL can carry an API key.
depositStake's error can carryverifyDeposit's raw RPC text too, so it is logged rather than returned. Two new tests fail on the previous source; 61/61 pass.Strix, second pass (2 LOW, on
2f900680; written againstd5d0e498):2f900680;d0e46baf: one wallet could take all 4 global slots with concurrent deposits the escrow then refused. Each payer now gets 1 slot a minute (case-insensitive), on top of the global cap. Rotating wallets still meets the global cap, and each wallet needs an account here and the USDC it signs for. Two tests fail on the previous source; 35/35 pass in the gasless suite.All Strix threads are replied to and resolved.
Gates on the current head: no Grok round covers
d0e46bafyet. The same raw-error echo exists, before this PR, onPOST /stake/deposit(depositStakeerrors) and the spend route; that is a follow-up.Not done here
receiveWithAuthorization(only the payee may submit) would stop third parties from front-running. Front-running here only moves the money to the escrow sooner, and the claim path still credits it by tx hash, so I kept to the type the x402 verifier already checks.🤖 Generated with Claude Code