# Solana Wallet Adapter → Gill & Wallet-UI Migration Guide Migrate from `@solana/wallet-adapter-react` & `@solana/web3.js` v1 to `gill` & `@wallet-ui/react` > **⚠️ IMPORTANT: Wallet-UI Status** > > The `@wallet-ui/react` package is currently **🚧 Work in Progress**. While the core hooks and providers work, UI components are not yet available. This guide shows both the current API and expected future patterns. > > **Current Status:** > - ✅ **gill** - Fully stable and production-ready > - 🚧 **@wallet-ui/react** - Core functionality works, UI components in development > - 🔄 **Alternative**: Consider using gill with traditional wallet adapters during transition > **✅ TESTED & VALIDATED**: The gill examples in this guide have been tested with working scripts and validated against real Solana devnet. The wallet-ui examples reflect the current API status. This is a comprehensive guide for migrating your Solana application from the traditional wallet adapter setup to modern alternatives. If there is an API you need which is missing or cannot find, create an issue in the respective repositories. The new setup offers better tree-shaking, lighter bundle sizes, and improved developer experience. While some APIs are more verbose, they provide better clarity, composability, and type safety. > **Important Note**: This migration involves two separate transitions that can be done independently. You can migrate from web3.js v1 to gill while keeping the existing wallet adapter, or vice versa. ## Overview The migration involves two main transitions: 1. **Blockchain Client**: `@solana/web3.js` v1 → `gill` 2. **Wallet Integration**: `@solana/wallet-adapter-react` → `@wallet-ui/react` ## Package Installation ### Remove Old Dependencies ```bash npm uninstall @solana/wallet-adapter-react @solana/wallet-adapter-react-ui @solana/wallet-adapter-wallets @solana/wallet-adapter-base ``` ### Install New Dependencies ```bash npm install gill @wallet-ui/react @solana/web3.js ``` ## Connection Provider → Solana Client ### @solana/web3.js v1 Connection #### Before ```typescript import { Connection, clusterApiUrl } from '@solana/web3.js'; const connection = new Connection(clusterApiUrl('devnet'), 'confirmed'); // Usage const slot = await connection.getSlot(); const { blockhash } = await connection.getRecentBlockhash(); ``` #### After ```typescript import { createSolanaClient } from 'gill'; const { rpc, rpcSubscriptions, sendAndConfirmTransaction } = createSolanaClient({ urlOrMoniker: 'devnet', // or full RPC URL }); // Usage const slot = await rpc.getSlot().send(); const { value: latestBlockhash } = await rpc.getLatestBlockhash().send(); ``` > Gill uses an explicit `send()` method for all RPC calls and provides destructured responses for cleaner code. ### Custom RPC Endpoint #### Before ```typescript import { Connection } from '@solana/web3.js'; const connection = new Connection('https://api.devnet.solana.com', 'confirmed'); ``` #### After ```typescript import { createSolanaClient } from 'gill'; const { rpc } = createSolanaClient({ urlOrMoniker: 'https://api.devnet.solana.com', }); ``` ## Wallet Provider → Wallet-UI Provider ### Provider Setup #### Before ```typescript "use client"; import React, { FC, ReactNode, useMemo } from "react"; import { ConnectionProvider, WalletProvider, } from "@solana/wallet-adapter-react"; import { WalletAdapterNetwork } from "@solana/wallet-adapter-base"; import { WalletModalProvider } from "@solana/wallet-adapter-react-ui"; import { clusterApiUrl } from "@solana/web3.js"; import { PhantomWalletAdapter } from "@solana/wallet-adapter-wallets"; import "@solana/wallet-adapter-react-ui/styles.css"; interface SolanaProviderProps { children: ReactNode; } export const SolanaProvider: FC = ({ children }) => { const network = WalletAdapterNetwork.Devnet; const endpoint = useMemo(() => clusterApiUrl(network), [network]); const wallets = useMemo(() => [new PhantomWalletAdapter()], []); return ( {children} ); }; ``` #### After (Current API - Work in Progress) ```typescript "use client"; import React, { FC, ReactNode } from "react"; import { WalletUi, createWalletUiConfig, createSolanaDevnet, createSolanaLocalnet, createSolanaMainnet } from "@wallet-ui/react"; import "@wallet-ui/tailwind/index.css"; // 🚨 CRITICAL: Required for component styling interface SolanaProviderProps { children: ReactNode; } export const SolanaProvider: FC = ({ children }) => { const config = createWalletUiConfig({ clusters: [ createSolanaDevnet(), createSolanaLocalnet(), // For local development createSolanaMainnet(), ], }); return ( {children} ); }; ``` > ⚠️ **Current Status**: This shows the current working API. Note that `@wallet-ui/react` is in development - UI components like dropdowns are not yet available. The core provider and hooks work for basic wallet connectivity. ### Wallet Connection Components #### Before ```typescript import { useWallet } from "@solana/wallet-adapter-react"; import { useWalletModal } from "@solana/wallet-adapter-react-ui"; export const ConnectButton = () => { const { disconnect, connected, publicKey } = useWallet(); const { setVisible } = useWalletModal(); const handleClick = () => { if (connected) { disconnect(); } else { setVisible(true); } }; return ( ); }; ``` #### After (Current API - Hooks Only) ```typescript "use client"; import { useSolanaWallet, useSolanaWalletAddress, useSolanaChain } from "@wallet-ui/react"; export const WalletInfo = () => { const [wallet, setWallet] = useSolanaWallet(); const walletAddress = useSolanaWalletAddress(); const { chain } = useSolanaChain(); return (

Network: {chain?.label || 'Unknown'}

{walletAddress ? ( Connected: {walletAddress.slice(0, 8)}... ) : ( No wallet connected )}

{/* Note: You'll need to build your own connect/disconnect UI */}

); }; ``` > ⚠️ **Current Limitation**: UI components don't exist yet. You'll need to build your own wallet connection buttons using the available hooks, or continue using traditional wallet adapters during the transition period. #### Alternative: Continue Using Wallet Adapter (Recommended for Now) Since wallet-ui doesn't have UI components yet, consider this hybrid approach: ```typescript // Keep using wallet adapter for UI, but with gill for RPC import { useWallet } from "@solana/wallet-adapter-react"; import { WalletMultiButton } from "@solana/wallet-adapter-react-ui"; import { createSolanaClient } from "gill"; export const HybridApproach = () => { const { publicKey, connected } = useWallet(); // Use gill for RPC operations const { rpc } = createSolanaClient({ urlOrMoniker: 'devnet' }); return (

{connected && publicKey && ( Connected: {publicKey.toBase58().slice(0, 8)}... )}

); }; ``` > 💡 **Recommended Strategy**: Use gill for blockchain operations (it's stable) while keeping wallet adapter for UI until wallet-ui components are ready. ## Next.js SSR Considerations ### Dynamic Imports (Recommended) For the best Next.js compatibility, we recommend dynamically importing wallet-UI components to prevent server-side rendering issues: ```typescript // ⚠️ POTENTIAL ISSUE: Direct imports may cause SSR hydration issues import { WalletUiDropdown } from "@wallet-ui/react"; // ✅ RECOMMENDED: Dynamic imports with SSR disabled export const WalletButton = dynamic( async () => (await import('@wallet-ui/react')).WalletUiDropdown, { ssr: false } ); ``` **Why dynamic imports are recommended:** - Wallet detection requires browser APIs (`window`, `navigator`) - Server-side rendering can't access these APIs - Dynamic imports ensure components only render on the client - Prevents hydration mismatches in production ### Client Component Requirements Provider components must use the `"use client"` directive: ```typescript "use client"; // Required for wallet-ui providers import { WalletUi } from "@wallet-ui/react"; import "@wallet-ui/tailwind/index.css"; // Also required for styling ``` ## Transaction Handling ### Creating and Sending Transactions #### Before ```typescript import { useWallet, useConnection } from "@solana/wallet-adapter-react"; import { Transaction, SystemProgram, PublicKey, LAMPORTS_PER_SOL } from "@solana/web3.js"; export const useTransfer = () => { const { connection } = useConnection(); const { publicKey, sendTransaction } = useWallet(); const transfer = async (to: string, amount: number) => { if (!publicKey) return; const transaction = new Transaction().add( SystemProgram.transfer({ fromPubkey: publicKey, toPubkey: new PublicKey(to), lamports: amount * LAMPORTS_PER_SOL, }) ); const { blockhash } = await connection.getRecentBlockhash(); transaction.recentBlockhash = blockhash; transaction.feePayer = publicKey; const signature = await sendTransaction(transaction, connection); return signature; }; return { transfer }; }; ``` #### After ```typescript import { useSolanaWallet, useSolanaWalletAddress, useSolanaRpc } from "@wallet-ui/react"; import { createTransaction, getSignatureFromTransaction, getExplorerLink } from "gill"; import { getTransferSolInstruction } from "gill/programs"; export const useTransfer = () => { const [wallet] = useSolanaWallet(); const walletAddress = useSolanaWalletAddress(); const { rpc, sendAndConfirmTransaction } = useSolanaRpc(); const transfer = async (to: string, amount: number) => { if (!walletAddress) return; const { value: latestBlockhash } = await rpc.getLatestBlockhash().send(); const transferInstruction = getTransferSolInstruction({ source: { address: walletAddress }, destination: { address: to }, amount: BigInt(amount * 1_000_000_000), // Convert to lamports }); const transaction = createTransaction({ version: "legacy", feePayer: { address: walletAddress }, latestBlockhash, instructions: [transferInstruction], }); // Note: Actual signing would need to be handled through the wallet const signature = await sendAndConfirmTransaction(transaction); console.log(getExplorerLink({ transaction: signature, cluster: "devnet" })); return signature; }; return { transfer }; }; ``` > ✅ **Key Improvement**: Now using `useSolanaRpc()` from wallet-ui to get the RPC client that automatically switches with the selected chain, instead of creating a new client. ## Account Information ### Fetching Account Data #### Before ```typescript import { useConnection } from "@solana/wallet-adapter-react"; import { PublicKey, LAMPORTS_PER_SOL } from "@solana/web3.js"; export const useAccountInfo = () => { const { connection } = useConnection(); const getAccountInfo = async (address: string) => { const publicKey = new PublicKey(address); const accountInfo = await connection.getAccountInfo(publicKey); return accountInfo; }; const getBalance = async (address: string) => { const publicKey = new PublicKey(address); const balance = await connection.getBalance(publicKey); return balance / LAMPORTS_PER_SOL; }; return { getAccountInfo, getBalance }; }; ``` #### After ```typescript import { useSolanaRpc } from "@wallet-ui/react"; import { address } from "gill"; export const useAccountInfo = () => { const { rpc } = useSolanaRpc(); const getAccountInfo = async (addressStr: string) => { const accountAddress = address(addressStr); const accountInfo = await rpc.getAccountInfo(accountAddress).send(); return accountInfo.value; }; const getBalance = async (addressStr: string) => { const accountAddress = address(addressStr); const balance = await rpc.getBalance(accountAddress).send(); return Number(balance.value) / 1_000_000_000; // Convert from lamports }; return { getAccountInfo, getBalance }; }; ``` > ✅ **Key Improvement**: Using the RPC client from wallet-ui context instead of creating a new one, ensuring chain switching works correctly. ## Cluster Management ### Network Switching #### Before ```typescript // Manual connection management for different networks const devnetConnection = new Connection(clusterApiUrl('devnet')); const mainnetConnection = new Connection(clusterApiUrl('mainnet-beta')); // Switching required recreating connections manually const connection = isDev ? devnetConnection : mainnetConnection; ``` #### After ```typescript import { useSolanaRpc, useSolanaChain } from "@wallet-ui/react"; import { address } from "gill"; // Note: No ClusterDropdown component available yet export const ChainInfo = () => { const { chain } = useSolanaChain(); return (

Network: {chain?.label || 'Unknown'} {/* You'll need to build your own chain switching UI */}

); }; // RPC client automatically switches with chain selection export const useNetworkAwareOperations = () => { const { rpc, sendAndConfirmTransaction } = useSolanaRpc(); const { chain } = useSolanaChain(); // RPC client automatically points to the selected chain const getBalance = async (addressStr: string) => { const accountAddress = address(addressStr); const balance = await rpc.getBalance(accountAddress).send(); return Number(balance.value) / 1_000_000_000; // Convert from lamports }; const getCurrentNetwork = () => { return { name: chain?.label || 'Unknown', endpoint: chain?.rpcUrl, chainId: chain?.id }; }; return { rpc, sendAndConfirmTransaction, getBalance, getCurrentNetwork, // All operations automatically use the selected chain! }; }; ``` > ⚠️ **Current Status**: Wallet-UI handles chain switching automatically through `useSolanaRpc()`. However, UI components for chain switching are not yet available - you'll need to build your own or use the chain configs programmatically. ## Creating Instructions ### System Transfer Instruction #### Before ```typescript import { SystemProgram, PublicKey } from "@solana/web3.js"; const transferInstruction = SystemProgram.transfer({ fromPubkey: new PublicKey(fromAddress), toPubkey: new PublicKey(toAddress), lamports: amount, }); ``` #### After ```typescript import { getTransferSolInstruction } from "gill/programs"; const transferInstruction = getTransferSolInstruction({ source: { address: fromAddress }, destination: { address: toAddress }, amount: BigInt(amount), }); ``` ### Memo Instruction #### Before ```typescript import { TransactionInstruction, PublicKey } from "@solana/web3.js"; const memoInstruction = new TransactionInstruction({ keys: [], programId: new PublicKey("MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr"), data: Buffer.from("Hello, world!", "utf8"), }); ``` #### After ```typescript import { getAddMemoInstruction } from "gill/programs"; const memoInstruction = getAddMemoInstruction({ memo: "Hello, world!", }); ``` ## Signing and Sending Transactions ### Transaction Signing #### Before ```typescript import { Transaction } from "@solana/web3.js"; // Signing was handled automatically by wallet adapter const signature = await sendTransaction(transaction, connection); ``` #### After ```typescript import { signTransactionMessageWithSigners, getSignatureFromTransaction } from "gill"; // For server-side signing with loaded keypair const signedTransaction = await signTransactionMessageWithSigners(transaction); const signature = getSignatureFromTransaction(signedTransaction); // For client-side, you can also let sendAndConfirmTransaction handle signing await sendAndConfirmTransaction(transaction); // Will partially sign automatically ``` ## Loading Keypairs (Node.js) ### From File System #### Before ```typescript import { Keypair } from "@solana/web3.js"; import fs from "fs"; const secretKey = JSON.parse(fs.readFileSync("/path/to/keypair.json", "utf8")); const keypair = Keypair.fromSecretKey(new Uint8Array(secretKey)); ``` #### After ```typescript import { loadKeypairSignerFromFile } from "gill/node"; // Default path: ~/.config/solana/id.json const signer = await loadKeypairSignerFromFile(); // Custom path const signer = await loadKeypairSignerFromFile("/path/to/keypair.json"); console.log("Address:", signer.address); ``` ## Real-World Example: Token Claim Status Hook ### Before ```typescript "use client"; import { MerkleTree } from "@/types/index"; import { useWallet } from "@solana/wallet-adapter-react"; import { Connection, PublicKey } from "@solana/web3.js"; import { useEffect, useState } from "react"; const PROGRAM_ID = new PublicKey( process.env.NEXT_PUBLIC_PROGRAM_ID || "E7HtfkEMhmn9uwL7EFNydcXBWy5WCYN1vFmKKjipEH1x" ); export const useClaimStatus = ( connection: Connection, distributorPk: PublicKey, merkleTree: MerkleTree ) => { const { publicKey } = useWallet(); const [status, setStatus] = useState< "unclaimed" | "claimed" | "ineligible" >(); useEffect(() => { if (!publicKey) return setStatus(undefined); const checkClaimStatus = async () => { const node = merkleTree.tree_nodes.find((node) => { const nodePublicKey = new PublicKey(node.claimant).toBase58(); return nodePublicKey === publicKey.toBase58(); }); if (!node) return setStatus("ineligible"); try { const [claimStatusPda] = PublicKey.findProgramAddressSync( [ Buffer.from("ClaimStatus"), publicKey.toBuffer(), distributorPk.toBuffer(), ], PROGRAM_ID ); const claimStatusAccount = await connection.getAccountInfo( claimStatusPda ); if (claimStatusAccount) { setStatus("claimed"); } else { setStatus("unclaimed"); } } catch (e) { console.log(e); setStatus("unclaimed"); } }; checkClaimStatus(); }, [publicKey, connection, distributorPk, merkleTree]); return { status }; }; ``` ### After ```typescript "use client"; import { MerkleTree } from "@/types/index"; import { useWalletUi, useWalletUiSolanaClient } from "@wallet-ui/react"; import { address } from "gill"; import { PublicKey } from "@solana/web3.js"; import { useEffect, useState } from "react"; const PROGRAM_ID = address( process.env.NEXT_PUBLIC_PROGRAM_ID || "E7HtfkEMhmn9uwL7EFNydcXBWy5WCYN1vFmKKjipEH1x" ); export const useClaimStatus = ( distributorAddress: string, merkleTree: MerkleTree ) => { const { account } = useWalletUi(); const { rpc } = useWalletUiSolanaClient(); const [status, setStatus] = useState< "unclaimed" | "claimed" | "ineligible" >(); useEffect(() => { if (!account) return setStatus(undefined); const checkClaimStatus = async () => { const node = merkleTree.tree_nodes.find((node) => { // Convert node.claimant (byte array) to base58 string for comparison const nodePublicKey = new PublicKey(node.claimant).toBase58(); return nodePublicKey === account.address; }); if (!node) return setStatus("ineligible"); try { // Hybrid approach: Use web3.js for PDA derivation, gill for RPC calls const programId = new PublicKey(process.env.NEXT_PUBLIC_PROGRAM_ID || "E7HtfkEMhmn9uwL7EFNydcXBWy5WCYN1vFmKKjipEH1x"); const userPubkey = new PublicKey(account.address); const distributorPubkey = new PublicKey(distributorAddress); // Keep PDA derivation with @solana/web3.js (works perfectly) const [claimStatusPda] = PublicKey.findProgramAddressSync( [ Buffer.from("ClaimStatus"), userPubkey.toBuffer(), distributorPubkey.toBuffer(), ], programId ); // Convert to gill address for RPC call const pdaAddress = address(claimStatusPda.toBase58()); const claimStatusAccount = await rpc.getAccountInfo(pdaAddress).send(); if (claimStatusAccount.value) { setStatus("claimed"); } else { setStatus("unclaimed"); } } catch (e) { console.log(e); setStatus("unclaimed"); } }; checkClaimStatus(); }, [account, rpc, distributorAddress, merkleTree]); return { status }; }; ``` > ✅ **Key Improvements**: > - Using `useWalletUi()` for wallet account and `useWalletUiSolanaClient()` for RPC client > - RPC client automatically switches with cluster changes > - No longer need to pass connection/RPC URL as parameters > - Cleaner dependency array in useEffect ## Complete Working Example Here's a full Next.js setup following all the patterns from this migration guide: ### 1. Provider Setup (`providers/solana-provider.tsx`) ```typescript "use client"; import React, { ReactNode } from "react"; import { WalletUi, createWalletUiConfig, createSolanaDevnet, createSolanaLocalnet, createSolanaMainnet } from "@wallet-ui/react"; import "@wallet-ui/tailwind/index.css"; interface SolanaProviderProps { children: ReactNode; } const config = createWalletUiConfig({ clusters: [ createSolanaDevnet(), createSolanaLocalnet(), createSolanaMainnet(), ], }); export const SolanaProvider: React.FC = ({ children }) => { return ( {children} ); }; ``` ### 2. Wallet Components (`components/wallet-components.tsx`) ```typescript "use client"; import dynamic from 'next/dynamic'; // Dynamic imports help avoid SSR issues (recommended for Next.js) export const WalletButton = dynamic( async () => (await import('@wallet-ui/react')).WalletUiDropdown, { ssr: false } ); export const ClusterButton = dynamic( async () => (await import('@wallet-ui/react')).WalletUiClusterDropdown, { ssr: false } ); ``` ### 3. Navigation Bar (`components/navbar.tsx`) ```typescript import { WalletButton, ClusterButton } from './wallet-components'; export const NavBar = () => { return ( ); }; ``` ### 4. Layout Setup (`app/layout.tsx`) ```typescript import { SolanaProvider } from '@/providers/solana-provider'; import { NavBar } from '@/components/navbar'; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return (

{children}

); } ``` ### 5. Using Wallet State in Components ```typescript "use client"; import { useWalletUi, useWalletUiSolanaClient, useWalletUiCluster } from "@wallet-ui/react"; import { address } from "gill"; export const WalletInfo = () => { const { account, connected } = useWalletUi(); const { rpc } = useWalletUiSolanaClient(); const { cluster } = useWalletUiCluster(); const getBalance = async () => { if (!account) return; const accountAddress = address(account.address); const balance = await rpc.getBalance(accountAddress).send(); console.log(`Balance: ${balance.value} lamports`); }; if (!connected || !account) { return

Please connect your wallet

; } return (

Connected: {account.address}

Network: {cluster.label}

); }; ``` > ✅ **This example demonstrates**: Proper provider setup, dynamic imports, cluster switching, and RPC client usage that automatically adapts to network changes. PublicKey.findProgramAddressSync() from @solana/web3.js during migration - it works perfectly with gill. Convert the result to gill address via .toBase58()." }, { id: 2, title: "Wallet Standard", description: "@wallet-ui/react uses the wallet standard for automatic wallet detection, which is different from the manual adapter approach." }, { id: 3, title: "Bundle Size", description: "You should see significant bundle size improvements with the new setup due to better tree-shaking." }, { id: 4, title: "RPC Calls", description: "All RPC calls in gill require the explicit .send() method and return structured responses with a .value property." }, { id: 5, title: "Migration Timeline", description: "These migrations can be done incrementally and independently. You can migrate the blockchain client first, then the wallet integration." }, { id: 6, title: "TypeScript", description: "The new setup provides better TypeScript support with more precise types." }, { id: 7, title: "Instruction Helpers", description: "Gill provides typed helper functions for common instructions, reducing boilerplate code." }, { id: 8, title: "RPC Client Management", description: "Always use useWalletUiSolanaClient() instead of creating new clients with createSolanaClient(). The wallet-ui RPC client automatically switches clusters when users change networks." }, { id: 9, title: "CSS Import Required", description: "You MUST import @wallet-ui/tailwind/index.css or wallet components will appear unstyled. This is different from the old wallet adapter which had separate CSS packages." }, { id: 10, title: "Next.js Dynamic Imports", description: "For Next.js applications, we recommend dynamically importing wallet components with { ssr: false } to avoid potential SSR hydration issues. While not strictly required, this prevents common client-server mismatches." } ]} /> ## Getting Help - **Gill Documentation**: [gill.site/docs](https://gill.site/docs) - **Gill Repository**: [github.com/solana-foundation/gill](https://github.com/solana-foundation/gill) - **Wallet-UI Repository**: [github.com/wallet-ui/wallet-ui](https://github.com/wallet-ui/wallet-ui) - **Solana Cookbook**: [solanacookbook.com](https://solanacookbook.com) (for general Solana patterns) This migration guide provides a comprehensive overview of moving from the traditional Solana wallet adapter setup to the modern gill and wallet-ui approach. The new setup offers better performance, smaller bundle sizes, and improved developer experience while maintaining the same core functionality. ## Validation Scripts All patterns in this guide have been tested with working scripts: - **`scripts/test-gill-rpc.ts`** - Tests basic gill RPC functionality - **`scripts/test-claim-status-gill.ts`** - Tests real-world hook migration (useClaimStatus) - **`scripts/test-pda-derivation.ts`** - Tests PDA derivation and address conversion - **`scripts/test-transaction-gill.ts`** - Tests transaction building patterns - **`components/test-wallet-ui-migration.tsx`** - Tests React component with @wallet-ui/react - **`scripts/run-all-migration-tests.ts`** - Runs complete validation suite Run the validation suite: `npx ts-node scripts/run-all-migration-tests.ts`