@naculus/connect-appkit-core 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,325 @@
+import { Namespace, UniversalWalletSession, TokenConfig, WalletError, WalletErrorCode, NameResolverConfig, NameResolver } from '@naculus/connect-core';
+
+/**
+ * The types the framework-neutral half of appkit is built on.
+ *
+ * They live here rather than in the React package because a Vue composable
+ * needs to name the same things, and importing them from a package called
+ * `-react` would be both odd and a lie about what the dependency is.
+ */
+
+type WalletChain = {
+    /**
+     * CAIP-2, and the chain's identity.
+     *
+     * This was `id: number` alongside a separate `namespace`, which could only
+     * ever describe an EIP-155 chain: a Solana reference is base58
+     * (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`) and an XRPL one is an
+     * unsigned network id. The registry structurally could not hold a non-EVM
+     * chain, so every non-EVM path fell out to "unknown".
+     *
+     * `namespace` is gone rather than kept alongside: two fields that must
+     * agree are two fields that eventually do not.
+     */
+    caip2: string;
+    name: string;
+    rpcUrl?: string;
+    explorerUrl?: string;
+    token?: string;
+};
+interface ChainInfo {
+    namespace: Namespace;
+    chainId: string;
+    name: string;
+    selected: boolean;
+}
+type ConnectionStatus = "disconnected" | "connecting" | "authenticating" | "connected" | "reconnecting";
+interface Web3State {
+    status: ConnectionStatus;
+    session: UniversalWalletSession | null;
+    accounts: string[];
+    chainId: string | null;
+    error: Error | null;
+}
+
+/**
+ * Which chains a session can actually switch to, and what the current one is.
+ *
+ * Framework-neutral, and deliberately built on `parseChainId` from
+ * `@naculus/connect-core` rather than on another `startsWith("eip155:")`.
+ */
+
+/**
+ * The EIP-155 chain number, or null when this is not an EVM chain.
+ *
+ * Callers that need a number — a viem client, an ERC-20 read — must handle
+ * the null rather than defaulting, because there is no number that means
+ * "Solana" and any stand-in would address a real EVM chain.
+ */
+declare function chainNumber(chain: WalletChain): number | null;
+/** The namespace a chain belongs to, read from its CAIP-2 id. */
+declare function chainNamespace(chain: WalletChain): string | null;
+/**
+ * The configured chain for a CAIP-2 id, or null.
+ *
+ * A string comparison now that `WalletChain` is keyed by CAIP-2. It used to
+ * pull an integer out of the id and compare that, which no non-EVM chain
+ * could ever match.
+ */
+declare function resolveChain(chains: WalletChain[], chainId: string | null | undefined): WalletChain | null;
+/**
+ * The chains worth offering for the session's namespace.
+ *
+ * This used to return every configured chain regardless of what was
+ * connected, so a Solana wallet was offered Ethereum and Polygon in the
+ * switcher. Clicking one asked a wallet that has no concept of EIP-155 to
+ * switch to chain 137 — an action the interface presented as available and
+ * that could never work.
+ *
+ * With no connected chain, everything is offered: nothing has been ruled out
+ * yet, and hiding the list would leave a user unable to pick.
+ */
+declare function chainsForNamespace(chains: WalletChain[], chainId: string | null | undefined): WalletChain[];
+/**
+ * A description of the connected chain for display.
+ *
+ * Returns something for every namespace. It used to return null for anything
+ * that was not EIP-155, so a connected Solana wallet had no chain to show at
+ * all and the interface fell back to "Unknown Chain".
+ */
+declare function describeChain(chains: WalletChain[], chainId: string | null | undefined): ChainInfo | null;
+
+/**
+ * The viem `Chain` shape for a configured EVM chain.
+ *
+ * Three hooks each built this inline — `useBalance`, `useTokenBalance` and
+ * `useViemClient` — with identical bodies and the same `?? "ETH"` in each.
+ * Three copies of a fallback is three places for it to be wrong.
+ *
+ * Returns a plain object rather than importing viem, so this package stays
+ * free of a dependency only the React bindings need. The shape satisfies
+ * viem's `Chain` structurally.
+ */
+
+interface ViemChainShape {
+    id: number;
+    name: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrls: {
+        default: {
+            http: string[];
+        };
+        public: {
+            http: string[];
+        };
+    };
+}
+/**
+ * Build the chain descriptor a viem client needs, or null when this chain is
+ * not one viem can talk to.
+ *
+ * Null for a non-EVM chain rather than a stand-in number: viem speaks to EVM
+ * nodes, and any number chosen to fill the gap addresses a real chain that is
+ * not the one connected.
+ *
+ * The native symbol comes from the chain's own `token`, then from the shared
+ * chain registry. For an unlisted chain it stays empty rather than claiming
+ * the asset is ETH. viem requires a string here; the user-facing symbol comes
+ * from `useBalance().symbol`, which stays null when it is unknown.
+ */
+declare function toViemChain(chain: WalletChain, chainNumber: number | null): ViemChainShape | null;
+
+/**
+ * Which EVM chain does an account-abstraction operation belong to?
+ *
+ * The smart-account hooks each resolved this as
+ * `options.chainId ?? connectedChainId ?? "eip155:1"`, and each then guarded
+ * with `if (connectedChainId && connectedChainId !== target)`. The guard is
+ * skipped precisely when the mainnet default is used, so the one branch that
+ * assumes a chain is the one branch that never checks it.
+ *
+ * That branch is reachable: a caller passing its own `signer` needs no
+ * session, so `connectedChainId` is legitimately absent. It would then build
+ * and sign a UserOperation for chain 1 — with chain 1's EntryPoint — while its
+ * configured RPC and bundler point somewhere else. The chain ID is part of the
+ * UserOperation hash, so the user approves a commitment to a chain they were
+ * never shown.
+ *
+ * Resolving to undefined instead lets each caller refuse in whatever way suits
+ * it. Framework-agnostic on purpose: it must not import React.
+ */
+declare function isEvmChainId(value: string | null | undefined): boolean;
+/**
+ * The chain to operate on, or undefined when it cannot be known.
+ *
+ * An explicitly requested chain wins over the connected one; a malformed value
+ * from either source resolves to undefined rather than being replaced by a
+ * guess, because the caller asked for something specific and got it wrong.
+ */
+declare function resolveEvmChainId(requested: string | null | undefined, connected: string | null | undefined): string | undefined;
+
+/**
+ * Does this token belong to the chain the wallet is pointed at?
+ *
+ * `TokenConfig.chainId` existed but was only ever read as a display label and
+ * a cache key. Nothing compared it to the connected chain, so a hook handed a
+ * mainnet token config while the wallet sat on Polygon would read — or
+ * approve — whatever contract happens to occupy that address on Polygon.
+ * Usually that address holds nothing and the call reverts, which is merely
+ * confusing. When it holds a different token, `allowance()` returns a
+ * plausible number for the wrong asset, and `approve()` grants a spender
+ * rights over something the user never looked at.
+ *
+ * Framework-agnostic on purpose: it must not import React.
+ */
+
+/**
+ * A mismatch, or undefined when the token is on the active chain — or when
+ * there is not enough information to tell.
+ *
+ * Silence on "cannot tell" is deliberate. A token config without a chainId, or
+ * a session with no resolved chain, is a gap in what the caller supplied; a
+ * guess in either direction would be worse than letting the call proceed and
+ * fail on its own terms.
+ */
+declare function tokenChainMismatch(token: Pick<TokenConfig, "address" | "chainId">, activeChainId: number | undefined): WalletError | undefined;
+
+/**
+ * Decimals cache keyed by the token it belongs to.
+ *
+ * The ERC-20 hooks cached decimals in a bare `useRef` seeded from the token
+ * prop. `useRef` only takes its initial value on mount, and nothing reset it,
+ * so a component that lets the user switch tokens kept the first token's
+ * precision: picking USDC (6) and then DAI (18) converted "100" with 6
+ * decimals and transferred 0.0000000001 DAI. The transaction succeeded, so
+ * nothing surfaced the mistake.
+ *
+ * Keying the cache by the token makes a stale hit impossible without needing
+ * an effect to fire first.
+ */
+interface TokenIdentity {
+    chainId?: number;
+    address: string;
+}
+interface DecimalsCache {
+    key: string;
+    value: number | undefined;
+}
+declare function tokenKey(token: TokenIdentity): string;
+declare function createDecimalsCache(token: TokenIdentity, known?: number): DecimalsCache;
+/**
+ * Cached decimals for `token`, or undefined when the cache holds another
+ * token's value. Resets the cache as a side effect so the next write lands
+ * against the right key.
+ */
+declare function readDecimals(cache: DecimalsCache, token: TokenIdentity, known?: number): number | undefined;
+declare function writeDecimals(cache: DecimalsCache, token: TokenIdentity, value: number): void;
+
+/**
+ * Normalize an EIP-1193 provider error into a WalletError.
+ *
+ * Hooks were collapsing every non-WalletError into one code — `useSwitchChain`
+ * labelled a user pressing Cancel as `chain_unsupported`, so the UI told them
+ * the chain was unavailable when they had simply declined. The codes below are
+ * the ones wallets actually send, and they mean different things to a caller:
+ * one is retryable by asking again, the other is not retryable at all until
+ * the chain is added.
+ *
+ * Framework-agnostic on purpose: it must not import React.
+ */
+
+/**
+ * Map a chain-switch failure onto the code that describes it.
+ *
+ * `fallback` is used when the wallet gave nothing to go on, so the caller
+ * still decides what an unexplained failure means in its own context.
+ */
+declare function toChainSwitchError(error: unknown, fallback?: WalletErrorCode): WalletError;
+
+/**
+ * Decode an EVM revert payload into something a user can act on.
+ *
+ * This text is what a wallet shows when a simulation says a transaction would
+ * fail, so it is worth getting right and worth sharing: the logic is pure and
+ * every binding needs the same answer.
+ *
+ * Two things are handled that the inlined version did not. The ABI length
+ * word is attacker-controlled, so a payload can declare a longer string than
+ * it carries; decoding that produced a run of NUL bytes rather than an honest
+ * "could not decode". And a Panic was reported as "Built-in failure" with the
+ * code discarded, which is the one piece of information that distinguishes an
+ * overflow from a division by zero.
+ */
+/**
+ * @param data Raw revert data from the node, with or without the 0x prefix.
+ * @returns The decoded reason, or undefined when the payload is not a shape
+ *   this understands — callers should fall back to the RPC error text rather
+ *   than presenting a guess.
+ */
+declare function decodeRevertReason(data: unknown): string | undefined;
+/** Decoded reason if available, otherwise the node's own message. */
+declare function resolveRevertReason(data: unknown, fallbackMessage: string): string;
+
+/**
+ * Shared NameResolver instance for the name-resolution hooks.
+ *
+ * useResolveName and useLookupAddress each carried an identical getResolver
+ * with its own module-level singleton, so the two directions of the same
+ * lookup ran against separate resolvers and separate caches. One definition,
+ * one instance.
+ */
+
+/**
+ * @param config When supplied, returns a dedicated resolver rather than the
+ *   shared one — a caller asking for specific settings must not be handed an
+ *   instance configured by someone else.
+ */
+declare function getResolver(config?: NameResolverConfig): NameResolver;
+/** Test seam: drop the shared instance. */
+declare function __resetResolverForTests(): void;
+
+declare function withTimeout<T>(promise: Promise<T>, ms: number, label?: string): Promise<T>;
+interface RetryOptions {
+    maxRetries: number;
+    baseDelay: number;
+    label?: string;
+}
+declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+/** Convert EIP-1193 chainChanged values into the CAIP-2 form used by sessions. */
+declare function normalizeEip155ChainId(value: unknown): string | undefined;
+declare function toEip155Accounts(accounts: unknown[], chainId: string): string[];
+/**
+ * Numeric EIP-155 chain id, or undefined for any other namespace.
+ *
+ * The previous implementation took the last CAIP segment and ran parseInt over
+ * it, which stops at the first non-digit: `solana:5eykt4Us…` became 5 — an
+ * EVM chain id — so asking for Solana mainnet's token list returned Goerli's,
+ * and `xrpl:0` became chain 0. Anchor the whole reference instead.
+ */
+declare function eip155ChainIdToNumber(chainId: string): number | undefined;
+type Web3Action = {
+    type: "SET_STATUS";
+    payload: ConnectionStatus;
+} | {
+    type: "SET_SESSION";
+    payload: Web3State["session"];
+} | {
+    type: "SET_ACCOUNTS";
+    payload: string[];
+} | {
+    type: "SET_CHAIN";
+    payload: string | null;
+} | {
+    type: "SET_ERROR";
+    payload: Error | null;
+} | {
+    type: "RESET";
+};
+declare const initialWeb3State: Web3State;
+declare function web3Reducer(state: Web3State, action: Web3Action): Web3State;
+
+export { type ChainInfo, type ConnectionStatus, type DecimalsCache, type RetryOptions, type TokenIdentity, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, chainNamespace, chainNumber, chainsForNamespace, createDecimalsCache, decodeRevertReason, describeChain, eip155ChainIdToNumber, getResolver, initialWeb3State, isEvmChainId, normalizeEip155ChainId, readDecimals, resolveChain, resolveEvmChainId, resolveRevertReason, toChainSwitchError, toEip155Accounts, toViemChain, tokenChainMismatch, tokenKey, web3Reducer, withRetry, withTimeout, writeDecimals };

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+import { Namespace, UniversalWalletSession, TokenConfig, WalletError, WalletErrorCode, NameResolverConfig, NameResolver } from '@naculus/connect-core';
+
+/**
+ * The types the framework-neutral half of appkit is built on.
+ *
+ * They live here rather than in the React package because a Vue composable
+ * needs to name the same things, and importing them from a package called
+ * `-react` would be both odd and a lie about what the dependency is.
+ */
+
+type WalletChain = {
+    /**
+     * CAIP-2, and the chain's identity.
+     *
+     * This was `id: number` alongside a separate `namespace`, which could only
+     * ever describe an EIP-155 chain: a Solana reference is base58
+     * (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`) and an XRPL one is an
+     * unsigned network id. The registry structurally could not hold a non-EVM
+     * chain, so every non-EVM path fell out to "unknown".
+     *
+     * `namespace` is gone rather than kept alongside: two fields that must
+     * agree are two fields that eventually do not.
+     */
+    caip2: string;
+    name: string;
+    rpcUrl?: string;
+    explorerUrl?: string;
+    token?: string;
+};
+interface ChainInfo {
+    namespace: Namespace;
+    chainId: string;
+    name: string;
+    selected: boolean;
+}
+type ConnectionStatus = "disconnected" | "connecting" | "authenticating" | "connected" | "reconnecting";
+interface Web3State {
+    status: ConnectionStatus;
+    session: UniversalWalletSession | null;
+    accounts: string[];
+    chainId: string | null;
+    error: Error | null;
+}
+
+/**
+ * Which chains a session can actually switch to, and what the current one is.
+ *
+ * Framework-neutral, and deliberately built on `parseChainId` from
+ * `@naculus/connect-core` rather than on another `startsWith("eip155:")`.
+ */
+
+/**
+ * The EIP-155 chain number, or null when this is not an EVM chain.
+ *
+ * Callers that need a number — a viem client, an ERC-20 read — must handle
+ * the null rather than defaulting, because there is no number that means
+ * "Solana" and any stand-in would address a real EVM chain.
+ */
+declare function chainNumber(chain: WalletChain): number | null;
+/** The namespace a chain belongs to, read from its CAIP-2 id. */
+declare function chainNamespace(chain: WalletChain): string | null;
+/**
+ * The configured chain for a CAIP-2 id, or null.
+ *
+ * A string comparison now that `WalletChain` is keyed by CAIP-2. It used to
+ * pull an integer out of the id and compare that, which no non-EVM chain
+ * could ever match.
+ */
+declare function resolveChain(chains: WalletChain[], chainId: string | null | undefined): WalletChain | null;
+/**
+ * The chains worth offering for the session's namespace.
+ *
+ * This used to return every configured chain regardless of what was
+ * connected, so a Solana wallet was offered Ethereum and Polygon in the
+ * switcher. Clicking one asked a wallet that has no concept of EIP-155 to
+ * switch to chain 137 — an action the interface presented as available and
+ * that could never work.
+ *
+ * With no connected chain, everything is offered: nothing has been ruled out
+ * yet, and hiding the list would leave a user unable to pick.
+ */
+declare function chainsForNamespace(chains: WalletChain[], chainId: string | null | undefined): WalletChain[];
+/**
+ * A description of the connected chain for display.
+ *
+ * Returns something for every namespace. It used to return null for anything
+ * that was not EIP-155, so a connected Solana wallet had no chain to show at
+ * all and the interface fell back to "Unknown Chain".
+ */
+declare function describeChain(chains: WalletChain[], chainId: string | null | undefined): ChainInfo | null;
+
+/**
+ * The viem `Chain` shape for a configured EVM chain.
+ *
+ * Three hooks each built this inline — `useBalance`, `useTokenBalance` and
+ * `useViemClient` — with identical bodies and the same `?? "ETH"` in each.
+ * Three copies of a fallback is three places for it to be wrong.
+ *
+ * Returns a plain object rather than importing viem, so this package stays
+ * free of a dependency only the React bindings need. The shape satisfies
+ * viem's `Chain` structurally.
+ */
+
+interface ViemChainShape {
+    id: number;
+    name: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrls: {
+        default: {
+            http: string[];
+        };
+        public: {
+            http: string[];
+        };
+    };
+}
+/**
+ * Build the chain descriptor a viem client needs, or null when this chain is
+ * not one viem can talk to.
+ *
+ * Null for a non-EVM chain rather than a stand-in number: viem speaks to EVM
+ * nodes, and any number chosen to fill the gap addresses a real chain that is
+ * not the one connected.
+ *
+ * The native symbol comes from the chain's own `token`, then from the shared
+ * chain registry. For an unlisted chain it stays empty rather than claiming
+ * the asset is ETH. viem requires a string here; the user-facing symbol comes
+ * from `useBalance().symbol`, which stays null when it is unknown.
+ */
+declare function toViemChain(chain: WalletChain, chainNumber: number | null): ViemChainShape | null;
+
+/**
+ * Which EVM chain does an account-abstraction operation belong to?
+ *
+ * The smart-account hooks each resolved this as
+ * `options.chainId ?? connectedChainId ?? "eip155:1"`, and each then guarded
+ * with `if (connectedChainId && connectedChainId !== target)`. The guard is
+ * skipped precisely when the mainnet default is used, so the one branch that
+ * assumes a chain is the one branch that never checks it.
+ *
+ * That branch is reachable: a caller passing its own `signer` needs no
+ * session, so `connectedChainId` is legitimately absent. It would then build
+ * and sign a UserOperation for chain 1 — with chain 1's EntryPoint — while its
+ * configured RPC and bundler point somewhere else. The chain ID is part of the
+ * UserOperation hash, so the user approves a commitment to a chain they were
+ * never shown.
+ *
+ * Resolving to undefined instead lets each caller refuse in whatever way suits
+ * it. Framework-agnostic on purpose: it must not import React.
+ */
+declare function isEvmChainId(value: string | null | undefined): boolean;
+/**
+ * The chain to operate on, or undefined when it cannot be known.
+ *
+ * An explicitly requested chain wins over the connected one; a malformed value
+ * from either source resolves to undefined rather than being replaced by a
+ * guess, because the caller asked for something specific and got it wrong.
+ */
+declare function resolveEvmChainId(requested: string | null | undefined, connected: string | null | undefined): string | undefined;
+
+/**
+ * Does this token belong to the chain the wallet is pointed at?
+ *
+ * `TokenConfig.chainId` existed but was only ever read as a display label and
+ * a cache key. Nothing compared it to the connected chain, so a hook handed a
+ * mainnet token config while the wallet sat on Polygon would read — or
+ * approve — whatever contract happens to occupy that address on Polygon.
+ * Usually that address holds nothing and the call reverts, which is merely
+ * confusing. When it holds a different token, `allowance()` returns a
+ * plausible number for the wrong asset, and `approve()` grants a spender
+ * rights over something the user never looked at.
+ *
+ * Framework-agnostic on purpose: it must not import React.
+ */
+
+/**
+ * A mismatch, or undefined when the token is on the active chain — or when
+ * there is not enough information to tell.
+ *
+ * Silence on "cannot tell" is deliberate. A token config without a chainId, or
+ * a session with no resolved chain, is a gap in what the caller supplied; a
+ * guess in either direction would be worse than letting the call proceed and
+ * fail on its own terms.
+ */
+declare function tokenChainMismatch(token: Pick<TokenConfig, "address" | "chainId">, activeChainId: number | undefined): WalletError | undefined;
+
+/**
+ * Decimals cache keyed by the token it belongs to.
+ *
+ * The ERC-20 hooks cached decimals in a bare `useRef` seeded from the token
+ * prop. `useRef` only takes its initial value on mount, and nothing reset it,
+ * so a component that lets the user switch tokens kept the first token's
+ * precision: picking USDC (6) and then DAI (18) converted "100" with 6
+ * decimals and transferred 0.0000000001 DAI. The transaction succeeded, so
+ * nothing surfaced the mistake.
+ *
+ * Keying the cache by the token makes a stale hit impossible without needing
+ * an effect to fire first.
+ */
+interface TokenIdentity {
+    chainId?: number;
+    address: string;
+}
+interface DecimalsCache {
+    key: string;
+    value: number | undefined;
+}
+declare function tokenKey(token: TokenIdentity): string;
+declare function createDecimalsCache(token: TokenIdentity, known?: number): DecimalsCache;
+/**
+ * Cached decimals for `token`, or undefined when the cache holds another
+ * token's value. Resets the cache as a side effect so the next write lands
+ * against the right key.
+ */
+declare function readDecimals(cache: DecimalsCache, token: TokenIdentity, known?: number): number | undefined;
+declare function writeDecimals(cache: DecimalsCache, token: TokenIdentity, value: number): void;
+
+/**
+ * Normalize an EIP-1193 provider error into a WalletError.
+ *
+ * Hooks were collapsing every non-WalletError into one code — `useSwitchChain`
+ * labelled a user pressing Cancel as `chain_unsupported`, so the UI told them
+ * the chain was unavailable when they had simply declined. The codes below are
+ * the ones wallets actually send, and they mean different things to a caller:
+ * one is retryable by asking again, the other is not retryable at all until
+ * the chain is added.
+ *
+ * Framework-agnostic on purpose: it must not import React.
+ */
+
+/**
+ * Map a chain-switch failure onto the code that describes it.
+ *
+ * `fallback` is used when the wallet gave nothing to go on, so the caller
+ * still decides what an unexplained failure means in its own context.
+ */
+declare function toChainSwitchError(error: unknown, fallback?: WalletErrorCode): WalletError;
+
+/**
+ * Decode an EVM revert payload into something a user can act on.
+ *
+ * This text is what a wallet shows when a simulation says a transaction would
+ * fail, so it is worth getting right and worth sharing: the logic is pure and
+ * every binding needs the same answer.
+ *
+ * Two things are handled that the inlined version did not. The ABI length
+ * word is attacker-controlled, so a payload can declare a longer string than
+ * it carries; decoding that produced a run of NUL bytes rather than an honest
+ * "could not decode". And a Panic was reported as "Built-in failure" with the
+ * code discarded, which is the one piece of information that distinguishes an
+ * overflow from a division by zero.
+ */
+/**
+ * @param data Raw revert data from the node, with or without the 0x prefix.
+ * @returns The decoded reason, or undefined when the payload is not a shape
+ *   this understands — callers should fall back to the RPC error text rather
+ *   than presenting a guess.
+ */
+declare function decodeRevertReason(data: unknown): string | undefined;
+/** Decoded reason if available, otherwise the node's own message. */
+declare function resolveRevertReason(data: unknown, fallbackMessage: string): string;
+
+/**
+ * Shared NameResolver instance for the name-resolution hooks.
+ *
+ * useResolveName and useLookupAddress each carried an identical getResolver
+ * with its own module-level singleton, so the two directions of the same
+ * lookup ran against separate resolvers and separate caches. One definition,
+ * one instance.
+ */
+
+/**
+ * @param config When supplied, returns a dedicated resolver rather than the
+ *   shared one — a caller asking for specific settings must not be handed an
+ *   instance configured by someone else.
+ */
+declare function getResolver(config?: NameResolverConfig): NameResolver;
+/** Test seam: drop the shared instance. */
+declare function __resetResolverForTests(): void;
+
+declare function withTimeout<T>(promise: Promise<T>, ms: number, label?: string): Promise<T>;
+interface RetryOptions {
+    maxRetries: number;
+    baseDelay: number;
+    label?: string;
+}
+declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+/** Convert EIP-1193 chainChanged values into the CAIP-2 form used by sessions. */
+declare function normalizeEip155ChainId(value: unknown): string | undefined;
+declare function toEip155Accounts(accounts: unknown[], chainId: string): string[];
+/**
+ * Numeric EIP-155 chain id, or undefined for any other namespace.
+ *
+ * The previous implementation took the last CAIP segment and ran parseInt over
+ * it, which stops at the first non-digit: `solana:5eykt4Us…` became 5 — an
+ * EVM chain id — so asking for Solana mainnet's token list returned Goerli's,
+ * and `xrpl:0` became chain 0. Anchor the whole reference instead.
+ */
+declare function eip155ChainIdToNumber(chainId: string): number | undefined;
+type Web3Action = {
+    type: "SET_STATUS";
+    payload: ConnectionStatus;
+} | {
+    type: "SET_SESSION";
+    payload: Web3State["session"];
+} | {
+    type: "SET_ACCOUNTS";
+    payload: string[];
+} | {
+    type: "SET_CHAIN";
+    payload: string | null;
+} | {
+    type: "SET_ERROR";
+    payload: Error | null;
+} | {
+    type: "RESET";
+};
+declare const initialWeb3State: Web3State;
+declare function web3Reducer(state: Web3State, action: Web3Action): Web3State;
+
+export { type ChainInfo, type ConnectionStatus, type DecimalsCache, type RetryOptions, type TokenIdentity, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, chainNamespace, chainNumber, chainsForNamespace, createDecimalsCache, decodeRevertReason, describeChain, eip155ChainIdToNumber, getResolver, initialWeb3State, isEvmChainId, normalizeEip155ChainId, readDecimals, resolveChain, resolveEvmChainId, resolveRevertReason, toChainSwitchError, toEip155Accounts, toViemChain, tokenChainMismatch, tokenKey, web3Reducer, withRetry, withTimeout, writeDecimals };