Skip to content

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

Description

@bussyjd

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 Docker requirements check #90).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions