@livo-build/runtime 0.2.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,6 +109,16 @@ 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

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;
@@ -136,6 +149,75 @@ 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"]));
     }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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";

package/dist/index.js

@@ -2,7 +2,7 @@
 // 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";

package/package.json

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