@livo-build/runtime 0.1.0 → 0.2.1

package/dist/chain.d.ts

@@ -2,6 +2,7 @@ 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 declare function isNonceCollision(err: unknown): boolean;
 export interface ChainOptions {
     /** env key holding the JSON-RPC URL. Default "RPC_URL". */
     rpcUrlSecret?: string;
@@ -33,6 +34,21 @@ export interface SendOptions {
     maxFeePerGas?: bigint;
     maxPriorityFeePerGas?: bigint;
 }
+export interface SendReliableOptions extends SendOptions {
+    /** Max broadcast attempts on a nonce collision (re-reads pending each retry). Default 5. */
+    maxAttempts?: number;
+    /** Delay between collision retries, ms. Default 250 (0 in tests). */
+    retryDelayMs?: number;
+    /** If set, wait this long for the tx to mine; if it doesn't, rebroadcast at the
+     *  SAME nonce with a bumped fee (replacement). Default: don't wait, return the hash. */
+    confirmMs?: number;
+    /** Receipt poll interval while waiting, ms. Default 2000. */
+    pollMs?: number;
+    /** Max fee-bump replacements when confirmMs elapses with no receipt. Default 3. */
+    maxReplacements?: number;
+    /** Fee bump per replacement, percent (must clear the node's ~10% min). Default 15. */
+    bumpPct?: bigint;
+}
 export interface ReadOptions {
     address: Hex;
     abi: AbiFunction[];
@@ -93,7 +109,24 @@ export declare class Chain {
      * Returns the transaction hash. Fails loudly on a funding-less signer.
      */
     send(opts: SendOptions): Promise<Hex>;
+    /**
+     * Optimistic reliable send (docs/WALLET-SPEC.md "optimistic, assigned at
+     * broadcast"). Resolves the nonce at broadcast (never pre-allocated), retries on a
+     * nonce collision by re-reading the pending count, and — when confirmMs is set —
+     * waits for the receipt and rebroadcasts at the SAME nonce with a bumped fee if the
+     * tx is stuck. Returns the hash of the (last) broadcast.
+     */
+    sendReliable(opts: SendReliableOptions): Promise<Hex>;
+    /** Poll eth_getTransactionReceipt until mined or the timeout elapses (null). */
+    waitReceipt(hash: Hex, timeoutMs: number, pollMs?: number): Promise<Receipt | null>;
     pendingNonce(address: Hex): Promise<bigint>;
+    /**
+     * The nonce to use for the next send (when the caller didn't pin one). Defaults
+     * to the RPC pending count — fine for a single signer. Subclasses (see Relayer)
+     * override this to serialize nonces across concurrent invocations that share one
+     * managed signing key, which the per-Worker RPC count alone can't coordinate.
+     */
+    protected nextNonce(address: Hex): Promise<bigint>;
     /** Compute maxFee/tip: maxFee = baseFee*2 + tip, tip = configurable default. */
     feeData(): Promise<{
         maxFeePerGas: bigint;

package/dist/chain.js

@@ -7,6 +7,19 @@ import { decodeLog, encodeFilterTopics, } from "./events.js";
 import { privateKeyToAddress, signTransaction, transactionHash, } from "./tx.js";
 import { 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
+// used, or our tx is already in the mempool. The optimistic sender treats these as
+// "re-read the pending count and try again" rather than a hard failure.
+export function isNonceCollision(err) {
+    const m = String(err?.message ?? err).toLowerCase();
+    return (m.includes("nonce too low") ||
+        m.includes("nonce has already been used") ||
+        m.includes("already known") ||
+        m.includes("already imported") ||
+        m.includes("known transaction") ||
+        m.includes("replacement transaction underpriced"));
+}
 export class Chain {
     rpcUrl;
     privateKey;
@@ -113,7 +126,7 @@ export class Chain {
         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),
+            opts.nonce !== undefined ? Promise.resolve(opts.nonce) : this.nextNonce(this.address),
             this.feeData(),
         ]);
         const gas = opts.gas ?? (await this.estimateGas({ to: opts.address, from: this.address, data, value }));
@@ -136,9 +149,87 @@ export class Chain {
             throw err;
         }
     }
+    /**
+     * Optimistic reliable send (docs/WALLET-SPEC.md "optimistic, assigned at
+     * broadcast"). Resolves the nonce at broadcast (never pre-allocated), retries on a
+     * nonce collision by re-reading the pending count, and — when confirmMs is set —
+     * waits for the receipt and rebroadcasts at the SAME nonce with a bumped fee if the
+     * tx is stuck. Returns the hash of the (last) broadcast.
+     */
+    async sendReliable(opts) {
+        if (!this.privateKey || !this.address)
+            throw this.noKey();
+        const maxAttempts = Math.max(1, opts.maxAttempts ?? 5);
+        const retryDelayMs = opts.retryDelayMs ?? 250;
+        const maxReplacements = Math.max(0, opts.maxReplacements ?? 3);
+        const pollMs = opts.pollMs ?? 2000;
+        const bumpPct = opts.bumpPct ?? 15n;
+        const fees = await this.feeData();
+        let maxFeePerGas = opts.maxFeePerGas ?? fees.maxFeePerGas;
+        let maxPriorityFeePerGas = opts.maxPriorityFeePerGas ?? fees.maxPriorityFeePerGas;
+        // Resolve the nonce ONCE, at broadcast — so a stuck tx can be replaced at the
+        // same nonce. On a collision we re-read it (someone else advanced the account).
+        let nonce = opts.nonce ?? (await this.nextNonce(this.address));
+        let hash;
+        for (let attempt = 0;; attempt++) {
+            try {
+                hash = await this.send({ ...opts, nonce, maxFeePerGas, maxPriorityFeePerGas });
+                break;
+            }
+            catch (err) {
+                if (isNonceCollision(err) && attempt < maxAttempts - 1) {
+                    if (retryDelayMs > 0)
+                        await sleep(retryDelayMs);
+                    nonce = await this.pendingNonce(this.address);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        if (!opts.confirmMs)
+            return hash;
+        for (let rep = 0;; rep++) {
+            const receipt = await this.waitReceipt(hash, opts.confirmMs, pollMs);
+            if (receipt || rep >= maxReplacements)
+                return hash;
+            // Stuck: bump the fee and rebroadcast at the SAME nonce (replacement tx).
+            maxFeePerGas = (maxFeePerGas * (100n + bumpPct)) / 100n;
+            maxPriorityFeePerGas = (maxPriorityFeePerGas * (100n + bumpPct)) / 100n;
+            try {
+                hash = await this.send({ ...opts, nonce, maxFeePerGas, maxPriorityFeePerGas });
+            }
+            catch (err) {
+                // "nonce too low" here means the original mined while we waited — done.
+                if (isNonceCollision(err))
+                    return hash;
+                throw err;
+            }
+        }
+    }
+    /** Poll eth_getTransactionReceipt until mined or the timeout elapses (null). */
+    async waitReceipt(hash, timeoutMs, pollMs = 2000) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const r = await this.rpc("eth_getTransactionReceipt", [hash]);
+            if (r)
+                return r;
+            if (Date.now() >= deadline)
+                return null;
+            await sleep(Math.max(0, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
+        }
+    }
     async pendingNonce(address) {
         return BigInt(await this.rpc("eth_getTransactionCount", [address, "pending"]));
     }
+    /**
+     * The nonce to use for the next send (when the caller didn't pin one). Defaults
+     * to the RPC pending count — fine for a single signer. Subclasses (see Relayer)
+     * override this to serialize nonces across concurrent invocations that share one
+     * managed signing key, which the per-Worker RPC count alone can't coordinate.
+     */
+    nextNonce(address) {
+        return this.pendingNonce(address);
+    }
     /** Compute maxFee/tip: maxFee = baseFee*2 + tip, tip = configurable default. */
     async feeData() {
         const tip = this.opts.defaultTipWei;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-export { Chain } from "./chain.js";
-export type { ChainOptions, SendOptions, ReadOptions, GetLogsOptions, Receipt, } from "./chain.js";
+export { Chain, isNonceCollision } from "./chain.js";
+export type { ChainOptions, SendOptions, SendReliableOptions, ReadOptions, GetLogsOptions, Receipt, } from "./chain.js";
+export { Relayer } from "./relayer.js";
+export type { RelayerOptions } from "./relayer.js";
 export { Store, STORE_TABLE } from "./store.js";
 export type { D1Like } from "./store.js";
 export { log } from "./log.js";

package/dist/index.js

@@ -2,7 +2,10 @@
 // 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";
+export { Chain, isNonceCollision } from "./chain.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";
 // Layer 3 — State + utilities.
 export { Store, STORE_TABLE } from "./store.js";
 export { log } from "./log.js";

package/dist/relayer.d.ts

@@ -0,0 +1,20 @@
+import { Chain, type ChainOptions } from "./chain.js";
+import type { Hex } from "./hex.js";
+export interface RelayerOptions extends ChainOptions {
+    /** Convex /relayer/nonce endpoint. Default: env RELAYER_NONCE_URL. */
+    nonceUrl?: string;
+    /** Bearer scoping the nonce allocation to this bot. Default: env RELAYER_NONCE_TOKEN. */
+    nonceToken?: string;
+}
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export declare class Relayer extends Chain {
+    private readonly nonceUrl?;
+    private readonly nonceToken?;
+    constructor(env: MinimalEnv | undefined, options?: RelayerOptions);
+    /** True when this relayer will serialize nonces through Convex (vs. RPC pending). */
+    get serializesNonce(): boolean;
+    protected nextNonce(address: Hex): Promise<bigint>;
+}
+export {};

package/dist/relayer.js

@@ -0,0 +1,54 @@
+// Relayer — the managed signing layer for bots. A bot's relayer wallet is a
+// platform-custodied key (a SEPARATE key from the project's keeper, so a bot and
+// a keeper never collide on the same address's nonce), injected at deploy as the
+// RELAYER_PRIVATE_KEY binding. So a bot just does `new Relayer(env).send(...)` —
+// no key handling, no faucet ritual, no hand-rolled crypto.
+//
+// When the platform also injects RELAYER_NONCE_URL + RELAYER_NONCE_TOKEN, the
+// relayer asks Convex for a *serialized* nonce before each send. Convex mutations
+// are serializable, so two concurrent bot invocations sharing one relayer key get
+// strictly increasing nonces instead of both reading the same RPC pending count
+// and colliding. With the bindings absent (e.g. local dev), it transparently
+// falls back to the RPC pending count — same behavior as a plain Chain.
+import { Chain } from "./chain.js";
+export class Relayer extends Chain {
+    nonceUrl;
+    nonceToken;
+    constructor(env, options = {}) {
+        const { nonceUrl, nonceToken, ...chainOpts } = options;
+        // The relayer key is the signer by default — NOT the keeper key.
+        super(env, { signerKeySecret: chainOpts.signerKeySecret ?? "RELAYER_PRIVATE_KEY", ...chainOpts });
+        this.nonceUrl = nonceUrl ?? env?.RELAYER_NONCE_URL;
+        this.nonceToken = nonceToken ?? env?.RELAYER_NONCE_TOKEN;
+    }
+    /** True when this relayer will serialize nonces through Convex (vs. RPC pending). */
+    get serializesNonce() {
+        return Boolean(this.nonceUrl && this.nonceToken);
+    }
+    // Ask Convex for the next serialized nonce, passing the RPC pending count so the
+    // server-side counter self-heals when the wallet advanced out-of-band. Any
+    // failure (no bindings, network, non-200) falls back to the RPC pending count —
+    // the relayer never blocks on the coordinator being reachable.
+    async nextNonce(address) {
+        const observedPending = await this.pendingNonce(address);
+        if (!this.nonceUrl || !this.nonceToken)
+            return observedPending;
+        try {
+            const chainId = await this.getChainId();
+            const res = await fetch(this.nonceUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${this.nonceToken}` },
+                body: JSON.stringify({ address, chainId, observedPending: Number(observedPending) }),
+            });
+            if (res.ok) {
+                const j = (await res.json());
+                if (j.ok && typeof j.nonce === "number" && j.nonce >= 0)
+                    return BigInt(j.nonce);
+            }
+        }
+        catch {
+            /* fall through to the RPC pending count */
+        }
+        return observedPending;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livo-build/runtime",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Livo runtime — chain signing/reads, D1 state, and logging for keepers, servers, and bots.",
   "type": "module",
   "license": "UNLICENSED",