@livo-build/runtime 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# @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).
+
+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.
+
+```ts
+import { Chain, Store, log } from "@livo-build/runtime";
+
+export default {
+  async scheduled(event, env, ctx) {
+    const chain = new Chain(env); // reads RPC_URL + KEEPER_PRIVATE_KEY from env
+    const count = await chain.call(FORUM, "topicCount()(uint256)");
+    const hash = await chain.send({ address: FORUM, abi: FORUM_ABI, functionName: "createPost", args: [count, "gm"] });
+    const receipt = await chain.waitForReceipt(hash);
+    log.info("posted", { hash, status: receipt.status });
+  },
+};
+```
+
+## Delivery model — explicit import, registry-installed, bundled at deploy
+
+You write **normal imported code** that is locally runnable and type-checked. The
+Livo deploy step produces the self-contained single-module Worker the platform
+requires. There are **no ambient globals** — what you read in the source is what
+runs.
+
+`@livo-build/runtime` is published to npm (like `@livo-build/livo`). A
+keeper/bot/server that imports it ships a `package.json` declaring the dependency:
+
+- On deploy, the presence of a `package.json` with deps routes the target through
+  the platform's existing **build container** (`npm install` + `esbuild`), which
+  resolves `@livo-build/runtime` from the registry and bundles it — plus its
+  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
+  update can't silently change a working keeper.
+
+Scaffold the common path with `create_keeper --template runtime-keeper`.
+
+## Layer 1 — `Chain`
+
+Reads need no key; writes need a signer key on `env`.
+
+```ts
+const chain = new Chain(env, {
+  rpcUrlSecret: "RPC_URL",               // default
+  signerKeySecret: "KEEPER_PRIVATE_KEY", // omit for read-only
+});
+
+// reads
+await chain.call(address, "balanceOf(address)(uint256)", [who]);
+await chain.readContract({ address, abi, functionName, args });
+await chain.getLogs({ address, event: "Transfer(address indexed from, address indexed to, uint256 value)", args: { from }, fromBlock });
+await chain.getBalance(addr);
+chain.address; // signer address (null when read-only)
+
+// writes — encode → nonce(pending) → fees → estimateGas(+20%) → sign EIP-1559 → broadcast
+const hash = await chain.send({ address, abi, functionName, args });
+const receipt = await chain.waitForReceipt(hash, { timeoutMs, pollMs });
+
+// escape hatches
+chain.encodeFunction(abi, fn, args); // 0x calldata
+chain.signTx(txFields);              // raw 0x EIP-1559 tx
+chain.rpc(method, params);           // raw JSON-RPC
+```
+
+Defaults (configurable): nonce `pending`; `tip = 1.5 gwei`; `maxFee = baseFee*2 +
+tip`; `estimateGas * 1.2` with a `500_000` fallback when the node reverts the
+estimate. A funding-less signer fails loudly: *"signer wallet 0x… can't afford
+this tx — needs ~N wei, has M wei."*
+
+Encoding and signing are validated **byte-for-byte against viem** in CI
+(`test/abi.test.ts`, `test/tx.test.ts`). EIP-1559 (type-2) only for v1.
+
+## Layer 2 — Contract bindings
+
+`sync_contract_bindings` emits a pure-data bindings module —
+`keepers/_livo/contracts.js` — from the **same canonical pointer (`pickCanonical`)
+the frontend's `interface/src/livo/contracts.ts` uses**, so runtime and UI can
+never watch different deployments. Feed it to `bindContracts` for
+name-addressable, typed contract handles:
+
+```ts
+import { Chain, bindContracts } from "@livo-build/runtime";
+import { addresses, abis } from "../_livo/contracts.js"; // generated, canonical
+
+const contracts = bindContracts(addresses, abis);
+const forum = contracts.Forum.connect(chain); // address resolved from the canonical registry
+await forum.read.topicCount();
+const hash = await forum.write.createPost(topicId, body);
+```
+
+(The module is pure data and dependency-free so it resolves in the deploy build
+container without the keeper's `node_modules`. `@livo-build/runtime/contracts`
+exports `bindContracts` and the binding types.)
+
+## Layer 3 — State + utilities
+
+```ts
+const store = new Store(env.DB);     // typed KV over D1; auto-creates `livo_kv`
+await store.get("heartbeat");        // string | null
+await store.set("heartbeat", "3");
+await store.getJSON<Config>("config");
+await store.setJSON("config", obj);
+
+log.info("posted", { tx, topicId }); // structured, consistently prefixed
+log.error("send failed", err);
+
+import { retry } from "@livo-build/runtime";
+await retry(() => chain.send(...), { tries: 3, backoffMs: 500 }); // flaky RPCs
+```
+
+`Store` replaces the hand-rolled `CREATE TABLE IF NOT EXISTS kv (k,v)`. The table
+is `livo_kv(k TEXT PRIMARY KEY, v TEXT, updated_at INTEGER)` — stable and
+documented.
+
+## Local testing
+
+Everything runs in Node with a mocked `env` — no platform involved. See
+`test/keeper-harness.test.ts` for the template: a fake JSON-RPC handler, an
+in-memory D1, and a real keeper handler driven end-to-end.
+
+```sh
+npm test            # vitest: viem-equivalence + keeper harness
+npm run build       # tsc → dist/*.js + .d.ts (what npm consumers install)
+```
+
+## Out of scope (v1)
+
+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.

package/dist/abi.d.ts

@@ -0,0 +1,58 @@
+import { type Bytes, type Hex } from "./hex.js";
+export interface AbiParameter {
+    type: string;
+    name?: string;
+    components?: AbiParameter[];
+}
+export interface AbiFunction {
+    type?: "function";
+    name: string;
+    inputs?: AbiParameter[];
+    outputs?: AbiParameter[];
+    stateMutability?: string;
+}
+type ParsedType = {
+    kind: "uint" | "int";
+    bits: number;
+} | {
+    kind: "address" | "bool" | "bytes" | "string";
+} | {
+    kind: "bytesN";
+    size: number;
+} | {
+    kind: "array";
+    element: ParsedType;
+    length: number | null;
+} | {
+    kind: "tuple";
+    components: ParsedType[];
+    names?: string[];
+};
+declare function parseType(input: string | AbiParameter): ParsedType;
+declare function isDynamic(t: ParsedType): boolean;
+/** Encode a parameter list to ABI bytes. Accepts type strings or JSON-ABI params. */
+export declare function encodeParameters(params: (string | AbiParameter)[], values: unknown[]): Bytes;
+declare function canonicalType(t: ParsedType): string;
+/** keccak256 of UTF-8 input as bytes. */
+export declare function keccak256(data: Bytes): Bytes;
+/** The 4-byte selector for a canonical signature like "transfer(address,uint256)". */
+export declare function functionSelector(signature: string): Bytes;
+/** Build the canonical "name(type,type)" signature from a parsed function. */
+export declare function functionSignature(fn: AbiFunction): string;
+/** Resolve a function from a JSON ABI by name (first match). */
+export declare function findFunction(abi: AbiFunction[], name: string): AbiFunction;
+/** 0x calldata = selector ++ encoded args, from a JSON-ABI function. */
+export declare function encodeFunctionData(fn: AbiFunction, args?: unknown[]): Hex;
+/** Decode an ABI-encoded return blob against a parameter list. */
+export declare function decodeParameters(params: (string | AbiParameter)[], data: Bytes): unknown[];
+/** Decode a function's outputs from a call result. Returns the single value when there's one output. */
+export declare function decodeFunctionResult(fn: AbiFunction, data: Bytes): unknown;
+export interface ParsedSignature {
+    name: string;
+    inputs: string[];
+    outputs: string[];
+}
+export declare function parseSignature(sig: string): ParsedSignature;
+/** Build a JSON-ABI function from a human-readable signature. */
+export declare function functionFromSignature(sig: string): AbiFunction;
+export { parseType, canonicalType, isDynamic };

package/dist/abi.js

@@ -0,0 +1,373 @@
+// Solidity ABI coder — encoding + decoding for the type set keepers actually use:
+// uintN / intN, address, bool, bytesN, bytes, string, fixed/dynamic arrays, and
+// tuples (structs), nested arbitrarily. Validated byte-for-byte against viem in
+// the test suite. The encoder is the hand-rolled-ABI footgun this runtime removes.
+import { keccak_256 } from "@noble/hashes/sha3";
+import { bytesToBigInt, bytesToBigIntSigned, bytesToHex, concatBytes, hexToBytes, toBytes, toBytesSigned, toBigInt, } from "./hex.js";
+const TUPLE_RE = /^\((.*)\)((?:\[\d*\])*)$/;
+const ARRAY_RE = /^(.*)\[(\d*)\]$/;
+/** Split a comma-separated tuple body, respecting nested parentheses/brackets. */
+function splitTopLevel(s) {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === "(" || c === "[")
+            depth++;
+        else if (c === ")" || c === "]")
+            depth--;
+        else if (c === "," && depth === 0) {
+            out.push(s.slice(start, i));
+            start = i + 1;
+        }
+    }
+    const last = s.slice(start);
+    if (last.trim() !== "" || out.length > 0)
+        out.push(last);
+    return out.map((x) => x.trim()).filter((x) => x.length > 0);
+}
+function parseType(input) {
+    // JSON-ABI tuple carries its shape in `components`.
+    if (typeof input !== "string") {
+        if (input.type.startsWith("tuple")) {
+            const inner = {
+                kind: "tuple",
+                components: (input.components ?? []).map(parseType),
+                names: (input.components ?? []).map((c) => c.name ?? ""),
+            };
+            const suffix = input.type.slice("tuple".length);
+            return suffix ? wrapArrays(inner, suffix) : inner;
+        }
+        return parseType(input.type);
+    }
+    const str = input.trim();
+    const arr = ARRAY_RE.exec(str);
+    if (arr) {
+        return {
+            kind: "array",
+            element: parseType(arr[1]),
+            length: arr[2] === "" ? null : Number(arr[2]),
+        };
+    }
+    const tup = TUPLE_RE.exec(str);
+    if (tup) {
+        const components = splitTopLevel(tup[1]).map(parseType);
+        const base = { kind: "tuple", components };
+        return tup[2] ? wrapArrays(base, tup[2]) : base;
+    }
+    if (str === "address" || str === "bool" || str === "bytes" || str === "string") {
+        return { kind: str };
+    }
+    if (str === "uint")
+        return { kind: "uint", bits: 256 };
+    if (str === "int")
+        return { kind: "int", bits: 256 };
+    let m = /^uint(\d+)$/.exec(str);
+    if (m)
+        return { kind: "uint", bits: Number(m[1]) };
+    m = /^int(\d+)$/.exec(str);
+    if (m)
+        return { kind: "int", bits: Number(m[1]) };
+    m = /^bytes(\d+)$/.exec(str);
+    if (m)
+        return { kind: "bytesN", size: Number(m[1]) };
+    throw new Error(`unsupported ABI type: ${str}`);
+}
+/** Apply trailing `[..]` array suffixes (outermost last) to a base type. */
+function wrapArrays(base, suffix) {
+    const dims = [];
+    const re = /\[(\d*)\]/g;
+    let m;
+    while ((m = re.exec(suffix)))
+        dims.push(m[1] === "" ? null : Number(m[1]));
+    // First-found dim is the innermost in Solidity type syntax (T[a][b] = (T[a])[b]).
+    let t = base;
+    for (const length of dims)
+        t = { kind: "array", element: t, length };
+    return t;
+}
+function isDynamic(t) {
+    switch (t.kind) {
+        case "bytes":
+        case "string":
+            return true;
+        case "array":
+            return t.length === null || isDynamic(t.element);
+        case "tuple":
+            return t.components.some(isDynamic);
+        default:
+            return false;
+    }
+}
+function encodeValue(t, value) {
+    switch (t.kind) {
+        case "uint":
+            return { dynamic: false, bytes: toBytes(toBigInt(value), 32) };
+        case "int":
+            return { dynamic: false, bytes: toBytesSigned(toBigInt(value), 32) };
+        case "bool":
+            return { dynamic: false, bytes: toBytes(value ? 1n : 0n, 32) };
+        case "address": {
+            const b = hexToBytes(value);
+            if (b.length !== 20)
+                throw new Error(`address must be 20 bytes: ${value}`);
+            return { dynamic: false, bytes: concatBytes(new Uint8Array(12), b) };
+        }
+        case "bytesN": {
+            const b = typeof value === "string" ? hexToBytes(value) : value;
+            if (b.length !== t.size)
+                throw new Error(`bytes${t.size} expects ${t.size} bytes, got ${b.length}`);
+            const out = new Uint8Array(32);
+            out.set(b, 0); // right-padded
+            return { dynamic: false, bytes: out };
+        }
+        case "bytes": {
+            const b = typeof value === "string" ? hexToBytes(value) : value;
+            return { dynamic: true, bytes: encodeBytesLike(b) };
+        }
+        case "string": {
+            const b = new TextEncoder().encode(value);
+            return { dynamic: true, bytes: encodeBytesLike(b) };
+        }
+        case "array": {
+            const items = value;
+            if (t.length !== null && items.length !== t.length)
+                throw new Error(`expected ${t.length} elements, got ${items.length}`);
+            const body = encodeTuple(items.map(() => t.element), items);
+            if (t.length === null) {
+                // dynamic array: length prefix + packed body
+                return { dynamic: true, bytes: concatBytes(toBytes(BigInt(items.length), 32), body) };
+            }
+            return { dynamic: isDynamic(t.element), bytes: body };
+        }
+        case "tuple": {
+            const vals = tupleValuesInOrder(t, value);
+            const body = encodeTuple(t.components, vals);
+            return { dynamic: isDynamic(t), bytes: body };
+        }
+    }
+}
+/** Accept a tuple value as an array (positional) or an object keyed by component name. */
+function tupleValuesInOrder(t, value) {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === "object") {
+        const names = t.names;
+        if (!names || names.some((n) => !n)) {
+            throw new Error("tuple passed as object but its ABI components are unnamed — pass an array");
+        }
+        return names.map((n) => value[n]);
+    }
+    throw new Error(`tuple value must be an array or object, got ${typeof value}`);
+}
+function encodeBytesLike(b) {
+    const padded = new Uint8Array(Math.ceil(b.length / 32) * 32);
+    padded.set(b, 0);
+    return concatBytes(toBytes(BigInt(b.length), 32), padded);
+}
+/** Head/tail encode a fixed list of typed values (the core ABI algorithm). */
+function encodeTuple(types, values) {
+    if (types.length !== values.length)
+        throw new Error(`arity mismatch: ${types.length} types vs ${values.length} values`);
+    const parts = types.map((t, i) => encodeValue(t, values[i]));
+    let headLen = 0;
+    for (const p of parts)
+        headLen += p.dynamic ? 32 : p.bytes.length;
+    const heads = [];
+    const tails = [];
+    let tailOffset = headLen;
+    for (const p of parts) {
+        if (p.dynamic) {
+            heads.push(toBytes(BigInt(tailOffset), 32));
+            tails.push(p.bytes);
+            tailOffset += p.bytes.length;
+        }
+        else {
+            heads.push(p.bytes);
+        }
+    }
+    return concatBytes(...heads, ...tails);
+}
+/** Encode a parameter list to ABI bytes. Accepts type strings or JSON-ABI params. */
+export function encodeParameters(params, values) {
+    return encodeTuple(params.map(parseType), values);
+}
+// --- function selectors / calldata -------------------------------------------
+function canonicalType(t) {
+    switch (t.kind) {
+        case "uint":
+            return `uint${t.bits}`;
+        case "int":
+            return `int${t.bits}`;
+        case "bytesN":
+            return `bytes${t.size}`;
+        case "address":
+        case "bool":
+        case "bytes":
+        case "string":
+            return t.kind;
+        case "array":
+            return `${canonicalType(t.element)}[${t.length ?? ""}]`;
+        case "tuple":
+            return `(${t.components.map(canonicalType).join(",")})`;
+    }
+}
+/** keccak256 of UTF-8 input as bytes. */
+export function keccak256(data) {
+    return keccak_256(data);
+}
+/** The 4-byte selector for a canonical signature like "transfer(address,uint256)". */
+export function functionSelector(signature) {
+    return keccak_256(new TextEncoder().encode(signature)).slice(0, 4);
+}
+/** Build the canonical "name(type,type)" signature from a parsed function. */
+export function functionSignature(fn) {
+    const inputs = (fn.inputs ?? []).map((p) => canonicalType(parseType(p)));
+    return `${fn.name}(${inputs.join(",")})`;
+}
+/** Resolve a function from a JSON ABI by name (first match). */
+export function findFunction(abi, name) {
+    const fn = abi.find((e) => (e.type === "function" || e.type === undefined) && e.name === name);
+    if (!fn)
+        throw new Error(`function "${name}" not found in ABI`);
+    return fn;
+}
+/** 0x calldata = selector ++ encoded args, from a JSON-ABI function. */
+export function encodeFunctionData(fn, args = []) {
+    const selector = functionSelector(functionSignature(fn));
+    const encoded = encodeParameters(fn.inputs ?? [], args);
+    return bytesToHex(concatBytes(selector, encoded));
+}
+function decodeValue(t, state, baseOffset, headOffset) {
+    const slot = state.data.subarray(headOffset, headOffset + 32);
+    switch (t.kind) {
+        case "uint":
+            return { value: bytesToBigInt(slot), nextHead: headOffset + 32 };
+        case "int":
+            return { value: bytesToBigIntSigned(slot), nextHead: headOffset + 32 };
+        case "bool":
+            return { value: bytesToBigInt(slot) !== 0n, nextHead: headOffset + 32 };
+        case "address":
+            return { value: bytesToHex(slot.subarray(12)), nextHead: headOffset + 32 };
+        case "bytesN":
+            return { value: bytesToHex(slot.subarray(0, t.size)), nextHead: headOffset + 32 };
+        case "bytes":
+        case "string": {
+            const ptr = baseOffset + Number(bytesToBigInt(slot));
+            const len = Number(bytesToBigInt(state.data.subarray(ptr, ptr + 32)));
+            const raw = state.data.subarray(ptr + 32, ptr + 32 + len);
+            const value = t.kind === "string" ? new TextDecoder().decode(raw) : bytesToHex(raw);
+            return { value, nextHead: headOffset + 32 };
+        }
+        case "array": {
+            if (t.length === null) {
+                const ptr = baseOffset + Number(bytesToBigInt(slot));
+                const len = Number(bytesToBigInt(state.data.subarray(ptr, ptr + 32)));
+                const elemBase = ptr + 32;
+                const value = decodeFixedSequence(Array(len).fill(t.element), state, elemBase);
+                return { value, nextHead: headOffset + 32 };
+            }
+            if (isDynamic(t.element)) {
+                const ptr = baseOffset + Number(bytesToBigInt(slot));
+                const value = decodeFixedSequence(Array(t.length).fill(t.element), state, ptr);
+                return { value, nextHead: headOffset + 32 };
+            }
+            // static fixed array: inline, consumes length*32(ish) bytes of head
+            const types = Array(t.length).fill(t.element);
+            const { values, consumed } = decodeInlineSequence(types, state, baseOffset, headOffset);
+            return { value: values, nextHead: headOffset + consumed };
+        }
+        case "tuple": {
+            if (isDynamic(t)) {
+                const ptr = baseOffset + Number(bytesToBigInt(slot));
+                const value = decodeFixedSequence(t.components, state, ptr);
+                return { value: tupleToObject(t, value), nextHead: headOffset + 32 };
+            }
+            const { values, consumed } = decodeInlineSequence(t.components, state, baseOffset, headOffset);
+            return { value: tupleToObject(t, values), nextHead: headOffset + consumed };
+        }
+    }
+}
+function tupleToObject(t, values) {
+    if (!t.names || t.names.every((n) => !n))
+        return values;
+    const obj = {};
+    t.components.forEach((_, i) => {
+        if (t.names[i])
+            obj[t.names[i]] = values[i];
+    });
+    return obj;
+}
+/** Decode a sequence laid out with its own head starting at `base` (offsets relative to base). */
+function decodeFixedSequence(types, state, base) {
+    const out = [];
+    let head = base;
+    for (const t of types) {
+        const { value, nextHead } = decodeValue(t, state, base, head);
+        out.push(value);
+        head = nextHead;
+    }
+    return out;
+}
+/** Decode static types inline within an enclosing head (no new base). */
+function decodeInlineSequence(types, state, base, start) {
+    const out = [];
+    let head = start;
+    for (const t of types) {
+        const { value, nextHead } = decodeValue(t, state, base, head);
+        out.push(value);
+        head = nextHead;
+    }
+    return { values: out, consumed: head - start };
+}
+/** Decode an ABI-encoded return blob against a parameter list. */
+export function decodeParameters(params, data) {
+    const types = params.map(parseType);
+    return decodeFixedSequence(types, { data }, 0);
+}
+/** Decode a function's outputs from a call result. Returns the single value when there's one output. */
+export function decodeFunctionResult(fn, data) {
+    const outputs = fn.outputs ?? [];
+    const decoded = decodeParameters(outputs, data);
+    return outputs.length === 1 ? decoded[0] : decoded;
+}
+export function parseSignature(sig) {
+    const m = /^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(([^]*)$/.exec(sig);
+    if (!m)
+        throw new Error(`unparseable signature: ${sig}`);
+    const name = m[1];
+    // Re-find the two top-level paren groups from the original string.
+    const rest = sig.slice(sig.indexOf("(")).trim();
+    const groups = [];
+    let depth = 0;
+    let start = -1;
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === "(") {
+            if (depth === 0)
+                start = i + 1;
+            depth++;
+        }
+        else if (rest[i] === ")") {
+            depth--;
+            if (depth === 0)
+                groups.push(rest.slice(start, i));
+        }
+    }
+    return {
+        name,
+        inputs: groups[0] !== undefined ? splitTopLevel(groups[0]) : [],
+        outputs: groups[1] !== undefined ? splitTopLevel(groups[1]) : [],
+    };
+}
+/** Build a JSON-ABI function from a human-readable signature. */
+export function functionFromSignature(sig) {
+    const p = parseSignature(sig);
+    return {
+        type: "function",
+        name: p.name,
+        inputs: p.inputs.map((type) => ({ type })),
+        outputs: p.outputs.map((type) => ({ type })),
+    };
+}
+export { parseType, canonicalType, isDynamic };

package/dist/chain.d.ts

@@ -0,0 +1,118 @@
+import { type AbiFunction } from "./abi.js";
+import { type AbiEvent, type DecodedLog } from "./events.js";
+import { type Eip1559Tx } from "./tx.js";
+import { type Hex } from "./hex.js";
+export interface ChainOptions {
+    /** env key holding the JSON-RPC URL. 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 the private key directly (takes precedence over env). */
+    privateKey?: string;
+    /** Override chainId (otherwise read from the RPC on first send). */
+    chainId?: number;
+    /** Default tip in wei (maxPriorityFeePerGas). Default 1.5 gwei. */
+    defaultTipWei?: bigint;
+    /** Gas estimate multiplier in percent. Default 120 (20% headroom). */
+    gasMultiplierPct?: bigint;
+    /** Fallback gas limit when estimateGas reverts. Default 500_000. */
+    fallbackGas?: bigint;
+}
+export interface SendOptions {
+    address: Hex;
+    abi: AbiFunction[];
+    functionName: string;
+    args?: unknown[];
+    value?: bigint;
+    /** Override nonce (default: pending count). */
+    nonce?: bigint;
+    /** Override gas limit (skips estimateGas). */
+    gas?: bigint;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+}
+export interface ReadOptions {
+    address: Hex;
+    abi: AbiFunction[];
+    functionName: string;
+    args?: unknown[];
+    /** Block tag for the call. Default "latest". */
+    block?: Hex | "latest" | "pending";
+}
+export interface GetLogsOptions {
+    address?: Hex | Hex[];
+    event: AbiEvent | string;
+    args?: Record<string, unknown> | unknown[];
+    fromBlock?: bigint | "latest" | "earliest";
+    toBlock?: bigint | "latest" | "earliest";
+}
+export interface Receipt {
+    transactionHash: Hex;
+    status: "success" | "reverted";
+    blockNumber: bigint;
+    gasUsed: bigint;
+    contractAddress: Hex | null;
+    raw: Record<string, unknown>;
+}
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export declare class Chain {
+    readonly rpcUrl: string;
+    private readonly privateKey?;
+    private _chainId?;
+    private readonly opts;
+    /** The signer's address (only present when a key is configured). */
+    readonly address: Hex | null;
+    /** 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. */
+    rpc<T = unknown>(method: string, params?: unknown[]): Promise<T>;
+    getChainId(): Promise<number>;
+    getBlockNumber(): Promise<bigint>;
+    getBalance(address: Hex, block?: Hex | "latest" | "pending"): Promise<bigint>;
+    /**
+     * Convenience read by human-readable signature, e.g.
+     *   chain.call(addr, "topicCount()(uint256)")
+     *   chain.call(addr, "balanceOf(address)(uint256)", ["0x..."])
+     */
+    call(address: Hex, signature: string, args?: unknown[]): Promise<unknown>;
+    /** Typed contract read against a JSON ABI. Returns the decoded output(s). */
+    readContract(opts: ReadOptions): Promise<unknown>;
+    /** Query + decode event logs. */
+    getLogs(opts: GetLogsOptions): Promise<DecodedLog[]>;
+    /** 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. */
+    signTx(tx: Eip1559Tx): Hex;
+    /**
+     * Encode → fetch nonce/fees → estimate gas (+headroom) → sign → broadcast.
+     * Returns the transaction hash. Fails loudly on a funding-less signer.
+     */
+    send(opts: SendOptions): Promise<Hex>;
+    pendingNonce(address: Hex): Promise<bigint>;
+    /** Compute maxFee/tip: maxFee = baseFee*2 + tip, tip = configurable default. */
+    feeData(): Promise<{
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    }>;
+    /** estimateGas with headroom and a safe fallback when the node reverts the estimate. */
+    estimateGas(tx: {
+        to: Hex;
+        from: Hex;
+        data: Hex;
+        value: bigint;
+    }): Promise<bigint>;
+    waitForReceipt(hash: Hex, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<Receipt>;
+    /** Compute the hash of a raw signed tx (parity with what the node returns). */
+    hashRawTx(rawTx: Hex): Hex;
+    private noKey;
+    private explainSendFailure;
+}
+export {};