Skip to content

Commit c3c9680

Browse files
marslavishmarslavish
authored
Merge pull request #6 from hyperweb-io/feat/cosmos-kit-migration-tool
feat: cosmos kit migration tool
2 parents 2dc69c2 + 644d53a commit c3c9680

File tree

3 files changed

+450
-0
lines changed

3 files changed

+450
-0
lines changed

‎src/index.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import { registerStarshipConfigGenTool } from './starship/tools/starship-config-
1212
import { registerStarshipSetupTool } from './starship/tools/starship-setup.js';
1313
import { registerUseChainRegistryTool } from './chain-registry/tools/use-chain-registry.js';
1414
import { registerUseInterchainKitTool } from './interchain-kit/tools/use-interchain-kit.js';
15+
import { registerMigrateFromCosmosKitToInterchainKitTool } from './interchain-kit/tools/migrate-from-cosmos-kit-to-interchain-kit.js';
1516

1617
// Get package.json version
1718
const __filename = fileURLToPath(import.meta.url);
@@ -41,6 +42,9 @@ async function main() {
4142
// Interchain Kit
4243
registerUseInterchainKitTool(server);
4344

45+
// Cosmos Kit to Interchain Kit Migration
46+
registerMigrateFromCosmosKitToInterchainKitTool(server);
47+
4448
const transport = new StdioServerTransport();
4549
await server.connect(transport);
4650
console.log('Hyperweb Agentic Tools MCP server started on stdio');

‎src/interchain-kit/prompts/cosmos-kit-to-interchain-kit-migration.md

Lines changed: 378 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,378 @@
1+
# CosmosKit to InterchainKit Migration Guide
2+
3+
## Persona
4+
5+
You are an expert React/TypeScript developer experienced in building decentralized applications (dApps) on the Cosmos ecosystem. You are familiar with wallet connection libraries like CosmosKit and are looking to migrate to the newer InterchainKit.
6+
7+
## Objective
8+
9+
Migrate a React application currently using `CosmosKit` (v2) for wallet connections and interactions to its functional equivalent using the beta version of `InterchainKit`. This involves updating package dependencies, replacing the provider component, migrating hooks, and adjusting configuration.
10+
11+
## Key Differences & API Mappings
12+
13+
| Feature | CosmosKit (`@cosmos-kit/react` or `react-lite`) | InterchainKit (Beta) (`@interchain-kit/react`) | Notes |
14+
| :--------------- | :-------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
15+
| **Core Package** | `@cosmos-kit/react` or `@cosmos-kit/react-lite` | `@interchain-kit/react` | Main React integration package. |
16+
| **Provider** | `ChainProvider` | `InterchainProvider` | Wraps the application to provide context. |
17+
| **Chains Data** | `chains` from `chain-registry` | `chains` from `chain-registry` | Same source, passed as prop. |
18+
| **Assets Data** | `assetLists` from `chain-registry` | `assets` from `@chain-registry/client` | Different source package (`@chain-registry/client` likely needed). Passed as `assetLists` prop. |
19+
| **Wallets** | `wallets` array (e.g., `import { wallets } from '@cosmos-kit/keplr'`) | `wallets` array (e.g., `import { KeplrWallet } from '@interchain-kit/keplr'`) | Wallet imports come from different packages (e.g., `@interchain-kit/keplr`). Structure seems similar. |
20+
| **Connect Hook** | `useChain(chainName)` returns `connect`, `disconnect`, `status`, `address`, `username`, `wallet`, etc. | `useConnectModal()`, `useConnect()`, `useDisconnect()`, `useWallet()` | Functionality split into multiple hooks. `useWallet()` provides connection status and address. |
21+
| **Manager Hook** | `useManager()` | `useWalletManager()` | Provides access to wallet management state and actions. |
22+
| **Client Hook** | `useWalletClient()` | `useSigningCosmWasmClient()`, `useStargateClient()` | Hooks for getting specific CosmJS clients. |
23+
| **Modal** | Default modal in `@cosmos-kit/react`, customizable via `walletModal` / `modalViews`. `@cosmos-kit/react-lite` has no modal. | Default modal provided. Customization options might differ (check InterchainKit docs for details). | InterchainKit seems to bundle a default modal experience. |
24+
| **Styling** | `@interchain-ui/react/styles` | `@interchain-kit/react/styles` | Import path for necessary base styles. |
25+
26+
## Missing or Different Features in InterchainKit (Beta)
27+
28+
InterchainKit is currently in Beta, and while it aims to provide a modern alternative to CosmosKit, some features might be missing, implemented differently, or less mature:
29+
30+
1. **Fewer Hooks:** InterchainKit appears to have a more focused set of hooks compared to CosmosKit's broader range (`useChains`, `useChainWallet`, `useIframe`, `useModalTheme`, `useNameService`). Functionality might be consolidated or require different approaches.
31+
2. **Name Service (`useNameService`):** There is no direct equivalent mentioned in the InterchainKit Beta documentation. Name service resolution might need manual implementation or rely on other libraries.
32+
3. **Wallet Support:** While key wallets like Keplr are supported, the _range_ of wallets integrated might be smaller than CosmosKit's extensive list during the Beta phase. Verify if all wallets used in your project are available for InterchainKit.
33+
4. **Modal Customization:** The exact mechanisms and extent of modal customization (`walletModal`, `modalViews` equivalents) in InterchainKit might differ from CosmosKit. Review InterchainKit documentation for customization capabilities.
34+
5. **`useChain` Hook Equivalent:** The `useChain(chainName)` hook in CosmosKit provides a convenient, chain-specific context. InterchainKit seems to rely on more general hooks (`useWallet`, `useConnect`, etc.) combined with the chain name or ID where needed. Managing state for multiple connected chains might require a different pattern.
35+
6. **Advanced Configuration:** Options available in CosmosKit's `ChainProvider` (like `sessionOptions`, `signerOptions`, `endpointOptions`, `walletConnectOptions`, `modalOptions`) may have different names, structures, or might not all be present in InterchainKit's `InterchainProvider`. Check the `InterchainProvider` props documentation carefully.
36+
7. **WalletConnect Integration:** Specific details and configuration options (`walletConnectOptions`) for WalletConnect might differ.
37+
38+
## Migration Steps
39+
40+
### Step 1: Update Dependencies
41+
42+
1. **Remove CosmosKit Packages:**
43+
Identify all `@cosmos-kit/*` packages and `chain-registry` in your `package.json`.
44+
45+
```bash
46+
# Example using yarn (adapt for npm/pnpm)
47+
yarn remove @cosmos-kit/react @cosmos-kit/keplr @cosmos-kit/core chain-registry # ... other cosmos-kit wallets
48+
```
49+
50+
2. **Install InterchainKit Packages:**
51+
Install the core InterchainKit package, necessary wallet packages, and the new assets package.
52+
```bash
53+
# Example using yarn (adapt for npm/pnpm)
54+
yarn add @interchain-kit/react @interchain-kit/keplr @chain-registry/client # ... other interchain-kit wallets
55+
```
56+
_Note: You will likely still need `chain-registry` for the `chains` data._ Check if InterchainKit re-exports it or if you need to add it back. Assume `chain-registry` is needed for now.\*
57+
```bash
58+
# Example using yarn (adapt for npm/pnpm)
59+
yarn add chain-registry
60+
```
61+
62+
### Step 2: Update Provider Setup
63+
64+
Locate the file where `ChainProvider` is used (often `_app.tsx` or `main.tsx`).
65+
66+
**CosmosKit:**
67+
68+
```typescript
69+
import { ChainProvider } from '@cosmos-kit/react';
70+
import { chains, assets as assetLists } from 'chain-registry'; // Asset import might vary
71+
import { wallets as keplrWallets } from '@cosmos-kit/keplr';
72+
// ... other wallet imports
73+
74+
// Import styles
75+
import '@interchain-ui/react/styles';
76+
77+
function App() {
78+
return (
79+
<ChainProvider
80+
chains={chains}
81+
assetLists={assetLists} // Or however assets were previously sourced
82+
wallets={[...keplrWallets /* ... other wallets */]}
83+
// ... other options like walletConnectOptions, signerOptions etc.
84+
>
85+
{/* Rest of the app */}
86+
</ChainProvider>
87+
);
88+
}
89+
```
90+
91+
**InterchainKit:**
92+
93+
```typescript
94+
import { InterchainProvider } from '@interchain-kit/react';
95+
import { chains } from 'chain-registry';
96+
import { assets as assetLists } from '@chain-registry/client'; // Updated assets import
97+
import { KeplrWallet } from '@interchain-kit/keplr'; // Updated wallet import
98+
// ... other wallet imports
99+
100+
// Import styles
101+
import '@interchain-kit/react/styles'; // Updated style import
102+
103+
function App() {
104+
return (
105+
<InterchainProvider
106+
chains={chains}
107+
assetLists={assetLists}
108+
wallets={[new KeplrWallet(/* options */) /* ... other wallets */]}
109+
// ... map relevant CosmosKit options to InterchainProvider props if available
110+
>
111+
{/* Rest of the app */}
112+
</InterchainProvider>
113+
);
114+
}
115+
```
116+
117+
_Key Changes:_ - Replace `ChainProvider` with `InterchainProvider`. - Update import paths for styles, assets (`@chain-registry/client`), and wallets (`@interchain-kit/*`). - Wallet instances might need explicit instantiation (`new KeplrWallet()`). - Review and map `ChainProvider` props (`walletConnectOptions`, `signerOptions`, etc.) to their corresponding props in `InterchainProvider` if they exist. Consult InterchainKit documentation for available props.
118+
119+
### Step 3: Migrate Hooks
120+
121+
Search your codebase for hooks imported from `@cosmos-kit/react` or `@cosmos-kit/react-lite`.
122+
123+
**Example: Migrating Connection Logic (`useChain`)**
124+
125+
**CosmosKit:**
126+
127+
```typescript
128+
import { useChain } from '@cosmos-kit/react';
129+
130+
function WalletConnectButton({ chainName = 'cosmoshub' }) {
131+
const { connect, disconnect, status, address, username, openView } = useChain(chainName);
132+
133+
if (status === 'Connected') {
134+
return (
135+
<div>
136+
<p>Connected as {username || address}</p>
137+
<button onClick={() => disconnect()}>Disconnect</button>
138+
</div>
139+
);
140+
}
141+
142+
return <button onClick={() => connect()}>Connect Wallet</button>;
143+
// Or use openView() for modal control
144+
}
145+
```
146+
147+
**InterchainKit:**
148+
149+
```typescript
150+
import { useConnectModal, useConnect, useDisconnect, useWallet } from '@interchain-kit/react';
151+
152+
function WalletConnectButton({ chainName = 'cosmoshub' }) {
153+
const { status, address, chain } = useWallet(chainName); // Or useWallet() for default chain
154+
const { open } = useConnectModal();
155+
const { connect } = useConnect(); // Might not be needed if using modal
156+
const { disconnect } = useDisconnect();
157+
158+
if (status === 'Connected' && chain?.chain_name === chainName) {
159+
return (
160+
<div>
161+
<p>Connected: {address}</p>
162+
<button onClick={() => disconnect()}>Disconnect</button>
163+
</div>
164+
);
165+
}
166+
167+
// Preferred way: Use the modal
168+
return <button onClick={open}>Connect Wallet</button>;
169+
170+
// Alternative (direct connect, less common):
171+
// return <button onClick={() => connect(chainName)}>Connect Wallet</button>;
172+
}
173+
```
174+
175+
_Key Changes:_ - Replace `useChain` with a combination of `useWallet`, `useConnectModal`, `useConnect`, `useDisconnect`. - `useWallet` provides `status`, `address`, `chain`. Check if the connected `chain.chain_name` matches the desired one if managing multiple chains. - Use `useConnectModal().open` to trigger the connection flow. Direct `connect()` might be available but the modal is standard. - `username` might not be directly available; check `useWallet` return type.
176+
177+
**Example: Migrating Client Usage (`useWalletClient`)**
178+
179+
**CosmosKit:**
180+
181+
```typescript
182+
import { useWalletClient } from '@cosmos-kit/react';
183+
import { SigningCosmWasmClient } from '@cosmjs/cosmwasm-stargate';
184+
185+
function MyComponent({ chainName = 'osmosis' }) {
186+
const { client } = useWalletClient(chainName);
187+
188+
async function doSomething() {
189+
if (!client || !(client instanceof SigningCosmWasmClient)) {
190+
console.error('Need SigningCosmWasmClient');
191+
return;
192+
}
193+
// Use client
194+
}
195+
// ...
196+
}
197+
```
198+
199+
**InterchainKit:**
200+
201+
```typescript
202+
import { useSigningCosmWasmClient } from '@interchain-kit/react';
203+
204+
function MyComponent({ chainName = 'osmosis' }) {
205+
const { data: client } = useSigningCosmWasmClient(chainName); // Pass chainName if needed
206+
207+
async function doSomething() {
208+
if (!client) {
209+
console.error('Client not available');
210+
return;
211+
}
212+
// Use client
213+
}
214+
// ...
215+
}
216+
```
217+
218+
_Key Changes:_ - Replace `useWalletClient` with the specific client hook needed (e.g., `useSigningCosmWasmClient`, `useStargateClient`). - Access the client via the `data` property of the hook's return value.
219+
220+
**Repeat this process for all other CosmosKit hooks (`useManager`, etc.), finding their InterchainKit equivalents (`useWalletManager`, etc.) and adapting the usage.**
221+
222+
### Step 4: Review and Test
223+
224+
- Thoroughly test all wallet connection flows, disconnections, transaction signing, and querying functionalities.
225+
- Pay close attention to multi-chain interactions if your application supports them.
226+
- Verify the behavior of the connection modal.
227+
- Check for console errors or warnings.
228+
229+
## Additional InterchainKit Code Examples (React)
230+
231+
Here are some more examples demonstrating common InterchainKit patterns:
232+
233+
**1. Provider Setup with All Mainnet Chains:**
234+
235+
This shows how to easily include all mainnet chains and assets from the `@chain-registry/v2` package.
236+
237+
```typescript
238+
import { ChainProvider, useChain } from "@interchain-kit/react";
239+
import { keplrWallet } from "@interchain-kit/keplr-extension"; // Assuming keplr extension
240+
import { ThemeProvider } from "@interchain-ui/react"; // For UI components
241+
import { chains, assetLists } from '@chain-registry/v2/mainnet';
242+
243+
import "@interchain-ui/react/styles"; // Import styles
244+
245+
const DisplayAddress = () => {
246+
// Example: Get address for osmosis
247+
const { address } = useChain('osmosis');
248+
return <div>Osmosis Address: {address || \'Not Connected\'}</div>;
249+
};
250+
251+
function App() {
252+
return (
253+
<ThemeProvider>
254+
<ChainProvider
255+
chains={chains}
256+
assetLists={assetLists}
257+
wallets={[keplrWallet]} // Use the imported wallet object
258+
// Add signerOptions and endpointOptions if needed
259+
// signerOptions={{}}
260+
// endpointOptions={{}}
261+
>
262+
<DisplayAddress />
263+
{/* Add connect/disconnect buttons and other components */}
264+
</ChainProvider>
265+
</ThemeProvider>
266+
);
267+
}
268+
269+
export default App;
270+
```
271+
272+
**2. Basic `useChain` Hook Usage:**
273+
274+
Retrieve various details and functions for a specific chain.
275+
276+
```typescript
277+
import { useChain } from '@interchain-kit/react';
278+
279+
const chainName = 'cosmoshub';
280+
const {
281+
chain, // Chain info for cosmoshub
282+
assetList, // Assets info for cosmoshub
283+
address, // User's address for cosmoshub (string when connected, undefined otherwise)
284+
wallet, // Info about the connected wallet (e.g., Keplr)
285+
connect, // Function to connect the wallet
286+
disconnect, // Function to disconnect the wallet
287+
getRpcEndpoint, // Function to get RPC endpoint: () => Promise<string | HttpEndpoint>
288+
getSigningClient, // Function to get a signing client: () => Promise<SigningClient>
289+
message, // Connection status message
290+
openView, // Function to open modal views
291+
} = useChain(chainName);
292+
293+
// Example: Log address if connected
294+
if (address) {
295+
console.log(`Connected to ${chainName} with address: ${address}`);
296+
}
297+
```
298+
299+
**3. Accessing Wallet Methods:**
300+
301+
Get the wallet object via `useChain` and call its methods.
302+
303+
```typescript
304+
import { useChain } from '@interchain-kit/react';
305+
// Assuming necessary types like StdSignDoc are imported
306+
307+
async function signSomething() {
308+
const { wallet, address: signAddress, chain } = useChain('osmosis');
309+
310+
if (wallet && signAddress && chain) {
311+
try {
312+
// Example: Sign Amino (replace stdDoc with actual sign doc)
313+
// const stdDoc: StdSignDoc = { ... };
314+
// const signature = await wallet.signAmino(chain.chain_id, signAddress, stdDoc);
315+
// console.log('Amino Signature:', signature);
316+
317+
// Example: Verify Arbitrary (replace message with actual data)
318+
// const message = 'Verify this message';
319+
// const verifyResult = await wallet.verifyArbitrary(chain.chain_id, signAddress, message);
320+
// console.log('Verification Result:', verifyResult);
321+
322+
console.log('Wallet methods available.'); // Placeholder
323+
} catch (error) {
324+
console.error('Error using wallet methods:', error);
325+
}
326+
} else {
327+
console.log('Wallet not connected or details missing.');
328+
}
329+
}
330+
```
331+
332+
**4. Configuring Multiple Wallets:**
333+
334+
Set up `ChainProvider` to support multiple wallet extensions.
335+
336+
```typescript
337+
import { ChainProvider } from '@interchain-kit/react';
338+
import { chains } from 'chain-registry'; // Or specific chains
339+
import { assets as assetLists } from '@chain-registry/client';
340+
import { ThemeProvider } from '@interchain-ui/react';
341+
342+
// Import wallet integrations
343+
import { keplrExtensionInfo, keplrWallet } from '@interchain-kit/keplr-extension';
344+
import { leapWallet } from '@interchain-kit/leap-extension'; // Example
345+
346+
import '@interchain-ui/react/styles';
347+
348+
// Optionally export names for reference
349+
export const keplrWalletName = keplrExtensionInfo.name;
350+
351+
function App() {
352+
return (
353+
<ThemeProvider>
354+
<ChainProvider
355+
chains={chains} // Provide desired chains
356+
assetLists={assetLists} // Provide corresponding asset lists
357+
wallets={[
358+
keplrWallet, // Add Keplr
359+
leapWallet, // Add Leap
360+
// Add other imported wallets here
361+
]}
362+
>
363+
{/* App Components */}
364+
</ChainProvider>
365+
</ThemeProvider>
366+
);
367+
}
368+
369+
export default App;
370+
```
371+
372+
## Important Considerations
373+
374+
- **Beta Software:** InterchainKit is in Beta. Expect potential API changes, bugs, or missing features compared to the more established CosmosKit.
375+
- **UI Differences:** If you were using the default modal from `@cosmos-kit/react`, the look and feel of the InterchainKit modal will likely be different. Adjust custom UI elements accordingly.
376+
- **Error Handling:** Review how errors are exposed and handled in InterchainKit hooks compared to CosmosKit.
377+
- **State Management:** The way connection state and wallet information are managed might differ. Adapt your application's state logic if necessary.
378+
- **Documentation:** Refer frequently to the official InterchainKit (Beta) documentation for detailed API specifications, configuration options, and examples.

0 commit comments

Comments
 (0)