ObolNetwork / ObolNetwork/obol-stack
batch-settlement: trustless reclaim escape hatch (initiateWithdraw/finalizeWithdraw)
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 11
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
Summary
Add client-side tooling for the batch-settlement trustless reclaim escape hatch —
initiateWithdraw(config, amount) → (grace period) → finalizeWithdraw(config) — so a payer can
unilaterally recover unclaimed escrow if the receiver/facilitator goes dark.
Context
The batch-settlement facilitator (upstream PR x402-rs/x402-rs#90; beta image #4) ships the escrow and
the cooperative refund path (refundWithSignature, gasless, needs receiver consent). The trustless
timed-withdrawal escape hatch is specified (scheme_batch_settlement_evm.md:51) and the escrow exposes
initiateWithdraw/finalizeWithdraw, but in x402-rs these are ABI bindings only — zero call sites
(crates/chains/x402-chain-eip155/src/v2_eip155_batch_settlement/facilitator/abi.rs:150,152).
Why the facilitator can't do it
initiateWithdraw/finalizeWithdraw are msg.sender-gated (caller must be payer or
payerAuthorizer) with no signature variant — unlike claimWithSignature/refundWithSignature.
So the facilitator cannot relay/sponsor them; the tx must be submitted by the payer's own wallet (needs
ETH). This is the reclaim path that keeps escrow trustless even if the service disappears.
Deliverables
- Rust client helper: build + submit
initiateWithdrawthenfinalizeWithdrawfrom a payer signer,
trackingwithdrawDelay(15 min–30 days) and auto-finalizing when the grace period elapses. - TS
@x402/evmclient helper (same, for browser/widget use). - Widget "force withdraw" fallback UI (main wallet submits; surfaces the grace-period wait).
- Note in docs: cooperative
refundWithSignatureis the everyday reclaim; this is the backstop.
Notes
finalizeWithdrawreturns only escrow still unclaimed after the grace window (server may claim
legitimately-held vouchers during it — fairness).- Depends on batch-settlement facilitator landing (PR #90).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with scheme_batch_settlement_evm.md:51 and the initiateWithdraw/finalizeWithdraw ABI bindings in crates/chains/x402-chain-eip155/src/v2_eip155_batch_settlement/facilitator/abi.rs. Check the batch-settlement facilitator dependency in PR #90, then trace the Rust client, the TS @x402/evm client, and widget entry points. Done means payer-submitted timed withdrawal works in both clients, the widget exposes the grace-period fallback, and the documentation distinguishes it from cooperative refunds.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust, typescript
- Domain
- blockchain, documentation, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100