@livo-build/runtime 0.2.6 → 0.2.12

package/dist/hyperliquid.js

@@ -25,6 +25,35 @@ import { keccak_256 } from "@noble/hashes/sha3";
 import { localAccount } from "./eip712.js";
 import { privateKeyToAddress } from "./tx.js";
 import { bytesToHex, concatBytes, hexToBytes } from "./hex.js";
+/** Parse a Hyperliquid clearinghouse position into a clean PositionInfo. */
+export function parseHlPosition(p) {
+    const szi = Number(p.szi);
+    return {
+        coin: p.coin,
+        size: Math.abs(szi),
+        side: szi > 0 ? "long" : szi < 0 ? "short" : "flat",
+        entryPx: Number(p.entryPx ?? 0),
+        positionValue: Number(p.positionValue ?? 0),
+        unrealizedPnl: Number(p.unrealizedPnl ?? 0),
+        returnOnEquity: Number(p.returnOnEquity ?? 0),
+        leverage: Number(p.leverage?.value ?? 0),
+        liquidationPx: p.liquidationPx != null ? Number(p.liquidationPx) : null,
+        marginUsed: Number(p.marginUsed ?? 0),
+    };
+}
+/** Parse an L2 book into a best bid/offer + mid + spread. */
+export function parseBbo(book) {
+    const bidPx = book.levels?.[0]?.[0]?.px;
+    const askPx = book.levels?.[1]?.[0]?.px;
+    const bid = bidPx != null ? Number(bidPx) : null;
+    const ask = askPx != null ? Number(askPx) : null;
+    return {
+        bid,
+        ask,
+        mid: bid != null && ask != null ? (bid + ask) / 2 : null,
+        spread: bid != null && ask != null ? ask - bid : null,
+    };
+}
 function truthy(v) {
     return v === true || v === 1 || v === "1" || v === "true";
 }
@@ -206,6 +235,47 @@ export class Hyperliquid {
         const startTime = opts.startTime ?? endTime - (opts.lookbackMs ?? 24 * 60 * 60 * 1000);
         return this._info.candleSnapshot({ coin, interval, startTime, endTime });
     }
+    /** Recent public trades for a coin. */
+    async recentTrades(coin) {
+        return this._info.recentTrades({ coin });
+    }
+    /** Best bid/offer + mid + spread for a coin (parsed from the L2 book). */
+    async bbo(coin) {
+        return parseBbo((await this.book(coin)));
+    }
+    /** All open positions as clean PositionInfo[] (default: the signer's account). */
+    async positionsList(user) {
+        const s = (await this.positions(user));
+        return (s.assetPositions ?? []).map((ap) => parseHlPosition(ap.position));
+    }
+    /** A single open position for a coin, or null if flat. */
+    async position(coin, user) {
+        return (await this.positionsList(user)).find((p) => p.coin === coin) ?? null;
+    }
+    /** Current hourly funding rate for a coin (fraction, e.g. 0.0000125). */
+    async fundingRate(coin) {
+        return (await this.assetCtx(coin)).funding;
+    }
+    /** Historical funding rates for a coin (default: the last 7 days). */
+    async fundingHistory(coin, opts = {}) {
+        const endTime = opts.endTime ?? Date.now();
+        const startTime = opts.startTime ?? endTime - (opts.lookbackMs ?? 7 * 24 * 60 * 60 * 1000);
+        return this._info.fundingHistory({ coin, startTime, endTime });
+    }
+    /** Funding payments paid/received by an account (default signer; last 7 days). */
+    async userFunding(opts = {}, user) {
+        const endTime = opts.endTime ?? Date.now();
+        const startTime = opts.startTime ?? endTime - (opts.lookbackMs ?? 7 * 24 * 60 * 60 * 1000);
+        return this._info.userFunding({ user: this.requireUser(user), startTime, endTime });
+    }
+    /** Predicted next funding rates across venues (no key). */
+    async predictedFundings() {
+        return this._info.predictedFundings();
+    }
+    /** Portfolio history (PnL/account-value time series) for an account (default: the signer). */
+    async portfolio(user) {
+        return this._info.portfolio({ user: this.requireUser(user) });
+    }
     // ---- trading (key required) ----
     /** Raw order passthrough (the @nktkas `order` shape) for full control. */
     async order(params) {
@@ -281,10 +351,134 @@ export class Hyperliquid {
     async cancel(coin, oid) {
         return this.exchange.cancel({ cancels: [{ a: await this.assetId(coin), o: oid }] });
     }
+    /** Cancel a resting order by its client order id (cloid). */
+    async cancelByCloid(coin, cloid) {
+        return this.exchange.cancelByCloid({ cancels: [{ asset: await this.assetId(coin), cloid }] });
+    }
+    /** Cancel ALL resting orders (optionally only for one coin). Returns the count cancelled. */
+    async cancelAll(coin) {
+        const orders = (await this.openOrders());
+        const targets = coin ? orders.filter((o) => o.coin === coin) : orders;
+        if (!targets.length)
+            return { cancelled: 0 };
+        const cancels = await Promise.all(targets.map(async (o) => ({ a: await this.assetId(o.coin), o: o.oid })));
+        await this.exchange.cancel({ cancels });
+        return { cancelled: targets.length };
+    }
+    /** Modify a resting limit order in place (new size/price/side). */
+    async modifyOrder(oid, coin, isBuy, size, price, opts = {}) {
+        const { id, szDecimals } = await this.lookup(coin);
+        return this.exchange.modify({
+            oid,
+            order: {
+                a: id,
+                b: isBuy,
+                p: formatPrice(price),
+                s: formatSize(size, szDecimals),
+                r: opts.reduceOnly ?? false,
+                t: { limit: { tif: opts.tif ?? "Gtc" } },
+            },
+        });
+    }
+    /**
+     * Place a trigger order (stop / take-profit). `triggerPx` is the activation price;
+     * `tpsl` is "sl" (stop) or "tp". Market trigger by default (fills at market once
+     * armed); reduce-only by default (closing). `isBuy` is the side that executes —
+     * to protect a LONG use isBuy=false (sell), for a SHORT use isBuy=true (buy).
+     */
+    async trigger(coin, isBuy, size, triggerPx, opts) {
+        const { id, szDecimals } = await this.lookup(coin);
+        return this.exchange.order({
+            orders: [
+                {
+                    a: id,
+                    b: isBuy,
+                    p: formatPrice(opts.price ?? triggerPx),
+                    s: formatSize(size, szDecimals),
+                    r: opts.reduceOnly ?? true,
+                    t: { trigger: { isMarket: opts.isMarket ?? true, triggerPx: formatPrice(triggerPx), tpsl: opts.tpsl } },
+                },
+            ],
+            grouping: "na",
+        });
+    }
+    /** Stop-loss trigger (reduce-only market by default). See `trigger` for `isBuy`. */
+    stopLoss(coin, isBuy, size, triggerPx, opts = {}) {
+        return this.trigger(coin, isBuy, size, triggerPx, { ...opts, tpsl: "sl" });
+    }
+    /** Take-profit trigger (reduce-only market by default). See `trigger` for `isBuy`. */
+    takeProfit(coin, isBuy, size, triggerPx, opts = {}) {
+        return this.trigger(coin, isBuy, size, triggerPx, { ...opts, tpsl: "tp" });
+    }
+    /** Dead-man's switch: auto-cancel all orders at `timeMs` (epoch) unless re-armed. Omit to clear. */
+    async scheduleCancel(timeMs) {
+        return this.exchange.scheduleCancel(timeMs ? { time: timeMs } : {});
+    }
+    /** Move USDC from spot into the perp wallet (margin top-up; not a withdrawal). */
+    async transferToPerp(usd) {
+        return this.exchange.usdClassTransfer({ amount: String(usd), toPerp: true });
+    }
+    /** Move USDC from the perp wallet back to spot. */
+    async transferToSpot(usd) {
+        return this.exchange.usdClassTransfer({ amount: String(usd), toPerp: false });
+    }
     /** Set leverage for a coin (cross by default). */
     async updateLeverage(coin, leverage, opts = {}) {
         return this.exchange.updateLeverage({ asset: await this.assetId(coin), isCross: opts.cross ?? true, leverage });
     }
+    /**
+     * Place a TWAP order — slice `size` evenly over `minutes` (5–1440) to reduce impact.
+     * `randomize` jitters slice timing. Returns the @nktkas response (incl. the TWAP id).
+     */
+    async twap(coin, isBuy, size, minutes, opts = {}) {
+        const { id, szDecimals } = await this.lookup(coin);
+        return this.exchange.twapOrder({
+            twap: { a: id, b: isBuy, s: formatSize(size, szDecimals), r: opts.reduceOnly ?? false, m: minutes, t: opts.randomize ?? false },
+        });
+    }
+    /** Cancel a running TWAP by its id (from the `twap()` response). */
+    async cancelTwap(coin, twapId) {
+        return this.exchange.twapCancel({ a: await this.assetId(coin), t: twapId });
+    }
+    // ---- sub-accounts (isolate strategies under one master) ----
+    /** Create a named sub-account (1–16 chars). Returns its address. */
+    async createSubAccount(name) {
+        return this.exchange.createSubAccount({ name });
+    }
+    /** List sub-accounts for an address (default: the signer). */
+    async subAccounts(user) {
+        return this._info.subAccounts({ user: this.requireUser(user) });
+    }
+    /** Move USDC from the master into a sub-account (`usd` in dollars). */
+    async transferToSubAccount(subAccount, usd) {
+        return this.exchange.subAccountTransfer({ subAccountUser: subAccount, isDeposit: true, usd: Math.round(usd * 1e6) });
+    }
+    /** Move USDC from a sub-account back to the master (`usd` in dollars). */
+    async transferFromSubAccount(subAccount, usd) {
+        return this.exchange.subAccountTransfer({ subAccountUser: subAccount, isDeposit: false, usd: Math.round(usd * 1e6) });
+    }
+    // ---- vaults (deposit into / withdraw from a Hyperliquid vault) ----
+    /** Deposit USDC into a vault (`usd` in dollars). */
+    async vaultDeposit(vault, usd) {
+        return this.exchange.vaultTransfer({ vaultAddress: vault, isDeposit: true, usd: Math.round(usd * 1e6) });
+    }
+    /** Withdraw USDC from a vault (`usd` in dollars). */
+    async vaultWithdraw(vault, usd) {
+        return this.exchange.vaultTransfer({ vaultAddress: vault, isDeposit: false, usd: Math.round(usd * 1e6) });
+    }
+    /** Vault details + your equity in it (public read; pass a user or use the signer). */
+    async vaultDetails(vault, user) {
+        return this._info.vaultDetails({ vaultAddress: vault, user: (user ?? this.address ?? undefined) });
+    }
+    // ---- account info ----
+    /** Your fee schedule + 14-day volume (default: the signer). */
+    async userFees(user) {
+        return this._info.userFees({ user: this.requireUser(user) });
+    }
+    /** Status of a single order by its oid (resting/filled/canceled). */
+    async orderStatus(oid, user) {
+        return this._info.orderStatus({ user: this.requireUser(user), oid });
+    }
     // The @nktkas SymbolConverter resolves asset ids + szDecimals across the main
     // perp dex, spot, AND HIP-3 builder dexes (so "xyz:TSLA" → its global asset id).
     symbols() {

package/dist/hyperliquid.test.js

@@ -1,7 +1,7 @@
 // Hyperliquid agent-wallet delegation: per-user agent keys must be deterministic
 // (recomputable, never stored) and the bound client must sign as the agent.
 import { describe, expect, it } from "vitest";
-import { Hyperliquid } from "./hyperliquid.js";
+import { Hyperliquid, parseHlPosition, parseBbo } from "./hyperliquid.js";
 import { localAccount } from "./eip712.js";
 const SECRET = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
 const MASTER = "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826";
@@ -29,3 +29,19 @@ describe("Hyperliquid agent-wallet delegation", () => {
         expect(() => bare.agentKey("user-1")).toThrow(/agent secret/i);
     });
 });
+describe("Hyperliquid parsers", () => {
+    it("parseHlPosition normalizes a clearinghouse position (side/size/fields)", () => {
+        const long = parseHlPosition({ coin: "BTC", szi: "0.5", entryPx: "60000", positionValue: "31000", unrealizedPnl: "1000", returnOnEquity: "0.12", leverage: { value: 10 }, liquidationPx: "40000", marginUsed: "3100" });
+        expect(long).toMatchObject({ coin: "BTC", size: 0.5, side: "long", entryPx: 60000, unrealizedPnl: 1000, leverage: 10, liquidationPx: 40000 });
+        const short = parseHlPosition({ coin: "ETH", szi: "-2" });
+        expect(short.side).toBe("short");
+        expect(short.size).toBe(2);
+        expect(short.liquidationPx).toBeNull();
+        expect(parseHlPosition({ coin: "X", szi: "0" }).side).toBe("flat");
+    });
+    it("parseBbo derives bid/ask/mid/spread from the L2 book", () => {
+        const bbo = parseBbo({ levels: [[{ px: "99.5" }], [{ px: "100.5" }]] });
+        expect(bbo).toEqual({ bid: 99.5, ask: 100.5, mid: 100, spread: 1 });
+        expect(parseBbo({ levels: [[], []] })).toEqual({ bid: null, ask: null, mid: null, spread: null });
+    });
+});

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { watchLogs } from "./watch.js";
 export type { WatchLogsOptions, WatchLogsResult } from "./watch.js";
 export { defineWatcher } from "./watcher.js";
 export type { WatcherEnv, WatcherMatch, WatcherScope, WatcherContext, WatcherDefinition, WatcherModule, SubscribeOptions, Confidence, MatchStatus, } from "./watcher.js";
+export { Signals, signals, DEFAULT_SIGNALS_URL } from "./signals.js";
+export type { SignalsOptions, Market, SignalMatch, Swap, Launch, EngineSnapshot, MarketFilter, } from "./signals.js";
 export { Relayer } from "./relayer.js";
 export { Queue, queue, queueEnvKey } from "./queue.js";
 export type { RelayerOptions } from "./relayer.js";
@@ -21,8 +23,25 @@ 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 { tokenMetadata, ownerOf, tokenURI } from "./reads.js";
+export type { TokenMetadata } from "./reads.js";
+export { resolveUri, fetchTokenMetadata } from "./nft.js";
+export type { NftMetadata, NftAttribute, FetchMetadataOptions } from "./nft.js";
+export { createSiweMessage, verifySiweMessage } from "./siwe.js";
+export type { SiweParams, SiweVerifyResult } from "./siwe.js";
+export { createSession, verifySession } from "./sessions.js";
+export type { SessionOptions } from "./sessions.js";
+export { json, error, withCors, CORS_HEADERS, Router, sse } from "./http.js";
+export type { RouteContext, RouteHandler, SseConnection } from "./http.js";
+export { rateLimit } from "./ratelimit.js";
+export type { KvLike, RateLimitOptions, RateLimitResult } from "./ratelimit.js";
+export { encrypt, decrypt } from "./aes.js";
+export { cached } from "./cache.js";
+export type { CacheOptions } from "./cache.js";
+export { verifyWebhook, signWebhook } from "./webhook.js";
+export type { VerifyWebhookParams, SignatureEncoding } from "./webhook.js";
 export { Hyperliquid } from "./hyperliquid.js";
-export type { HyperliquidOptions, PlaceOrderOptions, MarketOrderOptions, Tif, CandleInterval, CandlesOptions, AssetContext, AccountBalance, } from "./hyperliquid.js";
+export type { HyperliquidOptions, PlaceOrderOptions, MarketOrderOptions, Tif, CandleInterval, CandlesOptions, AssetContext, AccountBalance, PositionInfo, Bbo, } from "./hyperliquid.js";
 export { Polymarket } from "./polymarket.js";
 export type { PolymarketOptions, PolymarketCreds, PlaceOrderParams, Side, OrderType, SignatureType, PriceInterval, PriceHistoryOptions, MarketOutcome, ResolvedMarket, } from "./polymarket.js";
 export { hashTypedData, signTypedData, localAccount } from "./eip712.js";

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";
@@ -26,6 +30,15 @@ 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";
+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";

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