solid-drift 0.15.0 → 0.16.0

package/README.md

@@ -1094,6 +1094,37 @@ const connect = createConnectButton(() => btn, { strength: 0.35 });
 
 Returns `{ copyTick, chainPulse, status }`. `status()` is `"idle"`, `"ticking"` (check visible), or `"pulsing"` (ring expanding). Call `chainPulse()` after a successful connection or network switch. Under reduced motion there is no magnetic pull or scale; `copyTick()` and `chainPulse()` still show their overlays statically.
 
+### Web3 data layer
+
+A zero-dependency read layer for chain and market data as signals: public RPC and API endpoints over `fetch`, with user-swappable endpoints. Every network primitive shares the `{ data, error, status, retry, abort }` shape, is SSR-safe (nothing fetches on the server), and polls with error backoff. Defaults are conservative because public endpoints are rate-limited. This is read-only: transaction signing stays with wallet libraries.
+
+```tsx
+import {
+  createPoll, createTokenPrice, createPriceChange, createPriceCompare,
+  createGasPrice, createBalance, createTxReceipt, createBlockNumber,
+  createChainlinkPrice, createNFTMetadata, createENS, createIdenticon,
+  createChain, CHAINS, shortenAddress, isAddress, formatUnits, parseUnits,
+} from "solid-drift";
+```
+
+**Polling infra.** `createPoll(fetcher, options?)` fetches immediately (unless `immediate: false`), then on `interval` (default 30s). On error the interval multiplies by `backoff` (default 2) up to `maxInterval` (default 5min) and resets on the next success. Returns `{ data, error, status, retry, abort }`; `status()` is `"idle"`, `"loading"`, `"success"`, or `"error"`.
+
+**Pure helpers.** `isAddress(value)` checks `0x` + 40 hex chars. `shortenAddress(address, chars = 4)` renders `0xd8dA…6045` and passes invalid input through. `formatUnits(value, decimals = 18)` formats wei-style bigints as decimal strings without float artifacts; `parseUnits(value, decimals = 18)` parses them back and throws on invalid input. `CHAINS` maps seven chain ids (Ethereum, Optimism, BNB Chain, Polygon, Base, Arbitrum One, Sepolia) to name, currency, decimals, explorer, and a public RPC; `createChain(id)` looks one up as a reactive accessor (`undefined` for unknown ids).
+
+**Market.** `createTokenPrice(tokenId, options?)` polls CoinGecko's public API (default 60s; swap `endpoint` or `vsCurrency`) and exposes `price()` and `change24h()`. `createPriceChange(source, options?)` samples any numeric signal on change and on `sampleMs` (default 60s), keeps a rolling `windowMs` (default 1h), and reports the percent change between the first and last sample; `reset()` clears the window. `createPriceCompare(a, b)` compares two price signals with `ratio()`, `diffPercent()`, and `leader()` (`"a"`, `"b"`, or `"tie"`).
+
+**Chain (JSON-RPC).** `createGasPrice(options?)` reads `eth_gasPrice` every 15s as `{ wei, gwei }`. `createBalance(address, options?)` reads the native balance every 20s, or an ERC20 `balanceOf` when `token` is set, exposing `balance()` (bigint) and `formatted()`. `createTxReceipt(hash, options?)` polls every 4s until the receipt lands, then stops on its own; `mined()` mirrors that and `receipt()` carries `transactionHash`, `blockNumber`, `success`, and `gasUsed`. `createBlockNumber(options?)` polls the latest block every 12s as a chain-health heartbeat. `createChainlinkPrice(feed, options?)` reads a Chainlink `AggregatorV3Interface` feed on-chain (`decimals()` once, then `latestRoundData()` every 30s). All take an `endpoint` option defaulting to a public mainnet RPC.
+
+**Identity and NFTs.** `createNFTMetadata(contract, tokenId, options?)` fetches `tokenURI` on-chain, resolves the JSON (one-shot with `retry`), rewrites `ipfs://` through a gateway, and exposes `metadata()` (`name`, `description`, `image`, `attributes`, `raw`) plus `image()`. `createENS(address, options?)` reverse-resolves an address through the public ENS registry (one-shot with `retry`); `name()` is `undefined` when no name is set. `createIdenticon(address, options?)` renders a deterministic mirrored-grid SVG avatar as a data URI, pure computation, works on the server.
+
+```tsx
+const { price, change24h } = createTokenPrice("ethereum");
+const { change } = createPriceChange(price);
+const { formatted } = createBalance("0xd8dA…6045");
+const { mined, receipt } = createTxReceipt("0x5c50…f7b");
+const avatar = createIdenticon("0xd8dA…6045");
+```
+
 ### `createToast(options?)`
 
 A signal-native toast queue with choreographed lifecycle. The primitive owns timing and state; you own the rendering, so no component opinions leak into your design system. Each toast moves through `"entering"` to `"visible"` to `"leaving"` to removed on the shared animation clock: bind `state` to CSS classes or drift values for enter/exit motion without any timers of your own.

package/dist/index.d.ts

@@ -34,3 +34,5 @@ export { createStreamReveal, createAgentState, parseDriftSpec, createSpecPlayer,
 export type { StreamRevealStatus, StreamRevealOptions, StreamRevealControls, AgentState, AgentStateTransition, AgentStateOptions, AgentStateControls, DriftSpecPrimitive, DriftSpecStep, DriftSpec, SpecPlayerStatus, SpecPlayerControls, } from "./ai.js";
 export { createTxLifecycle, createTicker, createMintReveal, createConnectButton, } from "./web3.js";
 export type { TxState, TxStatusInput, TxLifecycleOptions, TxLifecycleControls, TickerOptions, TickerControls, MintRevealStatus, MintRevealOptions, MintRevealControls, ConnectButtonOptions, ConnectButtonStatus, ConnectButtonControls, } from "./web3.js";
+export { createPoll, shortenAddress, isAddress, formatUnits, parseUnits, CHAINS, createChain, createTokenPrice, createPriceChange, createPriceCompare, createGasPrice, createBalance, createTxReceipt, createBlockNumber, createChainlinkPrice, createNFTMetadata, createENS, createIdenticon, } from "./web3data.js";
+export type { PollStatus, PollOptions, PollControls, ChainInfo, TokenPrice, TokenPriceOptions, PriceChangeOptions, GasPriceOptions, GasPriceData, BalanceOptions, BalanceData, TxReceiptData, TxReceiptOptions, BlockNumberOptions, ChainlinkPriceOptions, NFTMetadata, NFTMetadataOptions, ENSOptions, IdenticonOptions, } from "./web3data.js";

package/dist/index.js

@@ -31,3 +31,4 @@ export { createKineticType, createScenePlayer, createShowreel, createCamera, cre
 export { createDrag, } from "./gesture.js";
 export { createStreamReveal, createAgentState, parseDriftSpec, createSpecPlayer, DriftSpecError, } from "./ai.js";
 export { createTxLifecycle, createTicker, createMintReveal, createConnectButton, } from "./web3.js";
+export { createPoll, shortenAddress, isAddress, formatUnits, parseUnits, CHAINS, createChain, createTokenPrice, createPriceChange, createPriceCompare, createGasPrice, createBalance, createTxReceipt, createBlockNumber, createChainlinkPrice, createNFTMetadata, createENS, createIdenticon, } from "./web3data.js";

package/dist/web3data.d.ts

@@ -0,0 +1,323 @@
+import { type Accessor } from "solid-js";
+/**
+ * Web3 data layer: zero-dependency chain and market data as signals.
+ *
+ * Public RPC and API endpoints over fetch, with user-swappable endpoints.
+ * Every network primitive shares the `{ data, error, status, retry, abort }`
+ * shape and is SSR-safe (nothing fetches on the server).
+ *
+ * Honest limits: public endpoints are rate-limited, so default polling
+ * intervals are conservative. This is a read-only data layer: transaction
+ * signing stays with wallet libraries like wagmi.
+ */
+export type PollStatus = "idle" | "loading" | "success" | "error";
+export interface PollOptions {
+    /** Milliseconds between fetches. Default 30000. */
+    interval?: number;
+    /** Error backoff multiplier. Default 2. */
+    backoff?: number;
+    /** Backoff cap in milliseconds. Default 300000. */
+    maxInterval?: number;
+    /** Fetch immediately on creation. Default true. */
+    immediate?: boolean;
+}
+export interface PollControls<T> {
+    data: Accessor<T | undefined>;
+    error: Accessor<Error | null>;
+    status: Accessor<PollStatus>;
+    /** Fetch now and reset the backoff. */
+    retry: () => void;
+    /** Stop polling and abort any in-flight request. */
+    abort: () => void;
+}
+/**
+ * Backoff polling infrastructure for the data primitives.
+ *
+ * Fetches immediately (unless `immediate: false`), then on `interval`.
+ * On error the interval multiplies by `backoff` up to `maxInterval` and
+ * resets on the next success. Uses `setTimeout`, so background tabs get
+ * the browser's natural timer throttling instead of a busy rAF loop.
+ * SSR-safe: never fetches on the server.
+ *
+ * ```ts
+ * const { data, status, retry, abort } = createPoll(
+ *   async (signal) => {
+ *     const res = await fetch("https://api.example.com/price", { signal });
+ *     return res.json();
+ *   },
+ *   { interval: 30000 },
+ * );
+ * ```
+ */
+export declare function createPoll<T>(fetcher: (signal: AbortSignal) => Promise<T>, options?: PollOptions): PollControls<T>;
+/**
+ * Shorten an EVM address: `0x1234567890abcdef...` becomes `0x1234…abcd`.
+ * Returns the input unchanged when it is not a valid address.
+ */
+export declare function shortenAddress(address: string, chars?: number): string;
+/** True for `0x` + 40 hex chars. Checksum-agnostic. */
+export declare function isAddress(value: string): boolean;
+/**
+ * Format a wei-style integer as a decimal string: `formatUnits(1500000000000000000n)`
+ * is `"1.5"`. Accepts bigint or integer strings. BigInt-safe, no floats.
+ */
+export declare function formatUnits(value: bigint | string, decimals?: number): string;
+/**
+ * Parse a decimal string into wei-style bigint: `parseUnits("1.5")` is
+ * `1500000000000000000n`. Throws on invalid input or too many decimals.
+ */
+export declare function parseUnits(value: string, decimals?: number): bigint;
+export interface ChainInfo {
+    id: number;
+    name: string;
+    currency: string;
+    decimals: number;
+    explorer: string;
+    rpc: string;
+}
+/** Registry of well-known EVM chains: id to name, currency, explorer, RPC. */
+export declare const CHAINS: Record<number, ChainInfo>;
+/**
+ * Look up a chain in `CHAINS` as an accessor. Unknown ids give `undefined`.
+ *
+ * ```ts
+ * const chain = createChain(() => 1)
+ * chain()?.explorer // "https://etherscan.io"
+ * ```
+ */
+export declare function createChain(source: number | Accessor<number>): Accessor<ChainInfo | undefined>;
+/**
+ * keccak256 of a byte array. Exported for tests; not part of the public API.
+ */
+export declare function keccak256(data: Uint8Array): Uint8Array<ArrayBuffer>;
+export interface TokenPrice {
+    /** Price in the quote currency. */
+    price: number;
+    /** 24h change percent, when the source reports it. */
+    change24h?: number;
+}
+export interface TokenPriceOptions extends PollOptions {
+    /** Quote currency id. Default "usd". */
+    vsCurrency?: string;
+    /** Price API base. Default CoinGecko public API. */
+    endpoint?: string;
+}
+/**
+ * Live token price as a signal, via CoinGecko's public API.
+ *
+ * The free endpoint is rate-limited; the default 60s interval is
+ * conservative on purpose. Pass your own `endpoint` (any base that
+ * answers `/simple/price?ids={id}&vs_currencies={vs}&include_24hr_change=true`).
+ *
+ * ```ts
+ * const { price, change24h, status } = createTokenPrice("ethereum");
+ * <Show when={status() === "success"}>
+ *   ${(price() ?? 0).toFixed(2)} ({(change24h() ?? 0).toFixed(1)}%)
+ * </Show>
+ * ```
+ */
+export declare function createTokenPrice(tokenId: string | Accessor<string>, options?: TokenPriceOptions): PollControls<TokenPrice> & {
+    price: Accessor<number | undefined>;
+    change24h: Accessor<number | undefined>;
+};
+export interface PriceChangeOptions {
+    /** Rolling window in ms. Default 3600000 (1h). */
+    windowMs?: number;
+    /** How often to sample the source in ms. Default 60000. */
+    sampleMs?: number;
+}
+/**
+ * Percent change of any numeric signal over a rolling window.
+ *
+ * Samples the source on each change and on `sampleMs`, keeps samples
+ * within `windowMs`, and reports `(last - first) / first * 100`.
+ * `undefined` until at least two samples exist. Signal-native, no network.
+ *
+ * ```ts
+ * const { price } = createTokenPrice("ethereum");
+ * const { change, reset } = createPriceChange(price);
+ * ```
+ */
+export declare function createPriceChange(source: Accessor<number | undefined>, options?: PriceChangeOptions): {
+    change: Accessor<number | undefined>;
+    reset: () => void;
+};
+/**
+ * Compare two numeric signals: their ratio, percent difference, and which
+ * is larger. Any side `undefined` makes everything `undefined` until both
+ * have values. Signal-native, no network.
+ *
+ * ```ts
+ * const { price: eth } = createTokenPrice("ethereum");
+ * const { price: btc } = createTokenPrice("bitcoin");
+ * const { ratio, diffPercent, leader } = createPriceCompare(eth, btc);
+ * ```
+ */
+export declare function createPriceCompare(a: Accessor<number | undefined>, b: Accessor<number | undefined>): {
+    ratio: Accessor<number | undefined>;
+    diffPercent: Accessor<number | undefined>;
+    leader: Accessor<"a" | "b" | "tie" | undefined>;
+};
+export interface GasPriceOptions extends PollOptions {
+    /** JSON-RPC endpoint. Default a public mainnet endpoint. */
+    endpoint?: string;
+}
+export interface GasPriceData {
+    wei: bigint;
+    gwei: number;
+}
+/**
+ * Current gas price over JSON-RPC (`eth_gasPrice`), as wei bigint and gwei.
+ * Default 15s polling. Swap `endpoint` for any chain.
+ */
+export declare function createGasPrice(options?: GasPriceOptions): PollControls<GasPriceData> & {
+    wei: Accessor<bigint | undefined>;
+    gwei: Accessor<number | undefined>;
+};
+export interface BalanceOptions extends PollOptions {
+    /** JSON-RPC endpoint. Default a public mainnet endpoint. */
+    endpoint?: string;
+    /** ERC20 token contract. Omit for the native balance. */
+    token?: string;
+    /** Decimals for formatting. Default 18. */
+    decimals?: number;
+}
+export interface BalanceData {
+    balance: bigint;
+    formatted: string;
+}
+/**
+ * Token balance of an address: native (`eth_getBalance`) or ERC20
+ * (`balanceOf` via `eth_call`). Read-only; never signs.
+ *
+ * ```ts
+ * const { formatted } = createBalance("0xabc…", { token: "0xdef…" });
+ * ```
+ */
+export declare function createBalance(address: string, options?: BalanceOptions): PollControls<BalanceData> & {
+    balance: Accessor<bigint | undefined>;
+    formatted: Accessor<string | undefined>;
+};
+export interface TxReceiptData {
+    transactionHash: string;
+    blockNumber: number;
+    /** true when `status` is 0x1, false when 0x0 (reverted). */
+    success: boolean;
+    gasUsed: bigint;
+}
+export interface TxReceiptOptions extends PollOptions {
+    /** JSON-RPC endpoint. Default a public mainnet endpoint. */
+    endpoint?: string;
+}
+/**
+ * Watch a transaction hash until its receipt lands. Polls every 4s and
+ * stops on its own once the receipt arrives; `mined()` mirrors that.
+ * Read-only confirmation; pairs with `createTxLifecycle` from web3.ts.
+ */
+export declare function createTxReceipt(hash: string, options?: TxReceiptOptions): PollControls<TxReceiptData | null> & {
+    receipt: Accessor<TxReceiptData | null | undefined>;
+    mined: Accessor<boolean>;
+};
+export interface BlockNumberOptions extends PollOptions {
+    /** JSON-RPC endpoint. Default a public mainnet endpoint. */
+    endpoint?: string;
+}
+/**
+ * Latest block number over JSON-RPC. Default 12s polling.
+ * Handy as a chain-health heartbeat and a cache-busting ticker.
+ */
+export declare function createBlockNumber(options?: BlockNumberOptions): PollControls<number> & {
+    blockNumber: Accessor<number | undefined>;
+};
+export interface ChainlinkPriceOptions extends PollOptions {
+    /** JSON-RPC endpoint. Default a public mainnet endpoint. */
+    endpoint?: string;
+}
+/**
+ * Read a Chainlink `AggregatorV3Interface` price feed on-chain:
+ * `decimals()` once, then `latestRoundData()` polled every 30s.
+ * Feed addresses live on the
+ * [Chainlink docs](https://docs.chain.link/data-feeds/price-feeds/addresses).
+ *
+ * ```ts
+ * // ETH / USD feed on mainnet
+ * const { price } = createChainlinkPrice("0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419");
+ * ```
+ */
+export declare function createChainlinkPrice(feed: string, options?: ChainlinkPriceOptions): PollControls<number> & {
+    price: Accessor<number | undefined>;
+};
+export interface NFTMetadata {
+    name?: string;
+    description?: string;
+    image?: string;
+    attributes?: Array<Record<string, unknown>>;
+    raw: unknown;
+}
+export interface NFTMetadataOptions {
+    /** JSON-RPC endpoint for `tokenURI`. Default a public mainnet endpoint. */
+    endpoint?: string;
+    /** IPFS gateway base. Default "https://ipfs.io". */
+    gateway?: string;
+}
+/**
+ * Fetch an NFT's `tokenURI` on-chain and resolve its JSON metadata
+ * (one-shot, with `retry`). `ipfs://` URIs are rewritten through the
+ * gateway. Returns the parsed fields plus `raw` for anything custom.
+ *
+ * ```ts
+ * const { metadata, image, status, retry } = createNFTMetadata(
+ *   "0xcontract…",
+ *   42,
+ * );
+ * ```
+ */
+export declare function createNFTMetadata(contract: string, tokenId: string | number | bigint, options?: NFTMetadataOptions): {
+    data: Accessor<NFTMetadata | undefined>;
+    error: Accessor<Error | null>;
+    status: Accessor<PollStatus>;
+    retry: () => void;
+    abort: () => void;
+    metadata: Accessor<NFTMetadata | undefined>;
+    image: Accessor<string | undefined>;
+};
+export interface ENSOptions {
+    /** JSON-RPC endpoint. Default a public mainnet endpoint. */
+    endpoint?: string;
+}
+/**
+ * Reverse-resolve an address to its ENS name via the public ENS registry
+ * (one-shot, with `retry`). `undefined` when the address has no name set;
+ * errors (network, RPC) surface on `error`.
+ *
+ * ```ts
+ * const { name, status } = createENS("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
+ * ```
+ */
+export declare function createENS(address: string, options?: ENSOptions): {
+    data: Accessor<string | undefined>;
+    error: Accessor<Error | null>;
+    status: Accessor<PollStatus>;
+    retry: () => void;
+    abort: () => void;
+    name: Accessor<string | undefined>;
+};
+export interface IdenticonOptions {
+    /** Pixel size of the square image. Default 64. */
+    size?: number;
+    /** Grid cells per side. Default 8. */
+    cells?: number;
+    /** Background color. Default "#f0f0f0". */
+    background?: string;
+}
+/**
+ * Deterministic identicon avatar for any address as a data URI: a mirrored
+ * random-walk grid in SVG, so the same address always renders the same
+ * image. Pure computation, works on the server, no network.
+ *
+ * ```tsx
+ * const avatar = createIdenticon("0xabc…");
+ * <img src={avatar()} alt="avatar" width={64} height={64} />;
+ * ```
+ */
+export declare function createIdenticon(address: string | Accessor<string>, options?: IdenticonOptions): Accessor<string>;

package/dist/web3data.js

@@ -0,0 +1,751 @@
+import { createEffect, createSignal, onCleanup, } from "solid-js";
+/**
+ * Backoff polling infrastructure for the data primitives.
+ *
+ * Fetches immediately (unless `immediate: false`), then on `interval`.
+ * On error the interval multiplies by `backoff` up to `maxInterval` and
+ * resets on the next success. Uses `setTimeout`, so background tabs get
+ * the browser's natural timer throttling instead of a busy rAF loop.
+ * SSR-safe: never fetches on the server.
+ *
+ * ```ts
+ * const { data, status, retry, abort } = createPoll(
+ *   async (signal) => {
+ *     const res = await fetch("https://api.example.com/price", { signal });
+ *     return res.json();
+ *   },
+ *   { interval: 30000 },
+ * );
+ * ```
+ */
+export function createPoll(fetcher, options = {}) {
+    const { interval = 30000, backoff = 2, maxInterval = 300000, immediate = true, } = options;
+    const [data, setData] = createSignal(undefined);
+    const [error, setError] = createSignal(null);
+    const [status, setStatus] = createSignal("idle");
+    let timer = null;
+    let aborter = null;
+    let delay = interval;
+    let stopped = false;
+    const clearTimer = () => {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    };
+    const run = async () => {
+        if (stopped || typeof window === "undefined")
+            return;
+        clearTimer();
+        aborter?.abort();
+        aborter = new AbortController();
+        const signal = aborter.signal;
+        setStatus("loading");
+        try {
+            const value = await fetcher(signal);
+            if (signal.aborted || stopped)
+                return;
+            setData(() => value);
+            setError(null);
+            setStatus("success");
+            delay = interval;
+        }
+        catch (e) {
+            if (signal.aborted || stopped)
+                return;
+            setError(e instanceof Error ? e : new Error(String(e)));
+            setStatus("error");
+            delay = Math.min(delay * backoff, maxInterval);
+        }
+        if (!stopped && typeof window !== "undefined") {
+            timer = setTimeout(() => void run(), delay);
+        }
+    };
+    const retry = () => {
+        stopped = false;
+        delay = interval;
+        void run();
+    };
+    const abort = () => {
+        stopped = true;
+        clearTimer();
+        aborter?.abort();
+        aborter = null;
+    };
+    if (typeof window !== "undefined" && immediate) {
+        void run();
+    }
+    onCleanup(abort);
+    return { data, error, status, retry, abort };
+}
+/**
+ * Shorten an EVM address: `0x1234567890abcdef...` becomes `0x1234…abcd`.
+ * Returns the input unchanged when it is not a valid address.
+ */
+export function shortenAddress(address, chars = 4) {
+    if (!isAddress(address))
+        return address;
+    return `${address.slice(0, 2 + chars)}…${address.slice(-chars)}`;
+}
+/** True for `0x` + 40 hex chars. Checksum-agnostic. */
+export function isAddress(value) {
+    return /^0x[0-9a-fA-F]{40}$/.test(value);
+}
+/**
+ * Format a wei-style integer as a decimal string: `formatUnits(1500000000000000000n)`
+ * is `"1.5"`. Accepts bigint or integer strings. BigInt-safe, no floats.
+ */
+export function formatUnits(value, decimals = 18) {
+    const str = typeof value === "bigint" ? value.toString() : value;
+    if (!/^-?\d+$/.test(str)) {
+        throw new Error("formatUnits: value must be an integer string or bigint.");
+    }
+    const negative = str.startsWith("-");
+    const digits = negative ? str.slice(1) : str;
+    const padded = digits.padStart(decimals + 1, "0");
+    const int = decimals > 0 ? padded.slice(0, -decimals) : padded;
+    const frac = decimals > 0 ? padded.slice(-decimals).replace(/0+$/, "") : "";
+    const intClean = int.replace(/^0+(?=\d)/, "");
+    return (negative ? "-" : "") + intClean + (frac ? `.${frac}` : "");
+}
+/**
+ * Parse a decimal string into wei-style bigint: `parseUnits("1.5")` is
+ * `1500000000000000000n`. Throws on invalid input or too many decimals.
+ */
+export function parseUnits(value, decimals = 18) {
+    const m = /^(-?)(\d*)(?:\.(\d*))?$/.exec(value.trim());
+    if (!m || (m[2] === "" && m[3] === "")) {
+        throw new Error("parseUnits: invalid decimal string.");
+    }
+    const fracPart = m[3] ?? "";
+    if (fracPart.length > decimals) {
+        throw new Error("parseUnits: too many decimal places.");
+    }
+    const int = (m[2] === "" ? "0" : m[2]) + fracPart.padEnd(decimals, "0");
+    const clean = int.replace(/^0+(?=\d)/, "");
+    return BigInt(`${m[1]}${clean}`);
+}
+/** Registry of well-known EVM chains: id to name, currency, explorer, RPC. */
+export const CHAINS = {
+    1: {
+        id: 1,
+        name: "Ethereum",
+        currency: "ETH",
+        decimals: 18,
+        explorer: "https://etherscan.io",
+        rpc: "https://ethereum.publicnode.com",
+    },
+    10: {
+        id: 10,
+        name: "Optimism",
+        currency: "ETH",
+        decimals: 18,
+        explorer: "https://optimistic.etherscan.io",
+        rpc: "https://optimism.publicnode.com",
+    },
+    56: {
+        id: 56,
+        name: "BNB Chain",
+        currency: "BNB",
+        decimals: 18,
+        explorer: "https://bscscan.com",
+        rpc: "https://bsc.publicnode.com",
+    },
+    137: {
+        id: 137,
+        name: "Polygon",
+        currency: "POL",
+        decimals: 18,
+        explorer: "https://polygonscan.com",
+        rpc: "https://polygon-bor.publicnode.com",
+    },
+    8453: {
+        id: 8453,
+        name: "Base",
+        currency: "ETH",
+        decimals: 18,
+        explorer: "https://basescan.org",
+        rpc: "https://base.publicnode.com",
+    },
+    42161: {
+        id: 42161,
+        name: "Arbitrum One",
+        currency: "ETH",
+        decimals: 18,
+        explorer: "https://arbiscan.io",
+        rpc: "https://arbitrum-one.publicnode.com",
+    },
+    11155111: {
+        id: 11155111,
+        name: "Sepolia",
+        currency: "ETH",
+        decimals: 18,
+        explorer: "https://sepolia.etherscan.io",
+        rpc: "https://ethereum-sepolia.publicnode.com",
+    },
+};
+/**
+ * Look up a chain in `CHAINS` as an accessor. Unknown ids give `undefined`.
+ *
+ * ```ts
+ * const chain = createChain(() => 1)
+ * chain()?.explorer // "https://etherscan.io"
+ * ```
+ */
+export function createChain(source) {
+    const get = typeof source === "function" ? source : () => source;
+    return () => CHAINS[get()];
+}
+// ---------------------------------------------------------------------------
+// keccak256 (for ENS namehash). Compact BigInt implementation, no dependencies.
+// ---------------------------------------------------------------------------
+const KECCAK_RC = [
+    0x0000000000000001n, 0x0000000000008082n, 0x800000000000808an,
+    0x8000000080008000n, 0x000000000000808bn, 0x0000000080000001n,
+    0x8000000080008081n, 0x8000000000008009n, 0x000000000000008an,
+    0x0000000000000088n, 0x0000000080008009n, 0x000000008000000an,
+    0x000000008000808bn, 0x800000000000008bn, 0x8000000000008089n,
+    0x8000000000008003n, 0x8000000000008002n, 0x8000000000000080n,
+    0x000000000000800an, 0x800000008000000an, 0x8000000080008081n,
+    0x8000000000008080n, 0x0000000080000001n, 0x8000000080008008n,
+];
+const KECCAK_ROT = [
+    [0, 36, 3, 41, 18],
+    [1, 44, 10, 45, 2],
+    [62, 6, 43, 15, 61],
+    [28, 55, 25, 21, 56],
+    [27, 20, 39, 8, 14],
+];
+const MASK64 = 0xffffffffffffffffn;
+function rotl64(v, n) {
+    if (n === 0)
+        return v;
+    return (((v << BigInt(n)) | (v >> BigInt(64 - n))) & MASK64);
+}
+function keccakF(state) {
+    for (let round = 0; round < 24; round++) {
+        const c = [0n, 0n, 0n, 0n, 0n];
+        for (let x = 0; x < 5; x++) {
+            for (let y = 0; y < 5; y++)
+                c[x] ^= state[x + 5 * y];
+        }
+        const d = [0n, 0n, 0n, 0n, 0n];
+        for (let x = 0; x < 5; x++) {
+            d[x] = c[(x + 4) % 5] ^ rotl64(c[(x + 1) % 5], 1);
+        }
+        for (let x = 0; x < 5; x++) {
+            for (let y = 0; y < 5; y++)
+                state[x + 5 * y] ^= d[x];
+        }
+        const b = new Array(25);
+        for (let x = 0; x < 5; x++) {
+            for (let y = 0; y < 5; y++) {
+                b[y + 5 * ((2 * x + 3 * y) % 5)] = rotl64(state[x + 5 * y], KECCAK_ROT[x][y]);
+            }
+        }
+        for (let x = 0; x < 5; x++) {
+            for (let y = 0; y < 5; y++) {
+                state[x + 5 * y] =
+                    b[x + 5 * y] ^ ((~b[(x + 1) % 5 + 5 * y] & MASK64) & b[(x + 2) % 5 + 5 * y]);
+            }
+        }
+        state[0] ^= KECCAK_RC[round];
+    }
+}
+/**
+ * keccak256 of a byte array. Exported for tests; not part of the public API.
+ */
+export function keccak256(data) {
+    const RATE = 136;
+    let total = data.length + 1;
+    total = total % RATE === 0 ? total + RATE : total + (RATE - (total % RATE));
+    const padded = new Uint8Array(total);
+    padded.set(data, 0);
+    padded[data.length] = 0x01;
+    padded[total - 1] |= 0x80;
+    const state = new Array(25).fill(0n);
+    for (let off = 0; off < total; off += RATE) {
+        for (let i = 0; i < RATE / 8; i++) {
+            let lane = 0n;
+            for (let j = 0; j < 8; j++) {
+                lane |= BigInt(padded[off + i * 8 + j]) << BigInt(8 * j);
+            }
+            state[i] ^= lane;
+        }
+        keccakF(state);
+    }
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 4; i++) {
+        for (let j = 0; j < 8; j++) {
+            out[i * 8 + j] = Number((state[i] >> BigInt(8 * j)) & 0xffn);
+        }
+    }
+    return out;
+}
+function bytesToHex(bytes) {
+    return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function namehash(name) {
+    let node = new Uint8Array(32);
+    if (name) {
+        const labels = name.split(".");
+        for (let i = labels.length - 1; i >= 0; i--) {
+            const combined = new Uint8Array(64);
+            combined.set(node, 0);
+            combined.set(keccak256(new TextEncoder().encode(labels[i])), 32);
+            node = keccak256(combined);
+        }
+    }
+    return `0x${bytesToHex(node)}`;
+}
+const DEFAULT_ENDPOINT = "https://ethereum.publicnode.com";
+async function rpc(endpoint, method, params, signal) {
+    const res = await fetch(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        signal,
+    });
+    if (!res.ok) {
+        throw new Error(`RPC ${method} failed with HTTP ${res.status}.`);
+    }
+    const json = (await res.json());
+    if (json.error) {
+        throw new Error(`RPC ${method} error: ${json.error.message ?? "unknown"}.`);
+    }
+    return json.result;
+}
+function parseAbiString(hex) {
+    const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+    const len = parseInt(clean.slice(64, 128), 16);
+    const dataHex = clean.slice(128, 128 + len * 2);
+    const bytes = new Uint8Array(dataHex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(dataHex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * Live token price as a signal, via CoinGecko's public API.
+ *
+ * The free endpoint is rate-limited; the default 60s interval is
+ * conservative on purpose. Pass your own `endpoint` (any base that
+ * answers `/simple/price?ids={id}&vs_currencies={vs}&include_24hr_change=true`).
+ *
+ * ```ts
+ * const { price, change24h, status } = createTokenPrice("ethereum");
+ * <Show when={status() === "success"}>
+ *   ${(price() ?? 0).toFixed(2)} ({(change24h() ?? 0).toFixed(1)}%)
+ * </Show>
+ * ```
+ */
+export function createTokenPrice(tokenId, options = {}) {
+    const { vsCurrency = "usd", endpoint = "https://api.coingecko.com/api/v3", ...poll } = options;
+    const getId = typeof tokenId === "function" ? tokenId : () => tokenId;
+    const p = createPoll(async (signal) => {
+        const res = await fetch(`${endpoint}/simple/price?ids=${encodeURIComponent(getId())}&vs_currencies=${encodeURIComponent(vsCurrency)}&include_24hr_change=true`, { signal });
+        if (!res.ok) {
+            throw new Error(`Price fetch failed with HTTP ${res.status}.`);
+        }
+        const json = (await res.json());
+        const row = json[getId()];
+        if (!row || typeof row[vsCurrency] !== "number") {
+            throw new Error(`No price returned for "${getId()}".`);
+        }
+        return {
+            price: row[vsCurrency],
+            change24h: row[`${vsCurrency}_24h_change`],
+        };
+    }, { interval: 60000, ...poll });
+    return {
+        ...p,
+        price: () => p.data()?.price,
+        change24h: () => p.data()?.change24h,
+    };
+}
+/**
+ * Percent change of any numeric signal over a rolling window.
+ *
+ * Samples the source on each change and on `sampleMs`, keeps samples
+ * within `windowMs`, and reports `(last - first) / first * 100`.
+ * `undefined` until at least two samples exist. Signal-native, no network.
+ *
+ * ```ts
+ * const { price } = createTokenPrice("ethereum");
+ * const { change, reset } = createPriceChange(price);
+ * ```
+ */
+export function createPriceChange(source, options = {}) {
+    const { windowMs = 3600000, sampleMs = 60000 } = options;
+    const [samples, setSamples] = createSignal([]);
+    const take = () => {
+        const v = source();
+        if (v == null || typeof window === "undefined")
+            return;
+        const t = Date.now();
+        setSamples((prev) => [...prev.filter((s) => t - s.t <= windowMs), { t, v }]);
+    };
+    createEffect(() => {
+        source();
+        take();
+    });
+    if (typeof window !== "undefined") {
+        const id = setInterval(take, sampleMs);
+        onCleanup(() => clearInterval(id));
+    }
+    return {
+        change: () => {
+            const list = samples();
+            if (list.length < 2)
+                return undefined;
+            const first = list[0].v;
+            const last = list[list.length - 1].v;
+            if (first === 0)
+                return undefined;
+            return ((last - first) / Math.abs(first)) * 100;
+        },
+        reset: () => setSamples([]),
+    };
+}
+/**
+ * Compare two numeric signals: their ratio, percent difference, and which
+ * is larger. Any side `undefined` makes everything `undefined` until both
+ * have values. Signal-native, no network.
+ *
+ * ```ts
+ * const { price: eth } = createTokenPrice("ethereum");
+ * const { price: btc } = createTokenPrice("bitcoin");
+ * const { ratio, diffPercent, leader } = createPriceCompare(eth, btc);
+ * ```
+ */
+export function createPriceCompare(a, b) {
+    return {
+        ratio: () => {
+            const x = a();
+            const y = b();
+            if (x == null || y == null || y === 0)
+                return undefined;
+            return x / y;
+        },
+        diffPercent: () => {
+            const x = a();
+            const y = b();
+            if (x == null || y == null || y === 0)
+                return undefined;
+            return ((x - y) / Math.abs(y)) * 100;
+        },
+        leader: () => {
+            const x = a();
+            const y = b();
+            if (x == null || y == null)
+                return undefined;
+            if (x === y)
+                return "tie";
+            return x > y ? "a" : "b";
+        },
+    };
+}
+/**
+ * Current gas price over JSON-RPC (`eth_gasPrice`), as wei bigint and gwei.
+ * Default 15s polling. Swap `endpoint` for any chain.
+ */
+export function createGasPrice(options = {}) {
+    const { endpoint = DEFAULT_ENDPOINT, ...poll } = options;
+    const p = createPoll(async (signal) => {
+        const hex = await rpc(endpoint, "eth_gasPrice", [], signal);
+        const wei = BigInt(hex);
+        return { wei, gwei: Number(wei) / 1e9 };
+    }, { interval: 15000, ...poll });
+    return { ...p, wei: () => p.data()?.wei, gwei: () => p.data()?.gwei };
+}
+const BALANCE_OF_SELECTOR = "0x70a08231";
+/**
+ * Token balance of an address: native (`eth_getBalance`) or ERC20
+ * (`balanceOf` via `eth_call`). Read-only; never signs.
+ *
+ * ```ts
+ * const { formatted } = createBalance("0xabc…", { token: "0xdef…" });
+ * ```
+ */
+export function createBalance(address, options = {}) {
+    const { endpoint = DEFAULT_ENDPOINT, token, decimals = 18, ...poll } = options;
+    if (!isAddress(address)) {
+        throw new Error("createBalance: invalid address.");
+    }
+    const p = createPoll(async (signal) => {
+        let hex;
+        if (token) {
+            if (!isAddress(token)) {
+                throw new Error("createBalance: invalid token address.");
+            }
+            const data = BALANCE_OF_SELECTOR + address.slice(2).toLowerCase().padStart(64, "0");
+            hex = await rpc(endpoint, "eth_call", [{ to: token, data }, "latest"], signal);
+        }
+        else {
+            hex = await rpc(endpoint, "eth_getBalance", [address, "latest"], signal);
+        }
+        const balance = BigInt(hex);
+        return { balance, formatted: formatUnits(balance, decimals) };
+    }, { interval: 20000, ...poll });
+    return {
+        ...p,
+        balance: () => p.data()?.balance,
+        formatted: () => p.data()?.formatted,
+    };
+}
+/**
+ * Watch a transaction hash until its receipt lands. Polls every 4s and
+ * stops on its own once the receipt arrives; `mined()` mirrors that.
+ * Read-only confirmation; pairs with `createTxLifecycle` from web3.ts.
+ */
+export function createTxReceipt(hash, options = {}) {
+    const { endpoint = DEFAULT_ENDPOINT, ...poll } = options;
+    const p = createPoll(async (signal) => {
+        const raw = await rpc(endpoint, "eth_getTransactionReceipt", [hash], signal);
+        if (!raw)
+            return null;
+        return {
+            transactionHash: raw.transactionHash,
+            blockNumber: parseInt(raw.blockNumber, 16),
+            success: raw.status === "0x1",
+            gasUsed: BigInt(raw.gasUsed),
+        };
+    }, { interval: 4000, ...poll });
+    createEffect(() => {
+        if (p.data() != null)
+            p.abort();
+    });
+    return { ...p, receipt: p.data, mined: () => p.data() != null };
+}
+/**
+ * Latest block number over JSON-RPC. Default 12s polling.
+ * Handy as a chain-health heartbeat and a cache-busting ticker.
+ */
+export function createBlockNumber(options = {}) {
+    const { endpoint = DEFAULT_ENDPOINT, ...poll } = options;
+    const p = createPoll(async (signal) => {
+        const hex = await rpc(endpoint, "eth_blockNumber", [], signal);
+        return parseInt(hex, 16);
+    }, { interval: 12000, ...poll });
+    return { ...p, blockNumber: p.data };
+}
+const CHAINLINK_DECIMALS_SELECTOR = "0x313ce567";
+const CHAINLINK_LATEST_SELECTOR = "0xfeaf968c";
+/**
+ * Read a Chainlink `AggregatorV3Interface` price feed on-chain:
+ * `decimals()` once, then `latestRoundData()` polled every 30s.
+ * Feed addresses live on the
+ * [Chainlink docs](https://docs.chain.link/data-feeds/price-feeds/addresses).
+ *
+ * ```ts
+ * // ETH / USD feed on mainnet
+ * const { price } = createChainlinkPrice("0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419");
+ * ```
+ */
+export function createChainlinkPrice(feed, options = {}) {
+    const { endpoint = DEFAULT_ENDPOINT, ...poll } = options;
+    if (!isAddress(feed)) {
+        throw new Error("createChainlinkPrice: invalid feed address.");
+    }
+    let decimals = null;
+    const p = createPoll(async (signal) => {
+        if (decimals === null) {
+            const raw = await rpc(endpoint, "eth_call", [{ to: feed, data: CHAINLINK_DECIMALS_SELECTOR }, "latest"], signal);
+            decimals = parseInt(raw, 16);
+        }
+        const raw = await rpc(endpoint, "eth_call", [{ to: feed, data: CHAINLINK_LATEST_SELECTOR }, "latest"], signal);
+        const answer = BigInt(`0x${raw.slice(2 + 64, 2 + 128)}`);
+        return Number(answer) / 10 ** decimals;
+    }, { interval: 30000, ...poll });
+    return { ...p, price: p.data };
+}
+/**
+ * Fetch an NFT's `tokenURI` on-chain and resolve its JSON metadata
+ * (one-shot, with `retry`). `ipfs://` URIs are rewritten through the
+ * gateway. Returns the parsed fields plus `raw` for anything custom.
+ *
+ * ```ts
+ * const { metadata, image, status, retry } = createNFTMetadata(
+ *   "0xcontract…",
+ *   42,
+ * );
+ * ```
+ */
+export function createNFTMetadata(contract, tokenId, options = {}) {
+    const { endpoint = DEFAULT_ENDPOINT, gateway = "https://ipfs.io" } = options;
+    if (!isAddress(contract)) {
+        throw new Error("createNFTMetadata: invalid contract address.");
+    }
+    const [data, setData] = createSignal(undefined);
+    const [error, setError] = createSignal(null);
+    const [status, setStatus] = createSignal("idle");
+    let aborter = null;
+    const toGateway = (uri) => uri.startsWith("ipfs://") ? `${gateway}/ipfs/${uri.slice(7)}` : uri;
+    const load = async () => {
+        if (typeof window === "undefined")
+            return;
+        aborter?.abort();
+        aborter = new AbortController();
+        const signal = aborter.signal;
+        setStatus("loading");
+        try {
+            const idHex = BigInt(tokenId).toString(16).padStart(64, "0");
+            const uriRaw = await rpc(endpoint, "eth_call", [{ to: contract, data: `0xc87b56dd${idHex}` }, "latest"], signal);
+            const uri = parseAbiString(uriRaw);
+            const res = await fetch(toGateway(uri), { signal });
+            if (!res.ok) {
+                throw new Error(`Metadata fetch failed with HTTP ${res.status}.`);
+            }
+            const json = (await res.json());
+            if (signal.aborted)
+                return;
+            setData({
+                name: typeof json.name === "string" ? json.name : undefined,
+                description: typeof json.description === "string" ? json.description : undefined,
+                image: typeof json.image === "string" ? toGateway(json.image) : undefined,
+                attributes: Array.isArray(json.attributes)
+                    ? json.attributes
+                    : undefined,
+                raw: json,
+            });
+            setError(null);
+            setStatus("success");
+        }
+        catch (e) {
+            if (signal.aborted)
+                return;
+            setError(e instanceof Error ? e : new Error(String(e)));
+            setStatus("error");
+        }
+    };
+    if (typeof window !== "undefined") {
+        void load();
+    }
+    onCleanup(() => aborter?.abort());
+    return {
+        data,
+        error,
+        status,
+        retry: () => void load(),
+        abort: () => aborter?.abort(),
+        metadata: data,
+        image: () => data()?.image,
+    };
+}
+const ENS_REGISTRY = "0x00000000000C2C1F563e148400aA1D00d43e5D";
+const ENS_RESOLVER_SELECTOR = "0x0178b8bf";
+const ENS_NAME_SELECTOR = "0x691f3431";
+/**
+ * Reverse-resolve an address to its ENS name via the public ENS registry
+ * (one-shot, with `retry`). `undefined` when the address has no name set;
+ * errors (network, RPC) surface on `error`.
+ *
+ * ```ts
+ * const { name, status } = createENS("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
+ * ```
+ */
+export function createENS(address, options = {}) {
+    const { endpoint = DEFAULT_ENDPOINT } = options;
+    if (!isAddress(address)) {
+        throw new Error("createENS: invalid address.");
+    }
+    const [data, setData] = createSignal(undefined);
+    const [error, setError] = createSignal(null);
+    const [status, setStatus] = createSignal("idle");
+    let aborter = null;
+    const load = async () => {
+        if (typeof window === "undefined")
+            return;
+        aborter?.abort();
+        aborter = new AbortController();
+        const signal = aborter.signal;
+        setStatus("loading");
+        try {
+            const node = namehash(`${address.slice(2).toLowerCase()}.addr.reverse`);
+            const resolverRaw = await rpc(endpoint, "eth_call", [
+                { to: ENS_REGISTRY, data: `${ENS_RESOLVER_SELECTOR}${node.slice(2)}` },
+                "latest",
+            ], signal);
+            const resolver = `0x${resolverRaw.slice(-40)}`;
+            if (/^0x0+$/.test(resolver)) {
+                if (!signal.aborted) {
+                    setData(undefined);
+                    setError(null);
+                    setStatus("success");
+                }
+                return;
+            }
+            const nameRaw = await rpc(endpoint, "eth_call", [
+                { to: resolver, data: `${ENS_NAME_SELECTOR}${node.slice(2)}` },
+                "latest",
+            ], signal);
+            const name = parseAbiString(nameRaw);
+            if (signal.aborted)
+                return;
+            setData(name || undefined);
+            setError(null);
+            setStatus("success");
+        }
+        catch (e) {
+            if (signal.aborted)
+                return;
+            setError(e instanceof Error ? e : new Error(String(e)));
+            setStatus("error");
+        }
+    };
+    if (typeof window !== "undefined") {
+        void load();
+    }
+    onCleanup(() => aborter?.abort());
+    return {
+        data,
+        error,
+        status,
+        retry: () => void load(),
+        abort: () => aborter?.abort(),
+        name: data,
+    };
+}
+/**
+ * Deterministic identicon avatar for any address as a data URI: a mirrored
+ * random-walk grid in SVG, so the same address always renders the same
+ * image. Pure computation, works on the server, no network.
+ *
+ * ```tsx
+ * const avatar = createIdenticon("0xabc…");
+ * <img src={avatar()} alt="avatar" width={64} height={64} />;
+ * ```
+ */
+export function createIdenticon(address, options = {}) {
+    const { size = 64, cells = 8, background = "#f0f0f0" } = options;
+    const get = typeof address === "function" ? address : () => address;
+    return () => {
+        const seed = keccak256(new TextEncoder().encode(get().toLowerCase()));
+        let s = (seed[0] << 24) | (seed[1] << 16) | (seed[2] << 8) | seed[3];
+        const rand = () => {
+            s |= 0;
+            s = (s + 0x6d2b79f5) | 0;
+            let t = Math.imul(s ^ (s >>> 15), 1 | s);
+            t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        };
+        const color = `hsl(${Math.floor(rand() * 360)}, 65%, 55%)`;
+        const half = Math.ceil(cells / 2);
+        const unit = size / cells;
+        let rects = "";
+        for (let y = 0; y < cells; y++) {
+            for (let x = 0; x < half; x++) {
+                if (rand() > 0.5) {
+                    const mirrorX = cells - 1 - x;
+                    const mk = (rx) => `<rect x="${(rx * unit).toFixed(2)}" y="${(y * unit).toFixed(2)}" width="${unit.toFixed(2)}" height="${unit.toFixed(2)}" fill="${color}"/>`;
+                    rects += mk(x);
+                    if (mirrorX !== x)
+                        rects += mk(mirrorX);
+                }
+            }
+        }
+        const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}">` +
+            `<rect width="${size}" height="${size}" fill="${background}"/>${rects}</svg>`;
+        return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+    };
+}

package/package.json

@@ -43,5 +43,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.15.0"
+  "version": "0.16.0"
 }