@usebutr/core 2.0.1 → 3.0.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @usebutr/core
 
+## 3.0.1
+
+### Patch Changes
+
+- [#208](https://github.com/pedroapfilho/usebutr/pull/208) [`488fe13`](https://github.com/pedroapfilho/usebutr/commit/488fe13fe9cddb99ff6c5d60f798140e6ac4076f) Thanks [@pedroapfilho](https://github.com/pedroapfilho)! - Bump runtime dependency ranges to the current non-major line.
+
+## 3.0.0
+
+### Major Changes
+
+- [#203](https://github.com/pedroapfilho/usebutr/pull/203) [`1263f86`](https://github.com/pedroapfilho/usebutr/commit/1263f8666afd43b4f7dbf8df1763709c3edf09d9) Thanks [@pedroapfilho](https://github.com/pedroapfilho)! - Adapters now say what they can do by having the method: `capabilities` is gone, and an optional method (`sendTx`, `signMessage`, `getBalance`, `switchChain`, …) exists only when it works for that wallet. No adapter returns a placeholder balance or a receipt that stays pending anymore.
+
+  - `sendTx(tx, { account, chain })` replaces `sendTx` and `sendTxToChain`, and `signMessage`, `signTransaction` and `getBalance` take options objects. `chain` is a `ChainBase`. An adapter either routes the call to that chain, switches the wallet to it, or rejects; none ignores it.
+  - An `account` the wallet does not expose now rejects instead of signing with the first account. `chain.name` is the chain's name, never the wallet's.
+  - `getAccounts()` resolves the active account first. `getAccount` and `switchAccount` are removed.
+  - `getSigner()` resolves a tagged `WalletSigner` (`eip1193`, `wallet-standard`, `walletconnect`, `ledger-*`, …), so it can be narrowed with `switch (signer.kind)` instead of cast.
+  - `createWalletManager(config, { initialState })` owns discovery, hydration and persistence, and works without React. `config.sources` replaces the `discovery`, `connectors` and `createConnector` props. `fromAdapters` registers WalletConnect, Ledger and hand-built adapters, which now also appear in `useDiscoveredWallets()`.
+  - `WalletManagerProvider` takes `config` and `initialState`. `useSigner(wallet)` and `useBalance(wallet, { token, account })` take the wallet entry itself, and id-taking hooks read the active wallet only when the id is omitted (`null` reads none). The hooks are `useWalletManager`, `useWalletState`, `useConnect`, `useWallet`, `useSelectedWallet` (now typed per platform), `useAccounts`, `useConnectionStatus`, `useIsHydrated`, `useIsReconnecting`, `useDiscoveredWallets`, `useConnectedWallets`, the `…ByPlatform` groupings, `useBalance` and `useSigner`.
+  - `manager.connect()` and `useConnect().connectAsync()` resolve the `ConnectedWallet` and reject with a `ConnectionError`, now an `Error` subclass with a `kind` and a new `WalletNotFound` kind. `useConnect().connect()` never rejects: the failure lands in its `error`.
+  - `WalletPersistence` is `load()` / `save(state)`, and `createWalletStorage` replaces `new WalletStorage`. Storage keys are unchanged.
+  - Chain registries (`EVM_CHAINS`, `SVM_CHAINS`, …, `CHAINS_BY_PLATFORM`) move to `@usebutr/core`, and `BITCOIN_CHAINS` gains `testnet4`. `@usebutr/wallets` loads every platform's signer kinds, so an app that imports only it can narrow `signer.kind`.
+  - `@usebutr/react` requires React 19, which its `use()` call already needed.
+  - WalletConnect requests on Solana, Sui and Bitcoin now carry their chain, so they no longer fall through to the first namespace in a multi-namespace session. Solana takes `SVM_CHAINS` chains and maps them to the genesis-hash ids WalletConnect sessions use.
+  - Ledger's Solana `signTransaction` returns the full signed transaction, Sui signs the intent message, and Bitcoin `signMessage` returns a BIP-137 signature.
+  - `@usebutr/testing`'s fake adapter resolves a `signer` you pass instead of registering a test-only signer kind.
+  - `setAccount` selects an exposed account without changing any account's chain. Unknown accounts are ignored; chain changes come from the adapter.
+  - WalletConnect EVM events use the namespace in `session_event`, including empty account lists that end the connection. Local chain switches still update the manager.
+  - Failed persistence saves wait for every key write to finish before reporting failure, so delayed writes cannot overwrite a later disconnect.
+  - `@usebutr/svm/transaction` provides the shared legacy/v0 signing codec used by Ledger and WalletConnect, with consistent layout and signature validation.
+
+  See the migration guide at https://docs.usebutr.com/migration.
+
+### Patch Changes
+
+- [#199](https://github.com/pedroapfilho/usebutr/pull/199) [`5d1f234`](https://github.com/pedroapfilho/usebutr/commit/5d1f23403263f7a1f8a48be061727972fe749b5f) Thanks [@pedroapfilho](https://github.com/pedroapfilho)! - Raise the zod dependency floor to 4.6.1.
+
 ## 2.0.1
 
 ### Patch Changes

package/README.md

@@ -11,23 +11,69 @@ connection-state library. Your application owns the picker UI and chain client.
 npm install @usebutr/core zustand
 ```
 
-The store works outside React. Add a discovery source or your own connector factory when wiring real wallets.
+The wallet manager works outside React. Pair it with `@usebutr/wallets` (or one
+platform's `discover*Adapters`) to find real wallets, or use `@usebutr/react`
+for the provider and hooks.
 
 ## Usage
 
-```tsx
-import { createWalletStore } from "@usebutr/core";
+```ts
+import { createWalletManager, fromAdapters } from "@usebutr/core";
+import { autoDiscovery } from "@usebutr/wallets";
 
-export const store = createWalletStore({
-  connectors: [],
-  createConnector: () => null,
+const manager = createWalletManager({
+  onConnectError: (error, connectorId) => console.warn(connectorId, error.kind),
+  sources: [autoDiscovery()],
 });
 
-// Read state from a non-React host.
-const wallets = store.getState().pool;
-console.log(wallets.size);
+// Creating a manager has no side effects; start() subscribes the sources,
+// restores persisted connections once, and bridges wallet events.
+const stop = manager.start();
+
+const wallet = await manager.connect("io.metamask");
+
+// A method exists only when it works for this wallet.
+if (wallet.connector.signMessage) {
+  await wallet.connector.signMessage(new TextEncoder().encode("hello"), {
+    account: wallet.account,
+  });
+}
+
+manager.subscribe((state) => console.log(state.pool.size, state.activeConnectorId));
 ```
 
+- **Sources.** A `WalletSource` is `(onAdapter) => unsubscribe`, so every
+  `discover*Adapters` export goes into `sources` as-is. `fromAdapters(adapters)`
+  wraps an array or a promise of built adapters (WalletConnect, Ledger,
+  hand-rolled ones). The first adapter announced for an id wins.
+- **State.** `getState()` holds the discovered `adapters`, the live `pool`,
+  the `selection` per platform, `activeConnectorId`, `reconnectingIds`, and the
+  latest attempt's `connectionStatus` / `connectionError`.
+- **Actions.** `connect`, `disconnect`, `disconnectAll`, `requestAccounts`,
+  `setAccount`, `setActive`, `setSelection`, `clearConnectionError`. `connect`
+  resolves the `ConnectedWallet` and rejects with a `ConnectionError` whose
+  `kind` is `UserRejected`, `RequestPending`, `WalletLocked`, `ChainMismatch`,
+  `NotConnected`, `Timeout`, `WalletNotFound` or `Unknown`.
+- **Signers.** `connector.getSigner()` resolves a tagged `WalletSigner`; narrow
+  it with `switch (signer.kind)`. Each transport package registers its kind.
+- **Chains and accounts.** Every registry lives here (`EVM_CHAINS`,
+  `SVM_CHAINS`, `SUI_CHAINS`, `BITCOIN_CHAINS`, `POLKADOT_CHAINS`, their
+  `*_LIST`, `CHAINS_BY_PLATFORM`). Adapters build chains with
+  `resolveChain(id, list)` and accounts with `buildAccount(address, chain)`.
+
+## Persistence
+
+Connections persist to localStorage and sessionStorage by default, written
+after every change once start-up hydration has read what was there. Swap the
+drivers with `createWalletStorage({ persistent, session })` (for example
+`createCookieStorageDriver()` so a server can read them), or pass any
+`WalletPersistence`: an object with `load()` and `save(state)`.
+
+To render connections on the server, read the cookies with
+`readWalletSnapshot(cookies)` and pass the snapshot as
+`createWalletManager(config, { initialState })`. Seeded wallets render at
+once and stay in `reconnectingIds` until their silent reconnect lands.
+
 ## Documentation
 
 - [Package reference](https://docs.usebutr.com/api/core)