@livo-build/runtime 0.2.2 → 0.2.3

package/README.md

@@ -12,7 +12,8 @@ project's subgraph, the Telegram webhook dance, talking to D1, and basic
 logging/retry. No more hand-bundling secp256k1 to fit a single Worker module.
 
 At a glance: `Chain` (read/sign/send + RPC failover), `Relayer` (managed bot
-signing), `bindContracts` (call contracts by name), `Indexer` (typed subgraph
+signing), `Wallet` (per-user custodial wallets, server-side custody),
+`bindContracts` (call contracts by name), `Indexer` (typed subgraph
 queries), `Telegram` (webhook plumbing in one call), `Store` (D1 KV + idempotency),
 `requireSecret`, `queue`, `retry`, `log`.
 
@@ -46,7 +47,7 @@ keeper/bot/server that imports it ships a `package.json` declaring the dependenc
   audited `@noble` crypto — into one self-contained Worker module. No hand-bundling.
 - Targets with **no `package.json`** deploy exactly as before — the build step is
   opt-in by the presence of a manifest. Existing keepers keep working untouched.
-- Versions pin in `package.json` (`"@livo-build/runtime": "^0.2.2"`), so a runtime
+- Versions pin in `package.json` (`"@livo-build/runtime": "^0.2.3"`), so a runtime
   update can't silently change a working keeper.
 
 Scaffold the common path with `create_keeper --template runtime-keeper`.
@@ -215,8 +216,7 @@ head" (new logs only); pass `fromBlock` to backfill.
 custodied **`RELAYER_PRIVATE_KEY`** (not the keeper key) and — when the platform
 injects `RELAYER_NONCE_URL` + `RELAYER_NONCE_TOKEN` — serializes nonces through
 Convex so concurrent bot invocations sharing one managed key don't collide
-(falling back to RPC pending otherwise). Scaffold with `create_bot --template
-relayer-bot`.
+(falling back to RPC pending otherwise).
 
 ```ts
 import { Relayer, log } from "@livo-build/runtime";
@@ -224,6 +224,28 @@ const relayer = new Relayer(env);                 // RELAYER_PRIVATE_KEY
 const hash = await relayer.send({ address, abi, functionName, args });
 ```
 
+## Bots — `Wallet` (per-user custodial wallets)
+
+`Wallet` gives each **end user** their own wallet(s). The bot signs on a user's
+behalf **without ever holding key material**: every call hits the platform
+(`WALLET_API_URL` + `WALLET_API_TOKEN`, auto-injected), which custodies a
+per-`(project, user)` seed and signs server-side. Generated wallets derive from
+the user's own seed (isolated from the project's platform mnemonic and from other
+users); imported wallets store an encrypted raw key. This is the sanctioned
+wallet primitive — don't hand-roll key storage. Scaffold with `create_bot
+--template wallet-bot` (the default).
+
+```ts
+import { Wallet } from "@livo-build/runtime";
+const acct = new Wallet(env).user(msg.from.id); // a handle for one end-user
+await acct.address();                  // active wallet (auto-created on first call)
+await acct.list();                     // [{ label, address, active, imported }]
+await acct.create("trading");          // new HD wallet from the user's own seed
+await acct.import("0x<key>", "main");  // bring your own key
+await acct.use("trading");             // switch active
+const hash = await acct.send({ address, abi, functionName, args }); // platform signs
+```
+
 ## Queues
 
 Publish to a per-project queue from any deployable that declares `produces: [name]`

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export type { WatchLogsOptions, WatchLogsResult } from "./watch.js";
 export { Relayer } from "./relayer.js";
 export { Queue, queue, queueEnvKey } from "./queue.js";
 export type { RelayerOptions } from "./relayer.js";
+export { Wallet, UserWallet } from "./wallet.js";
+export type { WalletOptions, WalletAccount, WalletSendOptions } from "./wallet.js";
 export { Indexer, indexer, indexerEnvKey, GraphQLError } from "./indexer.js";
 export type { IndexerOptions } from "./indexer.js";
 export { Telegram } from "./telegram.js";

package/dist/index.js

@@ -11,6 +11,10 @@ export { watchLogs } from "./watch.js";
 // Convex-serialized nonces). A Chain that defaults to the relayer key.
 export { Relayer } from "./relayer.js";
 export { Queue, queue, queueEnvKey } from "./queue.js";
+// Wallet — per-user CUSTODIAL wallets for bots. Each end-user owns wallet(s);
+// the bot signs on their behalf via the platform (server-side custody, raw keys
+// never reach the Worker). new Wallet(env).user(id).send({...}) / import / use.
+export { Wallet, UserWallet } from "./wallet.js";
 // Indexer — typed GraphQL client for a project's Goldsky subgraph (reads the
 // stable `live`-alias endpoint injected as INDEXER_<NAME>_URL).
 export { Indexer, indexer, indexerEnvKey, GraphQLError } from "./indexer.js";

package/dist/wallet.d.ts

@@ -0,0 +1,77 @@
+import { Chain } from "./chain.js";
+import { type AbiFunction } from "./abi.js";
+import type { Hex } from "./hex.js";
+import type { Receipt } from "./chain.js";
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export interface WalletOptions {
+    /** Platform wallet API base, e.g. https://<site>/wallet. Default env WALLET_API_URL. */
+    apiUrl?: string;
+    /** Bearer scoping calls to this bot. Default env WALLET_API_TOKEN. */
+    apiToken?: string;
+}
+/** One wallet a user owns. `imported` = brought their own key (vs. HD-generated). */
+export interface WalletAccount {
+    label: string;
+    address: Hex;
+    active: boolean;
+    imported: boolean;
+}
+export interface WalletSendOptions {
+    address: Hex;
+    abi: AbiFunction[];
+    functionName: string;
+    args?: unknown[];
+    /** Native value to send with the call, in wei. */
+    value?: bigint;
+}
+/** A handle bound to a single end-user (e.g. one Telegram account). */
+export declare class UserWallet {
+    private readonly wallet;
+    /** Platform-namespaced user id, e.g. "tg:12345". */
+    readonly userKey: string;
+    constructor(wallet: Wallet, 
+    /** Platform-namespaced user id, e.g. "tg:12345". */
+    userKey: string);
+    /** Every wallet the user owns (auto-creates their default on first call). */
+    list(): Promise<WalletAccount[]>;
+    /** The user's active wallet (the one `send` signs with), auto-created if none. */
+    account(): Promise<WalletAccount>;
+    /** Shorthand for the active wallet's address. */
+    address(): Promise<Hex>;
+    /** Generate a new HD wallet (from the user's own seed) and make it active. */
+    create(label?: string): Promise<WalletAccount>;
+    /** Import an external private key and make it active. */
+    import(privateKey: string, label?: string): Promise<WalletAccount>;
+    /** Switch the active wallet by label. */
+    use(label: string): Promise<WalletAccount>;
+    /** Stop tracking a wallet by label (active reassigns to another if needed). */
+    remove(label: string): Promise<void>;
+    /** Native balance (wei) of the user's active wallet. Reads via RPC, no key. */
+    balance(): Promise<bigint>;
+    /**
+     * 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.
+     */
+    send(opts: WalletSendOptions): Promise<Hex>;
+}
+export declare class Wallet {
+    private readonly apiUrl?;
+    private readonly apiToken?;
+    private readonly env?;
+    private _chain?;
+    constructor(env: MinimalEnv | undefined, options?: WalletOptions);
+    /** A handle for one end-user. Pass any stable id; it's namespaced as "tg:<id>". */
+    user(id: string | number, platform?: string): UserWallet;
+    /** Lazily build a read-only Chain (for balances/receipts) from env RPC_URL. */
+    chain(): Chain;
+    /** Wait for a tx broadcast by `send` to mine. Reads via RPC, no key. */
+    waitForReceipt(hash: Hex, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<Receipt>;
+    /** Internal: POST to a wallet API sub-path with the bot bearer; throws on error. */
+    post(path: "accounts" | "sign", body: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+export {};

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/package.json

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