solid-drift 0.15.0 → 0.17.0

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