@absol-labs/agent 0.11.0 → 0.12.0-rc.2

package/docs/agent-layer.md

@@ -25,8 +25,9 @@ challenge/response and reuses the protocol's existing settlement path. (`src/x40
 
 It is **not the x402 protocol**: its scheme string, challenge body, payload and
 `X-METRIK-PAYMENT` header are all Metrik's own, and it does not interoperate with
-`x402-fetch`, `x402-axios`, or `x402-express`. See [docs/x402.md](./x402.md) for the
-evidence and for what real x402 support would require.
+`x402-fetch`, `x402-axios`, or `x402-express`. Standard x402 v2 `exact` payments are
+handled by a separate, opt-in path — the opener facilitator and the gateway's x402 v2
+mode — described in [docs/x402.md](./x402.md).
 
 ### 2. MCP server
 

package/docs/autonomous-privy-wallet.md

@@ -131,3 +131,191 @@ capability typed-data requests only. It does not claim ERC-4337, EIP-1271,
 smart-account, or gas-sponsorship support. The broker deployment and its real
 Privy policy remain integration dependencies and must be health-checked before
 use.
+
+## Escrow cutover (V2 → V3): what the broker allows, and the Privy policy change it needs
+
+The broker (both the agent-owned and the session paths) sends transactions to
+exactly two kinds of escrow, read from the registries rather than hardcoded
+(`src/wallet/broker-escrows.ts`):
+
+| Target                                                                                                      | Allowed calls                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Current escrow** (the SDK network registry's escrow for the broker's network)                             | `openStream`, `close`, `reclaim`, `reclaimUnverified`                                                                             |
+| **Legacy escrow(s)** (`@absol-labs/shared` deployments with `status: "legacy"`, other than the current one) | `close`, `reclaim`, `reclaimUnverified` **only** — no `openStream`                                                                |
+| **USDC**                                                                                                    | `approve(spender, amount)` with `spender` = the **current** escrow only (never a legacy escrow), `amount` within the existing cap |
+
+Everything else is unchanged: chain id, zero `value`, `from` = the wallet, the
+mandate/spend-cap checks on `openStream`, `stream.buyer == wallet` on every exit
+(read from the escrow the exit targets), and invocation-capability typed data
+bound to the current escrow. V2 and V3 share the selectors of every allowed
+method, so one decoder (the union of the V2/V3 ABIs) serves both.
+
+While the SDK default is still `StreamEscrowV2` (`@absol-labs/sdk@0.10.0-rc.1`),
+V2 is current and nothing is legacy: behaviour is identical to before. With
+`0.10.0-rc.2` the default becomes `StreamEscrowV3` and V2 becomes exit-only, so
+agents holding open V2 streams can still close and reclaim them.
+
+### Privy policy rules to apply at cutover
+
+The broker's checks are a second line; the Privy policy is what Privy itself
+enforces. At the V3 cutover, the policy (`PRIVY_POLICY_ID`) must change as
+follows. Base Sepolia addresses (from `@absol-labs/shared` `escrowDeployments`
+and the SDK registry):
+
+- current escrow (V3): `0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13`
+- legacy escrow (V2): `0x0f09f36Ccc05A7c9882F438721C08De314dFd46C`
+- USDC: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
+
+Keep every existing numeric bound exactly as it is (`openStream`
+`deposit <= 1000000`, `ratePerSecond <= 1000`, `maxDuration <= 3600`; USDC
+`approve` `amount <= 1000000`; chain `eip155:84532`; `value == 0`).
+
+1. **Contract allowlist, escrow — `openStream`**: change the target from the V2
+   escrow to the **V3** escrow only. The legacy V2 escrow must NOT be allowed
+   `openStream`.
+2. **Contract allowlist, escrow — exits** (`close(bytes32)` `0x39c79e0c`,
+   `reclaim(bytes32,uint256,bytes32[])` `0x2c307c9c`,
+   `reclaimUnverified(bytes32)` `0x5fcdce22`): allow them on **both** the V3
+   escrow and the V2 escrow (`to` IN [V3, V2]).
+3. **USDC `approve`** (`0x095ea7b3`): change the allowed `spender` from the V2
+   escrow to the **V3** escrow only. No approval to V2.
+4. Remove any rule that allows the V2 escrow for a method other than the three
+   exits above.
+
+The same, as Privy policy rules (ALLOW rules, `eth_sendTransaction`,
+`chain_type: "ethereum"`; DENY is the default):
+
+```json
+[
+  {
+    "name": "metrik-open-stream-current-escrow",
+    "method": "eth_sendTransaction",
+    "action": "ALLOW",
+    "conditions": [
+      {
+        "field_source": "ethereum_transaction",
+        "field": "chain_id",
+        "operator": "eq",
+        "value": "84532"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "to",
+        "operator": "eq",
+        "value": "0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "value",
+        "operator": "eq",
+        "value": "0"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "openStream.deposit",
+        "operator": "lte",
+        "value": "1000000",
+        "abi": "<StreamEscrowV3 openStream ABI>"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "openStream.ratePerSecond",
+        "operator": "lte",
+        "value": "1000",
+        "abi": "<StreamEscrowV3 openStream ABI>"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "openStream.maxDuration",
+        "operator": "lte",
+        "value": "3600",
+        "abi": "<StreamEscrowV3 openStream ABI>"
+      }
+    ]
+  },
+  {
+    "name": "metrik-exits-current-and-legacy-escrow",
+    "method": "eth_sendTransaction",
+    "action": "ALLOW",
+    "conditions": [
+      {
+        "field_source": "ethereum_transaction",
+        "field": "chain_id",
+        "operator": "eq",
+        "value": "84532"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "to",
+        "operator": "in",
+        "value": [
+          "0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13",
+          "0x0f09f36Ccc05A7c9882F438721C08De314dFd46C"
+        ]
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "value",
+        "operator": "eq",
+        "value": "0"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "function_selector",
+        "operator": "in",
+        "value": ["0x39c79e0c", "0x2c307c9c", "0x5fcdce22"]
+      }
+    ]
+  },
+  {
+    "name": "metrik-usdc-approve-current-escrow",
+    "method": "eth_sendTransaction",
+    "action": "ALLOW",
+    "conditions": [
+      {
+        "field_source": "ethereum_transaction",
+        "field": "chain_id",
+        "operator": "eq",
+        "value": "84532"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "to",
+        "operator": "eq",
+        "value": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+      },
+      {
+        "field_source": "ethereum_transaction",
+        "field": "value",
+        "operator": "eq",
+        "value": "0"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "approve.spender",
+        "operator": "eq",
+        "value": "0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13",
+        "abi": "<ERC-20 approve ABI>"
+      },
+      {
+        "field_source": "ethereum_calldata",
+        "field": "approve.amount",
+        "operator": "lte",
+        "value": "1000000",
+        "abi": "<ERC-20 approve ABI>"
+      }
+    ]
+  }
+]
+```
+
+Express the selector restriction in whatever form the live policy already uses
+(a `function_selector` condition, or one calldata-field rule per exit method
+with its ABI). What matters is the set: `openStream` → V3 only; the three exits
+→ V3 and V2; `approve.spender` → V3 only. The existing invocation-capability
+typed-data rule must change its `verifyingContract` to the V3 escrow at the
+same time (the broker already binds it to the current escrow).
+
+Apply the policy change and the `@absol-labs/sdk@0.10.0-rc.2` bump together: the
+broker refuses a V2 `openStream` as soon as the registry default is V3, and the
+policy should too.

package/docs/cli.md

@@ -46,7 +46,8 @@ consumer who installed the package could not run at all. `metrik mcp
 ## Testnet only
 
 The CLI signs with a raw private key and moves USDC, so the chain is an **allowlist**,
-not a default: only Base Sepolia (`84532`) is accepted. There is deliberately **no
+not a default: only networks the `@absol-labs/sdk` network registry knows **and marks as
+a testnet** are accepted (today: Base Sepolia, `84532`). There is deliberately **no
 override flag** — an escape hatch that re-enabled real funds would defeat the guarantee,
 and there is no mainnet deployment for it to reach anyway.
 
@@ -104,6 +105,17 @@ A Privy wallet differs from the other two in one structural way: its account has
 client's transport** instead of the plain `http(--rpc-url)` a local signer uses. That is
 the whole of the wiring. Private-key and CDP runs are unchanged, byte for byte.
 
+**`metrik claim` does not work on a Privy wallet.** The broker's transaction allowlist
+carries the BUYER actions only (`openStream`, `close`, `reclaim`, `reclaimUnverified`), so
+an operator claim is refused server-side and the client cannot raise that ceiling. Claim
+with the operator's own `METRIK_AGENT_PRIVATE_KEY`. Every other command works. The CLI
+warns when you try it, and `metrik --help` / `metrik claim --help` say so up front.
+
+**`metrik mcp` does not carry a Privy wallet either.** The MCP server resolves its wallet
+with `parseAgentWalletEnv()`, which reads `METRIK_AGENT_PRIVATE_KEY` or the CDP variables
+and has no Privy branch — so `metrik mcp --print-config` prints a key placeholder and says
+why on stderr rather than emitting Privy variables the server would ignore.
+
 There are two shapes. Set one; setting both uses the agent-owned wallet and says so.
 
 **Agent-owned (`privy-autonomous`)** — headless, no browser, no user login:
@@ -245,19 +257,21 @@ that needs no key at all — it builds and prints the intended call and says whi
 
 ## Commands
 
-| Command              | Needs a wallet?                | Broadcasts a tx? | What it does                                     |
-| -------------------- | ------------------------------ | ---------------- | ------------------------------------------------ |
-| `discover`           | no                             | no               | Lists verified registry listings                 |
-| `open`               | **yes** (not with `--dry-run`) | **yes**          | Escrows USDC into a metered stream               |
-| `status`             | no                             | no               | One stream's on-chain state + verified accrual   |
-| `streams`            | no (with `--address`)          | no               | Lists a wallet's streams from the escrow's logs  |
-| `watch`              | no                             | no               | Polls that until the stream closes               |
-| `invoke`             | **yes** (off-chain capability) | no               | Calls the paid service, authorized by the stream |
-| `close`              | **yes**                        | **yes**          | Stops the clock                                  |
-| `reclaim`            | **yes**                        | **yes**          | Takes back what was never earned                 |
-| `reclaim-unverified` | **yes**                        | **yes**          | Buyer escape hatch: reclaim with no proof        |
-| `claim`              | **yes** (the operator's)       | **yes**          | Operator: redeem what verified                   |
-| `mcp`                | no                             | no               | Prints the MCP client config for `metrik-mcp`    |
+| Command              | Needs a wallet?                | Broadcasts a tx?  | What it does                                     |
+| -------------------- | ------------------------------ | ----------------- | ------------------------------------------------ |
+| `discover`           | no                             | no                | Lists verified registry listings                 |
+| `open`               | **yes** (not with `--dry-run`) | **yes**           | Escrows USDC into a metered stream               |
+| `status`             | no                             | no                | One stream's on-chain state + verified accrual   |
+| `streams`            | no (with `--address`)          | no                | Lists a wallet's streams from the escrow's logs  |
+| `watch`              | no                             | no                | Polls that until the stream closes               |
+| `invoke`             | **yes** (off-chain capability) | no                | Calls the paid service, authorized by the stream |
+| `pay`                | **yes** (EIP-3009 signature)   | no (relayer does) | Pays an x402 endpoint into an escrow stream      |
+| `refund`             | only for `--close`             | no (relay does)   | Gasless close/reclaim of an x402 stream          |
+| `close`              | **yes**                        | **yes**           | Stops the clock                                  |
+| `reclaim`            | **yes**                        | **yes**           | Takes back what was never earned                 |
+| `reclaim-unverified` | **yes**                        | **yes**           | Buyer escape hatch: reclaim with no proof        |
+| `claim`              | **yes** (the operator's)       | **yes**           | Operator: redeem what verified                   |
+| `mcp`                | no                             | no                | Prints the MCP client config for `metrik-mcp`    |
 
 ### `metrik discover`
 
@@ -311,8 +325,8 @@ claim cannot be true. Every rendering of it is labelled unverified, in human out
 ### `metrik open`
 
 ```bash
-metrik open --service <serviceRef> --rate 0.000001 --budget 0.27 --duration 1h
-metrik open --service <serviceRef> --rate 1 --budget 270000 --duration 3600 --units atomic
+metrik open --service <serviceRef> --rate 0.0001 --budget 0.36 --duration 1h
+metrik open --service <serviceRef> --rate 100 --budget 360000 --duration 3600 --units atomic
 metrik open ... --dry-run
 ```
 
@@ -358,6 +372,21 @@ as `simulationPendingApproval: true`, with no `simulationError` — a script bra
 that field no longer sees the expected path as a failure. An allowance-shaped revert when
 the allowance IS already sufficient, and every other revert, are still surfaced as errors.
 
+**The operator-signed rate band.** Before anything is signed or broadcast — `--dry-run`
+included — `open` re-verifies the listing's operator-signed descriptor (the same check the
+seller's gateway runs) and refuses at exit `2` when `--rate` is outside its
+`minRatePerSecond`..`maxRatePerSecond` band, e.g. `the operator signed rates 100..10000
+atomic/s (0.0001..0.01 USDC/s); --rate 20000 (0.02 USDC/s) would be refused by the
+service's gateway`. The escrow accepts any non-zero rate, but the gateway answers every
+request on an out-of-band stream with `403 stream-rate-out-of-bounds`, so the deposit
+would sit in a stream that can never be served. Bounds are inclusive; a bound the operator
+did not sign is not enforced, and a legacy binding signs none. A descriptor that does not
+verify is a refusal (exit `4`), never "no band". Without `--operator`, an unreachable
+registry already fails `open` (exit `4`). With `--operator` — the existing escape hatch for
+a service the registry cannot vouch for — the band cannot be read, so the open proceeds
+with a warning saying the rate was **not** checked. There is no flag to override a band
+the CLI can read.
+
 **Amounts.** `--budget` and `--rate` are decimal USDC by default; `--units atomic`
 switches both to raw 6-decimal base units (what the escrow, the oracle and every
 `METRIK_E2E_*` fixture use). The unit is explicit rather than inferred from magnitude,
@@ -430,6 +459,21 @@ escrow that grace is 900 seconds and immutable. An operator who has earned but n
 loses it at that moment, and the only defence is to `metrik claim` before it — which
 requires knowing the deadline exists.
 
+**A stream with nothing left for anyone reads as finished.** Once a stream has stopped
+(closed, or past expiry) and the operator's claimed amount — or on V3 the proven
+high-water — already covers the whole deposit, both buyer exits would revert
+`NothingToReclaim`, so `reclaimed` stays `false` forever. `status` renders it the way it
+renders a reclaimed stream: `buyer side finished`, the operator's settled / claimed /
+unclaimed amounts, and none of the buyer-reclaimable, escape-hatch or deadline rows. The
+JSON sets `buyerSideFinished: true` and `finalSettlement.finishedBy: "deposit-exhausted"`
+(`"reclaimed"` for a reclaimed stream). An unreadable proven high-water never makes a
+stream look finished.
+
+**Proven value is stated from chain.** On V3, when the latest checkpoint no longer contains
+the stream but `provenCumulativeOf` is non-zero, `verified accrual` states that proven
+amount (read from the escrow) instead of "not checkpointed yet", and `operator claimable`
+is what `claimProven` would pay (`claimableSource: "proven-on-chain"` in the JSON).
+
 StreamEscrowV2 has exactly two states, `active` and `closed`. There is no paused state
 and the CLI never renders one.
 
@@ -520,7 +564,10 @@ Configured mandate ceilings are carried through verbatim — they are policy, no
 and re-typing four caps from memory is where a wrong ceiling comes from. **Credentials are
 always placeholders.** This command never reads a key out of your environment and prints
 it back; the wallet block is simply shaped like the environment it ran in (the CDP
-variables if those are what you have set, `METRIK_AGENT_PRIVATE_KEY` otherwise).
+variables if those are what you have set, `METRIK_AGENT_PRIVATE_KEY` otherwise). A Privy
+wallet is **not** an option here — `parseAgentWalletEnv()` has no Privy branch — so when
+the environment carries one the command says so on stderr and prints a key placeholder
+instead of a config the server could not start from.
 
 ### `metrik invoke`
 
@@ -550,6 +597,136 @@ listings ("consumer-attested T2 invocation is not supported for gated listings")
 live listings are gated — so a `metrik prove` would be a command that fails for almost
 everyone who ran it. It is left out until that constraint lifts.
 
+### `metrik pay` (x402)
+
+```bash
+metrik pay https://x402.example/transform --json '{"text":"# hi"}' --max-amount 0.1
+metrik pay <url> [--json <body> | --data <body>] [--method POST] [--header "K: V"] \
+  --max-amount <usdc> [--max-rate <usdc/s>] [--max-upfront <usdc>] [--max-duration <s>] \
+  [--min-duration <s>] [--operator <address>] [--units atomic]
+```
+
+Pays any **x402 v2 `exact`** endpoint through `@absol-labs/sdk/x402`'s `payWithX402`,
+with every SDK protection intact (network and USDC from the registry, EIP-3009 only,
+registered opener factory, `payTo == factory.predict(terms)` read on-chain, bounded
+authorization lifetime, a plain transfer to the seller refused). A Metrik seller's
+payment opens an escrow stream with `deposit = price`; the seller earns
+`ratePerSecond x verified seconds`, capped at the deposit.
+
+**Upfront ("minimum charge") quotes.** A seller may instead quote the upfront opener:
+the price splits into a **non-refundable** per-call charge (`upfrontAmount`, paid to the
+seller at settlement whatever is delivered) and a **refundable**, metered part (`price -
+upfrontAmount`, escrowed as above — the most any refund can return). `metrik pay` prints
+the split before it signs (`quote: … = … NON-REFUNDABLE per-call charge + … metered and
+refundable`) and again in the result (`non-refundable` / `refundable` rows; JSON
+`openerKind`, `price`, `upfrontAmount`, `refundableAmount`, `upfrontFee`, `upfrontOnly`).
+`--max-upfront <usdc>` caps the non-refundable part (the SDK's `maxUpfrontAmount`;
+default 0.10 USDC, `0` refuses any upfront charge, never above the price ceiling). When
+`upfrontAmount == price` no stream opens: the payment is **final**, `streamId` is
+`null`, and no refund or reclaim command is printed, because there is nothing to
+refund.
+
+The payer needs **USDC only, no gas** (the facilitator's relayer submits the
+authorization). A Privy wallet cannot pay: its broker does not sign EIP-3009.
+
+**How the spend mandate bounds an x402 payment.** No spend without a mandate: a
+payment IS a stream open, so its opener terms are checked by `checkMandate()` exactly
+like `metrik open`, inside the SDK's `onQuote` hook, after the SDK's own checks and
+**before anything is signed**:
+
+| Mandate cap            | Checked against                                |
+| ---------------------- | ---------------------------------------------- |
+| `maxPerStreamUsdc`     | the quote's `amount` (the whole price)         |
+| `maxTotalUsdc`         | spent so far + `amount`                        |
+| `maxRatePerSecondUsdc` | `ratePerSecond` (how fast the seller can earn) |
+| `maxDurationSeconds`   | `maxDuration` (the stream window)              |
+| `allowedOperators`     | `operator` (who the stream pays)               |
+
+The caps are also handed to the SDK as `maxAmount` / `maxRatePerSecond`, so the price is
+enforced twice. A quote with no opener terms is refused. The mandate comes from
+`METRIK_AGENT_MANDATE_*` when set, otherwise it is sized to this command:
+`--max-amount` (required then) is the per-stream and total cap, `--max-rate` the rate cap
+(default: no tighter than the price), `--max-duration` the window cap (default 1 day),
+`--operator` the only allowed operator. With a standing mandate, every flag
+**intersects** it (the most restrictive value wins; an `--operator` outside
+`METRIK_AGENT_MANDATE_ALLOWED_OPERATORS` is refused): a flag can tighten the
+standing ceiling, never loosen or bypass it. Like every CLI mandate it covers one
+invocation.
+
+If anything fails after the authorization was handed to the seller, `metrik pay`
+establishes the outcome on-chain (USDC `authorizationState`, the opener's
+`StreamOpenedFor` log for that nonce), exits `4`, and says whether the money left
+the payer — with the `streamId` and the recovery command when the stream is found.
+It never reports "nothing moved" unless the authorization was unused and expired.
+For an upfront-only payment it says the money left the payer as a final, non-refundable
+charge with nothing to recover.
+
+A quote naming a **legacy** deployment's factory (for example a seller still on
+StreamEscrowV2 after the default moved to V3) is refused by the SDK unless you pass
+`--allow-legacy-factory`; that stream is then closed and reclaimed on the legacy
+escrow, and the printed recovery command carries `--escrow <legacy escrow>`.
+
+`--json <body>` is the request body (curl-style, sets `content-type: application/json`);
+`--json-body <body>` is accepted as an alias (give the body once, with either). A bare
+`--json` still selects JSON output, and both can be combined. The output is the
+response, the `streamId`, the opener, the deposit and rate, `minEarnSeconds` (after how
+many verified seconds nothing is left to reclaim) and the **refund URL**. When the
+facilitator's `PAYMENT-RESPONSE` header (relayed by the seller) carries the settlement
+transaction hash, it is printed as `settlement tx` and returned as
+`settlementTransaction` with `settlementTransactionSource: "PAYMENT-RESPONSE"`: the
+facilitator's relayer broadcast it, not the payer, and the CLI reports it as given.
+**Refunds are not automatic** — see `metrik refund`.
+
+Exit codes: `2` usage (including no ceiling), `3` refused by the mandate or the SDK
+(nothing signed, including an upfront part above `--max-upfront`), `4` the settlement failed after signing (the error says whether the
+authorization was used and how to cancel it; see [x402.md](./x402.md)).
+
+### `metrik refund`
+
+```bash
+metrik refund <streamId> --refund-url <url> [--close] [--reclaim] [--attempts 5] [--max-wait 60]
+```
+
+Drives the seller's **gasless refund relay** through the SDK's `refundClient`, bound to
+the stream and to the opener read **from chain** (`factory.isOpener`), never from the
+relay. With no action flag it prints the status and the next step. `--close` signs the
+opener's EIP-712 `Close` as the payer (the relay pays the gas; authorized on the mandate
+owner's signature only, like `metrik close`). `--reclaim` sends the permissionless
+`opener.reclaim` (no wallet needed; the refund always goes to `payerOf(streamId)`) and
+retries a bounded number of times while the settlement window is open, honouring
+`Retry-After`; a longer wait exits `3` with the time to retry. Every relay "success" is
+checked against the transaction receipt on the configured chain. `--refund-url` accepts
+the full URL `metrik pay` printed, a `{streamId}` template or the relay's origin; it can
+also come from `METRIK_AGENT_REFUND_URL`.
+
+`--close` needs the key that paid, and nothing else: it signs an off-chain EIP-712
+`Close` message, so the key needs no ETH or USDC. It is skipped (nothing signed, no
+wallet read) when the relay reports the stream already closed.
+
+**An upfront-only payment has nothing to refund.** `metrik refund 0x000…000` (stream id
+0, what an upfront-only payment amounts to) prints "Nothing to refund" and exits `0`
+without reading the chain, contacting a relay or signing anything; the JSON carries
+`finished: true`, `finishedReason: "upfront-only"`, `nothingToRefund: true`. For a
+partial-upfront payment the stream is refunded as usual, but only its deposit (`price -
+upfrontAmount`) can come back.
+
+**A finished recovery exits `0`.** When the stream is already closed and reclaimed, or
+the relay reports nothing to reclaim (`409 nothing-to-reclaim`: the verified delivery
+covers the whole deposit), `refund` says "Already finished … nothing to recover" and
+exits `0`; the JSON carries `finished: true`, `finishedReason` (`reclaimed` or
+`nothing-to-reclaim`), `nothingToRecover: true`, and `closeSkipped` / `reclaimSkipped`
+naming why a requested step sent nothing. It never suggests a gas-spending recovery when
+nothing is recoverable. Real failures (relay down, settlement window still open, wrong
+payer) still exit `3`.
+
+Nothing is refunded automatically, and the relay is a convenience: a payer can always
+recover on-chain without it (`metrik close` as the payer, with gas; `metrik reclaim` by
+anyone).
+
+`status`, `close` and `reclaim` understand opener-bought streams: they show the opener and the
+payer, `close` routes through the opener (payer only), and `reclaim` sends the
+permissionless opener reclaim and reports the refund to the payer.
+
 ### `metrik close` and `metrik reclaim`
 
 ```bash
@@ -563,12 +740,37 @@ returns the unspent budget, and the buyer sends it. `close` now points at
 `--close-first` for next time, rather than leaving the one-shot form visible only in
 `metrik reclaim --help`.
 
+**`reclaim` names the condition before it spends anything.** Three different on-chain
+states stop a reclaim, and they have three completely different answers: the stream was
+already reclaimed (you have the money), the stream is still running (close it first), or
+its stop time is not checkpointed yet (wait ~20 seconds). The CLI reads `getStream`,
+`latestCheckpointCheckedAt` and the chain clock up front and says which one it is, rather
+than sending a simulation and repeating whatever the endpoint's revert data decoded to —
+on the public Base Sepolia RPC all three came back as `Execution reverted for an unknown
+reason`. The pre-flight **fails open**: a read that does not answer never blocks the
+reclaim, because refusing to return a buyer's deposit over a dropped view call is worse
+than a wasted simulation.
+
+**What `reclaim` prints for the operator.** The `operator entitled` row is the amount
+the reclaim fixed as the operator's. No USDC moves to the operator at reclaim: the
+operator claims it separately with `metrik claim`, and the protocol fee is taken at that
+claim. `--json` keeps the field name `settledCumulative`.
+
 **`reclaim` waits, by design.** `reclaimWithProof` reverts with `SettlementWindowOpen`
 until a checkpoint whose `checkedAt` is at or after the stream's stop time has posted.
 That is the normal ordering of a checkpoint rail, not a fault — in practice the first
-attempt fails and one roughly 30 seconds later succeeds. The CLI retries **that one
-condition** on a bounded schedule and narrates the wait on stderr; every other failure is
-surfaced immediately and unretried.
+attempt fails and one roughly 30 seconds later succeeds. The CLI retries on a bounded
+schedule and narrates the wait on stderr; every other failure is surfaced immediately and
+unretried.
+
+The wait shows up in three shapes, and all three retry: the escrow's decoded
+`SettlementWindowOpen`; the **oracle** refusing a proof for a stream it has not
+checkpointed yet (the SDK fetches the proof before it simulates, so the escrow's revert
+never happens and the error is `StreamNotInCheckpointError` / `CheckpointNotReadyError`);
+and a reclaim revert the ABI could not decode, where the chain's state is read to decide.
+Only recognising the first of those is what made `--close-first` die on its first attempt
+against a stream closed before its first covering checkpoint — the ordinary result of a
+short trial run.
 
 If it is still blocked when the budget runs out, the message does **not** just say "retry
 later" — every attempt this command makes needs a proof from the oracle, so when the
@@ -584,8 +786,10 @@ lands on another that has not imported the block.) If the stream is **already**
 the close is skipped and the command goes straight to reclaim — so re-running it is always
 safe and never dead-ends on `StreamClosedAlready()`.
 
-`reclaim` on a stream that is still running reports that in words, with the command that
-fixes it, rather than surfacing the `StreamNotReclaimable()` selector.
+`--close-first` is also the one caller allowed past the still-running refusal, since
+clearing that state is the whole point of the flag. Once the close has landed it reports
+what the following retries are waiting for — the stop time, and how far the oracle has
+published — so the wait reads as the advertised wait rather than as a stalled command.
 
 Close and reclaim are buyer-recovery actions: `VerifiedStreamAgentClient` authorizes them
 on the mandate owner's signature alone, never on caps or expiry, so a lapsed mandate can
@@ -608,6 +812,21 @@ learn a fact that was already free. Same for a missing checkpoint: accrual lives
 oracle's proof, never in the stream tuple, so no proof means no claim is possible yet and
 the command says that instead of paying for `NothingToClaim()`.
 
+**On StreamEscrowV3 it falls back to `claimProven` automatically.** The escrow keeps a
+proven high-water (`provenCumulativeOf`) for every stream, and `claimProven` pays
+`provenCumulative − claimedCumulative` (net of the fee) with no proof. That is the only
+way to collect proven value whose checkpoint root has rotated out of the retained set (or
+that a later root regressed below). `claim` asks the escrow what each path would pay
+(`claimableFor` at the current proof's cumulative, and at the proven high-water), sends the
+larger, and prefers `claimWithProof` on a tie because it also raises the high-water. When
+both pay zero it exits `4` without broadcasting — "nothing to claim" when everything proven
+is already claimed. The JSON names the path in `method` (`claimWithProof` / `claimProven`)
+and adds `provenCumulative`; `verifiedCumulative` is `null` when there was no current proof.
+There is no flag: `claimProven` pays only an amount already proven against a signed root
+and recorded on-chain, to the same operator, under the same mandate check, so it can never
+pay more than a proof claim could have — and an opt-in would leave a seller reading "nothing
+provable" while their proven earnings sat stranded.
+
 ### `metrik reclaim-unverified`
 
 ```bash
@@ -672,7 +891,10 @@ wallet, mandate denied), `4` the operation failed.
 and the oracle fetch — an HTTP call the RPC transport does not cover — has its own 20s
 budget that names the endpoint when it expires. Any command still working after 8 seconds
 starts a heartbeat on stderr with the elapsed time, repeating every 10s, because with no
-output at all a slow endpoint and a wedged process are indistinguishable. The heartbeat is
+output at all a slow endpoint and a wedged process are indistinguishable. While a command
+is in a deliberate, announced wait — `reclaim` retrying until the oracle's next checkpoint
+(`attempt n/N`), `refund` letting the relay wait out the settlement window, `watch`
+polling — the heartbeat names that wait instead of blaming a slow RPC. The heartbeat is
 stderr in both modes, so `--json` stdout stays a single parseable document.
 
 Read paths time out; **broadcasts do not.** A transaction that has been sent may already be
@@ -682,17 +904,26 @@ that wait legible.
 
 ## Settlement configuration
 
-Everything defaults to Metrik's live Base Sepolia deployment, and every value is
-overridable per command or through the environment:
-
-| Flag             | Env                         | Default                               |
-| ---------------- | --------------------------- | ------------------------------------- |
-| `--chain-id`     | `METRIK_AGENT_CHAIN_ID`     | `84532`                               |
-| `--rpc-url`      | `METRIK_AGENT_RPC_URL`      | Base Sepolia public RPC               |
-| `--escrow`       | `METRIK_AGENT_ESCROW`       | `BASE_SEPOLIA_ESCROW_V2`              |
-| `--usdc`         | `METRIK_AGENT_USDC`         | `BASE_SEPOLIA_USDC`                   |
-| `--oracle-url`   | `METRIK_AGENT_ORACLE_URL`   | `https://oracle.metrik.live`          |
-| `--registry-url` | `METRIK_AGENT_REGISTRY_URL` | the oracle's public listings endpoint |
+Everything defaults to the selected network's entry in the `@absol-labs/sdk` network
+registry (the default network is Base Sepolia), and every value is overridable per
+command or through the environment. Nothing chain-specific is hardcoded in the CLI.
+
+| Flag                  | Env                              | Default                                                                |
+| --------------------- | -------------------------------- | ---------------------------------------------------------------------- |
+| `--network`           | `METRIK_NETWORK`                 | the registry default (id, chain id or CAIP-2)                          |
+| `--chain-id`          | `METRIK_AGENT_CHAIN_ID`          | the network's chain id (must agree if both set)                        |
+| `--rpc-url`           | `METRIK_AGENT_RPC_URL`           | the network's first registered RPC                                     |
+| `--escrow`            | `METRIK_AGENT_ESCROW`            | the network's current escrow (V3); a `legacy` one (V2) for its streams |
+| `--escrow-generation` | `METRIK_AGENT_ESCROW_GENERATION` | the registry's; REQUIRED only for an unregistered escrow               |
+| `--usdc`              | `METRIK_AGENT_USDC`              | the network's registered USDC                                          |
+| `--oracle-url`        | `METRIK_AGENT_ORACLE_URL`        | the network's oracle                                                   |
+| `--registry-url`      | `METRIK_AGENT_REGISTRY_URL`      | the network's public listings endpoint                                 |
+
+The gas preflight names the network's gas token and faucet (from its gas-token
+metadata) instead of assuming ETH; on a network whose gas IS the settlement USDC it
+checks the one USDC balance and requires the deposit to leave room for gas. An
+`--escrow` the registry does not record has no log-scan anchor, so `metrik streams`
+needs `--from-block` for it.
 
 ## Embedding it
 

package/docs/langchain.md

@@ -12,6 +12,11 @@ Create them with [`createLangChainVerifiedStreamTools()`](../src/frameworks/lang
 ## Safety model
 
 - `hire_verified_service` checks the signed mandate before any stream open.
+- It then refuses a `ratePerSecondUsdc` outside the listing's operator-signed rate
+  band (the seller's gateway would refuse every request on that stream), and fails
+  closed when the registry cannot be read. An unlisted `serviceRef` has no signed
+  band and is not constrained. The same check runs in the ElizaOS and AgentKit
+  adapters.
 - `reclaim_unspent` passes the same signed-mandate context into the agent client,
   which re-checks authorization before the SDK can write.
 - `check_stream_status` is read-only and also returns `shouldStop` for a closed