@absol-labs/agent 0.10.0 → 0.12.0-rc.1

package/docs/x402.md

@@ -0,0 +1,681 @@
+# Metrik and x402
+
+> **Status.** This package implements **x402 v2 `exact` payments that settle
+> into a `StreamEscrowV2` stream**, through the ownerless
+> `X402StreamOpenerFactory` (metrik-contracts#48). It ships a facilitator
+> service (`metrik-x402-opener-facilitator`) and an opt-in x402 v2 mode on the
+> seller gateway. **Both are OFF by default** and have not yet run in
+> production. The factory is deployed and Sourcify-verified on Base Sepolia at
+> `0x43DA0D9602f7fc5ac0bb90461e39b033EB493d24` (implementation
+> `0xbD8B7B2F49Fdb954bda6bE5ce22218d44345DC43`, block 47337415); everything
+> here is testnet only.
+>
+> The separate Metrik-native `402` flow (scheme `streamproof-verified-stream`,
+> header `X-METRIK-PAYMENT`) described at the end is **not** x402 and is
+> unchanged.
+
+## The hard rule: an opener `payTo` is settled ONLY by the Metrik opener facilitator
+
+**Read this before running any of it.** The x402 `payTo` in this mode is the
+address of an `X402StreamOpener`. Every stock x402 `exact` facilitator settles
+by calling `USDC.transferWithAuthorization(to = payTo)` directly. Pointed at an
+opener, that transfer succeeds and **strands 100% of the payer's payment in the
+opener permanently**: the opener deliberately has no sweep or "claim stray
+funds" path (one would be exploitable, because a used and a cancelled EIP-3009
+nonce are indistinguishable on-chain). The same happens if anyone who sees the
+signed payload submits it to USDC first. See metrik-contracts
+`evm/docs/x402-opener.md`.
+
+So, in this package, and for anyone integrating it:
+
+1. **Only the Metrik opener facilitator may settle an opener `payTo`.** It
+   calls `factory.deployAndSettle(terms, authorization)`, which pulls the
+   payment into the opener and opens the stream in the same transaction. Its
+   `GET /supported` advertises a marker —
+   `kinds[].extra.metrikStreamOpener = {settlement: "x402-stream-opener",
+factory, escrow, usdc, chainId, minAmount, receiptTimeoutSeconds, refundRelay?}` — so a resource server can tell it apart
+   from a stock facilitator. `refundRelay: true` means the same service also
+   runs the gasless refund relay (see below).
+2. **The gateway refuses to start** unless its configured facilitator's
+   `/supported` carries that marker for exactly the gateway's factory, escrow,
+   token and chain. It re-checks the marker on a timer (default every 300 s)
+   and **fails closed** whenever it cannot prove it: `503
+x402-facilitator-unavailable`, no `PAYMENT-REQUIRED`, nothing verified,
+   nothing served, nothing settled anywhere else. A facilitator that is
+   unreachable when a payment arrives produces `402`, never a free call.
+3. **Never advertise an opener `payTo` to third-party facilitators or discovery
+   catalogs** (the x402 Bazaar extension or any other). The gateway registers
+   no discovery extension and never submits its route to any catalog. Only
+   when the operator configures `METRIK_GATEWAY_X402V2_SCHEMA` does the 402
+   _declare_ an input/output schema, in the standard `extensions.bazaar` shape,
+   so a client can read what to send; the only facilitator that ever sees the
+   payment is the Metrik opener facilitator, and it catalogs nothing. Do not
+   register the route with a discovery service.
+4. **Authenticate an opener only as `factory.predict(terms) == payTo`** (or
+   `factory.isOpener(address)`), never by code or codehash: anyone can clone the
+   implementation outside the factory with byte-identical code. The
+   facilitator recomputes `predict` on-chain for every payment.
+5. **The signed payment never leaves the gateway→facilitator path.** The
+   gateway strips `PAYMENT-SIGNATURE` (and `X-PAYMENT`) before proxying to the
+   seller's upstream.
+
+## How a payment flows
+
+```
+buyer (@x402/fetch)            gateway (x402 mode)             opener facilitator           chain
+  │  GET /resource  ───────────▶ 402 + PAYMENT-REQUIRED
+  │                               payTo = factory.predict(terms)
+  │  PAYMENT-SIGNATURE ─────────▶ POST /verify ───────────────▶ all checks below
+  │                               upstream request (status < 400?)
+  │                               POST /settle (bearer) ──────▶ deployAndSettle ────────────▶ USDC → opener → StreamEscrowV2
+  │  200 + body + PAYMENT-RESPONSE ◀── receipt shows the stream ◀─────────────────────────── StreamOpened / StreamOpenedFor
+```
+
+- **Terms.** One listing's immutable terms are `{operator, serviceRef,
+ratePerSecond, maxDuration}`; the opener for them lives at
+  `factory.predict(terms)` whether or not it is deployed yet. The terms travel
+  in `PaymentRequirements.extra.metrikStreamOpener` (with the factory address);
+  the payer's EIP-3009 signature binds `to = payTo`, so it commits to them.
+- **Price = deposit.** Each paid request opens one stream with `deposit =
+price`, on the listing's terms. The escrow records the **opener** as the
+  stream's buyer; the opener records the payer (`payerOf(streamId)`).
+- **Earning.** Unchanged: the operator earns `ratePerSecond × verified
+seconds`, capped at the deposit, claimed with `claimWithProof` against the
+  oracle's checkpoints, minus the 0.5% protocol fee.
+- **Settle after serve.** The gateway settles only when the upstream answered
+  `< 400`, and before any upstream byte reaches the buyer (the reference
+  `@x402/*` middleware order). An upstream `>= 400` submits nothing, so no
+  funds move. A failed settlement sends no upstream body.
+
+### What the facilitator checks (every payment, fail closed)
+
+Standard `exact` checks are delegated to the official `@x402/evm`
+`ExactEvmScheme` verifier (signature, `to == payTo`, `value == amount`,
+validity window, asset contract, a simulation of the transfer). The stock
+scheme is given a signer that cannot broadcast, so its direct-transfer settle
+path is structurally unreachable. On top of it:
+
+| Check                                                                                                                                                                                                                                           | Refusal reason                                                         |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| x402 v2, scheme `exact`, the configured CAIP-2 network                                                                                                                                                                                          | `metrik_opener_unsupported_*`                                          |
+| `payload.accepted` equals the requirements exactly                                                                                                                                                                                              | `metrik_opener_accepted_requirements_mismatch`                         |
+| Asset transfer method is EIP-3009 (Permit2 and everything else refused)                                                                                                                                                                         | `metrik_opener_asset_transfer_method_not_eip3009`                      |
+| Not an ERC-6492 (counterfactual smart wallet) signature                                                                                                                                                                                         | `metrik_opener_erc6492_signature_unsupported`                          |
+| Asset is allowlisted and equals `factory.usdc()`                                                                                                                                                                                                | `metrik_opener_asset_not_allowed`                                      |
+| Terms are well formed; the factory named is the configured one                                                                                                                                                                                  | `metrik_opener_invalid_terms` / `_factory_mismatch`                    |
+| `0 < amount <= ratePerSecond × maxDuration`                                                                                                                                                                                                     | `metrik_opener_invalid_amount` / `_amount_exceeds_rate_times_duration` |
+| `payTo == factory.predict(terms)`, read on-chain                                                                                                                                                                                                | `metrik_opener_pay_to_not_predicted_opener`                            |
+| `(operator, serviceRef)` resolve to exactly one **operator-signed** listing (the existing discovery verification: schema, re-derived `serviceRef`, recovered EIP-712 operator signature), and the rate is inside its signed `commercial` bounds | `metrik_opener_listing_*`                                              |
+| `deployAndSettle` simulates cleanly from the relayer                                                                                                                                                                                            | `metrik_opener_settle_simulation_failed`                               |
+
+`settle` re-runs all of it, broadcasts `deployAndSettle`, waits for the
+receipt, and reports `success: true` only when the mined receipt contains both
+the escrow's `StreamOpened` (buyer = opener, exactly these terms and deposit)
+and the opener's `StreamOpenedFor` (this payer, nonce and amount). The
+`SettleResponse` carries `extra.metrikStreamOpener = {streamId, opener, escrow,
+deposit, ratePerSecond, expiresAt}`. A revert (for example an authorization that
+was already used) is `success: false` with the reason. A receipt that does not
+arrive in time is `settlement_pending`; a later settle of the same payload
+reconciles against that transaction instead of broadcasting a second one.
+
+### At most one success per authorization
+
+Each EIP-3009 authorization — keyed by chain, asset, payer and authorization
+nonce — receives **at most one successful `SettleResponse` from a facilitator
+instance, ever**:
+
+- A settle (or verify) of an authorization that is already in flight or already
+  settled returns `success: false` / `isValid: false` with
+  `duplicate_settlement` (carrying the tx hash when there is one). One payment
+  can never buy two served responses.
+- After `settlement_pending`, a retry of the SAME payload verifies (even though
+  the authorization may already be used on-chain) and its settle reconciles to
+  the mined outcome; it receives the one success only if none was delivered
+  before.
+- The gateway enforces the same rule on its side: a `PAYMENT-SIGNATURE` whose
+  authorization is in flight or already settled gets `409
+x402-payment-already-used` **without** an upstream call; a retry after
+  `settlement_pending` is let through so it can reconcile.
+- Relayer submissions (simulate + broadcast) are serialized, so concurrent
+  payers never collide on the relayer's account nonce.
+
+**Scope of the guarantee: both ledgers are in-memory and per instance.** They
+do not survive a restart and are not shared between replicas. Run exactly one
+facilitator instance (and one gateway instance per listing); a multi-instance
+deployment would need a shared store, which does not exist today. Entries are
+kept until the authorization's `validBefore` has passed (plus a grace), after
+which USDC itself refuses the authorization.
+
+## Getting unearned money back: the gasless refund relay
+
+**There is no automatic refund.** Nothing pushes money back to a payer, and no
+keeper runs in the background. Unearned money comes back only when someone
+calls the relay endpoints below (or calls the opener directly). What the relay
+removes is the need for ETH: a typical x402 payer holds only USDC, so the
+facilitator's relayer pays the gas for the two transactions a refund needs.
+
+The escrow's buyer of record is the opener, so a refund goes through it:
+
+1. **Close** (optional — only to stop before `expiresAt`). `opener.close` is
+   payer-only on-chain, because anyone else could cut a payer's service. The
+   relay submits `opener.closeWithSig` with the payer's EIP-712 signature.
+2. **Reclaim**, once the settlement window allows it: a checkpoint covering the
+   stop time (close, or `expiresAt`) is posted — the oracle posts every
+   ~15–22 s — or `escapeGraceSeconds` (900 s on the live escrow) have passed
+   since the stop. `opener.reclaim(streamId, cumulativeAmount, proof)` is
+   permissionless: the escrow fixes the amount (a Merkle proof against its
+   **latest** checkpoint root) and the opener fixes the destination
+   (`payerOf(streamId)`). The relay fetches the proof from the oracle itself.
+3. **Escape hatch**, only if no usable proof ever appears: after
+   `expiresAt + escapeGraceSeconds` the payer may sign `ReclaimUnverified` and
+   the relay submits `reclaimUnverifiedWithSig`. It returns `deposit -
+claimedCumulative` and forfeits the seller's earned-but-unclaimed revenue, so
+   it is **never** relayed without the payer's signature; the unsigned
+   `reclaimUnverified` is payer-only on-chain and the relay never calls it.
+
+The streamId and the refund URL arrive with the paid response:
+`PAYMENT-RESPONSE.extra.metrikStreamOpener = {streamId, opener, escrow,
+deposit, ratePerSecond, expiresAt, refundUrl}`.
+
+### Endpoints (on the facilitator service; public, no bearer token)
+
+| Method + path                                | Body                                           | Does                                                            |
+| -------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------- |
+| `GET /streams/:streamId`                     | —                                              | Status, and exactly what the payer can do next                  |
+| `POST /streams/:streamId/close`              | `{"deadline": "<unix s>", "signature": "0x…"}` | Relays `closeWithSig` (payer's EIP-712 `Close`)                 |
+| `POST /streams/:streamId/reclaim`            | none                                           | Fetches the oracle proof, relays `reclaim`                      |
+| `POST /streams/:streamId/reclaim-unverified` | `{"deadline": "<unix s>", "signature": "0x…"}` | Relays `reclaimUnverifiedWithSig` (payer's `ReclaimUnverified`) |
+
+The payer signs, with the opener as the EIP-712 domain
+(`{name: "Metrik X402StreamOpener", version: "1", chainId, verifyingContract:
+<opener>}`):
+
+```
+Close(bytes32 streamId,uint256 nonce,uint256 deadline)
+ReclaimUnverified(bytes32 streamId,uint256 nonce,uint256 deadline)
+```
+
+`nonce` is the payer's current `opener.nonces(payer)`; `deadline` must be at
+least 60 s after the current chain time. `GET /streams/:streamId` returns the
+ready-to-sign typed data (with the current nonce) under `next.typedData`, so a
+client signs it as-is after choosing a deadline. An optional `"nonce"` in the
+body turns a stale nonce into a clear `409 nonce-mismatch`.
+
+`GET /streams/:streamId` answers `200` with:
+
+```json
+{
+  "streamId": "0x…",
+  "chainId": 84532,
+  "escrow": "0x…",
+  "factory": "0x…",
+  "opener": "0x…",
+  "payer": "0x…",
+  "operator": "0x…",
+  "serviceRef": "0x…",
+  "deposit": "60000",
+  "ratePerSecond": "1000",
+  "claimedCumulative": "0",
+  "openedAt": 1790452888,
+  "expiresAt": 1790452948,
+  "closedAt": 1790452902,
+  "status": "closed",
+  "reclaimed": false,
+  "chainTime": 1790452910,
+  "settlement": {
+    "stopAt": 1790452902,
+    "latestCheckpointCheckedAt": 1790452904,
+    "checkpointCoversStop": true,
+    "fallbackAt": 1790453802,
+    "escapeHatchAt": 1790453848
+  },
+  "oracle": {
+    "cumulativeAmount": "14000",
+    "checkpointId": "61222",
+    "checkedAt": 1790452904,
+    "root": "0x…"
+  },
+  "reclaimable": "46000",
+  "payerNonce": "1",
+  "next": {
+    "action": "reclaim",
+    "method": "POST",
+    "path": "/streams/0x…/reclaim",
+    "message": "…"
+  },
+  "refunds": "There is no automatic refund. …"
+}
+```
+
+`closedAt` is `null` while active; `oracle` and `reclaimable` are `null` when
+no proof that matches the escrow's on-chain latest root is available (with an
+`oracleNote`). `next.action` is one of `close` (with `typedData` and the body
+shape), `wait` (with `retryAt` / `retryAfterSeconds`), `reclaim`,
+`reclaim-unverified` (with `typedData`), or `none`.
+
+A successful relayed transaction answers `200` only from its **mined** receipt:
+
+```json
+{ "ok": true, "action": "close", "streamId": "0x…", "opener": "0x…",
+  "payer": "0x…", "transaction": "0x…", "message": "…", "next": { "path": "/streams/0x…/reclaim" } }
+{ "ok": true, "action": "reclaim", "streamId": "0x…", "opener": "0x…",
+  "payer": "0x…", "amount": "46000", "entitlement": "14000", "transaction": "0x…", "message": "…" }
+```
+
+(`action` is `reclaim-unverified` for the escape hatch.) Every refusal is
+`{"ok": false, "error": "<code>", "message": "…", …}`, with `Retry-After`
+where a retry makes sense:
+
+| Status | `error`                                                                                         | Meaning                                                                                     |
+| ------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| 400    | `invalid-stream-id`, `invalid-request`, `invalid-json`                                          | Malformed input                                                                             |
+| 403    | `invalid-signature`, `signature-expired`                                                        | Not the payer's EIP-712 signature for this opener, stream and nonce; or deadline too near   |
+| 404    | `not-found`                                                                                     | Unknown stream, or its buyer is not an opener of the configured factory                     |
+| 409    | `already-closed`, `stream-expired`, `already-reclaimed`, `nothing-to-reclaim`, `nonce-mismatch` | Would have no effect; nothing sent                                                          |
+| 409    | `not-reclaimable-yet`, `settlement-window-open`, `proof-unavailable`, `escape-hatch-not-ready`  | Not yet; `retryAt` (unix s) says when at the latest                                         |
+| 409    | `simulation-failed`, `in-progress`, `blocked`                                                   | The simulation reverted; a relayed tx is in flight; an earlier tx had an unexpected outcome |
+| 202    | `pending`                                                                                       | Sent, not mined yet (`transaction`); repeat the same request — it is never re-sent          |
+| 429    | `rate-limited`                                                                                  | Per-IP, per-stream or global budget exhausted                                               |
+| 502    | `transaction-reverted`, `unexpected-receipt`, `submission-failed`                               | Never a success without the expected mined receipt                                          |
+| 503    | `chain-unavailable`, `oracle-unavailable`, `opener-domain-mismatch`                             | Fail closed                                                                                 |
+
+### Bounded against gas abuse
+
+- **Opener streams only.** `factory.isOpener(stream.buyer)` is read on-chain
+  first; every other stream is `404` before any signature check, oracle call or
+  simulation.
+- **No effect, no transaction.** Every precondition the contract checks is read
+  first (status, expiry, settlement window, `reclaimed`, a non-zero refund). A
+  reclaim's simulation must return exactly the non-zero `reclaimableFor`
+  amount. Nothing is broadcast without a successful simulation.
+- **Proofs are checked, not trusted.** The oracle's proof must be for this
+  stream, verify under the escrow's leaf
+  `keccak256(bytes.concat(keccak256(abi.encode(streamId, cumulative))))`, and
+  its root must equal the escrow's on-chain `latestCheckpointRoot`. A tampered
+  proof (for example one claiming less delivery) is refused without a
+  transaction; the contract would refuse it anyway.
+- **At most one successful close and one successful reclaim per stream** from
+  a facilitator instance (the proof and escape-hatch paths share the reclaim
+  slot, as the escrow allows one). Concurrent duplicates are refused
+  synchronously; a repeat after success is refused without any transaction.
+- **Read fan-out is bounded.** Every `/streams` request (read or write) counts
+  against a per-client-IP limit AND an IP-independent global limit (default
+  120/min, `429` + `Retry-After`). A stream's status and its oracle proof are
+  reused for a few seconds (default 5 s), so repeated requests for one stream
+  do not re-hit the RPC or the oracle; the cache for a stream is dropped as
+  soon as a relayed transaction for it is mined, and a broadcast is still
+  decided by a fresh simulation.
+- **No internal errors leak.** RPC, oracle and simulation failures are
+  answered with a generic message and an error code (`chain-unavailable`,
+  `oracle-unavailable`, `simulation-failed`, `submission-failed`); the detail
+  is logged server-side with URL paths redacted, never the relayer key. Only
+  a decoded contract custom-error name (for example `StreamClosedAlready`) is
+  returned.
+- **Budgets.** Per client IP (all `/streams` routes), per stream (relayed
+  submission attempts) and globally per minute. Refused requests — a forged
+  signature, a request with no effect — do not consume a stream's budget, so
+  spamming cannot lock a payer out.
+- **Receipts.** Success only from a mined receipt with the escrow's
+  `StreamClosed` / `BuyerReclaimed` and the opener's `StreamCloseRequested` /
+  `ReclaimForwarded` for exactly this stream, payer and amount.
+- **One relayer queue.** Relay submissions and `deployAndSettle` go through the
+  same serialized queue, so they never race for the relayer's nonce.
+
+## Running the facilitator
+
+```bash
+METRIK_OPENER_FACILITATOR_ENABLED=1 \
+METRIK_OPENER_FACILITATOR_RPC_URL=https://sepolia.base.org \
+METRIK_OPENER_FACILITATOR_RELAYER_PRIVATE_KEY=<from your secret store> \
+METRIK_OPENER_FACILITATOR_AUTH_TOKEN=<at least 32 random characters> \
+npx metrik-x402-opener-facilitator
+```
+
+| Variable                                                             | Default                               | Meaning                                                                              |
+| -------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `METRIK_OPENER_FACILITATOR_ENABLED`                                  | off                                   | Must be truthy or the service refuses to start.                                      |
+| `METRIK_OPENER_FACILITATOR_RPC_URL`                                  | required                              | RPC for reads, simulation and the settlement transaction.                            |
+| `METRIK_OPENER_FACILITATOR_RELAYER_PRIVATE_KEY`                      | required                              | Pays gas for `deployAndSettle`. Never holds buyer funds; never logged.               |
+| `METRIK_OPENER_FACILITATOR_AUTH_TOKEN`                               | required (≥ 32 chars)                 | Bearer token required on `/settle`.                                                  |
+| `METRIK_OPENER_FACILITATOR_FACTORY_ADDRESS`                          | the Base Sepolia factory              | Required on any other chain.                                                         |
+| `METRIK_OPENER_FACILITATOR_ESCROW_ADDRESS`                           | live Base Sepolia `StreamEscrowV2`    | Must equal `factory.escrow()`.                                                       |
+| `METRIK_OPENER_FACILITATOR_NETWORK`                                  | `eip155:84532`                        | Must match the RPC's chain id.                                                       |
+| `METRIK_OPENER_FACILITATOR_ASSETS`                                   | Circle test USDC                      | Comma-separated allowlist; must contain `factory.usdc()`.                            |
+| `METRIK_OPENER_FACILITATOR_REGISTRY_URL`                             | `https://oracle.metrik.live/listings` | Where operator-signed listings are read.                                             |
+| `METRIK_OPENER_FACILITATOR_LISTING_CACHE_SECONDS`                    | `60`                                  | Reuse of a successful registry read (failures are never cached).                     |
+| `METRIK_OPENER_FACILITATOR_RECEIPT_TIMEOUT_SECONDS`                  | `60`                                  | Receipt wait before `settlement_pending`.                                            |
+| `METRIK_OPENER_FACILITATOR_REQUIRE_AUTH_ON_VERIFY`                   | **on**                                | Require the token on `/verify` too; `0` opts out explicitly.                         |
+| `METRIK_OPENER_FACILITATOR_MIN_AMOUNT`                               | `10000` (0.01 USDC)                   | Smallest accepted payment; advertised in the marker.                                 |
+| `METRIK_OPENER_FACILITATOR_SETTLE_RATE_LIMIT_PER_MINUTE`             | `60`                                  | Authorized `/settle` calls per token per minute; beyond it `429`.                    |
+| `METRIK_OPENER_FACILITATOR_HOST` / `_PORT` (or `PORT`)               | `127.0.0.1` / `8788`                  | Bind address. Put TLS in front of it.                                                |
+| `METRIK_OPENER_FACILITATOR_REFUND_RELAY`                             | **on**                                | The gasless refund relay; `0` switches it off (a gateway then refuses to start).     |
+| `METRIK_OPENER_FACILITATOR_ORACLE_URL`                               | `https://oracle.metrik.live`          | Serves `GET /checkpoint/proof?streamId=`. Required off Base Sepolia.                 |
+| `METRIK_OPENER_FACILITATOR_PUBLIC_URL`                               | unset                                 | Public origin, for absolute links (`next.url`) in relay responses.                   |
+| `METRIK_OPENER_FACILITATOR_REFUND_RATE_LIMIT_PER_IP_PER_MINUTE`      | `30`                                  | `/streams/*` requests per client IP per minute.                                      |
+| `METRIK_OPENER_FACILITATOR_REFUND_GLOBAL_RATE_LIMIT_PER_MINUTE`      | `120`                                 | `/streams/*` requests per minute from all clients together (IP-independent).         |
+| `METRIK_OPENER_FACILITATOR_REFUND_READ_CACHE_SECONDS`                | `5`                                   | Reuse of one stream's status and oracle proof; `0` disables.                         |
+| `METRIK_OPENER_FACILITATOR_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE` | `3`                                   | Relayed transactions per stream per minute.                                          |
+| `METRIK_OPENER_FACILITATOR_REFUND_SUBMISSIONS_PER_MINUTE`            | `30`                                  | Relayed refund transactions per minute, all streams.                                 |
+| `METRIK_OPENER_FACILITATOR_TRUST_PROXY`                              | off                                   | Key the per-IP limit on the right-most `X-Forwarded-For` hop. See the warning below. |
+
+> **`TRUST_PROXY=1` is only safe when the service is bound to loopback
+> (`METRIK_OPENER_FACILITATOR_HOST=127.0.0.1`, the default) behind a reverse
+> proxy that overwrites `X-Forwarded-For` with the address it actually saw
+> (Caddy's `reverse_proxy` does).** Never enable it when the port is reachable
+> directly: any client could then send its own `X-Forwarded-For` and get a
+> fresh per-IP budget on every request. The global cap still applies either
+> way.
+
+At startup it proves the wiring (RPC chain id, factory code, `factory.escrow()`,
+`factory.usdc()` allowlisted; for the relay, `factory.escrow()` and the escrow's
+`escapeGraceSeconds`) and refuses to start otherwise. Endpoints:
+`GET /supported`, `POST /verify`, `POST /settle` (bearer), `GET /health`, and
+the refund relay's `GET /streams/:streamId` and
+`POST /streams/:streamId/{close,reclaim,reclaim-unverified}` (public).
+
+## Running the gateway in x402 mode
+
+The gateway's normal variables (`METRIK_GATEWAY_ESCROW_ADDRESS`,
+`METRIK_GATEWAY_RPC_URL`, `METRIK_GATEWAY_SERVICE_REF`,
+`METRIK_GATEWAY_UPSTREAM_URL`, …) are unchanged. The listing is the primary
+`METRIK_GATEWAY_SERVICE_REF`. Add:
+
+| Variable                                                         | Default                            | Meaning                                                                                                                                   |
+| ---------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `METRIK_GATEWAY_X402V2_OPENER`                                   | off                                | Truthy to enable the mode.                                                                                                                |
+| `METRIK_GATEWAY_X402V2_FACILITATOR_URL`                          | required                           | The Metrik opener facilitator.                                                                                                            |
+| `METRIK_GATEWAY_X402V2_FACILITATOR_TOKEN`                        | required                           | Its `/settle` bearer token.                                                                                                               |
+| `METRIK_GATEWAY_X402V2_OPERATOR`                                 | required                           | Must be the operator that signed the listing.                                                                                             |
+| `METRIK_GATEWAY_X402V2_RATE_PER_SECOND`                          | required                           | USDC base units per second.                                                                                                               |
+| `METRIK_GATEWAY_X402V2_MAX_DURATION_SECONDS`                     | required                           | Stream lifetime.                                                                                                                          |
+| `METRIK_GATEWAY_X402V2_PRICE`                                    | required                           | Base units per paid request (= deposit); `0 < price <= rate × maxDuration`.                                                               |
+| `METRIK_GATEWAY_X402V2_FACTORY_ADDRESS`                          | the Base Sepolia factory           | Required on any other chain.                                                                                                              |
+| `METRIK_GATEWAY_X402V2_NETWORK`                                  | `eip155:<METRIK_GATEWAY_CHAIN_ID>` | Must match the chain id.                                                                                                                  |
+| `METRIK_GATEWAY_X402V2_ASSET` / `_ASSET_NAME` / `_ASSET_VERSION` | Circle test USDC / `USDC` / `2`    | Token and its EIP-712 domain.                                                                                                             |
+| `METRIK_GATEWAY_X402V2_MAX_TIMEOUT_SECONDS`                      | `300`                              | Authorization validity the client signs for.                                                                                              |
+| `METRIK_GATEWAY_X402V2_FACILITATOR_TIMEOUT_SECONDS`              | `120`                              | Per-request facilitator timeout; must exceed its receipt wait by 30 s.                                                                    |
+| `METRIK_GATEWAY_X402V2_RESOURCE_BASE_URL`                        | derived from `Host`                | Public origin used in the 402 `resource.url`.                                                                                             |
+| `METRIK_GATEWAY_X402V2_REGISTRY_URL`                             | the public registry                | Where the listing is proven at startup.                                                                                                   |
+| `METRIK_GATEWAY_X402V2_REFUND_BASE_URL`                          | the facilitator URL                | Public base of the refund relay advertised in the 402. If different, its `/supported` must show the same marker with `refundRelay: true`. |
+| `METRIK_GATEWAY_X402V2_DOCS_URL`                                 | this document on GitHub            | Docs link in the 402.                                                                                                                     |
+| `METRIK_GATEWAY_X402V2_ASSET_DECIMALS`                           | `6`                                | Decimals for the amounts in the 402 description.                                                                                          |
+| `METRIK_GATEWAY_X402V2_DESCRIPTION`                              | unset                              | One sentence on what the service does, prefixed to the fixed disclosure.                                                                  |
+| `METRIK_GATEWAY_X402V2_SCHEMA`                                   | unset                              | JSON `{info: {input, output}, schema}`, declared as `extensions.bazaar` (declared only, never registered).                                |
+
+These names deliberately differ from the removed v1 mode's variables, so a
+leftover v1 environment can never switch a payment mode on.
+
+At startup the gateway validates the terms and price, proves the listing is
+operator-signed, checks `factory.escrow()` and `factory.usdc()`, computes
+`payTo = factory.predict(terms)`, and checks the facilitator's marker —
+including `refundRelay: true`, because the 402 promises a refund path without
+ETH — plus the marker at a separate refund base URL; any failure stops it from
+starting. The advertised window is `METRIK_GATEWAY_X402V2_MAX_DURATION_SECONDS`
+(for example `60`, with `RATE_PER_SECOND=1000` and `PRICE=60000`).
+
+### What the 402 says
+
+The resource `description` states plainly what one payment buys; an operator
+`DESCRIPTION` can only be prefixed to it. With a 60 s window at 1000 base
+units/s and a price of 60000:
+
+> Pays for one call. Your payment of 0.06 USDC funds a Metrik escrow stream of
+> 60 seconds at 0.001 USDC/s; the seller earns only for seconds Metrik's
+> verifier confirms the service is delivering, and anything unearned is
+> refundable to you (no ETH needed) via
+> https://&lt;facilitator&gt;/streams/{streamId}. Refunds are not automatic: close
+> the stream and reclaim there, using the streamId from the PAYMENT-RESPONSE.
+> Docs: &lt;docs URL&gt;
+
+When the price is below `rate × window`, it adds "(the seller can earn at most
+&lt;price&gt;)". `extra.metrikStreamOpener` also carries `refundUrl` (the
+template) and `docsUrl`; the facilitator accepts exactly these two
+informational http(s) links on top of the terms, never uses them for
+settlement, and still refuses any other key. "Verified" here means verified
+delivery, not verified output.
+
+| Request carries                                            | Result                                                                                |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| nothing                                                    | `402`, `PAYMENT-REQUIRED` quoting the opener `payTo` and the price                    |
+| `PAYMENT-SIGNATURE`                                        | verified → upstream → settled if upstream `< 400` → `200` + body + `PAYMENT-RESPONSE` |
+| `PAYMENT-SIGNATURE`, upstream `>= 400`                     | upstream response, nothing settled                                                    |
+| `PAYMENT-SIGNATURE`, settle fails                          | `402` + `PAYMENT-RESPONSE`, no upstream body                                          |
+| `x-metrik-capability`                                      | the capability path, unchanged                                                        |
+| capability **and** `PAYMENT-SIGNATURE`                     | `400 ambiguous-capability-and-payment`                                                |
+| probe capability **and** `PAYMENT-SIGNATURE`               | `400 ambiguous-probe-mode`                                                            |
+| any request while the facilitator marker cannot be proven  | `503 x402-facilitator-unavailable`                                                    |
+| a `PAYMENT-SIGNATURE` already in flight or already settled | `409 x402-payment-already-used`, no upstream call                                     |
+
+With `METRIK_GATEWAY_X402V2_OPENER` unset the gateway is byte for byte the
+capability-only gateway (`test/gateway-http-baseline.test.ts`), and the
+`@x402/*` packages are never loaded.
+
+## Paying as a buyer: `metrik pay`, MCP `x402_pay`, `@absol-labs/agent/x402-buyer`
+
+The buyer side is the SDK's `payWithX402` (`@absol-labs/sdk/x402`) with every SDK
+protection intact, wrapped by `payX402WithMandate` (`@absol-labs/agent/x402-buyer`)
+so the package's golden rule holds: **no spend without a mandate**. A Metrik x402
+payment opens a stream, so it is checked as the stream open it is:
+
+| Mandate cap            | x402 quote field                              |
+| ---------------------- | --------------------------------------------- |
+| `maxPerStreamUsdc`     | `amount` (the deposit, the price of the call) |
+| `maxTotalUsdc`         | spent so far + `amount`                       |
+| `maxRatePerSecondUsdc` | `ratePerSecond`                               |
+| `maxDurationSeconds`   | `maxDuration`                                 |
+| `allowedOperators`     | `operator`                                    |
+
+The mandate's signature, expiry, revocation, owner (= the payer) and chain are
+verified before the seller is contacted. The per-quote check runs in the SDK's
+`onQuote` hook — after the SDK has proven `payTo == factory.predict(terms)` on
+chain and before anything is signed — and the caps are also passed to the SDK as
+`maxAmount` / `maxRatePerSecond`. A quote without opener terms is refused
+(`X402MandateDeniedError` reason `not-an-opener-quote`).
+
+```bash
+metrik pay https://x402.137.23.50.249.sslip.io/transform --json '{"text":"# hi"}' --max-amount 0.1
+metrik refund <streamId> --refund-url <url printed above> --close --reclaim
+```
+
+The MCP server offers the same as `x402_pay`, `refund_status` and `refund`
+(see [mcp-reference.md](./mcp-reference.md)); `x402_pay` shares the server
+mandate and cumulative spend with `hire_verified_service`. Refunds are still
+**requested, never pushed**: `metrik refund` / `refund` call the relay; nothing
+calls it for you.
+
+The facilitator's `PAYMENT-RESPONSE` `extra.metrikStreamOpener.expiresAt` is a
+JSON **number** (it was a decimal string before metrik-agent#121, which the SDK's
+strict parser rejects after settlement — a facilitator deployed before that fix
+must be redeployed).
+
+## Network configuration
+
+Network, USDC (and its EIP-712 domain), escrow, opener factory and oracle all
+default from the `@absol-labs/sdk` network registry entry for the configured
+CAIP-2 network (`METRIK_OPENER_FACILITATOR_NETWORK`, `METRIK_GATEWAY_CHAIN_ID` /
+`METRIK_GATEWAY_X402V2_NETWORK`); every one has an env override, and on a network
+the registry does not know (or one with no opener factory) each must be given
+explicitly. The refund relay computes the no-proof escape hatch per escrow
+generation (`escrow.generation`): V2 `expiresAt + escapeGraceSeconds`, V3
+`min(expiresAt, closedAt) + escapeGraceSeconds` read from the escrow's
+`escapeHatchReadyAt` view.
+
+## Programmatic use
+
+Everything lives under the `@absol-labs/agent/x402-opener` subpath (the root
+barrel does not load `@x402/*`): `MetrikOpenerExactScheme`,
+`buildOpenerFacilitator`, `createOpenerFacilitatorServer`, `OpenerRefundRelay`,
+`openerActionTypedData`, `checkpointLeaf`, `RelayerQueue`,
+`RegistryListingResolver`, `readOpenerFacilitatorMarker`, the vendored
+`x402StreamOpenerFactoryAbi` / `x402StreamOpenerAbi`, and the terms helpers.
+The gateway mode is `buildGatewayX402OpenerMode` in
+`@absol-labs/agent/gateway/x402-opener-mode`, passed to
+`createCallerAuthGatewayServer({ x402Opener })`.
+
+## Honest limits
+
+- **Refunds are requested, never pushed.** There is no automatic refund: the
+  relay acts only when an endpoint is called, and a payer who never calls it
+  (or never has anyone call `reclaim` for them) gets nothing back. `metrik
+refund` and the MCP `refund` tool call it on request; `metrik close` /
+  `metrik reclaim` also route an opener stream through the opener directly.
+- **The relay depends on the oracle for proofs.** If the oracle's latest
+  checkpoint never includes the stream, the proof-based reclaim cannot run and
+  the payer-signed escape hatch (after `expiresAt + escapeGraceSeconds`) is the
+  way out. The relay ledgers are in-memory and per instance, like the
+  settlement ledger; the on-chain contracts still allow only one close and one
+  reclaim per stream regardless.
+- **Stray funds are unrecoverable**: USDC that reaches an opener any way other
+  than `deployAndSettle` / `settleAndOpen` stays there (see the hard rule).
+- **Blacklist blast radius**: one opener is the escrow buyer for every payer of
+  a listing's terms; if the token issuer blacklists it, refunds through it
+  freeze until it is un-blacklisted.
+- **ERC-6492 counterfactual wallets are refused**; deploy the wallet first. A
+  deployed ERC-1271 wallet works (USDC verifies it).
+- **Single instance**: one relayer, and the at-most-one-success ledgers are
+  in-memory per instance (see above). Do not run replicas.
+- **Listing freshness**: a successful registry read is reused for 60 s by
+  default, so a withdrawn listing can keep verifying for up to that long.
+  Discovery prefers a gated listing over a public one for the same operator and
+  origin; a listing hidden that way does not resolve (fail closed).
+
+---
+
+## History: the removed x402 v1 integration
+
+Until metrik-agent#115 this package shipped an x402 **v1** integration: a
+standard `exact` facilitator (`metrik-x402-facilitator`, exported as
+`@absol-labs/agent/x402-facilitator`) that consulted Metrik's oracle before
+settling, and an opt-in mode on the seller gateway that answered an
+uncapabilitied request with an x402 `402`. It was removed, before it ever ran in
+production, for four reasons:
+
+1. **It targeted a superseded protocol version.** It was built on `x402@1.2.0`
+   (`x402Version: 1`, `X-PAYMENT` / `X-PAYMENT-RESPONSE`, bare network names
+   such as `base-sepolia`). The protocol is at v2 (`PAYMENT-REQUIRED` /
+   `PAYMENT-SIGNATURE` / `PAYMENT-RESPONSE`, CAIP-2 network identifiers such as
+   `eip155:84532`).
+2. **It paid the seller directly.** `payTo` was the operator, so the money never
+   touched `StreamEscrowV2`: no escrow, no protocol fee, and nothing a buyer
+   could get back.
+3. **Its delivery gate gated nothing in practice.** On absent evidence it
+   defaulted to _allow_, and the live oracle's `GET /services` is built from
+   active streams, which was empty — so every payment would have passed.
+4. **Leaving it in place invited someone to enable it.** It was default-off
+   behind environment switches and had never broadcast a settlement.
+
+What changed for integrators:
+
+- The `metrik-x402-facilitator` bin, the `./x402-facilitator` subpath export,
+  the `x402:facilitator` script and every module behind them are gone.
+- The seller gateway no longer reads any `METRIK_GATEWAY_X402_*` variable, and
+  the facilitator's `METRIK_X402_*` variables have no reader. A gateway that
+  never set them behaves exactly as before: a request with no capability gets
+  `403 {"authorized":false,"reason":"missing-capability-header"}`, and a request
+  with a valid capability is proxied unchanged
+  (`test/gateway-http-baseline.test.ts` pins this over a real socket).
+- A request carrying an oracle probe capability **and** an `X-PAYMENT` header is
+  still refused with `400 ambiguous-probe-mode` (and, in the v2 mode, so is a
+  probe carrying `PAYMENT-SIGNATURE`). A probe is free verification
+  traffic and is never mixed with anything that looks like a payment.
+- The deprecated `X402*` / `x402*` aliases of the native flow's exports were
+  removed at the same time. Use the canonical names listed below.
+
+`test/x402-v1-removed.test.ts` fails if any source, test, script or example
+imports the v1 `x402` / `x402-fetch` packages again (the v2 `@x402/*` packages
+are what the opener path uses), or if `package.json` re-declares them or the
+removed bin, script or export. `scripts/check-packed-package.mjs` refuses to
+publish a tarball that still contains any removed artifact.
+
+---
+
+## The Metrik-native verified-stream `402` flow — NOT x402
+
+In [`src/x402/facilitator.ts`](../src/x402/facilitator.ts) (the directory name is
+historical):
+
+- scheme string **`streamproof-verified-stream`** — deliberately _not_ an x402
+  scheme name, and not registered with x402;
+- a challenge body of `{scheme, requirements}` where `requirements` is
+  Metrik-specific (`operator`, `serviceRef`, `ratePerSecondUsdc`,
+  `maxDurationSeconds`, `maxBudgetUsdc`, `escrow`, `chainId`) — **not** x402
+  `PaymentRequirements`;
+- a payload header of `` `${scheme} ${base64url(JSON)}` `` carrying the challenge
+  plus an owner-signed `SpendMandate` — **not** an x402 `PaymentPayload`;
+- no `/verify`, no `/settle`, no `/supported` endpoint.
+
+This flow is real, it is tested, and it opens real escrowed streams on Base
+Sepolia. It does not interoperate with `x402-fetch`, `x402-axios`,
+`x402-express` or any other x402 client or facilitator.
+
+Exports: `VerifiedStreamFacilitator`, `METRIK_STREAM_SCHEME`,
+`METRIK_PAYMENT_HEADER`, `encodeStreamPayloadHeader`,
+`parseStreamPayloadHeader`, `parseStreamChallengeJson`, `streamChallengeSchema`,
+`streamOpenPayloadSchema`, `verifiedStreamRequirementsSchema`,
+`StreamPayloadError`, `SpendControlUnavailableError`,
+`SettlementTargetMismatchError`, `DeliveryProofUnavailableError`, and the types
+`StreamFacilitator`, `StreamChallenge`, `StreamOpenPayload`,
+`ConsumedHttpsResponseProofInput`, `VerifiedStreamFacilitatorOptions`,
+`VerifiedStreamRequirements`.
+
+Two runtime error names still carry the old prefix: a `StreamPayloadError` has
+`.name === "X402PayloadError"` and a `SpendControlUnavailableError` has
+`.name === "X402SpendControlUnavailableError"`. They were left unchanged so code
+that matches on `error.name` keeps working; prefer `instanceof`.
+
+### The header name
+
+Metrik's payload travels as **`X-METRIK-PAYMENT`**. Metrik puts nothing on the
+x402 v1 `X-PAYMENT` header, and `X-METRIK-PAYMENT` also stays clear of the v2
+header names (`PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, `PAYMENT-RESPONSE`).
+
+---
+
+## Why the metered stream does not fit a shipped x402 scheme
+
+This analysis is why "support x402" was never a wire-format exercise for the
+stream itself. Package facts were gathered on **2026-09-18** from
+`x402-foundation/x402@main` and from `x402@1.2.0` as published on npm; the test
+that re-checked them against the real package was removed with the dependency
+in #115, so re-verify before relying on them.
+
+| Thing                               | Reality at the date above                                         |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| Spec repository                     | [`x402-foundation/x402`](https://github.com/x402-foundation/x402) |
+| Schemes implemented by `x402@1.2.0` | **`exact` only**                                                  |
+| Schemes that exist _in the spec_    | `exact`, `upto`, `batch-settlement`, `auth-capture`               |
+| Protocol versions in `x402@1.2.0`   | `x402Version: 1` only; v2 was specified, not yet in that package  |
+
+### `exact`
+
+`exact` on EVM is an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009)
+`transferWithAuthorization`: one fixed amount, one transfer, straight to
+`payTo`. No hold, no conditional release, no partial capture, no reclaim.
+
+Metrik's unit of payment is a **metered stream**: the buyer escrows a budget
+into `StreamEscrowV2` at a per-second rate with an expiry, a verifier probes the
+seller each interval, the seller earns only for intervals that verified
+(claimed against Merkle checkpoints), and whatever was never earned is
+recoverable by the buyer via a withdrawal transaction. Collapsing that into one
+up-front transfer to the seller deletes the product — which is exactly what the
+removed v1 integration did, and why it went. The opener path at the top of this
+document keeps the `exact` payment but points its `payTo` at an opener that
+opens the stream, instead of at the seller.
+
+### `upto`
+
+`upto` (authorize a maximum, settle actual usage) fits a single metered
+_request_, but its spec explicitly puts "multi-settlement / streaming" out of
+scope and requires each authorization to be settled at most once. A Metrik
+stream settles the same authorization repeatedly, once per verified checkpoint.
+
+### `auth-capture`
+
+`auth-capture` in its `escrow` flow is the closest conceptual match —
+`authorize`/`capture`/`void`/`reclaim` map onto `openStream`/`claim`/`close`/
+`reclaim` — but its EVM binding is pinned to the canonical `AuthCaptureEscrow`
+contract (Base's Commerce Payments Protocol), which a conformant facilitator
+must read and whose events it must observe. Metrik settles in `StreamEscrowV2`
+(`0x0f09f36Ccc05A7c9882F438721C08De314dFd46C`), a different contract with a
+different state model, so conformance there would be a contract deployment, not
+a code change in this package.