solid-drift 0.14.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.
@@ -1164,6 +1195,36 @@ const machine = createSlotMachine({
 
 Options: `symbols` (required, at least 2), `reels` (default `3`), `duration` (ms for the first reel, default `1400`), `stagger` (extra ms per subsequent reel, default `500`), `minSpins` (full rotations before stopping, default `3`), `easing` (default `"easeOutQuart"`), `onTick(reel, symbol)`, `onDone(result)`. Returns `{ values, result, status, spin, stop, reset }`: `values()` is the visible symbol per reel, `result()` the final symbols of the last spin, `status()` is `"idle"`, `"spinning"`, or `"done"`. `stop()` halts at the current symbols; `reset()` returns to idle. SSR-safe and reduced-motion safe: `spin()` jumps straight to the result.
 
+### `createRedPacket(options?)`
+
+Crypto red packet ceremony: tap to open, coins burst out with physics, the amount counts up. The primitive owns the ceremony state machine (`"sealed"`, `"opening"`, `"bursting"`, `"revealed"`) and the coin particle physics; you render the envelope and the coins. Each coin carries position, rotation, size, opacity, and its share of the total, split randomly like a real red packet grab.
+
+```tsx
+import { createRedPacket } from "solid-drift"
+
+const packet = createRedPacket({ amount: 88, coins: 14 })
+
+<button onClick={() => packet.open()}>
+  {packet.status() === "sealed"
+    ? "🧧 Tap to open"
+    : `$${packet.revealed().toFixed(2)}`}
+</button>
+<For each={packet.coins()}>
+  {(coin) => (
+    <div
+      class="coin"
+      style={{
+        transform: `translate(${coin.x}px, ${coin.y}px) rotate(${coin.rotation}deg)`,
+        opacity: coin.opacity,
+        width: `${coin.size}px`,
+      }}
+    />
+  )}
+</For>
+```
+
+Options: `coins` (default `12`), `amount` (total, default `88`), `spread` (burst size in px, default `160`), `gravity` (px/s^2, default `900`), `openDuration` (ms, default `500`), `burstDuration` (ms, default `1600`), `revealDuration` (ms, default `800`), `onOpen`, `onReveal(amount)`. Returns `{ status, coins, revealed, open, reset }`. SSR-safe and reduced-motion safe: `open()` jumps straight to revealed with no burst.
+
 ### Easings
 
 Named easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeOutExpo`, `easeOutBack`, plus the cartoon set: `easeInBack` (anticipation dip before movement), `easeInOutBack` (wind-up, overshoot, settle), `easeOutElastic` (decaying rubber-band oscillation), `easeOutBounce` (shrinking cartoon bounces). Also `cubicBezier(x1, y1, x2, y2)` for CSS-style curves. Pass a name or a custom `(t) => number` function anywhere an easing is accepted.

package/dist/fun.d.ts

@@ -62,3 +62,90 @@ export interface SlotMachineControls<T = string> {
  * ```
  */
 export declare function createSlotMachine<T = string>(options: SlotMachineOptions<T>): SlotMachineControls<T>;
+export type RedPacketStatus = "sealed" | "opening" | "bursting" | "revealed";
+export interface RedPacketCoin {
+    id: number;
+    /** Pixels right from the packet center. */
+    x: number;
+    /** Pixels down from the packet center. */
+    y: number;
+    vx: number;
+    vy: number;
+    /** Degrees. */
+    rotation: number;
+    /** Degrees per second. */
+    vr: number;
+    /** Diameter in pixels. */
+    size: number;
+    /** 0..1, fades at the end of life. */
+    opacity: number;
+    /** This coin's share of the total amount. */
+    amount: number;
+}
+export interface RedPacketOptions {
+    /** Coins in the burst. Default 12. */
+    coins?: number;
+    /** Total amount, split randomly across coins like a real red packet. Default 88. */
+    amount?: number;
+    /** Burst size in pixels, scales launch speed. Default 160. */
+    spread?: number;
+    /** Gravity in px/s^2. Default 900. */
+    gravity?: number;
+    /** Envelope opening ceremony in ms. Default 500. */
+    openDuration?: number;
+    /** Coin burst in ms before the reveal. Default 1600. */
+    burstDuration?: number;
+    /** Amount count-up in ms once revealed. Default 800. */
+    revealDuration?: number;
+    /** Called when the packet is tapped open. */
+    onOpen?: () => void;
+    /** Called with the total amount when the reveal lands. */
+    onReveal?: (amount: number) => void;
+}
+export interface RedPacketControls {
+    status: Accessor<RedPacketStatus>;
+    /** Live coin particles, centered on the packet. Render them absolutely. */
+    coins: Accessor<RedPacketCoin[]>;
+    /** Amount counted up so far. Reaches the total when revealed. */
+    revealed: Accessor<number>;
+    /** Tap the packet: sealed -> opening -> bursting -> revealed. */
+    open: () => void;
+    /** Back to sealed. */
+    reset: () => void;
+}
+/**
+ * Crypto red packet ceremony: tap to open, coins burst out with physics,
+ * the amount counts up. The hongbao moment, as a signal-native primitive.
+ *
+ * The primitive owns the ceremony state machine and the coin particle
+ * physics; you render the envelope and the coins however fits your design.
+ * Each coin carries position, rotation, size, opacity, and its share of
+ * the total amount, split randomly like a real red packet grab.
+ *
+ * SSR-safe: `open()` jumps straight to revealed on the server. Under
+ * reduced motion the packet opens instantly with no burst: the amount
+ * just appears.
+ *
+ * ```tsx
+ * import { createRedPacket } from "solid-drift"
+ *
+ * const packet = createRedPacket({ amount: 88, coins: 14 })
+ *
+ * <button onClick={() => packet.open()}>
+ *   {packet.status() === "sealed" ? "🧧 Tap to open" : `$${packet.revealed().toFixed(2)}`}
+ * </button>
+ * <For each={packet.coins()}>
+ *   {(coin) => (
+ *     <div
+ *       class="coin"
+ *       style={{
+ *         transform: `translate(${coin.x}px, ${coin.y}px) rotate(${coin.rotation}deg)`,
+ *         opacity: coin.opacity,
+ *         width: `${coin.size}px`,
+ *       }}
+ *     />
+ *   )}
+ * </For>
+ * ```
+ */
+export declare function createRedPacket(options?: RedPacketOptions): RedPacketControls;

package/dist/fun.js

@@ -1,6 +1,7 @@
 import { createSignal, onCleanup, } from "solid-js";
 import { now, schedule } from "./engine.js";
 import { resolveEasing } from "./easing.js";
+import { createTween } from "./tween.js";
 import { prefersReducedMotion } from "./reduced-motion.js";
 /**
  * Gacha slot machine: reels launch fast, decelerate with momentum, and
@@ -131,3 +132,145 @@ export function createSlotMachine(options) {
     onCleanup(() => cancel?.());
     return { values, result, status, spin, stop, reset };
 }
+/**
+ * Crypto red packet ceremony: tap to open, coins burst out with physics,
+ * the amount counts up. The hongbao moment, as a signal-native primitive.
+ *
+ * The primitive owns the ceremony state machine and the coin particle
+ * physics; you render the envelope and the coins however fits your design.
+ * Each coin carries position, rotation, size, opacity, and its share of
+ * the total amount, split randomly like a real red packet grab.
+ *
+ * SSR-safe: `open()` jumps straight to revealed on the server. Under
+ * reduced motion the packet opens instantly with no burst: the amount
+ * just appears.
+ *
+ * ```tsx
+ * import { createRedPacket } from "solid-drift"
+ *
+ * const packet = createRedPacket({ amount: 88, coins: 14 })
+ *
+ * <button onClick={() => packet.open()}>
+ *   {packet.status() === "sealed" ? "🧧 Tap to open" : `$${packet.revealed().toFixed(2)}`}
+ * </button>
+ * <For each={packet.coins()}>
+ *   {(coin) => (
+ *     <div
+ *       class="coin"
+ *       style={{
+ *         transform: `translate(${coin.x}px, ${coin.y}px) rotate(${coin.rotation}deg)`,
+ *         opacity: coin.opacity,
+ *         width: `${coin.size}px`,
+ *       }}
+ *     />
+ *   )}
+ * </For>
+ * ```
+ */
+export function createRedPacket(options = {}) {
+    const { coins: coinCount = 12, amount = 88, spread = 160, gravity = 900, openDuration = 500, burstDuration = 1600, revealDuration = 800, onOpen, onReveal, } = options;
+    const [status, setStatus] = createSignal("sealed");
+    const [coinList, setCoinList] = createSignal([]);
+    const [target, setTarget] = createSignal(0);
+    const tweened = createTween(target, {
+        duration: revealDuration,
+        easing: "easeOutExpo",
+    });
+    // On the server the tween effect never runs, so read the target directly.
+    const revealed = () => typeof window === "undefined" ? target() : tweened();
+    let cancel = null;
+    let burstAt = 0;
+    let lastT = 0;
+    let nextCoinId = 1;
+    const spawnCoins = () => {
+        const weights = Array.from({ length: coinCount }, () => 0.5 + Math.random());
+        const totalWeight = weights.reduce((a, b) => a + b, 0);
+        const speedScale = spread / 160;
+        return weights.map((w, i) => {
+            const angle = ((Math.random() * 120 - 60) * Math.PI) / 180;
+            const speed = (200 + Math.random() * 220) * speedScale;
+            return {
+                id: nextCoinId++,
+                x: 0,
+                y: 0,
+                vx: Math.sin(angle) * speed,
+                vy: -Math.cos(angle) * speed,
+                rotation: Math.random() * 360,
+                vr: (Math.random() - 0.5) * 720,
+                size: 24 + Math.random() * 16,
+                opacity: 1,
+                amount: (amount * w) / totalWeight,
+            };
+        });
+    };
+    const stepCoins = (t) => {
+        // Every coin is born at burstAt, so they share one age and one fade.
+        const dt = Math.min(Math.max((t - lastT) / 1000, 0), 0.05);
+        lastT = t;
+        const age = t - burstAt;
+        if (age >= burstDuration) {
+            setCoinList([]);
+            return;
+        }
+        const fadeStart = burstDuration * 0.7;
+        const opacity = age < fadeStart
+            ? 1
+            : Math.max(1 - (age - fadeStart) / (burstDuration - fadeStart), 0);
+        setCoinList((prev) => prev.map((c) => {
+            const vy = c.vy + gravity * dt;
+            return {
+                ...c,
+                x: c.x + c.vx * dt,
+                y: c.y + vy * dt,
+                vy,
+                rotation: c.rotation + c.vr * dt,
+                opacity,
+            };
+        }));
+    };
+    const open = () => {
+        if (status() !== "sealed")
+            return;
+        onOpen?.();
+        if (typeof window === "undefined" || prefersReducedMotion()) {
+            // Accessibility / SSR: no ceremony, the amount just appears.
+            setTarget(amount);
+            setStatus("revealed");
+            onReveal?.(amount);
+            return;
+        }
+        setStatus("opening");
+        const t0 = now();
+        cancel?.();
+        cancel = schedule((t) => {
+            const s = status();
+            if (s === "opening" && t - t0 >= openDuration) {
+                burstAt = t;
+                lastT = t;
+                setCoinList(spawnCoins());
+                setStatus("bursting");
+            }
+            else if (s === "bursting") {
+                stepCoins(t);
+                if (t - burstAt >= burstDuration) {
+                    setCoinList([]);
+                    setTarget(amount);
+                    setStatus("revealed");
+                    onReveal?.(amount);
+                    cancel = null;
+                    return false;
+                }
+            }
+            return true;
+        });
+    };
+    const reset = () => {
+        cancel?.();
+        cancel = null;
+        setCoinList([]);
+        setTarget(0);
+        setStatus("sealed");
+    };
+    onCleanup(() => cancel?.());
+    return { status, coins: coinList, revealed, open, reset };
+}

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { createScrollProgress, type ScrollTarget } from "./scroll.js";
 export { createInView, type InViewOptions } from "./inview.js";
 export { usePrefersReducedMotion, prefersReducedMotion, } from "./reduced-motion.js";
 export { isLowPowerMode, useLowPowerMode, type LowPowerOptions, } from "./power.js";
-export { createSlotMachine, type SlotMachineControls, type SlotMachineOptions, type SlotMachineStatus, } from "./fun.js";
+export { createSlotMachine, type SlotMachineControls, type SlotMachineOptions, type SlotMachineStatus, createRedPacket, type RedPacketCoin, type RedPacketControls, type RedPacketOptions, type RedPacketStatus, } from "./fun.js";
 export { createStagger } from "./stagger.js";
 export { createHorizontalScroll, type HorizontalScrollOptions, type HorizontalScrollResult, } from "./horizontal.js";
 export { createScrub, type ScrubKeyframe, type ScrubOptions } from "./scrub.js";
@@ -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

@@ -12,7 +12,7 @@ export { createScrollProgress } from "./scroll.js";
 export { createInView } from "./inview.js";
 export { usePrefersReducedMotion, prefersReducedMotion, } from "./reduced-motion.js";
 export { isLowPowerMode, useLowPowerMode, } from "./power.js";
-export { createSlotMachine, } from "./fun.js";
+export { createSlotMachine, createRedPacket, } from "./fun.js";
 export { createStagger } from "./stagger.js";
 export { createHorizontalScroll, } from "./horizontal.js";
 export { createScrub } from "./scrub.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>;