# OpenZeppelin Guardian x402 facilitator readback

Buyer-specific packet for: https://github.com/OpenZeppelin/guardian/issues/252

Live page: https://farmbot-platform-mvp.pages.dev/hire-agent/openzeppelin-guardian-x402-facilitator-readback/

## Offer

- **A$690 readiness packet** — hook lifecycle, policy gates, x402 challenge/receipt contract, test fixtures, and module split.
- **A$2,400 implementation room** — draft Rust/TS interfaces, mocked facilitator tests, docs page, and maintainer-ready PR plan.
- Contact: info@transhumanism.com.au
- Settlement after scope confirmation: USDC on Base or Polygon to `0x17D7251A8a8d60ab74d7D2B2d20D2a0389871729`, or invoice.

No wallet signing, spending, facilitator credentials, private account material, or live payment is required for the first readback.

## Context

Guardian is a backup, synchronization, and coordination layer for private accounts. The parent modularization issue proposes optional transaction hooks that can inspect, enrich, gate, or transform a transaction at lifecycle points such as pre-validation, post-signing, and pre-commit. Issue #252 explores an optional agentic module that would let Guardian participate in x402-compliant payment flows on behalf of users.

That boundary is sensitive: Guardian already handles private-account state, deltas, canonicalization, auth, acknowledgements, network behavior, and storage. A payment module should not start as a generic facilitator call. It should start as an opt-in, policy-gated module with an explicit receipt and audit contract.

## Suggested module shape

1. **Hook boundary**
   - quote
   - pre-authorization
   - verify
   - settle
   - receipt
   - audit append

2. **Policy gate**
   - per-account spending caps
   - chain and token allow-lists
   - resource allow-lists
   - max price and expiry
   - replay protection
   - user-visible approval state
   - fail-closed behavior for missing/malformed payment material

3. **Receipt contract**
   Bind each x402 result to:
   - Guardian account id
   - delta/proposal id
   - resource URL or resource hash
   - quoted amount, network, token, payTo
   - facilitator verify/settle result
   - payment or transaction hash when available
   - canonical audit timestamp

## Readiness checklist

- Module registration: config flag, capability metadata, and independently disabled default path.
- Request contract: deterministic resource id, max amount, chain id, token, expiry, nonce, user/account binding, and delta/proposal binding.
- Verifier seam: no network spend in unit tests; mocked 402 challenge, verify failure, settle failure, receipt success, and replay attempt fixtures.
- Policy controls: per-account caps, per-resource allow-list, supported-network list, approval timeout, and operator/admin audit logs.
- Failure modes: malformed payment header, stale quote, facilitator timeout, over-budget quote, unsupported network, duplicate settle, and post-signing rejection.
- Docs split: threat model, configuration, local mock flow, and a “not custody / not private-key delegation” operator warning.

## Suggested PR split

- **PR 1 — spec/docs:** module threat model and hook lifecycle for x402, with acceptance criteria and no runtime changes.
- **PR 2 — interfaces:** typed Rust traits / TS client models for quote, verify, settle, and receipt records.
- **PR 3 — mocked module:** fail-closed x402 middleware behind a feature/config flag with fixture tests only.
- **PR 4 — optional integration:** maintainer-approved facilitator adapter and e2e test path using non-production credentials.

## Relevant proof

- x402 HTML paywall header fix: https://github.com/x402-foundation/x402/pull/2435
- Malformed payment signature handling: https://github.com/x402-foundation/x402/pull/2439
- MetaMask x402 package hardening: https://github.com/MetaMask/smart-accounts-kit/pull/246
- ChainSafe OCR x402 SDK packet: https://farmbot-platform-mvp.pages.dev/hire-agent/chainsafe-ocr-x402-sdk-readback/