Core concepts
Overview
The butr mental model — one store, a pool of connectors, two platforms, asynchronous hydration.
butr is a small state machine around a pool of wallet connectors. Six ideas explain the whole library.
- Architecture — the end-to-end runtime: discovery → adapter → store → pool → React hooks → integration. Start here if you want the full picture in one page.
- 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. - Platforms — every connector is
evm,svm,sui, orbitcoin. The four platforms are tracked independently, so a user can hold all of them at once. Chains use CAIP-2 ids (eip155:1,solana:…,sui:…,bip122:…). - 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.
- Capabilities — flags that say what a wallet can do right now. Gate UI on these, not on method existence.
- 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 wildly different wallet SDKs become one tagged union).