@usebutr/core

Wallet managerCopy Anchor Link

createWalletManager(config?, options?): WalletManagerCopy Anchor Link

import { createWalletManager } from "@usebutr/core";
import { autoDiscovery } from "@usebutr/wallets";

const manager = createWalletManager({ sources: [autoDiscovery()] });
const stop = manager.start();

manager.subscribe((state) => {
  renderPicker(state.adapters);
});

const wallet = await manager.connect("io.metamask");

Framework-free: @usebutr/react's provider creates one per mount and calls start() in an effect. Creating a manager has no side effects, so it is safe during a server render. options.initialState (a WalletSnapshot) seeds it synchronously, as the provider's initialState prop does.

WalletManagerCopy Anchor Link

A read-only zustand store plus actions. Every action is a stable reference.

WalletManagerConfigCopy Anchor Link

Read once, when the manager is created. Define it at module scope.

WalletStateCopy Anchor Link

HydrationOutcomeCopy Anchor Link

type HydrationOutcome = {
  dropped: ReadonlyArray<{ connectorId: string; reason: ConnectionError }>;
  pendingIds: ReadonlyArray<string>;
  restoredIds: ReadonlyArray<string>;
};

pendingIds are not failures: their adapters had not been announced yet, and the manager restores them the moment they are.

SourcesCopy Anchor Link

WalletSourceCopy Anchor Link

type WalletSource = (onAdapter: (adapter: WalletAdapter) => void) => () => void;

A function that announces adapters and returns its unsubscribe. Every discover*Adapters export already has this shape, so it goes into sources as-is.

fromAdapters(adapters): WalletSourceCopy Anchor Link

Takes an adapter, an iterable of adapters, or a promise of either, for adapters that are built rather than discovered: WalletConnect, Ledger, hand-rolled ones. They then appear in useDiscoveredWallets() like any discovered wallet. A rejected promise is logged and contributes nothing, so give each factory its own fromAdapters.

import { fromAdapters } from "@usebutr/core";
import { createLedgerAdapter } from "@usebutr/ledger";
import { createWalletConnectAdapters } from "@usebutr/walletconnect";

const sources = [
  fromAdapters(createWalletConnectAdapters({ namespaces: { evm: [] }, projectId })),
  fromAdapters(createLedgerAdapter({ platform: "evm" })),
];

PlatformDiscovererCopy Anchor Link

{ subscribe: WalletSource; fallback?: { subscribe(onAdapter, { hasAnyPrimaryAdapter }) } }. Each platform package exports one; @usebutr/wallets composes them.

AdaptersCopy Anchor Link

Connector<P>Copy Anchor Link

What butr itself calls. Every adapter has chainPlatform, id, name, connect(options?: { silent?: boolean }) and getAccounts(), plus icon?. disconnect, requestAccounts and subscribe are optional. getAccounts() resolves the accounts the wallet exposes, active first; an empty list means not connected.

WalletBase<Tx>Copy Anchor Link

The wallet half. getSigner() is always there; everything else exists only when it works for that wallet, so presence is the capability check:

type WalletBase<Tx> = {
  getBalance?: (options?: BalanceOptions) => Promise<Balance>;
  getSigner: () => Promise<WalletSigner>;
  getTransactionReceipt?: (hash: string) => Promise<TransactionReceipt>;
  sendTx?: (tx: Tx, options?: TransactionOptions) => Promise<string>;
  signMessage?: (message: Uint8Array, options?: AccountOptions) => Promise<SignedMessage>;
  switchChain?: (chain: ChainBase) => Promise<void>;
};

• WalletAdapter is the union of the five adapter types. Narrow on chainPlatform to reach a platform's own methods and transaction type.
• WalletAdapterFor<P> picks one: WalletAdapterFor<"svm"> is SvmAdapter.
• EvmTransactionRequest is an eth_sendTransaction object whose quantities may be bigint; EvmTransactionValue is its value type.
• SuiTransactionInput is a @mysten/sui Transaction (anything with toJSON()), its JSON string, or BCS bytes.
• BitcoinTransfer is { amount: bigint; recipient: string }, in satoshis.

Options and resultsCopy Anchor Link

type AccountOptions = { account?: Account };
type TransactionOptions = AccountOptions & { chain?: ChainBase };
type BalanceOptions = AccountOptions & { token?: string };

type SignedMessage = { signature: Uint8Array; signedMessage: Uint8Array };
type SignInOutput = { account: Account; signature: Uint8Array; signedMessage: Uint8Array };
type TransactionReceipt = { status: "Error" | "Pending" | "Success" };
type Balance = { decimals: number; formatted: string; symbol: string; value: bigint };

An account the wallet does not expose rejects; omit it to use the active account. A chain targets one transaction: Wallet Standard and WalletConnect route it per call, an EVM wallet switches its network first, and a transport that can do neither rejects when it is not the current chain. SignInInput and SignInValue type the Sign In With Solana fields.

ConnectedWallet<P>Copy Anchor Link

type ConnectedWallet<P extends ChainPlatform = ChainPlatform> = {
  account: Account; // the active account, always one of `accounts`
  accounts: ReadonlyArray<Account>;
  connector: WalletAdapterFor<P>;
};

isPlatformWallet(wallet, platform)Copy Anchor Link

Type guard that narrows a pool entry to ConnectedWallet<P>, e.g. before calling its sendTx. The reverse needs nothing: a ConnectedWallet<"evm"> is already a ConnectedWallet.

import { isPlatformWallet } from "@usebutr/core";

if (isPlatformWallet(wallet, "svm") && wallet.connector.sendTx) {
  await wallet.connector.sendTx(serializedTx);
}

ConnectorEventCopy Anchor Link

type ConnectorEvent =
  { accounts: ReadonlyArray<Account>; type: "accountsChanged" } | { type: "disconnected" };

accounts is every account the wallet still exposes, active first. A chain switch arrives as a changed account.chain.

SignersCopy Anchor Link

getSigner() resolves a WalletSigner. Narrow it on kind; each branch is fully typed:

const signer = await wallet.connector.getSigner();
switch (signer.kind) {
  case "eip1193": {
    // signer.provider: Eip1193Provider, ready for viem's `custom()`
    break;
  }
  case "wallet-standard": {
    // signer.wallet: WalletStandardWallet, read features with `getFeature`
    break;
  }
  default: {
    // WalletConnect, Ledger, Unisat, … each carry their own fields
  }
}

• WalletSignerRegistry is an empty interface that transport packages fill through module augmentation. The signer kinds table lists every registered variant.
• WalletSigner is the union built from it, WalletSignerKind its kind values, and WalletSignerOf<K> one variant: WalletSignerOf<"eip1193">.

A kind exists in the union only when its package is part of the program. An app that imports neither @usebutr/evm nor @usebutr/wallets has no eip1193 variant; @usebutr/wallets loads every platform's kinds.

Chains and accountsCopy Anchor Link

• ChainBase: { id; name; namespace; reference }, CAIP-2 shaped. name is the chain's name, never the wallet's.
• ChainPlatform: "evm" | "svm" | "sui" | "bitcoin" | "polkadot". CHAIN_PLATFORMS is the same list at runtime; isChainPlatform(value) narrows a string.
• ChainsByPlatform: Readonly<Record<ChainPlatform, ReadonlyArray<ChainBase>>>.
• Account: { chain: ChainBase; id: string; walletAddress: string }.
• buildAccount(address, chain): Account builds the <chain id>:<address> id the manager compares accounts by. Hand-rolled adapters must use it.
• resolveChain(id, known?): ChainBase looks a CAIP-2 id up in a registry, and names a chain outside it by its id.

RegistriesCopy Anchor Link

CHAINS_BY_PLATFORM holds every list, keyed by platform: the shape a chain picker wants. The platform packages export no chain registries; an app that imports none of these bundles none of them.

ErrorsCopy Anchor Link

class ConnectionError extends ErrorCopy Anchor Link

kind: ConnectionErrorKind, message, and a standard cause holding the original value. ConnectionErrorKind is "UserRejected" | "RequestPending" | "WalletLocked" | "ChainMismatch" | "NotConnected" | "Timeout" | "WalletNotFound" | "Unknown". See errors.

toConnectionError(raw: unknown): ConnectionErrorCopy Anchor Link

Normalises any thrown value: EIP-1193 codes first, then message matching, else "Unknown". A ConnectionError passes through unchanged.

class ShadowConnectorError extends ErrorCopy Anchor Link

Thrown by connect, getAccounts and getSigner on a wallet still reconnecting from initialState. Carries connectorId and method; match it with instanceof. Check useIsReconnecting(id) first.

PersistenceCopy Anchor Link

createWalletStorage(options?): WalletPersistenceCopy Anchor Link

The default persistence: pool, selection and active id in the persistent driver, the disconnect intent in the session driver. WalletStorageOptions is { keyPrefix?; persistent?: StorageDriver; session?: StorageDriver }; keyPrefix defaults to "butr" and the drivers to localStorage and sessionStorage.

WalletPersistenceCopy Anchor Link

type WalletPersistence = {
  load: () => Promise<PersistedWalletState>;
  save: (state: PersistedWalletState) => Promise<void>;
};

The manager derives PersistedWalletState (a WalletSnapshot plus isUserDisconnected) after every change and hands the whole value to save, so an implementation never merges or diffs. See custom storage.

DriversCopy Anchor Link

• createBrowserStorageDriver(): BrowserStorageDrivers: { persistent, session } over localStorage and sessionStorage, falling back to memory where they do not exist.
• createMemoryStorageDriver(): StorageDriver: in-memory.
• createCookieStorageDriver(options?: CookieDriverOptions): StorageDriver: options are domain, initialCookies (InitialCookies, read on the server), maxAgeSeconds (default 30 days), path (default /), sameSite (default "lax") and secure (default true).

StorageDriver is { getItem; removeItem; setItem }, each returning a MaybePromise.

Server snapshotsCopy Anchor Link

• readWalletSnapshot(cookies: CookieSource, options?: SnapshotOptions): WalletSnapshot reads what the browser last persisted from a cookie list, map or record. Pass the same keyPrefix as storageKeyPrefix. See SSR without a flash.
• EMPTY_SNAPSHOT: a frozen snapshot with no connections.
• WalletSnapshot: { activeConnectorId; pool: StoredPoolRecord; selection: StoredSelectionRecord }. StoredPoolEntry is what a connection needs to render before its adapter exists: account, accounts, chainPlatform, connectorId, icon?, name.

Sign-inCopy Anchor Link

createSignInFlow(options): { signIn(wallet, account?) }Copy Anchor Link

Fetches a nonce, has the wallet sign, and hands the result to your verifier. Solana wallets with signIn take the Sign In With Solana path unless preferSignMessage is set.

SignInResult carries account, nonce, message?, signature, signedMessage, their base64 forms and wallet. SignInUnsupportedError (with connectorId) is thrown before the nonce request when the flow needs signMessage and the wallet has none. See the sign-in guide.

HelpersCopy Anchor Link

EncodingCopy Anchor Link

Source: packages/core/src/index.ts.