From da2a3f0b07e8ec377546f88777e705cfa6a1d145 Mon Sep 17 00:00:00 2001 From: Manuel Alessandro Collazo Date: Wed, 20 May 2026 15:01:17 +0700 Subject: [PATCH 1/2] docs: align interwovenkit-react docs --- docs.json | 5 +- .../features/autosign/api-reference.mdx | 13 +- .../components/interwovenkit-provider.mdx | 10 +- .../references/hooks/use-interwovenkit.mdx | 22 ++- interwovenkit/references/index.mdx | 4 + .../references/utilities/testing.mdx | 187 ++++++++++++++++++ 6 files changed, 232 insertions(+), 9 deletions(-) create mode 100644 interwovenkit/references/utilities/testing.mdx diff --git a/docs.json b/docs.json index 25d6bf8c..8bd52e34 100644 --- a/docs.json +++ b/docs.json @@ -460,7 +460,10 @@ }, { "group": "Utilities", - "pages": ["interwovenkit/references/utilities/inject-styles"] + "pages": [ + "interwovenkit/references/utilities/inject-styles", + "interwovenkit/references/utilities/testing" + ] }, { "group": "Errors", diff --git a/interwovenkit/features/autosign/api-reference.mdx b/interwovenkit/features/autosign/api-reference.mdx index c85cab6d..d7adf82e 100644 --- a/interwovenkit/features/autosign/api-reference.mdx +++ b/interwovenkit/features/autosign/api-reference.mdx @@ -27,12 +27,16 @@ function MyComponent() { ```tsx interface AutoSign { isLoading: boolean - enable: (chainId?: string) => Promise + enable: (chainId?: string, options?: EnableAutoSignOptions) => Promise disable: (chainId?: string) => Promise expiredAtByChain: Record isEnabledByChain: Record granteeByChain: Record } + +interface EnableAutoSignOptions { + defaultDuration?: number +} ``` ## Properties @@ -157,7 +161,10 @@ function MultiChainStatus() { Enables autosign for a specific chain or the default chain. - + Opens a drawer for user confirmation, derives the AutoSign wallet for the current app origin, and creates the necessary authz and feegrant permissions. Returns a Promise that resolves when autosign is successfully enabled or @@ -165,6 +172,8 @@ Enables autosign for a specific chain or the default chain. **Parameters:** - `chainId` (optional): Chain ID to enable autosign for. If not provided, uses the default chain ID from `InterwovenKitProvider`. +- `options` (optional): Extra enable-flow options. `defaultDuration` preselects + the expiration duration shown in the enable drawer. **Returns:** Promise that resolves when autosign is enabled diff --git a/interwovenkit/references/components/interwovenkit-provider.mdx b/interwovenkit/references/components/interwovenkit-provider.mdx index 2453b669..084d9bb6 100644 --- a/interwovenkit/references/components/interwovenkit-provider.mdx +++ b/interwovenkit/references/components/interwovenkit-provider.mdx @@ -88,6 +88,7 @@ export function AppProviders({ children }: { children: React.ReactNode }) { | `disableAnalytics` | `boolean` | `false` (mainnet), `true` (testnet) | When `true`, disables InterwovenKit's built‑in analytics events | | `enableAutoSign` | `boolean \| Record` | `undefined` | Enables AutoSign and optionally whitelists chains and message types. `true` enables the default message type for the current default chain. `Record` is a per-chain allowlist of message type URLs | | `autoSignFeePolicy` | `Record` | `undefined` | Optional per-chain fee policy overrides for AutoSign gas multiplier and allowed fee denoms | +| `cosmosWallets` | `CosmosWallet[]` | `undefined` | Additional Cosmos wallets shown in bridge wallet selection. Configured wallets are listed before the built-in Keplr and Leap entries, and a matching `name` replaces the built-in wallet with the same name | ## Return Value @@ -168,10 +169,11 @@ type Config = { disableAnalytics?: boolean enableAutoSign?: boolean | Record autoSignFeePolicy?: Record + cosmosWallets?: CosmosWallet[] } ``` -Types `Chain`, `GeneratedType`, `AminoConverters`, and `AutoSignFeePolicy` are -from InterwovenKit source and its external dependencies. See -`@initia/initia-registry-types`, `@cosmjs/proto-signing`, and `@cosmjs/stargate` -for related external types. +Types `Chain`, `GeneratedType`, `AminoConverters`, `AutoSignFeePolicy`, and +`CosmosWallet` are from InterwovenKit source and its external dependencies. See +`@initia/initia-registry-types`, `@cosmjs/proto-signing`, and +`@cosmjs/stargate` for related external types. diff --git a/interwovenkit/references/hooks/use-interwovenkit.mdx b/interwovenkit/references/hooks/use-interwovenkit.mdx index 09f528e5..8e88e76e 100644 --- a/interwovenkit/references/hooks/use-interwovenkit.mdx +++ b/interwovenkit/references/hooks/use-interwovenkit.mdx @@ -365,6 +365,11 @@ fees: Pre-calculated fee for the transaction. + + When AutoSign is enabled, prefers this denom for the fee if it's allowed and + available. Falls back to the chain's default fee denom otherwise. + + ### Transaction Confirmation Options The `WaitForTxOptions` interface defines parameters for tracking transaction @@ -472,7 +477,15 @@ signing: Whether AutoSign status is being loaded. - + + Map of chain IDs to the derived AutoSign wallet addresses authorized for each + chain. + + + Opens UI to enable AutoSign for a chain. Optionally specify a chain ID, or defaults to the provider's `defaultChainId` if omitted. @@ -616,6 +629,7 @@ type TxParams = { memo?: string chainId?: string fee: StdFee + preferredFeeDenom?: string } type WaitForTxOptions = { @@ -630,9 +644,13 @@ type AutoSignState = { isEnabledByChain: Record granteeByChain: Record isLoading: boolean - enable: (chainId?: string) => Promise + enable: (chainId?: string, options?: EnableAutoSignOptions) => Promise disable: (chainId?: string) => Promise } + +type EnableAutoSignOptions = { + defaultDuration?: number +} ``` Types `OfflineAminoSigner`, `EncodeObject`, `Coin`, `StdFee`, diff --git a/interwovenkit/references/index.mdx b/interwovenkit/references/index.mdx index 57657073..49655e7c 100644 --- a/interwovenkit/references/index.mdx +++ b/interwovenkit/references/index.mdx @@ -17,6 +17,7 @@ flows. The API is organized into: - **Hooks**: React hooks for connection state, transactions, and data (`useInterwovenKit`, `useAddress`, `usePortfolio`, etc.) - **Utilities**: Helper functions (`injectStyles`) +- **Testing**: Test helpers (`createTestWalletConnector`, `createTestCosmosWallet`) - **Errors**: Error types thrown by the API (`MoveError`) - **Constants**: Configuration presets and default values (`MAINNET`, `TESTNET`, gas constants, `PRIVY_APP_ID`) @@ -32,6 +33,9 @@ flows. The API is organized into: [`MAINNET`](./constants/mainnet) or [`TESTNET`](./constants/testnet) - **Inject styles**: Call [`injectStyles`](./utilities/inject-styles) before rendering InterwovenKit UI components +- **Test helpers**: Use [`createTestWalletConnector`](./utilities/testing) and + [`createTestCosmosWallet`](./utilities/testing) for automated EVM and Cosmos + wallet tests - **Read connection state**: [`useAddress`](./hooks/use-address) or [`useInterwovenKit`](./hooks/use-interwovenkit) - **Open UI flows**: [`useInterwovenKit`](./hooks/use-interwovenkit) diff --git a/interwovenkit/references/utilities/testing.mdx b/interwovenkit/references/utilities/testing.mdx new file mode 100644 index 00000000..dc6de36d --- /dev/null +++ b/interwovenkit/references/utilities/testing.mdx @@ -0,0 +1,187 @@ +--- +title: Testing Helpers +--- + +## Overview + +- `createTestWalletConnector` creates a wagmi-compatible, in-memory EVM wallet + connector backed by a mnemonic or private key. +- `createTestCosmosWallet` creates a Cosmos wallet entry that appears in the + Bridge wallet picker, derived lazily per chain prefix from a mnemonic. +- Use these helpers when you want deterministic wallet behavior in automated + tests (Playwright, Cypress, Vitest) or local development without browser + extensions or external wallet apps. + + + These helpers are intended for **testing and local development only**. They + read raw mnemonics and private keys directly from your environment. Never + ship them, or wallets created with them, with real user funds. + + +## Prerequisites + +- Must run in a browser-like environment for the EVM connector because it is + implemented as an injected wagmi connector. +- Provide test credentials via environment variables (e.g. + `TEST_MNEMONIC`, `TEST_PRIVATE_KEY`, `TEST_COSMOS_MNEMONIC`) — never hardcode + them in source. + +## `createTestWalletConnector` + +An EVM wallet connector that handles chain switching, message signing, and +transaction submission entirely in memory. Standard contract interactions and +RPC reads (gas estimation, receipts, etc.) are proxied to the chain's RPC +node. + +```tsx +import { createConfig, http } from 'wagmi' +import { mainnet } from 'wagmi/chains' +import { createTestWalletConnector } from '@initia/interwovenkit-react' + +const testConnector = createTestWalletConnector({ + mnemonic: process.env.TEST_MNEMONIC!, + // Or: privateKey: process.env.TEST_PRIVATE_KEY as `0x${string}`, +}) + +const wagmiConfig = createConfig({ + connectors: [testConnector], + chains: [mainnet], + transports: { [mainnet.id]: http() }, +}) +``` + +### Config + + + BIP-39 mnemonic phrase. Provide either `mnemonic` or `privateKey`. + + + + Hex-encoded private key with `0x` prefix. Provide either `mnemonic` or + `privateKey`. + + + + Wagmi connector ID. Set this when running multiple test wallets in the same + config. + + + + Display name shown in the wallet selection UI. + + + + CORS-friendly RPC URLs keyed by EVM chain ID. User-provided URLs override the + built-in defaults (Ethereum mainnet, Arbitrum One, Base) for matching chain + IDs. + + + + When `true`, logs every RPC call to the console. + + + + Overrides applied to every `eth_sendTransaction` call. Useful for forcing + failure scenarios in tests (e.g. `{ gas: 21000n }` to trigger out-of-gas + reverts on contract calls, or `{ maxFeePerGas: 1n }` to land below the base + fee). + + +### Supported EIP-1193 methods + +| Method | Behavior | +| ------------------------------------------------------- | ------------------------------------------------------------------------------ | +| `eth_requestAccounts`, `eth_accounts` | Returns the derived account address | +| `eth_chainId` | Returns the current chain ID (hex) | +| `personal_sign` | Signs the message with the test account | +| `eth_signTypedData`, `eth_signTypedData_v4` | Signs raw bytes (not EIP-712 compliant — sufficient for InterwovenKit's flows) | +| `wallet_switchEthereumChain` | Switches chain. Auto-registers from configured RPC URLs. Throws 4902 if unknown. | +| `wallet_addEthereumChain` | Registers a new chain with its RPC URL | +| `wallet_getPermissions`, `wallet_requestPermissions` | Returns the `eth_accounts` permission | +| `eth_sendTransaction` | Signs locally via viem and broadcasts to the RPC node | +| _Any other method_ | Proxied to the current chain's RPC node | + +### Return value + +```ts +function createTestWalletConnector(config: CreateTestWalletConfig): Connector +``` + +## `createTestCosmosWallet` + +Returns a `CosmosWallet` entry that appears in the Bridge wallet picker +alongside Keplr and Leap. Pass it through the `cosmosWallets` prop on +[`InterwovenKitProvider`](../components/interwovenkit-provider). + +```tsx +import { + createTestCosmosWallet, + InterwovenKitProvider, + MAINNET, +} from '@initia/interwovenkit-react' + +const testCosmosWallet = createTestCosmosWallet({ + mnemonic: process.env.TEST_COSMOS_MNEMONIC!, +}) + +export function Providers({ children }: { children: React.ReactNode }) { + return ( + + {children} + + ) +} +``` + +### Config + + + BIP-39 mnemonic phrase used to derive Cosmos accounts. + + + + Display name shown in the Bridge wallet selection list. A matching `name` + replaces the built-in wallet with the same name (e.g. naming this `Keplr` + replaces the Keplr entry). + + + + Wallet icon URL. Omit to show the default placeholder. + + + + Override the bech32 prefix for specific chain IDs. By default the prefix is + derived from the chain ID stem (e.g. `noble-1` → `noble`). Use this for + chains whose prefix differs from the stem (e.g. `cosmoshub-4` → `cosmos`). + + + + When `true`, logs signer creation to the console. + + +### Return value + +```ts +function createTestCosmosWallet(config: CreateTestCosmosWalletConfig): CosmosWallet +``` + +## Notes + +- `createTestWalletConnector` accepts either a `mnemonic` or a `privateKey`, + not both. Built-in CORS-safe RPCs are provided for Ethereum mainnet, + Arbitrum One, and Base; pass `rpcUrls` to add or override others. +- `wallet_addEthereumChain` does **not** auto-switch to the newly added chain, + unlike MetaMask. Call `wallet_switchEthereumChain` afterwards to activate + it. +- `eth_signTypedData` and `eth_signTypedData_v4` sign raw bytes rather than + performing full EIP-712 encoding. InterwovenKit only relies on + `personal_sign` for key derivation, so this is sufficient for its flows but + signatures will not validate against on-chain EIP-712 verifiers (e.g. + Permit2). +- `createTestCosmosWallet` caches one signer per derived bech32 prefix, so + repeated tests are deterministic and fast. +- See [`InterwovenKitProvider`](../components/interwovenkit-provider) for the + `cosmosWallets` prop and the related `CosmosWallet` type. From bcb651edd2e512c4d3b315a7eb08cdfb7a9ba581 Mon Sep 17 00:00:00 2001 From: Manuel Alessandro Collazo Date: Wed, 20 May 2026 15:03:38 +0700 Subject: [PATCH 2/2] style: Prettier formatting --- .../features/autosign/api-reference.mdx | 1 + .../components/interwovenkit-provider.mdx | 6 +- .../references/hooks/use-interwovenkit.mdx | 5 +- interwovenkit/references/index.mdx | 3 +- .../references/utilities/testing.mdx | 58 +++++++++---------- 5 files changed, 38 insertions(+), 35 deletions(-) diff --git a/interwovenkit/features/autosign/api-reference.mdx b/interwovenkit/features/autosign/api-reference.mdx index d7adf82e..4bfdb1d3 100644 --- a/interwovenkit/features/autosign/api-reference.mdx +++ b/interwovenkit/features/autosign/api-reference.mdx @@ -172,6 +172,7 @@ Enables autosign for a specific chain or the default chain. **Parameters:** - `chainId` (optional): Chain ID to enable autosign for. If not provided, uses the default chain ID from `InterwovenKitProvider`. + - `options` (optional): Extra enable-flow options. `defaultDuration` preselects the expiration duration shown in the enable drawer. diff --git a/interwovenkit/references/components/interwovenkit-provider.mdx b/interwovenkit/references/components/interwovenkit-provider.mdx index 084d9bb6..1856bf7d 100644 --- a/interwovenkit/references/components/interwovenkit-provider.mdx +++ b/interwovenkit/references/components/interwovenkit-provider.mdx @@ -88,7 +88,7 @@ export function AppProviders({ children }: { children: React.ReactNode }) { | `disableAnalytics` | `boolean` | `false` (mainnet), `true` (testnet) | When `true`, disables InterwovenKit's built‑in analytics events | | `enableAutoSign` | `boolean \| Record` | `undefined` | Enables AutoSign and optionally whitelists chains and message types. `true` enables the default message type for the current default chain. `Record` is a per-chain allowlist of message type URLs | | `autoSignFeePolicy` | `Record` | `undefined` | Optional per-chain fee policy overrides for AutoSign gas multiplier and allowed fee denoms | -| `cosmosWallets` | `CosmosWallet[]` | `undefined` | Additional Cosmos wallets shown in bridge wallet selection. Configured wallets are listed before the built-in Keplr and Leap entries, and a matching `name` replaces the built-in wallet with the same name | +| `cosmosWallets` | `CosmosWallet[]` | `undefined` | Additional Cosmos wallets shown in bridge wallet selection. Configured wallets are listed before the built-in Keplr and Leap entries, and a matching `name` replaces the built-in wallet with the same name | ## Return Value @@ -175,5 +175,5 @@ type Config = { Types `Chain`, `GeneratedType`, `AminoConverters`, `AutoSignFeePolicy`, and `CosmosWallet` are from InterwovenKit source and its external dependencies. See -`@initia/initia-registry-types`, `@cosmjs/proto-signing`, and -`@cosmjs/stargate` for related external types. +`@initia/initia-registry-types`, `@cosmjs/proto-signing`, and `@cosmjs/stargate` +for related external types. diff --git a/interwovenkit/references/hooks/use-interwovenkit.mdx b/interwovenkit/references/hooks/use-interwovenkit.mdx index 8e88e76e..fca439b7 100644 --- a/interwovenkit/references/hooks/use-interwovenkit.mdx +++ b/interwovenkit/references/hooks/use-interwovenkit.mdx @@ -477,7 +477,10 @@ signing: Whether AutoSign status is being loaded. - + Map of chain IDs to the derived AutoSign wallet addresses authorized for each chain. diff --git a/interwovenkit/references/index.mdx b/interwovenkit/references/index.mdx index 49655e7c..9c29fd7a 100644 --- a/interwovenkit/references/index.mdx +++ b/interwovenkit/references/index.mdx @@ -17,7 +17,8 @@ flows. The API is organized into: - **Hooks**: React hooks for connection state, transactions, and data (`useInterwovenKit`, `useAddress`, `usePortfolio`, etc.) - **Utilities**: Helper functions (`injectStyles`) -- **Testing**: Test helpers (`createTestWalletConnector`, `createTestCosmosWallet`) +- **Testing**: Test helpers (`createTestWalletConnector`, + `createTestCosmosWallet`) - **Errors**: Error types thrown by the API (`MoveError`) - **Constants**: Configuration presets and default values (`MAINNET`, `TESTNET`, gas constants, `PRIVY_APP_ID`) diff --git a/interwovenkit/references/utilities/testing.mdx b/interwovenkit/references/utilities/testing.mdx index dc6de36d..188ecf7d 100644 --- a/interwovenkit/references/utilities/testing.mdx +++ b/interwovenkit/references/utilities/testing.mdx @@ -14,24 +14,22 @@ title: Testing Helpers These helpers are intended for **testing and local development only**. They - read raw mnemonics and private keys directly from your environment. Never - ship them, or wallets created with them, with real user funds. + read raw mnemonics and private keys directly from your environment. Never ship + them, or wallets created with them, with real user funds. ## Prerequisites - Must run in a browser-like environment for the EVM connector because it is implemented as an injected wagmi connector. -- Provide test credentials via environment variables (e.g. - `TEST_MNEMONIC`, `TEST_PRIVATE_KEY`, `TEST_COSMOS_MNEMONIC`) — never hardcode - them in source. +- Provide test credentials via environment variables (e.g. `TEST_MNEMONIC`, + `TEST_PRIVATE_KEY`, `TEST_COSMOS_MNEMONIC`) — never hardcode them in source. ## `createTestWalletConnector` An EVM wallet connector that handles chain switching, message signing, and transaction submission entirely in memory. Standard contract interactions and -RPC reads (gas estimation, receipts, etc.) are proxied to the chain's RPC -node. +RPC reads (gas estimation, receipts, etc.) are proxied to the chain's RPC node. ```tsx import { createConfig, http } from 'wagmi' @@ -92,17 +90,17 @@ const wagmiConfig = createConfig({ ### Supported EIP-1193 methods -| Method | Behavior | -| ------------------------------------------------------- | ------------------------------------------------------------------------------ | -| `eth_requestAccounts`, `eth_accounts` | Returns the derived account address | -| `eth_chainId` | Returns the current chain ID (hex) | -| `personal_sign` | Signs the message with the test account | -| `eth_signTypedData`, `eth_signTypedData_v4` | Signs raw bytes (not EIP-712 compliant — sufficient for InterwovenKit's flows) | -| `wallet_switchEthereumChain` | Switches chain. Auto-registers from configured RPC URLs. Throws 4902 if unknown. | -| `wallet_addEthereumChain` | Registers a new chain with its RPC URL | -| `wallet_getPermissions`, `wallet_requestPermissions` | Returns the `eth_accounts` permission | -| `eth_sendTransaction` | Signs locally via viem and broadcasts to the RPC node | -| _Any other method_ | Proxied to the current chain's RPC node | +| Method | Behavior | +| ---------------------------------------------------- | -------------------------------------------------------------------------------- | +| `eth_requestAccounts`, `eth_accounts` | Returns the derived account address | +| `eth_chainId` | Returns the current chain ID (hex) | +| `personal_sign` | Signs the message with the test account | +| `eth_signTypedData`, `eth_signTypedData_v4` | Signs raw bytes (not EIP-712 compliant — sufficient for InterwovenKit's flows) | +| `wallet_switchEthereumChain` | Switches chain. Auto-registers from configured RPC URLs. Throws 4902 if unknown. | +| `wallet_addEthereumChain` | Registers a new chain with its RPC URL | +| `wallet_getPermissions`, `wallet_requestPermissions` | Returns the `eth_accounts` permission | +| `eth_sendTransaction` | Signs locally via viem and broadcasts to the RPC node | +| _Any other method_ | Proxied to the current chain's RPC node | ### Return value @@ -154,8 +152,8 @@ export function Providers({ children }: { children: React.ReactNode }) { Override the bech32 prefix for specific chain IDs. By default the prefix is - derived from the chain ID stem (e.g. `noble-1` → `noble`). Use this for - chains whose prefix differs from the stem (e.g. `cosmoshub-4` → `cosmos`). + derived from the chain ID stem (e.g. `noble-1` → `noble`). Use this for chains + whose prefix differs from the stem (e.g. `cosmoshub-4` → `cosmos`). @@ -165,22 +163,22 @@ export function Providers({ children }: { children: React.ReactNode }) { ### Return value ```ts -function createTestCosmosWallet(config: CreateTestCosmosWalletConfig): CosmosWallet +function createTestCosmosWallet( + config: CreateTestCosmosWalletConfig, +): CosmosWallet ``` ## Notes -- `createTestWalletConnector` accepts either a `mnemonic` or a `privateKey`, - not both. Built-in CORS-safe RPCs are provided for Ethereum mainnet, - Arbitrum One, and Base; pass `rpcUrls` to add or override others. +- `createTestWalletConnector` accepts either a `mnemonic` or a `privateKey`, not + both. Built-in CORS-safe RPCs are provided for Ethereum mainnet, Arbitrum One, + and Base; pass `rpcUrls` to add or override others. - `wallet_addEthereumChain` does **not** auto-switch to the newly added chain, - unlike MetaMask. Call `wallet_switchEthereumChain` afterwards to activate - it. + unlike MetaMask. Call `wallet_switchEthereumChain` afterwards to activate it. - `eth_signTypedData` and `eth_signTypedData_v4` sign raw bytes rather than - performing full EIP-712 encoding. InterwovenKit only relies on - `personal_sign` for key derivation, so this is sufficient for its flows but - signatures will not validate against on-chain EIP-712 verifiers (e.g. - Permit2). + performing full EIP-712 encoding. InterwovenKit only relies on `personal_sign` + for key derivation, so this is sufficient for its flows but signatures will + not validate against on-chain EIP-712 verifiers (e.g. Permit2). - `createTestCosmosWallet` caches one signer per derived bech32 prefix, so repeated tests are deterministic and fast. - See [`InterwovenKitProvider`](../components/interwovenkit-provider) for the