@livo-build/runtime 0.2.3 → 0.2.4

package/README.md

@@ -15,7 +15,7 @@ At a glance: `Chain` (read/sign/send + RPC failover), `Relayer` (managed bot
 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";
@@ -246,6 +246,26 @@ 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

@@ -23,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

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

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