@livo-build/runtime 0.1.0

package/dist/chain.js

@@ -0,0 +1,214 @@
+// Chain — the high-leverage layer. Read and write the chain from a Worker with
+// 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 { decodeLog, encodeFilterTopics, } from "./events.js";
+import { privateKeyToAddress, signTransaction, transactionHash, } from "./tx.js";
+import { hexToBytes } from "./hex.js";
+const GWEI = 1000000000n;
+export class Chain {
+    rpcUrl;
+    privateKey;
+    _chainId;
+    opts;
+    /** The signer's address (only present when a key is configured). */
+    address;
+    /** chainId passed at construction, if any — lets bindings resolve addresses synchronously. */
+    configuredChainId;
+    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.`);
+        }
+        this.privateKey = options.privateKey ?? env?.[keyKey];
+        this.address = this.privateKey ? privateKeyToAddress(this.privateKey) : null;
+        this._chainId = options.chainId;
+        this.configuredChainId = options.chainId;
+        this.opts = {
+            defaultTipWei: options.defaultTipWei ?? (GWEI * 3n) / 2n, // 1.5 gwei
+            gasMultiplierPct: options.gasMultiplierPct ?? 120n,
+            fallbackGas: options.fallbackGas ?? 500000n,
+        };
+    }
+    // --- raw JSON-RPC ----------------------------------------------------------
+    /** Raw JSON-RPC passthrough. Throws on RPC errors with the node's message. */
+    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;
+    }
+    async getChainId() {
+        if (this._chainId === undefined) {
+            this._chainId = Number(BigInt(await this.rpc("eth_chainId")));
+        }
+        return this._chainId;
+    }
+    async getBlockNumber() {
+        return BigInt(await this.rpc("eth_blockNumber"));
+    }
+    async getBalance(address, block = "latest") {
+        return BigInt(await this.rpc("eth_getBalance", [address, block]));
+    }
+    // --- reads -----------------------------------------------------------------
+    /**
+     * Convenience read by human-readable signature, e.g.
+     *   chain.call(addr, "topicCount()(uint256)")
+     *   chain.call(addr, "balanceOf(address)(uint256)", ["0x..."])
+     */
+    async call(address, signature, args = []) {
+        const fn = functionFromSignature(signature);
+        return this.readContract({ address, abi: [fn], functionName: fn.name, args });
+    }
+    /** Typed contract read against a JSON ABI. Returns the decoded output(s). */
+    async readContract(opts) {
+        const fn = findFunction(opts.abi, opts.functionName);
+        const data = encodeFunctionData(fn, opts.args ?? []);
+        const result = await this.rpc("eth_call", [
+            { to: opts.address, data },
+            opts.block ?? "latest",
+        ]);
+        return decodeFunctionResult(fn, hexToBytes(result));
+    }
+    /** Query + decode event logs. */
+    async getLogs(opts) {
+        const topics = encodeFilterTopics(opts.event, opts.args);
+        const filter = { topics };
+        if (opts.address)
+            filter.address = opts.address;
+        filter.fromBlock = blockTag(opts.fromBlock ?? "earliest");
+        filter.toBlock = blockTag(opts.toBlock ?? "latest");
+        const raw = await this.rpc("eth_getLogs", [filter]);
+        return raw.map((l) => decodeLog(opts.event, l));
+    }
+    // --- writes ----------------------------------------------------------------
+    /** Low-level: 0x calldata for a function call (no broadcast). */
+    encodeFunction(abi, functionName, args = []) {
+        return encodeFunctionData(findFunction(abi, functionName), args);
+    }
+    /** Low-level: sign a fully-specified EIP-1559 tx, returning the raw 0x tx. */
+    signTx(tx) {
+        if (!this.privateKey)
+            throw this.noKey();
+        return signTransaction(tx, this.privateKey);
+    }
+    /**
+     * Encode → fetch nonce/fees → estimate gas (+headroom) → sign → broadcast.
+     * Returns the transaction hash. Fails loudly on a funding-less signer.
+     */
+    async send(opts) {
+        if (!this.privateKey || !this.address)
+            throw this.noKey();
+        const data = this.encodeFunction(opts.abi, opts.functionName, opts.args ?? []);
+        const value = opts.value ?? 0n;
+        const [chainId, nonce, fees] = await Promise.all([
+            this.getChainId(),
+            opts.nonce !== undefined ? Promise.resolve(opts.nonce) : this.pendingNonce(this.address),
+            this.feeData(),
+        ]);
+        const gas = opts.gas ?? (await this.estimateGas({ to: opts.address, from: this.address, data, value }));
+        const tx = {
+            chainId: BigInt(chainId),
+            nonce,
+            maxPriorityFeePerGas: opts.maxPriorityFeePerGas ?? fees.maxPriorityFeePerGas,
+            maxFeePerGas: opts.maxFeePerGas ?? fees.maxFeePerGas,
+            gas,
+            to: opts.address,
+            value,
+            data,
+        };
+        const raw = signTransaction(tx, this.privateKey);
+        try {
+            return await this.rpc("eth_sendRawTransaction", [raw]);
+        }
+        catch (err) {
+            await this.explainSendFailure(err, value, gas, tx.maxFeePerGas);
+            throw err;
+        }
+    }
+    async pendingNonce(address) {
+        return BigInt(await this.rpc("eth_getTransactionCount", [address, "pending"]));
+    }
+    /** Compute maxFee/tip: maxFee = baseFee*2 + tip, tip = configurable default. */
+    async feeData() {
+        const tip = this.opts.defaultTipWei;
+        let baseFee;
+        try {
+            const block = await this.rpc("eth_getBlockByNumber", ["latest", false]);
+            baseFee = block.baseFeePerGas ? BigInt(block.baseFeePerGas) : BigInt(await this.rpc("eth_gasPrice"));
+        }
+        catch {
+            baseFee = BigInt(await this.rpc("eth_gasPrice"));
+        }
+        return { maxFeePerGas: baseFee * 2n + tip, maxPriorityFeePerGas: tip };
+    }
+    /** estimateGas with headroom and a safe fallback when the node reverts the estimate. */
+    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) },
+            ]));
+            return (est * this.opts.gasMultiplierPct) / 100n;
+        }
+        catch {
+            return this.opts.fallbackGas;
+        }
+    }
+    // --- receipts --------------------------------------------------------------
+    async waitForReceipt(hash, opts = {}) {
+        const timeout = opts.timeoutMs ?? 120_000;
+        const poll = opts.pollMs ?? 2_000;
+        const deadline = Date.now() + timeout;
+        for (;;) {
+            const r = await this.rpc("eth_getTransactionReceipt", [hash]);
+            if (r) {
+                return {
+                    transactionHash: r.transactionHash,
+                    status: BigInt(r.status ?? "0x0") === 1n ? "success" : "reverted",
+                    blockNumber: BigInt(r.blockNumber ?? "0x0"),
+                    gasUsed: BigInt(r.gasUsed ?? "0x0"),
+                    contractAddress: r.contractAddress ?? null,
+                    raw: r,
+                };
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`waitForReceipt: ${hash} not mined within ${timeout}ms`);
+            }
+            await new Promise((res) => setTimeout(res, poll));
+        }
+    }
+    /** Compute the hash of a raw signed tx (parity with what the node returns). */
+    hashRawTx(rawTx) {
+        return transactionHash(rawTx);
+    }
+    // --- internals -------------------------------------------------------------
+    noKey() {
+        return new Error("Chain: no signer key — set the KEEPER_PRIVATE_KEY secret (or pass signerKeySecret/privateKey). Reads work without one; writes need it.");
+    }
+    async explainSendFailure(err, value, gas, maxFee) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/insufficient funds|gas \* price|exceeds.*balance/i.test(msg) && this.address) {
+            const balance = await this.getBalance(this.address).catch(() => null);
+            const needed = value + gas * maxFee;
+            throw new Error(`signer wallet ${this.address} can't afford this tx — needs ~${needed} wei` +
+                (balance !== null ? `, has ${balance} wei` : "") +
+                `. Fund it, or lower gas/value. (RPC: ${msg})`);
+        }
+    }
+}
+function blockTag(b) {
+    return typeof b === "bigint" ? `0x${b.toString(16)}` : b;
+}
+function toQuantity(v) {
+    return `0x${v.toString(16)}`;
+}

package/dist/contracts.d.ts

@@ -0,0 +1,28 @@
+import type { AbiFunction } from "./abi.js";
+import type { Chain } from "./chain.js";
+import type { Hex } from "./hex.js";
+export type AddressBook = Record<number, Record<string, string>>;
+export type AbiBook = Record<string, AbiFunction[]>;
+export interface ContractHandle {
+    readonly address: Hex;
+    readonly abi: AbiFunction[];
+    /** Read methods (eth_call) keyed by function name. */
+    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>>;
+}
+export interface ContractBinding {
+    readonly name: string;
+    /** Resolve the canonical address for a chainId (defaults to the chain's id). */
+    addressFor(chainId: number): Hex;
+    /** Bind this contract to a Chain, producing callable read/write handles. */
+    connect(chain: Chain, opts?: {
+        chainId?: number;
+        address?: Hex;
+    }): ContractHandle;
+}
+/**
+ * Build name-addressable contract bindings from generated address/ABI books.
+ * The generated bindings module calls this and exports the result as `contracts`.
+ */
+export declare function bindContracts(addresses: AddressBook, abis: AbiBook): Record<string, ContractBinding>;

package/dist/contracts.js

@@ -0,0 +1,77 @@
+// Runtime contract bindings — the consumer side of Layer 2. The platform
+// generates a sibling module (like the frontend's interface/src/livo/contracts.ts)
+// exporting `addresses` (chainId → name → address) and `abis` (name → ABI), both
+// resolved through the SAME canonical pointer the frontend uses. This module turns
+// that generated data into name-addressable, typed-ish contract handles so a keeper
+// never hardcodes an address (the divergence footgun) again.
+//
+// Generated bindings re-export `bindContracts(...)` as `contracts` so callers write:
+//   import { contracts } from "@livo/runtime/contracts";
+//   const forum = contracts.Forum.connect(chain);
+//   await forum.read.topicCount();
+//   const hash = await forum.write.createPost(topicId, body);
+function buildHandle(chain, address, abi) {
+    const read = {};
+    const write = {};
+    for (const entry of abi) {
+        if ((entry.type ?? "function") !== "function" || !entry.name)
+            continue;
+        const isView = entry.stateMutability === "view" || entry.stateMutability === "pure";
+        const name = entry.name;
+        if (isView) {
+            read[name] = (...args) => chain.readContract({ address, abi, functionName: name, args });
+        }
+        else {
+            write[name] = (...args) => chain.send({ address, abi, functionName: name, args });
+            // Allow reading a non-view fn too (e.g. simulate) — but default to write.
+            read[name] = read[name] ?? ((...args) => chain.readContract({ address, abi, functionName: name, args }));
+        }
+    }
+    return { address, abi, read, write };
+}
+/**
+ * Build name-addressable contract bindings from generated address/ABI books.
+ * The generated bindings module calls this and exports the result as `contracts`.
+ */
+export function bindContracts(addresses, abis) {
+    const out = {};
+    const names = new Set();
+    for (const chainId of Object.keys(addresses)) {
+        for (const name of Object.keys(addresses[Number(chainId)]))
+            names.add(name);
+    }
+    for (const name of names) {
+        const binding = {
+            name,
+            addressFor(chainId) {
+                const addr = addresses[chainId]?.[name];
+                if (!addr) {
+                    const known = Object.keys(addresses).join(", ");
+                    throw new Error(`No canonical address for ${name} on chain ${chainId} (have chains: ${known || "none"}).`);
+                }
+                return addr;
+            },
+            connect(chain, opts) {
+                const abi = abis[name];
+                if (!abi)
+                    throw new Error(`No ABI for contract ${name} in generated bindings.`);
+                // Resolve via the explicit override, else the configured/looked-up chainId.
+                const chainId = opts?.chainId ?? chain.configuredChainId;
+                const address = opts?.address ??
+                    (chainId !== undefined
+                        ? binding.addressFor(chainId)
+                        : singleChainAddress(addresses, name));
+                return buildHandle(chain, address, abi);
+            },
+        };
+        out[name] = binding;
+    }
+    return out;
+}
+/** When bindings cover exactly one chain, connect() can resolve without a chainId. */
+function singleChainAddress(addresses, name) {
+    const chainIds = Object.keys(addresses).filter((c) => addresses[Number(c)][name]);
+    if (chainIds.length === 1)
+        return addresses[Number(chainIds[0])][name];
+    throw new Error(`${name} is deployed on multiple chains (${chainIds.join(", ")}); pass { chainId } to connect() or set chainId on the Chain.`);
+}

package/dist/events.d.ts

@@ -0,0 +1,37 @@
+import { functionSelector, type AbiParameter } from "./abi.js";
+import { type Hex } from "./hex.js";
+export interface AbiEvent {
+    type?: "event";
+    name: string;
+    inputs: Array<AbiParameter & {
+        indexed?: boolean;
+    }>;
+    anonymous?: boolean;
+}
+export interface RawLog {
+    address: Hex;
+    topics: Hex[];
+    data: Hex;
+    blockNumber?: Hex;
+    transactionHash?: Hex;
+    logIndex?: Hex;
+}
+export interface DecodedLog extends RawLog {
+    eventName: string;
+    args: Record<string, unknown>;
+}
+/** Parse "Transfer(address indexed from, address indexed to, uint256 value)" form. */
+export declare function parseEventSignature(sig: string): AbiEvent;
+/** keccak256("Name(type,type,...)") — the topic0 for a (non-anonymous) event. */
+export declare function eventTopic(event: AbiEvent | string): Hex;
+/** Encode a single indexed value into its 32-byte topic representation. */
+export declare function encodeIndexedTopic(type: string, value: unknown): Hex;
+/**
+ * Build the topics array for an eth_getLogs filter. `args` maps indexed input
+ * names (or positions) to values; omit any to leave it unfiltered (null).
+ */
+export declare function encodeFilterTopics(event: AbiEvent | string, args?: Record<string, unknown> | unknown[]): (Hex | null)[];
+/** Decode a single raw log into named args using the event's ABI. */
+export declare function decodeLog(event: AbiEvent | string, raw: RawLog): DecodedLog;
+/** Selector-style 4-byte tag isn't used for events, but exported for parity/tests. */
+export { functionSelector };

package/dist/events.js

@@ -0,0 +1,139 @@
+// Event log helpers — topic0 computation, indexed-arg topic filters, and decoding
+// returned logs back into named args. Covers value-type indexed params (address,
+// uintN/intN, bool, bytesN); dynamic indexed params (string/bytes/arrays) are
+// matched by their keccak hash per the ABI spec but not reversibly decoded.
+import { canonicalType, decodeParameters, functionSelector, keccak256, parseType, } from "./abi.js";
+import { bytesToBigInt, bytesToBigIntSigned, bytesToHex, concatBytes, hexToBytes, toBytes, toBytesSigned, toBigInt, } from "./hex.js";
+/** Parse "Transfer(address indexed from, address indexed to, uint256 value)" form. */
+export function parseEventSignature(sig) {
+    const m = /^\s*(?:event\s+)?([a-zA-Z_$][\w$]*)\s*\(([^]*)\)\s*$/.exec(sig);
+    if (!m)
+        throw new Error(`unparseable event signature: ${sig}`);
+    const inputs = splitTop(m[2]).map((part) => {
+        const t = part.trim();
+        const indexed = /\bindexed\b/.test(t);
+        const cleaned = t.replace(/\bindexed\b/, "").trim();
+        const tokens = cleaned.split(/\s+/);
+        const type = tokens[0];
+        const name = tokens[1];
+        return { type, name, indexed };
+    });
+    return { type: "event", name: m[1], inputs };
+}
+function splitTop(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;
+        }
+    }
+    if (s.slice(start).trim())
+        out.push(s.slice(start));
+    return out;
+}
+function asEvent(event) {
+    return typeof event === "string" ? parseEventSignature(event) : event;
+}
+/** keccak256("Name(type,type,...)") — the topic0 for a (non-anonymous) event. */
+export function eventTopic(event) {
+    const e = asEvent(event);
+    const sig = `${e.name}(${e.inputs.map((i) => canonicalType(parseType(i))).join(",")})`;
+    // Reuse the selector machinery (keccak) but keep the full 32-byte hash.
+    return bytesToHex(keccak256(new TextEncoder().encode(sig)));
+}
+/** Encode a single indexed value into its 32-byte topic representation. */
+export function encodeIndexedTopic(type, value) {
+    const t = parseType(type);
+    switch (t.kind) {
+        case "uint":
+            return bytesToHex(toBytes(toBigInt(value), 32));
+        case "int":
+            return bytesToHex(toBytesSigned(toBigInt(value), 32));
+        case "bool":
+            return bytesToHex(toBytes(value ? 1n : 0n, 32));
+        case "address": {
+            const b = hexToBytes(value);
+            return bytesToHex(concatBytes(new Uint8Array(12), b));
+        }
+        case "bytesN": {
+            const b = typeof value === "string" ? hexToBytes(value) : value;
+            const out = new Uint8Array(32);
+            out.set(b, 0);
+            return bytesToHex(out);
+        }
+        case "bytes":
+        case "string": {
+            const b = typeof value === "string" && t.kind === "string"
+                ? new TextEncoder().encode(value)
+                : hexToBytes(value);
+            return bytesToHex(keccak256(b)); // dynamic indexed → hashed
+        }
+        default:
+            throw new Error(`cannot index type ${type} as a topic`);
+    }
+}
+/**
+ * Build the topics array for an eth_getLogs filter. `args` maps indexed input
+ * names (or positions) to values; omit any to leave it unfiltered (null).
+ */
+export function encodeFilterTopics(event, args) {
+    const e = asEvent(event);
+    const topics = [eventTopic(e)];
+    const indexed = e.inputs.filter((i) => i.indexed);
+    indexed.forEach((input, i) => {
+        let value = undefined;
+        if (Array.isArray(args))
+            value = args[i];
+        else if (args && input.name && input.name in args)
+            value = args[input.name];
+        topics.push(value === undefined || value === null ? null : encodeIndexedTopic(input.type, value));
+    });
+    // Trim trailing nulls so the RPC filter stays minimal.
+    while (topics.length > 1 && topics[topics.length - 1] === null)
+        topics.pop();
+    return topics;
+}
+/** Decode a single raw log into named args using the event's ABI. */
+export function decodeLog(event, raw) {
+    const e = asEvent(event);
+    const args = {};
+    const indexedInputs = e.inputs.filter((i) => i.indexed);
+    const nonIndexed = e.inputs.filter((i) => !i.indexed);
+    // Indexed args come from topics[1..]; value types are decoded, dynamic stay raw.
+    indexedInputs.forEach((input, i) => {
+        const topic = raw.topics[i + 1];
+        if (topic === undefined)
+            return;
+        const t = parseType(input.type);
+        const bytes = hexToBytes(topic);
+        const key = input.name || String(i);
+        if (t.kind === "uint")
+            args[key] = bytesToBigInt(bytes);
+        else if (t.kind === "int")
+            args[key] = bytesToBigIntSigned(bytes);
+        else if (t.kind === "bool")
+            args[key] = bytesToBigInt(bytes) !== 0n;
+        else if (t.kind === "address")
+            args[key] = bytesToHex(bytes.subarray(12));
+        else
+            args[key] = topic; // bytesN / dynamic-hashed: surface the raw topic
+    });
+    // Non-indexed args are ABI-decoded from the data blob.
+    if (nonIndexed.length > 0) {
+        const decoded = decodeParameters(nonIndexed, hexToBytes(raw.data));
+        nonIndexed.forEach((input, i) => {
+            args[input.name || `data${i}`] = decoded[i];
+        });
+    }
+    return { ...raw, eventName: e.name, args };
+}
+/** Selector-style 4-byte tag isn't used for events, but exported for parity/tests. */
+export { functionSelector };

package/dist/hex.d.ts

@@ -0,0 +1,22 @@
+export type Hex = `0x${string}`;
+export type Bytes = Uint8Array;
+/** Lowercase 0x-hex for a byte array. */
+export declare function bytesToHex(bytes: Bytes): Hex;
+/** Parse 0x-hex (or bare hex) to bytes. Odd-length input is left-padded a nibble. */
+export declare function hexToBytes(hex: string): Bytes;
+/** Concatenate byte arrays into one. */
+export declare function concatBytes(...parts: Bytes[]): Bytes;
+/** Minimal big-endian byte encoding of a non-negative integer (no leading zeros). */
+export declare function toMinimalBytes(value: bigint): Bytes;
+/** Big-endian fixed-width (default 32) byte encoding of a non-negative integer. */
+export declare function toBytes(value: bigint, width?: number): Bytes;
+/** Two's-complement 32-byte encoding of a possibly-negative integer (int256 family). */
+export declare function toBytesSigned(value: bigint, width?: number): Bytes;
+/** Decode a big-endian byte slice to a non-negative bigint. */
+export declare function bytesToBigInt(bytes: Bytes): bigint;
+/** Interpret a width-byte two's-complement slice as a signed bigint. */
+export declare function bytesToBigIntSigned(bytes: Bytes): bigint;
+/** Coerce common numeric inputs to bigint. */
+export declare function toBigInt(value: bigint | number | string): bigint;
+/** Normalize an 0x-hex string to lowercase with a guaranteed 0x prefix. */
+export declare function asHex(value: string): Hex;

package/dist/hex.js

@@ -0,0 +1,100 @@
+// Byte / hex primitives shared by the ABI coder, RLP, and the signer. No deps.
+// Everything here is allocation-light and Worker-safe (Web APIs only).
+const HEX_CHARS = "0123456789abcdef";
+/** Lowercase 0x-hex for a byte array. */
+export function bytesToHex(bytes) {
+    let out = "0x";
+    for (let i = 0; i < bytes.length; i++) {
+        out += HEX_CHARS[bytes[i] >> 4] + HEX_CHARS[bytes[i] & 15];
+    }
+    return out;
+}
+/** Parse 0x-hex (or bare hex) to bytes. Odd-length input is left-padded a nibble. */
+export function hexToBytes(hex) {
+    let h = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (h.length % 2)
+        h = "0" + h;
+    const out = new Uint8Array(h.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const byte = Number.parseInt(h.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte))
+            throw new Error(`invalid hex at byte ${i}: ${hex}`);
+        out[i] = byte;
+    }
+    return out;
+}
+/** Concatenate byte arrays into one. */
+export function concatBytes(...parts) {
+    let len = 0;
+    for (const p of parts)
+        len += p.length;
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+/** Minimal big-endian byte encoding of a non-negative integer (no leading zeros). */
+export function toMinimalBytes(value) {
+    if (value < 0n)
+        throw new Error("toMinimalBytes: negative");
+    if (value === 0n)
+        return new Uint8Array(0);
+    let hex = value.toString(16);
+    if (hex.length % 2)
+        hex = "0" + hex;
+    return hexToBytes(hex);
+}
+/** Big-endian fixed-width (default 32) byte encoding of a non-negative integer. */
+export function toBytes(value, width = 32) {
+    if (value < 0n)
+        throw new Error("toBytes: use twosComplement for negatives");
+    const out = new Uint8Array(width);
+    let v = value;
+    for (let i = width - 1; i >= 0 && v > 0n; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    if (v > 0n)
+        throw new Error(`value ${value} does not fit in ${width} bytes`);
+    return out;
+}
+/** Two's-complement 32-byte encoding of a possibly-negative integer (int256 family). */
+export function toBytesSigned(value, width = 32) {
+    const bits = BigInt(width * 8);
+    const mod = 1n << bits;
+    const v = ((value % mod) + mod) % mod; // wrap into unsigned range
+    return toBytes(v, width);
+}
+/** Decode a big-endian byte slice to a non-negative bigint. */
+export function bytesToBigInt(bytes) {
+    let out = 0n;
+    for (const b of bytes)
+        out = (out << 8n) | BigInt(b);
+    return out;
+}
+/** Interpret a width-byte two's-complement slice as a signed bigint. */
+export function bytesToBigIntSigned(bytes) {
+    const unsigned = bytesToBigInt(bytes);
+    const bits = BigInt(bytes.length * 8);
+    const signBit = 1n << (bits - 1n);
+    return unsigned >= signBit ? unsigned - (1n << bits) : unsigned;
+}
+/** Coerce common numeric inputs to bigint. */
+export function toBigInt(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isInteger(value))
+            throw new Error(`not an integer: ${value}`);
+        return BigInt(value);
+    }
+    return value.startsWith("0x") ? BigInt(value) : BigInt(value);
+}
+/** Normalize an 0x-hex string to lowercase with a guaranteed 0x prefix. */
+export function asHex(value) {
+    const h = value.startsWith("0x") ? value : `0x${value}`;
+    return h.toLowerCase();
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { Chain } from "./chain.js";
+export type { ChainOptions, SendOptions, ReadOptions, GetLogsOptions, Receipt, } from "./chain.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 { 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";
+export type { Eip1559Tx } from "./tx.js";
+export { eventTopic, encodeFilterTopics, encodeIndexedTopic, decodeLog, parseEventSignature, } from "./events.js";
+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";

package/dist/index.js

@@ -0,0 +1,16 @@
+// @livo/runtime — the standard library available to every Livo compute target
+// that isn't a contract or a static frontend (keepers, servers, bots). Named,
+// 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 } from "./chain.js";
+// Layer 3 — State + utilities.
+export { Store, STORE_TABLE } from "./store.js";
+export { log } from "./log.js";
+export { retry } from "./retry.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";

package/dist/log.d.ts

@@ -0,0 +1,8 @@
+type Fields = Record<string, unknown>;
+export declare const log: {
+    info: (msg: string, fields?: Fields) => void;
+    warn: (msg: string, fields?: Fields) => void;
+    error: (msg: string, err?: Fields | Error) => void;
+    debug: (msg: string, fields?: Fields) => void;
+};
+export {};