@livo-build/runtime 0.2.6 → 0.2.13

package/dist/index.js

@@ -10,6 +10,10 @@ export { watchLogs } from "./watch.js";
 // defineWatcher — onMatch primitive for Signal Radar watchers (HTTP-triggered,
 // one subscription-addressed match per request) + ctx.subscribe/cancel.
 export { defineWatcher } from "./watcher.js";
+// Signals — READ client for the shared on-chain signals engine (Signal Radar):
+// live markets, recent swaps, fired matches. Zero-config (defaults to the public
+// engine). The push counterpart is defineWatcher above.
+export { Signals, signals, DEFAULT_SIGNALS_URL } from "./signals.js";
 // Relayer — managed signing for bots (custodied RELAYER_PRIVATE_KEY + optional
 // Convex-serialized nonces). A Chain that defaults to the relayer key.
 export { Relayer } from "./relayer.js";
@@ -24,11 +28,24 @@ 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";
+// Email — the project's own inbox at {slug}@livo.build (read + send/reply).
+export { Email } from "./email.js";
 export { TelegramLinks, TELEGRAM_LINKS_TABLE } from "./telegramLinks.js";
 export { tokenBalanceOf, meetsGate } from "./gate.js";
+export { tokenMetadata, ownerOf, tokenURI } from "./reads.js";
+export { resolveUri, fetchTokenMetadata } from "./nft.js";
+export { createSiweMessage, verifySiweMessage } from "./siwe.js";
+export { createSession, verifySession } from "./sessions.js";
+export { json, error, withCors, CORS_HEADERS, Router, sse } from "./http.js";
+export { rateLimit } from "./ratelimit.js";
+export { encrypt, decrypt } from "./aes.js";
+export { cached } from "./cache.js";
+export { verifyWebhook, signWebhook } from "./webhook.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";
+// Hyperliquid bridge — deposit USDC from Arbitrum into the L1 account (funds-in).
+export { depositToHyperliquid, usdcBaseUnits, HL_BRIDGE } from "./hyperliquidBridge.js";
 // Polymarket — prediction-market data (public, frontend-safe) + CLOB order
 // placement (native EIP-712 + L2 HMAC; no @polymarket/clob-client, no ethers).
 export { Polymarket } from "./polymarket.js";

package/dist/nft.d.ts

@@ -0,0 +1,33 @@
+import type { Chain } from "./chain.js";
+export interface NftAttribute {
+    trait_type?: string;
+    value?: unknown;
+    [k: string]: unknown;
+}
+export interface NftMetadata {
+    name?: string;
+    description?: string;
+    /** Image URL resolved through the gateway (ipfs:// → https). */
+    image?: string;
+    /** The original, unresolved image value from the metadata document. */
+    imageRaw?: string;
+    /** animation_url resolved through the gateway (video/audio/3D media). */
+    animationUrl?: string;
+    attributes?: NftAttribute[];
+    /** The full parsed metadata document. */
+    raw: Record<string, unknown>;
+}
+export interface FetchMetadataOptions {
+    /** IPFS gateway base, trailing slash included. Default "https://ipfs.io/ipfs/". */
+    gateway?: string;
+    /** ERC-1155 reads uri(id) with {id} substitution; default ERC-721 tokenURI(id). */
+    standard?: "erc721" | "erc1155";
+}
+/** Resolve an ipfs:// / ar:// URI to an HTTP(S) URL. http(s)/data URIs pass through. */
+export declare function resolveUri(uri: string, gateway?: string): string;
+/**
+ * Read a token's metadata URI on-chain, resolve + fetch + parse it, and resolve
+ * the embedded image/animation URLs. Returns null if the URI read reverts (e.g.
+ * unminted). Throws if the metadata document itself can't be fetched/parsed.
+ */
+export declare function fetchTokenMetadata(chain: Chain, token: string, tokenId: bigint, opts?: FetchMetadataOptions): Promise<NftMetadata | null>;

package/dist/nft.js

@@ -0,0 +1,72 @@
+// NFT metadata — read a token's metadata URI on-chain, resolve it (ipfs:// →
+// gateway), fetch + parse the JSON, and resolve the embedded media URLs. Works for
+// ERC-721 (tokenURI) and ERC-1155 (uri(id) with {id} substitution). Pairs with the
+// kit's useNFT / <NFTCard>.
+const DEFAULT_GATEWAY = "https://ipfs.io/ipfs/";
+/** Resolve an ipfs:// / ar:// URI to an HTTP(S) URL. http(s)/data URIs pass through. */
+export function resolveUri(uri, gateway = DEFAULT_GATEWAY) {
+    if (!uri)
+        return uri;
+    if (uri.startsWith("ipfs://")) {
+        let rest = uri.slice("ipfs://".length);
+        if (rest.startsWith("ipfs/"))
+            rest = rest.slice("ipfs/".length); // odd ipfs://ipfs/CID form
+        return gateway + rest;
+    }
+    if (uri.startsWith("ar://"))
+        return "https://arweave.net/" + uri.slice("ar://".length);
+    return uri;
+}
+/** ERC-1155 {id} substitution token: lowercase hex, zero-padded to 64 chars. */
+function erc1155IdHex(tokenId) {
+    return tokenId.toString(16).padStart(64, "0");
+}
+async function loadJson(uri) {
+    if (uri.startsWith("data:")) {
+        const comma = uri.indexOf(",");
+        const header = uri.slice(5, comma);
+        const body = uri.slice(comma + 1);
+        const text = header.includes("base64") ? atob(body) : decodeURIComponent(body);
+        return JSON.parse(text);
+    }
+    const res = await fetch(uri);
+    if (!res.ok)
+        throw new Error(`metadata fetch ${res.status} for ${uri}`);
+    return (await res.json());
+}
+/**
+ * Read a token's metadata URI on-chain, resolve + fetch + parse it, and resolve
+ * the embedded image/animation URLs. Returns null if the URI read reverts (e.g.
+ * unminted). Throws if the metadata document itself can't be fetched/parsed.
+ */
+export async function fetchTokenMetadata(chain, token, tokenId, opts = {}) {
+    const gateway = opts.gateway ?? DEFAULT_GATEWAY;
+    const t = token;
+    let uri;
+    try {
+        if (opts.standard === "erc1155") {
+            const raw = (await chain.call(t, "uri(uint256)(string)", [tokenId]));
+            uri = raw?.replace(/\{id\}/g, erc1155IdHex(tokenId));
+        }
+        else {
+            uri = (await chain.call(t, "tokenURI(uint256)(string)", [tokenId]));
+        }
+    }
+    catch {
+        return null;
+    }
+    if (!uri)
+        return null;
+    const doc = await loadJson(resolveUri(uri, gateway));
+    const imageRaw = (doc.image ?? doc.image_url ?? doc.imageUrl);
+    const animationRaw = (doc.animation_url ?? doc.animationUrl);
+    return {
+        name: doc.name,
+        description: doc.description,
+        image: imageRaw ? resolveUri(imageRaw, gateway) : undefined,
+        imageRaw,
+        animationUrl: animationRaw ? resolveUri(animationRaw, gateway) : undefined,
+        attributes: doc.attributes ?? undefined,
+        raw: doc,
+    };
+}

package/dist/nft.test.d.ts

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

package/dist/nft.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { resolveUri, fetchTokenMetadata } from "./nft.js";
+describe("resolveUri", () => {
+    it("maps ipfs:// (and ipfs://ipfs/) to the gateway, ar:// to arweave, passes http/data through", () => {
+        expect(resolveUri("ipfs://bafyCID/1.json")).toBe("https://ipfs.io/ipfs/bafyCID/1.json");
+        expect(resolveUri("ipfs://ipfs/bafyCID")).toBe("https://ipfs.io/ipfs/bafyCID");
+        expect(resolveUri("ipfs://CID", "https://x.mypinata.cloud/ipfs/")).toBe("https://x.mypinata.cloud/ipfs/CID");
+        expect(resolveUri("ar://TXID")).toBe("https://arweave.net/TXID");
+        expect(resolveUri("https://example.com/1.json")).toBe("https://example.com/1.json");
+        expect(resolveUri("data:application/json,{}")).toBe("data:application/json,{}");
+    });
+});
+// A fake Chain that returns a canned tokenURI/uri string — no network, no RPC.
+function fakeChain(uri) {
+    return { call: async () => uri };
+}
+describe("fetchTokenMetadata", () => {
+    it("reads tokenURI, parses a base64 data: doc, and resolves the ipfs image", async () => {
+        const doc = { name: "Glyph #7", description: "x", image: "ipfs://imgCID/7.png", attributes: [{ trait_type: "Eyes", value: "Laser" }] };
+        const dataUri = "data:application/json;base64," + btoa(JSON.stringify(doc));
+        const m = await fetchTokenMetadata(fakeChain(dataUri), "0xabc", 7n);
+        expect(m?.name).toBe("Glyph #7");
+        expect(m?.image).toBe("https://ipfs.io/ipfs/imgCID/7.png");
+        expect(m?.imageRaw).toBe("ipfs://imgCID/7.png");
+        expect(m?.attributes?.[0]).toEqual({ trait_type: "Eyes", value: "Laser" });
+    });
+    it("parses a plain (url-encoded) data: doc and image_url fallback", async () => {
+        const doc = { name: "B", image_url: "https://cdn/x.png" };
+        const dataUri = "data:application/json," + encodeURIComponent(JSON.stringify(doc));
+        const m = await fetchTokenMetadata(fakeChain(dataUri), "0xabc", 1n);
+        expect(m?.image).toBe("https://cdn/x.png");
+    });
+    it("substitutes {id} (64-hex padded) for ERC-1155 uris before fetching", async () => {
+        // uri(id) returns a template with {id}; we replace it across the whole URI. Here the
+        // literal {id} sits in a plain data: body so the substituted value is observable.
+        const uri = 'data:application/json,{"name":"id-{id}"}';
+        const m = await fetchTokenMetadata(fakeChain(uri), "0xabc", 1n, { standard: "erc1155" });
+        expect(m?.name).toBe("id-0000000000000000000000000000000000000000000000000000000000000001");
+    });
+    it("returns null when the URI read reverts", async () => {
+        const reverting = { call: async () => { throw new Error("revert"); } };
+        expect(await fetchTokenMetadata(reverting, "0xabc", 1n)).toBeNull();
+    });
+});

package/dist/ratelimit.d.ts

@@ -0,0 +1,19 @@
+export interface KvLike {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+}
+export interface RateLimitOptions {
+    /** Max requests allowed in the window. */
+    limit: number;
+    /** Window length in seconds. */
+    windowSeconds: number;
+    /** Key prefix (default "rl"). */
+    prefix?: string;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+}
+export declare function rateLimit(kv: KvLike, key: string, opts: RateLimitOptions): Promise<RateLimitResult>;

package/dist/ratelimit.js

@@ -0,0 +1,11 @@
+// A KV-backed fixed-window rate limiter for bots / api Workers (e.g. per wallet or
+// per Telegram user). Pass the project's env.KV.
+// Increment the counter for `key`; allow until `limit` is reached within the window.
+export async function rateLimit(kv, key, opts) {
+    const k = `${opts.prefix ?? "rl"}:${key}`;
+    const current = Number((await kv.get(k)) ?? "0");
+    if (current >= opts.limit)
+        return { allowed: false, remaining: 0 };
+    await kv.put(k, String(current + 1), { expirationTtl: opts.windowSeconds });
+    return { allowed: true, remaining: Math.max(0, opts.limit - current - 1) };
+}

package/dist/reads.d.ts

@@ -0,0 +1,12 @@
+import type { Chain } from "./chain.js";
+export interface TokenMetadata {
+    name?: string;
+    symbol?: string;
+    decimals?: number;
+}
+/** ERC-20 name / symbol / decimals (each best-effort — missing fields stay undefined). */
+export declare function tokenMetadata(chain: Chain, token: string): Promise<TokenMetadata>;
+/** Owner of an ERC-721 token id (or null if the read reverts, e.g. unminted). */
+export declare function ownerOf(chain: Chain, token: string, tokenId: bigint): Promise<string | null>;
+/** ERC-721 tokenURI for a token id (or null on revert). */
+export declare function tokenURI(chain: Chain, token: string, tokenId: bigint): Promise<string | null>;

package/dist/reads.js

@@ -0,0 +1,36 @@
+// Convenience contract reads on top of Chain.call — ERC-20 metadata + ERC-721
+// ownership. (For balances use tokenBalanceOf from ./gate; for native balance,
+// block number and receipts use chain.getBalance / chain.blockNumber /
+// chain.waitForReceipt directly.)
+/** ERC-20 name / symbol / decimals (each best-effort — missing fields stay undefined). */
+export async function tokenMetadata(chain, token) {
+    const t = token;
+    const [name, symbol, decimals] = await Promise.all([
+        chain.call(t, "name()(string)").catch(() => undefined),
+        chain.call(t, "symbol()(string)").catch(() => undefined),
+        chain.call(t, "decimals()(uint8)").catch(() => undefined),
+    ]);
+    return {
+        name: name,
+        symbol: symbol,
+        decimals: decimals !== undefined ? Number(decimals) : undefined,
+    };
+}
+/** Owner of an ERC-721 token id (or null if the read reverts, e.g. unminted). */
+export async function ownerOf(chain, token, tokenId) {
+    try {
+        return (await chain.call(token, "ownerOf(uint256)(address)", [tokenId]));
+    }
+    catch {
+        return null;
+    }
+}
+/** ERC-721 tokenURI for a token id (or null on revert). */
+export async function tokenURI(chain, token, tokenId) {
+    try {
+        return (await chain.call(token, "tokenURI(uint256)(string)", [tokenId]));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sessions.d.ts

@@ -0,0 +1,8 @@
+export interface SessionOptions {
+    /** Token lifetime in seconds (sets `exp`). Omit for non-expiring. */
+    ttlSeconds?: number;
+}
+/** Sign a payload into a `<payload>.<hmac>` token. */
+export declare function createSession<T extends Record<string, unknown>>(payload: T, secret: string, opts?: SessionOptions): Promise<string>;
+/** Verify + decode a session token. Returns the payload, or null if bad/expired. */
+export declare function verifySession<T = Record<string, unknown>>(token: string, secret: string): Promise<T | null>;

package/dist/sessions.js

@@ -0,0 +1,60 @@
+// Stateless signed sessions — an HMAC-SHA256 token (like a minimal JWT) you issue
+// after wallet auth and verify on later requests. Worker-safe (Web Crypto, base64url).
+const enc = (s) => new TextEncoder().encode(s);
+function b64url(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64url(s) {
+    const p = s.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = p + "=".repeat((4 - (p.length % 4)) % 4);
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+async function hmac(secret, msg) {
+    const key = await crypto.subtle.importKey("raw", enc(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", key, enc(msg)));
+}
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return d === 0;
+}
+/** Sign a payload into a `<payload>.<hmac>` token. */
+export async function createSession(payload, secret, opts = {}) {
+    const body = { ...payload };
+    if (opts.ttlSeconds)
+        body.exp = Math.floor(Date.now() / 1000) + opts.ttlSeconds;
+    const p = b64url(enc(JSON.stringify(body)));
+    const sig = b64url(await hmac(secret, p));
+    return `${p}.${sig}`;
+}
+/** Verify + decode a session token. Returns the payload, or null if bad/expired. */
+export async function verifySession(token, secret) {
+    const dot = token.indexOf(".");
+    if (dot < 0)
+        return null;
+    const p = token.slice(0, dot);
+    const sig = token.slice(dot + 1);
+    const expected = b64url(await hmac(secret, p));
+    if (!safeEqual(expected, sig))
+        return null;
+    let body;
+    try {
+        body = JSON.parse(new TextDecoder().decode(unb64url(p)));
+    }
+    catch {
+        return null;
+    }
+    if (typeof body.exp === "number" && body.exp < Math.floor(Date.now() / 1000))
+        return null;
+    return body;
+}

package/dist/signals.d.ts

@@ -0,0 +1,131 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+/** The public Livo signals engine. Override via `{ url }` or `SIGNALS_URL`. */
+export declare const DEFAULT_SIGNALS_URL = "https://signals.livo.build";
+export interface SignalsOptions {
+    /** Override the engine base URL (takes precedence over env). */
+    url?: string;
+    /** env key holding the engine base URL. Default `SIGNALS_URL`. */
+    urlSecret?: string;
+}
+/** A live, above-floor market the engine is metering. USD figures are dollars;
+ *  `chg*` are percent; `spark` is recent candle closes (oldest→newest). */
+export interface Market {
+    pair: string;
+    base: string;
+    quote: string;
+    pool: string;
+    price: number;
+    liq: number;
+    vol5m: number;
+    vol1h: number;
+    vol24h: number;
+    trades5m: number;
+    buyers: number;
+    chg5m: number;
+    chg1h: number;
+    chg24h: number;
+    spark: number[];
+}
+/** A fired signal-match (the public house feed: whale_buy/sell, price_surge, new_pool, …). */
+export interface SignalMatch {
+    signal: string;
+    detail: string;
+    pair: string;
+    base: string;
+    pool: string;
+    side: string;
+    usd: number;
+    actor: string;
+    ago: number;
+}
+/** A recent priced swap from the firehose. */
+export interface Swap {
+    block: number;
+    pair: string;
+    base: string;
+    pool: string;
+    side: string;
+    usd: number;
+    conf: string;
+    ago: number;
+}
+/** A newly-launched pool (young + climbing). `age` seconds, `pct` since launch. */
+export interface Launch {
+    pair: string;
+    base: string;
+    pool: string;
+    age: number;
+    price: number;
+    pct: number;
+    vol: number;
+    buyers: number;
+    liq: number;
+}
+/** The full engine snapshot (the `/data` document). */
+export interface EngineSnapshot {
+    mode: string;
+    caught_up: boolean;
+    head_block: number;
+    markets_tracked: number;
+    matches_total: number;
+    swaps_total: number;
+    markets: Market[];
+    matches: SignalMatch[];
+    swaps: Swap[];
+    launches: Launch[];
+    [key: string]: unknown;
+}
+export interface MarketFilter {
+    /** Min real TVL (USD). */
+    minLiq?: number;
+    /** Min 5-minute volume (USD) — "heating up right now". */
+    minVol5m?: number;
+    /** Min 24h volume (USD). */
+    minVol24h?: number;
+    /** Substring match on the pair, case-insensitive (e.g. "WETH"). */
+    pair?: string;
+    /** Cap the number returned (already sorted by 5m volume, desc). */
+    limit?: number;
+}
+export declare class Signals {
+    readonly url: string;
+    constructor(env?: MinimalEnv, options?: SignalsOptions);
+    /** The raw engine snapshot (markets + recent swaps + fired matches + launches). */
+    data(): Promise<EngineSnapshot>;
+    /** Live markets, newest-hottest first, optionally filtered. */
+    markets(filter?: MarketFilter): Promise<Market[]>;
+    /** One market by pool OR base-token address (0x-insensitive). undefined if absent. */
+    market(poolOrToken: string): Promise<Market | undefined>;
+    /** Find a token's deepest market by address or pair symbol (e.g. "PEPE"). */
+    token(addressOrSymbol: string): Promise<Market | undefined>;
+    /** Recently fired public signal-matches, newest first. */
+    matches(opts?: {
+        signal?: string;
+        limit?: number;
+    }): Promise<SignalMatch[]>;
+    /** Recent priced swaps (firehose), newest first. */
+    swaps(opts?: {
+        minUsd?: number;
+        side?: "BUY" | "SELL";
+        limit?: number;
+    }): Promise<Swap[]>;
+    /** Newly-launched pools (young + climbing). */
+    launches(): Promise<Launch[]>;
+    /** True if the engine is live and caught up to the chain tip. */
+    health(): Promise<boolean>;
+    /**
+     * Subscribe to the live Server-Sent-Events stream (for long-lived servers /
+     * Durable Objects). `onEvent` is called with each event's topic
+     * (`stats` | `swap` | `signal` | `pending`) and parsed JSON payload. Runs until
+     * the stream closes or `signal` (AbortSignal) aborts. Keepers should poll
+     * `markets()`/`matches()` on their schedule instead.
+     */
+    stream(onEvent: (topic: string, data: unknown) => void | Promise<void>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** Convenience: `await signals(env).markets({ minVol5m: 50_000 })`. */
+export declare function signals(env?: MinimalEnv, options?: SignalsOptions): Signals;
+export {};

package/dist/signals.js

@@ -0,0 +1,146 @@
+// Signals — a read client for the Livo on-chain signals engine ("Signal Radar").
+// The engine is a SHARED public service (mainnet DEX activity, priced + metered):
+// live markets, recent swaps, and fired signal-matches. This is the PULL side —
+// poll it from a keeper or read it from a server/bot. The PUSH side (get a webhook
+// when a signal fires for YOUR token) is `defineWatcher` + the create_watcher tool.
+//
+//   import { signals } from "@livo-build/runtime";
+//   const sig = signals(env);                       // zero-config → signals.livo.build
+//   const hot = await sig.markets({ minVol5m: 50_000 });   // markets heating up now
+//   const m   = await sig.token("0x6982…");          // one token's market
+//   const fired = await sig.matches({ signal: "whale_buy" });
+//
+// Zero config: defaults to the public engine, so it works out of the box. Override
+// with { url } or a SIGNALS_URL binding for a private/local engine.
+/** The public Livo signals engine. Override via `{ url }` or `SIGNALS_URL`. */
+export const DEFAULT_SIGNALS_URL = "https://signals.livo.build";
+const bare = (a) => a.replace(/^0x/, "").toLowerCase();
+export class Signals {
+    url;
+    constructor(env, options = {}) {
+        const fromEnv = env?.[options.urlSecret ?? "SIGNALS_URL"];
+        this.url = (options.url ?? fromEnv ?? DEFAULT_SIGNALS_URL).replace(/\/$/, "");
+    }
+    /** The raw engine snapshot (markets + recent swaps + fired matches + launches). */
+    async data() {
+        const res = await fetch(`${this.url}/data`, { headers: { accept: "application/json" } });
+        if (!res.ok) {
+            throw new Error(`signals engine /data failed: HTTP ${res.status}`);
+        }
+        return (await res.json());
+    }
+    /** Live markets, newest-hottest first, optionally filtered. */
+    async markets(filter = {}) {
+        let rows = (await this.data()).markets ?? [];
+        if (filter.minLiq != null)
+            rows = rows.filter((m) => m.liq >= filter.minLiq);
+        if (filter.minVol5m != null)
+            rows = rows.filter((m) => m.vol5m >= filter.minVol5m);
+        if (filter.minVol24h != null)
+            rows = rows.filter((m) => m.vol24h >= filter.minVol24h);
+        if (filter.pair) {
+            const q = filter.pair.toLowerCase();
+            rows = rows.filter((m) => m.pair.toLowerCase().includes(q));
+        }
+        return filter.limit != null ? rows.slice(0, filter.limit) : rows;
+    }
+    /** One market by pool OR base-token address (0x-insensitive). undefined if absent. */
+    async market(poolOrToken) {
+        const q = bare(poolOrToken);
+        return (await this.data()).markets?.find((m) => bare(m.pool) === q || bare(m.base) === q);
+    }
+    /** Find a token's deepest market by address or pair symbol (e.g. "PEPE"). */
+    async token(addressOrSymbol) {
+        const rows = (await this.data()).markets ?? [];
+        const q = addressOrSymbol.toLowerCase();
+        const byAddr = rows.find((m) => bare(m.base) === bare(addressOrSymbol));
+        if (byAddr)
+            return byAddr;
+        // Symbol match → the deepest (highest-liq) market for that base symbol.
+        const matches = rows.filter((m) => m.pair.toLowerCase().split("/")[0] === q);
+        return matches.sort((a, b) => b.liq - a.liq)[0];
+    }
+    /** Recently fired public signal-matches, newest first. */
+    async matches(opts = {}) {
+        let rows = (await this.data()).matches ?? [];
+        if (opts.signal)
+            rows = rows.filter((m) => m.signal === opts.signal);
+        return opts.limit != null ? rows.slice(0, opts.limit) : rows;
+    }
+    /** Recent priced swaps (firehose), newest first. */
+    async swaps(opts = {}) {
+        let rows = (await this.data()).swaps ?? [];
+        if (opts.minUsd != null)
+            rows = rows.filter((s) => s.usd >= opts.minUsd);
+        if (opts.side)
+            rows = rows.filter((s) => s.side === opts.side);
+        return opts.limit != null ? rows.slice(0, opts.limit) : rows;
+    }
+    /** Newly-launched pools (young + climbing). */
+    async launches() {
+        return (await this.data()).launches ?? [];
+    }
+    /** True if the engine is live and caught up to the chain tip. */
+    async health() {
+        try {
+            const res = await fetch(`${this.url}/health`);
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Subscribe to the live Server-Sent-Events stream (for long-lived servers /
+     * Durable Objects). `onEvent` is called with each event's topic
+     * (`stats` | `swap` | `signal` | `pending`) and parsed JSON payload. Runs until
+     * the stream closes or `signal` (AbortSignal) aborts. Keepers should poll
+     * `markets()`/`matches()` on their schedule instead.
+     */
+    async stream(onEvent, opts = {}) {
+        const res = await fetch(`${this.url}/stream`, {
+            headers: { accept: "text/event-stream" },
+            signal: opts.signal,
+        });
+        if (!res.ok || !res.body) {
+            throw new Error(`signals engine /stream failed: HTTP ${res.status}`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            // SSE frames are separated by a blank line; each has `event:` + `data:` lines.
+            let sep;
+            while ((sep = buf.indexOf("\n\n")) !== -1) {
+                const frame = buf.slice(0, sep);
+                buf = buf.slice(sep + 2);
+                let topic = "message";
+                const dataLines = [];
+                for (const line of frame.split("\n")) {
+                    if (line.startsWith("event:"))
+                        topic = line.slice(6).trim();
+                    else if (line.startsWith("data:"))
+                        dataLines.push(line.slice(5).trim());
+                }
+                if (!dataLines.length)
+                    continue;
+                let payload = dataLines.join("\n");
+                try {
+                    payload = JSON.parse(payload);
+                }
+                catch {
+                    /* leave as string */
+                }
+                await onEvent(topic, payload);
+            }
+        }
+    }
+}
+/** Convenience: `await signals(env).markets({ minVol5m: 50_000 })`. */
+export function signals(env, options) {
+    return new Signals(env, options);
+}

package/dist/siwe.d.ts

@@ -0,0 +1,24 @@
+export interface SiweParams {
+    /** The domain requesting the sign-in (e.g. "app.livo.build"). */
+    domain: string;
+    address: string;
+    uri: string;
+    chainId: number;
+    nonce: string;
+    statement?: string;
+    /** ISO timestamp; defaults to now. */
+    issuedAt?: string;
+    /** ISO timestamp; if set, verifySiweMessage rejects after it. */
+    expirationTime?: string;
+    version?: string;
+}
+export declare function createSiweMessage(p: SiweParams): string;
+export interface SiweVerifyResult {
+    valid: boolean;
+    address?: string;
+    nonce?: string;
+}
+export declare function verifySiweMessage(message: string, signature: string, opts?: {
+    nonce?: string;
+    domain?: string;
+}): Promise<SiweVerifyResult>;