Wallet Provider

The WalletProvider is the core component that orchestrates all wallet interactions in your application. It must wrap your entire app (or the parts that need wallet functionality) to provide wallet state management, network selection, and account persistence.

Why WalletProvider?

The WalletProvider serves as the foundation for all wallet-related functionality:

• Multi-chain Support: Manages multiple blockchain networks (Solana, Ethereum, Sui, etc.) through a unified API
• State Management: Tracks connected wallets, accounts, and network selection
• Persistence: Automatically saves and restores wallet connections across page reloads
• Context Provision: Exposes wallet state to all child components via React Context

Installation

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @wallet-kit/provider
Copy

Initialization

The WalletProvider must be initialized with a configuration object. Use createWalletConfig to create the configuration with your networks and settings.

Basic Setup

Copyimport {
  createWalletConfig,
  WalletProvider,
} from "@/components/wallet/provider";
import { createSolanaMainnet, createSolanaDevnet } from "@/lib/chains/solana";
 
export default function App({ children }) {
  const config = createWalletConfig({
    networks: [createSolanaMainnet(), createSolanaDevnet()],
  });
 
  return <WalletProvider config={config}>{children}</WalletProvider>;
}

Advanced Setup with Plugin Architecture

Copyimport { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import {
  createWalletConfig,
  WalletProvider,
} from "@/components/wallet/provider";
import { createStorageAccount, createStorageNetwork } from "@/lib/chains/storage";
import { createSolanaMainnet, createSolanaDevnet, createSolanaTestnet } from "@/lib/chains/solana";
import { SolanaWalletProvider } from "@/lib/chains/solana/adapter";
 
const queryClient = new QueryClient();
 
// Custom storage keys (optional)
const accountStorage = createStorageAccount("my-app:account");
const networkStorage = createStorageNetwork("my-app:network");
 
export default function App({ children }) {
  const config = createWalletConfig({
    networks: [
      createSolanaMainnet(),
      createSolanaDevnet(),
      createSolanaTestnet(),
    ],
    accountStorage,
    networkStorage,
    onNetworkChange: (networkId) => {
      console.log("Network changed to:", networkId);
    },
  });
 
  return (
    <QueryClientProvider client={queryClient}>
      <WalletProvider config={config}>
        <SolanaWalletProvider queryClient={queryClient}>
          {children}
        </SolanaWalletProvider>
      </WalletProvider>
    </QueryClientProvider>
  );
}

Architecture

The provider initializes three main contexts that work together:

1. WalletNetworkContext

Manages the list of available networks and the currently selected network. It persists the selection to localStorage.

Responsibilities:

• Network selection and switching
• Network persistence
• Network validation

2. WalletAccountContext

Manages the currently connected account. It automatically attempts to reconnect to the last used wallet and account on mount.

Responsibilities:

• Account connection/disconnection
• Account persistence
• Wallet-to-account mapping
• Account validation

3. WalletUiContext

Exposes UI helpers like connect, disconnect, and modal state management.

Responsibilities:

• UI state (modals, dialogs)
• Wallet list filtering
• Connection helpers

API Reference

WalletProvider

The main provider component that wraps your application.

Props

createWalletConfig

Factory function to create a wallet configuration object.

Copyfunction createWalletConfig(props: WalletConfig): WalletConfig

WalletConfig

Configuration object for WalletProvider.

Persistence

State is automatically persisted to localStorage using nanostores:

• Network: The ID of the selected network (e.g., "solana:mainnet")
• Account: A string in the format "walletName:accountAddress" (e.g., "Phantom:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU")

This ensures that users stay connected and on the correct network across page reloads.

Multi-chain Support

The WalletProvider is designed to work with multiple blockchains using a plugin architecture. While we currently provide first-class support for Solana, you can add support for other chains by:

1. Creating network definitions using defineNetwork()
2. Implementing chain-specific utilities (like formatSol for Solana)
3. Creating chain-specific adapter providers (like SolanaWalletProvider)
4. Passing the networks to the provider and wrapping with chain adapters

Plugin Architecture

The wallet kit uses a plugin-based architecture where each blockchain can provide an optional adapter:

Copy<WalletProvider config={walletConfig}>
  <SolanaWalletProvider>
    {/* Future: <BitcoinWalletProvider> */}
    {/* Future: <EthereumWalletProvider> */}
    {children}
  </SolanaWalletProvider>
</WalletProvider>

This allows consumers to choose which blockchains to enable. See the Supported Networks section for blockchain-specific integrations.