@livo-build/runtime 0.1.0 → 0.2.0

package/dist/chain.d.ts

@@ -94,6 +94,13 @@ export declare class Chain {
      */
     send(opts: SendOptions): Promise<Hex>;
     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

@@ -113,7 +113,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 }));
@@ -139,6 +139,15 @@ export class Chain {
     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 { 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

@@ -3,6 +3,9 @@
 // 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";
+// 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.0",
   "description": "Livo runtime — chain signing/reads, D1 state, and logging for keepers, servers, and bots.",
   "type": "module",
   "license": "UNLICENSED",