vana-cli 0.15.0 → 0.23.3

package/README.md

@@ -1,37 +1,95 @@
-# OpenDataLabs Context Gateway JavaScript SDK
+# Vana CLI
 
-`vana-cli` is the JavaScript client SDK for
-[OpenDataLabs Context Gateway](https://www.opendatalabs.com/context-gateway).
-Use it to let users connect their own data to your app.
+`vana` is the command line for Vana: it collects a person's own data into
+their Personal Server, and it drives the builder side of the protocol so an
+app or an agent can ask for that data, read it, and pay for it from a
+terminal.
 
-## CLI
+This repository also ships the JavaScript SDK the CLI is built on, which is
+documented further down.
 
-The `vana` CLI collects your personal data from any platform. See the **[CLI README](./cli/README.md)**.
+## Install
 
-Install on macOS with Homebrew:
+Run it without installing anything:
 
 ```bash
-brew tap vana-com/tap
-brew install vana
-vana status
+npx vana-cli status
 ```
 
-Or use the hosted prerelease installer on macOS/Linux:
+Or install the standalone binary, which is signed and notarized on macOS:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/vana-com/vana-cli/main/install/install.sh | sh
+vana status
 ```
 
-Branch prerelease:
+Windows uses `install/install.ps1`. Homebrew (`brew tap vana-com/tap && brew
+install vana`) is still published but lags the installer.
+
+The npm route runs under your own Node, which some endpoint security
+products prefer over an unknown executable; the installer gives you a
+single self-contained binary with no Node required. Both are the same CLI.
 
-- `https://github.com/vana-com/vana-cli/releases/tag/canary-feat-connect-cli-v1`
+## Two halves
 
-Once installed:
+**Owner side** collects your own data and keeps it in your Personal Server:
 
 ```bash
-vana connect linkedin
+vana login                  # Vana account, or --server <url> for a self-hosted PS
+vana connect github         # managed browser, collects, syncs to your server
+vana data show github       # what was collected
+vana server status          # your server, local and registered URLs
 ```
 
+**Builder side** is what an app or an agent uses to work with someone
+else's data, with their consent:
+
+```bash
+vana app register                                  # once per machine
+vana app request --scopes github.repositories      # prints an approval URL, waits
+vana app read github.repositories --grant <id>     # signed read
+```
+
+`request` returns the grant id once the person approves. `read` stops at
+exit 4 with the exact price before spending anything; add `--pay` to settle
+it from escrow and `--max-fee` to cap it. The rest of the group:
+
+| Command                                              | What it does                                                                    |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `vana app ask "<q>" --sources a,b --derived <scope>` | ask a question computed on the person's own server, without reading the sources |
+| `vana app status <derived-scope>`                    | is the answer coming, and when                                                  |
+| `vana app lineage <scope>`                           | what an answer was computed from, redacted where it must be                     |
+| `vana app whoami`                                    | app address, key source, network, registration state                            |
+| `vana app requests list\|show <id>`                  | what was asked, what was approved                                               |
+| `vana app escrow balance\|fund`                      | what the app can spend, and funding it                                          |
+| `vana app onchain <scope> --owner <addr>`            | data point version, hashes, deletion state                                      |
+
+Everything defaults to **moksha**, the testnet; `--network mainnet` spends
+real money and is never implied.
+
+## For agents
+
+Every command takes `--json` and `--no-input`, and exits with a code an
+agent can branch on: `0` done, `1` failed, `2` bad usage, `3` no grant,
+`4` payment required, `5` no server answered, `6` not ready yet, `7` a
+person has to act. The full contract is in
+[docs/CLI-EXIT-CODE-MATRIX.md](./docs/CLI-EXIT-CODE-MATRIX.md).
+
+Install the skills that teach an agent each half:
+
+```bash
+vana skills install builder        # ask for access, read, pay
+vana skills install connect-data   # collect your own data
+```
+
+There is also an MCP server over stdio for clients that prefer tools:
+
+```bash
+claude mcp add vana -- vana mcp
+```
+
+## The SDK
+
 ## What problem this solves
 
 Your users already have rich personal data — ChatGPT conversations, Instagram activity, Gmail, purchase history — but it's locked inside the platforms that collected it. As a builder, you can't easily use that data to personalize onboarding, tailor recommendations, or skip lengthy signup forms.

package/dist/cli/app/ask.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `vana app ask "<question>" --sources a,b --derived <scope>`
+ *
+ * The consent path by default: the question travels inside an access
+ * request, so the person approves the question itself and the app ends up
+ * holding a grant on the answer rather than on the sources it was computed
+ * from. `--registered` switches to the builder-registered path, which needs
+ * a read grant on every source scope and says so.
+ *
+ * This composes commands that already exist rather than reimplementing
+ * them: it creates the request, waits for the answer to settle, and reads
+ * the derived scope through the same escrow path, gates and receipts as any
+ * other read. Costs are reported separately (see derivatives.ts).
+ */
+import { type AppCommandOptions } from "./outcome.js";
+import { runAppRead } from "./read.js";
+import { runAppRequest } from "./request.js";
+import { runAppStatus } from "./derivatives.js";
+export interface AskCommandOptions extends AppCommandOptions {
+    sources?: string;
+    derived?: string;
+    /** Settle the derived-scope read from escrow. */
+    pay?: boolean;
+    maxFee?: string;
+    timeout?: string;
+    /**
+     * Register the question as a builder instead of carrying it through
+     * consent. Needs a read grant on every source scope.
+     */
+    registered?: boolean;
+}
+export interface AskDeps {
+    request?: typeof runAppRequest;
+    status?: typeof runAppStatus;
+    read?: typeof runAppRead;
+}
+export declare function runAppAsk(question: string, options: AskCommandOptions, deps?: AskDeps): Promise<number>;
+//# sourceMappingURL=ask.d.ts.map

package/dist/cli/app/ask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../../src/cli/app/ask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,UAAU,EAA2B,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,aAAa,EAA8B,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAgBhD,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,OAAO;IACtB,OAAO,CAAC,EAAE,OAAO,aAAa,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,YAAY,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,UAAU,CAAC;CAC1B;AAED,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,iBAAiB,EAC1B,IAAI,GAAE,OAAY,GACjB,OAAO,CAAC,MAAM,CAAC,CA0FjB"}

package/dist/cli/app/ask.js

@@ -0,0 +1,110 @@
+/**
+ * `vana app ask "<question>" --sources a,b --derived <scope>`
+ *
+ * The consent path by default: the question travels inside an access
+ * request, so the person approves the question itself and the app ends up
+ * holding a grant on the answer rather than on the sources it was computed
+ * from. `--registered` switches to the builder-registered path, which needs
+ * a read grant on every source scope and says so.
+ *
+ * This composes commands that already exist rather than reimplementing
+ * them: it creates the request, waits for the answer to settle, and reads
+ * the derived scope through the same escrow path, gates and receipts as any
+ * other read. Costs are reported separately (see derivatives.ts).
+ */
+import { UnknownNetworkError, resolveNetwork, } from "../../core/network.js";
+import { emitAppOutcome } from "./outcome.js";
+import { runAppRead } from "./read.js";
+import { runAppRequest } from "./request.js";
+import { runAppStatus } from "./derivatives.js";
+import { createRequestsStore } from "../../core/requests-store.js";
+/** Newest approved grant covering a scope, from the local request index. */
+function findGrantForScope(scope, network) {
+    return (createRequestsStore()
+        .list({ network })
+        .find((entry) => Boolean(entry.grantId) &&
+        (entry.approvedScopes ?? entry.scopes).includes(scope))?.grantId ?? null);
+}
+export async function runAppAsk(question, options, deps = {}) {
+    let network;
+    try {
+        network = resolveNetwork(options.network);
+    }
+    catch (error) {
+        if (error instanceof UnknownNetworkError) {
+            return emitAppOutcome(options, {
+                status: "failed",
+                code: "bad_usage",
+                message: error.message,
+            });
+        }
+        throw error;
+    }
+    const sources = (options.sources ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    if (!question.trim() || sources.length === 0 || !options.derived) {
+        return emitAppOutcome(options, {
+            status: "failed",
+            code: "bad_usage",
+            message: "ask needs a question, --sources and --derived.",
+            remedy: `vana app ask "..." --sources spotify.history --derived myapp.summary`,
+            network: network.name,
+        });
+    }
+    if (options.registered) {
+        // Honest refusal rather than a half-path: registering a question as the
+        // builder requires a read grant on every source scope, which is exactly
+        // the access the consent path is designed to avoid. Until someone needs
+        // it, say so instead of pretending.
+        return emitAppOutcome(options, {
+            status: "failed",
+            code: "bad_usage",
+            message: "--registered is not wired yet. It needs a read grant on every source scope, which the consent path deliberately avoids.",
+            remedy: `drop --registered to ask through consent`,
+            network: network.name,
+        });
+    }
+    // 1. Ask the person. The derived scope must also be granted as a plain
+    //    read so the answer can be read back; request validates that.
+    const requestOptions = {
+        ...options,
+        scopes: [...sources, options.derived].join(","),
+        question,
+        derived: options.derived,
+        sources: options.sources,
+    };
+    const requestExit = await (deps.request ?? runAppRequest)(requestOptions);
+    if (requestExit !== 0) {
+        // request already emitted a precise outcome (7 when a person must act,
+        // 3 on denial, 6 on timeout); nothing to add.
+        return requestExit;
+    }
+    // 2. Wait for the answer to settle on the owner's server.
+    const statusExit = await (deps.status ?? runAppStatus)(options.derived, options);
+    if (statusExit !== 0) {
+        return statusExit;
+    }
+    // 3. Read the answer, through the ordinary billable read path. The grant
+    //    comes from the request just approved; read resolves the owner and the
+    //    server from it.
+    const grantId = findGrantForScope(options.derived, network.name);
+    if (!grantId) {
+        return emitAppOutcome(options, {
+            status: "failed",
+            code: "grant_invalid",
+            message: "The request was approved but no grant id was recorded.",
+            remedy: "vana app requests list",
+            network: network.name,
+        });
+    }
+    const readOptions = {
+        ...options,
+        grant: grantId,
+        pay: options.pay,
+        maxFee: options.maxFee,
+    };
+    return (deps.read ?? runAppRead)(options.derived, readOptions);
+}
+//# sourceMappingURL=ask.js.map

package/dist/cli/app/ask.js.map

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

package/dist/cli/app/derivatives.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `vana app ask | status | lineage` - questions over a person's data.
+ *
+ * A question is computed on the owner's own Personal Server over source
+ * scopes the app never reads, and the answer is written into a derived
+ * scope the app does read. That is why `ask` goes through consent: the
+ * question travels inside the access request, so the app holds a grant on
+ * the answer rather than on the sources.
+ *
+ * Pricing note. Two separate costs live here and the CLI reports them
+ * separately rather than folding them into one number, because only one of
+ * them exists today and the other is an open decision:
+ *
+ * - the compute itself emits no fee event today, so it is reported as
+ *   `computeCost: null` rather than as free; when a price appears it is a
+ *   number in a field that already exists
+ * - reading the derived scope afterwards is an ordinary billable read and
+ *   goes through the same escrow path, gates and receipts as any other
+ *
+ * No price is hardcoded anywhere: every amount comes from what the
+ * protocol quotes.
+ */
+import { getDerivativeStatus, getLineage } from "@opendatalabs/vana-sdk";
+import { resolveAppKey } from "../../core/app-key.js";
+import { type RequestsStore } from "../../core/requests-store.js";
+import { type AppCommandOptions } from "./outcome.js";
+export interface DerivativeCommandOptions extends AppCommandOptions {
+    /** Grant covering the derived scope; resolved from the store when absent. */
+    grant?: string;
+    /** Personal Server URL; resolved from the stored request when absent. */
+    server?: string;
+}
+export interface DerivativeDeps {
+    resolveKey?: typeof resolveAppKey;
+    requests?: RequestsStore;
+    status?: typeof getDerivativeStatus;
+    lineage?: typeof getLineage;
+}
+export declare function runAppStatus(derivedScope: string, options: DerivativeCommandOptions, deps?: DerivativeDeps): Promise<number>;
+export declare function runAppLineage(scope: string, options: DerivativeCommandOptions, deps?: DerivativeDeps): Promise<number>;
+//# sourceMappingURL=derivatives.d.ts.map

package/dist/cli/app/derivatives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivatives.d.ts","sourceRoot":"","sources":["../../../src/cli/app/derivatives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,mBAAmB,EACnB,UAAU,EAEX,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAEL,aAAa,EAEd,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtE,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,OAAO,aAAa,CAAC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,mBAAmB,CAAC;IACpC,OAAO,CAAC,EAAE,OAAO,UAAU,CAAC;CAC7B;AAwHD,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,wBAAwB,EACjC,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,MAAM,CAAC,CA6DjB;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,wBAAwB,EACjC,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,MAAM,CAAC,CAgCjB"}

package/dist/cli/app/derivatives.js

@@ -0,0 +1,227 @@
+/**
+ * `vana app ask | status | lineage` - questions over a person's data.
+ *
+ * A question is computed on the owner's own Personal Server over source
+ * scopes the app never reads, and the answer is written into a derived
+ * scope the app does read. That is why `ask` goes through consent: the
+ * question travels inside the access request, so the app holds a grant on
+ * the answer rather than on the sources.
+ *
+ * Pricing note. Two separate costs live here and the CLI reports them
+ * separately rather than folding them into one number, because only one of
+ * them exists today and the other is an open decision:
+ *
+ * - the compute itself emits no fee event today, so it is reported as
+ *   `computeCost: null` rather than as free; when a price appears it is a
+ *   number in a field that already exists
+ * - reading the derived scope afterwards is an ordinary billable read and
+ *   goes through the same escrow path, gates and receipts as any other
+ *
+ * No price is hardcoded anywhere: every amount comes from what the
+ * protocol quotes.
+ */
+import { getDerivativeStatus, getLineage, isDerivativeStatusSettled, } from "@opendatalabs/vana-sdk";
+import { privateKeyToAccount } from "viem/accounts";
+import { AppKeyMissingError, resolveAppKey, } from "../../core/app-key.js";
+import { UnknownNetworkError, resolveNetwork, } from "../../core/network.js";
+import { createRequestsStore, } from "../../core/requests-store.js";
+import { emitAppOutcome } from "./outcome.js";
+/**
+ * Resolve what a derivative call needs: the network, the app key, a grant
+ * covering the derived scope and the server that holds it. Explicit flags
+ * win; otherwise the newest approved request that covers the scope answers
+ * both, which is how `ask` hands off to `status` without the caller
+ * carrying ids around.
+ */
+function resolveContext(derivedScope, options, deps) {
+    let network;
+    try {
+        network = resolveNetwork(options.network);
+    }
+    catch (error) {
+        if (error instanceof UnknownNetworkError) {
+            return {
+                ok: false,
+                exitCode: emitAppOutcome(options, {
+                    status: "failed",
+                    code: "bad_usage",
+                    message: error.message,
+                }),
+            };
+        }
+        throw error;
+    }
+    let key;
+    try {
+        key = (deps.resolveKey ?? resolveAppKey)({});
+    }
+    catch (error) {
+        if (error instanceof AppKeyMissingError) {
+            return {
+                ok: false,
+                exitCode: emitAppOutcome(options, {
+                    status: "failed",
+                    code: "bad_usage",
+                    message: "No app key on this machine yet.",
+                    remedy: "vana app register",
+                    network: network.name,
+                }),
+            };
+        }
+        throw error;
+    }
+    let grantId = options.grant;
+    let personalServerUrl = options.server;
+    if (!grantId || !personalServerUrl) {
+        const match = findApprovedRequest(derivedScope, network.name, key.address, deps.requests ?? createRequestsStore());
+        grantId ??= match?.grantId;
+        personalServerUrl ??= match?.personalServerUrl;
+    }
+    if (!grantId) {
+        return {
+            ok: false,
+            exitCode: emitAppOutcome(options, {
+                status: "failed",
+                code: "grant_invalid",
+                message: `No approved grant covering ${derivedScope}.`,
+                remedy: `vana app request --scopes ${derivedScope} --question "..." --derived ${derivedScope} --sources <scopes>`,
+                network: network.name,
+            }),
+        };
+    }
+    if (!personalServerUrl) {
+        return {
+            ok: false,
+            exitCode: emitAppOutcome(options, {
+                status: "failed",
+                code: "owner_not_ready",
+                message: "No Personal Server URL for this grant; the owner may serve through the enclave path, which derivatives do not use yet.",
+                remedy: "pass --server explicitly if you know the URL",
+                network: network.name,
+            }),
+        };
+    }
+    return {
+        ok: true,
+        context: { network, key, grantId, personalServerUrl },
+    };
+}
+function findApprovedRequest(derivedScope, network, appAddress, requests) {
+    return (requests
+        .list({ network, appAddress })
+        .find((entry) => Boolean(entry.grantId) &&
+        (entry.approvedScopes ?? entry.scopes).includes(derivedScope)) ?? null);
+}
+export async function runAppStatus(derivedScope, options, deps = {}) {
+    const resolved = resolveContext(derivedScope, options, deps);
+    if (!resolved.ok) {
+        return resolved.exitCode;
+    }
+    const { network, key, grantId, personalServerUrl } = resolved.context;
+    if (!options.quiet && !options.json) {
+        // The route is free to the caller and triggers a recompute, so a loop
+        // here spends the inference budget without reading anything.
+        process.stderr.write("Note: this route can trigger a recompute. Poll on the interval the server names, not faster.\n");
+    }
+    try {
+        const status = await (deps.status ?? getDerivativeStatus)({
+            personalServerUrl,
+            derivedScope,
+            grantId,
+            signer: privateKeyToAccount(key.privateKey),
+        });
+        const settled = isDerivativeStatusSettled(status);
+        const ready = status.status === "ready";
+        return emitAppOutcome(options, {
+            status: ready || settled ? "done" : "failed",
+            code: ready
+                ? "ok"
+                : status.status === "failed"
+                    ? mapDerivativeError(status.errorCode)
+                    : "not_ready",
+            message: derivativeMessage(status),
+            remedy: ready
+                ? `vana app read ${derivedScope} --grant ${grantId}`
+                : status.retryAfterSeconds
+                    ? `retry in ${status.retryAfterSeconds}s`
+                    : undefined,
+            network: network.name,
+            data: {
+                derivedScope,
+                state: status.status,
+                version: status.derivedVersion,
+                lastComputedAt: status.lastComputedAt,
+                errorCode: status.errorCode,
+                retryAfterSeconds: status.retryAfterSeconds,
+                // Compute emits no fee event today; null says "unknown/unpriced",
+                // not "free". A price lands here as a number without a shape change.
+                computeCost: null,
+            },
+        });
+    }
+    catch (error) {
+        return emitAppOutcome(options, {
+            status: "failed",
+            code: "server_unavailable",
+            message: `Could not read the derivative status: ${error instanceof Error ? error.message : String(error)}`,
+            network: network.name,
+        });
+    }
+}
+export async function runAppLineage(scope, options, deps = {}) {
+    const resolved = resolveContext(scope, options, deps);
+    if (!resolved.ok) {
+        return resolved.exitCode;
+    }
+    const { network, key, grantId, personalServerUrl } = resolved.context;
+    try {
+        const result = await (deps.lineage ?? getLineage)({
+            personalServerUrl,
+            scope,
+            grantId,
+            signer: privateKeyToAccount(key.privateKey),
+        });
+        return emitAppOutcome(options, {
+            status: "done",
+            code: "ok",
+            message: `Lineage for ${scope}.`,
+            network: network.name,
+            data: { scope, lineage: result },
+        });
+    }
+    catch (error) {
+        return emitAppOutcome(options, {
+            status: "failed",
+            code: "server_unavailable",
+            message: `Could not read the lineage: ${error instanceof Error ? error.message : String(error)}`,
+            network: network.name,
+        });
+    }
+}
+function mapDerivativeError(code) {
+    switch (code) {
+        case "grant_invalid":
+            return "grant_invalid";
+        case "source_missing":
+            return "scope_not_found";
+        case "inference_unavailable":
+            return "not_ready";
+        default:
+            return "internal";
+    }
+}
+function derivativeMessage(status) {
+    switch (status.status) {
+        case "ready":
+            return `Answer is ready (version ${status.derivedVersion ?? "?"}).`;
+        case "pending":
+            return "The answer is being computed.";
+        case "stale":
+            return "A source changed; the answer is being recomputed.";
+        case "failed":
+            return `The computation failed: ${status.errorCode ?? "unknown"}.`;
+        default:
+            return `State: ${status.status}.`;
+    }
+}
+//# sourceMappingURL=derivatives.js.map

package/dist/cli/app/derivatives.js.map

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

package/dist/cli/app/escrow.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `vana app escrow balance|fund` - what the app can spend, and funding it.
+ *
+ * Funding is deliberately one command for both halves: the on-chain
+ * `depositNative(account)` transaction and the gateway deposit
+ * registration. Either half alone produces a contract that looks funded
+ * while every read still answers 402.
+ */
+import { type GatewayClient } from "@opendatalabs/vana-sdk";
+import { resolveAppKey, type ResolvedAppKey } from "../../core/app-key.js";
+import { type ResolvedNetwork } from "../../core/network.js";
+import { type AppCommandOptions } from "./outcome.js";
+export interface EscrowFundOptions extends AppCommandOptions {
+    /** Amount to deposit, decimal, in units of the chosen asset. */
+    amount?: string;
+    /**
+     * ERC20 to deposit instead of native VANA. Reads are priced in USDC.e on
+     * mainnet, so funding native alone leaves every read answering 402.
+     */
+    asset?: string;
+}
+export interface EscrowDeps {
+    createClient?: (gatewayUrl: string) => GatewayClient;
+    resolveKey?: typeof resolveAppKey;
+    /** Injectable chain senders for tests. */
+    sendDeposit?: (params: {
+        network: ResolvedNetwork;
+        key: ResolvedAppKey;
+        escrowContract: `0x${string}`;
+        amountWei: bigint;
+        asset?: string;
+    }) => Promise<{
+        txHash: `0x${string}`;
+    }>;
+}
+export declare function runAppEscrowBalance(options: AppCommandOptions, deps?: EscrowDeps): Promise<number>;
+export declare class InsufficientFundsError extends Error {
+    readonly balanceWei: bigint;
+    readonly neededWei: bigint;
+    readonly asset?: string | undefined;
+    constructor(balanceWei: bigint, neededWei: bigint, asset?: string | undefined);
+}
+export declare function runAppEscrowFund(options: EscrowFundOptions, deps?: EscrowDeps): Promise<number>;
+//# sourceMappingURL=escrow.d.ts.map

package/dist/cli/app/escrow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow.d.ts","sourceRoot":"","sources":["../../../src/cli/app/escrow.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,wBAAwB,CAAC;AAiBhC,OAAO,EAEL,aAAa,EACb,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtE,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,aAAa,CAAC;IACrD,UAAU,CAAC,EAAE,OAAO,aAAa,CAAC;IAClC,0CAA0C;IAC1C,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE;QACrB,OAAO,EAAE,eAAe,CAAC;QACzB,GAAG,EAAE,cAAc,CAAC;QACpB,cAAc,EAAE,KAAK,MAAM,EAAE,CAAC;QAC9B,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAC1C;AA4CD,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,iBAAiB,EAC1B,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,MAAM,CAAC,CA0CjB;AA2ED,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,UAAU,EAAE,MAAM;aAClB,SAAS,EAAE,MAAM;aACjB,KAAK,CAAC,EAAE,MAAM;gBAFd,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,YAAA;CASjC;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,iBAAiB,EAC1B,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,MAAM,CAAC,CAkHjB"}