Overview

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

1. Architecture: the end-to-end runtime of discovery → adapter → store → 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, getAccount, subscribe); your app calls the wallet half (signMessage, sendTx, getSigner). All adapters plug in through one seam: WalletManagerConfig.createConnector.
3. Platforms: every connector 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: flags that say what a wallet can do right now. Gate UI on these, not on method existence.
6. Hydration: restoring the previous session is asynchronous because wallet adapters announce themselves asynchronously.

Two supporting topics round it out: persistence (how state survives reloads, and why storage writes are silent) and errors (how thrown values from inconsistent wallet SDKs become one tagged union).