Skip to content

feat(wallet): accelerate storage synchronization #486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
BraydenLangley wants to merge 9 commits into
base: main
Choose a base branch
from
Draft

feat(wallet): accelerate storage synchronization #486

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
3d420ab
feat(wallet): accelerate storage synchronization
BraydenLangley Aug 17, 2026
bc57cac
fix(wallet): disambiguate storage sync checkpoints
BraydenLangley Aug 18, 2026
246d7fc
refactor(wallet): simplify sync state selection
BraydenLangley Aug 18, 2026
bb21239
fix(wallet): keep sync state selection bundle-neutral
BraydenLangley Aug 18, 2026
4e49816
chore(wallet): record sync bundle growth
BraydenLangley Aug 18, 2026
de31259
chore(wallet): align platform budgets with clean builds
BraydenLangley Aug 18, 2026
15d17bc
chore(wallet): account for Linux gzip output
BraydenLangley Aug 18, 2026
e998189
fix(wallet): retry oversized sync responses
BraydenLangley Aug 19, 2026
74ee852
chore(wallet): account for hosted compression
BraydenLangley Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions docs/packages/wallet/wallet-toolbox-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ id: pkg-wallet-toolbox-client
title: '@bsv/wallet-toolbox-client'
kind: package
domain: wallet
version: '2.10.2'
last_updated: '2026-08-14'
last_verified: '2026-08-14'
version: '2.11.0'
last_updated: '2026-08-17'
last_verified: '2026-08-17'
review_cadence_days: 30
npm: 'https://www.npmjs.com/package/@bsv/wallet-toolbox-client'
repo: 'https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox/client'
Expand All @@ -18,6 +18,13 @@ tags: [wallet, browser, indexeddb, storage, brc-100]
`@bsv/wallet-toolbox-client` is the browser-safe Wallet Toolbox distribution.
It includes the BRC-100 wallet, signer, services, IndexedDB storage, and remote
storage client without Node-only Knex, SQLite, MySQL, or filesystem adapters.

Wallet replication uses adaptive, size-aware source reads. Browser clients can
set `includeTotals` on sync-chunk requests to obtain optional source record
totals for exact progress displays; older providers remain compatible and may
omit the totals. New clients also carry the registered writer-local sync-state
identifier to disambiguate legacy duplicate checkpoints on upgraded providers;
older protocol peers remain compatible.
Related browser `noSend` chains retain local action batching, while unrelated
actions cannot join or commit the active workspace. Supported remote providers
can resume a soft-expired workspace using its exact persisted inputs.
Expand Down
13 changes: 10 additions & 3 deletions docs/packages/wallet/wallet-toolbox-mobile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ id: pkg-wallet-toolbox-mobile
title: '@bsv/wallet-toolbox-mobile'
kind: package
domain: wallet
version: '2.10.2'
last_updated: '2026-08-14'
last_verified: '2026-08-14'
version: '2.11.0'
last_updated: '2026-08-17'
last_verified: '2026-08-17'
review_cadence_days: 30
npm: 'https://www.npmjs.com/package/@bsv/wallet-toolbox-mobile'
repo: 'https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox/mobile'
Expand All @@ -18,6 +18,13 @@ tags: [wallet, react-native, mobile, storage, brc-100]
`@bsv/wallet-toolbox-mobile` is the React Native and mobile-safe Wallet
Toolbox distribution. It includes wallet, signer, services, monitoring, and
remote storage surfaces without Knex, SQLite/MySQL, IndexedDB, or Node-only IO.

Wallet replication uses adaptive, size-aware source reads. Mobile clients can
set `includeTotals` on sync-chunk requests to obtain optional source record
totals for exact progress displays; older providers remain compatible and may
omit the totals. New clients also carry the registered writer-local sync-state
identifier to disambiguate legacy duplicate checkpoints on upgraded providers;
older protocol peers remain compatible.
Related mobile `noSend` chains retain local action batching, while unrelated
actions cannot join or commit the active workspace. Supported remote providers
can resume a soft-expired workspace using its exact persisted inputs.
Expand Down
16 changes: 13 additions & 3 deletions docs/packages/wallet/wallet-toolbox.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ title: '@bsv/wallet-toolbox'
kind: package
domain: wallet
npm: '@bsv/wallet-toolbox'
version: '2.10.2'
last_updated: '2026-08-14'
last_verified: '2026-08-14'
version: '2.11.0'
last_updated: '2026-08-17'
last_verified: '2026-08-17'
review_cadence_days: 30
status: stable
tags: ['wallet', 'brc100']
Expand Down Expand Up @@ -56,6 +56,16 @@ Opt-in remote-storage timing spans retain trace and parent-span correlation in
the telemetry sink without adding headers to authenticated requests. BRC-103,
BRC-104, AuthFetch, and the storage RPC wire contract remain unchanged.

Wallet replication fills bounded pages with adaptive, size-aware reads. A
client can set `includeTotals` on `RequestSyncChunkArgs` to request optional
source record totals for exact progress and ETA displays. Providers that do not
implement efficient totals omit them, preserving compatibility without adding
count-query overhead. Clients also carry the writer-local sync-state identifier
selected at provider registration so upgraded providers can safely address a
legacy duplicate checkpoint. Older clients and providers remain supported.
Knex storage creates the user-scoped proof lookup indexes through its normal
migration path.

UMP account lookup accepts one verified matching token as an existing account.
When no token verifies, one clean empty overlay response establishes a new
account even if other hosts fail or return malformed records. Multiple distinct
Expand Down
18 changes: 9 additions & 9 deletions docs/reference/package-api-migrations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,9 @@ and clean-consumer tests remain the executable type authority.
| `@bsv/verifast` | `0.3.0` | `0.3.4` | patch | [API and usage](../packages/sdk/verifast.md) | No consumer migration is required; exports, verification behavior, worker protocols, package paths, and runtime defaults are unchanged. |
| `@bsv/wallet-helper` | `0.1.1` | `0.1.6` | patch | [API and usage](../packages/helpers/wallet-helper.md) | No consumer migration is required; fluent builder APIs and transaction semantics are unchanged. |
| `@bsv/wallet-relay` | `0.2.2` | `0.3.5` | minor | [API and usage](../packages/wallet/wallet-relay.md) | No wallet RPC migration is required; upgrade to @bsv/sdk 2.4.1 or later. Existing relay sessions and number arrays remain valid, and host applications continue to provide their matching Express runtime and type graph. |
| `@bsv/wallet-toolbox` | `2.10.0` | `2.10.2` | patch | [API and usage](../packages/wallet/wallet-toolbox.md) | No consumer migration is required. Canonical AtomicBEEF and existing number-array behavior are unchanged; upgrade to @bsv/sdk 2.4.1 or later for cross-version JSON and wallet-error compatibility. |
| `@bsv/wallet-toolbox-client` | `2.10.0` | `2.10.2` | patch | [API and usage](../packages/wallet/wallet-toolbox-client.md) | No consumer migration is required. Browser exports, wire types, and canonical AtomicBEEF behavior are unchanged; use @bsv/sdk 2.4.1 or later. |
| `@bsv/wallet-toolbox-mobile` | `2.10.0` | `2.10.2` | patch | [API and usage](../packages/wallet/wallet-toolbox-mobile.md) | No consumer migration is required. React Native exports, wire types, and canonical AtomicBEEF behavior are unchanged; use @bsv/sdk 2.4.1 or later. |
| `@bsv/wallet-toolbox` | `2.10.2` | `2.11.0` | minor | [API and usage](../packages/wallet/wallet-toolbox.md) | No consumer migration is required. Existing sync requests and providers remain wire-compatible. Clients may optionally set includeTotals; capable providers return totals, older providers ignore the hint, and upgraded clients automatically carry a writer-local sync-state identifier that upgraded providers use when legacy checkpoints collide. Remote clients transparently retry HTTP 413 sync reads with a smaller response budget. SQL storage creates the new indexes through its normal migration path. |
| `@bsv/wallet-toolbox-client` | `2.10.2` | `2.11.0` | minor | [API and usage](../packages/wallet/wallet-toolbox-client.md) | No consumer migration is required. Existing browser sync calls remain valid; applications may optionally request and consume source totals, upgraded clients automatically carry the registered sync-state identifier, oversized read-only sync responses retry with a smaller remembered budget, and older remote providers continue to work without either addition. |
| `@bsv/wallet-toolbox-mobile` | `2.10.2` | `2.11.0` | minor | [API and usage](../packages/wallet/wallet-toolbox-mobile.md) | No consumer migration is required. Existing mobile sync calls remain valid; applications may optionally request and consume source totals, upgraded clients automatically carry the registered sync-state identifier, oversized read-only sync responses retry with a smaller remembered budget, and older remote providers continue to work without either addition. |
| `create-bsv-app` | `1.0.2` | `1.1.0` | minor | [API and usage](../packages/helpers/create-bsv-app.md) | Existing mainnet and testnet scaffolds are unchanged. New TTN projects pass --network ttn or select TerraTestNet in the configurator. |

`none` means the source manifest matches the recorded npm baseline. Any other
Expand Down Expand Up @@ -477,8 +477,8 @@ CLI entry points: `{"wallet-relay":"./bin/init.mjs"}`.

- Package documentation: [docs/packages/wallet/wallet-toolbox.md](../packages/wallet/wallet-toolbox.md)
- Source: [packages/wallet/wallet-toolbox](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox)
- Release note: Retains BRC-95 internalization compatibility, preserves typed AtomicBEEF, competing BEEF, and wallet review errors across portable and historical wallet JSON representations, and leaves opaque WAB response JSON unchanged.
- Migration: No consumer migration is required. Canonical AtomicBEEF and existing number-array behavior are unchanged; upgrade to @bsv/sdk 2.4.1 or later for cross-version JSON and wallet-error compatibility.
- Release note: Accelerates wallet-storage replication with adaptive size-aware source reads and user-scoped SQL proof indexes, adds opt-in source record totals for exact progress reporting, disambiguates legacy duplicate sync checkpoints, and retries oversized read-only sync responses with a smaller remembered page budget.
- Migration: No consumer migration is required. Existing sync requests and providers remain wire-compatible. Clients may optionally set includeTotals; capable providers return totals, older providers ignore the hint, and upgraded clients automatically carry a writer-local sync-state identifier that upgraded providers use when legacy checkpoints collide. Remote clients transparently retry HTTP 413 sync reads with a smaller response budget. SQL storage creates the new indexes through its normal migration path.

| Public subpath | Runtime target(s) | Declaration target(s) |
| ---------------- | ---------------------------------------------------- | -------------------------- |
Expand All @@ -491,8 +491,8 @@ CLI entry points: `{"wallet-relay":"./bin/init.mjs"}`.

- Package documentation: [docs/packages/wallet/wallet-toolbox-client.md](../packages/wallet/wallet-toolbox-client.md)
- Source: [packages/wallet/wallet-toolbox/client](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox/client)
- Release note: Carries the browser Wallet Toolbox internalization and BRC-100 JSON byte-boundary compatibility fixes, including portable wallet review errors and historical response recovery.
- Migration: No consumer migration is required. Browser exports, wire types, and canonical AtomicBEEF behavior are unchanged; use @bsv/sdk 2.4.1 or later.
- Release note: Carries adaptive size-aware wallet sync reads, HTTP 413 response-budget retries, the backward-compatible includeTotals progress contract, and duplicate-checkpoint disambiguation for browser and WebView wallets.
- Migration: No consumer migration is required. Existing browser sync calls remain valid; applications may optionally request and consume source totals, upgraded clients automatically carry the registered sync-state identifier, oversized read-only sync responses retry with a smaller remembered budget, and older remote providers continue to work without either addition.

| Public subpath | Runtime target(s) | Declaration target(s) |
| ---------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
Expand All @@ -503,8 +503,8 @@ CLI entry points: `{"wallet-relay":"./bin/init.mjs"}`.

- Package documentation: [docs/packages/wallet/wallet-toolbox-mobile.md](../packages/wallet/wallet-toolbox-mobile.md)
- Source: [packages/wallet/wallet-toolbox/mobile](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox/mobile)
- Release note: Carries the mobile Wallet Toolbox internalization and BRC-100 JSON byte-boundary compatibility fixes, including portable wallet review errors and historical response recovery.
- Migration: No consumer migration is required. React Native exports, wire types, and canonical AtomicBEEF behavior are unchanged; use @bsv/sdk 2.4.1 or later.
- Release note: Carries adaptive size-aware wallet sync reads, HTTP 413 response-budget retries, the backward-compatible includeTotals progress contract, and duplicate-checkpoint disambiguation for React Native wallets.
- Migration: No consumer migration is required. Existing mobile sync calls remain valid; applications may optionally request and consume source totals, upgraded clients automatically carry the registered sync-state identifier, oversized read-only sync responses retry with a smaller remembered budget, and older remote providers continue to work without either addition.

| Public subpath | Runtime target(s) | Declaration target(s) |
| ---------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
Expand Down
6 changes: 3 additions & 3 deletions docs/reference/stack-facts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,9 @@ authorized release action.
| wallet | `@bsv/btms` | `1.2.1` | node-library | node-cjs, node-esm | node | `>=22` | [packages/wallet/btms](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/btms) |
| wallet | `@bsv/btms-permission-module` | `1.1.3` | node-library | node-esm | node | `>=22` | [packages/wallet/btms-permission-module](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/btms-permission-module) |
| wallet | `@bsv/wallet-relay` | `0.3.5` | cli-library | browser-bundler, browser-esm, cli, node-cjs, node-esm | browser, node | `>=22` | [packages/wallet/ts-wallet-relay](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/ts-wallet-relay) |
| wallet | `@bsv/wallet-toolbox` | `2.10.2` | node-library | node-cjs | node | `>=22` | [packages/wallet/wallet-toolbox](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox) |
| wallet | `@bsv/wallet-toolbox-client` | `2.10.2` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm | browser, node | `>=22` | [packages/wallet/wallet-toolbox/client](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox/client) |
| wallet | `@bsv/wallet-toolbox-mobile` | `2.10.2` | react-native-library | react-native-metro | react-native | `>=22` | [packages/wallet/wallet-toolbox/mobile](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox/mobile) |
| wallet | `@bsv/wallet-toolbox` | `2.11.0` | node-library | node-cjs | node | `>=22` | [packages/wallet/wallet-toolbox](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox) |
| wallet | `@bsv/wallet-toolbox-client` | `2.11.0` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm | browser, node | `>=22` | [packages/wallet/wallet-toolbox/client](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox/client) |
| wallet | `@bsv/wallet-toolbox-mobile` | `2.11.0` | react-native-library | react-native-metro | react-native | `>=22` | [packages/wallet/wallet-toolbox/mobile](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox/mobile) |

## Standalone infrastructure manifests

Expand Down
Loading
Loading