@absol-labs/agent 0.9.0 → 0.10.0

package/src/cli/commands/open.ts

@@ -0,0 +1,331 @@
+import { MandateDeniedError } from "../../sdk/client.js";
+import { booleanFlag, requiredStringFlag, stringFlag } from "../args.js";
+import {
+  formatDuration,
+  formatUsdc,
+  parseAmountUnits,
+  parseDurationSeconds,
+  parseUsdcAmount,
+} from "../amounts.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { CliError, configError } from "../errors.js";
+import { cliMandateCaps, signCliMandate } from "../mandate.js";
+import { assertCanFundStream, assertCanPayGas } from "../preflight.js";
+import {
+  optionalCliWallet,
+  resolveCliWallet,
+  PRIVATE_KEY_ENV,
+} from "../wallet.js";
+import { resolveListing } from "../listings.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+export const openCommand: CommandSpec = {
+  name: "open",
+  summary: "Hire a verified service: escrow USDC into a metered stream",
+  usage:
+    "metrik open --service <serviceRef> --rate <usdc/s> --budget <usdc> --duration <seconds> [--units atomic] [--dry-run]",
+  flags: [
+    "service",
+    "rate",
+    "budget",
+    "duration",
+    "units",
+    "operator",
+    "dry-run",
+  ],
+  signs: true,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out, deps } = context;
+    const units = parseAmountUnits(stringFlag(args, "units"));
+    const serviceRef = parseBytes32(
+      requiredStringFlag(args, "service"),
+      "--service",
+    );
+    const budgetUsdc = parseUsdcAmount(
+      requiredStringFlag(args, "budget"),
+      units,
+      "budget",
+    );
+    const ratePerSecondUsdc = parseUsdcAmount(
+      requiredStringFlag(args, "rate"),
+      units,
+      "rate",
+    );
+    const durationSeconds = parseDurationSeconds(
+      requiredStringFlag(args, "duration"),
+    );
+    const dryRun = booleanFlag(args, "dry-run");
+
+    if (budgetUsdc <= 0n || ratePerSecondUsdc <= 0n) {
+      throw new CliError("--budget and --rate must both be greater than zero", {
+        exitCode: 2,
+      });
+    }
+    const maxSpend = ratePerSecondUsdc * BigInt(durationSeconds);
+    if (maxSpend > budgetUsdc) {
+      out.note(
+        `note: --rate x --duration (${formatUsdc(maxSpend)}) exceeds --budget; accrual is capped at the deposit and the stream simply runs out of budget before it expires.`,
+      );
+    }
+
+    // `--dry-run` broadcasts nothing, so it does NOT require a key: it is the
+    // look-before-you-leap path, and the person most in need of it is exactly
+    // the one who has not funded a wallet yet. Without a key the preview prints
+    // the intended call and says which parts (allowance, simulation, mandate
+    // signature) could not be produced, rather than inventing them.
+    const wallet = dryRun
+      ? await optionalCliWallet(env, { note: out.note })
+      : await resolveCliWallet(env, { note: out.note });
+    const account = wallet?.account ?? null;
+    const read = deps.createReadClient(config);
+    await assertTestnetRpc(config, () => read.getChainId());
+    if (account !== null && !dryRun) {
+      // Both balances, before anything is signed. Gas first: a wallet with no
+      // ETH cannot send the approval that the USDC check exists to protect.
+      await assertCanPayGas(read, account.address);
+      await assertCanFundStream(read, account.address, budgetUsdc);
+    }
+
+    const operatorOverride = stringFlag(args, "operator");
+    const listing = await resolveListing(context, serviceRef, {
+      required: operatorOverride === undefined,
+    });
+    const operator = (operatorOverride ?? listing?.operator) as
+      | `0x${string}`
+      | undefined;
+    if (operator === undefined) {
+      throw configError(
+        `serviceRef ${serviceRef} is not in the registry and no --operator was given`,
+        "run `metrik discover` to find a listed service, or pass --operator explicitly.",
+      );
+    }
+
+    const spend = { operator, budgetUsdc, ratePerSecondUsdc, durationSeconds };
+    const mandate =
+      account === null
+        ? null
+        : await signCliMandate(account, spend, {
+            chainId: config.chainId,
+            env,
+          });
+    const mandateCaps = cliMandateCaps(spend, env);
+
+    const write = deps.createWriteClient(config, account);
+    const hire = {
+      operator,
+      serviceRef,
+      budgetUsdc,
+      ratePerSecond: ratePerSecondUsdc,
+      maxDurationSeconds: durationSeconds,
+    };
+
+    if (dryRun) {
+      const preview = await write.buildHireTx(hire);
+      // A dry run simulates `openStream` from the CURRENT chain state, which
+      // does not include the USDC approval the real command sends first. So the
+      // simulation reverts on the allowance every time the allowance is not
+      // already in place — which, on a first hire, is always. Reporting that as
+      // `simulationError` made the one command meant to build confidence
+      // predict failure on first use. It is a known ordering step, not a fault.
+      const approvalBlocksSimulation = isApprovalOrdering(preview);
+      // Reported, never enforced: a dry run broadcasts nothing, so an
+      // underfunded wallet is information here, not a refusal. The same read
+      // IS a gate on the real path (`assertCanFundStream` above).
+      const usdcBalance =
+        account === null
+          ? null
+          : await read.usdcBalance(account.address).catch(() => null);
+      out.result({
+        dryRun: true,
+        buyer: account?.address ?? null,
+        operator,
+        serviceRef,
+        budgetUsdc,
+        ratePerSecondUsdc,
+        durationSeconds,
+        mandateSource: mandateCaps.source,
+        mandateSigned: mandate !== null,
+        to: preview.to,
+        data: preview.data,
+        chainId: preview.chainId,
+        approval: {
+          required: preview.approval.required,
+          amount: preview.approval.amount,
+          spender: preview.approval.spender,
+          token: preview.approval.token,
+        },
+        usdcBalance,
+        usdcSufficient: usdcBalance === null ? null : usdcBalance >= budgetUsdc,
+        simulatedStreamId: preview.simulatedStreamId,
+        // Mutually exclusive by construction: an allowance-ordering revert is
+        // reported as `simulationPendingApproval`, never as an error, so a
+        // script branching on `simulationError` does not treat the expected
+        // first-hire path as a failure.
+        simulationPendingApproval: approvalBlocksSimulation,
+        ...(preview.simulationError === undefined || approvalBlocksSimulation
+          ? {}
+          : { simulationError: preview.simulationError }),
+      });
+      out.print("Dry run — nothing was broadcast.");
+      out.table([
+        [
+          "buyer",
+          account?.address ??
+            `unknown (no wallet configured — set ${PRIVATE_KEY_ENV} or the CDP variables to preview from a real address)`,
+        ],
+        ["operator", operator],
+        ["serviceRef", serviceRef],
+        ["budget", formatUsdc(budgetUsdc)],
+        ["rate", `${formatUsdc(ratePerSecondUsdc)} / second`],
+        ["duration", formatDuration(durationSeconds)],
+        [
+          "mandate",
+          mandate === null
+            ? `not signed (no wallet); caps would come from ${mandateCaps.source}`
+            : `self-signed, caps from ${mandateCaps.source}`,
+        ],
+        ["escrow", preview.to],
+        [
+          "usdc balance",
+          usdcBalance === null
+            ? "unread (no wallet configured)"
+            : usdcBalance >= budgetUsdc
+              ? `${formatUsdc(usdcBalance)} (covers the budget)`
+              : `${formatUsdc(usdcBalance)} — SHORT of the ${formatUsdc(budgetUsdc)} budget; a real open would be refused`,
+        ],
+        [
+          "usdc approval",
+          preview.approval.required === null
+            ? `${formatUsdc(preview.approval.amount)} (allowance unread)`
+            : preview.approval.required
+              ? `${formatUsdc(preview.approval.amount)} (required)`
+              : "already sufficient",
+        ],
+        [
+          "simulated streamId",
+          preview.simulatedStreamId ??
+            (approvalBlocksSimulation
+              ? "not simulated yet — the bounded USDC approval above is sent FIRST by a real open, and the escrow cannot pull the deposit until it lands. Expected on a first hire, not a failure."
+              : `unavailable (${preview.simulationError ?? "simulation did not run"})`),
+        ],
+      ]);
+      out.print("");
+      out.print(METERING_NOTE);
+      return;
+    }
+
+    out.note(
+      `opening a stream on chain ${config.chainId} for ${formatUsdc(budgetUsdc)} …`,
+    );
+    // Unreachable without a wallet: `resolveCliWallet` above throws when the
+    // command is not a dry run. The narrowing keeps that a type-level fact.
+    if (account === null || mandate === null) {
+      throw configError(
+        "this command signs a transaction and needs a wallet, and none was resolved",
+      );
+    }
+
+    let result;
+    try {
+      result = await write.openVerifiedStream({
+        operator,
+        serviceRef,
+        budgetUsdc,
+        ratePerSecondUsdc,
+        maxDurationSeconds: durationSeconds,
+        signedMandate: mandate.signed,
+        spentSoFarUsdc: 0n,
+        nowSeconds: deps.nowSeconds(),
+      });
+    } catch (error) {
+      if (error instanceof MandateDeniedError) {
+        throw new CliError(`spend mandate denied this hire: ${error.reason}`, {
+          exitCode: 3,
+          hint:
+            mandateCaps.source === "env"
+              ? "the requested hire exceeds your METRIK_AGENT_MANDATE_* ceiling."
+              : "the hire does not satisfy the mandate signed for it.",
+          cause: error,
+        });
+      }
+      throw error;
+    }
+
+    out.result({
+      streamId: result.streamId,
+      txHash: result.txHash,
+      approveTxHash: result.approveTxHash,
+      buyer: account.address,
+      operator,
+      serviceRef,
+      budgetUsdc,
+      ratePerSecondUsdc,
+      durationSeconds,
+      escrow: result.handle.escrow,
+      chainId: result.handle.chainId,
+    });
+    out.print("Stream opened.");
+    out.table([
+      ["streamId", result.streamId],
+      ["tx", result.txHash],
+      ["approve tx", result.approveTxHash ?? "not needed"],
+      ["buyer", account.address],
+      ["operator", operator],
+      ["budget", formatUsdc(budgetUsdc)],
+      ["rate", `${formatUsdc(ratePerSecondUsdc)} / second`],
+      ["duration", formatDuration(durationSeconds)],
+    ]);
+    out.print("");
+    out.print(METERING_NOTE);
+    out.print("");
+    out.print(`Next:  metrik status ${result.streamId}`);
+  },
+};
+
+/**
+ * What the buyer is actually paying for.
+ *
+ * A live acceptance run made ONE `invoke` call and paid for 302 seconds, which
+ * is exactly the design — and exactly what nothing in the CLI said. "Pay for
+ * verified delivery" reads as "pay for delivery TO ME", so a buyer expects
+ * per-call billing and gets a rental meter. The meter runs on the oracle's
+ * probes of the endpoint, not on the buyer's own requests; one call and a
+ * thousand calls cost the same second.
+ */
+const METERING_NOTE =
+  "How you are billed: this is TIME-metered rental of an endpoint the oracle keeps probing — not per-call billing. The meter runs on verified availability, so it charges the same whether you send one request or a thousand, and it keeps charging while you send none. `metrik close <streamId>` stops the clock; nothing else does.";
+
+/**
+ * Shapes that mean "the spender's allowance is too small", across the OpenZeppelin
+ * string revert and the ERC-6093 custom error. Matched as phrases, never on the
+ * bare word `allowance`: the no-wallet preview reports `no account configured —
+ * allowance and simulation skipped`, which contains the word and is a COMPLETELY
+ * different fact. Excusing that as "an approval will be sent first" would state
+ * a reason the CLI does not have.
+ */
+const ALLOWANCE_SHORTFALL: readonly RegExp[] = [
+  /transfer amount exceeds allowance/i,
+  /insufficient allowance/i,
+  /ERC20InsufficientAllowance/,
+];
+
+/**
+ * True when the dry run's simulation failed ONLY because the USDC approval a
+ * real open sends first has not been sent.
+ *
+ * Deliberately narrow: it requires an actual REVERT, whose reason is an
+ * allowance shortfall, on a preview that says an approval is (or may be)
+ * needed. Anything else keeps being reported as a simulation error, because
+ * every other failure is a real one the buyer should see before spending.
+ */
+function isApprovalOrdering(preview: {
+  readonly simulationError?: string | undefined;
+  readonly simulatedStreamId?: string | null | undefined;
+  readonly approval: { readonly required: boolean | null };
+}): boolean {
+  const error = preview.simulationError;
+  if (error === undefined || preview.simulatedStreamId != null) return false;
+  if (preview.approval.required === false) return false;
+  if (!/\brevert(ed)?\b/i.test(error)) return false;
+  return ALLOWANCE_SHORTFALL.some((pattern) => pattern.test(error));
+}

package/src/cli/commands/reclaim-unverified.ts

@@ -0,0 +1,206 @@
+import { booleanFlag } from "../args.js";
+import { formatDuration, formatUsdc } from "../amounts.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { CliError, usageError } from "../errors.js";
+import {
+  escapeHatchWindow,
+  formatTimestamp,
+  readChainNow,
+  type EscapeHatchWindow,
+} 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 } from "../deps.js";
+
+/**
+ * The acknowledgement this command will not run without.
+ *
+ * `reclaim-unverified` is deliberately BOTH a command of its own and a command
+ * that refuses to run on its arguments alone:
+ *
+ *  - it is not `metrik reclaim --unverified`, because that is one token away
+ *    from the safe path, sits in the same command's flag list (so a script that
+ *    templates flags can pick it up), and shell completion offers it beside
+ *    `--close-first`;
+ *  - and the flag below has no default and no `--no-` form, so the only way to
+ *    reach the transaction is to type a phrase that says what it costs.
+ *
+ * Nothing about this command is reachable by fat-fingering the ordinary one.
+ */
+const ACKNOWLEDGEMENT_FLAG = "forfeit-unclaimed";
+
+/**
+ * Exactly what the escrow does, so the warning does not have to be trusted.
+ *
+ * `StreamEscrowV2.reclaimUnverified` sets `entitlement = stream.claimedCumulative`
+ * and then `settledCumulative = entitlement; deposit = entitlement`. The
+ * operator's own redemption path caps at that value once the stream is
+ * reclaimed (`if (stream.reclaimed && payableCumulative > stream.settledCumulative)
+ * payableCumulative = stream.settledCumulative;`) and then requires
+ * `payableCumulative > stream.claimedCumulative` — which can never hold again.
+ * Every voucher earned but not yet redeemed on-chain is therefore forfeit
+ * PERMANENTLY, and its value is paid to the buyer.
+ */
+const FORFEIT_WARNING = [
+  "This pays you deposit - claimedCumulative with NO proof and NO oracle.",
+  "What it costs the operator: everything they verifiably earned but have not yet",
+  "claimed on-chain is forfeited to you, permanently. The escrow caps their",
+  "entitlement at what they had already claimed, so every later claim reverts",
+  "NothingToClaim(). There is no way to pay it back afterwards.",
+  "",
+  "Use it when the oracle cannot give you a proof. Where `metrik reclaim` works,",
+  "use that instead — it settles the operator honestly and pays you the rest.",
+];
+
+export const reclaimUnverifiedCommand: CommandSpec = {
+  name: "reclaim-unverified",
+  summary:
+    "Escape hatch: reclaim with no proof when the oracle cannot give you one",
+  usage: `metrik reclaim-unverified <streamId> --${ACKNOWLEDGEMENT_FLAG}`,
+  flags: [ACKNOWLEDGEMENT_FLAG],
+  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-unverified requires a <streamId>");
+    }
+    const streamId = parseBytes32(streamIdArg, "<streamId>");
+
+    if (!booleanFlag(args, ACKNOWLEDGEMENT_FLAG)) {
+      throw usageError(
+        `metrik reclaim-unverified forfeits the operator's unclaimed earnings, so it requires --${ACKNOWLEDGEMENT_FLAG}`,
+        [
+          ...FORFEIT_WARNING,
+          "",
+          `Re-run with --${ACKNOWLEDGEMENT_FLAG} once that is what you intend.`,
+        ].join("\n  "),
+      );
+    }
+
+    const { account } = await resolveCliWallet(env, { note: out.note });
+    const read = deps.createReadClient(config);
+    await assertTestnetRpc(config, () => read.getChainId());
+    await assertCanPayGas(read, account.address);
+
+    const stream = await read.getStreamV2(streamId);
+    if (stream.reclaimed) {
+      throw new CliError(
+        "this stream has already been reclaimed — there is nothing left to take back",
+        {
+          exitCode: 4,
+          hint: `check where it went:  metrik status ${streamId}`,
+        },
+      );
+    }
+
+    // Readiness is computed against the chain's clock, because the escrow
+    // compares against `block.timestamp`. Spending gas on a guaranteed
+    // `EscapeHatchNotReady()` revert is exactly the failure this gate exists to
+    // prevent.
+    const grace = await readEscapeGrace(read);
+    const now = await readChainNow(read, deps.nowSeconds());
+    const window = escapeHatchWindow(stream, grace, now.seconds);
+    if (!window.ready) {
+      throw notReady(streamId, window, now.source);
+    }
+
+    // The amount at stake, when it is knowable. It usually is not: the reason to
+    // be on this path at all is that the oracle is not answering, and the
+    // operator's redeemable balance is derived from the oracle's proof.
+    const forfeit = await readForfeitEstimate(read, streamId);
+    out.note("");
+    for (const line of FORFEIT_WARNING) out.note(line);
+    out.note(
+      forfeit === null
+        ? "Operator balance at stake: unknown — the oracle did not answer, which is the situation this command is for."
+        : `Operator balance at stake right now: ${formatUsdc(forfeit)} (net of protocol fee). This transaction forfeits it.`,
+    );
+    out.note("");
+
+    const write = deps.createWriteClient(config, account);
+    const result = await write.reclaimUnverifiedStream({
+      streamId,
+      signedMandate: await signRecoveryMandate(account, config.chainId),
+      spentSoFarUsdc: 0n,
+      nowSeconds: deps.nowSeconds(),
+    });
+
+    out.result({
+      streamId,
+      txHash: result.txHash,
+      unverified: true,
+      escapeHatchReadyAt: window.readyAt,
+      escapeGraceSeconds: window.graceSeconds,
+      forfeitedOperatorClaimable: forfeit,
+    });
+    out.print("Reclaimed without a proof.");
+    out.table([
+      ["streamId", streamId],
+      ["tx", result.txHash],
+      ["escape hatch opened", formatTimestamp(window.readyAt)],
+      [
+        "operator earnings forfeited",
+        forfeit === null ? "unknown (oracle unreachable)" : formatUsdc(forfeit),
+      ],
+    ]);
+  },
+};
+
+function notReady(
+  streamId: `0x${string}`,
+  window: EscapeHatchWindow,
+  clock: "chain" | "local",
+): CliError {
+  return new CliError(
+    `the no-proof escape hatch is not open yet: it unlocks at ${formatTimestamp(
+      window.readyAt,
+    )}, in ${formatDuration(window.secondsRemaining)}`,
+    {
+      exitCode: 4,
+      hint: [
+        `The escrow gates this on expiresAt + escapeGraceSeconds (${window.graceSeconds}s), never on when you closed${
+          clock === "chain"
+            ? ""
+            : " — and the chain's own clock could not be read, so this is your machine's"
+        }.`,
+        `Until then the honest path is the proof-based one:  metrik reclaim ${streamId}`,
+      ].join(" "),
+    },
+  );
+}
+
+/** `escapeGraceSeconds` is a public immutable; failing to read it is fatal here. */
+async function readEscapeGrace(read: CliReadClient): Promise<number> {
+  try {
+    return await read.escapeGraceSeconds();
+  } catch (error) {
+    throw new CliError(
+      "could not read escapeGraceSeconds from the escrow, so whether the escape hatch is open is unknown",
+      {
+        exitCode: 4,
+        hint: "this command refuses to broadcast on a guess: retry when the RPC endpoint answers.",
+        cause: error,
+      },
+    );
+  }
+}
+
+/**
+ * What the operator could redeem right now, i.e. what this transaction takes
+ * from them. `null` when the oracle cannot be reached — which is the normal case
+ * on this path and is reported as unknown rather than as zero.
+ */
+async function readForfeitEstimate(
+  read: CliReadClient,
+  streamId: `0x${string}`,
+): Promise<bigint | null> {
+  try {
+    const proof = await read.checkpointProof(streamId);
+    return await read.claimableForV2(streamId, proof.cumulativeAmount);
+  } catch {
+    return null;
+  }
+}