@absol-labs/agent 0.9.1 → 0.11.0

package/dist/cli/commands/reclaim.js

@@ -0,0 +1,308 @@
+import { SettlementWindowOpenError } from "@absol-labs/sdk";
+import { booleanFlag, integerFlag } from "../args.js";
+import { formatUsdc } from "../amounts.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { CliError, describeError, usageError } from "../errors.js";
+import { describeEscapeHatch, escapeHatchWindow, readChainNow, } from "../escape-hatch.js";
+import { signRecoveryMandate } from "../mandate.js";
+import { assertCanPayGas } from "../preflight.js";
+import { writeClientOptions } from "../deps.js";
+import { isPolicyEnforced, resolveCliWallet } from "../wallet.js";
+/**
+ * How long to keep retrying a reclaim that is blocked only by an open
+ * settlement window. Defaults chosen to comfortably cover the oracle's ~15-22s
+ * checkpoint cadence: 12 x 10s = two minutes.
+ */
+const DEFAULT_ATTEMPTS = 12;
+const DEFAULT_INTERVAL_SECONDS = 10;
+export const reclaimCommand = {
+    name: "reclaim",
+    summary: "Take back the budget that was never earned",
+    usage: "metrik reclaim <streamId> [--close-first] [--attempts 12] [--interval 10]",
+    flags: ["close-first", "attempts", "interval"],
+    signs: true,
+    async run(context) {
+        const { args, config, env, out, deps } = context;
+        const [streamIdArg] = args.positionals;
+        if (streamIdArg === undefined) {
+            throw usageError("metrik reclaim requires a <streamId>");
+        }
+        const streamId = parseBytes32(streamIdArg, "<streamId>");
+        const closeFirst = booleanFlag(args, "close-first");
+        const attempts = integerFlag(args, "attempts") ?? DEFAULT_ATTEMPTS;
+        const interval = integerFlag(args, "interval") ?? DEFAULT_INTERVAL_SECONDS;
+        if (attempts < 1)
+            throw usageError("--attempts must be at least 1");
+        if (interval < 1)
+            throw usageError("--interval must be at least 1 second");
+        const wallet = await resolveCliWallet(env, {
+            note: out.note,
+            rpcUrl: config.rpcUrl,
+        });
+        const { account } = wallet;
+        const read = deps.createReadClient(config);
+        await assertTestnetRpc(config, () => read.getChainId());
+        await assertCanPayGas(read, account.address);
+        const write = deps.createWriteClient(config, account, writeClientOptions(wallet));
+        // A policy-enforced wallet (Privy) signs no mandate of its own: these are
+        // buyer-recovery actions, gated by the escrow on the buyer address and by
+        // the broker on `stream.buyer == wallet`. See `../spend-policy.ts`.
+        const recoveryMandate = async () => isPolicyEnforced(wallet)
+            ? null
+            : await signRecoveryMandate(account, config.chainId);
+        // `--close-first` is TWO transactions, and the second one only simulates
+        // successfully against post-close state. Sequencing them inside a single SDK
+        // call sent the reclaim simulation at a node that had not yet applied the
+        // close, and the command died with `StreamNotReclaimable()` having already
+        // spent the buyer's close — leaving the stream closed-but-unreclaimed, and
+        // the obvious retry dead-ending on `StreamClosedAlready()`. So the CLI owns
+        // the ordering: skip the close when the stream is already closed, and wait
+        // for the close to be VISIBLE to the node we are about to simulate against.
+        let closeResult = null;
+        let alreadyClosed = false;
+        if (closeFirst) {
+            const before = await read.getStreamV2(streamId).catch(() => null);
+            if (before !== null && before.status === "closed") {
+                alreadyClosed = true;
+                out.note("stream is already closed — skipping the close and going straight to reclaim.");
+            }
+            else {
+                closeResult = await closeBeforeReclaim(write, {
+                    streamId,
+                    signedMandate: await recoveryMandate(),
+                    spentSoFarUsdc: 0n,
+                    nowSeconds: deps.nowSeconds(),
+                });
+                if (closeResult === null) {
+                    alreadyClosed = true;
+                    out.note("the stream was already closed by the time the close was sent — going straight to reclaim.");
+                }
+                else {
+                    out.note(`closed in ${closeResult.txHash} — waiting for it to land …`);
+                    await awaitClosed(read, streamId, deps.sleep, closeResult.txHash);
+                }
+            }
+        }
+        const result = await reclaimWithBoundedRetry(write, async () => ({
+            streamId,
+            signedMandate: await recoveryMandate(),
+            spentSoFarUsdc: 0n,
+            nowSeconds: deps.nowSeconds(),
+        }), {
+            attempts,
+            intervalMs: interval * 1_000,
+            sleep: deps.sleep,
+            onRetry: (attempt, reason) => out.note(`reclaim blocked: no checkpoint covers the stream's stop time yet (attempt ${attempt}/${attempts}) — ${reason}`),
+            // "Retry later" is the wrong advice when the oracle is gone: every
+            // attempt this command makes needs a proof FROM that oracle. So the
+            // give-up message names the path that needs no proof, and says whether
+            // it is open yet.
+            exhaustedHint: async () => await describeLastResort(read, streamId, deps.nowSeconds()),
+        });
+        // Read the settled figure back only once the node we are reading from has
+        // actually applied the reclaim. `sepolia.base.org` is load-balanced, so an
+        // immediate read can land on a lagged node and report `settledCumulative: 0`
+        // for a stream that just settled a non-zero amount — printing "settled to
+        // operator 0 USDC" when it was not zero. Poll for `reclaimed` (which the
+        // transaction we just landed sets) so the number beside it is from the same
+        // post-reclaim state. Bounded, and falls back to the last value read.
+        const stream = await readSettledStream(read, streamId, deps.sleep);
+        out.result({
+            streamId,
+            txHash: result.reclaimResult.txHash,
+            closeTxHash: closeResult?.txHash ?? null,
+            // `--close-first` on a stream that was already closed is a no-op, not a
+            // failure. Machine consumers need to tell that apart from "no close was
+            // asked for".
+            closeSkippedAlreadyClosed: closeFirst ? alreadyClosed : null,
+            settledCumulative: stream?.settledCumulative ?? null,
+        });
+        out.print("Reclaimed.");
+        out.table([
+            ["streamId", streamId],
+            ["reclaim tx", result.reclaimResult.txHash],
+            ...(closeResult === null
+                ? alreadyClosed
+                    ? [["close", "skipped — already closed"]]
+                    : []
+                : [["close tx", closeResult.txHash]]),
+            ...(stream === null
+                ? []
+                : [
+                    ["settled to operator", formatUsdc(stream.settledCumulative)],
+                ]),
+        ]);
+    },
+};
+/**
+ * Send the close that `--close-first` asks for, tolerating the one race that
+ * matters: a stale read said "active" but the stream was in fact already closed.
+ * That is the state the caller wanted, so it is reported as `null` (no close
+ * sent) rather than as a failure — re-running the command must never dead-end on
+ * `StreamClosedAlready()` while the buyer's money is still reclaimable.
+ *
+ * Every OTHER close failure is rethrown untouched.
+ */
+export async function closeBeforeReclaim(write, input) {
+    try {
+        return await write.closeStream(input);
+    }
+    catch (error) {
+        if (isAlreadyClosed(error))
+            return null;
+        throw error;
+    }
+}
+/** True when `error`, or anything in its cause chain, is StreamClosedAlready. */
+function isAlreadyClosed(error) {
+    for (let current = error, depth = 0; depth < 8; depth++) {
+        if (!(current instanceof Error))
+            return false;
+        if (current.message.includes("StreamClosedAlready"))
+            return true;
+        if (current.cause === undefined)
+            return false;
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * Block until the node we read from reports the stream as closed.
+ *
+ * The close transaction's own receipt is awaited inside the SDK, but
+ * `sepolia.base.org` is load-balanced: the receipt can come back from one node
+ * while the very next `simulateContract` lands on another that has not imported
+ * the block yet. That node simulates `reclaim` against PRE-close state and
+ * reverts `StreamNotReclaimable()`. Confirming the close through the same read
+ * path the reclaim will use is what closes that window.
+ */
+const CLOSE_VISIBLE_ATTEMPTS = 20;
+const CLOSE_VISIBLE_INTERVAL_MS = 500;
+export async function awaitClosed(read, streamId, sleep, closeTxHash) {
+    for (let attempt = 1; attempt <= CLOSE_VISIBLE_ATTEMPTS; attempt += 1) {
+        const stream = await read.getStreamV2(streamId).catch(() => null);
+        if (stream !== null && stream.status === "closed")
+            return;
+        if (attempt < CLOSE_VISIBLE_ATTEMPTS)
+            await sleep(CLOSE_VISIBLE_INTERVAL_MS);
+    }
+    throw new CliError(`the close landed in ${closeTxHash} but the RPC endpoint still reports the stream as active`, {
+        exitCode: 4,
+        hint: `the close is not lost and neither is the money: re-run \`metrik reclaim ${streamId} --close-first\` once the endpoint has caught up — it will skip the close and reclaim.`,
+    });
+}
+/**
+ * `reclaimWithProof` reverts with `SettlementWindowOpen` until the oracle has
+ * published a checkpoint whose `checkedAt` is at or after the stream's stop
+ * time. That is not an error condition — it is the normal ordering of a
+ * checkpoint rail, and it happens on the FIRST attempt essentially every time.
+ * A CLI that surfaced the raw revert would teach every user that reclaim is
+ * broken, so the wait is built in and narrated. Any other failure is rethrown
+ * immediately: only an open settlement window is retried.
+ */
+export async function reclaimWithBoundedRetry(write, buildInput, options) {
+    let lastError;
+    for (let attempt = 1; attempt <= options.attempts; attempt++) {
+        try {
+            return await write.reclaimStream(await buildInput());
+        }
+        catch (error) {
+            if (!isSettlementWindowOpen(error))
+                throw explainReclaimFailure(error);
+            lastError = error;
+            if (attempt === options.attempts)
+                break;
+            options.onRetry(attempt, describeError(error));
+            await options.sleep(options.intervalMs);
+        }
+    }
+    throw new CliError(`reclaim is still blocked after ${options.attempts} attempt${options.attempts === 1 ? "" : "s"}: the oracle has not published a checkpoint covering this stream's stop time`, {
+        exitCode: 4,
+        hint: (await options.exhaustedHint?.().catch(() => null)) ??
+            DEFAULT_EXHAUSTED_HINT,
+        cause: lastError,
+    });
+}
+const DEFAULT_EXHAUSTED_HINT = "the funds are not lost — retry later, or raise --attempts / --interval. If the oracle stays down, `metrik reclaim-unverified` takes them back with no proof once the escape hatch opens.";
+/**
+ * What to do when the proof-based path has run out of attempts.
+ *
+ * Every reclaim this command can perform goes through `reclaimWithProof`, which
+ * needs a Merkle proof fetched from the oracle — so a buyer whose oracle is gone
+ * can retry this command forever and never get their money. The escrow's
+ * `reclaimUnverified` is the path that does not need the oracle, and the only
+ * question that matters is whether its window has opened yet. That is fully
+ * computable: `expiresAt + escapeGraceSeconds` against the chain's clock.
+ */
+async function describeLastResort(read, streamId, fallbackNowSeconds) {
+    const [stream, grace] = await Promise.all([
+        read.getStreamV2(streamId),
+        read.escapeGraceSeconds(),
+    ]);
+    const now = await readChainNow(read, fallbackNowSeconds);
+    const window = escapeHatchWindow(stream, grace, now.seconds);
+    const escapeCommand = `metrik reclaim-unverified ${streamId} --forfeit-unclaimed`;
+    return window.ready
+        ? `the funds are not lost. The no-proof escape hatch is OPEN (${describeEscapeHatch(window)}): \`${escapeCommand}\` takes them back without the oracle — at the cost of forfeiting whatever the operator earned but has not yet claimed. Retrying this command only helps if the oracle comes back.`
+        : `the funds are not lost, but retrying only helps if the oracle comes back — this path needs a proof from it. The no-proof escape hatch ${describeEscapeHatch(window)}; from then on \`${escapeCommand}\` takes them back without the oracle, forfeiting whatever the operator earned but has not yet claimed.`;
+}
+/**
+ * `StreamNotReclaimable()` means exactly one thing: the stream is neither closed
+ * nor past its expiry. Say that, and say which command fixes it, instead of
+ * handing the reader a selector.
+ */
+function explainReclaimFailure(error) {
+    if (!(error instanceof Error))
+        return error;
+    for (let current = error, depth = 0; depth < 8; depth++) {
+        if (!(current instanceof Error))
+            break;
+        if (current.message.includes("StreamNotReclaimable")) {
+            return new CliError("the stream is still running, so there is nothing to reclaim yet", {
+                exitCode: 4,
+                hint: "stop the clock first — `metrik close <streamId>`, or re-run this command with --close-first — or wait for the stream to expire.",
+                cause: error,
+            });
+        }
+        if (current.cause === undefined)
+            break;
+        current = current.cause;
+    }
+    return error;
+}
+/** True when `error`, or anything in its cause chain, is SettlementWindowOpen. */
+function isSettlementWindowOpen(error) {
+    for (let current = error, depth = 0; depth < 8; depth++) {
+        if (current instanceof SettlementWindowOpenError)
+            return true;
+        if (!(current instanceof Error) || current.cause === undefined)
+            return false;
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * Bounded poll for the post-reclaim stream state. Returns as soon as the node
+ * reports `reclaimed`, or the last successful read once attempts are exhausted
+ * (never throws — the reclaim already succeeded and a display read must not
+ * turn that into a command failure).
+ */
+const SETTLED_READ_ATTEMPTS = 5;
+// Deliberately sub-second and distinct from the retry interval (whole seconds,
+// `--interval`), so the two waits are tellable apart in tests and in logs.
+const SETTLED_READ_INTERVAL_MS = 500;
+async function readSettledStream(read, streamId, sleep) {
+    let last = null;
+    for (let attempt = 1; attempt <= SETTLED_READ_ATTEMPTS; attempt += 1) {
+        const stream = await read.getStreamV2(streamId).catch(() => null);
+        if (stream !== null) {
+            last = stream;
+            if (stream.reclaimed)
+                return stream;
+        }
+        if (attempt < SETTLED_READ_ATTEMPTS)
+            await sleep(SETTLED_READ_INTERVAL_MS);
+    }
+    return last;
+}
+//# sourceMappingURL=reclaim.js.map

package/dist/cli/commands/reclaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reclaim.js","sourceRoot":"","sources":["../../../src/cli/commands/reclaim.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/status.d.ts

@@ -0,0 +1,3 @@
+import type { CommandSpec } from "../context.js";
+export declare const statusCommand: CommandSpec;
+//# sourceMappingURL=status.d.ts.map

package/dist/cli/commands/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/status.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjE,eAAO,MAAM,aAAa,EAAE,WA6C3B,CAAC"}

package/dist/cli/commands/status.js

@@ -0,0 +1,43 @@
+import { attesterDisclosure } from "../attesters.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { usageError } from "../errors.js";
+import { readStreamReport, streamReportJson, streamReportRows, } from "../status.js";
+export const statusCommand = {
+    name: "status",
+    summary: "Show a stream's on-chain state and its oracle-verified accrual",
+    usage: "metrik status <streamId>",
+    flags: [],
+    signs: false,
+    async run(context) {
+        const { args, config, out, deps } = context;
+        const [streamIdArg] = args.positionals;
+        if (streamIdArg === undefined) {
+            throw usageError("metrik status requires a <streamId>");
+        }
+        const streamId = parseBytes32(streamIdArg, "<streamId>");
+        const read = deps.createReadClient(config);
+        // Reads get the same chain allowlist as the signing paths. A read pointed at
+        // the wrong chain does not lose money, but the V1 and V2 stream tuples
+        // diverge from index 5 onward, so a wrong-chain read does not revert — it
+        // silently decodes something else into fields with the right names.
+        await assertTestnetRpc(config, () => read.getChainId());
+        const report = await readStreamReport(read, streamId, deps.nowSeconds());
+        out.result(streamReportJson(report));
+        // Who attests, before the numbers. Printed on stderr so it survives `--json`
+        // and cannot be lost by a consumer that only parses stdout.
+        const disclosure = attesterDisclosure(report.attesters, report.stream.operator);
+        if (disclosure !== null)
+            out.note(disclosure);
+        out.print(`Stream ${streamId}`);
+        out.table(streamReportRows(report));
+        if (report.settlement.pending) {
+            out.print("");
+            out.print("This stream has stopped but its final checkpoint has not landed, so there is no settled reclaimable figure yet — reclaim reverts until the oracle publishes a checkpoint reaching the stop time. `metrik reclaim <streamId>` waits for exactly that.");
+        }
+        if (report.proof === null) {
+            out.print("");
+            out.print("No checkpoint covers this stream yet. Accrual is published by the oracle roughly every 15-22s; funds are earned only for intervals that verified.");
+        }
+    },
+};
+//# sourceMappingURL=status.js.map

package/dist/cli/commands/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../src/cli/commands/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAGtB,MAAM,CAAC,MAAM,aAAa,GAAgB;IACxC,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,gEAAgE;IACzE,KAAK,EAAE,0BAA0B;IACjC,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,KAAK;IACZ,KAAK,CAAC,GAAG,CAAC,OAAuB;QAC/B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;QAC5C,MAAM,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;QACvC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,UAAU,CAAC,qCAAqC,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QAEzD,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC3C,6EAA6E;QAC7E,uEAAuE;QACvE,0EAA0E;QAC1E,oEAAoE;QACpE,MAAM,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACxD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAEzE,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;QACrC,6EAA6E;QAC7E,4DAA4D;QAC5D,MAAM,UAAU,GAAG,kBAAkB,CACnC,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,MAAM,CAAC,QAAQ,CACvB,CAAC;QACF,IAAI,UAAU,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC9C,GAAG,CAAC,KAAK,CAAC,UAAU,QAAQ,EAAE,CAAC,CAAC;QAChC,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;QACpC,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YAC9B,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACd,GAAG,CAAC,KAAK,CACP,sPAAsP,CACvP,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YAC1B,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACd,GAAG,CAAC,KAAK,CACP,mJAAmJ,CACpJ,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/cli/commands/streams.d.ts

@@ -0,0 +1,3 @@
+import type { CommandSpec } from "../context.js";
+export declare const streamsCommand: CommandSpec;
+//# sourceMappingURL=streams.d.ts.map

package/dist/cli/commands/streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/streams.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,eAAe,CAAC;AA8BjE,eAAO,MAAM,cAAc,EAAE,WA6K5B,CAAC"}

package/dist/cli/commands/streams.js

@@ -0,0 +1,257 @@
+import { BASE_SEPOLIA_ESCROW_V2 } from "@absol-labs/sdk";
+import { getAddress, isAddress } from "viem";
+import { integerFlag, stringFlag } from "../args.js";
+import { formatUsdc } from "../amounts.js";
+import { BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK, assertTestnetRpc, } from "../config.js";
+import { CliError, configError, usageError } from "../errors.js";
+import { escrowScanRange } from "../scan-range.js";
+import { optionalCliWallet, PRIVATE_KEY_ENV } from "../wallet.js";
+/** Indexed-party filters, and the `--role` values that select them. */
+const ROLES = ["buyer", "operator"];
+/**
+ * How many `eth_getLogs` calls are in flight at once. The full history of the
+ * live escrow is ~106 windows x 2 role filters; firing those unbounded is how a
+ * public RPC starts answering 429, and a rate-limited window is a window this
+ * command has to report as unscanned.
+ */
+const SCAN_CONCURRENCY = 6;
+/**
+ * Attempts per window before it is reported as unscanned. A public RPC answers
+ * a burst of `eth_getLogs` with an occasional 429 — measured against
+ * `sepolia.base.org`, 2 of 212 windows on a full-history scan — and a transient
+ * rate-limit is NOT a window that cannot be scanned. Declaring it one would
+ * make the "this scan is incomplete" warning routine, and a warning that fires
+ * on every healthy run is a warning nobody reads on the run that matters.
+ */
+const WINDOW_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 400;
+export const streamsCommand = {
+    name: "streams",
+    summary: "List the streams a wallet has opened, or been hired through",
+    usage: "metrik streams [--address 0x…] [--role buyer|operator|any] [--limit N] [--from-block N]",
+    flags: ["address", "role", "limit", "from-block"],
+    signs: false,
+    async run(context) {
+        const { args, config, env, out, deps } = context;
+        const roleFlag = stringFlag(args, "role") ?? "any";
+        if (roleFlag !== "any" && !ROLES.includes(roleFlag)) {
+            throw usageError(`--role must be buyer, operator or any (got "${roleFlag}")`);
+        }
+        const roles = roleFlag === "any" ? ROLES : [roleFlag];
+        const limit = integerFlag(args, "limit");
+        if (limit !== undefined && limit < 1) {
+            throw usageError("--limit must be at least 1");
+        }
+        const address = await resolveScanAddress(context);
+        const read = deps.createReadClient(config);
+        // The same allowlist the signing paths get. This command spends nothing,
+        // but it reads a V2 stream tuple, and the V1 and V2 tuples diverge from
+        // index 5 onward — a wrong-chain read does not revert, it decodes something
+        // else into fields with the right names.
+        await assertTestnetRpc(config, () => read.getChainId());
+        const anchor = resolveAnchorBlock(args, config.escrow);
+        const head = await read.blockNumber();
+        const range = escrowScanRange(head, anchor.block);
+        // Retention canary, before the scan is believed. A node that has pruned its
+        // log index answers a range it no longer retains with a SUCCESSFUL EMPTY
+        // result (measured on Base Sepolia: one public endpoint returned 0 logs for
+        // a window where two others returned 582). This CLI talks to ONE endpoint,
+        // so it cannot recover those logs from a sibling the way a multi-provider
+        // client can — but it can refuse to call the silence "no streams".
+        const retention = anchor.canary === null
+            ? null
+            : await read
+                .escrowLogCountAt(anchor.canary)
+                .then((count) => count > 0)
+                .catch(() => false);
+        const scan = await scanOpenedStreams(read, address, roles, range.windows, deps.sleep);
+        const reasons = [];
+        if (range.degraded) {
+            reasons.push(`the window budget could not reach block ${anchor.block} (scan starts at ${range.fromBlock})`);
+        }
+        if (scan.failedWindows > 0) {
+            reasons.push(`${scan.failedWindows} of ${range.windows.length * roles.length} log queries failed after ${WINDOW_ATTEMPTS} attempts each`);
+        }
+        if (retention === false) {
+            reasons.push(`${config.rpcUrl} does not serve logs for block ${anchor.canary}, so it has pruned the escrow's history and its empty windows cannot be trusted`);
+        }
+        const degraded = reasons.length > 0;
+        // Newest first: the stream someone is looking for is almost always the one
+        // they just opened.
+        const opened = [...scan.opened].sort((a, b) => a.blockNumber === b.blockNumber
+            ? 0
+            : a.blockNumber > b.blockNumber
+                ? -1
+                : 1);
+        const shown = limit === undefined ? opened : opened.slice(0, limit);
+        // One `getStream` per row. A list that cannot distinguish an active stream
+        // from a closed one is not actionable, and status is the one field the
+        // event cannot carry. The oracle's checkpoint proof is deliberately NOT
+        // fetched here — that is a per-stream HTTP call, and `metrik status` is the
+        // command that makes it.
+        const rows = await Promise.all(shown.map(async (log) => {
+            const stream = await read.getStreamV2(log.streamId).catch(() => null);
+            return {
+                streamId: log.streamId,
+                role: describeRole(log, address),
+                buyer: log.buyer,
+                operator: log.operator,
+                serviceRef: log.serviceRef,
+                // V2 MUTATES `Stream.deposit` on reclaim, so the event is the only
+                // surviving record of what was originally escrowed.
+                originalDepositUsdc: log.deposit,
+                ratePerSecondUsdc: log.ratePerSecond,
+                expiresAt: log.expiresAt,
+                openedAtBlock: log.blockNumber,
+                // A read failure is reported as unread, never as a dropped row: a
+                // stream that vanishes from this list is the exact failure the whole
+                // command is built to avoid.
+                status: stream?.status ?? "unread",
+                reclaimed: stream?.reclaimed ?? null,
+            };
+        }));
+        out.result({
+            address,
+            role: roleFlag,
+            escrow: config.escrow,
+            fromBlock: range.fromBlock,
+            toBlock: range.toBlock,
+            windows: range.windows.length,
+            logRetentionProven: retention,
+            degraded,
+            degradedReasons: reasons,
+            found: opened.length,
+            count: rows.length,
+            streams: rows,
+        });
+        if (degraded) {
+            // stderr in both modes: a partial scan must reach someone piping stdout
+            // into jq just as loudly as someone reading the table.
+            out.note(`warning: this scan is INCOMPLETE — ${reasons.join("; ")}. Streams may exist that are not listed below.`);
+        }
+        if (rows.length === 0) {
+            out.print(degraded
+                ? `No streams found for ${address} in the part of the escrow's history that could be scanned. This is NOT a statement that none exist — see the warning above.`
+                : `No streams for ${address} across the escrow's full history (blocks ${range.fromBlock}-${range.toBlock}).`);
+            return;
+        }
+        out.print(`${rows.length} stream${rows.length === 1 ? "" : "s"} for ${address}${opened.length > rows.length ? ` (of ${opened.length}, limited)` : ""}`);
+        for (const row of rows) {
+            out.print("");
+            out.print(`${row.streamId}  [${row.status}]`);
+            out.table([
+                ["role", row.role],
+                ["counterparty", row.role === "buyer" ? row.operator : row.buyer],
+                ["serviceRef", row.serviceRef],
+                ["escrowed", formatUsdc(row.originalDepositUsdc)],
+                ["rate", `${formatUsdc(row.ratePerSecondUsdc)} / second`],
+                ["opened at block", row.openedAtBlock.toString()],
+                [
+                    "reclaimed",
+                    row.reclaimed === null ? "unread" : String(row.reclaimed),
+                ],
+            ]);
+        }
+        out.print("");
+        out.print("Earned-so-far is published by the oracle, not held on the stream:  metrik status <streamId>");
+    },
+};
+/** Whose streams to list: an explicit `--address`, else the configured wallet. */
+async function resolveScanAddress(context) {
+    const { args, env, out } = context;
+    const explicit = stringFlag(args, "address");
+    if (explicit !== undefined) {
+        if (!isAddress(explicit)) {
+            throw usageError(`--address must be an EVM address (got "${explicit}")`);
+        }
+        return getAddress(explicit);
+    }
+    // This command broadcasts nothing and signs nothing, so it must not demand a
+    // wallet: `--address` is enough to read anyone's streams. A configured wallet
+    // is simply the default subject.
+    const wallet = await optionalCliWallet(env, { note: out.note });
+    if (wallet === null) {
+        throw configError("metrik streams needs a wallet to know whose streams to list", `pass --address 0x… to list any address's streams without one, or set ${PRIVATE_KEY_ENV} (or the CDP or Privy variables).`);
+    }
+    return wallet.account.address;
+}
+/**
+ * Where the log scan starts, and whether a retention canary is possible there.
+ *
+ * The canary block must be one that is KNOWN to carry escrow logs, otherwise a
+ * zero from it proves nothing and every scan would report itself degraded
+ * forever. That is only true of the deploy block of the escrow we shipped the
+ * constant for — so an overridden `--escrow` or `--from-block` scans without a
+ * canary rather than with a meaningless one.
+ */
+function resolveAnchorBlock(args, escrow) {
+    const override = integerFlag(args, "from-block");
+    const isKnownEscrow = escrow.toLowerCase() === BASE_SEPOLIA_ESCROW_V2.toLowerCase();
+    if (override !== undefined) {
+        return { block: BigInt(override), canary: null };
+    }
+    if (!isKnownEscrow) {
+        throw configError(`no scan anchor is known for escrow ${escrow}`, "the scan is anchored at the escrow's deploy block, and this CLI only ships that block for its default Base Sepolia escrow. Pass --from-block <deploy block> for a different escrow.");
+    }
+    return {
+        block: BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
+        canary: BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
+    };
+}
+/**
+ * Page every window for every selected role filter, bounded concurrency.
+ *
+ * A window that ERRORS is counted, not thrown: a partial list with an honest
+ * warning is more useful than no list at all, and the count is what makes the
+ * warning specific.
+ */
+async function scanOpenedStreams(read, address, roles, windows, sleep) {
+    // A wallet that is BOTH buyer and operator on one stream matches two filters.
+    const byStreamId = new Map();
+    let failedWindows = 0;
+    const readWindow = async (query) => {
+        for (let attempt = 1; attempt <= WINDOW_ATTEMPTS; attempt++) {
+            try {
+                return await read.streamOpenedLogs(query);
+            }
+            catch {
+                if (attempt < WINDOW_ATTEMPTS)
+                    await sleep(RETRY_DELAY_MS * attempt);
+            }
+        }
+        return null;
+    };
+    const queries = windows.flatMap(([fromBlock, toBlock]) => roles.map((role) => ({ role, address, fromBlock, toBlock })));
+    for (let index = 0; index < queries.length; index += SCAN_CONCURRENCY) {
+        const batch = queries.slice(index, index + SCAN_CONCURRENCY);
+        const settled = await Promise.all(batch.map(readWindow));
+        for (const logs of settled) {
+            if (logs === null) {
+                failedWindows++;
+                continue;
+            }
+            for (const log of logs) {
+                if (!byStreamId.has(log.streamId))
+                    byStreamId.set(log.streamId, log);
+            }
+        }
+    }
+    return { opened: [...byStreamId.values()], failedWindows };
+}
+function describeRole(log, address) {
+    const wanted = address.toLowerCase();
+    const isBuyer = log.buyer.toLowerCase() === wanted;
+    const isOperator = log.operator.toLowerCase() === wanted;
+    if (isBuyer && isOperator)
+        return "buyer+operator";
+    if (isBuyer)
+        return "buyer";
+    if (isOperator)
+        return "operator";
+    // Only reachable if the node ignored the indexed topic filter it was given.
+    throw new CliError(`the RPC returned stream ${log.streamId}, which does not involve ${address}`, {
+        exitCode: 4,
+        hint: "the escrow log filter was not applied by the endpoint; the result cannot be trusted.",
+    });
+}
+//# sourceMappingURL=streams.js.map