@livo-build/runtime 0.2.5 → 0.2.6

package/dist/gate.d.ts

@@ -0,0 +1,10 @@
+import type { Chain } from "./chain.js";
+export declare function tokenBalanceOf(chain: Chain, token: string, owner: string): Promise<bigint>;
+export interface TokenGate {
+    /** ERC-20 / ERC-721 token address. */
+    token: string;
+    /** Minimum balance (base units for ERC-20; token count for ERC-721). */
+    minBalance: bigint;
+}
+/** Whether an owner currently meets a token gate. */
+export declare function meetsGate(chain: Chain, owner: string, gate: TokenGate): Promise<boolean>;

package/dist/gate.js

@@ -0,0 +1,18 @@
+// Token-gating helpers — does a wallet hold enough of a token to enter / stay in a
+// gated room? Works for ERC-20 (balance) and ERC-721 (count) since both expose
+// balanceOf(address). Read-only — a bot/keeper Chain needs only an RPC_URL.
+// The balanceOf(address)→uint256 of a token for an owner. Returns 0n on a failed
+// read (treat as "doesn't hold") rather than throwing the whole keeper sweep.
+export async function tokenBalanceOf(chain, token, owner) {
+    try {
+        const r = await chain.call(token, "balanceOf(address)(uint256)", [owner]);
+        return BigInt(r);
+    }
+    catch {
+        return 0n;
+    }
+}
+/** Whether an owner currently meets a token gate. */
+export async function meetsGate(chain, owner, gate) {
+    return (await tokenBalanceOf(chain, gate.token, owner)) >= gate.minBalance;
+}

package/dist/index.d.ts

@@ -14,7 +14,13 @@ export type { WalletOptions, WalletAccount, WalletSendOptions } from "./wallet.j
 export { Indexer, indexer, indexerEnvKey, GraphQLError } from "./indexer.js";
 export type { IndexerOptions } from "./indexer.js";
 export { Telegram } from "./telegram.js";
-export type { TelegramOptions, BotMessage, SendMessageOptions } from "./telegram.js";
+export type { TelegramOptions, BotMessage, SendMessageOptions, ChatJoinRequest } from "./telegram.js";
+export { verifyTelegramInitData, verifyTelegramLoginWidget, parseStartPayload } from "./telegramAuth.js";
+export type { TelegramUser, VerifyOptions } from "./telegramAuth.js";
+export { TelegramLinks, TELEGRAM_LINKS_TABLE } from "./telegramLinks.js";
+export type { TelegramLink } from "./telegramLinks.js";
+export { tokenBalanceOf, meetsGate } from "./gate.js";
+export type { TokenGate } from "./gate.js";
 export { Hyperliquid } from "./hyperliquid.js";
 export type { HyperliquidOptions, PlaceOrderOptions, MarketOrderOptions, Tif, CandleInterval, CandlesOptions, AssetContext, AccountBalance, } from "./hyperliquid.js";
 export { Polymarket } from "./polymarket.js";

package/dist/index.js

@@ -23,6 +23,9 @@ export { Wallet, UserWallet } from "./wallet.js";
 export { Indexer, indexer, indexerEnvKey, GraphQLError } from "./indexer.js";
 // Telegram — webhook verification + reply plumbing for bots.
 export { Telegram } from "./telegram.js";
+export { verifyTelegramInitData, verifyTelegramLoginWidget, parseStartPayload } from "./telegramAuth.js";
+export { TelegramLinks, TELEGRAM_LINKS_TABLE } from "./telegramLinks.js";
+export { tokenBalanceOf, meetsGate } from "./gate.js";
 // Hyperliquid — perps/spot data + trading (wraps @nktkas/hyperliquid; signs with
 // the runtime's EIP-712 signer, no viem/ethers in the bundle).
 export { Hyperliquid } from "./hyperliquid.js";

package/dist/polymarket.d.ts

@@ -38,6 +38,15 @@ export interface PolymarketOptions {
      * reads always work).
      */
     allowLegacyV1?: boolean;
+    /**
+     * Polymarket Builder/Relayer API key that authorizes V2 deposit-wallet deployment
+     * + order placement. On Livo this is a PLATFORM credential (one Livo-held builder
+     * key serving every project), injected as env.POLYMARKET_BUILDER_API_KEY — projects
+     * never set it. Default: env.POLYMARKET_BUILDER_API_KEY. (V2 order placement via
+     * @polymarket/client is not wired yet even when present — see
+     * docs/POLYMARKET-V2-IMPLEMENTATION.md.)
+     */
+    builderApiKey?: string;
     /** Signing key. Default: env.POLYMARKET_PRIVATE_KEY, then env.RELAYER_PRIVATE_KEY. */
     privateKey?: string;
     /** Env var name to read the key from. Default: "POLYMARKET_PRIVATE_KEY". */
@@ -85,6 +94,7 @@ export declare class Polymarket {
     private readonly host;
     private readonly privateKey?;
     private readonly legacyV1;
+    private readonly builderApiKey?;
     private readonly contracts;
     private creds?;
     constructor(env: MinimalEnv | undefined, options?: PolymarketOptions);
@@ -122,6 +132,8 @@ export declare class Polymarket {
     positions(user?: string): Promise<unknown>;
     /** Ensure API credentials exist (derive existing, else create). Cached on the instance. */
     ensureCreds(): Promise<PolymarketCreds>;
+    /** True once Livo's platform Polymarket builder key is configured (env.POLYMARKET_BUILDER_API_KEY). */
+    get builderConfigured(): boolean;
     private assertTradingEnabled;
     private deriveOrCreateApiKey;
     /** Build, sign, and submit an order. Returns the CLOB response JSON. */

package/dist/polymarket.js

@@ -171,12 +171,16 @@ export class Polymarket {
     host;
     privateKey;
     legacyV1;
+    builderApiKey;
     contracts;
     creds;
     constructor(env, options = {}) {
         this.chainId = options.chainId ?? Number(env?.POLYMARKET_CHAIN_ID ?? 137);
         this.host = options.host ?? env?.POLYMARKET_CLOB_HOST ?? CLOB_HOST;
         this.legacyV1 = options.allowLegacyV1 ?? (env?.POLYMARKET_ALLOW_LEGACY_V1 === "1" || env?.POLYMARKET_ALLOW_LEGACY_V1 === "true");
+        // Platform-injected Livo builder credential (one key for all projects). Read-only here;
+        // V2 order placement via @polymarket/client isn't wired yet, so this is detection only.
+        this.builderApiKey = options.builderApiKey ?? env?.POLYMARKET_BUILDER_API_KEY;
         this.contracts = this.legacyV1 ? CONTRACTS_V1 : CONTRACTS_V2;
         const keySecret = options.privateKeySecret ?? "POLYMARKET_PRIVATE_KEY";
         this.privateKey =
@@ -306,15 +310,24 @@ export class Polymarket {
     // All trading + L2-auth methods route through ensureCreds, so this one guard covers
     // them. Data reads never call it. V2 order signing isn't correctly implemented yet
     // (see the header note) — gate it rather than submit invalid orders.
+    /** True once Livo's platform Polymarket builder key is configured (env.POLYMARKET_BUILDER_API_KEY). */
+    get builderConfigured() {
+        return Boolean(this.builderApiKey);
+    }
     assertTradingEnabled() {
         if (this.legacyV1)
             return; // deprecated V1 path (testnet/legacy)
-        throw new Error("Polymarket V2 trading isn't available through this helper. Verified live: V2 (Apr 2026) REQUIRES " +
-            "the deposit-wallet flow (a plain EOA maker is rejected: 'use the deposit wallet flow'), and deploying " +
-            "a deposit wallet needs a Polymarket BUILDER or RELAYER API key — a credential Polymarket issues to " +
-            "builders, not something derivable here. The path is to wrap the official @polymarket/client SDK with " +
-            "that key (see docs/POLYMARKET-V2-IMPLEMENTATION.md). Market-DATA reads work without any of this. " +
-            "{ allowLegacyV1: true } enables the deprecated V1 path on testnet only.");
+        // V2 trading needs BOTH (1) Livo's platform builder key and (2) the @polymarket/client
+        // wrap — which isn't wired yet. Message reflects which prerequisite is missing.
+        if (this.builderConfigured) {
+            throw new Error("Polymarket builder key is configured, but V2 order placement via @polymarket/client isn't wired up in " +
+                "this runtime yet (deposit-wallet deploy + EIP-1271 signing) — tracked in docs/POLYMARKET-V2-IMPLEMENTATION.md. " +
+                "Market-DATA reads work. { allowLegacyV1: true } enables the deprecated V1 path on testnet.");
+        }
+        throw new Error("Polymarket V2 trading needs Livo's platform builder key (env.POLYMARKET_BUILDER_API_KEY), which isn't " +
+            "configured. V2 (Apr 2026) requires the deposit-wallet flow — a plain EOA maker is rejected — and deploying " +
+            "a deposit wallet needs a Polymarket Builder/Relayer credential (one Livo-held key serves all projects; see " +
+            "docs/POLYMARKET-V2-IMPLEMENTATION.md). Market-DATA reads work without it. { allowLegacyV1: true } = V1 testnet.");
     }
     async deriveOrCreateApiKey() {
         // Try derive (deterministic) first; fall back to create.

package/dist/polymarket.test.js

@@ -68,6 +68,16 @@ describe("Polymarket V2 trading gate", () => {
         expect(new Polymarket({}).collateralToken).toBe("0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB");
         expect(new Polymarket({}, { allowLegacyV1: true }).collateralToken).toBeUndefined();
     });
+    it("detects the platform builder key and adjusts the gate message", async () => {
+        // No key configured → message points at the missing platform builder key.
+        const noKey = new Polymarket({ POLYMARKET_PRIVATE_KEY: PK });
+        expect(noKey.builderConfigured).toBe(false);
+        await expect(noKey.placeOrder({ tokenId: "1", side: "BUY", price: 0.5, size: 2, tickSize: "0.01", negRisk: false })).rejects.toThrow(/platform builder key/);
+        // Platform key injected (env) → detected; gate now points at the un-wired SDK path.
+        const withKey = new Polymarket({ POLYMARKET_PRIVATE_KEY: PK, POLYMARKET_BUILDER_API_KEY: "blder_test" });
+        expect(withKey.builderConfigured).toBe(true);
+        await expect(withKey.placeOrder({ tokenId: "1", side: "BUY", price: 0.5, size: 2, tickSize: "0.01", negRisk: false })).rejects.toThrow(/isn't wired up/);
+    });
 });
 describe("Polymarket data helpers", () => {
     it("resolveMarket maps Gamma clobTokenIds + outcomes to tradable tokens", async () => {

package/dist/telegram.d.ts

@@ -67,5 +67,36 @@ export declare class Telegram {
         command: string;
         description: string;
     }>): Promise<void>;
+    private api;
+    /** Parse a `chat_join_request` update (a user asking to join a join-request chat). */
+    joinRequest(update: Record<string, unknown>): ChatJoinRequest | null;
+    /** Admit a pending join request. */
+    approveJoinRequest(chatId: number | string, userId: number): Promise<unknown>;
+    /** Reject a pending join request. */
+    declineJoinRequest(chatId: number | string, userId: number): Promise<unknown>;
+    /** Remove (ban) a member — the "boot" when they no longer qualify. */
+    banMember(chatId: number | string, userId: number, opts?: {
+        untilDate?: number;
+        revokeMessages?: boolean;
+    }): Promise<unknown>;
+    /** Lift a ban so a re-qualified user can rejoin (does NOT add them back). */
+    unbanMember(chatId: number | string, userId: number, opts?: {
+        onlyIfBanned?: boolean;
+    }): Promise<unknown>;
+    /** Create an invite link. With createsJoinRequest, joins need bot approval (the gate). */
+    createInviteLink(chatId: number | string, opts?: {
+        name?: string;
+        createsJoinRequest?: boolean;
+        expireDate?: number;
+    }): Promise<string>;
+    /** A member's status in a chat ("member" | "left" | "kicked" | "administrator" | "creator" | "restricted"). */
+    memberStatus(chatId: number | string, userId: number): Promise<string | null>;
+}
+export interface ChatJoinRequest {
+    chatId: number;
+    userId: number;
+    username?: string;
+    from: Record<string, unknown>;
+    raw: Record<string, unknown>;
 }
 export {};

package/dist/telegram.js

@@ -132,4 +132,77 @@ export class Telegram {
             body: JSON.stringify({ commands }),
         });
     }
+    // ---- Group / membership management (token-gated rooms) --------------------
+    // Generic Bot API call: POST JSON, return result, throw on Telegram error.
+    async api(method, body) {
+        if (!this.token)
+            throw new Error("Telegram: no bot token (set_secret TELEGRAM_BOT_TOKEN=<token>).");
+        const res = await fetch(`${API}${this.token}/${method}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const j = (await res.json().catch(() => null));
+        if (!res.ok || !j?.ok)
+            throw new Error(`Telegram ${method} failed: ${j?.description ?? "HTTP " + res.status}`);
+        return j.result;
+    }
+    /** Parse a `chat_join_request` update (a user asking to join a join-request chat). */
+    joinRequest(update) {
+        const r = update.chat_join_request;
+        if (!r)
+            return null;
+        const from = r.from;
+        const chat = r.chat;
+        if (!from || !chat)
+            return null;
+        return {
+            chatId: chat.id,
+            userId: from.id,
+            username: from.username,
+            from,
+            raw: r,
+        };
+    }
+    /** Admit a pending join request. */
+    approveJoinRequest(chatId, userId) {
+        return this.api("approveChatJoinRequest", { chat_id: chatId, user_id: userId });
+    }
+    /** Reject a pending join request. */
+    declineJoinRequest(chatId, userId) {
+        return this.api("declineChatJoinRequest", { chat_id: chatId, user_id: userId });
+    }
+    /** Remove (ban) a member — the "boot" when they no longer qualify. */
+    banMember(chatId, userId, opts = {}) {
+        return this.api("banChatMember", {
+            chat_id: chatId,
+            user_id: userId,
+            ...(opts.untilDate ? { until_date: opts.untilDate } : {}),
+            ...(opts.revokeMessages ? { revoke_messages: true } : {}),
+        });
+    }
+    /** Lift a ban so a re-qualified user can rejoin (does NOT add them back). */
+    unbanMember(chatId, userId, opts = { onlyIfBanned: true }) {
+        return this.api("unbanChatMember", { chat_id: chatId, user_id: userId, only_if_banned: opts.onlyIfBanned !== false });
+    }
+    /** Create an invite link. With createsJoinRequest, joins need bot approval (the gate). */
+    async createInviteLink(chatId, opts = {}) {
+        const result = (await this.api("createChatInviteLink", {
+            chat_id: chatId,
+            ...(opts.name ? { name: opts.name } : {}),
+            ...(opts.createsJoinRequest ? { creates_join_request: true } : {}),
+            ...(opts.expireDate ? { expire_date: opts.expireDate } : {}),
+        }));
+        return result.invite_link ?? "";
+    }
+    /** A member's status in a chat ("member" | "left" | "kicked" | "administrator" | "creator" | "restricted"). */
+    async memberStatus(chatId, userId) {
+        try {
+            const result = (await this.api("getChatMember", { chat_id: chatId, user_id: userId }));
+            return result.status ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
 }

package/dist/telegramAuth.d.ts

@@ -0,0 +1,16 @@
+export interface TelegramUser {
+    id: number;
+    username?: string;
+    firstName?: string;
+    lastName?: string;
+    languageCode?: string;
+    isPremium?: boolean;
+    photoUrl?: string;
+}
+export interface VerifyOptions {
+    /** Reject if auth_date is older than this many seconds (0 = no check). Default 86400. */
+    maxAgeSeconds?: number;
+}
+export declare function verifyTelegramInitData(initData: string, botToken: string, options?: VerifyOptions): Promise<TelegramUser | null>;
+export declare function verifyTelegramLoginWidget(data: Record<string, string | number | undefined>, botToken: string, options?: VerifyOptions): Promise<TelegramUser | null>;
+export declare function parseStartPayload(text: string): string | null;

package/dist/telegramAuth.js

@@ -0,0 +1,108 @@
+// Telegram identity verification — the security core of linking a Telegram user to
+// a wallet. Runs server-side (bot token never leaves the server). Two sources:
+//   • Mini App initData  — verifyTelegramInitData (HMAC keyed by "WebAppData")
+//   • Login Widget data   — verifyTelegramLoginWidget (HMAC keyed by SHA256(token))
+// Both follow Telegram's documented algorithm exactly: build a data_check_string of
+// the fields (sorted, key=value, "\n"-joined, EXCLUDING `hash`), HMAC-SHA256 it, and
+// constant-time compare to the provided `hash`. Web Crypto only (Worker-safe).
+// Bare lowercase hex (NO "0x" prefix) — Telegram's `hash` is bare hex, so we must
+// not use the chain-style bytesToHex (which prefixes "0x").
+function toHex(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i++)
+        out += bytes[i].toString(16).padStart(2, "0");
+    return out;
+}
+const enc = (s) => new TextEncoder().encode(s);
+async function hmacSha256(keyBytes, msg) {
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", key, msg));
+}
+async function sha256(bytes) {
+    return new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+}
+// Constant-time-ish hex compare (avoids leaking the match position).
+function safeEqualHex(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+function freshEnough(authDate, maxAgeSeconds) {
+    if (maxAgeSeconds <= 0)
+        return true;
+    if (!authDate)
+        return false;
+    return Math.floor(Date.now() / 1000) - authDate <= maxAgeSeconds;
+}
+function userFromRaw(u) {
+    return {
+        id: Number(u.id),
+        username: u.username,
+        firstName: u.first_name,
+        lastName: u.last_name,
+        languageCode: u.language_code,
+        isPremium: u.is_premium,
+        photoUrl: u.photo_url,
+    };
+}
+// Verify Telegram Mini App `initData` (the raw query string from
+// window.Telegram.WebApp.initData). Returns the verified user, or null.
+export async function verifyTelegramInitData(initData, botToken, options = {}) {
+    if (!initData || !botToken)
+        return null;
+    const params = new URLSearchParams(initData);
+    const hash = params.get("hash");
+    if (!hash)
+        return null;
+    params.delete("hash");
+    const dataCheckString = [...params.entries()]
+        .map(([k, v]) => `${k}=${v}`)
+        .sort()
+        .join("\n");
+    // secret_key = HMAC_SHA256(key="WebAppData", message=bot_token)
+    const secretKey = await hmacSha256(enc("WebAppData"), enc(botToken));
+    const calc = toHex(await hmacSha256(secretKey, enc(dataCheckString)));
+    if (!safeEqualHex(calc, hash))
+        return null;
+    if (!freshEnough(Number(params.get("auth_date") ?? 0), options.maxAgeSeconds ?? 86400))
+        return null;
+    const userJson = params.get("user");
+    if (!userJson)
+        return null;
+    try {
+        return userFromRaw(JSON.parse(userJson));
+    }
+    catch {
+        return null;
+    }
+}
+// Verify Telegram Login Widget data (the object the widget hands your page, with a
+// `hash`). Returns the verified user, or null.
+export async function verifyTelegramLoginWidget(data, botToken, options = {}) {
+    const hash = data.hash;
+    if (!hash || !botToken)
+        return null;
+    const dataCheckString = Object.keys(data)
+        .filter((k) => k !== "hash" && data[k] !== undefined)
+        .sort()
+        .map((k) => `${k}=${data[k]}`)
+        .join("\n");
+    // secret_key = SHA256(bot_token) (NOTE: plain SHA-256 here, not HMAC).
+    const secretKey = await sha256(enc(botToken));
+    const calc = toHex(await hmacSha256(secretKey, enc(dataCheckString)));
+    if (!safeEqualHex(calc, String(hash)))
+        return null;
+    if (!freshEnough(Number(data.auth_date ?? 0), options.maxAgeSeconds ?? 86400))
+        return null;
+    return userFromRaw(data);
+}
+// Pull the payload from a `/start <payload>` deep-link command (the non-Mini-App
+// linking flow). Returns the trimmed payload, or null.
+export function parseStartPayload(text) {
+    const m = /^\/start(?:@\w+)?(?:\s+(.+))?$/.exec(text.trim());
+    const payload = m?.[1]?.trim();
+    return payload ? payload : null;
+}

package/dist/telegramAuth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/telegramAuth.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { createHmac, createHash } from "node:crypto";
+import { verifyTelegramInitData, verifyTelegramLoginWidget, parseStartPayload } from "./telegramAuth.js";
+const BOT_TOKEN = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11";
+const USER = { id: 42, username: "alice", first_name: "Alice", language_code: "en" };
+// Build a valid Mini App initData the way Telegram does — using node:crypto, an
+// INDEPENDENT implementation from the verifier's Web Crypto. Agreement = correct.
+function makeInitData(botToken, authDate, user = USER) {
+    const params = new URLSearchParams();
+    params.set("user", JSON.stringify(user));
+    params.set("auth_date", String(authDate));
+    params.set("query_id", "AAH-test");
+    const dcs = [...params.entries()].map(([k, v]) => `${k}=${v}`).sort().join("\n");
+    const secret = createHmac("sha256", "WebAppData").update(botToken).digest();
+    const hash = createHmac("sha256", secret).update(dcs).digest("hex");
+    params.set("hash", hash);
+    return params.toString();
+}
+const now = () => Math.floor(Date.now() / 1000);
+describe("verifyTelegramInitData", () => {
+    it("accepts a valid initData and returns the user", async () => {
+        const u = await verifyTelegramInitData(makeInitData(BOT_TOKEN, now()), BOT_TOKEN);
+        expect(u).not.toBeNull();
+        expect(u?.id).toBe(42);
+        expect(u?.username).toBe("alice");
+        expect(u?.firstName).toBe("Alice");
+    });
+    it("rejects a tampered hash", async () => {
+        const good = makeInitData(BOT_TOKEN, now());
+        const tampered = good.replace(/hash=([0-9a-f])/, (_, c) => `hash=${c === "0" ? "1" : "0"}`);
+        expect(await verifyTelegramInitData(tampered, BOT_TOKEN)).toBeNull();
+    });
+    it("rejects the wrong bot token", async () => {
+        expect(await verifyTelegramInitData(makeInitData(BOT_TOKEN, now()), "999:WRONG")).toBeNull();
+    });
+    it("rejects stale auth_date", async () => {
+        const old = makeInitData(BOT_TOKEN, now() - 100_000);
+        expect(await verifyTelegramInitData(old, BOT_TOKEN, { maxAgeSeconds: 3600 })).toBeNull();
+        // ...but accepts it when the age check is disabled.
+        expect(await verifyTelegramInitData(old, BOT_TOKEN, { maxAgeSeconds: 0 })).not.toBeNull();
+    });
+    it("rejects empty / hashless input", async () => {
+        expect(await verifyTelegramInitData("", BOT_TOKEN)).toBeNull();
+        expect(await verifyTelegramInitData("user=%7B%7D&auth_date=1", BOT_TOKEN)).toBeNull();
+    });
+});
+describe("verifyTelegramLoginWidget", () => {
+    it("accepts valid widget data (SHA256(token) secret)", async () => {
+        const data = { id: 42, username: "alice", auth_date: now() };
+        const dcs = Object.keys(data).sort().map((k) => `${k}=${data[k]}`).join("\n");
+        const secret = createHash("sha256").update(BOT_TOKEN).digest();
+        data.hash = createHmac("sha256", secret).update(dcs).digest("hex");
+        const u = await verifyTelegramLoginWidget(data, BOT_TOKEN);
+        expect(u?.id).toBe(42);
+        expect(u?.username).toBe("alice");
+    });
+    it("rejects a bad hash", async () => {
+        expect(await verifyTelegramLoginWidget({ id: 1, auth_date: now(), hash: "deadbeef" }, BOT_TOKEN)).toBeNull();
+    });
+});
+describe("parseStartPayload", () => {
+    it("extracts the payload from /start", () => {
+        expect(parseStartPayload("/start link_abc123")).toBe("link_abc123");
+        expect(parseStartPayload("/start@MyBot tok")).toBe("tok");
+        expect(parseStartPayload("/start")).toBeNull();
+        expect(parseStartPayload("hello")).toBeNull();
+    });
+});

package/dist/telegramLinks.d.ts

@@ -0,0 +1,27 @@
+import type { D1Like } from "./store.js";
+export declare const TELEGRAM_LINKS_TABLE = "telegram_links";
+export interface TelegramLink {
+    telegramId: string;
+    address: string;
+    username?: string;
+    createdAt: number;
+}
+export declare class TelegramLinks {
+    private readonly db;
+    private readonly table;
+    private ready;
+    constructor(db: D1Like, table?: string);
+    private init;
+    /** Create/replace the link for a Telegram user (one wallet per Telegram id). */
+    link(telegramId: string | number, address: string, username?: string): Promise<void>;
+    /** Remove the link for a Telegram user. */
+    unlink(telegramId: string | number): Promise<void>;
+    /** The wallet address linked to a Telegram user, or null. */
+    walletFor(telegramId: string | number): Promise<string | null>;
+    /** The Telegram link for a wallet address, or null. */
+    telegramFor(address: string): Promise<TelegramLink | null>;
+    /** Whether a Telegram user has a linked wallet. */
+    isLinked(telegramId: string | number): Promise<boolean>;
+    /** Every link — for a keeper that re-checks balances and boots ineligible users. */
+    all(limit?: number): Promise<TelegramLink[]>;
+}

package/dist/telegramLinks.js

@@ -0,0 +1,78 @@
+// TelegramLinks — the shared binding between a Telegram user and a wallet address,
+// stored in the project's D1 (env.DB, which is bound into BOTH the api Worker and
+// the bot). Write it from the api after verifying both proofs; read it from the bot
+// to answer "is this user's wallet connected?".
+export const TELEGRAM_LINKS_TABLE = "telegram_links";
+export class TelegramLinks {
+    db;
+    table;
+    ready = null;
+    constructor(db, table = TELEGRAM_LINKS_TABLE) {
+        this.db = db;
+        this.table = table;
+        if (!db)
+            throw new Error("TelegramLinks: no D1 binding — pass env.DB (is the project's D1 bound?)");
+    }
+    async init() {
+        if (!this.ready) {
+            this.ready = (async () => {
+                if (this.db.exec) {
+                    await this.db.exec(`CREATE TABLE IF NOT EXISTS ${this.table} (telegram_id TEXT PRIMARY KEY, address TEXT NOT NULL, username TEXT, created_at INTEGER); CREATE INDEX IF NOT EXISTS ${this.table}_address ON ${this.table} (address);`);
+                }
+            })();
+        }
+        return this.ready;
+    }
+    /** Create/replace the link for a Telegram user (one wallet per Telegram id). */
+    async link(telegramId, address, username) {
+        await this.init();
+        await this.db
+            .prepare(`INSERT INTO ${this.table} (telegram_id, address, username, created_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(telegram_id) DO UPDATE SET address = excluded.address, username = excluded.username, created_at = excluded.created_at`)
+            .bind(String(telegramId), address.toLowerCase(), username ?? null, Date.now())
+            .run();
+    }
+    /** Remove the link for a Telegram user. */
+    async unlink(telegramId) {
+        await this.init();
+        await this.db.prepare(`DELETE FROM ${this.table} WHERE telegram_id = ?`).bind(String(telegramId)).run();
+    }
+    /** The wallet address linked to a Telegram user, or null. */
+    async walletFor(telegramId) {
+        await this.init();
+        const row = await this.db
+            .prepare(`SELECT address FROM ${this.table} WHERE telegram_id = ?`)
+            .bind(String(telegramId))
+            .first();
+        return row ? row.address : null;
+    }
+    /** The Telegram link for a wallet address, or null. */
+    async telegramFor(address) {
+        await this.init();
+        const row = await this.db
+            .prepare(`SELECT telegram_id, address, username, created_at FROM ${this.table} WHERE address = ?`)
+            .bind(address.toLowerCase())
+            .first();
+        return row
+            ? { telegramId: row.telegram_id, address: row.address, username: row.username ?? undefined, createdAt: row.created_at }
+            : null;
+    }
+    /** Whether a Telegram user has a linked wallet. */
+    async isLinked(telegramId) {
+        return (await this.walletFor(telegramId)) !== null;
+    }
+    /** Every link — for a keeper that re-checks balances and boots ineligible users. */
+    async all(limit = 1000) {
+        await this.init();
+        const res = await this.db
+            .prepare(`SELECT telegram_id, address, username, created_at FROM ${this.table} LIMIT ?`)
+            .bind(limit)
+            .all();
+        return (res.results ?? []).map((r) => ({
+            telegramId: r.telegram_id,
+            address: r.address,
+            username: r.username ?? undefined,
+            createdAt: r.created_at,
+        }));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livo-build/runtime",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Livo runtime — chain signing/reads, D1 state, and logging for keepers, servers, and bots.",
   "type": "module",
   "license": "UNLICENSED",
@@ -16,9 +16,19 @@
       "import": "./dist/contracts.js"
     }
   },
-  "files": ["dist"],
-  "engines": { "node": ">=18" },
-  "keywords": ["livo", "web3", "keeper", "eip1559", "evm"],
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "livo",
+    "web3",
+    "keeper",
+    "eip1559",
+    "evm"
+  ],
   "publishConfig": {
     "access": "public"
   },