@initia/interwovenkit-react 2.4.6 → 2.5.0

package/dist/index.d.ts

@@ -14,6 +14,7 @@ import { IndexedTx } from '@cosmjs/stargate';
 import { JSX } from 'react/jsx-runtime';
 import { OfflineAminoSigner } from '@cosmjs/amino';
 import { PropsWithChildren } from 'react';
+import { ProviderConnectInfo } from 'viem';
 import { SimulateResponse } from 'cosmjs-types/cosmos/tx/v1beta1/service';
 import { StdFee } from '@cosmjs/stargate';
 import { StdSignDoc } from '@cosmjs/amino';
@@ -49,8 +50,296 @@ declare interface Config {
     disableAnalytics?: boolean;
     enableAutoSign?: boolean | Record<string, string[]>;
     autoSignFeePolicy?: Record<string, AutoSignFeePolicy>;
+    cosmosWallets?: CosmosWallet[];
 }
 
+export declare interface CosmosWallet {
+    name: string;
+    image?: string;
+    getProvider: () => CosmosWalletProvider | undefined;
+    fallbackUrl?: string;
+}
+
+export declare interface CosmosWalletProvider {
+    getOfflineSigner(chainId: string): OfflineAminoSigner;
+    getOfflineSignerOnlyAmino(chainId: string): OfflineAminoSigner;
+}
+
+/**
+ * Creates a Cosmos wallet for the Bridge wallet selection list,
+ * backed by a mnemonic-derived `Secp256k1HdWallet` (standard Cosmos
+ * secp256k1 signing). Designed for automated testing and local
+ * development against chains like Noble and Neutron.
+ *
+ * Pass the returned wallet via the `cosmosWallets` config prop
+ * on `InterwovenKitProvider`. It will appear in the Bridge's
+ * "Connect wallet" list alongside Keplr and Leap.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   InterwovenKitProvider,
+ *   createTestCosmosWallet,
+ * } from "@initia/interwovenkit-react"
+ *
+ * const testCosmosWallet = createTestCosmosWallet({
+ *   mnemonic: process.env.TEST_COSMOS_MNEMONIC!,
+ * })
+ *
+ * function App() {
+ *   return (
+ *     <InterwovenKitProvider cosmosWallets={[testCosmosWallet]}>
+ *       {children}
+ *     </InterwovenKitProvider>
+ *   )
+ * }
+ * ```
+ */
+export declare function createTestCosmosWallet(config: CreateTestCosmosWalletConfig): CosmosWallet;
+
+export declare interface CreateTestCosmosWalletConfig {
+    /**
+     * BIP-39 mnemonic phrase used to derive Cosmos accounts.
+     */
+    mnemonic: string;
+    /**
+     * Display name shown in the wallet selection list.
+     * @default "Test Cosmos Wallet"
+     */
+    name?: string;
+    /**
+     * Wallet icon URL. Omit to show the default placeholder.
+     */
+    image?: string;
+    /**
+     * Override the bech32 prefix for specific chain IDs.
+     * By default, the prefix is derived from the chain ID
+     * (e.g. `noble-1` → `noble`). Use this for chains where
+     * the prefix differs from the chain ID stem.
+     *
+     * @example
+     * ```ts
+     * chains: {
+     *   "cosmoshub-4": { prefix: "cosmos" },
+     *   "osmosis-1": { prefix: "osmo" },
+     * }
+     * ```
+     */
+    chains?: Record<string, {
+        prefix: string;
+    }>;
+    /**
+     * Log signer creation to the console for debugging.
+     * @default false
+     */
+    debug?: boolean;
+}
+
+export declare type CreateTestWalletConfig = CreateTestWalletOptions & {
+    /**
+     * Wagmi connector id. Useful when running multiple test wallets.
+     * @default "testWallet"
+     */
+    id?: string;
+    /**
+     * Display name shown in wallet selection UI.
+     * @default "Test Wallet"
+     */
+    name?: string;
+    /**
+     * CORS-friendly RPC URLs keyed by chain ID.
+     * User-provided URLs override built-in defaults for matching chain IDs.
+     */
+    rpcUrls?: Record<number, string>;
+    /**
+     * Log every RPC call to the console for debugging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Override fields on every `eth_sendTransaction` call.
+     * Useful for testing failure scenarios:
+     * - `{ gas: 21000n }` — out of gas for contract calls (triggers revert)
+     * - `{ maxFeePerGas: 1n }` — below base fee (rejected by RPC or stuck in mempool)
+     */
+    sendTransactionOverrides?: {
+        gas?: bigint;
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+};
+
+/**
+ * Creates a wagmi-compatible wallet connector from a mnemonic or
+ * private key for automated testing and local development.
+ *
+ * Browser wallets require manual interaction (popups, confirmations)
+ * that cannot be driven programmatically. This connector creates an
+ * in-memory EIP-1193 wallet that handles chain switching, transaction
+ * signing, and gas estimation entirely in code. Standard contract
+ * interactions (e.g. ERC-20 approvals) work via the RPC proxy.
+ *
+ * @example
+ * ```ts
+ * import { createTestWalletConnector } from "@initia/interwovenkit-react"
+ *
+ * // From mnemonic
+ * const connector = createTestWalletConnector({
+ *   mnemonic: process.env.TEST_MNEMONIC!,
+ * })
+ *
+ * // Or from private key
+ * const connector = createTestWalletConnector({
+ *   privateKey: process.env.TEST_PRIVATE_KEY as `0x${string}`,
+ * })
+ *
+ * const config = createConfig({
+ *   connectors: [connector, ...otherConnectors],
+ * })
+ * ```
+ *
+ * ### Supported EIP-1193 methods
+ *
+ * | Method | Behavior |
+ * | --- | --- |
+ * | `eth_requestAccounts`, `eth_accounts` | Returns the account address |
+ * | `eth_chainId` | Returns current chain ID (hex) |
+ * | `personal_sign` | Signs with the account |
+ * | `eth_signTypedData`, `eth_signTypedData_v4` | Simplified: signs raw bytes (not EIP-712 compliant) |
+ * | `wallet_switchEthereumChain` | Switches chain; auto-registers from rpcUrls; throws 4902 if no RPC known |
+ * | `wallet_addEthereumChain` | Registers a new chain with its RPC URL |
+ * | `wallet_getPermissions`, `wallet_requestPermissions` | Returns `eth_accounts` permission |
+ * | `eth_sendTransaction` | Signs locally via viem, broadcasts to RPC |
+ * | *(any other method)* | Proxied to the current chain's RPC node |
+ */
+export declare function createTestWalletConnector(options: CreateTestWalletConfig): CreateConnectorFn<    {
+on: <event extends keyof EIP1193EventMap>(event: event, listener: EIP1193EventMap[event]) => void;
+removeListener: <event extends keyof EIP1193EventMap>(event: event, listener: EIP1193EventMap[event]) => void;
+request: EIP1193RequestFn<EIP1474Methods>;
+isApexWallet?: true | undefined;
+isAvalanche?: true | undefined;
+isBackpack?: true | undefined;
+isBifrost?: true | undefined;
+isBitKeep?: true | undefined;
+isBitski?: true | undefined;
+isBlockWallet?: true | undefined;
+isBraveWallet?: true | undefined;
+isCoinbaseWallet?: true | undefined;
+isDawn?: true | undefined;
+isEnkrypt?: true | undefined;
+isExodus?: true | undefined;
+isFrame?: true | undefined;
+isFrontier?: true | undefined;
+isGamestop?: true | undefined;
+isHyperPay?: true | undefined;
+isImToken?: true | undefined;
+isKuCoinWallet?: true | undefined;
+isMathWallet?: true | undefined;
+isMetaMask?: true | undefined;
+isOkxWallet?: true | undefined;
+isOKExWallet?: true | undefined;
+isOneInchAndroidWallet?: true | undefined;
+isOneInchIOSWallet?: true | undefined;
+isOpera?: true | undefined;
+isPhantom?: true | undefined;
+isPortal?: true | undefined;
+isRabby?: true | undefined;
+isRainbow?: true | undefined;
+isStatus?: true | undefined;
+isTally?: true | undefined;
+isTokenPocket?: true | undefined;
+isTokenary?: true | undefined;
+isTrust?: true | undefined;
+isTrustWallet?: true | undefined;
+isUniswapWallet?: true | undefined;
+isXDEFI?: true | undefined;
+isZerion?: true | undefined;
+providers?: {
+on: <event extends keyof EIP1193EventMap>(event: event, listener: EIP1193EventMap[event]) => void;
+removeListener: <event extends keyof EIP1193EventMap>(event: event, listener: EIP1193EventMap[event]) => void;
+request: EIP1193RequestFn<EIP1474Methods>;
+isApexWallet?: true | undefined;
+isAvalanche?: true | undefined;
+isBackpack?: true | undefined;
+isBifrost?: true | undefined;
+isBitKeep?: true | undefined;
+isBitski?: true | undefined;
+isBlockWallet?: true | undefined;
+isBraveWallet?: true | undefined;
+isCoinbaseWallet?: true | undefined;
+isDawn?: true | undefined;
+isEnkrypt?: true | undefined;
+isExodus?: true | undefined;
+isFrame?: true | undefined;
+isFrontier?: true | undefined;
+isGamestop?: true | undefined;
+isHyperPay?: true | undefined;
+isImToken?: true | undefined;
+isKuCoinWallet?: true | undefined;
+isMathWallet?: true | undefined;
+isMetaMask?: true | undefined;
+isOkxWallet?: true | undefined;
+isOKExWallet?: true | undefined;
+isOneInchAndroidWallet?: true | undefined;
+isOneInchIOSWallet?: true | undefined;
+isOpera?: true | undefined;
+isPhantom?: true | undefined;
+isPortal?: true | undefined;
+isRabby?: true | undefined;
+isRainbow?: true | undefined;
+isStatus?: true | undefined;
+isTally?: true | undefined;
+isTokenPocket?: true | undefined;
+isTokenary?: true | undefined;
+isTrust?: true | undefined;
+isTrustWallet?: true | undefined;
+isUniswapWallet?: true | undefined;
+isXDEFI?: true | undefined;
+isZerion?: true | undefined;
+providers?: /*elided*/ any[] | undefined | undefined;
+_events?: {
+connect?: (() => void) | undefined;
+} | undefined | undefined;
+_state?: {
+accounts?: string[];
+initialized?: boolean;
+isConnected?: boolean;
+isPermanentlyDisconnected?: boolean;
+isUnlocked?: boolean;
+} | undefined | undefined;
+}[] | undefined | undefined;
+_events?: {
+connect?: (() => void) | undefined;
+} | undefined | undefined;
+_state?: {
+accounts?: string[];
+initialized?: boolean;
+isConnected?: boolean;
+isPermanentlyDisconnected?: boolean;
+isUnlocked?: boolean;
+} | undefined | undefined;
+} | undefined, {
+onConnect(connectInfo: ProviderConnectInfo): void;
+}, {
+[x: `${string}.disconnected`]: true;
+"injected.connected": true;
+}>;
+
+export declare type CreateTestWalletOptions = {
+    /**
+     * BIP-39 mnemonic phrase. Provide either `mnemonic` or `privateKey`.
+     */
+    mnemonic: string;
+    privateKey?: never;
+} | {
+    mnemonic?: never;
+    /**
+     * Hex-encoded private key (with `0x` prefix).
+     * Provide either `mnemonic` or `privateKey`.
+     */
+    privateKey: `0x${string}`;
+};
+
 export declare const DEFAULT_GAS_ADJUSTMENT = 1.4;
 
 export declare const DEFAULT_GAS_PRICE_MULTIPLIER = 1.05;