@livo-build/runtime 0.2.1 → 0.2.3

package/dist/indexer.d.ts

@@ -0,0 +1,35 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export interface IndexerOptions {
+    /** Override the endpoint directly (takes precedence over env). */
+    url?: string;
+    /** env key holding the GraphQL endpoint. Default `INDEXER_<NAME>_URL`. */
+    urlSecret?: string;
+}
+export declare class GraphQLError extends Error {
+    readonly errors: unknown[];
+    constructor(message: string, errors: unknown[]);
+}
+/** Binding-name form of an indexer name: upper-snake (INDEXER_<THIS>_URL). */
+export declare function indexerEnvKey(name: string): string;
+export declare class Indexer {
+    readonly name: string;
+    readonly url: string | undefined;
+    constructor(env: MinimalEnv | undefined, name: string, options?: IndexerOptions);
+    /** True when the endpoint binding for this indexer was injected. */
+    get configured(): boolean;
+    /**
+     * Run a GraphQL query and return `data` (typed via the caller's generic).
+     * Throws on transport errors or GraphQL `errors`.
+     */
+    query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /** The subgraph's `_meta` — current head block + whether indexing has errored. */
+    meta(): Promise<{
+        block: number | null;
+        hasIndexingErrors: boolean;
+    }>;
+}
+/** Convenience: `await indexer(env, "hearth").query(gql, vars)`. */
+export declare function indexer(env: MinimalEnv | undefined, name: string, options?: IndexerOptions): Indexer;
+export {};

package/dist/indexer.js

@@ -0,0 +1,73 @@
+// Indexer — a typed GraphQL client for a project's Goldsky subgraph. A keeper /
+// bot / server reads `INDEXER_<NAME>_URL` (injected at deploy as the subgraph's
+// STABLE `live`-tag alias, NOT a version-pinned URL), so the worker never holds a
+// URL that breaks on the next sync_indexers/reindex. Just:
+//
+//   const { keepers } = await indexer(env, "hearth").query(
+//     `query($min:Int!){ keepers(where:{count_gte:$min}){ id count } }`, { min: 3 });
+//
+// Mirrors the Queue producer-binding pattern (queue.ts): a deployable gets the
+// binding injected by the platform; this wraps it so there's no fetch/URL/GraphQL
+// boilerplate to hand-roll. Pass an explicit `url` to point it anywhere (local dev).
+export class GraphQLError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.errors = errors;
+        this.name = "GraphQLError";
+    }
+}
+/** Binding-name form of an indexer name: upper-snake (INDEXER_<THIS>_URL). */
+export function indexerEnvKey(name) {
+    return name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+}
+export class Indexer {
+    name;
+    url;
+    constructor(env, name, options = {}) {
+        this.name = name;
+        const key = options.urlSecret ?? `INDEXER_${indexerEnvKey(name)}_URL`;
+        this.url = options.url ?? env?.[key];
+    }
+    /** True when the endpoint binding for this indexer was injected. */
+    get configured() {
+        return Boolean(this.url);
+    }
+    /**
+     * Run a GraphQL query and return `data` (typed via the caller's generic).
+     * Throws on transport errors or GraphQL `errors`.
+     */
+    async query(query, variables) {
+        if (!this.url) {
+            throw new Error(`indexer "${this.name}" not configured — no INDEXER_${indexerEnvKey(this.name)}_URL binding. ` +
+                `Deploy/sync the subgraph (create_indexer / sync_indexers) so the platform injects it, ` +
+                `or pass { url } for local dev.`);
+        }
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ query, variables: variables ?? {} }),
+        });
+        if (!res.ok) {
+            throw new Error(`indexer "${this.name}" query failed: HTTP ${res.status}`);
+        }
+        const json = (await res.json());
+        if (json.errors && json.errors.length) {
+            const first = json.errors[0];
+            throw new GraphQLError(`indexer "${this.name}" GraphQL error: ${first?.message ?? "unknown"}`, json.errors);
+        }
+        return json.data;
+    }
+    /** The subgraph's `_meta` — current head block + whether indexing has errored. */
+    async meta() {
+        const data = await this.query(`{ _meta { block { number } hasIndexingErrors } }`);
+        return {
+            block: data._meta?.block?.number ?? null,
+            hasIndexingErrors: Boolean(data._meta?.hasIndexingErrors),
+        };
+    }
+}
+/** Convenience: `await indexer(env, "hearth").query(gql, vars)`. */
+export function indexer(env, name, options) {
+    return new Indexer(env, name, options);
+}

package/dist/multicall.d.ts

@@ -0,0 +1,30 @@
+import { type AbiFunction } from "./abi.js";
+import { type Hex } from "./hex.js";
+/** Canonical Multicall3 (same address on mainnet, testnets, L2s, …). */
+export declare const MULTICALL3_ADDRESS: Hex;
+export interface MulticallCall {
+    address: Hex;
+    abi: AbiFunction[];
+    functionName: string;
+    args?: unknown[];
+    /** Per-call override of the batch allowFailure. */
+    allowFailure?: boolean;
+}
+export interface MulticallOptions {
+    /** When true (default), a reverting sub-call yields null instead of throwing the batch. */
+    allowFailure?: boolean;
+    /** Override the Multicall3 address (e.g. a local Anvil predeploy). */
+    multicallAddress?: Hex;
+    block?: Hex | "latest" | "pending";
+}
+/** Minimal Chain surface multicall needs — just the JSON-RPC passthrough. */
+interface RpcLike {
+    rpc<T = unknown>(method: string, params?: unknown[]): Promise<T>;
+}
+/**
+ * Encode N reads into one aggregate3 eth_call and decode each result against its
+ * own function ABI. Returns one entry per input call (null for a reverted call
+ * when allowFailure). Throws on a reverted call when allowFailure is false.
+ */
+export declare function multicall(chain: RpcLike, calls: MulticallCall[], opts?: MulticallOptions): Promise<(unknown | null)[]>;
+export {};

package/dist/multicall.js

@@ -0,0 +1,65 @@
+// Multicall — batch many contract reads into one eth_call via Multicall3's
+// aggregate3. Encodes/decodes with the same abi.ts coder the rest of the runtime
+// uses (no new deps). Multicall3 is deployed at the canonical address on virtually
+// every EVM chain; pass `multicallAddress` for exotic/local chains where it isn't.
+import { decodeFunctionResult, decodeParameters, encodeFunctionData, encodeParameters, findFunction, functionSelector, } from "./abi.js";
+import { bytesToHex, concatBytes, hexToBytes } from "./hex.js";
+/** Canonical Multicall3 (same address on mainnet, testnets, L2s, …). */
+export const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
+// aggregate3((address target, bool allowFailure, bytes callData)[])
+//   returns ((bool success, bytes returnData)[])
+const AGGREGATE3_INPUTS = [
+    {
+        type: "tuple[]",
+        components: [
+            { name: "target", type: "address" },
+            { name: "allowFailure", type: "bool" },
+            { name: "callData", type: "bytes" },
+        ],
+    },
+];
+const AGGREGATE3_OUTPUTS = [
+    {
+        type: "tuple[]",
+        components: [
+            { name: "success", type: "bool" },
+            { name: "returnData", type: "bytes" },
+        ],
+    },
+];
+// Computed once from the canonical signature — single source of truth with abi.ts.
+const AGGREGATE3_SELECTOR = functionSelector("aggregate3((address,bool,bytes)[])");
+/**
+ * Encode N reads into one aggregate3 eth_call and decode each result against its
+ * own function ABI. Returns one entry per input call (null for a reverted call
+ * when allowFailure). Throws on a reverted call when allowFailure is false.
+ */
+export async function multicall(chain, calls, opts = {}) {
+    if (calls.length === 0)
+        return [];
+    const batchAllow = opts.allowFailure ?? true;
+    const fns = [];
+    const tuples = calls.map((c) => {
+        const fn = findFunction(c.abi, c.functionName);
+        fns.push(fn);
+        return {
+            target: c.address,
+            allowFailure: c.allowFailure ?? batchAllow,
+            callData: encodeFunctionData(fn, c.args ?? []),
+        };
+    });
+    const data = bytesToHex(concatBytes(AGGREGATE3_SELECTOR, encodeParameters(AGGREGATE3_INPUTS, [tuples])));
+    const result = await chain.rpc("eth_call", [
+        { to: opts.multicallAddress ?? MULTICALL3_ADDRESS, data },
+        opts.block ?? "latest",
+    ]);
+    const [rows] = decodeParameters(AGGREGATE3_OUTPUTS, hexToBytes(result));
+    return rows.map((row, i) => {
+        if (!row.success) {
+            if (calls[i].allowFailure ?? batchAllow)
+                return null;
+            throw new Error(`multicall: ${calls[i].functionName} on ${calls[i].address} reverted`);
+        }
+        return decodeFunctionResult(fns[i], hexToBytes(row.returnData));
+    });
+}

package/dist/queue.d.ts

@@ -0,0 +1,27 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+/** Binding-name form of a queue name: upper-snake (QUEUE_<THIS>_URL/TOKEN). */
+export declare function queueEnvKey(name: string): string;
+export declare class Queue {
+    readonly name: string;
+    private readonly url?;
+    private readonly token?;
+    constructor(env: MinimalEnv | undefined, name: string);
+    /** True when the producer bindings for this queue were injected. */
+    get configured(): boolean;
+    /** Publish one message. */
+    send(message: unknown): Promise<{
+        ok: boolean;
+        queued?: number;
+    }>;
+    /** Publish many messages in one request. */
+    sendBatch(messages: unknown[]): Promise<{
+        ok: boolean;
+        queued?: number;
+    }>;
+    private post;
+}
+/** Convenience: `await queue(env, "settler").send(msg)`. */
+export declare function queue(env: MinimalEnv | undefined, name: string): Queue;
+export {};

package/dist/queue.js

@@ -0,0 +1,49 @@
+// Queue — a producer handle for a Livo per-project queue (docs/QUEUES-SPEC.md). A
+// deployable that declares `produces: [name]` gets QUEUE_<NAME>_URL +
+// QUEUE_<NAME>_TOKEN injected at deploy; this wraps them so a keeper/bot/server just
+// does `queue(env, "name").send(msg)` — no URL or token handling. The consumer then
+// batches the messages to its consume(batch, env).
+/** Binding-name form of a queue name: upper-snake (QUEUE_<THIS>_URL/TOKEN). */
+export function queueEnvKey(name) {
+    return name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+}
+export class Queue {
+    name;
+    url;
+    token;
+    constructor(env, name) {
+        this.name = name;
+        const k = queueEnvKey(name);
+        this.url = env?.[`QUEUE_${k}_URL`];
+        this.token = env?.[`QUEUE_${k}_TOKEN`];
+    }
+    /** True when the producer bindings for this queue were injected. */
+    get configured() {
+        return Boolean(this.url && this.token);
+    }
+    /** Publish one message. */
+    send(message) {
+        return this.post(message);
+    }
+    /** Publish many messages in one request. */
+    sendBatch(messages) {
+        return this.post(messages);
+    }
+    async post(body) {
+        if (!this.url || !this.token) {
+            throw new Error(`queue "${this.name}" not configured — add it to this deployable's \`produces:\` so QUEUE_${queueEnvKey(this.name)}_URL/TOKEN are injected`);
+        }
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${this.token}` },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`queue "${this.name}" send failed: HTTP ${res.status}`);
+        return (await res.json());
+    }
+}
+/** Convenience: `await queue(env, "settler").send(msg)`. */
+export function queue(env, name) {
+    return new Queue(env, name);
+}

package/dist/secret.d.ts

@@ -0,0 +1,15 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+/**
+ * Read a required secret/binding off `env`, throwing a clear error when it's
+ * missing or empty. Use at the top of a handler so misconfiguration fails fast:
+ *
+ *   const token = requireSecret(env, "BOT_TOKEN");
+ */
+export declare function requireSecret(env: MinimalEnv | undefined, name: string): string;
+/** Read an optional secret/binding, returning `fallback` (default undefined) when absent or empty. */
+export declare function getSecret(env: MinimalEnv | undefined, name: string, fallback?: string): string | undefined;
+/** Assert several secrets are present at once; throws listing ALL missing ones. */
+export declare function requireSecrets<K extends string>(env: MinimalEnv | undefined, names: readonly K[]): Record<K, string>;
+export {};

package/dist/secret.js

@@ -0,0 +1,40 @@
+// Typed secret access. Project secrets (set_secret) and auto-injected bindings
+// arrive on the Worker `env`. Reading them raw means a missing one is `undefined`
+// and silently disables a feature at runtime (the classic "my Telegram send did
+// nothing" bug). `requireSecret` turns that into a loud, actionable error the
+// moment the code runs, instead of a silent no-op.
+/**
+ * Read a required secret/binding off `env`, throwing a clear error when it's
+ * missing or empty. Use at the top of a handler so misconfiguration fails fast:
+ *
+ *   const token = requireSecret(env, "BOT_TOKEN");
+ */
+export function requireSecret(env, name) {
+    const v = env?.[name];
+    if (typeof v === "string" && v.length > 0)
+        return v;
+    throw new Error(`missing secret "${name}" — set it with set_secret ${name}=<value> (or, for an ` +
+        `auto-injected binding like KEEPER_PRIVATE_KEY/RPC_URL, check it's wired for this deployable).`);
+}
+/** Read an optional secret/binding, returning `fallback` (default undefined) when absent or empty. */
+export function getSecret(env, name, fallback) {
+    const v = env?.[name];
+    return typeof v === "string" && v.length > 0 ? v : fallback;
+}
+/** Assert several secrets are present at once; throws listing ALL missing ones. */
+export function requireSecrets(env, names) {
+    const out = {};
+    const missing = [];
+    for (const n of names) {
+        const v = env?.[n];
+        if (typeof v === "string" && v.length > 0)
+            out[n] = v;
+        else
+            missing.push(n);
+    }
+    if (missing.length) {
+        throw new Error(`missing secret${missing.length > 1 ? "s" : ""} ${missing.map((m) => `"${m}"`).join(", ")} — ` +
+            `set with set_secret (e.g. set_secret ${missing[0]}=<value>).`);
+    }
+    return out;
+}

package/dist/store.d.ts

@@ -28,4 +28,15 @@ export declare class Store {
     getJSON<T>(key: string): Promise<T | null>;
     /** Upsert a JSON-serialized value. */
     setJSON<T>(key: string, value: T): Promise<void>;
+    /**
+     * Idempotency guard. Returns `true` the FIRST time a key is seen (claim it and
+     * proceed) and `false` on every later call — so a retried cron tick or a
+     * redelivered webhook doesn't double-fire:
+     *
+     *   if (!(await store.once(`block:${n}`))) return; // already processed n
+     *
+     * Atomic via `INSERT … ON CONFLICT DO NOTHING` + the row-changed count, so two
+     * concurrent calls can't both win.
+     */
+    once(key: string): Promise<boolean>;
 }

package/dist/store.js

@@ -57,4 +57,28 @@ export class Store {
     async setJSON(key, value) {
         await this.set(key, JSON.stringify(value));
     }
+    /**
+     * Idempotency guard. Returns `true` the FIRST time a key is seen (claim it and
+     * proceed) and `false` on every later call — so a retried cron tick or a
+     * redelivered webhook doesn't double-fire:
+     *
+     *   if (!(await store.once(`block:${n}`))) return; // already processed n
+     *
+     * Atomic via `INSERT … ON CONFLICT DO NOTHING` + the row-changed count, so two
+     * concurrent calls can't both win.
+     */
+    async once(key) {
+        await this.init();
+        const res = (await this.db
+            .prepare(`INSERT INTO ${this.table} (k, v, updated_at) VALUES (?, '1', ?)
+         ON CONFLICT(k) DO NOTHING`)
+            .bind(key, Date.now())
+            .run());
+        // D1 reports affected rows on `meta.changes` (or `changes`); 1 ⇒ we inserted.
+        const changes = res?.meta?.changes ?? res?.changes;
+        if (typeof changes === "number")
+            return changes > 0;
+        // Driver didn't surface a count — fall back to a read (non-atomic, best effort).
+        return (await this.get(key)) === "1";
+    }
 }

package/dist/telegram.d.ts

@@ -0,0 +1,63 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export interface TelegramOptions {
+    /** env key for the bot token. Default "BOT_TOKEN". */
+    tokenSecret?: string;
+    /** env key for the webhook secret token. Default "WEBHOOK_SECRET". */
+    webhookSecretKey?: string;
+    /** Override the token directly. */
+    token?: string;
+    /** Override the webhook secret directly. */
+    webhookSecret?: string;
+}
+/** A parsed inbound message — the shape a reply handler actually wants. */
+export interface BotMessage {
+    /** Trimmed message text. */
+    text: string;
+    /** Chat to reply into. */
+    chatId: number | string;
+    /** Sender attribution: "@username" or the numeric id as a string. */
+    handle: string;
+    /** Raw Telegram `from` object (id, username, first_name, …). */
+    from: Record<string, unknown> | undefined;
+    /** Raw Telegram message object. */
+    raw: Record<string, unknown>;
+    /** True when this came from Livo's test_bot harness (not real Telegram). */
+    isTest: boolean;
+}
+export interface SendMessageOptions {
+    parseMode?: "Markdown" | "MarkdownV2" | "HTML" | null;
+    replyToMessageId?: number;
+    disablePreview?: boolean;
+}
+export declare class Telegram {
+    private readonly token?;
+    private readonly webhookSecret?;
+    constructor(env: MinimalEnv | undefined, options?: TelegramOptions);
+    /** True when a bot token is configured (sends will actually reach Telegram). */
+    get configured(): boolean;
+    /**
+     * Verify a request really came from Telegram (or Livo's test_bot) by matching
+     * the secret-token header against WEBHOOK_SECRET. Returns true when no secret is
+     * configured (nothing to check). Use it if you parse the update yourself.
+     */
+    verify(req: Request): boolean;
+    /** Parse a raw Telegram update into a BotMessage, or null if it has no text message. */
+    parse(update: Record<string, unknown>): BotMessage | null;
+    /**
+     * Full webhook handler: verifies the secret, parses the update, runs `reply`,
+     * and either returns the computed reply to test_bot (__livo_test) or sends it to
+     * Telegram. `reply` returns a string to send, or null/undefined to stay silent.
+     * Returns the Worker Response — `return new Telegram(env).handleUpdate(req, fn)`.
+     */
+    handleUpdate(req: Request, reply: (msg: BotMessage) => string | null | undefined | Promise<string | null | undefined>, opts?: SendMessageOptions): Promise<Response>;
+    /** Send a message to a chat. No-op-safe: throws if no token is configured. */
+    sendMessage(chatId: number | string, text: string, opts?: SendMessageOptions): Promise<void>;
+    /** Register the slash-command menu (setMyCommands) — autocompletes in chat. */
+    setMyCommands(commands: Array<{
+        command: string;
+        description: string;
+    }>): Promise<void>;
+}
+export {};

package/dist/telegram.js

@@ -0,0 +1,115 @@
+// Telegram — collapses the webhook plumbing every Livo bot re-implements by hand:
+// the secret-token gate, the `__livo_test` short-circuit (so test_bot can read a
+// reply without hitting Telegram), update parsing, and the sendMessage call. A bot
+// becomes just its reply logic:
+//
+//   import { Telegram } from "@livo-build/runtime";
+//   export default {
+//     fetch(req, env) {
+//       return new Telegram(env).handleUpdate(req, (msg) =>
+//         msg.text === "/start" ? "👋 hi" : "you said " + msg.text);
+//     },
+//   };
+//
+// The deploy injects env.BOT_TOKEN (the resolved Telegram token) and
+// env.WEBHOOK_SECRET (authenticates Telegram's calls) — same bindings the
+// hand-rolled templates read.
+const API = "https://api.telegram.org/bot";
+export class Telegram {
+    token;
+    webhookSecret;
+    constructor(env, options = {}) {
+        this.token = options.token ?? env?.[options.tokenSecret ?? "BOT_TOKEN"];
+        this.webhookSecret =
+            options.webhookSecret ?? env?.[options.webhookSecretKey ?? "WEBHOOK_SECRET"];
+    }
+    /** True when a bot token is configured (sends will actually reach Telegram). */
+    get configured() {
+        return Boolean(this.token);
+    }
+    /**
+     * Verify a request really came from Telegram (or Livo's test_bot) by matching
+     * the secret-token header against WEBHOOK_SECRET. Returns true when no secret is
+     * configured (nothing to check). Use it if you parse the update yourself.
+     */
+    verify(req) {
+        if (!this.webhookSecret)
+            return true;
+        return req.headers.get("x-telegram-bot-api-secret-token") === this.webhookSecret;
+    }
+    /** Parse a raw Telegram update into a BotMessage, or null if it has no text message. */
+    parse(update) {
+        const msg = (update.message ?? update.edited_message);
+        const text = msg && typeof msg.text === "string" ? msg.text : undefined;
+        if (!msg || text === undefined)
+            return null;
+        const from = msg.from;
+        const username = from && typeof from.username === "string" ? from.username : undefined;
+        const handle = username ? `@${username}` : from?.id != null ? String(from.id) : "anon";
+        const chat = msg.chat;
+        return {
+            text: text.trim(),
+            chatId: chat?.id ?? 0,
+            handle,
+            from,
+            raw: msg,
+            isTest: update.__livo_test === true,
+        };
+    }
+    /**
+     * Full webhook handler: verifies the secret, parses the update, runs `reply`,
+     * and either returns the computed reply to test_bot (__livo_test) or sends it to
+     * Telegram. `reply` returns a string to send, or null/undefined to stay silent.
+     * Returns the Worker Response — `return new Telegram(env).handleUpdate(req, fn)`.
+     */
+    async handleUpdate(req, reply, opts = {}) {
+        if (req.method !== "POST")
+            return new Response("ok");
+        if (!this.verify(req))
+            return new Response("forbidden", { status: 403 });
+        const update = (await req.json().catch(() => ({})));
+        const msg = this.parse(update);
+        if (!msg)
+            return new Response("ok");
+        const out = (await reply(msg)) ?? null;
+        if (msg.isTest) {
+            return new Response(JSON.stringify({ reply: out }), {
+                headers: { "content-type": "application/json" },
+            });
+        }
+        if (out != null && this.configured) {
+            await this.sendMessage(msg.chatId, out, opts);
+        }
+        return new Response("ok");
+    }
+    /** Send a message to a chat. No-op-safe: throws if no token is configured. */
+    async sendMessage(chatId, text, opts = {}) {
+        if (!this.token) {
+            throw new Error("Telegram: no bot token — set it with set_secret BOT_TOKEN=<token> (the deploy injects it as env.BOT_TOKEN).");
+        }
+        const body = { chat_id: chatId, text };
+        if (opts.parseMode !== null)
+            body.parse_mode = opts.parseMode ?? "Markdown";
+        if (opts.replyToMessageId)
+            body.reply_to_message_id = opts.replyToMessageId;
+        if (opts.disablePreview)
+            body.disable_web_page_preview = true;
+        const res = await fetch(`${API}${this.token}/sendMessage`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`Telegram sendMessage failed: HTTP ${res.status}`);
+    }
+    /** Register the slash-command menu (setMyCommands) — autocompletes in chat. */
+    async setMyCommands(commands) {
+        if (!this.token)
+            throw new Error("Telegram: no bot token (set_secret BOT_TOKEN=<token>).");
+        await fetch(`${API}${this.token}/setMyCommands`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ commands }),
+        });
+    }
+}

package/dist/wallet.d.ts

@@ -0,0 +1,77 @@
+import { Chain } from "./chain.js";
+import { type AbiFunction } from "./abi.js";
+import type { Hex } from "./hex.js";
+import type { Receipt } from "./chain.js";
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export interface WalletOptions {
+    /** Platform wallet API base, e.g. https://<site>/wallet. Default env WALLET_API_URL. */
+    apiUrl?: string;
+    /** Bearer scoping calls to this bot. Default env WALLET_API_TOKEN. */
+    apiToken?: string;
+}
+/** One wallet a user owns. `imported` = brought their own key (vs. HD-generated). */
+export interface WalletAccount {
+    label: string;
+    address: Hex;
+    active: boolean;
+    imported: boolean;
+}
+export interface WalletSendOptions {
+    address: Hex;
+    abi: AbiFunction[];
+    functionName: string;
+    args?: unknown[];
+    /** Native value to send with the call, in wei. */
+    value?: bigint;
+}
+/** A handle bound to a single end-user (e.g. one Telegram account). */
+export declare class UserWallet {
+    private readonly wallet;
+    /** Platform-namespaced user id, e.g. "tg:12345". */
+    readonly userKey: string;
+    constructor(wallet: Wallet, 
+    /** Platform-namespaced user id, e.g. "tg:12345". */
+    userKey: string);
+    /** Every wallet the user owns (auto-creates their default on first call). */
+    list(): Promise<WalletAccount[]>;
+    /** The user's active wallet (the one `send` signs with), auto-created if none. */
+    account(): Promise<WalletAccount>;
+    /** Shorthand for the active wallet's address. */
+    address(): Promise<Hex>;
+    /** Generate a new HD wallet (from the user's own seed) and make it active. */
+    create(label?: string): Promise<WalletAccount>;
+    /** Import an external private key and make it active. */
+    import(privateKey: string, label?: string): Promise<WalletAccount>;
+    /** Switch the active wallet by label. */
+    use(label: string): Promise<WalletAccount>;
+    /** Stop tracking a wallet by label (active reassigns to another if needed). */
+    remove(label: string): Promise<void>;
+    /** Native balance (wei) of the user's active wallet. Reads via RPC, no key. */
+    balance(): Promise<bigint>;
+    /**
+     * Sign + broadcast a state-changing call with the user's ACTIVE wallet. The
+     * calldata is encoded here; the platform signs server-side and returns the hash.
+     */
+    send(opts: WalletSendOptions): Promise<Hex>;
+}
+export declare class Wallet {
+    private readonly apiUrl?;
+    private readonly apiToken?;
+    private readonly env?;
+    private _chain?;
+    constructor(env: MinimalEnv | undefined, options?: WalletOptions);
+    /** A handle for one end-user. Pass any stable id; it's namespaced as "tg:<id>". */
+    user(id: string | number, platform?: string): UserWallet;
+    /** Lazily build a read-only Chain (for balances/receipts) from env RPC_URL. */
+    chain(): Chain;
+    /** Wait for a tx broadcast by `send` to mine. Reads via RPC, no key. */
+    waitForReceipt(hash: Hex, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<Receipt>;
+    /** Internal: POST to a wallet API sub-path with the bot bearer; throws on error. */
+    post(path: "accounts" | "sign", body: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+export {};