@livo-build/runtime 0.2.6 → 0.2.12

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>;

package/dist/siwe.js

@@ -0,0 +1,33 @@
+// Sign-In With Ethereum (EIP-4361) — build the canonical message + verify a signed
+// one. The standard way to authenticate a wallet to a backend; pairs with sessions.
+import { verifyMessage } from "./sig.js";
+export function createSiweMessage(p) {
+    const lines = [`${p.domain} wants you to sign in with your Ethereum account:`, p.address, ""];
+    if (p.statement)
+        lines.push(p.statement, "");
+    lines.push(`URI: ${p.uri}`, `Version: ${p.version ?? "1"}`, `Chain ID: ${p.chainId}`, `Nonce: ${p.nonce}`, `Issued At: ${p.issuedAt ?? new Date().toISOString()}`);
+    if (p.expirationTime)
+        lines.push(`Expiration Time: ${p.expirationTime}`);
+    return lines.join("\n");
+}
+function field(message, label) {
+    const m = new RegExp(`^${label}(.*)$`, "m").exec(message);
+    return m?.[1]?.trim();
+}
+// Verify a SIWE message + signature: the signature recovers to the claimed address,
+// the nonce matches (if given), and it isn't expired.
+export async function verifySiweMessage(message, signature, opts = {}) {
+    const address = message.split("\n")[1]?.trim();
+    if (!address || !/^0x[0-9a-fA-F]{40}$/.test(address))
+        return { valid: false };
+    const nonce = field(message, "Nonce: ");
+    if (opts.nonce && nonce !== opts.nonce)
+        return { valid: false };
+    if (opts.domain && !message.startsWith(opts.domain + " "))
+        return { valid: false };
+    const exp = field(message, "Expiration Time: ");
+    if (exp && Date.parse(exp) < Date.now())
+        return { valid: false };
+    const ok = await verifyMessage({ address: address, message, signature: signature });
+    return { valid: ok, address: ok ? address : undefined, nonce };
+}

package/dist/sse.test.d.ts

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

package/dist/sse.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import { sse } from "./http.js";
+async function readAll(res) {
+    return await res.text();
+}
+describe("sse", () => {
+    it("formats events (data/event/id) and a heartbeat, and sets the right headers", async () => {
+        const conn = sse();
+        expect(conn.response.headers.get("content-type")).toBe("text/event-stream");
+        conn.send({ px: 100 });
+        conn.send("hello", { event: "tick", id: "7" });
+        conn.ping();
+        conn.send("a\nb"); // multiline → two data: lines
+        conn.close();
+        const text = await readAll(conn.response);
+        expect(text).toContain('data: {"px":100}\n\n');
+        expect(text).toContain("event: tick\nid: 7\ndata: hello\n\n");
+        expect(text).toContain(": ping\n\n");
+        expect(text).toContain("data: a\ndata: b\n\n");
+        expect(conn.closed).toBe(true);
+    });
+    it("stops writing after close (no throw)", async () => {
+        const conn = sse();
+        conn.close();
+        conn.send({ ignored: true });
+        expect(await readAll(conn.response)).toBe("");
+    });
+});

package/dist/webhook.d.ts

@@ -0,0 +1,18 @@
+export type SignatureEncoding = "hex" | "base64";
+/** Compute the HMAC-SHA256 signature of a payload (for signing outgoing webhooks/tests). */
+export declare function signWebhook(payload: string, secret: string, encoding?: SignatureEncoding): Promise<string>;
+export interface VerifyWebhookParams {
+    /** The RAW request body (verify before JSON.parse — re-serialization changes bytes). */
+    payload: string;
+    secret: string;
+    /** The signature header value. A `scheme=` prefix (e.g. "sha256=") is stripped for hex. */
+    signature: string;
+    /** Digest encoding of `signature` (default "hex"). */
+    encoding?: SignatureEncoding;
+}
+/**
+ * Verify a webhook's HMAC-SHA256 signature against the raw body. Returns true iff the
+ * signature matches. For hex signatures a leading `algo=` prefix (GitHub's "sha256=")
+ * is stripped automatically.
+ */
+export declare function verifyWebhook(params: VerifyWebhookParams): Promise<boolean>;

package/dist/webhook.js

@@ -0,0 +1,49 @@
+// Inbound webhook signature verification (GitHub/Stripe-style HMAC-SHA256). Verify
+// that a raw request body was signed with your shared secret before trusting it.
+// Constant-time comparison; no hand-rolled crypto.
+function enc(s) {
+    return new TextEncoder().encode(s);
+}
+function toHex(bytes) {
+    let out = "";
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+function toBase64(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin);
+}
+async function hmac(secret, payload) {
+    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(payload)));
+}
+/** Constant-time string compare (length-independent leak is acceptable for digests). */
+function timingSafeEqual(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;
+}
+/** Compute the HMAC-SHA256 signature of a payload (for signing outgoing webhooks/tests). */
+export async function signWebhook(payload, secret, encoding = "hex") {
+    const mac = await hmac(secret, payload);
+    return encoding === "base64" ? toBase64(mac) : toHex(mac);
+}
+/**
+ * Verify a webhook's HMAC-SHA256 signature against the raw body. Returns true iff the
+ * signature matches. For hex signatures a leading `algo=` prefix (GitHub's "sha256=")
+ * is stripped automatically.
+ */
+export async function verifyWebhook(params) {
+    const encoding = params.encoding ?? "hex";
+    let provided = params.signature.trim();
+    if (encoding === "hex")
+        provided = provided.replace(/^[A-Za-z0-9_-]+=/, ""); // strip "sha256=" etc (hex has no '=')
+    const expected = await signWebhook(params.payload, params.secret, encoding);
+    return timingSafeEqual(expected.toLowerCase(), provided.toLowerCase());
+}

package/dist/webhook.test.d.ts

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

package/dist/webhook.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { signWebhook, verifyWebhook } from "./webhook.js";
+import { cached } from "./cache.js";
+describe("webhook signatures", () => {
+    it("round-trips a hex signature and strips a sha256= prefix", async () => {
+        const sig = await signWebhook("payload-body", "shh");
+        expect(await verifyWebhook({ payload: "payload-body", secret: "shh", signature: sig })).toBe(true);
+        expect(await verifyWebhook({ payload: "payload-body", secret: "shh", signature: "sha256=" + sig })).toBe(true);
+    });
+    it("rejects a wrong secret or tampered payload", async () => {
+        const sig = await signWebhook("a", "s1");
+        expect(await verifyWebhook({ payload: "a", secret: "s2", signature: sig })).toBe(false);
+        expect(await verifyWebhook({ payload: "b", secret: "s1", signature: sig })).toBe(false);
+    });
+    it("supports base64 encoding", async () => {
+        const sig = await signWebhook("x", "k", "base64");
+        expect(await verifyWebhook({ payload: "x", secret: "k", signature: sig, encoding: "base64" })).toBe(true);
+    });
+});
+function memKv() {
+    const store = new Map();
+    return {
+        store,
+        get: async (k) => store.get(k) ?? null,
+        put: async (k, v) => void store.set(k, v),
+    };
+}
+describe("cached", () => {
+    it("computes once, then serves from cache", async () => {
+        const kv = memKv();
+        let calls = 0;
+        const produce = async () => {
+            calls++;
+            return { n: 42 };
+        };
+        expect(await cached(kv, "k", produce, { ttlSeconds: 60 })).toEqual({ n: 42 });
+        expect(await cached(kv, "k", produce, { ttlSeconds: 60 })).toEqual({ n: 42 });
+        expect(calls).toBe(1);
+        expect(kv.store.has("cache:k")).toBe(true);
+    });
+    it("recomputes when the cached value is corrupt", async () => {
+        const kv = memKv();
+        kv.store.set("cache:bad", "{not json");
+        expect(await cached(kv, "bad", async () => "fresh", { ttlSeconds: 60 })).toBe("fresh");
+    });
+});

package/package.json

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