@moon-x/core 0.10.1 → 0.12.0

package/dist/lib/index.d.mts

@@ -1,6 +1,6 @@
 export { C as CachedAssertion, g as generatePasskeyUserId } from '../passkey-cache-WnDFQ-v4.mjs';
 export { a as PasskeyFormFactor, P as PasskeyMetadata, b as PasskeyMetadataInput, f as formatPasskeyLabel, r as resolvePasskeyMetadata } from '../passkey-metadata-QqFF2SWQ.mjs';
-import { Chain, WalletChain } from '../types/index.mjs';
+import { ChainEntry, ChainConfigItem, Chain, EvmChainEntry, SolanaChainEntry, WalletChain } from '../types/index.mjs';
 import { SiweMessage } from 'siwe';
 import { Connection, PublicKey } from '@solana/web3.js';
 
@@ -45,13 +45,6 @@ declare const toB64url: (bytes: Uint8Array) => string;
  * Chain utilities for MoonKey
  */
 
-/**
- * Set a custom RPC URL for a chain
- * @param chain - The chain to configure
- * @param rpcUrl - The custom RPC URL
- * @returns A new chain object with the custom RPC URL
- */
-declare function setChainRpcUrl(chain: Chain, rpcUrl: string): Chain;
 /**
  * Get the RPC URL for a chain
  * @param chain - The chain to get the RPC URL for
@@ -122,35 +115,105 @@ declare function estimateEvmGasReserve(rpcUrl: string, chainId: number, opts?: {
     bufferBps?: number;
 }): Promise<number>;
 /**
- * Find a chain by its ID
- * @param chains - Array of chains to search
- * @param chainId - The chain ID to find
- * @returns The matching chain or undefined
+ * Find a viem `Chain` by its numeric chain ID.
+ *
+ * Accepts the unified `ChainConfigItem[]` shape: each element may be a bare
+ * viem `Chain`, an `{ chain, rpcUrl? }` EVM entry, or a Solana entry. The id
+ * lives on `chain.id` for entry-form items, so we normalize before comparing
+ * — a plain `item.id` check would miss every `{ chain }` entry (the documented
+ * override shape). Solana entries (string id) never match a numeric chainId.
  */
-declare function getChainById(chains: Chain[], chainId: number): Chain | undefined;
+declare function getChainById(chains: ChainConfigItem[], chainId: number): Chain | undefined;
 /**
- * Check if a chain is supported
- * @param chains - Array of supported chains
- * @param chainId - The chain ID to check
- * @returns True if the chain is supported
+ * Check if a numeric chain ID is configured. Handles the unified
+ * `ChainConfigItem[]` shape (see `getChainById`).
  */
-declare function isChainSupported(chains: Chain[], chainId: number): boolean;
+declare function isChainSupported(chains: ChainConfigItem[], chainId: number): boolean;
+/** Type guard: is this normalized entry an EVM entry (carries a viem Chain)? */
+declare function isEvmEntry(entry: ChainEntry): entry is EvmChainEntry;
 /**
- * Validate chain configuration
- * Throws an error if configuration is invalid
+ * Coerce a `ChainConfigItem` to its normalized form. A bare viem `Chain`
+ * (numeric `id`) becomes an `EvmChainEntry`; `{ chain, … }` is already one;
+ * anything else (string `id`) is a `SolanaChainEntry`.
  */
-declare function validateChainConfig(config: {
-    defaultChain?: Chain;
-    supportedChains?: Chain[];
-}): void;
+declare function normalizeChainItem(item: ChainConfigItem): ChainEntry;
+/** Canonical CAIP-2 id for a normalized entry. */
+declare function entryCaip2(entry: ChainEntry): string;
+interface ChainIndex {
+    /** Normalized entries in declaration order. */
+    entries: ChainEntry[];
+    /** Normalized alias key -> entry (first declaration wins on collision). */
+    byAlias: Map<string, ChainEntry>;
+}
+/**
+ * Normalize a chain reference to its alias-lookup key. Numbers → `eip155:<id>`.
+ *
+ * Throws a clear error on anything that isn't a string or number — most often
+ * an old-shape viem `Chain` object passed where a reference is now expected
+ * (e.g. `defaultChain: mainnet`). Without this guard the bare `.trim()` below
+ * would surface an opaque `TypeError`.
+ */
+declare function normalizeChainKey(key: string | number): string;
+/** Normalize every element and build the alias→entry index. */
+declare function buildChainIndex(chains?: ChainConfigItem[]): ChainIndex;
+/**
+ * Resolve a chain entry from the config by selector (alias | CAIP-2 | numeric
+ * chainId | Solana id). With no selector, falls back to `defaultSelector`, then
+ * to the first configured chain. Returns undefined when nothing matches.
+ */
+declare function resolveChainEntry(chains: ChainConfigItem[] | undefined, selector?: string | number, defaultSelector?: string | number): ChainEntry | undefined;
+/**
+ * Resolve a SOLANA entry, honoring (highest priority first): per-call
+ * `selector` → `defaultSelector` (`config.defaultChain`, when it points at a
+ * Solana cluster) → first configured Solana entry. This mirrors the EVM hooks
+ * and the documented precedence — rather than hardcoding `solana:mainnet`.
+ *
+ * Constrained to non-EVM entries so a Solana operation can never resolve an
+ * Ethereum chain: any selector (per-call or default) that matches an EVM alias
+ * (e.g. `8453` / `"eip155:8453"` / `"eth:base"`) is ignored rather than handing
+ * back an EVM HTTP RPC. An explicit `selector` that doesn't resolve to a Solana
+ * entry returns `undefined` (no fall-through) — fails closed, so the Solana
+ * hooks throw a clear "no RPC URL" error.
+ */
+declare function resolveSolanaChainEntry(chains: ChainConfigItem[] | undefined, selector?: string | number, defaultSelector?: string | number): SolanaChainEntry | undefined;
 /**
- * Get the default chain from config
- * If no defaultChain is set but supportedChains is set, returns the first supported chain
+ * Resolve the EVM entry to use, honoring (highest priority first):
+ * per-call `selector` → tx `requestedChainId` → `walletChainId` →
+ * `defaultSelector` → first EVM entry.
+ *
+ * Crucially, an EXPLICIT input (`selector` or `requestedChainId`) must resolve
+ * to a configured EVM chain — if one is provided but doesn't match, this
+ * returns `undefined` WITHOUT silently falling back to the wallet chain /
+ * default / first entry. A caller that named a network it didn't configure
+ * must hear about it (the hooks turn this into a clear error), rather than
+ * having the send/read quietly run on a different chain. Implicit sources
+ * (`walletChainId`, `defaultSelector`, first entry) are consulted only when no
+ * explicit input is given.
  */
-declare function getDefaultChain(config: {
-    defaultChain?: Chain;
-    supportedChains?: Chain[];
-}): Chain | undefined;
+declare function resolveEvmChainEntry(opts: {
+    chains?: ChainConfigItem[];
+    selector?: string | number;
+    requestedChainId?: number;
+    walletChainId?: number;
+    defaultSelector?: string | number;
+}): EvmChainEntry | undefined;
+/**
+ * Resolve the HTTP RPC URL for an entry. An explicit `override` (per-call
+ * `rpcUrl`) always wins; otherwise the entry's `rpcUrl`, then the viem chain's
+ * built-in default (EVM only).
+ */
+declare function resolveRpcUrl(entry: ChainEntry, override?: string): string;
+/** Resolve the WebSocket URL for an entry, with the same override precedence. */
+declare function resolveWsUrl(entry: ChainEntry, override?: string): string | undefined;
+/**
+ * Validate the unified chain config. Throws on an empty `chains` array,
+ * duplicate canonical ids, a Solana entry missing its `rpcUrl`, or a
+ * `defaultChain` that doesn't reference a configured chain.
+ */
+declare function validateChainConfig(config: {
+    chains?: ChainConfigItem[];
+    defaultChain?: string | number;
+}): void;
 
 interface EthereumSiweMessageProps {
     nonce: string;
@@ -205,34 +268,50 @@ interface EvmTxPrepWallet {
     chainId?: number;
 }
 interface ChainResolutionInput {
+    /** Unified chain config (`config.chains`). */
+    chains?: ChainConfigItem[];
+    /** Per-call chain selector (`params.chain`): alias | CAIP-2 | numeric id. */
+    chainSelector?: string | number;
     /** Pull from the input transaction's `chainId` if the caller was explicit. */
     requestedChainId?: number;
     /** Wallet's bound chain, if any. */
     walletChainId?: number;
-    supportedChains?: Chain[];
-    defaultChain?: Chain;
+    /** Provider-level default chain reference (`config.defaultChain`). */
+    defaultChain?: string | number;
+    /** Per-call inline `rpcUrl` override. */
+    rpcUrlOverride?: string;
     /**
-     * When true, reject if requestedChainId is not in supportedChains.
+     * When true, reject if an explicit requested chain isn't configured.
      * Sign-only paths leave this false (best-effort fallback to default).
      * Send paths set it true so a Base tx never silently broadcasts to mainnet.
      */
     strict?: boolean;
 }
 /**
- * Resolve which chain to use for the operation.
+ * Resolve which chain (and RPC URL) to use for the operation.
  *
- * Priority:
- *   1. `requestedChainId` from the transaction (caller is explicit).
- *   2. `walletChainId` from the wallet's bound chain.
- *   3. `defaultChain` from provider config.
+ * Priority: per-call `chainSelector` → tx `requestedChainId` →
+ * `walletChainId` → `defaultChain` → first configured EVM chain.
  *
- * Under `strict: true`, an explicit `requestedChainId` outside the
- * configured `supportedChains` throws — sending a Base tx through a
- * mainnet RPC would otherwise silently land on the wrong chain. Sign-
- * only flows (where there's no broadcast) leave strict off so the
- * fallback to defaultChain is allowed.
+ * Explicit selections are honored exactly — they never silently degrade to a
+ * different chain:
+ *   - An explicit `chainSelector` that isn't configured ALWAYS throws (the
+ *     caller named a network that doesn't exist), even if an `rpcUrlOverride`
+ *     is present — a one-off override is addressed by `requestedChainId`, not
+ *     by a chain alias.
+ *   - An explicit `requestedChainId` that isn't configured does NOT fall back
+ *     to the wallet / default chain. With an `rpcUrlOverride` it becomes a
+ *     one-off: the tx serializes against `requestedChainId` and broadcasts via
+ *     the override (so a Polygon tx never gets rewritten to mainnet's id).
+ *     Without an override it throws under `strict`, or falls through to
+ *     implicit resolution on the sign path (`strict: false`).
+ *
+ * An `rpcUrlOverride` overrides the transport for whichever chain is resolved.
  */
-declare function resolveEvmChain({ requestedChainId, walletChainId, supportedChains, defaultChain, strict, }: ChainResolutionInput): Chain;
+declare function resolveEvmChain({ chains, chainSelector, requestedChainId, walletChainId, defaultChain, rpcUrlOverride, strict, }: ChainResolutionInput): {
+    chain: Chain;
+    rpcUrl: string;
+};
 /**
  * Sign-path prep. Converts an input transaction (string or object) into
  * the serialized RLP string the iframe-side signer expects. Handles
@@ -241,11 +320,12 @@ declare function resolveEvmChain({ requestedChainId, walletChainId, supportedCha
  * No RPC calls — caller can sign now and broadcast later. Returns the
  * resolved chain too so the hook can stash it if needed.
  */
-declare function prepareEvmSignTransaction({ transaction, wallet, supportedChains, defaultChain, }: {
+declare function prepareEvmSignTransaction({ transaction, wallet, chains, defaultChain, chainSelector, }: {
     transaction: string | EvmTransactionInput;
     wallet: EvmTxPrepWallet;
-    supportedChains?: Chain[];
-    defaultChain?: Chain;
+    chains?: ChainConfigItem[];
+    defaultChain?: string | number;
+    chainSelector?: string | number;
 }): Promise<{
     serializedTransaction: string;
     chain: Chain | undefined;
@@ -275,11 +355,13 @@ declare function prepareEvmSignTransaction({ transaction, wallet, supportedChain
  * let the downstream serializer handle it. The caller gets a clearer
  * error from the chain than a silent stuck tx.
  */
-declare function prepareEvmSendTransaction({ transaction, wallet, supportedChains, defaultChain, }: {
+declare function prepareEvmSendTransaction({ transaction, wallet, chains, defaultChain, chainSelector, rpcUrlOverride, }: {
     transaction: EvmTransactionInput;
     wallet: EvmTxPrepWallet;
-    supportedChains?: Chain[];
-    defaultChain?: Chain;
+    chains?: ChainConfigItem[];
+    defaultChain?: string | number;
+    chainSelector?: string | number;
+    rpcUrlOverride?: string;
 }): Promise<{
     transaction: EvmTransactionInput;
     rpcUrl: string;
@@ -437,4 +519,4 @@ declare const arrayLikeToBytes: (value: unknown) => Uint8Array;
  */
 declare const bs58ToBytes: (value: unknown) => Promise<Uint8Array>;
 
-export { type BuildUrlConfig, DEFAULT_AUTH_URL, EthereumSiweMessage, type EthereumSiweMessageProps, type EvmTransactionInput, type EvmTxPrepWallet, type ManualSiweMessageProps, SiwsMessage, SolanaTransactionParser, type VerifyIdTokenResponse, arrayLikeToBytes, authState, broadcastEthereumRaw, broadcastSolanaSigned, bs58ToBytes, buildUrl, canonicalAlgorithmFor, createManualSiweMessage, estimateEvmGas, estimateEvmGasReserve, fromB64url, getChainById, getDefaultChain, getEvmGasPrice, getEvmMaxPriorityFeePerGas, getEvmNonce, getInstructionsForHTML, getRpcUrl, getSOLTransfersFromInstructions, getTransferInfoFromInstructions, isChainSupported, parseDerivationPath, prepareEvmSendTransaction, prepareEvmSignTransaction, resolveEvmChain, sanitizeUserData, serializeEthereumTransaction, setChainRpcUrl, toB64url, validateChainConfig, verifyIdToken };
+export { type BuildUrlConfig, type ChainIndex, DEFAULT_AUTH_URL, EthereumSiweMessage, type EthereumSiweMessageProps, type EvmTransactionInput, type EvmTxPrepWallet, type ManualSiweMessageProps, SiwsMessage, SolanaTransactionParser, type VerifyIdTokenResponse, arrayLikeToBytes, authState, broadcastEthereumRaw, broadcastSolanaSigned, bs58ToBytes, buildChainIndex, buildUrl, canonicalAlgorithmFor, createManualSiweMessage, entryCaip2, estimateEvmGas, estimateEvmGasReserve, fromB64url, getChainById, getEvmGasPrice, getEvmMaxPriorityFeePerGas, getEvmNonce, getInstructionsForHTML, getRpcUrl, getSOLTransfersFromInstructions, getTransferInfoFromInstructions, isChainSupported, isEvmEntry, normalizeChainItem, normalizeChainKey, parseDerivationPath, prepareEvmSendTransaction, prepareEvmSignTransaction, resolveChainEntry, resolveEvmChain, resolveEvmChainEntry, resolveRpcUrl, resolveSolanaChainEntry, resolveWsUrl, sanitizeUserData, serializeEthereumTransaction, toB64url, validateChainConfig, verifyIdToken };

package/dist/lib/index.d.ts

@@ -1,6 +1,6 @@
 export { C as CachedAssertion, g as generatePasskeyUserId } from '../passkey-cache-WnDFQ-v4.js';
 export { a as PasskeyFormFactor, P as PasskeyMetadata, b as PasskeyMetadataInput, f as formatPasskeyLabel, r as resolvePasskeyMetadata } from '../passkey-metadata-QqFF2SWQ.js';
-import { Chain, WalletChain } from '../types/index.js';
+import { ChainEntry, ChainConfigItem, Chain, EvmChainEntry, SolanaChainEntry, WalletChain } from '../types/index.js';
 import { SiweMessage } from 'siwe';
 import { Connection, PublicKey } from '@solana/web3.js';
 
@@ -45,13 +45,6 @@ declare const toB64url: (bytes: Uint8Array) => string;
  * Chain utilities for MoonKey
  */
 
-/**
- * Set a custom RPC URL for a chain
- * @param chain - The chain to configure
- * @param rpcUrl - The custom RPC URL
- * @returns A new chain object with the custom RPC URL
- */
-declare function setChainRpcUrl(chain: Chain, rpcUrl: string): Chain;
 /**
  * Get the RPC URL for a chain
  * @param chain - The chain to get the RPC URL for
@@ -122,35 +115,105 @@ declare function estimateEvmGasReserve(rpcUrl: string, chainId: number, opts?: {
     bufferBps?: number;
 }): Promise<number>;
 /**
- * Find a chain by its ID
- * @param chains - Array of chains to search
- * @param chainId - The chain ID to find
- * @returns The matching chain or undefined
+ * Find a viem `Chain` by its numeric chain ID.
+ *
+ * Accepts the unified `ChainConfigItem[]` shape: each element may be a bare
+ * viem `Chain`, an `{ chain, rpcUrl? }` EVM entry, or a Solana entry. The id
+ * lives on `chain.id` for entry-form items, so we normalize before comparing
+ * — a plain `item.id` check would miss every `{ chain }` entry (the documented
+ * override shape). Solana entries (string id) never match a numeric chainId.
  */
-declare function getChainById(chains: Chain[], chainId: number): Chain | undefined;
+declare function getChainById(chains: ChainConfigItem[], chainId: number): Chain | undefined;
 /**
- * Check if a chain is supported
- * @param chains - Array of supported chains
- * @param chainId - The chain ID to check
- * @returns True if the chain is supported
+ * Check if a numeric chain ID is configured. Handles the unified
+ * `ChainConfigItem[]` shape (see `getChainById`).
  */
-declare function isChainSupported(chains: Chain[], chainId: number): boolean;
+declare function isChainSupported(chains: ChainConfigItem[], chainId: number): boolean;
+/** Type guard: is this normalized entry an EVM entry (carries a viem Chain)? */
+declare function isEvmEntry(entry: ChainEntry): entry is EvmChainEntry;
 /**
- * Validate chain configuration
- * Throws an error if configuration is invalid
+ * Coerce a `ChainConfigItem` to its normalized form. A bare viem `Chain`
+ * (numeric `id`) becomes an `EvmChainEntry`; `{ chain, … }` is already one;
+ * anything else (string `id`) is a `SolanaChainEntry`.
  */
-declare function validateChainConfig(config: {
-    defaultChain?: Chain;
-    supportedChains?: Chain[];
-}): void;
+declare function normalizeChainItem(item: ChainConfigItem): ChainEntry;
+/** Canonical CAIP-2 id for a normalized entry. */
+declare function entryCaip2(entry: ChainEntry): string;
+interface ChainIndex {
+    /** Normalized entries in declaration order. */
+    entries: ChainEntry[];
+    /** Normalized alias key -> entry (first declaration wins on collision). */
+    byAlias: Map<string, ChainEntry>;
+}
+/**
+ * Normalize a chain reference to its alias-lookup key. Numbers → `eip155:<id>`.
+ *
+ * Throws a clear error on anything that isn't a string or number — most often
+ * an old-shape viem `Chain` object passed where a reference is now expected
+ * (e.g. `defaultChain: mainnet`). Without this guard the bare `.trim()` below
+ * would surface an opaque `TypeError`.
+ */
+declare function normalizeChainKey(key: string | number): string;
+/** Normalize every element and build the alias→entry index. */
+declare function buildChainIndex(chains?: ChainConfigItem[]): ChainIndex;
+/**
+ * Resolve a chain entry from the config by selector (alias | CAIP-2 | numeric
+ * chainId | Solana id). With no selector, falls back to `defaultSelector`, then
+ * to the first configured chain. Returns undefined when nothing matches.
+ */
+declare function resolveChainEntry(chains: ChainConfigItem[] | undefined, selector?: string | number, defaultSelector?: string | number): ChainEntry | undefined;
+/**
+ * Resolve a SOLANA entry, honoring (highest priority first): per-call
+ * `selector` → `defaultSelector` (`config.defaultChain`, when it points at a
+ * Solana cluster) → first configured Solana entry. This mirrors the EVM hooks
+ * and the documented precedence — rather than hardcoding `solana:mainnet`.
+ *
+ * Constrained to non-EVM entries so a Solana operation can never resolve an
+ * Ethereum chain: any selector (per-call or default) that matches an EVM alias
+ * (e.g. `8453` / `"eip155:8453"` / `"eth:base"`) is ignored rather than handing
+ * back an EVM HTTP RPC. An explicit `selector` that doesn't resolve to a Solana
+ * entry returns `undefined` (no fall-through) — fails closed, so the Solana
+ * hooks throw a clear "no RPC URL" error.
+ */
+declare function resolveSolanaChainEntry(chains: ChainConfigItem[] | undefined, selector?: string | number, defaultSelector?: string | number): SolanaChainEntry | undefined;
 /**
- * Get the default chain from config
- * If no defaultChain is set but supportedChains is set, returns the first supported chain
+ * Resolve the EVM entry to use, honoring (highest priority first):
+ * per-call `selector` → tx `requestedChainId` → `walletChainId` →
+ * `defaultSelector` → first EVM entry.
+ *
+ * Crucially, an EXPLICIT input (`selector` or `requestedChainId`) must resolve
+ * to a configured EVM chain — if one is provided but doesn't match, this
+ * returns `undefined` WITHOUT silently falling back to the wallet chain /
+ * default / first entry. A caller that named a network it didn't configure
+ * must hear about it (the hooks turn this into a clear error), rather than
+ * having the send/read quietly run on a different chain. Implicit sources
+ * (`walletChainId`, `defaultSelector`, first entry) are consulted only when no
+ * explicit input is given.
  */
-declare function getDefaultChain(config: {
-    defaultChain?: Chain;
-    supportedChains?: Chain[];
-}): Chain | undefined;
+declare function resolveEvmChainEntry(opts: {
+    chains?: ChainConfigItem[];
+    selector?: string | number;
+    requestedChainId?: number;
+    walletChainId?: number;
+    defaultSelector?: string | number;
+}): EvmChainEntry | undefined;
+/**
+ * Resolve the HTTP RPC URL for an entry. An explicit `override` (per-call
+ * `rpcUrl`) always wins; otherwise the entry's `rpcUrl`, then the viem chain's
+ * built-in default (EVM only).
+ */
+declare function resolveRpcUrl(entry: ChainEntry, override?: string): string;
+/** Resolve the WebSocket URL for an entry, with the same override precedence. */
+declare function resolveWsUrl(entry: ChainEntry, override?: string): string | undefined;
+/**
+ * Validate the unified chain config. Throws on an empty `chains` array,
+ * duplicate canonical ids, a Solana entry missing its `rpcUrl`, or a
+ * `defaultChain` that doesn't reference a configured chain.
+ */
+declare function validateChainConfig(config: {
+    chains?: ChainConfigItem[];
+    defaultChain?: string | number;
+}): void;
 
 interface EthereumSiweMessageProps {
     nonce: string;
@@ -205,34 +268,50 @@ interface EvmTxPrepWallet {
     chainId?: number;
 }
 interface ChainResolutionInput {
+    /** Unified chain config (`config.chains`). */
+    chains?: ChainConfigItem[];
+    /** Per-call chain selector (`params.chain`): alias | CAIP-2 | numeric id. */
+    chainSelector?: string | number;
     /** Pull from the input transaction's `chainId` if the caller was explicit. */
     requestedChainId?: number;
     /** Wallet's bound chain, if any. */
     walletChainId?: number;
-    supportedChains?: Chain[];
-    defaultChain?: Chain;
+    /** Provider-level default chain reference (`config.defaultChain`). */
+    defaultChain?: string | number;
+    /** Per-call inline `rpcUrl` override. */
+    rpcUrlOverride?: string;
     /**
-     * When true, reject if requestedChainId is not in supportedChains.
+     * When true, reject if an explicit requested chain isn't configured.
      * Sign-only paths leave this false (best-effort fallback to default).
      * Send paths set it true so a Base tx never silently broadcasts to mainnet.
      */
     strict?: boolean;
 }
 /**
- * Resolve which chain to use for the operation.
+ * Resolve which chain (and RPC URL) to use for the operation.
  *
- * Priority:
- *   1. `requestedChainId` from the transaction (caller is explicit).
- *   2. `walletChainId` from the wallet's bound chain.
- *   3. `defaultChain` from provider config.
+ * Priority: per-call `chainSelector` → tx `requestedChainId` →
+ * `walletChainId` → `defaultChain` → first configured EVM chain.
  *
- * Under `strict: true`, an explicit `requestedChainId` outside the
- * configured `supportedChains` throws — sending a Base tx through a
- * mainnet RPC would otherwise silently land on the wrong chain. Sign-
- * only flows (where there's no broadcast) leave strict off so the
- * fallback to defaultChain is allowed.
+ * Explicit selections are honored exactly — they never silently degrade to a
+ * different chain:
+ *   - An explicit `chainSelector` that isn't configured ALWAYS throws (the
+ *     caller named a network that doesn't exist), even if an `rpcUrlOverride`
+ *     is present — a one-off override is addressed by `requestedChainId`, not
+ *     by a chain alias.
+ *   - An explicit `requestedChainId` that isn't configured does NOT fall back
+ *     to the wallet / default chain. With an `rpcUrlOverride` it becomes a
+ *     one-off: the tx serializes against `requestedChainId` and broadcasts via
+ *     the override (so a Polygon tx never gets rewritten to mainnet's id).
+ *     Without an override it throws under `strict`, or falls through to
+ *     implicit resolution on the sign path (`strict: false`).
+ *
+ * An `rpcUrlOverride` overrides the transport for whichever chain is resolved.
  */
-declare function resolveEvmChain({ requestedChainId, walletChainId, supportedChains, defaultChain, strict, }: ChainResolutionInput): Chain;
+declare function resolveEvmChain({ chains, chainSelector, requestedChainId, walletChainId, defaultChain, rpcUrlOverride, strict, }: ChainResolutionInput): {
+    chain: Chain;
+    rpcUrl: string;
+};
 /**
  * Sign-path prep. Converts an input transaction (string or object) into
  * the serialized RLP string the iframe-side signer expects. Handles
@@ -241,11 +320,12 @@ declare function resolveEvmChain({ requestedChainId, walletChainId, supportedCha
  * No RPC calls — caller can sign now and broadcast later. Returns the
  * resolved chain too so the hook can stash it if needed.
  */
-declare function prepareEvmSignTransaction({ transaction, wallet, supportedChains, defaultChain, }: {
+declare function prepareEvmSignTransaction({ transaction, wallet, chains, defaultChain, chainSelector, }: {
     transaction: string | EvmTransactionInput;
     wallet: EvmTxPrepWallet;
-    supportedChains?: Chain[];
-    defaultChain?: Chain;
+    chains?: ChainConfigItem[];
+    defaultChain?: string | number;
+    chainSelector?: string | number;
 }): Promise<{
     serializedTransaction: string;
     chain: Chain | undefined;
@@ -275,11 +355,13 @@ declare function prepareEvmSignTransaction({ transaction, wallet, supportedChain
  * let the downstream serializer handle it. The caller gets a clearer
  * error from the chain than a silent stuck tx.
  */
-declare function prepareEvmSendTransaction({ transaction, wallet, supportedChains, defaultChain, }: {
+declare function prepareEvmSendTransaction({ transaction, wallet, chains, defaultChain, chainSelector, rpcUrlOverride, }: {
     transaction: EvmTransactionInput;
     wallet: EvmTxPrepWallet;
-    supportedChains?: Chain[];
-    defaultChain?: Chain;
+    chains?: ChainConfigItem[];
+    defaultChain?: string | number;
+    chainSelector?: string | number;
+    rpcUrlOverride?: string;
 }): Promise<{
     transaction: EvmTransactionInput;
     rpcUrl: string;
@@ -437,4 +519,4 @@ declare const arrayLikeToBytes: (value: unknown) => Uint8Array;
  */
 declare const bs58ToBytes: (value: unknown) => Promise<Uint8Array>;
 
-export { type BuildUrlConfig, DEFAULT_AUTH_URL, EthereumSiweMessage, type EthereumSiweMessageProps, type EvmTransactionInput, type EvmTxPrepWallet, type ManualSiweMessageProps, SiwsMessage, SolanaTransactionParser, type VerifyIdTokenResponse, arrayLikeToBytes, authState, broadcastEthereumRaw, broadcastSolanaSigned, bs58ToBytes, buildUrl, canonicalAlgorithmFor, createManualSiweMessage, estimateEvmGas, estimateEvmGasReserve, fromB64url, getChainById, getDefaultChain, getEvmGasPrice, getEvmMaxPriorityFeePerGas, getEvmNonce, getInstructionsForHTML, getRpcUrl, getSOLTransfersFromInstructions, getTransferInfoFromInstructions, isChainSupported, parseDerivationPath, prepareEvmSendTransaction, prepareEvmSignTransaction, resolveEvmChain, sanitizeUserData, serializeEthereumTransaction, setChainRpcUrl, toB64url, validateChainConfig, verifyIdToken };
+export { type BuildUrlConfig, type ChainIndex, DEFAULT_AUTH_URL, EthereumSiweMessage, type EthereumSiweMessageProps, type EvmTransactionInput, type EvmTxPrepWallet, type ManualSiweMessageProps, SiwsMessage, SolanaTransactionParser, type VerifyIdTokenResponse, arrayLikeToBytes, authState, broadcastEthereumRaw, broadcastSolanaSigned, bs58ToBytes, buildChainIndex, buildUrl, canonicalAlgorithmFor, createManualSiweMessage, entryCaip2, estimateEvmGas, estimateEvmGasReserve, fromB64url, getChainById, getEvmGasPrice, getEvmMaxPriorityFeePerGas, getEvmNonce, getInstructionsForHTML, getRpcUrl, getSOLTransfersFromInstructions, getTransferInfoFromInstructions, isChainSupported, isEvmEntry, normalizeChainItem, normalizeChainKey, parseDerivationPath, prepareEvmSendTransaction, prepareEvmSignTransaction, resolveChainEntry, resolveEvmChain, resolveEvmChainEntry, resolveRpcUrl, resolveSolanaChainEntry, resolveWsUrl, sanitizeUserData, serializeEthereumTransaction, toB64url, validateChainConfig, verifyIdToken };