@initia/interwovenkit-react 2.0.0-rc.4 → 2.0.0-rc.6

package/README.md

@@ -1,217 +1,191 @@
 # @initia/interwovenkit-react
 
-`@initia/interwovenkit-react` is a React SDK that provides hooks and components to integrate Initia blockchain wallet connection, bridge functionality, and transaction signing into your React applications.
+InterwovenKit is a React library that provides components and hooks to connect dApps to Initia and Interwoven Rollups.
 
-## Simple Example
+## Table of Contents
 
-Below is a minimal example to demonstrate core capabilities: connecting a wallet, opening the wallet drawer, opening the bridge drawer, and sending a transaction.
+- [Features](#features)
+- [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [Configure Providers](#configure-providers)
+  - [Basic Example](#basic-example)
+- [Usage on Testnet](#usage-on-testnet)
+- [Migrating From v1](#migrating-from-v1)
 
-```tsx
-import { MsgSend } from "cosmjs-types/cosmos/bank/v1beta1/tx"
-import { truncate, useAddress, useInterwovenKit } from "@initia/interwovenkit-react"
+## Features
 
-const Example = () => {
-  const address = useAddress()
-  const { username, openConnect, openWallet, openBridge, requestTxBlock } = useInterwovenKit()
+### Connect
 
-  if (!address) {
-    return <button onClick={openConnect}>Connect</button>
-  }
-
-  const send = async () => {
-    const messages = [
-      {
-        typeUrl: "/cosmos.bank.v1beta1.MsgSend",
-        value: MsgSend.fromPartial({
-          fromAddress: address,
-          toAddress: address,
-          amount: [{ amount: "1000000", denom: "uinit" }],
-        }),
-      },
-    ]
+Connect to external wallets. Supports multiple wallet providers including MetaMask and Keplr.
 
-    const { transactionHash } = await requestTxBlock({ messages })
-    console.log(transactionHash)
-  }
+### Wallet
 
-  return (
-    <>
-      <header>
-        <button
-          onClick={() =>
-            openBridge({
-              srcChainId: "interwoven-1",
-              srcDenom: "ibc/6490A7EAB61059BFC1CDDEB05917DD70BDF3A611654162A1A47DB930D40D8AF4",
-              dstChainId: "interwoven-1",
-              dstDenom: "uinit",
-            })
-          }
-        >
-          Bridge
-        </button>
-
-        <button onClick={openWallet}>{truncate(username ?? address)}</button>
-      </header>
-
-      <main>
-        <button onClick={send}>Send</button>
-      </main>
-    </>
-  )
-}
-```
+Wallet interface for managing assets across Interwoven rollups:
 
-## Getting Started
+- View fungible tokens
+- Browse NFT items
+- Track transaction history
 
-### Install Dependencies
+### Bridge
 
-Install the core package and required peer dependencies:
+Cross-chain bridge and swap functionality:
 
-```bash
-pnpm add @initia/interwovenkit-react
-```
+- Transfer assets between Initia and Interwoven rollups
+- Swap tokens within and across chains
+- Automatic route optimization for best rates
+- Support for OP Bridge withdrawals
 
-### Provider Setup
+### Transaction Signing
 
-You must install a wallet connector to inject a wallet into the app.
+Transaction handling with detailed preview:
 
-```bash
-pnpm add @tanstack/react-query wagmi
-```
+- Fee estimation with multiple fee token options
+- Transaction simulation before signing
+- Detailed message breakdown
 
-⚠️ Refer to the examples below.
+## Getting Started
 
-- **Vite**: [examples/vite/src/Providers.tsx](https://github.com/initia-labs/interwovenkit/blob/main/examples/vite/src/Providers.tsx)
-- **Next.js**: [examples/nextjs/src/app/providers.tsx](https://github.com/initia-labs/interwovenkit/blob/main/examples/nextjs/src/app/providers.tsx)
+### Installation
 
-```tsx
-import { InterwovenKit } from "@initia/interwovenkit-react"
+Install `@initia/interwovenkit-react` along with its peer dependencies:
 
-const App = () => {
-  return <InterwovenKit defaultChainId="YOUR_CHAIN_ID">{/* YOUR APP HERE */}</InterwovenKit>
-}
+```bash
+pnpm add @initia/interwovenkit-react wagmi viem @tanstack/react-query
 ```
 
-**Using a custom chain configuration:**
+### Configure Providers
+
+Wrap your app with providers:
 
 ```tsx
-import { ChainSchema } from "@initia/initia-registry-types/zod"
-import { InterwovenKit } from "@initia/interwovenkit-react"
-
-const customChain = 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",
+// providers.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,
+} 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(() => {
+    // Inject styles into the shadow DOM used by Initia Wallet
+    injectStyles(InterwovenKitStyles)
+  }, [])
 
-const App = () => {
   return (
-    <InterwovenKit defaultChainId="YOUR_CHAIN_ID" customChain={customChain}>
-      {/* YOUR APP HERE */}
-    </InterwovenKit>
+    <QueryClientProvider client={queryClient}>
+      <WagmiProvider config={wagmiConfig}>
+        <InterwovenKitProvider defaultChainId="YOUR_CHAIN_ID">{children}</InterwovenKitProvider>
+      </WagmiProvider>
+    </QueryClientProvider>
   )
 }
 ```
 
-## Configuration Interface
-
-```ts
-interface Config {
-  /** Wallet integration interface. */
-  wallet?: {
-    meta: { icon?: string; name: string }
-    address: string
-    getEthereumProvider: () => Promise<Eip1193Provider>
-    sign: (message: string) => Promise<string>
-    disconnect: () => void
-  }
-
-  /** The default chain ID for wallet connection (registered in initia-registry). Defaults to "interwoven-1". */
-  defaultChainId?: string
-
-  /** Custom chain configuration when your chain is not registered in initia-registry. */
-  customChain?: Chain
-
-  /** Protobuf message types for custom transaction signing. */
-  protoTypes?: Iterable<[string, GeneratedType]>
+Then wrap your application root:
 
-  /** Amino converters for encoding/decoding custom messages. */
-  aminoConverters?: AminoConverters
+```tsx
+// layout.tsx
+import Providers from "./providers"
 
-  /** UI theme preference: "light" or "dark". */
-  theme?: "light" | "dark"
+export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
 }
 ```
 
-## React Hooks API
-
-### `useInterwovenKit()`
+### Basic Example
 
-Provides core package state and actions:
+Connect the wallet, check the balance, and send a transaction:
 
-```ts
-interface UseInterwovenKitResult {
-  /** Resolves to either the bech32 or hex address based on the current `minitia` type. */
-  address: string
-
-  /** Bech32-formatted Initia wallet address of the connected account. */
-  initiaAddress: string
-
-  /** Hex-encoded Ethereum-compatible address of the connected account. */
-  hexAddress: string
+```tsx
+// page.tsx
+"use client"
 
-  /** Optional username associated with the account. */
-  username?: string | null
+import { MsgSend } from "cosmjs-types/cosmos/bank/v1beta1/tx"
+import { truncate } from "@initia/utils"
+import { useInterwovenKit } from "@initia/interwovenkit-react"
+
+export default function Home() {
+  const {
+    address,
+    username,
+    openConnect,
+    openWallet,
+    openBridge,
+    requestTxSync,
+    waitForTxConfirmation,
+  } = useInterwovenKit()
 
-  /** Opens the wallet drawer UI. */
-  openWallet(): void
+  const send = async () => {
+    const messages = [
+      {
+        typeUrl: "/cosmos.bank.v1beta1.MsgSend",
+        value: MsgSend.fromPartial({
+          fromAddress: address,
+          toAddress: address,
+          amount: [{ amount: "1000000", denom: "uinit" }],
+        }),
+      },
+    ]
 
-  /** Opens the bridge drawer UI. */
-  openBridge(defaultValues: Partial<FormValues>): void
+    const transactionHash = await requestTxSync({ messages })
+    console.log("Transaction sent:", transactionHash)
 
-  /** Estimates gas required for a transaction. */
-  estimateGas(txRequest: TxRequest): Promise<number>
+    await waitForTxConfirmation({ txHash: transactionHash })
+    console.log("Transaction confirmed:", transactionHash)
+  }
 
-  /** Signs and broadcasts a transaction, waits for block inclusion, and returns the full transaction response. */
-  requestTxBlock(txRequest: TxRequest): Promise<DeliverTxResponse>
+  const ETH = "move/edfcddacac79ab86737a1e9e65805066d8be286a37cb94f4884b892b0e39f954"
+  const USDC = "ibc/6490A7EAB61059BFC1CDDEB05917DD70BDF3A611654162A1A47DB930D40D8AF4"
 
-  /** Signs and broadcasts a transaction and returns the transaction hash immediately. */
-  requestTxSync(txRequest: TxRequest): Promise<string>
+  const bridgeTransferDetails = {
+    srcChainId: "interwoven-1",
+    srcDenom: ETH,
+    dstChainId: "interwoven-1",
+    dstDenom: USDC,
+  }
 
-  /** Waits for a transaction to be confirmed on-chain. */
-  waitForTxConfirmation(params: {
-    txHash: string
-    chainId?: string
-    timeoutSeconds?: number
-    intervalSeconds?: number
-  }): Promise<IndexedTx>
-}
+  if (!address) {
+    return <button onClick={openConnect}>Connect</button>
+  }
 
-interface TxRequest {
-  messages: EncodeObject[]
-  memo?: string
-  chainId?: string
-  gasAdjustment?: number
-  gas?: number
-  fee?: StdFee | null
+  return (
+    <>
+      <button onClick={send}>Send</button>
+      <button onClick={() => openBridge(bridgeTransferDetails)}>Bridge</button>
+      <button onClick={openWallet}>{truncate(username ?? address)}</button>
+    </>
+  )
 }
 ```
 
 ## Usage on Testnet
 
 ```tsx
-import { InterwovenKit, TESTNET } from "@initia/interwovenkit-react"
+import type { PropsWithChildren } from "react"
+import { InterwovenKitProvider, TESTNET } from "@initia/interwovenkit-react"
 
-const App = () => {
-  return <InterwovenKit {...TESTNET}>{/* YOUR APP HERE */}</InterwovenKit>
+export default function Providers({ children }: PropsWithChildren) {
+  return <InterwovenKitProvider {...TESTNET}>{children}</InterwovenKitProvider>
 }
 ```