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

package/docs/quickstart.md

@@ -111,7 +111,7 @@ const account = wallet.account;
 const mandate = spendMandateSchema.parse({
   maxPerStreamUsdc: 100_000n, // 0.1 USDC (6 decimals) — max deposit per stream
   maxTotalUsdc: 100_000n, // cumulative cap across all streams
-  maxRatePerSecondUsdc: 1n, // max accrual rate the agent may agree to
+  maxRatePerSecondUsdc: 100n, // max accrual rate the agent may agree to (0.0001 USDC/s)
   maxDurationSeconds: 3600, // max stream lifetime
   allowedOperators: [account.address as `0x${string}`], // omit/empty ⇒ any operator
   expiresAt: nowSeconds + 365 * 24 * 60 * 60,
@@ -228,7 +228,7 @@ const hire = await agent.openVerifiedStream({
   operator: target.operator, // seller payout wallet from discovery
   serviceRef: target.serviceRef, // bytes32 the oracle verifies delivery against
   budgetUsdc: 100_000n,
-  ratePerSecondUsdc: 1n,
+  ratePerSecondUsdc: 100n, // must sit inside the listing's signed rate band
   maxDurationSeconds: 3600,
   signedMandate,
   spentSoFarUsdc: 0n,
@@ -340,7 +340,7 @@ loop (`discover -> open -> invoke -> watch -> close -> reclaim`):
 ```bash
 npx --package @absol-labs/agent metrik discover --min-tier 2
 npx --package @absol-labs/agent metrik open --service <serviceRef> \
-  --rate 0.000001 --budget 0.27 --duration 1h --dry-run
+  --rate 0.0001 --budget 0.36 --duration 1h --dry-run
 ```
 
 Testnet-only, key read from `METRIK_AGENT_PRIVATE_KEY`, `--json` for scripting. Full

package/docs/x402.md

@@ -10,6 +10,16 @@
 > `0xbD8B7B2F49Fdb954bda6bE5ce22218d44345DC43`, block 47337415); everything
 > here is testnet only.
 >
+> **Upfront ("minimum charge") opener.** A listing can instead quote the
+> `X402UpfrontStreamOpenerFactory` (metrik-contracts#54; Base Sepolia
+> `0x17126c80C12a51183d3664EEE2b602552592c2Aa`, implementation
+> `0xA9C58A2554Eb869B0D1ECBa46a0435cFFC90341d`, bound to StreamEscrowV3
+> `0x0643ba482C6A7aF31a1f8225e7e7e79Cfc467b13`): part of each payment is a
+> NON-REFUNDABLE per-call charge, only the rest is escrowed and metered. See
+> [The upfront (minimum-charge) opener](#the-upfront-minimum-charge-opener).
+> The V3-bound stream factory `0x3d3a…cFB2` stays live, and its clones are
+> still served and refunded.
+>
 > The separate Metrik-native `402` flow (scheme `streamproof-verified-stream`,
 > header `X-METRIK-PAYMENT`) described at the end is **not** x402 and is
 > unchanged.
@@ -33,9 +43,11 @@ So, in this package, and for anyone integrating it:
    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
+factory, escrow, usdc, chainId, minAmount, receiptTimeoutSeconds, refundRelay?, upfrontOpener?}` — 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).
+   runs the gasless refund relay (see below). `upfrontOpener = {factory,
+implementation, escrow, termsVersion: "upfront-1"}` is present when it also
+   settles the upfront opener kind; `factory` stays the stream factory.
 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)
@@ -146,6 +158,93 @@ 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.
 
+## The upfront (minimum-charge) opener
+
+A stream-opener payment funds a stream of the WHOLE payment, and accrual starts
+only at the first verified interval: a buyer who takes the response and closes
+within seconds reclaims almost all of it, so one delivered call can cost
+nothing. The upfront opener (metrik-contracts#54, design note
+`docs/x402-opener-min-charge.md`) fixes that with a new opener and factory;
+nothing deployed changed.
+
+- **Terms** gain two fields: `{operator, serviceRef, ratePerSecond,
+maxDuration, price, upfrontAmount}`. All six are committed by `payTo =
+upfrontFactory.predict(terms)` (CREATE2 over `abi.encode(terms)`), so the
+  payer's EIP-3009 signature binds the split too.
+- **`amount == price`**, exactly: the opener rejects any other value on-chain
+  (`PriceMismatch`) before anything moves.
+- **At settlement, in the same transaction**, `upfrontAmount` is paid to the
+  seller (minus the escrow's protocol fee, rounded up, to its fee recipient)
+  and is **NOT refundable**: it pays for the call whatever is delivered. Only
+  `price - upfrontAmount` funds a `StreamEscrowV3` stream, metered exactly like
+  a stream opener's, and that deposit is the most any refund can return.
+- **`upfrontAmount == price` is upfront-only**: no stream is opened at all. The
+  settlement reports `streamId: null` (on-chain `bytes32(0)`), the response is
+  served, no metered session exists, and there is nothing to close, reclaim or
+  refund.
+
+### The 402 `extra` (what the SDK enforces before signing)
+
+```json
+{
+  "factory": "<registry upfront factory>",
+  "termsVersion": "upfront-1",
+  "operator": "0x…",
+  "serviceRef": "0x…",
+  "ratePerSecond": "100",
+  "maxDuration": "3600",
+  "price": "60000",
+  "upfrontAmount": "15000",
+  "refundUrl": "https://<relay>/streams/{streamId}"
+}
+```
+
+under `extra.metrikStreamOpener`, with `amount == price` and `payTo ==
+predict(6 terms)`. An upfront-only quote carries no `refundUrl`. The SDK buyer
+(`payWithX402`, 0.10.0-rc.3) recomputes `payTo` OFFLINE from the registry's
+factory and implementation, runs `validateUpfrontTerms`, requires `price -
+upfrontAmount <= ratePerSecond × maxDuration`, and refuses an upfront part above
+`maxUpfrontAmount` (default 0.10 USDC; `0` refuses any).
+
+The settlement's `PAYMENT-RESPONSE.extra.metrikStreamOpener` is `{streamId
+(null when upfront-only), opener, escrow, deposit (= price - upfrontAmount),
+ratePerSecond, expiresAt (only with a stream), upfrontAmount, upfrontFee,
+refundUrl (only with a stream)}`; `upfrontAmount` and `upfrontFee` are read from
+the opener's `UpfrontCharged` event in the mined receipt.
+
+### What the facilitator checks for an upfront payment
+
+Everything in the table above, plus: the factory is the upfront factory this
+facilitator is bound to (anything not one of its configured factories is
+`metrik_opener_factory_mismatch`); the six terms pass the factory's own
+`validateTerms` rules and `price - upfrontAmount <= ratePerSecond ×
+maxDuration` (`metrik_opener_invalid_terms`); a `termsVersion`, when present,
+is `upfront-1`; `amount == price` (`metrik_opener_invalid_amount`); `payTo ==
+upfrontFactory.predict(terms)` on-chain; and an `eth_call` of the 6-tuple
+`deployAndSettle`. Price/upfront fields on a STREAM-factory quote are refused
+(that `payTo` does not commit to them). `settle` reports success only when the
+receipt shows exactly the signed split: `UpfrontCharged` for this payer, nonce,
+operator and `upfrontAmount` (when non-zero), and — unless upfront-only — the
+escrow's `StreamOpened` and the opener's `StreamOpenedFor` for a deposit of
+exactly `price - upfrontAmount`; an upfront-only receipt must show
+`UpfrontCharged` with `streamId 0` and no stream.
+
+### Running an upfront listing
+
+On the gateway, set `METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT` (base units) next to
+the usual `METRIK_GATEWAY_X402V2_*` variables; its presence selects the upfront
+kind, and the factory defaults to the registry's upfront factory
+(`METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS` overrides it;
+`METRIK_GATEWAY_X402V2_FACTORY_ADDRESS`, which names the stream factory, is
+refused alongside it). At startup the gateway validates the six terms, reads
+the factory's `escrow()`, `usdc()` and `implementation()`, and requires its
+on-chain `predict` to equal the offline CREATE2 derivation the SDK uses; the
+facilitator's marker must advertise exactly this upfront factory in
+`upfrontOpener`. Size `upfrontAmount` to at least the marginal cost of serving
+one call; use `upfrontAmount == price` for calls with nothing ongoing to meter.
+The facilitator settles the registry's upfront factory by default (see
+`METRIK_OPENER_FACILITATOR_UPFRONT_FACTORY_ADDRESS`).
+
 ## Getting unearned money back: the gasless refund relay
 
 **There is no automatic refund.** Nothing pushes money back to a payer, and no
@@ -177,6 +276,16 @@ The streamId and the refund URL arrive with the paid response:
 `PAYMENT-RESPONSE.extra.metrikStreamOpener = {streamId, opener, escrow,
 deposit, ratePerSecond, expiresAt, refundUrl}`.
 
+**Upfront openers.** The relay serves the upfront factory's clones too. Which
+factory's `isOpener` claims the stream's buyer, read on-chain, decides the
+opener's kind and so the EIP-712 domain the payer signs under (`"Metrik
+X402UpfrontStreamOpener"` instead of `"Metrik X402StreamOpener"`); the status
+reports `openerKind`, `price`, `upfrontAmount` and `maxRefund` (the deposit, =
+`price - upfrontAmount`) — the upfront part was paid at settlement and can
+never come back. **Stream id 0** is an upfront-only payment: every route
+answers `nothing-to-refund` (`404` for the status, `409` for the actions)
+without a chain read, and no close or reclaim is ever submitted for it.
+
 ### Endpoints (on the facilitator service; public, no bearer token)
 
 | Method + path                                | Body                                           | Does                                                            |
@@ -338,6 +447,7 @@ npx metrik-x402-opener-facilitator
 | `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_UPFRONT_FACTORY_ADDRESS`                  | the registry's, for the escrow        | Upfront opener factory settled too (same escrow and token); `off` disables it.       |
 | `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()`.                            |
@@ -390,6 +500,8 @@ The gateway's normal variables (`METRIK_GATEWAY_ESCROW_ADDRESS`,
 | `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_UPFRONT_AMOUNT`                           | unset (stream kind)                | Set = the upfront kind: the non-refundable per-call part, base units, `<= PRICE`; `PRICE - it <= rate × maxDuration`.                     |
+| `METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS`                  | the registry's upfront factory     | Only with `_UPFRONT_AMOUNT`.                                                                                                              |
 | `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.                                                                                              |
@@ -428,7 +540,17 @@ units/s and a price of 60000:
 > 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
+&lt;price&gt;)". An upfront listing (price 0.06, upfront 0.015) states the split:
+
+> Pays for one call: 0.06 USDC in total. 0.015 USDC is a NON-REFUNDABLE per-call
+> charge, paid to the seller at settlement whatever is delivered. The remaining
+> 0.045 USDC is metered and refundable: it funds a Metrik escrow stream of …;
+> the seller earns it only for seconds Metrik's verifier confirms the service is
+> delivering, and any unearned part of it (at most 0.045 USDC) is refundable to
+> you (no ETH needed) via …. Refunds are not automatic: …
+
+and an upfront-only one says the whole price is charged in full at settlement,
+is not refundable, and that nothing is metered or refundable. `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
@@ -457,13 +579,13 @@ protection intact, wrapped by `payX402WithMandate` (`@absol-labs/agent/x402-buye
 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`                                    |
+| Mandate cap            | x402 quote field                       |
+| ---------------------- | -------------------------------------- |
+| `maxPerStreamUsdc`     | `amount` (the whole 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
@@ -472,6 +594,17 @@ chain and before anything is signed — and the caps are also passed to the SDK
 `maxAmount` / `maxRatePerSecond`. A quote without opener terms is refused
 (`X402MandateDeniedError` reason `not-an-opener-quote`).
 
+For an upfront quote the mandate counts the WHOLE price, upfront part included,
+as spend (`budgetUsdc = price`); that part is non-recoverable and nothing a
+refund returns is credited back. Its size is also capped separately before
+signing by `maxUpfrontAmount` (`metrik pay --max-upfront`, MCP
+`maxUpfrontAmountUsdc`; default 0.10 USDC, `0` refuses any upfront charge). The
+split is shown before signing and in the result. An upfront-only payment
+(`streamId: null`) is final: `metrik pay` prints no refund or reclaim command,
+`metrik refund 0x00…00` and the MCP refund tools answer "nothing to refund"
+(exit 0 / not an error), and the MCP server records no stream for it — only a
+non-stream charge that still counts against the mandate.
+
 ```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
@@ -525,6 +658,13 @@ refund` and the MCP `refund` tool call it on request; `metrik close` /
   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.
+- **An upfront charge is final.** With an upfront listing the `upfrontAmount`
+  is paid to the seller at settlement whatever is delivered; only `price -
+upfrontAmount` is escrowed. The contract enforces the terms, not the
+  marketing text: a buyer's protection is the SDK recomputing `payTo` from the
+  advertised six terms and refusing on any difference, plus its
+  `maxUpfrontAmount` cap. The listing's signed `commercial` rate band bounds
+  only `ratePerSecond`, not the upfront part.
 - **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.12.0-rc.1",
+  "version": "0.12.0-rc.2",
   "description": "Metrik agent layer: verified-streaming USDC payments metered by delivery, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
@@ -85,8 +85,8 @@
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "0.10.0-rc.2",
-    "@absol-labs/shared": "0.14.0-rc.1",
+    "@absol-labs/sdk": "0.10.0-rc.3",
+    "@absol-labs/shared": "0.14.0-rc.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "1.3.0",
     "@privy-io/node": "0.33.0",

package/src/cli/commands/claim.ts

@@ -10,6 +10,9 @@ import {
   resolveCliWallet,
 } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
+import type { CliReadClient } from "../deps.js";
+import { escrowGenerationFor } from "../../escrow-generation.js";
+import type { StreamV2 } from "@absol-labs/sdk";
 
 /**
  * The seller's side of the loop.
@@ -65,40 +68,20 @@ export const claimCommand: CommandSpec = {
       );
     }
 
-    // Accrual lives in the oracle's checkpoint proof, never in the stream tuple.
-    // No proof means no claim is possible yet, and saying that is better than
-    // paying gas for a `NothingToClaim()` revert.
-    let cumulativeAmount: bigint;
-    try {
-      cumulativeAmount = (await read.checkpointProof(streamId))
-        .cumulativeAmount;
-    } catch (error) {
-      throw new CliError(
-        "no checkpoint covers this stream yet, so there is nothing provable to claim",
-        {
-          exitCode: 4,
-          hint: `the oracle publishes roughly every 15-22s and pays only for intervals that verified; ${describeError(
-            error,
-          )}`,
-          cause: error,
-        },
-      );
-    }
-
-    const claimable = await read.claimableForV2(streamId, cumulativeAmount);
-    if (claimable === 0n) {
-      throw new CliError("this stream has nothing claimable right now", {
-        exitCode: 4,
-        hint: `everything checkpointed so far has already been claimed. See where it stands:  metrik status ${streamId}`,
-      });
-    }
+    const plan = await planClaim(
+      read,
+      streamId,
+      stream,
+      escrowGenerationFor(config.chainId, config.escrow),
+    );
+    if (plan.kind === "nothing") throw plan.error;
 
     const write = deps.createWriteClient(
       config,
       account,
       writeClientOptions(wallet),
     );
-    const result = await write.claimStream({
+    const action = {
       streamId,
       // `null` for a policy-enforced wallet — see `../spend-policy.ts`.
       signedMandate: isPolicyEnforced(wallet)
@@ -106,21 +89,173 @@ export const claimCommand: CommandSpec = {
         : await signClaimMandate(account, config.chainId),
       spentSoFarUsdc: 0n,
       nowSeconds: deps.nowSeconds(),
-    });
+    };
+    let result: { readonly txHash: `0x${string}` };
+    if (plan.kind === "claimWithProof") {
+      result = await write.claimStream(action);
+    } else {
+      if (write.claimProvenStream === undefined) {
+        throw new CliError(
+          "this write client cannot send claimProven, which is the only way to collect this stream's proven value",
+          {
+            exitCode: 3,
+            hint: "no current checkpoint proof pays it, so a proof claim would revert NothingToClaim",
+          },
+        );
+      }
+      result = await write.claimProvenStream(action);
+    }
 
     out.result({
       streamId,
       txHash: result.txHash,
       operator: stream.operator,
-      claimed: claimable,
-      verifiedCumulative: cumulativeAmount,
+      claimed: plan.claimable,
+      method: plan.kind,
+      verifiedCumulative: plan.verifiedCumulative,
+      provenCumulative: plan.provenCumulative,
     });
     out.print("Claimed.");
     out.table([
       ["streamId", streamId],
       ["tx", result.txHash],
       ["operator", stream.operator],
-      ["claimed", `${formatUsdc(claimable)} (net of protocol fee)`],
+      ["claimed", `${formatUsdc(plan.claimable)} (net of protocol fee)`],
+      [
+        "via",
+        plan.kind === "claimWithProof"
+          ? "claimWithProof (the oracle's current checkpoint proof)"
+          : `claimProven (the on-chain proven high-water, ${formatUsdc(plan.provenCumulative ?? 0n)} gross — no current checkpoint proof pays more)`,
+      ],
     ]);
   },
 };
+
+/**
+ * Which claim, if any, `metrik claim` would send. Reads only, so it is
+ * testable (and checkable against a live stream) without a key.
+ *
+ * - `claimWithProof` pays `min(proofCumulative, deposit) − claimed` against ANY
+ *   retained checkpoint root.
+ * - `claimProven` (StreamEscrowV3) pays `min(provenCumulative, deposit) −
+ *   claimed` with NO proof: the high-water was itself proven against a signed
+ *   root when it was recorded. It is the only way to collect proven value whose
+ *   root has rotated out of the retained set, or that a later root regressed.
+ *
+ * Both are asked of the escrow (`claimableFor` at each cumulative; the escrow
+ * pays a claim with exactly that math), and the larger is chosen. A proof
+ * claim wins a tie, because it also raises the proven high-water. Nothing is
+ * chosen when both pay zero, so no gas is spent to learn `NothingToClaim`.
+ */
+export type ClaimPlan =
+  | {
+      readonly kind: "claimWithProof" | "claimProven";
+      /** What the operator receives, net of the protocol fee. */
+      readonly claimable: bigint;
+      /** The current proof's cumulative; `null` when no proof was available. */
+      readonly verifiedCumulative: bigint | null;
+      /** V3 proven high-water; `null` on V2 or when unreadable. */
+      readonly provenCumulative: bigint | null;
+    }
+  | { readonly kind: "nothing"; readonly error: CliError };
+
+export async function planClaim(
+  read: CliReadClient,
+  streamId: `0x${string}`,
+  stream: Pick<StreamV2, "claimedCumulative">,
+  escrowGeneration: string,
+): Promise<ClaimPlan> {
+  let verifiedCumulative: bigint | null = null;
+  let proofError: unknown = null;
+  try {
+    verifiedCumulative = (await read.checkpointProof(streamId))
+      .cumulativeAmount;
+  } catch (error) {
+    proofError = error;
+  }
+
+  let provenCumulative: bigint | null = null;
+  let provenError: string | null = null;
+  if (escrowGeneration === "v3") {
+    if (read.provenCumulativeOf === undefined) {
+      provenError = "this read client cannot read provenCumulativeOf";
+    } else {
+      try {
+        provenCumulative = await read.provenCumulativeOf(streamId);
+      } catch (error) {
+        provenError = describeError(error);
+      }
+    }
+  }
+
+  const [proofClaimable, provenClaimable] = await Promise.all([
+    verifiedCumulative === null
+      ? 0n
+      : read.claimableForV2(streamId, verifiedCumulative),
+    // `claimProven` pays at the high-water, so it is worth asking only when
+    // the high-water is above what has already been claimed.
+    provenCumulative === null || provenCumulative <= stream.claimedCumulative
+      ? 0n
+      : read.claimableForV2(streamId, provenCumulative),
+  ]);
+
+  if (proofClaimable > 0n && proofClaimable >= provenClaimable) {
+    return {
+      kind: "claimWithProof",
+      claimable: proofClaimable,
+      verifiedCumulative,
+      provenCumulative,
+    };
+  }
+  if (provenClaimable > 0n) {
+    return {
+      kind: "claimProven",
+      claimable: provenClaimable,
+      verifiedCumulative,
+      provenCumulative,
+    };
+  }
+
+  if (provenCumulative !== null && provenCumulative > 0n) {
+    return {
+      kind: "nothing",
+      error: new CliError("this stream has nothing to claim", {
+        exitCode: 4,
+        hint: `everything proven on-chain for it (${formatUsdc(provenCumulative)} gross) has already been claimed${
+          verifiedCumulative === null
+            ? ", and the latest checkpoint no longer contains it"
+            : ""
+        }. See where it stands:  metrik status ${streamId}`,
+      }),
+    };
+  }
+  if (verifiedCumulative === null) {
+    // Accrual lives in the oracle's checkpoint proof (and, on V3, the proven
+    // high-water), never in the stream tuple. Saying so is better than paying
+    // gas for a `NothingToClaim()` revert.
+    return {
+      kind: "nothing",
+      error: new CliError(
+        "no checkpoint covers this stream yet, so there is nothing provable to claim",
+        {
+          exitCode: 4,
+          hint: `the oracle publishes roughly every 15-22s and pays only for intervals that verified; ${describeError(
+            proofError,
+          )}${
+            provenError === null
+              ? ""
+              : `; the on-chain proven high-water could not be read either (${provenError})`
+          }`,
+          cause: proofError,
+        },
+      ),
+    };
+  }
+  return {
+    kind: "nothing",
+    error: new CliError("this stream has nothing claimable right now", {
+      exitCode: 4,
+      hint: `everything checkpointed so far has already been claimed. See where it stands:  metrik status ${streamId}`,
+    }),
+  };
+}