Skip to content

feat(stake): gasless owner deposit via USDC EIP-3009, default off (R3) - #1558

Merged
DealAppSeo merged 6 commits into
mainfrom
claude/r3-gasless-deposit-eip3009
Nov 16, 2026
Merged

DealAppSeo merged 6 commits into
mainfrom
claude/r3-gasless-deposit-eip3009

Conversation

@DealAppSeo

@DealAppSeo DealAppSeo commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

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_MODE on the repid-engine service (Railway project repid-engine). The default is off. Suggested order: shadow first (every check runs, nothing is sent), then on.

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,s transferWithAuthorization exists: a static call reverted at the signature check ("ECRecover: invalid signature 's' value"), not at an unknown function.

Nothing here is a second verifier

step reused code
signature, time window, recipient verifyEip3009Local (x402-resilient.ts, the x402 path)
USDC's signing domain resolveAndVerifyDomain (x402-outbound-client.ts): name/version read from the chain and matched to DOMAIN_SEPARATOR
the send the escrow's guarded path. realSender's body is now escrowCall, 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.
the credit depositStake's verified path: the on-chain Transfer check from that wallet to the escrow, the exact-amount rule, and one credit per tx hash

src/services/gasless-deposit.ts adds 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 existing POST /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.
  • Negative control: without the replay guard, the second call reaches the relay and the replay tests go red.
  • 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.
  • With the existing refunder, deposit-route, auth, flag-registry and stake-spend suites: 147 passed, 1 skipped (Windows local). tsc --noEmit clean.

Grok review (fenced lane, v4)

  • r1 on 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:
    1. Confirmed and fixed in 94443820: if depositStake threw after the escrow had sent, the route answered 500 with no tx hash. It now answers 202 credit_not_checked with the hash. Test added; it fails on the previous source.
    2. Not a defect: the balance is not re-checked inside the per-nonce lock, but a second deposit with too little USDC fails at gas estimation, before broadcast, so the escrow pays no gas.
    3. Not a double credit: depositStake ignores its duplicate-read error, but the unique index stake_deposits_real_tx_hash_uniq is applied in prod [V SQL] and refuses a second credit of one transfer.
  • r2 on 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.
  • A process-wide admission budget, createGaslessAdmission(4/min), injected as deps.admit. Past it, the answer is 429 escrow_busy and nothing is queued. Shadow mode and refused deposits use no admission.
  • Three new tests fail on the previous source. The gasless, auth, relay and refunder suites pass 59/59.

Not changed: depositStake and 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 in 2f900680: 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 carry verifyDeposit'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 against d5d0e498):

  • the raw-error echo was already fixed in 2f900680;
  • confirmed and fixed in 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 d0e46baf yet. The same raw-error echo exists, before this PR, on POST /stake/deposit (depositStake errors) and the spend route; that is a follow-up.

Not done here

  • No route hands out the typed data to sign. The client (TrustShell, the PAI) builds it from the domain above. Add one if a client wants it.
  • 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

…_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>
@DealAppSeo
DealAppSeo marked this pull request as ready for review November 16, 2026 05:04
@strix-security

strix-security Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

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 summary

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.

3 resolved findings
Ruled out (5)
  • Can two simultaneous, or cross-replica, submissions of the same authorization make the escrow relay it twice and pay gas for a duplicate?
    The in-process lock only suppresses duplicates; the USDC nonce is the shared authority, a failed send maps to a plain error answered as not_sent (never sent:true), and the single-replica precondition with its advisory-lock follow-up is already documented in the repo.
  • Can a caller make the escrow pay gas for a transaction that must revert, then resubmit that authorization indefinitely?
    populateTransaction runs eth_estimateGas before signing or broadcast, so an already-invalid authorization never reaches the wire, and a revert that consumes the nonce flips authorizationState so resubmission is refused as authorization_used.
  • Does the keyless route's catch-all echo internal error text such as an RPC provider URL containing an API key?
    Every chain, DB, relay and credit error inside the service is caught and logged with a fixed answer, leaving only operator-config text (a network name, the already-public escrow address) reachable through the handler's catch, which also matches the file's pre-existing pattern.
  • Is the new escrowRelayAuthorization under-guarded, since it checks only the recipient and has no value floor, time window or local signature check?
    Its only production caller gates amount, recipient, expiry, signature, account, nonce and balance first, and the helper itself cannot move escrow funds: the call debits the signer's own address and the recipient must be the escrow.
  • Can an unauthenticated caller exhaust database and RPC work through the keyless route despite the admission budget?
    The global per-source limiter is mounted ahead of the auth middleware and the v1 router so it caps the route at 60 requests per minute, the default-off mode returns before any read, and the same wallet lookup already existed on the pre-existing keyless deposit route.
Review history (5)
  • Review 5 · 64e0209 · Nov 16 06:03 UTC · Nothing new
  • Review 4 · d0e46ba · Nov 16 05:57 UTC · Nothing new
  • Review 3 · 2f90068 · Nov 16 05:49 UTC · Fixed 2
  • Review 2 · d5d0e49 · Nov 16 05:23 UTC · Found 2 new Low Vulnerabilities · Fixed 1
  • Review 1 · 9444382 · Nov 16 05:10 UTC · Found 1 Low Vulnerability

Review 5 on this PR · 64e0209 · requested Nov 16 05:57 UTC on a new commit


Reviewed by Strix
Re-run review · Configure security review settings · Try a deeper review with @strix-security /deep

@strix-security strix-security Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strix flagged a new security finding below. See the pinned summary comment for the full PR status.

Comment thread src/services/gasless-deposit.ts Resolved
Comment thread src/services/gasless-deposit.ts Resolved
Comment thread src/services/gasless-deposit.ts Resolved
…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>

@strix-security strix-security Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strix flagged 2 new security findings below. See the pinned summary comment for the full PR status.

Comment thread src/services/gasless-deposit.ts Resolved
Comment thread src/services/gasless-deposit.ts Resolved
Comment thread src/services/gasless-deposit.ts Resolved
Comment thread src/services/gasless-deposit.ts Resolved
Comment thread src/services/gasless-deposit.ts Resolved
DealAppSeo and others added 2 commits November 15, 2026 21:42
…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>

@strix-security strix-security Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

@strix-security strix-security Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@strix-security strix-security Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@DealAppSeo

Copy link
Copy Markdown
Owner Author

Grok review (fenced lane) round 4 on 64e02092: NO_FINDINGS

Run by Claude Code through the fenced wrapper (grok-review.v4.mjs, reviewer profile, read-only, MCP off). The wrapper accepted the answer: the nonce matched, the checkout was on 64e02092f6413f09f9549b7f04a8f0ae099ecf2a, and every cited file was opened.

Round 3 was on d5d0e498. This round covers the three commits since:

  • 2f900680: admission now happens after the in-lock authorizationState re-check (Grok r3's finding), and answers never carry error text.
  • d0e46baf: one admission slot per payer per minute, on top of the global 4 (Strix).
  • 64e02092: renames that variable; no behaviour change.

Spec checked (R1–R6):

  • R1: a value under 1 USDC is refused before any chain read, admission or relay. Shadow mode never admits.
  • R2: admit is called once per request, only in on mode, after every refusal including the in-lock re-check, and before relay. A 409/503 from the re-check takes no slot; false answers 429 without relaying.
  • R3: at most 4 admissions per minute overall and 1 per payer (case-insensitive). A refused call records nothing.
  • R4: there is one process-wide admission instance, keyed by the signature-bound from.
  • R5: no answer carries error text from the chain reads, account lookup, relay or credit. Every answer after relay returns keeps the tx hash.
  • R6: the tests cover R2, R3 and R5.

Evidence:

  • r3.r4.test-output-head.txt: 41/41 pass across the gasless, auth-bypass and relay suites.
  • r3.r4.test-output-old-src.txt: the same tests against the round-3 gasless-deposit.ts. The 4 new tests fail: re-check takes no slot, no error text, wired per-payer 429, and the createGaslessAdmission per-payer bound.

Result: NO_FINDINGS, nothing listed as not checked.

My adjudication: agree. Two notes, neither a finding:

  • A relay that fails (502 not_sent) keeps its slot, by design: the escrow did attempt a send.
  • bad_signature still carries verifyEip3009Local's reason, including ethers' local signature-recovery text. That function makes no network call, so no URL or key can be in it.

Not merged, and auto-merge is off.

@DealAppSeo
DealAppSeo merged commit 95d60b3 into main Nov 16, 2026
19 checks passed
@DealAppSeo
DealAppSeo deleted the claude/r3-gasless-deposit-eip3009 branch November 16, 2026 16:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant