@livo-build/runtime 0.2.1 → 0.2.3

package/dist/wallet.js

@@ -0,0 +1,122 @@
+// Wallet — per-user custodial wallets for bots. A bot's END USERS each get their
+// own wallet(s); the bot signs on a user's behalf WITHOUT ever holding raw key
+// material. Every management + signing call goes to the platform (WALLET_API_URL,
+// authorized by WALLET_API_TOKEN, both injected at deploy); Convex resolves the
+// user's active wallet and signs server-side, so a leaked Worker never leaks keys.
+//
+//   const w = new Wallet(env);
+//   const acct = w.user(msg.from.id);        // a handle scoped to one end-user
+//   await acct.address();                    // their active wallet (auto-created)
+//   await acct.list();                       // every wallet they own
+//   await acct.import("0x<key>", "trading"); // bring your own key
+//   await acct.use("trading");               // switch the active wallet
+//   const hash = await acct.send({ address, abi, functionName, args }); // platform signs
+//
+// Reads (balance, receipts) use the injected RPC_URL via a plain Chain — no key.
+import { Chain } from "./chain.js";
+import { encodeFunctionData, findFunction } from "./abi.js";
+/** A handle bound to a single end-user (e.g. one Telegram account). */
+export class UserWallet {
+    wallet;
+    userKey;
+    constructor(wallet, 
+    /** Platform-namespaced user id, e.g. "tg:12345". */
+    userKey) {
+        this.wallet = wallet;
+        this.userKey = userKey;
+    }
+    /** Every wallet the user owns (auto-creates their default on first call). */
+    async list() {
+        const r = await this.wallet.post("accounts", { op: "list", user: this.userKey });
+        return (r.wallets ?? []);
+    }
+    /** The user's active wallet (the one `send` signs with), auto-created if none. */
+    async account() {
+        const r = await this.wallet.post("accounts", { op: "address", user: this.userKey });
+        return r.wallet;
+    }
+    /** Shorthand for the active wallet's address. */
+    async address() {
+        return (await this.account()).address;
+    }
+    /** Generate a new HD wallet (from the user's own seed) and make it active. */
+    async create(label) {
+        const r = await this.wallet.post("accounts", { op: "create", user: this.userKey, label });
+        return r.wallet;
+    }
+    /** Import an external private key and make it active. */
+    async import(privateKey, label) {
+        const r = await this.wallet.post("accounts", { op: "import", user: this.userKey, privateKey, label });
+        return r.wallet;
+    }
+    /** Switch the active wallet by label. */
+    async use(label) {
+        const r = await this.wallet.post("accounts", { op: "use", user: this.userKey, label });
+        return r.wallet;
+    }
+    /** Stop tracking a wallet by label (active reassigns to another if needed). */
+    async remove(label) {
+        await this.wallet.post("accounts", { op: "remove", user: this.userKey, label });
+    }
+    /** Native balance (wei) of the user's active wallet. Reads via RPC, no key. */
+    async balance() {
+        return this.wallet.chain().getBalance(await this.address());
+    }
+    /**
+     * Sign + broadcast a state-changing call with the user's ACTIVE wallet. The
+     * calldata is encoded here; the platform signs server-side and returns the hash.
+     */
+    async send(opts) {
+        const data = encodeFunctionData(findFunction(opts.abi, opts.functionName), opts.args ?? []);
+        const r = await this.wallet.post("sign", {
+            user: this.userKey,
+            to: opts.address,
+            data,
+            value: opts.value !== undefined ? `0x${opts.value.toString(16)}` : undefined,
+        });
+        return r.hash;
+    }
+}
+export class Wallet {
+    apiUrl;
+    apiToken;
+    env;
+    _chain;
+    constructor(env, options = {}) {
+        this.env = env;
+        this.apiUrl = (options.apiUrl ?? env?.WALLET_API_URL)?.replace(/\/$/, "");
+        this.apiToken = options.apiToken ?? env?.WALLET_API_TOKEN;
+    }
+    /** A handle for one end-user. Pass any stable id; it's namespaced as "tg:<id>". */
+    user(id, platform = "tg") {
+        const raw = String(id);
+        const userKey = /^[a-z]+:/.test(raw) ? raw : `${platform}:${raw}`;
+        return new UserWallet(this, userKey);
+    }
+    /** Lazily build a read-only Chain (for balances/receipts) from env RPC_URL. */
+    chain() {
+        if (!this._chain)
+            this._chain = new Chain(this.env);
+        return this._chain;
+    }
+    /** Wait for a tx broadcast by `send` to mine. Reads via RPC, no key. */
+    waitForReceipt(hash, opts) {
+        return this.chain().waitForReceipt(hash, opts);
+    }
+    /** Internal: POST to a wallet API sub-path with the bot bearer; throws on error. */
+    async post(path, body) {
+        if (!this.apiUrl || !this.apiToken) {
+            throw new Error("Wallet: not provisioned — WALLET_API_URL/WALLET_API_TOKEN missing (redeploy the bot so the platform injects them).");
+        }
+        const res = await fetch(`${this.apiUrl}/${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${this.apiToken}` },
+            body: JSON.stringify(body),
+        });
+        const j = (await res.json().catch(() => ({})));
+        if (!res.ok || j.error) {
+            throw new Error(`Wallet ${path}: ${String(j.message ?? j.error ?? `HTTP ${res.status}`)}`);
+        }
+        return j;
+    }
+}

package/dist/watch.d.ts

@@ -0,0 +1,44 @@
+import type { Chain } from "./chain.js";
+import type { Store } from "./store.js";
+import type { AbiEvent, DecodedLog } from "./events.js";
+import type { Hex } from "./hex.js";
+export interface WatchLogsOptions {
+    /** Event to decode — an AbiEvent or a human-readable signature. */
+    event: AbiEvent | string;
+    /** Contract address(es) to filter (omit to match any). */
+    address?: Hex | Hex[];
+    /** Indexed-arg filter, positional or by name (see Chain.getLogs). */
+    args?: Record<string, unknown> | unknown[];
+    /** Store key holding this watcher's cursor. Namespace it per watcher. */
+    cursorKey: string;
+    /** First block to scan when no cursor exists yet. Default: current head (new logs only). */
+    fromBlock?: bigint;
+    /** Stay this many blocks behind head for reorg safety. Default 0. */
+    confirmations?: bigint;
+    /** Max blocks per eth_getLogs window (RPC range cap). Default 2000n. */
+    chunkSize?: bigint;
+    /** Invoked per non-empty chunk with that chunk's decoded logs. Must be idempotent. */
+    onLogs: (logs: DecodedLog[], range: {
+        fromBlock: bigint;
+        toBlock: bigint;
+    }) => Promise<void> | void;
+}
+export interface WatchLogsResult {
+    /** First block scanned this run. */
+    fromBlock: bigint;
+    /** New cursor — the last block scanned (head - confirmations). */
+    toBlock: bigint;
+    /** Total logs delivered to onLogs this run. */
+    logCount: number;
+    /** Number of eth_getLogs windows scanned. */
+    chunks: number;
+}
+/**
+ * Catch up on event logs since the last run. Reads the cursor (or `fromBlock`),
+ * scans `[cursor, head - confirmations]` in `chunkSize` windows, calls `onLogs`
+ * per non-empty chunk, and persists the cursor AFTER each chunk — so a Worker
+ * killed mid-catch-up resumes from the last completed window. Delivery is
+ * at-least-once: if `onLogs` throws, the cursor is not advanced past that chunk
+ * and the next tick retries it, so `onLogs` must be idempotent.
+ */
+export declare function watchLogs(chain: Chain, store: Store, opts: WatchLogsOptions): Promise<WatchLogsResult>;

package/dist/watch.js

@@ -0,0 +1,46 @@
+// watchLogs — resumable event catch-up for keepers. A Worker has no long-lived
+// process, so this is NOT a websocket subscription: each scheduled tick reads new
+// logs since a Store-persisted block cursor, up to the (confirmed) head, in
+// chunked eth_getLogs windows. Layered as a free function over Chain + Store so
+// Chain (Layer 1, may hold keys) never imports Store (Layer 3).
+/**
+ * Catch up on event logs since the last run. Reads the cursor (or `fromBlock`),
+ * scans `[cursor, head - confirmations]` in `chunkSize` windows, calls `onLogs`
+ * per non-empty chunk, and persists the cursor AFTER each chunk — so a Worker
+ * killed mid-catch-up resumes from the last completed window. Delivery is
+ * at-least-once: if `onLogs` throws, the cursor is not advanced past that chunk
+ * and the next tick retries it, so `onLogs` must be idempotent.
+ */
+export async function watchLogs(chain, store, opts) {
+    const confirmations = opts.confirmations ?? 0n;
+    const chunkSize = opts.chunkSize ?? 2000n;
+    const head = await chain.getBlockNumber();
+    const safeHead = head - confirmations;
+    const stored = await store.getJSON(opts.cursorKey);
+    const from = stored ? BigInt(stored.next) : (opts.fromBlock ?? safeHead);
+    if (from > safeHead) {
+        return { fromBlock: from, toBlock: from - 1n, logCount: 0, chunks: 0 };
+    }
+    let cur = from;
+    let logCount = 0;
+    let chunks = 0;
+    while (cur <= safeHead) {
+        const to = cur + chunkSize - 1n < safeHead ? cur + chunkSize - 1n : safeHead;
+        const logs = await chain.getLogs({
+            event: opts.event,
+            address: opts.address,
+            args: opts.args,
+            fromBlock: cur,
+            toBlock: to,
+        });
+        chunks++;
+        if (logs.length) {
+            await opts.onLogs(logs, { fromBlock: cur, toBlock: to });
+            logCount += logs.length;
+        }
+        // Advance + persist only after a successful onLogs, so a throw retries this window.
+        await store.setJSON(opts.cursorKey, { next: (to + 1n).toString() });
+        cur = to + 1n;
+    }
+    return { fromBlock: from, toBlock: safeHead, logCount, chunks };
+}

package/package.json

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