@absol-labs/agent 0.9.1 → 0.10.0

package/src/cli/commands/reclaim.ts

@@ -0,0 +1,360 @@
+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 { resolveCliWallet } from "../wallet.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+import type { CliReadClient, CliWriteClient } from "../deps.js";
+import type {
+  ReclaimVerifiedStreamResult,
+  StreamProofTransactionResult,
+} from "../../sdk/client.js";
+import type { StreamV2 } from "@absol-labs/sdk";
+
+/**
+ * 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: CommandSpec = {
+  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: CommandContext): Promise<void> {
+    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 { account } = await resolveCliWallet(env, { note: out.note });
+    const read = deps.createReadClient(config);
+    await assertTestnetRpc(config, () => read.getChainId());
+    await assertCanPayGas(read, account.address);
+
+    const write = deps.createWriteClient(config, account);
+
+    // `--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: StreamProofTransactionResult | null = 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 signRecoveryMandate(account, config.chainId),
+          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 signRecoveryMandate(account, config.chainId),
+        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"]] as const)
+          : []
+        : ([["close tx", closeResult.txHash]] as const)),
+      ...(stream === null
+        ? []
+        : ([
+            ["settled to operator", formatUsdc(stream.settledCumulative)],
+          ] as const)),
+    ]);
+  },
+};
+
+/**
+ * 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: CliWriteClient,
+  input: Parameters<CliWriteClient["closeStream"]>[0],
+): Promise<StreamProofTransactionResult | null> {
+  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: unknown): boolean {
+  for (let current: unknown = 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: Pick<CliReadClient, "getStreamV2">,
+  streamId: `0x${string}`,
+  sleep: (ms: number) => Promise<void>,
+  closeTxHash: string,
+): Promise<void> {
+  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: CliWriteClient,
+  buildInput: () => Promise<Parameters<CliWriteClient["reclaimStream"]>[0]>,
+  options: {
+    readonly attempts: number;
+    readonly intervalMs: number;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly onRetry: (attempt: number, reason: string) => void;
+    /** What to tell the buyer once the budget is spent. See `describeLastResort`. */
+    readonly exhaustedHint?: () => Promise<string>;
+  },
+): Promise<ReclaimVerifiedStreamResult> {
+  let lastError: unknown;
+  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: CliReadClient,
+  streamId: `0x${string}`,
+  fallbackNowSeconds: number,
+): Promise<string> {
+  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: unknown): unknown {
+  if (!(error instanceof Error)) return error;
+  for (let current: unknown = 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: unknown): boolean {
+  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: { getStreamV2(streamId: `0x${string}`): Promise<StreamV2> },
+  streamId: `0x${string}`,
+  sleep: (ms: number) => Promise<void>,
+): Promise<StreamV2 | null> {
+  let last: StreamV2 | null = 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;
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,56 @@
+import { attesterDisclosure } from "../attesters.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { usageError } from "../errors.js";
+import {
+  readStreamReport,
+  streamReportJson,
+  streamReportRows,
+} from "../status.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+export const statusCommand: CommandSpec = {
+  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: CommandContext): Promise<void> {
+    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.",
+      );
+    }
+  },
+};