@usebutr/core 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,243 @@
+# @usebutr/core
+
+## 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
+
+- [#179](https://github.com/pedroapfilho/usebutr/pull/179) [`bc5b58c`](https://github.com/pedroapfilho/usebutr/commit/bc5b58cd87601be38dbb77a14e16eaaa36e8f012) Thanks [@pedroapfilho](https://github.com/pedroapfilho)! - Include package READMEs, MIT licenses, and documentation and issue links on npm.
+
+## 2.0.0
+
+### Major Changes
+
+- 9b1caa2: Correctness pass across the storage, hydration and connector layers. Several of
+  these change observable behaviour; the ones worth knowing about before upgrading:
+
+  **Breaking**
+
+  - `SuiWallet.signTransaction` now returns `{ bytes, signature }` instead of
+    `Uint8Array`. Sui's `executeTransactionBlock` needs both, and each connector
+    previously returned a different half, so the old value could not be broadcast
+    and a consumer could not tell which half they held. SVM and Bitcoin keep their
+    single-`Uint8Array` shape.
+  - `@usebutr/svm`'s `sendTx` returns the signature base58-encoded, matching the
+    WalletConnect namespace, the Ledger app, Solana explorers and
+    `getSignatureStatuses`. It previously returned base64.
+  - `@usebutr/sui`'s feature input types drop the `string` arm from
+    `transaction`; wallets only ever accepted the `toJSON()` form. Strings and BCS
+    bytes are now wrapped for you, so `sendTx` accepts strictly more than before.
+
+  **Behaviour fixes**
+
+  - `WalletStorage.setPool` and `removePoolEntry` could self-deadlock on a corrupt
+    pool payload, leaving `connectWallet` unresolved and every later pool write
+    jammed for the page's life. Both are fixed, and `readWalletSnapshot` now shares
+    one codec with `WalletStorage` so the server and client decodes cannot drift.
+  - A seeded (SSR) entry whose silent reconnect failed used to stay in the pool
+    backed by a placeholder connector forever, so `useSigner`/`useBalance`
+    reported an error and `useConnectionStatus` reported `"reconnecting"`
+    permanently. Those entries are now dropped.
+  - `useSigner` and `useBalance` stay `idle` for a wallet that is still
+    reconnecting instead of surfacing a placeholder rejection as `status: "error"`.
+  - `useConnectionStatus` lets a live `"connecting"`/`"error"` take precedence over
+    the derived `"reconnecting"`, so an in-flight attempt and a connection error
+    are no longer hidden. New `useIsReconnecting(connectorId?)` answers the
+    per-wallet question directly.
+  - A background restore no longer writes the connect-attempt status or steals
+    `activeConnectorId`, and a superseded `CONNECT_FAILED` no longer overwrites the
+    current attempt.
+  - An externally-disconnected connector is now torn down, not just dropped from
+    the pool, so a cached adapter is not reused while still holding a session.
+  - EVM: a malformed provider response is treated as absent rather than `""`, which
+    previously produced chain `eip155:0`, zero-length signatures, empty transaction
+    hashes and a confident `0 ETH`. `switchChain` gained the same-chain
+    short-circuit `sendTxToChain` already had.
+  - WalletConnect: accounts carry their own chain instead of all being stamped with
+    the active one, so a multi-chain session no longer returns a wrong-chain
+    address. One pairing now covers every configured namespace, the pairing URI
+    survives a reconnect, and concurrent connects share one pairing.
+  - Bitcoin: the sats-connect (Xverse) adapter honours `silent`, so a reload no
+    longer triggers an unsolicited approval prompt, and exposes the payment address
+    as its single account instead of also presenting the ordinals address as
+    spendable.
+  - Polkadot: the injected adapter actually delivers events to subscribers,
+    `switchChain` notifies like its Wallet Standard sibling, and chain resolution
+    prefers the mainnets rather than whatever the wallet listed first.
+  - Ledger: the device session is committed atomically, so a locked device no
+    longer leaves an open transport that reports itself connected, and concurrent
+    connects open one transport.
+  - SVM: `sendTxToChain` submits to the chain you asked for instead of the
+    adapter's current one, and rejects a chain the wallet does not advertise.
+  - `@usebutr/svm`'s `switchChain` capability now counts only `solana:` chains, so
+    a multi-namespace wallet no longer advertises a method that always throws.
+
+  **Testing**
+
+  - `createFakePersistence` is now the real `WalletStorage` over memory drivers
+    rather than a parallel implementation, so it inherits upsert semantics,
+    validation and JSON round-tripping. Two divergences are fixed as a result:
+    `setPool` upserts rather than replaces, and `clearAll` leaves the
+    user-disconnected flag alone.
+  - `createFakeConnectedWallet` rejects being given both an `adapter` and explicit
+    `addresses`/`accounts`, a combination whose halves could disagree.
+
+## 1.1.0
+
+### Minor Changes
+
+- 8ecaf89: Close five gaps that made multi-chain integration harder than it needed to be.
+
+  **Group wallets by platform without writing the loop yourself.**
+  `groupByPlatform(items, getPlatform)` in `@usebutr/core` buckets any list into
+  a `Map<ChainPlatform, T[]>` keyed in `CHAIN_PLATFORMS` order with empty
+  platforms omitted, and `@usebutr/react` adds
+  `useDiscoveredWalletsByPlatform()` / `useConnectedWalletsByPlatform()` on top.
+  A multi-chain wallet announces one adapter per platform, so every app hitting
+  more than one chain was writing this bucketing by hand.
+
+  **`autoDiscovery` takes an allowlist array, and says something when it's empty.**
+  `autoDiscovery(["evm", "svm"])` now works alongside the object form and reads
+  as the allowlist it is. An options value that enables no platforms logs a
+  warning instead of silently discovering nothing: a list built at runtime that
+  comes back empty was otherwise indistinguishable from "no wallets installed".
+  The bare `autoDiscovery()` everything-path is unchanged and stays silent.
+
+  **`createFakeConnectedWallet` in `@usebutr/testing`.** Builds the
+  `{ account, accounts, connector }` pool entry that UI tests actually render,
+  with accounts constructed through `buildAccount` so the `<chain>:<address>` id
+  format is never restated in a fixture. Defaults to the platform's mainnet chain
+  and a deterministic address; pass `adapter` to wrap a connector you already
+  built.
+
+  **The icon sanitization contract is now on the type.** `Connector.icon` is
+  already run through `sanitizeIcon` at discovery, so it is a trimmed non-empty
+  string or `undefined`, safe to hand to `next/image` with no second call and no
+  `icon !== ""` guard. `ConnectorMeta.icon` documents the opposite: it is
+  consumer-supplied and not sanitized.
+
+  **`createSignInFlow` in `@usebutr/core`.** Wraps the nonce, capability gate,
+  signature, base64 encoding, and verification handshake that every wallet-auth
+  app writes identically. Solana wallets advertising `solana:signIn` take the
+  SIWS path automatically. It deliberately does not define a message format: pass
+  `buildMessage` to match your backend. Also re-exports the SVM SIWS types
+  (`SolanaSignInFeature`, `SolanaSignInInput`, `SolanaSignInOutput`) from
+  `@usebutr/svm`, which were defined but not exported.
+
+## 1.0.0
+
+### Major Changes
+
+- f0a5116: **Breaking:** the `platform` field is gone from the `PlatformDiscoverer` type in `@usebutr/core`, and from the `evmDiscoverer`, `svmDiscoverer`, `suiDiscoverer`, `bitcoinDiscoverer` and `polkadotDiscoverer` objects that implement it. Nothing read it: the aggregator keys discoverers by `ChainPlatform` in its own registry, so the field only restated the key.
+
+  Migration: read the platform from the `KNOWN_DISCOVERERS` key in `@usebutr/wallets` (`Object.entries(KNOWN_DISCOVERERS)`), or from `adapter.chainPlatform` on a discovered adapter. Custom `PlatformDiscoverer` implementations must drop the `platform` property; keeping it is now an excess-property error.
+
+- f0a5116: **Breaking:** the deprecated `Wallet` type alias is removed from `@usebutr/core`.
+
+  Migration: import `WalletBase` instead (`type Wallet = WalletBase` was all the alias ever was), or the per-platform surface you actually mean: `EvmWallet`, `SvmWallet`, `SuiWallet`, `BitcoinWallet`, `PolkadotWallet`.
+
+### Minor Changes
+
+- 7887cf0: Add `bytesToBase58` and `base58ToBytes` to the shared encoding module, alongside the existing hex and base64 helpers. Base58 was hand-rolled in eight places across the connector packages and the demo apps; a single tested implementation removes the drift surface on Solana addresses and signatures.
+
+### Patch Changes
+
+- 7887cf0: Split the 497-line `types/wallet.ts` into focused modules (platform, account, capabilities, connector, wallet, manager) behind the same barrel. Pure file motion: every exported name and type is unchanged.
+
+## 0.5.0
+
+### Minor Changes
+
+- 4467a5e: Compare the adapter instance in `walletEqual` instead of `connector.id`, so selectors re-render when hydration swaps a shadow adapter for the live one. Previously an SSR consumer stayed pinned to the placeholder whose methods throw `ShadowConnectorError`.
+
+  `isShadowAdapter` and `ShadowConnectorError` are now exported from the package root.
+
+## 0.4.2
+
+### Patch Changes
+
+- c1309ee: Validate persisted wallet data and WalletConnect responses with shared Zod schemas.
+
+## 0.4.1
+
+### Patch Changes
+
+- 937dfae: Bump runtime dependency floors (`@wallet-standard/app` 1.1.1, `@ledgerhq/*` latest minors, `@walletconnect/universal-provider` 2.23.10) and modernize public type declarations from method signatures to property function types (oxlint `method-signature-style`). Type-level only — no runtime behavior change.
+
+## 0.4.0
+
+### Minor Changes
+
+- b5322ae: Add shared byte-encoding utilities (`bytesToHex`, `bytesToHexPrefixed`,
+  `hexToBytes`, `base64ToBytes`, `bytesToBase64`) and consolidate the per-connector
+  copies onto them. Behavior preserved: prefixed (`0x`) and bare hex are distinct
+  variants so each chain keeps its existing output.
+
+### Patch Changes
+
+- d5f32c7: Fix Polkadot wallet connections failing to persist and reconnect on reload.
+  The storage validators' chain-platform allowlist was missing `polkadot`, so
+  Polkadot pool entries were rejected on write — and because the write rejects
+  the whole batch, a co-connected sibling (e.g. Solana) could be dropped too.
+  The allowlist is now derived from a single `CHAIN_PLATFORMS` source of truth
+  shared with the `ChainPlatform` type, so the runtime checks can't drift from
+  the type again.
+- a46eecd: Ship unminified ESM so downstream bundlers (Vite/esbuild dep pre-bundling) process the package correctly; fixes a ReferenceError in consumer dev servers. The consuming app minifies once at its own build.
+
+## 0.3.0
+
+### Minor Changes
+
+- 886ee1d: Add Polkadot/Substrate support. New `@usebutr/polkadot` package discovers wallets via injectedWeb3 (polkadot-js, Talisman, SubWallet, Nova, Enkrypt) with a Wallet Standard `polkadot:*` fallback. `ChainPlatform` widens to include `"polkadot"`; `autoDiscovery({ polkadot: true })` and `CHAINS_BY_PLATFORM` now cover it. Message signing works via the injected `signer.signRaw`; transaction signing is delegated to the consumer through `getSigner()` (e.g. polkadot-api), matching butr's no-RPC posture.
+
+## 0.2.2
+
+### Patch Changes
+
+- db5d7e9: Fix intermittent wallet disconnect on page reload. Two storage-write bugs caused a remembered connection to be erased:
+
+  - An external `disconnected` event (EIP-1193 emits `accountsChanged: []`) fired on a simple wallet **auto-lock**, not just on permission revocation — and the store persisted the resulting empty pool, wiping the saved connection on every lock. The store now mirrors the disconnect into reducer state (so the UI hides the wallet) but leaves storage untouched; the next hydrate retries and self-heals once the wallet is unlocked. Explicit `disconnectWallet` still evicts via `removePoolEntry`.
+  - A transient `eth_accounts: []` during eager restore (a locked wallet) was treated as a permanent failure and the storage entry was deleted. Hydration now preserves storage on a failed restore and reports it as `dropped` for telemetry only, so a reload retries.
+
+  Additionally, `WalletStorage.setPool` is now **additive** and serialized through an internal mutation queue, so concurrent fire-and-forget writes can't interleave their read-modify-write phases and clobber each other's entries. `connectWallet` / `disconnectWallet` now await their storage writes so callers can trust persistence has landed on the next line.
+
+## 0.2.1
+
+### Patch Changes
+
+- f846e77: Wallet-announced icons are trimmed of surrounding whitespace on ingestion. Some wallets ship data-URI icons with a leading newline, which strict consumers reject — Next.js's `<Image>` throws because `src` must not start with a control character. `@usebutr/core` exports a `sanitizeIcon` helper; the EIP-6963 and Wallet Standard adapters apply it, and an all-whitespace icon now resolves to `undefined` rather than a blank string.
+
+## 0.2.0
+
+### Minor Changes
+
+- b77a477: Persisted pool entries now require the `accounts` field. Entries written by older versions without it are dropped on read with a warning.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Filho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @usebutr/core
+
+Core types, store, storage, and discovery seam for butr. No React, no protocols.
+
+Part of [butr](https://www.usebutr.com), a multi-chain wallet discovery and
+connection-state library. Your application owns the picker UI and chain client.
+
+## Install
+
+```bash
+npm install @usebutr/core zustand
+```
+
+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
+
+```ts
+import { createWalletManager, fromAdapters } from "@usebutr/core";
+import { autoDiscovery } from "@usebutr/wallets";
+
+const manager = createWalletManager({
+  onConnectError: (error, connectorId) => console.warn(connectorId, error.kind),
+  sources: [autoDiscovery()],
+});
+
+// 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)
+- [Getting started](https://docs.usebutr.com/getting-started/quickstart)
+- [Examples and source](https://github.com/pedroapfilho/usebutr)
+- [Report an issue](https://github.com/pedroapfilho/usebutr/issues)
+
+## License
+
+[MIT](./LICENSE), copyright 2026 Pedro Filho.