@absol-labs/agent 0.9.1 → 0.11.0

package/dist/cli/privy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privy.d.ts","sourceRoot":"","sources":["../../src/cli/privy.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,OAAO,EACZ,KAAK,SAAS,EACf,MAAM,MAAM,CAAC;AAEd,OAAO,EAQL,KAAK,+BAA+B,EAErC,MAAM,gCAAgC,CAAC;AAQxC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAExE,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,kCAAkC,CAAC;AACpE,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,kCAAkC,CAAC;AACpE,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,qCAAqC,CAAC;AAC1E,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,+BAA+B,CAAC;AAC9D,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,4KAMjB,CAAC;AAEX,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,2IAKzB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,uFAAuF;AACvF,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAyC3B;AAUD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,4BAA4B;IAC3C,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,+BAA+B,CAAC;IACjD,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CA8CxC"}

package/dist/cli/privy.js

@@ -0,0 +1,230 @@
+import { custom, isAddress, getAddress, } from "viem";
+import { AutonomousWalletError, EncryptedFileCredentialStore, HttpAutonomousWalletBroker, METRIK_AUTONOMOUS_WALLET_BROKER_URL, METRIK_WALLET_ENCRYPTION_KEY_ENV, createAutonomousWalletProvider, createDefaultAutonomousWalletStore, } from "../wallet/autonomous-wallet.js";
+import { createPrivySessionProvider } from "../wallet/privy-session-provider.js";
+import { createPrivyEmbeddedAccount, } from "../wallet/provider.js";
+import { configError } from "./errors.js";
+/** The store key naming the agent-owned wallet in the host credential store. */
+export const PRIVY_WALLET_KEY_ENV = "METRIK_AGENT_PRIVY_WALLET_KEY";
+/** Broker base URL. Optional for `autonomous`, REQUIRED for `session`. */
+export const PRIVY_BROKER_URL_ENV = "METRIK_AGENT_PRIVY_BROKER_URL";
+/** A scoped session token minted by the broker's `POST /v1/sessions`. */
+export const PRIVY_SESSION_TOKEN_ENV = "METRIK_AGENT_PRIVY_SESSION_TOKEN";
+/** The embedded wallet address the session is bound to. */
+export const PRIVY_ADDRESS_ENV = "METRIK_AGENT_PRIVY_ADDRESS";
+/** The PUBLIC Privy app id. Not a secret — the broker serves it at `/v1/config`. */
+export const PRIVY_APP_ID_ENV = "METRIK_AGENT_PRIVY_APP_ID";
+/** Every variable either Privy shape reads. Named in errors, never printed. */
+export const PRIVY_ENV_VARS = [
+    PRIVY_WALLET_KEY_ENV,
+    PRIVY_BROKER_URL_ENV,
+    PRIVY_SESSION_TOKEN_ENV,
+    PRIVY_ADDRESS_ENV,
+    PRIVY_APP_ID_ENV,
+];
+/** The variables the user-owned session shape needs, all of them. */
+export const PRIVY_SESSION_ENV_VARS = [
+    PRIVY_BROKER_URL_ENV,
+    PRIVY_SESSION_TOKEN_ENV,
+    PRIVY_ADDRESS_ENV,
+    PRIVY_APP_ID_ENV,
+];
+/** Reads a broker's public policy. No credential is sent; nothing secret is served. */
+export async function fetchPrivySpendPolicy(brokerUrl, fetchImpl = fetch) {
+    const base = brokerUrl.replace(/\/$/, "");
+    const response = await fetchImpl(`${base}/v1/config`, {
+        headers: { accept: "application/json" },
+    }).catch((error) => {
+        throw configError(`the Privy broker at ${base} did not answer its public policy`, `${describe(error)} The CLI reads GET /v1/config to know the ceiling your wallet is capped at; without it, it cannot tell you before broadcasting whether a hire fits.`);
+    });
+    const body = (await response.json().catch(() => null));
+    if (!response.ok || body === null) {
+        throw configError(`the Privy broker at ${base} rejected the public policy read (${response.status})`);
+    }
+    const chainId = Number(body.chainId);
+    const maxTotalUsdc = asBigint(body.maxTotalUsdcAtomic);
+    const maxRatePerSecondUsdc = asBigint(body.maxRatePerSecondAtomic);
+    const maxDurationSeconds = Number(body.maxDurationSeconds);
+    if (!Number.isSafeInteger(chainId) ||
+        maxTotalUsdc === null ||
+        maxRatePerSecondUsdc === null ||
+        !Number.isSafeInteger(maxDurationSeconds)) {
+        throw configError(`the Privy broker at ${base} returned a policy this CLI cannot read`, "expected chainId, maxTotalUsdcAtomic, maxRatePerSecondAtomic and maxDurationSeconds.");
+    }
+    return {
+        brokerUrl: base,
+        chainId,
+        maxTotalUsdc,
+        maxRatePerSecondUsdc,
+        maxDurationSeconds,
+    };
+}
+function asBigint(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number" && Number.isSafeInteger(value))
+        return BigInt(value);
+    if (typeof value === "string" && /^[0-9]+$/.test(value))
+        return BigInt(value);
+    return null;
+}
+/**
+ * Resolves a Privy wallet from the environment, or `null` when no Privy
+ * variable is set at all.
+ *
+ * A PARTIALLY configured Privy setup is an error, not a `null` — "you set the
+ * session token but not the address" and "you configured no Privy wallet" are
+ * different facts, and rendering the first as the second sends the reader
+ * looking in the wrong place. This mirrors the CDP path exactly.
+ */
+export async function resolvePrivyCliWallet(env, options = {}) {
+    const walletKey = read(env, PRIVY_WALLET_KEY_ENV);
+    const brokerUrl = read(env, PRIVY_BROKER_URL_ENV);
+    const sessionToken = read(env, PRIVY_SESSION_TOKEN_ENV);
+    const address = read(env, PRIVY_ADDRESS_ENV);
+    const appId = read(env, PRIVY_APP_ID_ENV);
+    if (walletKey === null &&
+        brokerUrl === null &&
+        sessionToken === null &&
+        address === null &&
+        appId === null) {
+        return null;
+    }
+    if (walletKey !== null) {
+        if (sessionToken !== null) {
+            options.note?.(`warning: both ${PRIVY_WALLET_KEY_ENV} and ${PRIVY_SESSION_TOKEN_ENV} are set; using the agent-owned wallet named by ${PRIVY_WALLET_KEY_ENV}. Unset it to sign with the session token.`);
+        }
+        return await resolveAutonomous(walletKey, brokerUrl, env, options);
+    }
+    const missing = PRIVY_SESSION_ENV_VARS.filter((name) => read(env, name) === null);
+    if (missing.length > 0) {
+        throw configError(`the Privy wallet is partially configured: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not set`, `a Privy wallet is configured one of two ways: set ${PRIVY_WALLET_KEY_ENV} to the store key of an agent-owned wallet you provisioned with provisionMetrikAutonomousWallet(), or set all of ${PRIVY_SESSION_ENV_VARS.join(", ")} for a broker session. Set the missing one${missing.length === 1 ? "" : "s"}, or unset the others to use a different wallet.`);
+    }
+    return resolveSession({
+        brokerUrl: brokerUrl,
+        sessionToken: sessionToken,
+        address: address,
+        appId: appId,
+        ...(options.rpcUrl === undefined ? {} : { rpcUrl: options.rpcUrl }),
+        ...(options.fetchImpl === undefined
+            ? {}
+            : { fetchImpl: options.fetchImpl }),
+    });
+}
+async function resolveAutonomous(walletKey, brokerUrlOverride, env, options) {
+    const store = options.store ?? selectCredentialStore(env);
+    let record;
+    try {
+        record = await store.load(walletKey);
+    }
+    catch (error) {
+        throw configError(`could not read the agent-owned Privy wallet "${walletKey}" from the credential store`, `${describe(error)} On a headless host the OS credential store is often unavailable; set ${METRIK_WALLET_ENCRYPTION_KEY_ENV} to use the encrypted-file store instead.`);
+    }
+    if (record === null) {
+        throw configError(`no agent-owned Privy wallet is stored under the key "${walletKey}"`, `the CLI never provisions a wallet on your behalf — a fund-moving command is the wrong place to mint one. Provision it once with provisionMetrikAutonomousWallet({ storeKey: "${walletKey}" }) (see docs/autonomous-privy-wallet.md), then re-run this command.`);
+    }
+    if (record.walletId === undefined || record.address === undefined) {
+        throw configError(`the agent-owned Privy wallet "${walletKey}" was never finished provisioning`, "the local key exists but the broker never returned a wallet id and address. Re-run provisionMetrikAutonomousWallet() with the same store key — it retries with the same key and idempotency nonce.");
+    }
+    const brokerUrl = brokerUrlOverride ?? record.brokerUrl;
+    if (brokerUrlOverride !== null && brokerUrlOverride !== record.brokerUrl) {
+        options.note?.(`note: ${PRIVY_BROKER_URL_ENV} (${brokerUrlOverride}) overrides the broker this wallet was provisioned against (${record.brokerUrl}); only a broker holding this wallet's Privy authorization key can authorize it.`);
+    }
+    let broker;
+    try {
+        broker = new HttpAutonomousWalletBroker(brokerUrl, {
+            ...(options.fetchImpl === undefined
+                ? {}
+                : { fetchImpl: options.fetchImpl }),
+        });
+    }
+    catch (error) {
+        throw configError(`the autonomous wallet broker URL is not usable: ${describe(error)}`, `set ${PRIVY_BROKER_URL_ENV} to an HTTPS broker you control (the default is ${METRIK_AUTONOMOUS_WALLET_BROKER_URL}).`);
+    }
+    const provider = createAutonomousWalletProvider({
+        wallet: record,
+        broker,
+        ...(options.rpcUrl === undefined ? {} : { rpcUrl: options.rpcUrl }),
+        ...(options.fetchImpl === undefined
+            ? {}
+            : { fetchImpl: options.fetchImpl }),
+    });
+    const account = await embeddedAccount(provider, record.appId, record.address);
+    return {
+        source: "privy-autonomous",
+        account,
+        transport: custom(provider),
+        description: `${record.address} (agent-owned Privy wallet "${walletKey}" via ${brokerUrl})`,
+        readSpendPolicy: async () => await fetchPrivySpendPolicy(brokerUrl, options.fetchImpl ?? globalThis.fetch.bind(globalThis)),
+    };
+}
+function resolveSession(input) {
+    if (!isAddress(input.address)) {
+        throw configError(`${PRIVY_ADDRESS_ENV} must be a 0x-prefixed 20-byte address`);
+    }
+    const address = getAddress(input.address);
+    let provider;
+    try {
+        provider = createPrivySessionProvider({
+            brokerUrl: input.brokerUrl,
+            sessionToken: input.sessionToken,
+            address,
+            ...(input.rpcUrl === undefined ? {} : { rpcUrl: input.rpcUrl }),
+            ...(input.fetchImpl === undefined ? {} : { fetchImpl: input.fetchImpl }),
+        });
+    }
+    catch (error) {
+        throw configError(`the Privy session broker URL is not usable: ${describe(error)}`, `set ${PRIVY_BROKER_URL_ENV} to the HTTPS broker that minted ${PRIVY_SESSION_TOKEN_ENV}. A session token is only valid against the broker that issued it.`);
+    }
+    return embeddedAccount(provider, input.appId, address).then((account) => ({
+        source: "privy-session",
+        account,
+        transport: custom(provider),
+        description: `${address} (Privy broker session via ${input.brokerUrl})`,
+        readSpendPolicy: async () => await fetchPrivySpendPolicy(input.brokerUrl, input.fetchImpl ?? globalThis.fetch.bind(globalThis)),
+    }));
+}
+/**
+ * Wraps a provider in the package's existing Privy EOA adapter.
+ *
+ * Both CLI providers answer `eth_chainId` and `eth_accounts` locally, so the
+ * adapter's session assertion is a pure local consistency check here — no
+ * network call happens while the wallet is being resolved.
+ */
+async function embeddedAccount(provider, appId, address) {
+    try {
+        return await createPrivyEmbeddedAccount({
+            appId,
+            address,
+            provider,
+            chainId: 84532,
+        });
+    }
+    catch (error) {
+        throw configError(`the Privy wallet could not be prepared: ${describe(error)}`, `check ${PRIVY_ENV_VARS.join(", ")}. Metrik Privy wallets are Base Sepolia (84532) only.`);
+    }
+}
+/**
+ * The credential store the autonomous wallet was provisioned into.
+ *
+ * Selection mirrors `provisionMetrikAutonomousWallet`'s documented options:
+ * setting `METRIK_WALLET_ENCRYPTION_KEY` means the encrypted-file store (the
+ * durable option for a headless host), otherwise the host OS store. Picking a
+ * different store than provisioning used simply finds no record, and the
+ * "no wallet is stored under this key" error above says so.
+ */
+function selectCredentialStore(env) {
+    if (read(env, METRIK_WALLET_ENCRYPTION_KEY_ENV) !== null) {
+        return new EncryptedFileCredentialStore({ env });
+    }
+    return createDefaultAutonomousWalletStore();
+}
+function read(env, name) {
+    const value = env[name];
+    return value === undefined || value.length === 0 ? null : value;
+}
+function describe(error) {
+    if (error instanceof AutonomousWalletError)
+        return error.message;
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=privy.js.map

package/dist/cli/privy.js.map

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

package/dist/cli/progress.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A heartbeat on stderr for commands that can take a while.
+ *
+ * A live acceptance run saw `close` take 8s once and 142s the next time, and
+ * `status` calls run past two minutes with nothing on screen. With no output at
+ * all, a slow RPC and a wedged process look identical, and the only safe reading
+ * of that ambiguity — on a command that may have already broadcast a
+ * transaction — is the expensive one: wait, or kill it and risk double-sending.
+ *
+ * So the CLI narrates. Not progress towards a known total (there isn't one), but
+ * proof of life plus elapsed time, which is what distinguishes "slow" from
+ * "stuck". stderr in BOTH modes, so `--json` stdout stays a single parseable
+ * document.
+ */
+export interface Heartbeat {
+    /** Stops the ticker. Safe to call more than once. */
+    readonly stop: () => void;
+}
+/** Silence before the first tick — below this, a command is simply fast. */
+export declare const HEARTBEAT_DELAY_MS = 8000;
+/** Gap between ticks once it has started. */
+export declare const HEARTBEAT_INTERVAL_MS = 10000;
+export interface HeartbeatOptions {
+    readonly delayMs?: number;
+    readonly intervalMs?: number;
+    /** Injectable for tests; defaults to the global timers. */
+    readonly setTimer?: typeof setTimeout;
+    readonly clearTimer?: typeof clearTimeout;
+    readonly now?: () => number;
+}
+/**
+ * Start narrating `label`. Nothing is printed unless the work outlasts
+ * `delayMs`, so a fast command is silent and a slow one is legible.
+ */
+export declare function startHeartbeat(note: (line: string) => void, label: string, options?: HeartbeatOptions): Heartbeat;
+//# sourceMappingURL=progress.d.ts.map

package/dist/cli/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/cli/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,SAAS;IACxB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AACxC,6CAA6C;AAC7C,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,UAAU,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,YAAY,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CAiCX"}

package/dist/cli/progress.js

@@ -0,0 +1,40 @@
+/** Silence before the first tick — below this, a command is simply fast. */
+export const HEARTBEAT_DELAY_MS = 8_000;
+/** Gap between ticks once it has started. */
+export const HEARTBEAT_INTERVAL_MS = 10_000;
+/**
+ * Start narrating `label`. Nothing is printed unless the work outlasts
+ * `delayMs`, so a fast command is silent and a slow one is legible.
+ */
+export function startHeartbeat(note, label, options = {}) {
+    const delayMs = options.delayMs ?? HEARTBEAT_DELAY_MS;
+    const intervalMs = options.intervalMs ?? HEARTBEAT_INTERVAL_MS;
+    const setTimer = options.setTimer ?? setTimeout;
+    const clearTimer = options.clearTimer ?? clearTimeout;
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    let timer;
+    let stopped = false;
+    const tick = () => {
+        if (stopped)
+            return;
+        const elapsed = Math.round((now() - startedAt) / 1000);
+        note(`… still working: ${label} (${elapsed}s elapsed). Slow RPC or oracle, not a hang — nothing is retried silently.`);
+        schedule(intervalMs);
+    };
+    const schedule = (ms) => {
+        timer = setTimer(tick, ms);
+        // Never hold the process open on account of the narration.
+        timer.unref?.();
+    };
+    schedule(delayMs);
+    return {
+        stop() {
+            stopped = true;
+            if (timer !== undefined)
+                clearTimer(timer);
+            timer = undefined;
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/cli/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/cli/progress.ts"],"names":[],"mappings":"AAmBA,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AACxC,6CAA6C;AAC7C,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAW5C;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,IAA4B,EAC5B,KAAa,EACb,UAA4B,EAAE;IAE9B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,kBAAkB,CAAC;IACtD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,qBAAqB,CAAC;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,UAAU,CAAC;IAChD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,YAAY,CAAC;IACtD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAEpC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC;IACxB,IAAI,KAAgD,CAAC;IACrD,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,OAAO;YAAE,OAAO;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC;QACvD,IAAI,CACF,oBAAoB,KAAK,KAAK,OAAO,2EAA2E,CACjH,CAAC;QACF,QAAQ,CAAC,UAAU,CAAC,CAAC;IACvB,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAQ,EAAE;QACpC,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC3B,2DAA2D;QAC1D,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAC;IAC9C,CAAC,CAAC;IACF,QAAQ,CAAC,OAAO,CAAC,CAAC;IAElB,OAAO;QACL,IAAI;YACF,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,KAAK,KAAK,SAAS;gBAAE,UAAU,CAAC,KAAK,CAAC,CAAC;YAC3C,KAAK,GAAG,SAAS,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/run.d.ts

@@ -0,0 +1,25 @@
+import { type CliStreams } from "./output.js";
+import { type CliDependencies } from "./deps.js";
+import type { CommandSpec } from "./context.js";
+/**
+ * The command surface, in the order the product loop runs:
+ * discover -> open -> invoke -> watch/status -> close -> reclaim, then the
+ * operator's own redemption (`claim`) and the buyer's last-resort exit
+ * (`reclaim-unverified`). `streams` (which of them are mine?) sits inside that
+ * loop; `mcp` (run the same loop from an MCP host) sits after it.
+ */
+export declare const COMMANDS: readonly CommandSpec[];
+export interface RunCliOptions {
+    readonly argv: readonly string[];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly streams?: CliStreams;
+    readonly deps?: CliDependencies;
+}
+/**
+ * Runs one CLI invocation and returns the process exit code. Pure in its
+ * inputs: argv, env, output sinks and side-effecting dependencies are all
+ * injected, so the whole surface is testable without a key or an RPC.
+ */
+export declare function runCli(options: RunCliOptions): Promise<number>;
+export declare function renderHelp(commandName?: string): string;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAQA,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAGzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAchD;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,WAAW,EAY1C,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAiEpE;AAqBD,wBAAgB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CA8DvD"}

package/dist/cli/run.js

@@ -0,0 +1,173 @@
+import { assertKnownFlags, booleanFlag, parseArgs } from "./args.js";
+import { CONFIG_FLAGS, GLOBAL_FLAGS, TESTNET_CHAIN_IDS, resolveConfig, } from "./config.js";
+import { CliError, describeError, usageError } from "./errors.js";
+import { createPrinter } from "./output.js";
+import { startHeartbeat } from "./progress.js";
+import { defaultCliDependencies } from "./deps.js";
+import { packageVersion } from "./version.js";
+import { CDP_ENV_VARS, PRIVATE_KEY_ENV } from "./wallet.js";
+import { claimCommand } from "./commands/claim.js";
+import { closeCommand } from "./commands/close.js";
+import { discoverCommand } from "./commands/discover.js";
+import { invokeCommand } from "./commands/invoke.js";
+import { mcpCommand } from "./commands/mcp.js";
+import { openCommand } from "./commands/open.js";
+import { reclaimCommand } from "./commands/reclaim.js";
+import { reclaimUnverifiedCommand } from "./commands/reclaim-unverified.js";
+import { statusCommand } from "./commands/status.js";
+import { streamsCommand } from "./commands/streams.js";
+import { watchCommand } from "./commands/watch.js";
+/**
+ * The command surface, in the order the product loop runs:
+ * discover -> open -> invoke -> watch/status -> close -> reclaim, then the
+ * operator's own redemption (`claim`) and the buyer's last-resort exit
+ * (`reclaim-unverified`). `streams` (which of them are mine?) sits inside that
+ * loop; `mcp` (run the same loop from an MCP host) sits after it.
+ */
+export const COMMANDS = [
+    discoverCommand,
+    openCommand,
+    statusCommand,
+    streamsCommand,
+    watchCommand,
+    invokeCommand,
+    closeCommand,
+    reclaimCommand,
+    reclaimUnverifiedCommand,
+    claimCommand,
+    mcpCommand,
+];
+/**
+ * Runs one CLI invocation and returns the process exit code. Pure in its
+ * inputs: argv, env, output sinks and side-effecting dependencies are all
+ * injected, so the whole surface is testable without a key or an RPC.
+ */
+export async function runCli(options) {
+    const env = options.env ?? process.env;
+    const streams = options.streams ?? {
+        stdout: (line) => process.stdout.write(`${line}\n`),
+        stderr: (line) => process.stderr.write(`${line}\n`),
+    };
+    const deps = options.deps ?? defaultCliDependencies;
+    let json = false;
+    try {
+        const args = parseArgs(options.argv);
+        json = booleanFlag(args, "json");
+        const out = createPrinter(streams, json);
+        // `--version` is checked before the bare-invocation help branch: `metrik
+        // --version` parses to no command at all.
+        if (args.command === "version" || booleanFlag(args, "version")) {
+            streams.stdout(packageVersion());
+            return 0;
+        }
+        if (args.command === null || args.command === "help") {
+            // A misspelled TOP-LEVEL flag must fail like a misspelled per-command one
+            // does. Printing help and exiting 0 tells a script the invocation
+            // succeeded, which is how a typo goes unnoticed.
+            assertKnownFlags(args, [...GLOBAL_FLAGS, "version"]);
+            streams.stdout(renderHelp(args.positionals[0]));
+            return 0;
+        }
+        const command = COMMANDS.find((spec) => spec.name === args.command);
+        if (command === undefined) {
+            throw usageError(`unknown command: ${args.command}`, `commands: ${COMMANDS.map((spec) => spec.name).join(", ")}`);
+        }
+        if (booleanFlag(args, "help")) {
+            streams.stdout(renderHelp(command.name));
+            return 0;
+        }
+        assertKnownFlags(args, [
+            ...GLOBAL_FLAGS,
+            ...CONFIG_FLAGS,
+            ...command.flags,
+        ]);
+        const config = resolveConfig(args, env);
+        // Every command gets the heartbeat, in one place rather than per command:
+        // any of them can be the one waiting on a slow endpoint, and a rule with an
+        // exception is a rule someone forgets to apply to the next command.
+        const heartbeat = startHeartbeat(out.note, `metrik ${command.name}`);
+        try {
+            await command.run({ args, config, env, out, deps });
+        }
+        finally {
+            heartbeat.stop();
+        }
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            emitFailure(streams, json, error.message, error.hint, error.exitCode);
+            return error.exitCode;
+        }
+        emitFailure(streams, json, describeError(error), undefined, 4);
+        return 4;
+    }
+}
+function emitFailure(streams, json, message, hint, exitCode) {
+    if (json) {
+        // The failure goes to stderr even in --json mode so stdout stays either a
+        // result document or nothing at all.
+        streams.stderr(JSON.stringify({ error: message, hint: hint ?? null, exitCode }));
+        return;
+    }
+    streams.stderr(`error: ${message}`);
+    if (hint !== undefined)
+        streams.stderr(`  ${hint}`);
+}
+export function renderHelp(commandName) {
+    const command = COMMANDS.find((spec) => spec.name === commandName);
+    if (command !== undefined) {
+        return [
+            `metrik ${command.name} — ${command.summary}`,
+            "",
+            `Usage: ${command.usage}`,
+            "",
+            command.flags.length === 0
+                ? "Command flags: (none)"
+                : `Command flags: ${command.flags.map((flag) => `--${flag}`).join(" ")}`,
+            `Settlement flags: ${CONFIG_FLAGS.map((flag) => `--${flag}`).join(" ")}`,
+            "Output flags: --json",
+            ...(command.signs
+                ? [
+                    "",
+                    `Broadcasts a transaction. Requires a wallet in the environment: ${PRIVATE_KEY_ENV}, or ${CDP_ENV_VARS.join(" + ")}.`,
+                ]
+                : command.requiresKey === true
+                    ? [
+                        "",
+                        `Broadcasts nothing, but signs an off-chain EIP-712 capability, so it requires a wallet in the environment: ${PRIVATE_KEY_ENV}, or ${CDP_ENV_VARS.join(" + ")}.`,
+                    ]
+                    : []),
+        ].join("\n");
+    }
+    const width = COMMANDS.reduce((max, spec) => Math.max(max, spec.name.length), 0);
+    return [
+        `metrik ${packageVersion()} — pay for verified delivery, metered by the second`,
+        "",
+        "You rent a verified-live endpoint BY TIME, not per call: the oracle probes it and the",
+        "meter runs on availability that verified. One request and a thousand cost the same",
+        "second, and the clock keeps running while you send none. `metrik close` stops it.",
+        "",
+        "Usage: metrik <command> [options]",
+        "",
+        "Commands:",
+        ...COMMANDS.map((spec) => `  ${spec.name.padEnd(width)}  ${spec.summary}${spec.signs ? "  [broadcasts a tx]" : spec.requiresKey === true ? "  [needs a key]" : ""}`),
+        "",
+        "Global flags:",
+        "  --json          machine-readable output on stdout",
+        "  --help          this text, or `metrik <command> --help`",
+        "",
+        "Settlement flags (all default to Metrik's Base Sepolia deployment):",
+        "  --chain-id  --rpc-url  --escrow  --usdc  --oracle-url  --registry-url",
+        "",
+        "Wallet (read from the environment only; never accepted as a flag):",
+        `  ${PRIVATE_KEY_ENV}  a Base Sepolia test key. Checked first.`,
+        `  ${CDP_ENV_VARS.join(", ")}`,
+        "    a Coinbase CDP Server Wallet v2 account. Used when no private key is set.",
+        "  A credential on the command line lands in shell history; these never are.",
+        "",
+        `TESTNET ONLY: this CLI refuses any chain outside ${TESTNET_CHAIN_IDS.join(", ")} (Base Sepolia),`,
+        "and re-checks the chain id the RPC actually serves before signing. There is no override.",
+    ].join("\n");
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAwB,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG5D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAA2B;IAC9C,eAAe;IACf,WAAW;IACX,aAAa;IACb,cAAc;IACd,YAAY;IACZ,aAAa;IACb,YAAY;IACZ,cAAc;IACd,wBAAwB;IACxB,YAAY;IACZ,UAAU;CACX,CAAC;AASF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAsB;IACjD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI;QACjC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;QACnD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;KACpD,CAAC;IACF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,sBAAsB,CAAC;IAEpD,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAEzC,yEAAyE;QACzE,0CAA0C;QAC1C,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;YAC/D,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC;YACjC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YACrD,0EAA0E;YAC1E,kEAAkE;YAClE,iDAAiD;YACjD,gBAAgB,CAAC,IAAI,EAAE,CAAC,GAAG,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;YACrD,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAChD,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,CAAC;QACpE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,UAAU,CACd,oBAAoB,IAAI,CAAC,OAAO,EAAE,EAClC,aAAa,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5D,CAAC;QACJ,CAAC;QACD,IAAI,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;YAC9B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACzC,OAAO,CAAC,CAAC;QACX,CAAC;QAED,gBAAgB,CAAC,IAAI,EAAE;YACrB,GAAG,YAAY;YACf,GAAG,YAAY;YACf,GAAG,OAAO,CAAC,KAAK;SACjB,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACxC,0EAA0E;QAC1E,4EAA4E;QAC5E,oEAAoE;QACpE,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;YAC9B,WAAW,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YACtE,OAAO,KAAK,CAAC,QAAQ,CAAC;QACxB,CAAC;QACD,WAAW,CAAC,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAC/D,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAClB,OAAmB,EACnB,IAAa,EACb,OAAe,EACf,IAAwB,EACxB,QAAgB;IAEhB,IAAI,IAAI,EAAE,CAAC;QACT,0EAA0E;QAC1E,qCAAqC;QACrC,OAAO,CAAC,MAAM,CACZ,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,IAAI,IAAI,EAAE,QAAQ,EAAE,CAAC,CACjE,CAAC;QACF,OAAO;IACT,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;IACpC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,WAAoB;IAC7C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;IACnE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO;YACL,UAAU,OAAO,CAAC,IAAI,MAAM,OAAO,CAAC,OAAO,EAAE;YAC7C,EAAE;YACF,UAAU,OAAO,CAAC,KAAK,EAAE;YACzB,EAAE;YACF,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;gBACxB,CAAC,CAAC,uBAAuB;gBACzB,CAAC,CAAC,kBAAkB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;YAC1E,qBAAqB,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;YACxE,sBAAsB;YACtB,GAAG,CAAC,OAAO,CAAC,KAAK;gBACf,CAAC,CAAC;oBACE,EAAE;oBACF,mEAAmE,eAAe,QAAQ,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG;iBACtH;gBACH,CAAC,CAAC,OAAO,CAAC,WAAW,KAAK,IAAI;oBAC5B,CAAC,CAAC;wBACE,EAAE;wBACF,8GAA8G,eAAe,QAAQ,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG;qBACjK;oBACH,CAAC,CAAC,EAAE,CAAC;SACV,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAC3B,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAC9C,CAAC,CACF,CAAC;IACF,OAAO;QACL,UAAU,cAAc,EAAE,qDAAqD;QAC/E,EAAE;QACF,uFAAuF;QACvF,oFAAoF;QACpF,mFAAmF;QACnF,EAAE;QACF,mCAAmC;QACnC,EAAE;QACF,WAAW;QACX,GAAG,QAAQ,CAAC,GAAG,CACb,CAAC,IAAI,EAAE,EAAE,CACP,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,EAAE,CAC5I;QACD,EAAE;QACF,eAAe;QACf,qDAAqD;QACrD,2DAA2D;QAC3D,EAAE;QACF,qEAAqE;QACrE,yEAAyE;QACzE,EAAE;QACF,oEAAoE;QACpE,KAAK,eAAe,2CAA2C;QAC/D,KAAK,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAC9B,+EAA+E;QAC/E,6EAA6E;QAC7E,EAAE;QACF,oDAAoD,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB;QAClG,0FAA0F;KAC3F,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/cli/scan-range.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure block-range arithmetic for the escrow log scan behind `metrik streams`.
+ * No RPC, no clock, no env — so the coverage rules below are unit-testable
+ * without a network, which is the point: they decide when an empty result is
+ * allowed to be rendered as "you have no streams".
+ *
+ * ## Why the anchor is the deploy block
+ *
+ * A fixed lookback ("the last N blocks") cannot describe coverage: a wallet
+ * whose stream predates the window is shown an empty list with nothing to
+ * distinguish it from a wallet that never opened one. For a payments tool,
+ * telling someone their escrowed funds do not exist is the worst failure we
+ * have. The escrow has NO history before its deploy block, so that block is the
+ * honest anchor — and whether the budget reached it is then a fact the command
+ * can state.
+ *
+ * ## Why the window is 10 000 blocks
+ *
+ * `buyer` and `operator` are INDEXED on `StreamOpened`, so a per-wallet scan is
+ * a server-side topic filter whose response is tiny regardless of range. What
+ * public RPCs cap is the per-call BLOCK RANGE, and a topic filter does not lift
+ * it: `sepolia.base.org` answers a wider range with `-32614 "eth_getLogs is
+ * limited to a 10,000 range"`. So the page size is the cap, not a guess below
+ * it.
+ */
+/**
+ * getLogs page size. The window is `chunk + 1` blocks (bounds inclusive), so
+ * 9 999 is the largest page `sepolia.base.org` accepts.
+ */
+export declare const LOG_SCAN_CHUNK = 9999n;
+/**
+ * Window budget for one scan. 400 x 10 000 = 4 000 000 blocks, comfortably more
+ * than the live escrow's history (~1.06M blocks on 2026-09-17), so the default
+ * scan is complete rather than merely large. It is a CEILING, not a fixed cost:
+ * windows are built for the actual anchor-to-head span. Exceeding it is not an
+ * error — it is reported as `degraded`.
+ */
+export declare const LOG_SCAN_MAX_WINDOWS = 400;
+export interface ScanRange {
+    readonly fromBlock: bigint;
+    readonly toBlock: bigint;
+    /** Inclusive `[from, to]` windows, in ascending order. */
+    readonly windows: readonly (readonly [bigint, bigint])[];
+    /** True iff the budget could NOT reach `anchor`, i.e. the scan is partial. */
+    readonly degraded: boolean;
+}
+/**
+ * Page `[anchor, head]` into non-overlapping inclusive windows.
+ *
+ * An RPC that is behind the deployment yields an empty-but-valid range rather
+ * than a negative one, and an anchor past the head is clamped: a node still
+ * syncing must not produce a nonsense scan.
+ */
+export declare function escrowScanRange(head: bigint, anchorBlock: bigint, chunk?: bigint, maxWindows?: number): ScanRange;
+//# sourceMappingURL=scan-range.d.ts.map

package/dist/cli/scan-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-range.d.ts","sourceRoot":"","sources":["../../src/cli/scan-range.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAS,CAAC;AAErC;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;IACzD,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,MAAuB,EAC9B,UAAU,GAAE,MAA6B,GACxC,SAAS,CAaX"}