@bopen-io/wallet-toolbox 2.6.2-brc153.5 → 2.14.5

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,35 @@
+<!-- Generated by scripts/third-party-license-policy.mjs. Do not edit by hand. -->
+
+# Third-Party Notices
+
+The Open BSV License Version 6 in `LICENSE.txt` applies to current TS Stack
+first-party contributions. It does not replace, narrow, or relicense historical
+or third-party material identified below. Each identified portion remains available
+under its stated terms.
+
+Distributors must keep this file and the referenced `LICENSES/` files with source,
+npm tarballs, browser bundles, WebAssembly artifacts, and container images that
+contain the corresponding material. Ordinary dependency licenses remain with those
+dependencies and are additionally inventoried in release SBOMs.
+
+Registry: `governance/third-party-materials.json`
+
+## Release clearance status
+
+The notices below reduce attribution risk but do not create rights. A release is
+blocked while any item marked `required` remains unresolved.
+
+- **2026-stack-license-uniformization-authority — cleared:** The uniformization changed 107 total paths, including 55 license or policy texts; all 28 preexisting license/policy files are inventoried and every prior grant remains scoped to its snapshot code, so no blanket retroactive relicensing authority is relied upon.
+  Accepted evidence: governance/license-continuity.json, governance/license-evidence/pre-uniformization-root-policy.md, and the nine hash-pinned historical Open BSV texts.
+
+## Wallet Toolbox pre-uniformization Open BSV License version 4 source (snapshot d215223af67b2b08ef628e8e07f5cff8b60ec9b3)
+
+- License: `LicenseRef-Open-BSV-License-4`
+- Use in this stack: license continuity for wallet source present before the 2026 license-file uniformization
+- Upstream: https://github.com/bsv-blockchain/ts-stack/tree/d215223af67b2b08ef628e8e07f5cff8b60ec9b3/packages/wallet/wallet-toolbox
+- License text: [Open-BSV-License-4-wallet-pre-2026.txt](./LICENSES/Open-BSV-License-4-wallet-pre-2026.txt)
+- Incorporated paths:
+  - `packages/wallet/wallet-toolbox`
+  - `packages/wallet/wallet-toolbox-examples`
+
+Copyright (c) 2023 BSV Blockchain Association (Bitcoin Association)

package/docs/README.md

@@ -2,7 +2,11 @@
 
 The documentation is split into various pages, each covering a set of related functionality. The pages are as follows:
 
-- [Examples](https://bsv-blockchain.github.io/wallet-toolbox-examples/) - Getting started and specialized examples.
+- [Backup and recovery](https://bsv-blockchain.github.io/ts-stack/guides/wallet-backup-recovery/) — Both key material and wallet records are required.
+- [BRC-38/39 integration](https://bsv-blockchain.github.io/ts-stack/guides/wallet-data-portability/) — Current portable data APIs and import/export limits.
+- [Recovery drill](https://bsv-blockchain.github.io/ts-stack/guides/wallet-recovery-drill/) — Acceptance checklist and evidence template.
+- [Agent implementation brief](https://bsv-blockchain.github.io/ts-stack/guides/wallet-recovery-agent-brief/) — Source map and implementation guidance.
+- [Examples](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/wallet-toolbox-examples) — Current workspace examples and safety instructions.
 - [Setup](./setup.md) — Classes supporting wallet setup, experimentation and customization.
 - [Wallet](./wallet.md) — Top level `Wallet` class and related APIs.
 - [Client](./client.md) — Browser deployment friendly toolbox subset.
@@ -12,18 +16,25 @@ The documentation is split into various pages, each covering a set of related fu
 - [Action batch planning](./action-batch-planning.md) — Session-local `noSend` planning and atomic storage commit.
 - [WAB Shamir](./wab-shamir.md) — Shamir 2-of-3 key recovery system with entropy collection and WAB server integration.
 - [Authentication observability](./authentication-observability.md) — Privacy-safe telemetry, WAB transport hardening, and account-continuity handling.
+- [Local-first ChainTracks](./local-first-chaintracks.md) — Packaged checkpoints, local persistence, background synchronization, fallback quorum, and recovery controls.
 
 ## Open API
 
 [BRC-100](https://brc.dev/100) defines a Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface which is implemented in this library within the WalletClient class. The API is laid out here as a swagger openapi document to offer a fast-track to understanding the interface which is implemented across multiple substrates. The JSON api is generally considered a developer friendly introduction to the WalletClient, where an binary equivalent ABI may be preferred for production use cases.
 
-- [Wallet API Swagger UI](https://bsv-blockchain.github.io/ts-sdk/swagger)
+- [BRC-100 wallet API](https://bsv-blockchain.github.io/ts-stack/specs/brc-100-wallet/)
 
 ## Open RPC
 
-StorageClient implements the WalletStorageProvider interface over https using a JSON-RPC api which can be explored using the JSight UI.
-
-- [StorageClient JSight UI](https://bsv-blockchain.github.io/wallet-toolbox/open-rpc)
+`StorageClient` implements `WalletStorageProvider` over HTTPS using JSON-RPC.
+Every response must complete BRC-103 mutual authentication. By default, the
+first authenticated server identity reached through the configured HTTPS
+endpoint is authoritative for the client instance; callers with an
+independently validated key can pass `serverIdentityKey` to pin it from the
+first response. The distinct storage identity advertised through that
+authenticated response is authoritative by default and can be independently
+pinned with the `storageIdentityKey` option. Its maintained API documentation is in the
+[Storage reference](./storage.md#class-storageclient).
 
 ## Getting Started
 
@@ -40,45 +51,47 @@ npm install @bsv/wallet-toolbox
 Here's a simple example of using the toolbox to create and fund a testnet wallet using SQLite for persistent storage:
 
 ```ts
-import { InternalizeActionArgs, PrivateKey, Utils } from '@bsv/sdk'
+import { InternalizeActionArgs, Utils } from '@bsv/sdk'
 import { Setup } from '@bsv/wallet-toolbox'
 
-const rootKeyHex = PrivateKey.fromRandom().toString()
-console.log(`MAKE A SECURE COPY OF YOUR WALLET PRIVATE ROOT KEY: ${rootKeyHex}`)
+// Test fixture only: supply a recoverable test key; never log it.
+// Production wallets use their reviewed secret-store/key-recovery integration.
+const rootKeyHex = process.env.TEST_WALLET_ROOT_KEY
+if (!rootKeyHex) throw new Error('Configure a test wallet root key first')
 
 const { wallet } = await Setup.createWalletSQLite({
-    filePath: './myTestWallet.sqlite',
-    databaseName: 'myTestWallet',
-    chain: 'test',
-    rootKeyHex
+  filePath: './myTestWallet.sqlite',
+  databaseName: 'myTestWallet',
+  chain: 'test',
+  rootKeyHex
 })
 
 // Obtain a Wallet Payment for your new wallet from a testnet funding faucet.
 // Update or replace the values in the following example object with your actual funding payment.
 // Note that the values below will not be accepted as they are not intended for your new wallet.
 const r = {
-    senderIdentityKey: '03ac2d10bdb0023f4145cc2eba2fcd2ad3070cb2107b0b48170c46a9440e4cc3fe',
-    vout: 0,
-    txid: '942f094cee517276182e5857369ea53d64763a327d433489312a9606db188dfb',
-    derivationPrefix: 'jSlU588BWkw=',
-    derivationSuffix: 'l37vv/Bn4Lw=',
-    atomicBEEF: '01010101942f094cee517...a914b29d56273f6c1df90cd8f383c8117680f2bdd05188ac00000000'
+  senderIdentityKey: '03ac2d10bdb0023f4145cc2eba2fcd2ad3070cb2107b0b48170c46a9440e4cc3fe',
+  vout: 0,
+  txid: '942f094cee517276182e5857369ea53d64763a327d433489312a9606db188dfb',
+  derivationPrefix: 'jSlU588BWkw=',
+  derivationSuffix: 'l37vv/Bn4Lw=',
+  atomicBEEF: '01010101942f094cee517...a914b29d56273f6c1df90cd8f383c8117680f2bdd05188ac00000000'
 }
 
 const args: InternalizeActionArgs = {
-    tx: Utils.toArray(r.atomicBEEF, 'hex'),
-    outputs: [
-        {
-            outputIndex: r.vout,
-            protocol: 'wallet payment',
-            paymentRemittance: {
-                derivationPrefix: r.derivationPrefix,
-                derivationSuffix: r.derivationSuffix,
-                senderIdentityKey: r.senderIdentityKey
-            }
-        }
-    ],
-    description: 'from faucet'
+  tx: Utils.toArray(r.atomicBEEF, 'hex'),
+  outputs: [
+    {
+      outputIndex: r.vout,
+      protocol: 'wallet payment',
+      paymentRemittance: {
+        derivationPrefix: r.derivationPrefix,
+        derivationSuffix: r.derivationSuffix,
+        senderIdentityKey: r.senderIdentityKey
+      }
+    }
+  ],
+  description: 'from faucet'
 }
 
 const rw = await wallet.internalizeAction(args)

package/docs/action-batch-planning.md

@@ -17,12 +17,34 @@ Large first actions use compact bootstrap only when the provider also advertises
 `compactBegin: true`; this keeps new clients compatible with older version-1
 servers during a rolling deployment.
 
+One `Wallet` instance owns at most one in-memory action-batch workspace. An
+independent `noSend` graph created while that workspace is open uses the ordinary
+persistent path; it is not captured merely because the calls overlap. Storage
+providers may host many concurrent batches for different wallets or sessions,
+and their output reservations remain disjoint. A future client-side multi-workspace
+router would also need defined semantics for a `sendWith` request or child action
+that joins more than one graph; this version deliberately does not imply those
+semantics.
+
 The original manifest and one-blob-per-request transport remain version 1. A
 provider can independently advertise the additive `manifestVersion: 2`,
-`commitByDigest`, and `packedUploads` capabilities. A new client uses each
-optimization only when its provider advertises it. Old clients ignore the extra
-fields, new clients retain the version-1 path against old providers, and the two
-new storage methods are optional for third-party `WalletStorage` implementations.
+`commitByDigest`, `resume`, `maxReservedOutputs`, and `packedUploads`
+capabilities. A new client uses each optimization only when its provider
+advertises it. Old clients ignore the extra fields, new clients retain the
+version-1 path against old providers, and additive storage methods remain
+optional for third-party `WalletStorage` implementations. The exported capability
+helper does not advertise `resume` by default; built-in providers opt in because
+they implement the optional `resumeActionBatch` method.
+
+The retained browser platform contract measures the resumable implementation at
+1,548,179 raw / 364,550 gzip / 285,697 Brotli bytes with Vite and 1,209,217 raw /
+331,318 gzip / 267,001 Brotli bytes with esbuild. Every browser size ceiling
+remains unchanged.
+
+The mobile contract measures 1,609,633 raw / 405,646 gzip / 315,527 Brotli
+Metro bytes and 3,253,366 raw / 1,293,591 gzip / 1,018,837 Brotli Hermes bytes.
+Only the Hermes raw ceiling advances, by less than 0.15%; every compressed and
+Metro ceiling remains unchanged.
 
 The capability and its methods are Wallet Toolbox storage extensions. They do not
 extend `WalletInterface`, `CreateActionArgs`, `SignActionArgs`, `noSend`,
@@ -36,17 +58,26 @@ extend `WalletInterface`, `CreateActionArgs`, `SignActionArgs`, `noSend`,
    output-script lengths at bootstrap. Signed transactions and the external
    proof frontier follow through the binary commit path, so a hexadecimal
    script is not duplicated into a large JSON request.
-2. The wallet plans, signs, validates, and indexes subsequent actions locally. A
-   shared BEEF graph avoids retaining repeated ancestry. The signed transaction
-   is the canonical source for output scripts; format 2 carries script digests
-   for validation, rather than carrying the same scripts as transaction bytes,
-   plan strings, metadata strings, and standalone blobs.
+2. The wallet plans, signs, validates, and indexes a subsequent action locally
+   only when it belongs to the same transaction graph: an input or
+   `noSendChange` outpoint references a staged output, or `sendWith` references
+   a transaction owned by the workspace. Time adjacency, a shared wallet or
+   originator, and merely being another `noSend` action do not establish
+   membership. Unrelated work continues through the ordinary persistence path.
+   A shared BEEF graph avoids retaining repeated ancestry. The signed
+   transaction is the canonical source for output scripts; format 2 carries
+   script digests for validation rather than duplicating scripts.
 3. If confirmed funding runs low, the wallet extends its reservation pool using
    an EWMA estimate and geometrically increasing runway. Forwarded staged change
    needs no reservation or extension.
-4. `sendWith`, or a normal action created while the workspace is open, validates
-   and atomically persists every staged action. Only the requested transactions
-   are sent; earlier actions retain their `nosend` status.
+4. `sendWith` that names a workspace transaction, or a normal action that
+   explicitly depends on a staged output, validates and atomically persists
+   every member action. An unrelated normal action neither joins nor commits
+   the workspace. Only the requested transactions are sent; earlier actions
+   retain their `nosend` status. If a workspace-owned `noSend` action also
+   requests only unrelated persisted transactions through `sendWith`, the new
+   action remains staged and the explicit broadcasts run through the ordinary
+   persistence path; neither request is silently dropped.
 5. Broadcast occurs after the storage transaction. Delayed mode returns after the
    batch is durably queued; immediate mode uses the existing aggregate broadcaster
    and review results.
@@ -62,17 +93,24 @@ can use unreserved outputs normally. A uniqueness constraint prevents one output
 from belonging to two active batches.
 
 The initial reservation includes at most three extra candidates and never more
-than eight outputs. Its canonical funding target includes the marginal P2PKH
-input fee and enough value to recover an economically viable first change output,
-so a low basket minimum cannot repeatedly select inputs that satisfy the nominal
-deficit but cost too much to use.
-
-Extensions add at most 64 outputs per storage call, but there is no cumulative
-reservation, workspace-size, action-count, or spend-chain limit. Additional
-bounded calls continue for as long as the workspace needs confirmed funding.
-They use the same exact, least-over, then largest-under selection policy as
-normal funding. Retry targets are incremental shortfalls: the planner credits
-the value and count of every unconsumed reserved output before asking for more.
+than eight outputs or the operator's lower cumulative reservation cap. Its
+canonical funding target includes the marginal P2PKH input fee and enough value
+to recover an economically viable first change output, so a low basket minimum
+cannot repeatedly select inputs that satisfy the nominal deficit but cost too
+much to use.
+
+Extensions add at most 64 outputs per storage call. Built-in providers also
+enforce and advertise a cumulative maximum of 256 persisted output reservations
+per workspace, including caller-selected persisted inputs and confirmed inputs
+already consumed by uncommitted member transactions. This is a provider resource
+bound, not a transaction or consensus input limit; staged outputs do not consume
+additional persisted reservations. Set `StorageProviderOptions.actionBatchMaxReservedOutputs`
+(or the matching `SetupWalletKnexArgs` option when using
+`Setup.createStorageKnex`) to another positive integer, or to `-1` for
+operator-selected unlimited operation. The provider advertises the effective value. Extensions use the same
+exact, least-over, then largest-under selection policy as normal funding. Retry
+targets are incremental shortfalls: the planner credits the value and count of
+every unconsumed reserved output before asking for more.
 Confirmed inputs already used by staged transactions remain reserved until
 commit but are not credited as available funding. Proactive EWMA requests
 likewise subtract the unconsumed pool, initialize from the first complete
@@ -80,9 +118,14 @@ sample, and increase geometric runway only when the provider fulfills both the
 requested count and value. Empty or partial extensions therefore cannot
 compound a target against unchanged wallet state.
 Leases last 15 minutes with a 60-minute hard lifetime. Long-running workspaces
-renew near 80% of the lease; commit may atomically reacquire an expired reservation
-when no conflicting spend or reservation occurred. Commit, abort, wallet
-destruction, expiry cleanup, and the one-minute monitor task release unused state.
+renew near 80% of the lease. A client and provider advertising `resume` can
+atomically reacquire only the exact persisted outpoints already held by that
+workspace after soft expiry; a conflicting spend or reservation fails that
+connected workflow without capturing unrelated actions. Lifecycle failures use
+`WERR_ACTION_BATCH_STATE` with a machine-readable state rather than message-text
+matching. Version-1 commit retains its compatible expired-input reacquisition
+path. Commit, abort, wallet destruction, expiry cleanup, and the one-minute
+monitor task release unused state.
 
 ## Atomic commit and payload transport
 
@@ -193,15 +236,15 @@ pnpm --filter @bsv/wallet-toolbox bench:action-batch
 On the same Apple Silicon host with Node.js v25.9.0, a representative cold
 250-action, 1 KiB-script run reduced planning/signing/validation from
 19,117.03 ms in legacy mode to 10,907.93 ms in batch mode (42.9%, or 1.75x).
-Including atomic commit, total local time was 19,163.87 ms versus 11,462.13 ms
-(40.2% lower), while storage calls fell from 501 to 2 and database transactions
-from 252 to 3. At 100 ms storage RTT those calls represent 50,100 ms versus
-200 ms of control-path latency, a 99.6% reduction.
-
-A generic single 4 MiB zero-filled script took 1,258.13 ms through the legacy
-path and 208.60 ms through format 2, including upload and atomic commit: 83.4%
-less local time. Its instrumented requests fell from 13,982,465 bytes to 8,064
-bytes. The one 4,195,234-byte logical pack compressed to 5,233 bytes and was
+Including atomic commit, total local time was 11,131.49 ms versus 5,795.95 ms
+(47.9% lower), while storage calls and database transactions fell from 750 to
+2 and from 750 to 3, respectively. At 100 ms storage RTT those calls represent
+75,000 ms versus 200 ms of control-path latency, a 99.7% reduction.
+
+A generic single 4 MiB zero-filled script took 1,160.86 ms through the legacy
+path and 288.20 ms through format 2, including upload and atomic commit: 75.2%
+less local time. Its instrumented requests fell from 13,982,465 bytes to 8,067
+bytes. The one 4,195,234-byte logical pack compressed to 5,236 bytes and was
 uploaded in one call. This synthetic compression ratio represents highly
 repetitive data; incompressible data falls back to identity encoding without
 expansion. Absolute times remain host- and database-dependent.
@@ -210,8 +253,8 @@ It records planning, signing and validation, storage RPCs, database transactions
 request bytes, commit and broadcast time, CPU, and incremental peak heap. Physical
 SQLite runs compare 1, 10, 50, and 250 action chains at 1 KiB and exercise each
 larger script size with a real action, including the 4 MiB upload path. Its
-complete model covers dependent, independent, explicit-input, and two-step
-signing workloads at every action count; 1 KiB, 64 KiB, 1 MiB, and 4 MiB
+complete model covers dependent, isolated-root fallback, explicit-input, and
+two-step signing workloads at every action count; 1 KiB, 64 KiB, 1 MiB, and 4 MiB
 scripts; and 25, 100, and 250 ms storage RTT. The measured cases deliberately
 include both many-small-action and few-large-action shapes so transport tuning
 is not fitted to one contract or graph. Production rollout should additionally