ObolNetwork / ObolNetwork/obol-stack

batch-settlement: trustless reclaim escape hatch (initiateWithdraw/finalizeWithdraw)

Open
#788 0 comments 0 reactions 0 assignees View on GitHub

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 initiateWithdraw then finalizeWithdraw from a payer signer,
    tracking withdrawDelay (15 min–30 days) and auto-finalizing when the grace period elapses.
  • TS @x402/evm client helper (same, for browser/widget use).
  • Widget "force withdraw" fallback UI (main wallet submits; surfaces the grace-period wait).
  • Note in docs: cooperative refundWithSignature is the everyday reclaim; this is the backstop.

Notes

  • finalizeWithdraw returns 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.