@livo-build/runtime 0.2.1 → 0.2.2

package/README.md

@@ -1,13 +1,20 @@
 # @livo-build/runtime
 
-The standard library available to every Livo compute target that isn't a contract
-or a static frontend — **keepers** (cron Workers), **servers** (Durable Objects /
-long-running Workers), and **bots** (Telegram/Twitter Workers).
+The standard library for Livo compute targets that bundle npm deps at deploy —
+**keepers** (cron Workers) and **bots** (Telegram/Twitter Workers). (Servers /
+Durable Objects deploy as a single un-bundled module today, so they can't import
+this yet — use fetch + Web Crypto there; their `INDEXER_<NAME>_URL` env binding is
+still injected.)
 
 It deletes the most-repeated, most-error-prone code these targets hand-roll:
-signing and sending on-chain transactions, reading contract state, talking to D1,
-and basic logging/retry. No more hand-bundling secp256k1 to fit a single Worker
-module.
+signing and sending on-chain transactions, reading contract state, querying the
+project's subgraph, the Telegram webhook dance, talking to D1, and basic
+logging/retry. No more hand-bundling secp256k1 to fit a single Worker module.
+
+At a glance: `Chain` (read/sign/send + RPC failover), `Relayer` (managed bot
+signing), `bindContracts` (call contracts by name), `Indexer` (typed subgraph
+queries), `Telegram` (webhook plumbing in one call), `Store` (D1 KV + idempotency),
+`requireSecret`, `queue`, `retry`, `log`.
 
 ```ts
 import { Chain, Store, log } from "@livo-build/runtime";
@@ -39,7 +46,7 @@ keeper/bot/server that imports it ships a `package.json` declaring the dependenc
   audited `@noble` crypto — into one self-contained Worker module. No hand-bundling.
 - Targets with **no `package.json`** deploy exactly as before — the build step is
   opt-in by the presence of a manifest. Existing keepers keep working untouched.
-- Versions pin in `package.json` (`"@livo-build/runtime": "^0.1.0"`), so a runtime
+- Versions pin in `package.json` (`"@livo-build/runtime": "^0.2.2"`), so a runtime
   update can't silently change a working keeper.
 
 Scaffold the common path with `create_keeper --template runtime-keeper`.
@@ -65,6 +72,18 @@ chain.address; // signer address (null when read-only)
 const hash = await chain.send({ address, abi, functionName, args });
 const receipt = await chain.waitForReceipt(hash, { timeoutMs, pollMs });
 
+// reliable write — nonce resolved at broadcast, retry-on-collision + replace-by-fee
+const h = await chain.sendReliable({ address, abi, functionName, args, confirmMs: 30_000 });
+
+// batch reads — ONE eth_call via Multicall3 (allowFailure defaults true → null on revert)
+const [supply, mine] = await chain.multicall([
+  { address: token, abi, functionName: "totalSupply" },
+  { address: token, abi, functionName: "balanceOf", args: [chain.address] },
+]);
+
+// deploy a contract — to:null creation, waits for the receipt's contractAddress
+const { address: deployed } = await chain.deploy({ abi, bytecode, args: [param] });
+
 // escape hatches
 chain.encodeFunction(abi, fn, args); // 0x calldata
 chain.signTx(txFields);              // raw 0x EIP-1559 tx
@@ -101,6 +120,47 @@ const hash = await forum.write.createPost(topicId, body);
 container without the keeper's `node_modules`. `@livo-build/runtime/contracts`
 exports `bindContracts` and the binding types.)
 
+### RPC failover
+
+`Chain` accepts several endpoints and rotates past transport failures (network
+error, 5xx, 429) — a deterministic chain error (revert/nonce) is surfaced, not
+retried elsewhere:
+
+```ts
+new Chain(env, { rpcUrls: ["https://a", "https://b"] });
+new Chain(env); // or set RPC_URL to a comma/whitespace-separated list
+```
+
+## Indexer — query the project's subgraph
+
+`INDEXER_<NAME>_URL` is injected at deploy as the subgraph's **stable `live`
+alias**, so the worker never holds a version-pinned URL that breaks on the next
+`sync_indexers`/`reindex`:
+
+```ts
+import { indexer } from "@livo-build/runtime";
+const { keepers } = await indexer(env, "hearth").query(
+  `query($m:Int!){ keepers(where:{count_gte:$m}){ id count } }`, { m: 3 });
+await indexer(env, "hearth").meta(); // { block, hasIndexingErrors }
+```
+
+## Telegram — webhook plumbing in one call
+
+```ts
+import { Telegram } from "@livo-build/runtime";
+export default {
+  fetch(req, env) {
+    return new Telegram(env).handleUpdate(req, (msg) =>
+      msg.text === "/start" ? "👋 hi " + msg.handle : "you said " + msg.text);
+  },
+};
+```
+
+`handleUpdate` verifies the `WEBHOOK_SECRET` secret-token, short-circuits Livo's
+`__livo_test` harness (returns the computed reply without calling Telegram),
+parses the update, and sends the reply. Lower-level `verify` / `parse` /
+`sendMessage` / `setMyCommands` are exposed too.
+
 ## Layer 3 — State + utilities
 
 ```ts
@@ -110,10 +170,15 @@ await store.set("heartbeat", "3");
 await store.getJSON<Config>("config");
 await store.setJSON("config", obj);
 
+// Idempotency: true only the FIRST time a key is seen — a retried cron tick or a
+// redelivered webhook won't double-fire.
+if (!(await store.once(`block:${n}`))) return;
+
 log.info("posted", { tx, topicId }); // structured, consistently prefixed
 log.error("send failed", err);
 
-import { retry } from "@livo-build/runtime";
+import { requireSecret, retry } from "@livo-build/runtime";
+const apiKey = requireSecret(env, "SOME_API_KEY"); // loud error if missing, not silent undefined
 await retry(() => chain.send(...), { tries: 3, backoffMs: 500 }); // flaky RPCs
 ```
 
@@ -121,6 +186,55 @@ await retry(() => chain.send(...), { tries: 3, backoffMs: 500 }); // flaky RPCs
 is `livo_kv(k TEXT PRIMARY KEY, v TEXT, updated_at INTEGER)` — stable and
 documented.
 
+## Watching events — `watchLogs`
+
+A Worker has no long-lived process, so this is **catch-up per scheduled tick**, not
+a websocket subscription. It reads new logs since a `Store`-persisted block cursor,
+up to the (confirmed) head, in chunked `eth_getLogs` windows:
+
+```ts
+import { watchLogs } from "@livo-build/runtime";
+
+await watchLogs(chain, store, {
+  event: "Transfer(address indexed from, address indexed to, uint256 value)",
+  address: token,                 // optional filter
+  cursorKey: "transfers",         // namespaced Store cursor
+  confirmations: 2n,              // reorg safety (default 0)
+  chunkSize: 2000n,               // match your RPC's eth_getLogs range cap
+  onLogs: async (logs, range) => { /* idempotent! at-least-once delivery */ },
+});
+```
+
+The cursor advances **after** each successful `onLogs`, so a throw retries that
+window on the next tick — `onLogs` must be idempotent. First run defaults to "from
+head" (new logs only); pass `fromBlock` to backfill.
+
+## Bots — `Relayer`
+
+`Relayer extends Chain`: same read/write/multicall surface, but it signs with the
+custodied **`RELAYER_PRIVATE_KEY`** (not the keeper key) and — when the platform
+injects `RELAYER_NONCE_URL` + `RELAYER_NONCE_TOKEN` — serializes nonces through
+Convex so concurrent bot invocations sharing one managed key don't collide
+(falling back to RPC pending otherwise). Scaffold with `create_bot --template
+relayer-bot`.
+
+```ts
+import { Relayer, log } from "@livo-build/runtime";
+const relayer = new Relayer(env);                 // RELAYER_PRIVATE_KEY
+const hash = await relayer.send({ address, abi, functionName, args });
+```
+
+## Queues
+
+Publish to a per-project queue from any deployable that declares `produces: [name]`
+(the platform injects `QUEUE_<NAME>_URL` + `QUEUE_<NAME>_TOKEN`):
+
+```ts
+import { queue } from "@livo-build/runtime";       // or new Queue(env, "settler")
+await queue(env, "settler").send({ orderId });
+await queue(env, "settler").sendBatch([{ a: 1 }, { a: 2 }]);
+```
+
 ## Local testing
 
 Everything runs in Node with a mocked `env` — no platform involved. See
@@ -137,3 +251,7 @@ npm run build       # tsc → dist/*.js + .d.ts (what npm consumers install)
 Legacy pre-1559 txs, multi-chain abstraction beyond a chainId, account
 abstraction / paymasters, anything non-EVM. Added later only when a second real
 use case demands it.
+
+> Agent-facing copy of this reference lives at the MCP resource
+> **`livo://skill/runtime`**; `test/skill-coverage.test.ts` fails CI if a public
+> export here isn't documented there, so the two can't drift.

package/dist/chain.d.ts

@@ -1,15 +1,18 @@
-import { type AbiFunction } from "./abi.js";
+import { type AbiFunction, type AbiParameter } from "./abi.js";
 import { type AbiEvent, type DecodedLog } from "./events.js";
 import { type Eip1559Tx } from "./tx.js";
+import { type MulticallCall, type MulticallOptions } from "./multicall.js";
 import { type Hex } from "./hex.js";
 export declare function isNonceCollision(err: unknown): boolean;
 export interface ChainOptions {
-    /** env key holding the JSON-RPC URL. Default "RPC_URL". */
+    /** env key holding the JSON-RPC URL(s). One URL, or several comma/whitespace-separated for failover. Default "RPC_URL". */
     rpcUrlSecret?: string;
     /** env key holding the 0x signer private key. Omit for read-only usage. Default "KEEPER_PRIVATE_KEY". */
     signerKeySecret?: string;
     /** Override the RPC URL directly (takes precedence over env). */
     rpcUrl?: string;
+    /** Override with several RPC URLs for failover (takes precedence over env + rpcUrl). */
+    rpcUrls?: string[];
     /** Override the private key directly (takes precedence over env). */
     privateKey?: string;
     /** Override chainId (otherwise read from the RPC on first send). */
@@ -72,11 +75,40 @@ export interface Receipt {
     contractAddress: Hex | null;
     raw: Record<string, unknown>;
 }
+/** A constructor entry has no `name`, so it doesn't fit AbiFunction — accept either. */
+type ConstructorEntry = {
+    type: "constructor";
+    inputs?: AbiParameter[];
+    stateMutability?: string;
+};
+export interface DeployOptions {
+    /** Full contract ABI — only the `constructor` entry is read (for arg encoding). */
+    abi: ReadonlyArray<AbiFunction | ConstructorEntry>;
+    /** Creation bytecode, 0x-prefixed. */
+    bytecode: Hex;
+    /** Constructor args, ABI-encoded against the constructor's inputs and appended. */
+    args?: unknown[];
+    value?: bigint;
+    /** Override gas (skips estimateGas — recommended for large contracts). */
+    gas?: bigint;
+    nonce?: bigint;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+    /** Receipt wait timeout, ms. Default 120_000. */
+    timeoutMs?: number;
+    /** Receipt poll interval, ms. Default 2_000. */
+    pollMs?: number;
+}
 interface MinimalEnv {
     [key: string]: unknown;
 }
 export declare class Chain {
+    /** Primary RPC URL (first of `rpcUrls`). Kept for back-compat. */
     readonly rpcUrl: string;
+    /** All configured RPC URLs, tried in rotation with failover on transport errors. */
+    readonly rpcUrls: string[];
+    /** Rotating start offset so load spreads across endpoints. */
+    private rpcCursor;
     private readonly privateKey?;
     private _chainId?;
     private readonly opts;
@@ -85,7 +117,13 @@ export declare class Chain {
     /** chainId passed at construction, if any — lets bindings resolve addresses synchronously. */
     readonly configuredChainId?: number;
     constructor(env: MinimalEnv | undefined, options?: ChainOptions);
-    /** Raw JSON-RPC passthrough. Throws on RPC errors with the node's message. */
+    /**
+     * Raw JSON-RPC passthrough. Throws on RPC errors with the node's message.
+     * With multiple `rpcUrls`, a TRANSPORT failure (network error, 5xx, 429) on one
+     * endpoint rotates to the next; a JSON-level `error` (a deterministic chain
+     * response, e.g. revert/nonce) is returned as-is — retrying elsewhere wouldn't
+     * change it. The start endpoint rotates per call to spread load.
+     */
     rpc<T = unknown>(method: string, params?: unknown[]): Promise<T>;
     getChainId(): Promise<number>;
     getBlockNumber(): Promise<bigint>;
@@ -100,6 +138,13 @@ export declare class Chain {
     readContract(opts: ReadOptions): Promise<unknown>;
     /** Query + decode event logs. */
     getLogs(opts: GetLogsOptions): Promise<DecodedLog[]>;
+    /**
+     * Batch many contract reads into ONE eth_call via Multicall3 (aggregate3).
+     * Results are positionally aligned with `calls`; a reverting call yields null
+     * when allowFailure (default true) or throws otherwise. All calls observe the
+     * same block, so the batch is atomic/consistent.
+     */
+    multicall(calls: MulticallCall[], opts?: MulticallOptions): Promise<(unknown | null)[]>;
     /** Low-level: 0x calldata for a function call (no broadcast). */
     encodeFunction(abi: AbiFunction[], functionName: string, args?: unknown[]): Hex;
     /** Low-level: sign a fully-specified EIP-1559 tx, returning the raw 0x tx. */
@@ -109,6 +154,17 @@ export declare class Chain {
      * Returns the transaction hash. Fails loudly on a funding-less signer.
      */
     send(opts: SendOptions): Promise<Hex>;
+    /**
+     * Deploy a contract: build a creation tx (to:null, data = bytecode ++ encoded
+     * constructor args), sign + broadcast on the same nonce/fee/gas path as send(),
+     * wait for the receipt, and return the deployed address. Note: the default
+     * fallbackGas (500k) is low for real contracts — pass `gas` for large ones.
+     */
+    deploy(opts: DeployOptions): Promise<{
+        address: Hex;
+        hash: Hex;
+        receipt: Receipt;
+    }>;
     /**
      * Optimistic reliable send (docs/WALLET-SPEC.md "optimistic, assigned at
      * broadcast"). Resolves the nonce at broadcast (never pre-allocated), retries on a
@@ -132,9 +188,10 @@ export declare class Chain {
         maxFeePerGas: bigint;
         maxPriorityFeePerGas: bigint;
     }>;
-    /** estimateGas with headroom and a safe fallback when the node reverts the estimate. */
+    /** estimateGas with headroom and a safe fallback when the node reverts the estimate.
+     *  `to: null` estimates a contract-creation tx (the `to` field is omitted). */
     estimateGas(tx: {
-        to: Hex;
+        to: Hex | null;
         from: Hex;
         data: Hex;
         value: bigint;

package/dist/chain.js

@@ -2,10 +2,11 @@
 // zero hand-rolled crypto or ABI. Constructed from the keeper/server/bot `env`:
 // reads RPC_URL and (for writes) a signing key, both as env bindings injected at
 // deploy. Reads need no key; writes derive the signer address from the key.
-import { decodeFunctionResult, encodeFunctionData, findFunction, functionFromSignature, } from "./abi.js";
+import { decodeFunctionResult, encodeFunctionData, encodeParameters, findFunction, functionFromSignature, } from "./abi.js";
 import { decodeLog, encodeFilterTopics, } from "./events.js";
 import { privateKeyToAddress, signTransaction, transactionHash, } from "./tx.js";
-import { hexToBytes } from "./hex.js";
+import { multicall as multicallImpl } from "./multicall.js";
+import { bytesToHex, concatBytes, hexToBytes } from "./hex.js";
 const GWEI = 1000000000n;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Classify an RPC error as a nonce collision — another sender took the nonce we
@@ -20,8 +21,16 @@ export function isNonceCollision(err) {
         m.includes("known transaction") ||
         m.includes("replacement transaction underpriced"));
 }
+function findConstructor(abi) {
+    return abi.find((e) => e.type === "constructor");
+}
 export class Chain {
+    /** Primary RPC URL (first of `rpcUrls`). Kept for back-compat. */
     rpcUrl;
+    /** All configured RPC URLs, tried in rotation with failover on transport errors. */
+    rpcUrls;
+    /** Rotating start offset so load spreads across endpoints. */
+    rpcCursor = 0;
     privateKey;
     _chainId;
     opts;
@@ -32,10 +41,20 @@ export class Chain {
     constructor(env, options = {}) {
         const rpcKey = options.rpcUrlSecret ?? "RPC_URL";
         const keyKey = options.signerKeySecret ?? "KEEPER_PRIVATE_KEY";
-        this.rpcUrl = options.rpcUrl ?? env?.[rpcKey] ?? "";
-        if (!this.rpcUrl) {
-            throw new Error(`Chain: no RPC URL — set the ${rpcKey} secret (set_secret ${rpcKey}=<https rpc>) or pass rpcUrl.`);
+        // URL sources, in precedence order: rpcUrls[] → rpcUrl → env (which may itself
+        // hold several comma/whitespace-separated URLs). Failover rotates across them.
+        const fromEnv = env?.[rpcKey] ?? "";
+        this.rpcUrls = (options.rpcUrls && options.rpcUrls.length
+            ? options.rpcUrls
+            : options.rpcUrl
+                ? [options.rpcUrl]
+                : fromEnv.split(/[\s,]+/))
+            .map((u) => u.trim())
+            .filter(Boolean);
+        if (!this.rpcUrls.length) {
+            throw new Error(`Chain: no RPC URL — set the ${rpcKey} secret (set_secret ${rpcKey}=<https rpc>) or pass rpcUrl/rpcUrls.`);
         }
+        this.rpcUrl = this.rpcUrls[0];
         this.privateKey = options.privateKey ?? env?.[keyKey];
         this.address = this.privateKey ? privateKeyToAddress(this.privateKey) : null;
         this._chainId = options.chainId;
@@ -47,19 +66,46 @@ export class Chain {
         };
     }
     // --- raw JSON-RPC ----------------------------------------------------------
-    /** Raw JSON-RPC passthrough. Throws on RPC errors with the node's message. */
+    /**
+     * Raw JSON-RPC passthrough. Throws on RPC errors with the node's message.
+     * With multiple `rpcUrls`, a TRANSPORT failure (network error, 5xx, 429) on one
+     * endpoint rotates to the next; a JSON-level `error` (a deterministic chain
+     * response, e.g. revert/nonce) is returned as-is — retrying elsewhere wouldn't
+     * change it. The start endpoint rotates per call to spread load.
+     */
     async rpc(method, params = []) {
-        const res = await fetch(this.rpcUrl, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
-        });
-        if (!res.ok)
-            throw new Error(`RPC ${method} HTTP ${res.status}`);
-        const json = (await res.json());
-        if (json.error)
-            throw new Error(`RPC ${method} error ${json.error.code}: ${json.error.message}`);
-        return json.result;
+        const body = JSON.stringify({ jsonrpc: "2.0", id: 1, method, params });
+        const n = this.rpcUrls.length;
+        const start = this.rpcCursor++ % n;
+        let lastErr;
+        for (let i = 0; i < n; i++) {
+            const url = this.rpcUrls[(start + i) % n];
+            try {
+                const res = await fetch(url, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body,
+                });
+                // Retry-worthy HTTP statuses → try the next endpoint.
+                if (res.status >= 500 || res.status === 429) {
+                    lastErr = new Error(`RPC ${method} HTTP ${res.status}`);
+                    continue;
+                }
+                if (!res.ok)
+                    throw new Error(`RPC ${method} HTTP ${res.status}`);
+                const json = (await res.json());
+                if (json.error)
+                    throw new Error(`RPC ${method} error ${json.error.code}: ${json.error.message}`);
+                return json.result;
+            }
+            catch (err) {
+                // A 4xx (other than 429) or chain-level error is deterministic — surface it.
+                if (err instanceof Error && /HTTP 4|RPC .* error /.test(err.message))
+                    throw err;
+                lastErr = err; // network/transport error → failover to the next endpoint
+            }
+        }
+        throw lastErr ?? new Error(`RPC ${method} failed on all ${n} endpoint(s)`);
     }
     async getChainId() {
         if (this._chainId === undefined) {
@@ -104,6 +150,15 @@ export class Chain {
         const raw = await this.rpc("eth_getLogs", [filter]);
         return raw.map((l) => decodeLog(opts.event, l));
     }
+    /**
+     * Batch many contract reads into ONE eth_call via Multicall3 (aggregate3).
+     * Results are positionally aligned with `calls`; a reverting call yields null
+     * when allowFailure (default true) or throws otherwise. All calls observe the
+     * same block, so the batch is atomic/consistent.
+     */
+    multicall(calls, opts) {
+        return multicallImpl(this, calls, opts);
+    }
     // --- writes ----------------------------------------------------------------
     /** Low-level: 0x calldata for a function call (no broadcast). */
     encodeFunction(abi, functionName, args = []) {
@@ -149,6 +204,54 @@ export class Chain {
             throw err;
         }
     }
+    /**
+     * Deploy a contract: build a creation tx (to:null, data = bytecode ++ encoded
+     * constructor args), sign + broadcast on the same nonce/fee/gas path as send(),
+     * wait for the receipt, and return the deployed address. Note: the default
+     * fallbackGas (500k) is low for real contracts — pass `gas` for large ones.
+     */
+    async deploy(opts) {
+        if (!this.privateKey || !this.address)
+            throw this.noKey();
+        const ctor = findConstructor(opts.abi);
+        const args = opts.args ?? [];
+        if (args.length && !ctor) {
+            throw new Error("deploy: constructor args provided but the ABI has no constructor entry.");
+        }
+        const encodedArgs = args.length ? encodeParameters(ctor?.inputs ?? [], args) : new Uint8Array(0);
+        const data = bytesToHex(concatBytes(hexToBytes(opts.bytecode), encodedArgs));
+        const value = opts.value ?? 0n;
+        const [chainId, nonce, fees] = await Promise.all([
+            this.getChainId(),
+            opts.nonce !== undefined ? Promise.resolve(opts.nonce) : this.nextNonce(this.address),
+            this.feeData(),
+        ]);
+        const gas = opts.gas ?? (await this.estimateGas({ to: null, from: this.address, data, value }));
+        const tx = {
+            chainId: BigInt(chainId),
+            nonce,
+            maxPriorityFeePerGas: opts.maxPriorityFeePerGas ?? fees.maxPriorityFeePerGas,
+            maxFeePerGas: opts.maxFeePerGas ?? fees.maxFeePerGas,
+            gas,
+            to: null,
+            value,
+            data,
+        };
+        const raw = signTransaction(tx, this.privateKey);
+        let hash;
+        try {
+            hash = await this.rpc("eth_sendRawTransaction", [raw]);
+        }
+        catch (err) {
+            await this.explainSendFailure(err, value, gas, tx.maxFeePerGas);
+            throw err;
+        }
+        const receipt = await this.waitForReceipt(hash, { timeoutMs: opts.timeoutMs, pollMs: opts.pollMs });
+        if (receipt.status === "reverted" || !receipt.contractAddress) {
+            throw new Error(`deploy: creation tx ${hash} ${receipt.status === "reverted" ? "reverted" : "produced no contract address"}.`);
+        }
+        return { address: receipt.contractAddress, hash, receipt };
+    }
     /**
      * Optimistic reliable send (docs/WALLET-SPEC.md "optimistic, assigned at
      * broadcast"). Resolves the nonce at broadcast (never pre-allocated), retries on a
@@ -243,12 +346,14 @@ export class Chain {
         }
         return { maxFeePerGas: baseFee * 2n + tip, maxPriorityFeePerGas: tip };
     }
-    /** estimateGas with headroom and a safe fallback when the node reverts the estimate. */
+    /** estimateGas with headroom and a safe fallback when the node reverts the estimate.
+     *  `to: null` estimates a contract-creation tx (the `to` field is omitted). */
     async estimateGas(tx) {
         try {
-            const est = BigInt(await this.rpc("eth_estimateGas", [
-                { to: tx.to, from: tx.from, data: tx.data, value: toQuantity(tx.value) },
-            ]));
+            const call = { from: tx.from, data: tx.data, value: toQuantity(tx.value) };
+            if (tx.to !== null)
+                call.to = tx.to;
+            const est = BigInt(await this.rpc("eth_estimateGas", [call]));
             return (est * this.opts.gasMultiplierPct) / 100n;
         }
         catch {

package/dist/contracts.d.ts

@@ -1,8 +1,15 @@
 import type { AbiFunction } from "./abi.js";
 import type { Chain } from "./chain.js";
+import type { MulticallOptions } from "./multicall.js";
 import type { Hex } from "./hex.js";
 export type AddressBook = Record<number, Record<string, string>>;
 export type AbiBook = Record<string, AbiFunction[]>;
+/** A read on this handle to batch through multicall (function + args). */
+export interface HandleMulticallRead {
+    functionName: string;
+    args?: unknown[];
+    allowFailure?: boolean;
+}
 export interface ContractHandle {
     readonly address: Hex;
     readonly abi: AbiFunction[];
@@ -10,6 +17,8 @@ export interface ContractHandle {
     read: Record<string, (...args: unknown[]) => Promise<unknown>>;
     /** Write methods (sign + eth_sendRawTransaction) keyed by function name; returns tx hash. */
     write: Record<string, (...args: unknown[]) => Promise<Hex>>;
+    /** Batch several reads on THIS contract into one eth_call (Multicall3). */
+    multicallRead(calls: HandleMulticallRead[], opts?: MulticallOptions): Promise<(unknown | null)[]>;
 }
 export interface ContractBinding {
     readonly name: string;
@@ -21,6 +30,16 @@ export interface ContractBinding {
         address?: Hex;
     }): ContractHandle;
 }
+/**
+ * Batch reads across DIFFERENT bound contracts into one eth_call. Each entry
+ * names a connected handle + a function on it; results are positionally aligned.
+ */
+export declare function multicallContracts(chain: Chain, calls: Array<{
+    handle: ContractHandle;
+    functionName: string;
+    args?: unknown[];
+    allowFailure?: boolean;
+}>, opts?: MulticallOptions): Promise<(unknown | null)[]>;
 /**
  * Build name-addressable contract bindings from generated address/ABI books.
  * The generated bindings module calls this and exports the result as `contracts`.

package/dist/contracts.js

@@ -27,7 +27,21 @@ function buildHandle(chain, address, abi) {
             read[name] = read[name] ?? ((...args) => chain.readContract({ address, abi, functionName: name, args }));
         }
     }
-    return { address, abi, read, write };
+    const multicallRead = (calls, opts) => chain.multicall(calls.map((c) => ({ address, abi, functionName: c.functionName, args: c.args, allowFailure: c.allowFailure })), opts);
+    return { address, abi, read, write, multicallRead };
+}
+/**
+ * Batch reads across DIFFERENT bound contracts into one eth_call. Each entry
+ * names a connected handle + a function on it; results are positionally aligned.
+ */
+export function multicallContracts(chain, calls, opts) {
+    return chain.multicall(calls.map((c) => ({
+        address: c.handle.address,
+        abi: c.handle.abi,
+        functionName: c.functionName,
+        args: c.args,
+        allowFailure: c.allowFailure,
+    })), opts);
 }
 /**
  * Build name-addressable contract bindings from generated address/ABI books.

package/dist/index.d.ts

@@ -1,12 +1,22 @@
 export { Chain, isNonceCollision } from "./chain.js";
-export type { ChainOptions, SendOptions, SendReliableOptions, ReadOptions, GetLogsOptions, Receipt, } from "./chain.js";
+export type { ChainOptions, SendOptions, SendReliableOptions, ReadOptions, GetLogsOptions, Receipt, DeployOptions, } from "./chain.js";
+export { multicall, MULTICALL3_ADDRESS } from "./multicall.js";
+export type { MulticallCall, MulticallOptions } from "./multicall.js";
+export { watchLogs } from "./watch.js";
+export type { WatchLogsOptions, WatchLogsResult } from "./watch.js";
 export { Relayer } from "./relayer.js";
+export { Queue, queue, queueEnvKey } from "./queue.js";
 export type { RelayerOptions } from "./relayer.js";
+export { Indexer, indexer, indexerEnvKey, GraphQLError } from "./indexer.js";
+export type { IndexerOptions } from "./indexer.js";
+export { Telegram } from "./telegram.js";
+export type { TelegramOptions, BotMessage, SendMessageOptions } from "./telegram.js";
 export { Store, STORE_TABLE } from "./store.js";
 export type { D1Like } from "./store.js";
 export { log } from "./log.js";
 export { retry } from "./retry.js";
 export type { RetryOptions } from "./retry.js";
+export { requireSecret, requireSecrets, getSecret } from "./secret.js";
 export { encodeFunctionData, encodeParameters, decodeParameters, decodeFunctionResult, functionSelector, functionSignature, functionFromSignature, parseSignature, findFunction, keccak256, } from "./abi.js";
 export type { AbiFunction, AbiParameter, ParsedSignature } from "./abi.js";
 export { signTransaction, transactionHashToSign, transactionHash, privateKeyToAddress, toChecksumAddress, } from "./tx.js";
@@ -15,5 +25,5 @@ export { eventTopic, encodeFilterTopics, encodeIndexedTopic, decodeLog, parseEve
 export type { AbiEvent, RawLog, DecodedLog } from "./events.js";
 export { bytesToHex, hexToBytes, concatBytes, toBigInt, } from "./hex.js";
 export type { Hex, Bytes } from "./hex.js";
-export { bindContracts } from "./contracts.js";
-export type { ContractBinding, ContractHandle, AddressBook, AbiBook } from "./contracts.js";
+export { bindContracts, multicallContracts } from "./contracts.js";
+export type { ContractBinding, ContractHandle, HandleMulticallRead, AddressBook, AbiBook, } from "./contracts.js";

package/dist/index.js

@@ -3,17 +3,28 @@
 // tree-shakeable exports; keep the core small and auditable (it may hold keys).
 // Layer 1 — Chain: sign + send + read with zero hand-rolled crypto/ABI.
 export { Chain, isNonceCollision } from "./chain.js";
+// Multicall — batch reads into one eth_call (Multicall3 aggregate3).
+export { multicall, MULTICALL3_ADDRESS } from "./multicall.js";
+// watchLogs — resumable, cursor-persisted event catch-up for keepers.
+export { watchLogs } from "./watch.js";
 // Relayer — managed signing for bots (custodied RELAYER_PRIVATE_KEY + optional
 // Convex-serialized nonces). A Chain that defaults to the relayer key.
 export { Relayer } from "./relayer.js";
+export { Queue, queue, queueEnvKey } from "./queue.js";
+// Indexer — typed GraphQL client for a project's Goldsky subgraph (reads the
+// stable `live`-alias endpoint injected as INDEXER_<NAME>_URL).
+export { Indexer, indexer, indexerEnvKey, GraphQLError } from "./indexer.js";
+// Telegram — webhook verification + reply plumbing for bots.
+export { Telegram } from "./telegram.js";
 // Layer 3 — State + utilities.
 export { Store, STORE_TABLE } from "./store.js";
 export { log } from "./log.js";
 export { retry } from "./retry.js";
+export { requireSecret, requireSecrets, getSecret } from "./secret.js";
 // Low-level escape hatches — ABI coding, signing, RLP, hex. Power users only.
 export { encodeFunctionData, encodeParameters, decodeParameters, decodeFunctionResult, functionSelector, functionSignature, functionFromSignature, parseSignature, findFunction, keccak256, } from "./abi.js";
 export { signTransaction, transactionHashToSign, transactionHash, privateKeyToAddress, toChecksumAddress, } from "./tx.js";
 export { eventTopic, encodeFilterTopics, encodeIndexedTopic, decodeLog, parseEventSignature, } from "./events.js";
 export { bytesToHex, hexToBytes, concatBytes, toBigInt, } from "./hex.js";
 // Layer 2 — generated contract bindings live in "@livo/runtime/contracts".
-export { bindContracts } from "./contracts.js";
+export { bindContracts, multicallContracts } from "./contracts.js";