Gasless USDC/USDT0 transfers (replaces OpenGSN for transfers)

[sisou]

Stablecoin sends (the send modal and Moonpay sells) now use gasless USDC/USDT0 transfers through the GaslessTransfer contract and Nimiq relay of NimiqToolbox/gas-abstraction (private) instead of OpenGSN. Mainnet has been in gas abstraction maintenance mode since 2026-09-18. Swaps, HTLC refunds and the USDC.e conversion are unchanged and still use OpenGSN; they move to the new gas abstraction in a follow-up.

Part of a coordinated change

Repo	PR	Depends on
Keyguard	nimiq/keyguard#570	–
Hub	nimiq/hub#592	nimiq/keyguard#570
Wallet	this PR	nimiq/hub#592 (new @nimiq/hub-api types)

Release order: Keyguard, then Hub, then Wallet.

Flow

1. The relay quotes the fee (GET /v1/fee, permit mode). The Wallet refuses quotes above maxAcceptableFee (0.50); the Keyguard applies the same limit.
2. The Wallet reads the sender's permit nonce and checks the token's DOMAIN_SEPARATOR() against the pins.
3. The Hub and Keyguard sign the intent and a permit (signPolygonTransaction with a SignPolygonGaslessTransferRequest).
4. The Wallet records the signed version, then submits it (POST /v1/transfer), re-posting after unclear answers. It waits until the transfer is mined and parses the receipt's TransferRelayed event.

Never paying twice

Every version of a payment keeps its intent nonce, so at most one executes (see the SDK's "Failures, retries and replacements").

• stores/GaslessPayments.ts records each payment's latest signed version before it is submitted, until its outcome is final at the finalized block. It keeps no signatures. It is persisted, and on startup the outcome checks resume.
• A retry, or a new send of the same token to the same recipient after a failure (also after a reload, or from Moonpay), is a correction that keeps the nonce. Before signing a correction, the Wallet checks on-chain whether a version already executed.
• lib/usdc/GaslessOutcome.ts is an ethers v5 port of the SDK's confirmOnChain / waitForTransferOutcome. The Wallet doesn't use viem.

Other changes

• History: a relay fee is recognized in gasless transactions and merged into the principal transfer. OpenGSN fee detection stays for past transactions. OpenGSN contracts that are not configured are skipped, which fixes the history sync on the local stack.
• Config: polygon.gasless (relay URL, contract, relay addresses, deploy block, fee limits). Sending is controlled by the new isGaslessTransferUnderMaintenance; isGasAbstractionUnderMaintenance still controls swaps. The local config targets the gas-abstraction Anvil stack.
• Removed: only createTransactionRequest, the OpenGSN transfer request.
• Fixed: Moonpay USDC sells used the USDT token contract.

Before merging

• Set polygon.gasless.relayUrl and relays in config.mainnet.ts (TODOs), then set isGaslessTransferUnderMaintenance: false.
• Replace "@nimiq/gasless-sdk": "file:../gas-abstraction/sdk" with the published package. A clean install fails without the sibling checkout.
• Update @nimiq/hub-api to the version released from Gasless USDC/USDT0 transfers (replaces OpenGSN for transfers) hub#592. Locally, this was tested with yarn link.
• End-to-end test against the local Anvil stack (send, fee_too_low and sender_busy corrections, relay restart, reload during a pending payment), then a mainnet canary from team accounts.

Open points

• A send is lowered to balance − fee if needed, as before. A Moonpay deposit would then arrive short; refusing may be better.
• waitForTransferOutcome has no per-request time budget like the SDK, so a hung RPC can stall that background check.

Testing

• tsc (the only src/ errors are the two in router.ts that also exist on master), yarn lint, testnet build.
• Not tested end to end yet.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AKgXoeSB62akioiTzYya6C