Overview

butr is a small state machine around a pool of wallet adapters. Six ideas explain the whole library.

1. Architecture: the end-to-end runtime of sources → adapters → wallet manager → pool → React hooks → integration. Start here if you want the full picture in one page.
2. Connectors vs. wallets: every wallet is a WalletAdapter. butr calls the connector half (connect, getAccounts, subscribe); your app calls the wallet half (signMessage, sendTx, getSigner). All adapters arrive through one seam: WalletManagerConfig.sources.
3. Platforms: every adapter is evm, svm, sui, bitcoin, or polkadot. The five platforms are tracked independently, so a user can hold all of them at once. Chains use CAIP-2 ids (eip155:1, solana:…, sui:…, bip122:…, polkadot:…).
4. Pool, selection, active: the pool is every connected wallet; selection is the chosen wallet per platform; the active wallet is the single one in front of the user now.
5. Capabilities: an adapter method exists only when it works for that wallet. Check for the method before you call it.
6. Hydration: restoring the previous session is asynchronous because wallet adapters announce themselves asynchronously.

Two supporting topics round it out: persistence (what survives a reload, and why it is derived from state rather than written by hand) and errors (how thrown values from inconsistent wallet SDKs become one ConnectionError class).