@livo-build/runtime 0.2.2 → 0.2.4

package/README.md

@@ -12,9 +12,10 @@ 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`.
+`verifyMessage` (prove wallet ownership), `requireSecret`, `queue`, `retry`, `log`.
 
 ```ts
 import { Chain, Store, log } from "@livo-build/runtime";
@@ -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,48 @@ 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
+```
+
+## Prove wallet ownership — `verifyMessage`
+
+Verify a "prove you own this wallet" signature **server-side** (EIP-191 `personal_sign`,
+the basis of wallet-link / SIWE login) — no hand-rolled secp256k1. The pattern: a website
+has the user connect a wallet and `personal_sign` a nonce; a bot/keeper then verifies it and
+links the recovered address to the user's account.
+
+```ts
+import { verifyMessage, recoverMessageAddress } from "@livo-build/runtime";
+
+// true iff `address` produced `signature` over `message` (never throws)
+if (verifyMessage({ address, message: "Link my wallet · nonce: " + nonce, signature })) {
+  // ownership proven — link `address` to the user
+}
+recoverMessageAddress(message, signature); // → the signer's checksummed address
+```
+
+Scaffold the full flow (bot serves the connect+sign page, verifies, links, and gates a private
+group; a keeper boots members who fall below) with `create_bot --template wallet-link-bot`.
+
 ## 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";
@@ -21,6 +23,8 @@ export { encodeFunctionData, encodeParameters, decodeParameters, decodeFunctionR
 export type { AbiFunction, AbiParameter, ParsedSignature } from "./abi.js";
 export { signTransaction, transactionHashToSign, transactionHash, privateKeyToAddress, toChecksumAddress, } from "./tx.js";
 export type { Eip1559Tx } from "./tx.js";
+export { hashMessage, recoverMessageAddress, verifyMessage } from "./sig.js";
+export type { VerifyMessageParams } from "./sig.js";
 export { eventTopic, encodeFilterTopics, encodeIndexedTopic, decodeLog, parseEventSignature, } from "./events.js";
 export type { AbiEvent, RawLog, DecodedLog } from "./events.js";
 export { bytesToHex, hexToBytes, concatBytes, toBigInt, } from "./hex.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";
@@ -24,6 +28,9 @@ export { requireSecret, requireSecrets, getSecret } from "./secret.js";
 // Low-level escape hatches — ABI coding, signing, RLP, hex. Power users only.
 export { encodeFunctionData, encodeParameters, decodeParameters, decodeFunctionResult, functionSelector, functionSignature, functionFromSignature, parseSignature, findFunction, keccak256, } from "./abi.js";
 export { signTransaction, transactionHashToSign, transactionHash, privateKeyToAddress, toChecksumAddress, } from "./tx.js";
+// EIP-191 message verification — prove a user controls an address from a signed
+// message (wallet-link / SIWE login), recovered server-side with no hand-rolled crypto.
+export { hashMessage, recoverMessageAddress, verifyMessage } from "./sig.js";
 export { eventTopic, encodeFilterTopics, encodeIndexedTopic, decodeLog, parseEventSignature, } from "./events.js";
 export { bytesToHex, hexToBytes, concatBytes, toBigInt, } from "./hex.js";
 // Layer 2 — generated contract bindings live in "@livo/runtime/contracts".

package/dist/sig.d.ts

@@ -0,0 +1,27 @@
+import { type Bytes, type Hex } from "./hex.js";
+/**
+ * The EIP-191 digest a wallet signs for `personal_sign(message)`:
+ *   keccak256("\x19Ethereum Signed Message:\n" + byteLength(message) + message)
+ * `message` is treated as UTF-8 text (the common case for login/link flows).
+ */
+export declare function hashMessage(message: string): Bytes;
+/**
+ * Recover the EIP-55 checksummed address that produced `signature` over
+ * `message` (an EIP-191 personal_sign). `signature` is the 65-byte 0x string
+ * r(32) ++ s(32) ++ v(1), where v is 27/28 (or 0/1). Throws on a malformed sig.
+ */
+export declare function recoverMessageAddress(message: string, signature: Hex | string): Hex;
+export interface VerifyMessageParams {
+    /** The address you expect signed the message. */
+    address: Hex | string;
+    /** The exact message string that was signed. */
+    message: string;
+    /** The 65-byte 0x signature returned by the wallet. */
+    signature: Hex | string;
+}
+/**
+ * True iff `signature` over `message` was produced by `address` — the safe way to
+ * verify "prove you own this wallet" server-side. Never throws: a malformed
+ * signature returns false.
+ */
+export declare function verifyMessage({ address, message, signature }: VerifyMessageParams): boolean;

package/dist/sig.js

@@ -0,0 +1,50 @@
+// EIP-191 personal_sign message verification — prove a user controls an address
+// from a signature, with zero hand-rolled crypto. The counterpart to tx.ts's
+// signing: here we RECOVER the signer of a `personal_sign` message (what
+// wallets produce for `eth_sign`/`personal_sign` and SIWE login). secp256k1
+// recovery via noble; same keccak + hex helpers as the rest of the runtime.
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { bytesToHex, concatBytes, hexToBytes } from "./hex.js";
+import { toChecksumAddress } from "./tx.js";
+const PERSONAL_PREFIX = "\x19Ethereum Signed Message:\n";
+/**
+ * The EIP-191 digest a wallet signs for `personal_sign(message)`:
+ *   keccak256("\x19Ethereum Signed Message:\n" + byteLength(message) + message)
+ * `message` is treated as UTF-8 text (the common case for login/link flows).
+ */
+export function hashMessage(message) {
+    const body = new TextEncoder().encode(message);
+    const prefix = new TextEncoder().encode(PERSONAL_PREFIX + body.length);
+    return keccak_256(concatBytes(prefix, body));
+}
+/**
+ * Recover the EIP-55 checksummed address that produced `signature` over
+ * `message` (an EIP-191 personal_sign). `signature` is the 65-byte 0x string
+ * r(32) ++ s(32) ++ v(1), where v is 27/28 (or 0/1). Throws on a malformed sig.
+ */
+export function recoverMessageAddress(message, signature) {
+    const bytes = hexToBytes(signature);
+    if (bytes.length !== 65)
+        throw new Error("signature must be 65 bytes (r,s,v)");
+    const v = bytes[64];
+    const recovery = v >= 27 ? v - 27 : v;
+    if (recovery !== 0 && recovery !== 1)
+        throw new Error(`invalid signature recovery byte: ${v}`);
+    const sig = secp256k1.Signature.fromCompact(bytes.slice(0, 64)).addRecoveryBit(recovery);
+    const pub = sig.recoverPublicKey(hashMessage(message)).toRawBytes(false).slice(1); // drop 0x04
+    return toChecksumAddress(bytesToHex(keccak_256(pub).slice(-20)));
+}
+/**
+ * True iff `signature` over `message` was produced by `address` — the safe way to
+ * verify "prove you own this wallet" server-side. Never throws: a malformed
+ * signature returns false.
+ */
+export function verifyMessage({ address, message, signature }) {
+    try {
+        return recoverMessageAddress(message, signature).toLowerCase() === address.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/telegram.d.ts

@@ -54,6 +54,14 @@ export declare class Telegram {
     handleUpdate(req: Request, reply: (msg: BotMessage) => string | null | undefined | Promise<string | null | undefined>, opts?: SendMessageOptions): Promise<Response>;
     /** Send a message to a chat. No-op-safe: throws if no token is configured. */
     sendMessage(chatId: number | string, text: string, opts?: SendMessageOptions): Promise<void>;
+    /**
+     * Send a photo to a chat. `photo` is a URL Telegram fetches, or a Telegram
+     * file_id. (To upload raw bytes, post multipart/form-data to sendPhoto directly.)
+     */
+    sendPhoto(chatId: number | string, photo: string, opts?: {
+        caption?: string;
+        parseMode?: "Markdown" | "MarkdownV2" | "HTML";
+    }): Promise<void>;
     /** Register the slash-command menu (setMyCommands) — autocompletes in chat. */
     setMyCommands(commands: Array<{
         command: string;

package/dist/telegram.js

@@ -102,6 +102,26 @@ export class Telegram {
         if (!res.ok)
             throw new Error(`Telegram sendMessage failed: HTTP ${res.status}`);
     }
+    /**
+     * Send a photo to a chat. `photo` is a URL Telegram fetches, or a Telegram
+     * file_id. (To upload raw bytes, post multipart/form-data to sendPhoto directly.)
+     */
+    async sendPhoto(chatId, photo, opts = {}) {
+        if (!this.token)
+            throw new Error("Telegram: no bot token (set_secret BOT_TOKEN=<token>).");
+        const body = { chat_id: chatId, photo };
+        if (opts.caption)
+            body.caption = opts.caption;
+        if (opts.parseMode)
+            body.parse_mode = opts.parseMode;
+        const res = await fetch(`${API}${this.token}/sendPhoto`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`Telegram sendPhoto failed: HTTP ${res.status}`);
+    }
     /** Register the slash-command menu (setMyCommands) — autocompletes in chat. */
     async setMyCommands(commands) {
         if (!this.token)

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