diff --git a/docs.json b/docs.json index 75450c6..7f3d962 100644 --- a/docs.json +++ b/docs.json @@ -414,10 +414,55 @@ ] }, { - "group": "References", + "group": "API Reference", "pages": [ - "interwovenkit/references/interwovenkit-provider", - "interwovenkit/references/useinterwovenkit" + "interwovenkit/references/index", + { + "group": "Setup", + "pages": ["interwovenkit/references/setup/providers"] + }, + { + "group": "Components", + "pages": [ + "interwovenkit/references/components/interwovenkit-provider" + ] + }, + { + "group": "Hooks", + "pages": [ + "interwovenkit/references/hooks/use-interwovenkit", + "interwovenkit/references/hooks/use-address", + "interwovenkit/references/hooks/use-initia-address", + "interwovenkit/references/hooks/use-hex-address", + "interwovenkit/references/hooks/use-portfolio", + "interwovenkit/references/hooks/use-username-query" + ] + }, + { + "group": "Utilities", + "pages": ["interwovenkit/references/utilities/inject-styles"] + }, + { + "group": "Errors", + "pages": ["interwovenkit/references/errors/move-error"] + }, + { + "group": "Constants", + "pages": [ + "interwovenkit/references/constants/mainnet", + "interwovenkit/references/constants/testnet", + "interwovenkit/references/constants/default-gas-adjustment", + "interwovenkit/references/constants/default-gas-price-multiplier", + "interwovenkit/references/constants/privy-app-id" + ] + }, + { + "group": "Social Login", + "pages": [ + "interwovenkit/references/social-login/initia-privy-wallet", + "interwovenkit/references/social-login/initia-privy-wallet-connector" + ] + } ] } ] diff --git a/interwovenkit/integrations/evm.mdx b/interwovenkit/integrations/evm.mdx index 5d14183..a2136a0 100644 --- a/interwovenkit/integrations/evm.mdx +++ b/interwovenkit/integrations/evm.mdx @@ -41,7 +41,7 @@ import { InterwovenKitProvider, TESTNET, } from '@initia/interwovenkit-react' -import InterwovenKitStyles from '@initia/interwovenkit-react/styles.js' +import interwovenKitStyles from '@initia/interwovenkit-react/styles.js' const minievm = { id: 4303131403034904, @@ -63,7 +63,7 @@ const queryClient = new QueryClient() export default function Providers({ children }: PropsWithChildren) { useEffect(() => { // Inject styles into the shadow DOM used by Initia Wallet - injectStyles(InterwovenKitStyles) + injectStyles(interwovenKitStyles) }, []) return ( @@ -96,7 +96,8 @@ export default function Providers({ children }: PropsWithChildren) { blockchain for Initia Wallet operations. For EVM rollups, use your rollup's chain ID (like `"minievm-2"`), not the EVM chain ID. This ensures proper balance display and bridging functionality. See [InterwovenKitProvider - reference](/interwovenkit/references/interwovenkit-provider) for more details. + reference](/interwovenkit/references/components/interwovenkit-provider) for + more details. diff --git a/interwovenkit/integrations/native.mdx b/interwovenkit/integrations/native.mdx index 9ab0fd0..a297b15 100644 --- a/interwovenkit/integrations/native.mdx +++ b/interwovenkit/integrations/native.mdx @@ -68,7 +68,7 @@ import { injectStyles, InterwovenKitProvider, } from '@initia/interwovenkit-react' -import InterwovenKitStyles from '@initia/interwovenkit-react/styles.js' +import interwovenKitStyles from '@initia/interwovenkit-react/styles.js' const wagmiConfig = createConfig({ connectors: [initiaPrivyWalletConnector], @@ -80,7 +80,7 @@ const queryClient = new QueryClient() export default function Providers({ children }: PropsWithChildren) { useEffect(() => { // Inject styles into the shadow DOM used by Initia Wallet - injectStyles(InterwovenKitStyles) + injectStyles(interwovenKitStyles) }, []) return ( @@ -102,7 +102,8 @@ export default function Providers({ children }: PropsWithChildren) { [initia-registry](https://registry.initia.xyz) This sets the primary network for transactions, balance queries, and serves as the default for all operations. See the [InterwovenKitProvider - reference](/interwovenkit/references/interwovenkit-provider) for details. + reference](/interwovenkit/references/components/interwovenkit-provider) for + details. diff --git a/interwovenkit/integrations/rainbowkit.mdx b/interwovenkit/integrations/rainbowkit.mdx index fa131c4..8805231 100644 --- a/interwovenkit/integrations/rainbowkit.mdx +++ b/interwovenkit/integrations/rainbowkit.mdx @@ -66,7 +66,7 @@ RainbowKit integration with InterwovenKit provides: import { connectorsForWallets, RainbowKitProvider } from "@rainbow-me/rainbowkit" import "@rainbow-me/rainbowkit/styles.css" import { initiaPrivyWallet, injectStyles, InterwovenKitProvider } from "@initia/interwovenkit-react" - import InterwovenKitStyles from "@initia/interwovenkit-react/styles.js" + import interwovenKitStyles from "@initia/interwovenkit-react/styles.js" const connectors = connectorsForWallets( [ @@ -92,7 +92,7 @@ RainbowKit integration with InterwovenKit provides: export default function Providers({ children }: PropsWithChildren) { useEffect(() => { // Inject styles into the shadow DOM used by Initia Wallet - injectStyles(InterwovenKitStyles) + injectStyles(interwovenKitStyles) }, []) return ( @@ -117,7 +117,7 @@ RainbowKit integration with InterwovenKit provides: - Or any valid chain ID from the [initia-registry](https://registry.initia.xyz) - Update `appName` and `projectId` to match your application details - The `defaultChainId` sets the primary network for all Initia Wallet operations. See [InterwovenKitProvider reference](/interwovenkit/references/interwovenkit-provider) for details. + The `defaultChainId` sets the primary network for all Initia Wallet operations. See [InterwovenKitProvider reference](/interwovenkit/references/components/interwovenkit-provider) for details. diff --git a/interwovenkit/migration.mdx b/interwovenkit/migration.mdx index 455425c..dc22bfc 100644 --- a/interwovenkit/migration.mdx +++ b/interwovenkit/migration.mdx @@ -131,7 +131,7 @@ improved TypeScript support, and a more intuitive API. injectStyles, InterwovenKitProvider } from "@initia/interwovenkit-react" - import InterwovenKitStyles from "@initia/interwovenkit-react/styles.js" + import interwovenKitStyles from "@initia/interwovenkit-react/styles.js" // Configure Wagmi for wallet connections const wagmiConfig = createConfig({ @@ -145,7 +145,7 @@ improved TypeScript support, and a more intuitive API. export default function Providers({ children }: PropsWithChildren) { useEffect(() => { // Inject styles into the shadow DOM used by Initia Wallet - injectStyles(InterwovenKitStyles) + injectStyles(interwovenKitStyles) }, []) return ( @@ -345,7 +345,8 @@ export default function TransactionComponent() { For more granular control over transaction states, use `requestTxSync()` to get the transaction hash immediately, then `waitForTxConfirmation()` to wait for blockchain confirmation. See the [useInterwovenKit - reference](./references/useinterwovenkit#transactions) for details. + reference](./references/hooks/use-interwovenkit#transaction-methods) for + details. ## Advanced Integration @@ -436,5 +437,5 @@ export default function SendTransaction() { Need help with migration? Check out the [Getting Started guide](./getting-started) for complete implementation examples, or refer to - the [API Reference](./references) for detailed method documentation. + the [API Reference](./references/index) for detailed method documentation. diff --git a/interwovenkit/references/components/interwovenkit-provider.mdx b/interwovenkit/references/components/interwovenkit-provider.mdx new file mode 100644 index 0000000..61f3333 --- /dev/null +++ b/interwovenkit/references/components/interwovenkit-provider.mdx @@ -0,0 +1,180 @@ +--- +title: InterwovenKitProvider +--- + +## Overview + +- React provider that configures and renders the InterwovenKit widget shell + (drawer, routes, and supporting providers). +- Mount once near the top of your app, wrapping your root component. +- Privy and AutoSign are optional. Configure `privyContext` and `enableAutoSign` + only if needed. AutoSign requires Privy (`PrivyProvider` and `privyContext`). + +## Prerequisites + +- Must be used within a React Query `QueryClientProvider`. +- Must be used within a wagmi `WagmiProvider` if using wallet-related APIs. +- Client-only (no SSR): Put this in a `use client` provider tree, or use a + dynamic import in Next.js. + +## Styles + +- CSS styles must be injected manually using + [`injectStyles`](../utilities/inject-styles) once at app startup. Otherwise + the UI will be unstyled. + +## Quickstart + +```tsx +'use client' + +import { useEffect } from 'react' +import { QueryClient, QueryClientProvider } from '@tanstack/react-query' +import { createConfig, http, WagmiProvider } from 'wagmi' +import { mainnet } from 'wagmi/chains' +import { + initiaPrivyWalletConnector, + injectStyles, + InterwovenKitProvider, + MAINNET, +} from '@initia/interwovenkit-react' +import interwovenKitStyles from '@initia/interwovenkit-react/styles.js' + +const queryClient = new QueryClient() +const wagmiConfig = createConfig({ + connectors: [initiaPrivyWalletConnector], + chains: [mainnet], + transports: { [mainnet.id]: http() }, +}) + +export function AppProviders({ children }: { children: React.ReactNode }) { + useEffect(() => { + injectStyles(interwovenKitStyles) + }, []) + + return ( + + + {children} + + + ) +} +``` + + + This example shows the provider structure. For complete setup configurations, + see [Provider Setup](../setup/providers). + + +## Props + +| Prop | Type | Default | Description | +| ------------------------ | ------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `defaultChainId` | `string` | From preset | Initia or rollup chain ID that InterwovenKit should treat as the "home" chain | +| `registryUrl` | `string` | From preset | Base URL for the Initia registry API used to resolve chains and assets | +| `routerApiUrl` | `string` | From preset | Base URL for the router API used by the bridge and swap flows | +| `glyphUrl` | `string` | From preset | Base URL for Glyph profile data (user avatars and related metadata) | +| `usernamesModuleAddress` | `string` | From preset | On‑chain module address of the Initia (`.init`) username contract | +| `theme` | `"light" \| "dark"` | From preset (typically dark) | Visual theme for the widget | +| `customChain` | `Chain` | `undefined` | Adds or overrides a chain definition in the Initia registry. Use when you run a private rollup or need to inject a chain that is not yet in the public registry | +| `protoTypes` | `Iterable<[string, GeneratedType]>` | `undefined` | Additional protobuf type mappings used when encoding Cosmos transactions. Only needed if you use custom message types | +| `aminoConverters` | `AminoConverters` | `undefined` | Custom Amino converters for legacy signing. Only needed for advanced integrations | +| `container` | `HTMLElement` | `undefined` | Optional element the widget should render into instead of the default Shadow DOM host | +| `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 for supported chains and messages. `Record` is a per-chain allowlist of message type URLs. **Requires Privy** (`PrivyProvider` and `privyContext`). Required at runtime only if you want AutoSign flows to be available | +| `privyContext` | `PrivyContext` | `undefined` | Passes Privy authentication and wallet helpers into InterwovenKit. **Required for AutoSign and embedded wallet features**, otherwise optional | + +## Return value + +Renders `children` and mounts the InterwovenKit UI shell. + +## Examples + +### Custom chain configuration + +```tsx +import type { Chain } from '@initia/initia-registry-types' +import { InterwovenKitProvider, MAINNET } from '@initia/interwovenkit-react' + +const MY_ROLLUP: Chain = { + chain_id: 'my-rollup-1', + chain_name: 'my-rollup', + pretty_name: 'My Rollup', + network_type: 'mainnet', + bech32_prefix: 'init', + fees: { + fee_tokens: [ + { + denom: 'uinit', + fixed_min_gas_price: 0.1, + }, + ], + }, + apis: { + rpc: [{ address: 'https://rpc.my-rollup.com' }], + rest: [{ address: 'https://api.my-rollup.com' }], + indexer: [{ address: 'https://indexer.my-rollup.com' }], + }, +} as Chain + +export function Providers({ children }: { children: React.ReactNode }) { + return ( + + {children} + + ) +} +``` + + + This example shows only the `InterwovenKitProvider` configuration. For + complete provider setup including `QueryClientProvider`, `WagmiProvider`, and + `injectStyles`, see [Provider Setup](../setup/providers). + + +## Notes + +- For AutoSign and Privy integration setup, see + [Provider Setup](../setup/providers). + +## Type reference (advanced) + +```ts +type InterwovenKitProviderProps = React.PropsWithChildren> + +type Config = { + defaultChainId: string + customChain?: Chain + protoTypes?: Iterable<[string, GeneratedType]> + aminoConverters?: AminoConverters + registryUrl: string + routerApiUrl: string + glyphUrl: string + usernamesModuleAddress: string + theme: 'light' | 'dark' + container?: HTMLElement + disableAnalytics?: boolean + enableAutoSign?: boolean | Record + privyContext?: PrivyContext +} + +type PrivyContext = { + privy: ReturnType + createWallet: ReturnType['createWallet'] + wallets: ReturnType['wallets'] + siwe: ReturnType +} +``` + +Types `Chain`, `GeneratedType`, and `AminoConverters` are from external +packages. See `@initia/initia-registry-types`, `@cosmjs/proto-signing`, and +`@cosmjs/stargate` for details. + +`PrivyContext` members are derived from Privy hooks: `usePrivy`, +`useCreateWallet`, `useWallets`, and `useLoginWithSiwe` from +`@privy-io/react-auth`. diff --git a/interwovenkit/references/constants/default-gas-adjustment.mdx b/interwovenkit/references/constants/default-gas-adjustment.mdx new file mode 100644 index 0000000..2382a69 --- /dev/null +++ b/interwovenkit/references/constants/default-gas-adjustment.mdx @@ -0,0 +1,33 @@ +--- +title: DEFAULT_GAS_ADJUSTMENT +--- + +## Overview + +- Default gas adjustment multiplier used when `gasAdjustment` is not provided in + transaction requests. +- Reference only if you need to match InterwovenKit's default in custom logic. + +## Quickstart + +```ts +import { DEFAULT_GAS_ADJUSTMENT } from "@initia/interwovenkit-react" + +// Pass explicit gasAdjustment to match InterwovenKit's default +const { requestTxBlock } = useInterwovenKit() +await requestTxBlock({ + messages: [...], + gasAdjustment: DEFAULT_GAS_ADJUSTMENT, // Optional: defaults to this value if omitted +}) +``` + +## Value + +```ts +const DEFAULT_GAS_ADJUSTMENT: number // 1.4 +``` + +## Notes + +- InterwovenKit uses this automatically when `gasAdjustment` is omitted. +- Reference only if you need to match the default in custom logic. diff --git a/interwovenkit/references/constants/default-gas-price-multiplier.mdx b/interwovenkit/references/constants/default-gas-price-multiplier.mdx new file mode 100644 index 0000000..b18fe37 --- /dev/null +++ b/interwovenkit/references/constants/default-gas-price-multiplier.mdx @@ -0,0 +1,29 @@ +--- +title: DEFAULT_GAS_PRICE_MULTIPLIER +--- + +## Overview + +- Default gas price multiplier used for non-INIT fee tokens on Layer 1 chains. +- Reference only if you need to reproduce InterwovenKit's fee calculation logic. + +## Quickstart + +```ts +import { DEFAULT_GAS_PRICE_MULTIPLIER } from '@initia/interwovenkit-react' + +// Reproduce InterwovenKit's fee calculation logic +const adjustedPrice = baseGasPrice * DEFAULT_GAS_PRICE_MULTIPLIER +``` + +## Value + +```ts +const DEFAULT_GAS_PRICE_MULTIPLIER: number // 1.05 +``` + +## Notes + +- InterwovenKit applies this automatically when suggesting fees. +- Reference only if building custom fee calculation logic that needs to match + InterwovenKit's behavior. diff --git a/interwovenkit/references/constants/mainnet.mdx b/interwovenkit/references/constants/mainnet.mdx new file mode 100644 index 0000000..dcae2b7 --- /dev/null +++ b/interwovenkit/references/constants/mainnet.mdx @@ -0,0 +1,46 @@ +--- +title: MAINNET +--- + +## Overview + +- Configuration preset for Initia mainnet with defaults for registry, router, + glyph, and username services. +- Use as a starting point for production apps. + +## Quickstart + +```tsx +import { InterwovenKitProvider, MAINNET } from '@initia/interwovenkit-react' + +export function Providers({ children }: { children: React.ReactNode }) { + return {children} +} +``` + +## Value + +```ts +const MAINNET: { + defaultChainId: 'interwoven-1' + registryUrl: 'https://registry.initia.xyz' + routerApiUrl: 'https://router-api.initia.xyz' + glyphUrl: 'https://glyph.initia.xyz' + usernamesModuleAddress: '0x72ed9b26ecdcd6a21d304df50f19abfdbe31d2c02f60c84627844620a45940ef' + theme: 'dark' +} +``` + +**Property descriptions:** + +- `usernamesModuleAddress`: On-chain module address of the Initia (`.init`) + username contract. This is the same for all apps using mainnet and it + represents the deployed contract address that handles username lookups (e.g., + resolving `alice.init` to an address) +- `theme`: Default theme is `"dark"`, but can be overridden to `"light"` when + using the preset + +## Notes + +- Most apps should start with `{...MAINNET}` and override only what they need + (for example `defaultChainId` or `theme`). diff --git a/interwovenkit/references/constants/privy-app-id.mdx b/interwovenkit/references/constants/privy-app-id.mdx new file mode 100644 index 0000000..2128f22 --- /dev/null +++ b/interwovenkit/references/constants/privy-app-id.mdx @@ -0,0 +1,57 @@ +--- +title: PRIVY_APP_ID +--- + +## Overview + +- Initia's shared Privy application ID used by bundled wallet helpers. +- NOT your app's Privy ID. References Initia's shared Privy app (bundled + social/embedded wallet). +- Use when configuring login methods that include the Initia Privy wallet + alongside your own Privy app. + +## Prerequisites + +- Relevant only if you are using Privy. +- Privy must be set up separately (see Privy documentation for setup). + +## Quickstart + +```tsx +import { PRIVY_APP_ID } from '@initia/interwovenkit-react' +import { PrivyProvider } from '@privy-io/react-auth' + +export function Providers({ children }: { children: React.ReactNode }) { + return ( + + {children} + + ) +} +``` + + + This example shows only `PrivyProvider` configuration. For complete provider + setup including `InterwovenKitProvider`, `WagmiProvider`, + `QueryClientProvider`, and `injectStyles`, see [Provider + Setup](../setup/providers). + + +## Value + +```ts +const PRIVY_APP_ID: string +``` + +## Notes + +- Do not pass this value as your `PrivyProvider` `appId`. It is only for + referencing Initia's bundled wallet in login method configuration. +- Your own Privy app ID must be set separately as shown in the example above. diff --git a/interwovenkit/references/constants/testnet.mdx b/interwovenkit/references/constants/testnet.mdx new file mode 100644 index 0000000..b28e56b --- /dev/null +++ b/interwovenkit/references/constants/testnet.mdx @@ -0,0 +1,48 @@ +--- +title: TESTNET +--- + +## Overview + +- Configuration preset for Initia testnet with testnet registry, router, glyph, + and username services. +- Use for development or staging apps. + +## Quickstart + +```tsx +import { InterwovenKitProvider, TESTNET } from '@initia/interwovenkit-react' + +export function Providers({ children }: { children: React.ReactNode }) { + return {children} +} +``` + +## Value + +```ts +const TESTNET: { + defaultChainId: 'initiation-2' + registryUrl: 'https://registry.testnet.initia.xyz' + routerApiUrl: 'https://router-api.initiation-2.initia.xyz' + glyphUrl: 'https://glyph.initiation-2.initia.xyz' + usernamesModuleAddress: '0x42cd8467b1c86e59bf319e5664a09b6b5840bb3fac64f5ce690b5041c530565a' + theme: 'dark' + disableAnalytics: true +} +``` + +**Property descriptions:** + +- `usernamesModuleAddress`: On-chain module address of the Initia (`.init`) + username contract. This is the same for all apps using testnet and it + represents the deployed contract address that handles username lookups (e.g., + resolving `alice.init` to an address) +- `theme`: Default theme is `"dark"`, but can be overridden to `"light"` when + using the preset + +## Notes + +- Analytics are disabled by default on testnet via `disableAnalytics: true`. +- Most apps should start with `{...TESTNET}` in non‑production environments and + override only what they need. diff --git a/interwovenkit/references/errors/move-error.mdx b/interwovenkit/references/errors/move-error.mdx new file mode 100644 index 0000000..11a4ca0 --- /dev/null +++ b/interwovenkit/references/errors/move-error.mdx @@ -0,0 +1,58 @@ +--- +title: MoveError +--- + +## Overview + +- Error type that carries parsed Move VM error metadata. +- Thrown by transaction helpers on Move VM failures. +- Use `instanceof MoveError` to identify and handle Move VM errors separately. + +## Quickstart + +```tsx +import { MoveError, useInterwovenKit } from '@initia/interwovenkit-react' +import type { EncodeObject, StdFee } from '@cosmjs/stargate' + +function isMoveError(error: unknown): error is MoveError { + return error instanceof MoveError +} + +function MyComponent() { + const { submitTxBlock } = useInterwovenKit() + + const handleSubmit = async (messages: EncodeObject[], fee: StdFee) => { + try { + await submitTxBlock({ messages, fee }) + } catch (error) { + if (isMoveError(error)) { + console.error( + `Move error in ${error.moduleName} at ${error.moduleAddress}: ${error.errorCode}`, + error.originalError, + ) + } + } + } +} +``` + +## Properties + +```ts +class MoveError extends Error { + originalError: Error + moduleAddress: string + moduleName: string + errorCode: string + errorCodeHex: string + isFromRegistry: boolean +} +``` + +## Notes + +- Use `instanceof MoveError` to branch UI or logging based on Move-specific + metadata (`moduleAddress`, `moduleName`, `errorCode`). +- `originalError` contains the original error with full message and stack trace. +- `isFromRegistry` indicates whether the error message was resolved from the + Initia error registry (more user-friendly when `true`). diff --git a/interwovenkit/references/hooks/use-address.mdx b/interwovenkit/references/hooks/use-address.mdx new file mode 100644 index 0000000..6ad99a3 --- /dev/null +++ b/interwovenkit/references/hooks/use-address.mdx @@ -0,0 +1,52 @@ +--- +title: useAddress +--- + +## Overview + +- Returns the connected wallet address, adapting to the default chain's format + (hex for `minievm`, bech32 for others). +- Use when you need a single address that matches the default chain's format. + +## Prerequisites + +- Must be rendered within `InterwovenKitProvider`. +- Must be used within a React Query `QueryClientProvider`. +- Must be used within a wagmi `WagmiProvider`. +- Client-only (no SSR): Put this in a `use client` provider tree, or use a + dynamic import in Next.js. + +## Quickstart + +```tsx +'use client' + +import { useAddress } from '@initia/interwovenkit-react' + +function Address() { + const address = useAddress() + return {address || 'Not connected'} +} +``` + + + This example assumes providers are already set up. For complete setup + configurations, see [Provider Setup](../setup/providers). + + +## Return value + +```ts +function useAddress(): string +``` + +Returns a hex address when the default chain is `minievm`, or an Initia bech32 +address for other chain types. Returns an empty string when there is no +connected address. + +## Notes + +- Prefer this hook over chain-specific address hooks (`useHexAddress`, + `useInitiaAddress`) when you need a single address that automatically adapts + to the default chain's format. +- Returns hex format for `minievm` chains, bech32 format for other chain types. diff --git a/interwovenkit/references/hooks/use-hex-address.mdx b/interwovenkit/references/hooks/use-hex-address.mdx new file mode 100644 index 0000000..c83eb9d --- /dev/null +++ b/interwovenkit/references/hooks/use-hex-address.mdx @@ -0,0 +1,52 @@ +--- +title: useHexAddress +--- + +## Overview + +- Returns the connected wallet address in hex format (always hex, regardless of + chain type). +- Use when you need a hex address for EVM-style tooling or a consistent hex + format. + +## Prerequisites + +- Must be rendered within `InterwovenKitProvider`. +- Must be used within a React Query `QueryClientProvider`. +- Must be used within a wagmi `WagmiProvider`. +- Client-only (no SSR): Put this in a `use client` provider tree, or use a + dynamic import in Next.js. + +## Quickstart + +```tsx +'use client' + +import { useHexAddress } from '@initia/interwovenkit-react' + +function Address() { + const address = useHexAddress() + return {address || 'Not connected'} +} +``` + + + This example assumes providers are already set up. For complete setup + configurations, see [Provider Setup](../setup/providers). + + +## Return value + +```ts +function useHexAddress(): string +``` + +Returns the Initia account address in hex format when a wallet is connected. +Returns an empty string when there is no connected address. + +## Notes + +- Always returns hex format, unlike `useAddress` which adapts to the default + chain's format. +- Use for EVM-style integrations or when you need a consistent hex format + regardless of chain type. diff --git a/interwovenkit/references/hooks/use-initia-address.mdx b/interwovenkit/references/hooks/use-initia-address.mdx new file mode 100644 index 0000000..7e9fb42 --- /dev/null +++ b/interwovenkit/references/hooks/use-initia-address.mdx @@ -0,0 +1,52 @@ +--- +title: useInitiaAddress +--- + +## Overview + +- Returns the connected wallet address in Initia bech32 format (always bech32, + regardless of chain type). +- Use when you always need a bech32 address, regardless of the default chain + type. + +## Prerequisites + +- Must be rendered within `InterwovenKitProvider`. +- Must be used within a React Query `QueryClientProvider`. +- Must be used within a wagmi `WagmiProvider`. +- Client-only (no SSR): Put this in a `use client` provider tree, or use a + dynamic import in Next.js. + +## Quickstart + +```tsx +'use client' + +import { useInitiaAddress } from '@initia/interwovenkit-react' + +function Address() { + const address = useInitiaAddress() + return {address || 'Not connected'} +} +``` + + + This example assumes providers are already set up. For complete setup + configurations, see [Provider Setup](../setup/providers). + + +## Return value + +```ts +function useInitiaAddress(): string +``` + +Converts the connected hex wallet address into an Initia bech32 address. Returns +an empty string when there is no connected address. + +## Notes + +- Always returns bech32 format, unlike `useAddress` which adapts to the default + chain's format. +- Use for Initia-specific integrations or when you need a consistent bech32 + format regardless of chain type. diff --git a/interwovenkit/references/hooks/use-interwovenkit.mdx b/interwovenkit/references/hooks/use-interwovenkit.mdx new file mode 100644 index 0000000..329bee1 --- /dev/null +++ b/interwovenkit/references/hooks/use-interwovenkit.mdx @@ -0,0 +1,567 @@ +--- +title: useInterwovenKit +--- + +## Overview + +The `useInterwovenKit` hook provides access to wallet connection state, account +information, UI controls, transaction utilities, and AutoSign functionality for +interacting with the Initia blockchain. + + + This hook must be used within a component wrapped by `InterwovenKitProvider` + to access wallet functionality. For simple reads, prefer smaller hooks + (`useAddress`, `useUsernameQuery`) to avoid overhead. + + +## Prerequisites + +- Must be rendered within `InterwovenKitProvider`. +- Must be used within a React Query `QueryClientProvider`. +- Must be used within a wagmi `WagmiProvider`. +- Client-only (no SSR): Put this in a `use client` provider tree, or use a + dynamic import in Next.js. + +## Quickstart + +```tsx +'use client' + +import { useInterwovenKit } from '@initia/interwovenkit-react' + +function ConnectButton() { + const { isConnected, openConnect, openWallet } = useInterwovenKit() + return ( + + ) +} +``` + + + This example assumes providers are already set up. For complete setup + configurations, see [Provider Setup](../setup/providers). + + +## Account Information + +The hook provides multiple address formats and account details for the currently +connected wallet: + + + Current address in either Bech32 or hex format, depending on the configured + chain type (hex for `minievm`, bech32 for others). Returns an empty string + when not connected. + + + + Bech32-formatted Initia wallet address of the connected account. Returns an + empty string when not connected. + + + + Hex-encoded Ethereum-compatible address of the connected account. Returns an + empty string when not connected. + + + + Optional username linked to the account. Returns `null` if no username is + associated, or `undefined` before the query has produced a value. + + + + Offline signer for Cosmos transactions. + + + + Whether a wallet is currently connected. + + + + Whether the InterwovenKit drawer/modal is currently open. + + +```tsx +function AccountInfo() { + const { address, initiaAddress, hexAddress, username, isConnected } = + useInterwovenKit() + + if (!isConnected) return
Not connected
+ + return ( +
+
Address: {address}
+
Initia Address: {initiaAddress}
+
Hex Address: {hexAddress}
+ {username &&
Username: {username}
} +
+ ) +} +``` + +## UI Controls + +The hook provides methods for controlling wallet-related UI components: + + + Opens a drawer for connecting an external wallet. + + + + Opens the main wallet drawer showing balances for the connected account. + + + + Opens the bridge drawer to onboard assets with optional pre-populated values. + + + + Disconnects the current wallet connection. + + +### Bridge Form Values + +The `openBridge` method accepts optional `FormValues` to pre-populate the bridge +form: + + + Source chain ID for the bridge transaction. + + + + Source token denomination to bridge from. + + + + Destination chain ID for the bridge transaction. + + + + Destination token denomination to bridge to. + + + + Initial bridge amount (use human-readable values, e.g., "1" for 1 INIT). + + + + Sender address. + + + + Recipient address. + + + + Slippage tolerance percentage. + + + + Optional Cosmos wallet name. + + + + All bridge form values are optional. You can pre-populate any subset of fields + to improve the user experience. + + +```tsx +function BridgeButton() { + const { openBridge } = useInterwovenKit() + + return ( + + ) +} +``` + +## Transaction Methods + +The hook provides utilities for estimating, simulating, signing, and sending +transactions on the blockchain: + + + Estimates the gas required for a transaction before execution. + + + + Simulates a transaction without broadcasting, returning the transaction + result. + + + + Signs and broadcasts a transaction, returning the transaction hash immediately + without waiting for block inclusion. Shows transaction approval UI before + signing. + + + + Signs, broadcasts, and waits for block inclusion, returning the complete + transaction response. Shows transaction approval UI before signing. Defaults + to `timeoutMs: 30000` (30 seconds) and `intervalMs: 500` (0.5 seconds). + + + + Signs and broadcasts a transaction with pre-calculated fee, returning the + transaction hash immediately without waiting for block inclusion. Does not + show UI. + + + + Signs, broadcasts, and waits for block inclusion with pre-calculated fee, + returning the complete transaction response. Does not show UI. Defaults to + `timeoutMs: 30000` (30 seconds) and `intervalMs: 500` (0.5 seconds). + + + + Polls for transaction confirmation on-chain using a transaction hash. + + + + Use `requestTxSync` for better UX when you want to show immediate feedback, + then use `waitForTxConfirmation` to track the final transaction status. Use + `requestTxBlock` when you need the complete transaction result immediately. + + +### Transaction Request Interface + +The `TxRequest` interface defines parameters for transaction operations that +include gas estimation: + + + Array of encoded transaction messages to include in the transaction. + + + + Optional memo to attach to the transaction. + + + + Target chain ID for the transaction. Defaults to the provider's + `defaultChainId`. + + + + Multiplier applied to the estimated gas amount for safety margin. + + + + Explicit gas limit for the transaction. If provided, skips gas estimation. + + + + Explicit gas prices. If provided, skips the fee denomination selection UI. + + + + Coins to spend for the transaction fee. + + +### Transaction Params Interface + +The `TxParams` interface defines parameters for transactions with pre-calculated +fees: + + + Array of encoded transaction messages to include in the transaction. + + + + Optional memo to attach to the transaction. + + + + Target chain ID for the transaction. Defaults to the provider's + `defaultChainId`. + + + + Pre-calculated fee for the transaction. + + +### Transaction Confirmation Options + +The `WaitForTxOptions` interface defines parameters for tracking transaction +confirmation: + + + Hash of the transaction to track for confirmation. + + + + Chain ID where the transaction was broadcast. + + + + Maximum time in milliseconds to wait for transaction confirmation before + failing. Defaults to 30000 (30 seconds). + + + + Polling interval in milliseconds for checking transaction status. Defaults to + 500 (0.5 seconds). + + +### Transaction Examples + +```tsx +import { useInterwovenKit } from '@initia/interwovenkit-react' +import type { EncodeObject, StdFee } from '@cosmjs/stargate' + +function SendTransaction() { + const { requestTxBlock, submitTxSync, waitForTxConfirmation } = + useInterwovenKit() + + // Example: Request transaction with UI approval + const handleRequestTx = async (messages: EncodeObject[]) => { + try { + const response = await requestTxBlock({ messages }) + console.log('Transaction confirmed:', response.transactionHash) + } catch (error) { + console.error('Transaction failed:', error) + } + } + + // Example: Submit transaction directly without UI + const handleSubmitTx = async (messages: EncodeObject[], fee: StdFee) => { + try { + const txHash = await submitTxSync({ messages, fee }) + console.log('Transaction hash:', txHash) + + // Optionally wait for confirmation + const confirmed = await waitForTxConfirmation({ txHash }) + console.log('Transaction confirmed:', confirmed) + } catch (error) { + console.error('Transaction failed:', error) + } + } + + return ( +
+ + +
+ ) +} +``` + +## AutoSign + +The hook provides AutoSign state and control methods for automatic transaction +signing: + + + Expiration dates for AutoSign permissions by chain ID. + + + + Whether AutoSign is enabled for each chain. + + + + Whether AutoSign status is being loaded. + + + + Opens UI to enable AutoSign for a chain. Optionally specify a chain ID, or + defaults to the provider's `defaultChainId` if omitted. + + + + Disables AutoSign for a chain. Optionally specify a chain ID, or defaults to + the provider's `defaultChainId` if omitted. + + + + AutoSign requires Privy integration. See [AutoSign + setup](../setup/providers#autosign-setup-requires-privy) for complete AutoSign + configuration. + + +```tsx +function AutoSignControls() { + const { autoSign } = useInterwovenKit() + const chainId = 'interwoven-1' + + return ( +
+ {autoSign.isLoading ? ( +
Loading AutoSign status...
+ ) : ( + <> +
+ AutoSign enabled:{' '} + {autoSign.isEnabledByChain[chainId] ? 'Yes' : 'No'} +
+ {autoSign.expiredAtByChain[chainId] && ( +
+ Expires: {autoSign.expiredAtByChain[chainId]?.toLocaleString()} +
+ )} + + + + )} +
+ ) +} +``` + +## Notes + +- Transaction helpers throw `MoveError` on Move VM errors (see + [MoveError](../errors/move-error)). +- `requestTx*` methods show a transaction approval UI before signing. +- `submitTx*` methods sign and broadcast directly without UI. +- `waitForTxConfirmation` polls until confirmed or timeout. + +## Type reference (advanced) + +```ts +function useInterwovenKit(): InterwovenKitResult + +type InterwovenKitResult = { + address: string + initiaAddress: string + hexAddress: string + username: string | null | undefined + offlineSigner: OfflineAminoSigner + isConnected: boolean + isOpen: boolean + openConnect: () => void + openWallet: () => void + openBridge: (defaultValues?: Partial) => void + disconnect: () => void + autoSign: AutoSignState + estimateGas: ( + tx: Pick, + ) => Promise + simulateTx: ( + tx: Pick, + ) => Promise + requestTxSync: (tx: TxRequest) => Promise + requestTxBlock: ( + tx: TxRequest, + timeoutMs?: number, + intervalMs?: number, + ) => Promise + submitTxSync: (tx: TxParams) => Promise + submitTxBlock: ( + tx: TxParams, + timeoutMs?: number, + intervalMs?: number, + ) => Promise + waitForTxConfirmation: (options: WaitForTxOptions) => Promise +} + +type FormValues = { + srcChainId: string + srcDenom: string + dstChainId: string + dstDenom: string + quantity: string + sender: string + cosmosWalletName?: string + recipient: string + slippagePercent: string +} + +type TxRequest = { + messages: EncodeObject[] + memo?: string + chainId?: string + gas?: number + gasAdjustment?: number + gasPrices?: Coin[] | null + spendCoins?: Coin[] +} + +type TxParams = { + messages: EncodeObject[] + memo?: string + chainId?: string + fee: StdFee +} + +type WaitForTxOptions = { + txHash: string + chainId?: string + timeoutMs?: number + intervalMs?: number +} + +type AutoSignState = { + expiredAtByChain: Record + isEnabledByChain: Record + isLoading: boolean + enable: (chainId?: string) => Promise + disable: (chainId?: string) => Promise +} +``` + +Types `OfflineAminoSigner`, `EncodeObject`, `Coin`, `StdFee`, +`DeliverTxResponse`, and `IndexedTx` are from external packages. See +`@cosmjs/amino`, `@cosmjs/proto-signing`, `cosmjs-types`, `@cosmjs/stargate` for +details. diff --git a/interwovenkit/references/hooks/use-portfolio.mdx b/interwovenkit/references/hooks/use-portfolio.mdx new file mode 100644 index 0000000..83039ad --- /dev/null +++ b/interwovenkit/references/hooks/use-portfolio.mdx @@ -0,0 +1,126 @@ +--- +title: usePortfolio +--- + +## Overview + +- Aggregates balances, asset metadata, and prices across all chains in the + Initia registry into a single portfolio view. +- Groups assets by symbol and computes per-chain and total portfolio value. +- Tracks loading state and provides manual refetching for all underlying + queries. + +## Prerequisites + +- Must be rendered within `InterwovenKitProvider`. +- Must be used within a React Query `QueryClientProvider`. +- Must be used within a wagmi `WagmiProvider`. +- Client-only (no SSR): Put this in a `use client` provider tree, or use a + dynamic import in Next.js. + +## Quickstart + +```tsx +'use client' + +import { usePortfolio } from '@initia/interwovenkit-react' + +function PortfolioValue() { + const { totalValue, isLoading } = usePortfolio() + if (isLoading) return Loading… + return ${totalValue.toFixed(2)} +} +``` + + + This example assumes providers are already set up. For complete setup + configurations, see [Provider Setup](../setup/providers). + + +## Return value + +The hook returns an object with aggregated portfolio data, grouped assets, and +control methods: + +**Aggregated values:** + + + Estimated total USD value across all chains. + + + + List of chains sorted by portfolio value on each chain. + + +**Grouped assets:** + + + Aggregated assets grouped by symbol across chains. + + + + Assets without registry metadata, kept separate from grouped assets. + + +**Loading and control:** + + + `true` while any underlying query is loading. + + + + Manually refetches all balances, assets, and prices. + + +## Notes + +- The portfolio view only includes chains and assets that have non‑zero + balances. + +## Type reference (advanced) + +```ts +function usePortfolio(): PortfolioResult + +type PortfolioResult = { + chainsByValue: PortfolioChainItem[] + assetGroups: PortfolioAssetGroup[] + unlistedAssets: PortfolioAssetItem[] + totalValue: number + isLoading: boolean + refetch: () => void +} + +type PortfolioChainItem = { + chainId: string + name: string + logoUrl: string + value: number +} + +type PortfolioAssetGroup = { + symbol: string + logoUrl: string + assets: PortfolioAssetItem[] +} + +type PortfolioAssetItem = { + symbol: string + logoUrl: string + amount: string + denom: string + decimals: number + quantity: string + price?: number + value?: number + address?: string + unlisted?: boolean + chain: PortfolioChainInfo +} + +type PortfolioChainInfo = { + chainId: string + name: string + logoUrl: string +} +``` diff --git a/interwovenkit/references/hooks/use-username-query.mdx b/interwovenkit/references/hooks/use-username-query.mdx new file mode 100644 index 0000000..f5c3a94 --- /dev/null +++ b/interwovenkit/references/hooks/use-username-query.mdx @@ -0,0 +1,58 @@ +--- +title: useUsernameQuery +--- + +## Overview + +- React Query hook that fetches the Initia (`.init`) username for the connected + address. +- Automatically re-runs when the address changes. +- Exposes standard React Query state (`isLoading`, `error`, etc.). + +## Prerequisites + +- Must be rendered within `InterwovenKitProvider`. +- Must be used within a React Query `QueryClientProvider`. +- Must be used within a wagmi `WagmiProvider`. +- Client-only (no SSR): Put this in a `use client` provider tree, or use a + dynamic import in Next.js. + +## Quickstart + +```tsx +'use client' + +import { useUsernameQuery } from '@initia/interwovenkit-react' + +function Username() { + const { data, isLoading } = useUsernameQuery() + if (isLoading) return Loading… + return {data ?? 'No username'} +} +``` + + + This example assumes providers are already set up. For complete setup + configurations, see [Provider Setup](../setup/providers). + + +## Return value + +```ts +function useUsernameQuery(): UseQueryResult +``` + +Returns a React Query `UseQueryResult` object. The `data` +property is: + +- `string` when a username exists (ends with `.init`) +- `null` when no username exists or the address is invalid +- `undefined` before the query has produced a value or when the query is + disabled (e.g., when no address is connected) + +Type `UseQueryResult` is from `@tanstack/react-query`. + +## Notes + +- The query is disabled until a non‑empty address is available from + `useAddress()`. diff --git a/interwovenkit/references/index.mdx b/interwovenkit/references/index.mdx new file mode 100644 index 0000000..504029a --- /dev/null +++ b/interwovenkit/references/index.mdx @@ -0,0 +1,45 @@ +--- +title: Overview +--- + +The InterwovenKit React API provides components, hooks, and utilities for +integrating Initia wallet connections, transaction signing, and UI flows into +React applications. + +InterwovenKit is designed around a single provider (`InterwovenKitProvider`) +that configures network and UI behavior, with hooks layered on top for state, UI +control, and transactions. Most users start by configuring +`InterwovenKitProvider` with a preset (`MAINNET` or `TESTNET`), then use hooks +like `useInterwovenKit` or `useAddress` to read connection state and trigger UI +flows. The API is organized into: + +- **Components**: React providers and UI components (`InterwovenKitProvider`) +- **Hooks**: React hooks for connection state, transactions, and data + (`useInterwovenKit`, `useAddress`, `usePortfolio`, etc.) +- **Utilities**: Helper functions (`injectStyles`) +- **Errors**: Error types thrown by the API (`MoveError`) +- **Constants**: Configuration presets and default values (`MAINNET`, `TESTNET`, + gas constants, `PRIVY_APP_ID`) +- **Social Login**: Wagmi and RainbowKit helpers for social login + (`initiaPrivyWalletConnector`, `initiaPrivyWallet`) + +## Common starting points + +- **Provider setup**: See [Provider Setup](./setup/providers) for complete + configuration (basic setup or AutoSign with Privy) +- **Initial setup**: + [`InterwovenKitProvider`](./components/interwovenkit-provider) with + [`MAINNET`](./constants/mainnet) or [`TESTNET`](./constants/testnet) +- **Inject styles**: Call [`injectStyles`](./utilities/inject-styles) before + rendering InterwovenKit UI components +- **Read connection state**: [`useAddress`](./hooks/use-address) or + [`useInterwovenKit`](./hooks/use-interwovenkit) +- **Open UI flows**: [`useInterwovenKit`](./hooks/use-interwovenkit) + (`openConnect`, `openWallet`, `openBridge`) +- **Send transactions**: [`useInterwovenKit`](./hooks/use-interwovenkit) + (`requestTxBlock`, `submitTxBlock`) + +If you are new to InterwovenKit, start with +[`InterwovenKitProvider`](./components/interwovenkit-provider) and +[`useInterwovenKit`](./hooks/use-interwovenkit). Everything else builds on top +of those two APIs. diff --git a/interwovenkit/references/interwovenkit-provider.mdx b/interwovenkit/references/interwovenkit-provider.mdx deleted file mode 100644 index 6d04232..0000000 --- a/interwovenkit/references/interwovenkit-provider.mdx +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: InterwovenKitProvider ---- - -The `InterwovenKitProvider` is the root component that enables wallet -connectivity and transaction signing. - - - All applications using InterwovenKit must be wrapped with - `InterwovenKitProvider` at the root level to enable wallet functionality. - - -## Basic Configuration - -### Chain Connection - - - Sets the primary blockchain network that InterwovenKit uses as its default - throughout the application. This chain is used for transactions, balance - queries, appears first in asset displays, and serves as a fallback when no - specific chain is provided. - - -The `defaultChainId` parameter accepts **chain ID strings** that correspond to -chains in the [Initia registry](https://registry.initia.xyz). Common values -include: - -**Mainnet:** - -- `"interwoven-1"` - The main Initia network (default for mainnet) - -**Testnet:** - -- `"initiation-2"` - The Initia testnet (default for testnet) - - - When no `defaultChainId` is provided, the system automatically defaults to - `"interwoven-1"` (mainnet). For testnet development, use the `TESTNET` - configuration which includes `defaultChainId: "initiation-2"`. - - -```tsx -// Explicitly set to mainnet -export default function Providers() { - return ( - - {children} - - ) -} - -// Use testnet configuration (includes defaultChainId: "initiation-2") -export default function Providers() { - return {children} -} -``` - - - The `defaultChainId` affects transaction defaults, portfolio sorting, balance - queries, and bridge operations. Assets from the default chain will appear - first in lists, and all operations will use this chain unless explicitly - overridden. - - -### Custom Chain Support - - - Custom chain configuration for chains not registered in the initia-registry. - Use this when connecting to private or development chains. - - -```tsx -import { Chain } from '@initia/initia-registry-types' -import { ChainSchema } from '@initia/initia-registry-types/zod' -import { InterwovenKit } from '@initia/interwovenkit-react' - -const customChain: Chain = ChainSchema.parse({ - chain_id: 'YOUR_CHAIN_ID', - chain_name: 'YOUR_CHAIN_NAME', - apis: { - rpc: [{ address: 'YOUR_RPC_URL' }], - rest: [{ address: 'YOUR_LCD_URL' }], - }, - fees: { - fee_tokens: [{ denom: 'YOUR_FEE_DENOM', fixed_min_gas_price: 0.015 }], - }, - bech32_prefix: 'init', - network_type: 'mainnet', -}) - -export default function Providers() { - return ( - - {children} - - ) -} -``` - -### UI Theme - - - Controls the visual theme of wallet modals and components. - - -```tsx -export default function Providers() { - return {children} -} -``` - -## Advanced Configuration - -### Custom Message Types - -For applications that use custom transaction types beyond the standard Cosmos -and Initia modules, you'll need to configure protobuf types and amino -converters. - - - Protobuf message types for custom transaction signing. Only required when - using message types not included in default modules. - - -```tsx -import type { GeneratedType } from '@cosmjs/proto-signing' -import { MsgCustomAction } from './codec/myapp/tx' - -const protoTypes = [['/myapp.MsgCustomAction', MsgCustomAction]] as const - -export default function Providers() { - return ( - - {children} - - ) -} -``` - - - Amino converters for encoding/decoding custom messages. Required for - Amino-compatible messages not covered by default converters. - - -```tsx -import type { AminoConverters } from '@cosmjs/stargate' - -const aminoConverters: AminoConverters = { - '/myapp.MsgCustomAction': { - aminoType: 'myapp/MsgCustomAction', - toAmino: (msg) => ({ - creator: msg.creator, - data: msg.data, - }), - fromAmino: (amino) => ({ - creator: amino.creator, - data: amino.data, - }), - }, -} - -export default function Providers() { - return ( - - {children} - - ) -} -``` - -## Testnet Configuration - -### Infrastructure Endpoints - -The following props are automatically configured for Initia's mainnet -infrastructure and typically don't need to be set for rollup configurations: - - - URL for the chain registry service - - - - URL for the router API service - - - - Contract address for the usernames module - - -### Testnet Setup - -For testnet development, use the exported `TESTNET` constant which automatically -configures all required endpoints: - -```tsx -// providers.tsx -import { InterwovenKitProvider, TESTNET } from '@initia/interwovenkit-react' - -export default function Providers() { - return {children} -} -``` - - - The `TESTNET` constant automatically sets the correct `registryUrl`, - `routerApiUrl`, and `usernamesModuleAddress` for Initia's testnet environment. - - - - When switching between testnet and mainnet environments, clear your browser's - `localStorage` to avoid conflicts. InterwovenKit stores chain information - locally, and cached values from different networks can cause connection - errors. - diff --git a/interwovenkit/references/setup/providers.mdx b/interwovenkit/references/setup/providers.mdx new file mode 100644 index 0000000..23c42f7 --- /dev/null +++ b/interwovenkit/references/setup/providers.mdx @@ -0,0 +1,167 @@ +--- +title: Provider Setup +--- + +## Overview + +- Complete provider setup for InterwovenKit with all required dependencies. +- Two variants: basic setup (no Privy/AutoSign) and AutoSign setup (requires + Privy). +- Use the basic setup unless you need AutoSign or embedded wallet features. + +## Basic setup + +For apps that don't need AutoSign or embedded wallets. + + + This setup uses `initiaPrivyWalletConnector` as a wagmi connector option, but + does not require `PrivyProvider` at runtime. + + +```tsx +'use client' + +import { PropsWithChildren, useEffect } from 'react' +import { createConfig, http, WagmiProvider } from 'wagmi' +import { mainnet } from 'wagmi/chains' +import { QueryClient, QueryClientProvider } from '@tanstack/react-query' +import { + initiaPrivyWalletConnector, + injectStyles, + InterwovenKitProvider, + MAINNET, +} from '@initia/interwovenkit-react' +import interwovenKitStyles from '@initia/interwovenkit-react/styles.js' + +const wagmiConfig = createConfig({ + connectors: [initiaPrivyWalletConnector], + chains: [mainnet], + transports: { [mainnet.id]: http() }, +}) + +const queryClient = new QueryClient() + +export default function Providers({ children }: PropsWithChildren) { + useEffect(() => { + injectStyles(interwovenKitStyles) + }, []) + + return ( + + + {children} + + + ) +} +``` + +## AutoSign setup (requires Privy) + +For apps that need AutoSign or embedded wallet features. **Privy is required** +for AutoSign to work: + +```tsx +'use client' + +import { PropsWithChildren, useEffect } from 'react' +import { createConfig, http, WagmiProvider } from 'wagmi' +import { mainnet } from 'wagmi/chains' +import { QueryClient, QueryClientProvider } from '@tanstack/react-query' +import { + initiaPrivyWalletConnector, + injectStyles, + InterwovenKitProvider, + PRIVY_APP_ID, +} from '@initia/interwovenkit-react' +import interwovenKitStyles from '@initia/interwovenkit-react/styles.js' +import { + PrivyProvider, + useCreateWallet, + useLoginWithSiwe, + usePrivy, + useWallets, +} from '@privy-io/react-auth' + +const wagmiConfig = createConfig({ + connectors: [initiaPrivyWalletConnector], + chains: [mainnet], + transports: { [mainnet.id]: http() }, +}) + +const queryClient = new QueryClient() + +function InterwovenKitWrapper({ children }: PropsWithChildren) { + const privy = usePrivy() + const siwe = useLoginWithSiwe() + const { createWallet } = useCreateWallet() + const { wallets } = useWallets() + + return ( + + {children} + + ) +} + +export default function Providers({ children }: PropsWithChildren) { + useEffect(() => { + injectStyles(interwovenKitStyles) + }, []) + + return ( + + + + {children} + + + + ) +} +``` + +## Notes + +- Call `injectStyles()` once at app startup to avoid duplicate style tags. +- Privy is **required** for AutoSign. AutoSign will not work without + `PrivyProvider` and `privyContext`. +- Replace `YOUR_PRIVY_APP_ID` with your own Privy app ID. This is distinct from + the imported `PRIVY_APP_ID` (which is Initia's shared Privy app ID). +- The `privyContext` prop must be passed from within a component that has access + to Privy hooks (`usePrivy`, `useLoginWithSiwe`, `useCreateWallet`, + `useWallets`). +- **`enableAutoSign` configuration**: + - **Boolean (`true`)**: Enables AutoSign with default message types based on + chain type: + - `minievm`: `/minievm.evm.v1.MsgCall` + - `miniwasm`: `/cosmwasm.wasm.v1.MsgExecuteContract` + - `default`: `/initia.move.v1.MsgExecute` + - **Record (`Record`)**: Per-chain allowlist of specific + message type URLs. Use this to control exactly which message types can be + auto-signed (e.g., `MsgSend`, `MsgDelegate`, `MsgExecute`). +- **Config vs runtime**: Both setups use `initiaPrivyWalletConnector` in wagmi + config (config-time), but only the AutoSign setup requires `PrivyProvider` at + runtime. The connector itself does not require Privy runtime unless you need + AutoSign or embedded wallet features. diff --git a/interwovenkit/references/social-login/initia-privy-wallet-connector.mdx b/interwovenkit/references/social-login/initia-privy-wallet-connector.mdx new file mode 100644 index 0000000..0cae232 --- /dev/null +++ b/interwovenkit/references/social-login/initia-privy-wallet-connector.mdx @@ -0,0 +1,60 @@ +--- +title: initiaPrivyWalletConnector +--- + +## Overview + +- Wagmi connector that enables social login (email, Google, X) in your wagmi + connector list. +- Social logins only. Does not require `PrivyProvider`. + +## Prerequisites + +- Must be used with wagmi `createConfig`. +- If you need AutoSign or embedded wallet features, use + `initiaPrivyWalletConnector` with `PrivyProvider` (see + [Provider Setup](../setup/providers)). + +## Quickstart + +```tsx +'use client' + +import { PropsWithChildren } from 'react' +import { QueryClient, QueryClientProvider } from '@tanstack/react-query' +import { createConfig, http, WagmiProvider } from 'wagmi' +import { mainnet } from 'wagmi/chains' +import { initiaPrivyWalletConnector } from '@initia/interwovenkit-react' + +const wagmiConfig = createConfig({ + connectors: [ + initiaPrivyWalletConnector, // Social logins - shows as "Connect Socials" + ], + chains: [mainnet], + transports: { [mainnet.id]: http() }, +}) + +const queryClient = new QueryClient() + +export function Providers({ children }: PropsWithChildren) { + return ( + + {children} + + ) +} +``` + +## Return value + +```ts +const initiaPrivyWalletConnector: Connector +``` + +Type `Connector` is from `wagmi`. + +## Notes + +- Enables social login options without requiring `PrivyProvider`. +- Use alongside other wagmi connectors (MetaMask, WalletConnect, etc.). +- Display name: "Connect Socials". diff --git a/interwovenkit/references/social-login/initia-privy-wallet.mdx b/interwovenkit/references/social-login/initia-privy-wallet.mdx new file mode 100644 index 0000000..de25e87 --- /dev/null +++ b/interwovenkit/references/social-login/initia-privy-wallet.mdx @@ -0,0 +1,74 @@ +--- +title: initiaPrivyWallet +--- + +## Overview + +- RainbowKit wallet that enables social login (email, Google, X) in your + RainbowKit wallets list. +- Social logins only. Does not require `PrivyProvider`. + +## Prerequisites + +- Must be used with RainbowKit `getDefaultConfig` or `createConfig`. +- If you need AutoSign or embedded wallet features, use `initiaPrivyWallet` with + `PrivyProvider` (see [Provider Setup](../setup/providers)). + +## Quickstart + +```tsx +'use client' + +import { PropsWithChildren } from 'react' +import { QueryClient, QueryClientProvider } from '@tanstack/react-query' +import { WagmiProvider } from 'wagmi' +import { mainnet } from 'wagmi/chains' +import { getDefaultConfig, RainbowKitProvider } from '@rainbow-me/rainbowkit' +import { metaMaskWallet } from '@rainbow-me/rainbowkit/wallets' +import { initiaPrivyWallet } from '@initia/interwovenkit-react' +import '@rainbow-me/rainbowkit/styles.css' + +const projectId = 'YOUR_WALLETCONNECT_PROJECT_ID' // Required: Get from https://cloud.walletconnect.com + +const rainbowConfig = getDefaultConfig({ + appName: 'My dApp', + projectId, + chains: [mainnet], + wallets: [ + { + groupName: 'Social', + wallets: [initiaPrivyWallet], // Social logins - shows as "Socials" + }, + { + groupName: 'Popular', + wallets: [(params) => metaMaskWallet({ ...params, projectId })], // External wallets + }, + ], +}) + +const queryClient = new QueryClient() + +export function Providers({ children }: PropsWithChildren) { + return ( + + + {children} + + + ) +} +``` + +## Return value + +```ts +const initiaPrivyWallet: Wallet +``` + +Type `Wallet` is from `@rainbow-me/rainbowkit`. + +## Notes + +- Enables social login options without requiring `PrivyProvider`. +- Use alongside other RainbowKit wallets (MetaMask, WalletConnect, etc.). +- Display name: "Socials". diff --git a/interwovenkit/references/useinterwovenkit.mdx b/interwovenkit/references/useinterwovenkit.mdx deleted file mode 100644 index 7cf05be..0000000 --- a/interwovenkit/references/useinterwovenkit.mdx +++ /dev/null @@ -1,263 +0,0 @@ ---- -title: useInterwovenKit ---- - -The `useInterwovenKit` hook provides access to wallet connection state, account -information, UI controls, and transaction utilities for interacting with the -Initia blockchain. - - - This hook must be used within a component wrapped by `InterwovenKitProvider` - to access wallet functionality. - - -## Account Information - -The hook provides multiple address formats and account details for the currently -connected wallet: - - - Current address in either Bech32 or hex format, depending on the configured - `minitia` type. - - - - Bech32-formatted Initia wallet address of the connected account. - - - - Hex-encoded Ethereum-compatible address of the connected account. - - - - Optional username linked to the account. Returns `null` if no username is - associated. - - -```tsx -export default function Home() { - const { address, initiaAddress, hexAddress, username } = useInterwovenKit() - - return ( - <> -
{address}
-
{initiaAddress}
-
{hexAddress}
-
{username}
- - ) -} -``` - -## UI Controls - -The hook provides methods for controlling wallet-related UI components: - - - Opens a drawer for connecting an external wallet. - - - - Opens the main wallet drawer showing balances for the connected account. - - - - Opens the bridge drawer to onboard assets with optional pre-populated values. - - -### Bridge Form Interface - -The `BridgeFormValues` interface defines the optional parameters for -pre-populating the bridge form: - - - Source chain ID for the bridge transaction. - - - - Source token denomination to bridge from. - - - - Destination chain ID for the bridge transaction. - - - - Destination token denomination to bridge to. - - - - Initial bridge amount as entered by the user. Use human-readable values (e.g., - "1" for 1 INIT, not "1000000"). - - - - All bridge form values are optional. You can pre-populate any subset of fields - to improve the user experience. - - -```tsx -interface BridgeFormValues { - srcChainId?: string - srcDenom?: string - dstChainId?: string - dstDenom?: string - quantity?: string -} -``` - -### Example Usage - -```tsx -export default function Home() { - const { openConnect, openWallet, openBridge } = useInterwovenKit() - - return ( - <> - - - - - ) -} -``` - -## Transaction Methods - -The hook provides utilities for estimating, signing, and sending transactions on -the blockchain: - - - Estimates the gas required for a transaction before execution. - - - - Signs, broadcasts, and waits for block inclusion, returning the complete - transaction response. - - - - Signs and broadcasts a transaction, returning the transaction hash immediately - without waiting for block inclusion. - - - - Signs, broadcasts, and waits for block inclusion with pre-calculated fee, - returning the complete transaction response. - - - - Signs and broadcasts a transaction with pre-calculated fee, returning the - transaction hash immediately without waiting for block inclusion. - - - - Polls for transaction confirmation on-chain using a transaction hash. - - - - Use `requestTxSync` for better UX when you want to show immediate feedback, - then use `waitForTxConfirmation` to track the final transaction status. Use - `requestTxBlock` when you need the complete transaction result immediately. - - -### Transaction Request Interface - -The `TxRequest` interface defines the parameters for transaction operations: - - - Array of encoded transaction messages to include in the transaction. - - - - Optional memo to attach to the transaction. - - - - Target chain ID for the transaction. Defaults to the provider's - `defaultChainId`. - - - - Multiplier applied to the estimated gas amount for safety margin. - - - - Explicit gas limit for the transaction. If provided, skips gas estimation. - - - - Explicit fee for the transaction. If provided, skips the fee denomination - selection UI. - - -### Transaction Query Interface - -The `TxQuery` interface defines parameters for tracking transaction -confirmation: - - - Hash of the transaction to track for confirmation. - - - - Chain ID where the transaction was broadcast. - - - - Maximum time to wait for transaction confirmation before failing. - - - - Polling interval in seconds for checking transaction status. - - -### Type Definitions - -```tsx -import type { EncodeObject } from '@cosmjs/proto-signing' -import type { DeliverTxResponse, IndexedTx } from '@cosmjs/stargate' - -interface TxRequest { - messages: EncodeObject[] - memo?: string - chainId?: string - gasAdjustment?: number - gas?: number - fee?: StdFee | null -} - -interface TxQuery { - txHash: string - chainId?: string - timeoutSeconds?: number - intervalSeconds?: number -} -``` diff --git a/interwovenkit/references/utilities/inject-styles.mdx b/interwovenkit/references/utilities/inject-styles.mdx new file mode 100644 index 0000000..5b117d1 --- /dev/null +++ b/interwovenkit/references/utilities/inject-styles.mdx @@ -0,0 +1,73 @@ +--- +title: injectStyles +--- + +## Overview + +- Injects CSS into InterwovenKit's Shadow DOM by appending a `