@bsv/wallet-toolbox 2.4.3 → 2.4.20

package/CHANGELOG.md

@@ -6,6 +6,86 @@ attention to changes that materially alter behavior or extend functionality.
 
 ## wallet-toolbox (unreleased)
 
+- Point Wallet Toolbox contributors and AI agents to the canonical stack-level
+  contribution and quality policy; keep client and mobile candidate versions
+  in release lockstep without changing runtime behavior.
+- Harden storage, action-batch, remoting, WAB, authentication, chaintracker,
+  and monitor implementation paths while preserving persisted schemas,
+  positional call compatibility, and public wallet/storage contracts.
+- Refresh compatible rate-limit, MySQL, and React Native build dependencies;
+  consolidate entropy, Merkle-path, and action-batch iteration without
+  changing persisted data, generated paths, or public wallet contracts.
+- Remove generated SQLite test databases before and after every Jest run so
+  repeated local validation cannot silently consume unbounded disk space.
+- Ship the Express declaration dependency required by the public storage
+  server, edge-policy, and rate-limit declarations. Validate authenticated
+  storage identities explicitly and normalize multi-value Express 5 headers
+  instead of relying on implicit request augmentation or scalar headers.
+- Add capability-negotiated action-batch manifest format 2 without changing
+  BRC-100. It derives source/output scripts from the authenticated transaction
+  graph, retains only the external proof frontier, bulk-loads shared storage
+  rows, and commits an already prepared manifest by semantic digest. Version-1
+  providers and clients retain their existing behavior.
+- Add authenticated `ABP1` multi-blob uploads with bounded gzip/Brotli/identity
+  negotiation, decompression limits, prepared-manifest authorization, per-item
+  content verification, bounded concurrency, and one-transaction bulk storage.
+  The physical request limit chunks unbounded logical transactions; it is not
+  a script or consensus limit.
+- Add optional script-verifier injection to Wallet, setup helpers, and local
+  storage providers. Internal checks use explicit consensus context, distinguish
+  resource exhaustion from invalid scripts, and continue verifying resolvable
+  inputs when another source transaction is intentionally omitted.
+- Retain typed bytes through action-batch planning, hashing, validation, and
+  chunk assembly; preload external inputs and shared metadata once per atomic
+  manifest; and convert Atomic BEEF only at the historical public `number[]`
+  boundary without changing BRC-100 or storage protocol contracts.
+- Make StorageServer, AdminServer, and the reusable ChaintracksService
+  credential-free public-CORS compatible by default, with opt-in exact origin
+  lists and configurable CSP/browser response headers. Add bounded parsers,
+  in-flight work and Node connection limits, stable non-sensitive errors, and
+  metadata-only request logging. Storage RPC work remains protected by
+  BRC-103 identity, per-IP/per-identity limits, method allowlisting, and
+  optional payment policy.
+- Bound StorageServer work per source IP before BRC-103 authentication and per
+  identity before payment/RPC handling. Both stages support shared stores, and
+  proxy trust now requires an explicit hop/subnet/predicate configuration.
+- Harden CWI/WAB account continuity so overlay failures, malformed or ambiguous
+  UMP results, and snapshot-load failures cannot silently enter new-user
+  onboarding. Add an expiring WAB auth session, legacy-compatible WAB account
+  status inference, canonical E.164 phone identity, bounded KDF/snapshot
+  parsing, and fail-closed UMP renewal/broadcast behavior.
+- Replace WAB's endpoint-by-endpoint raw `fetch` calls with one typed transport
+  enforcing HTTPS (localhost excepted), timeouts, request/response limits,
+  redirect and ambient-credential protection, correlation IDs, and privacy-safe errors.
+  Wallet authentication, UMP, WAB, and snapshot events now support the SDK's
+  opt-in generic telemetry sink without reporting keys, snapshots, payloads,
+  OTPs, or Shamir shares.
+- Add automatically negotiated, in-memory planning for dependent `noSend` workloads. Capable
+  storage providers reserve funding once, perform middle action planning and signing without
+  persistence round trips, and atomically commit the complete workspace on `sendWith`. Existing
+  BRC-100 arguments and results are unchanged, and providers without `actionBatch: 1` retain the
+  legacy path. SQLite, MySQL/Knex, IndexedDB, authenticated remote clients, browser, and mobile
+  builds share the same capability contract.
+- Add leased per-output batch reservations, expiry cleanup, adaptive pool extension, idempotent
+  manifest commits, inline content-addressed blobs up to 4 MiB, and authenticated binary uploads
+  in provider-sized chunks with four-way bounded concurrency for larger batches. Broadcast remains
+  outside the atomic persistence transaction.
+- Make batch funding converge on fragmented wallets at production fee rates. Reservation targets
+  include the fee and viable-change overhead of an added input, reactive extensions request only
+  the remaining shortfall, and EWMA runway extensions subtract unconsumed reserved funding without
+  compounding after empty or partial responses. The regression runs 16 independent actions through
+  both the in-process and authenticated remote-storage paths and commits the complete batch.
+- Bind remote batch authorization exclusively to the BRC-103 authenticated identity and its active
+  storage provider, ignoring caller-supplied user IDs and active-state claims. Restrict JSON-RPC
+  dispatch to the public remote-storage protocol so authenticated callers cannot invoke low-level
+  provider methods, and rate-limit authenticated RPCs per identity key without limiting workspace
+  length. Unauthenticated and cross-user batch-management regressions cover the boundary.
+- Replace the cumulative 64-output reservation ceiling with repeatable extensions bounded to 64
+  outputs per storage call. Workspaces and spend chains no longer have an action-count or confirmed
+  funding-input ceiling; an 80-action independent batch crosses the old boundary and commits.
+- Add a retained workload benchmark covering 1, 10, 50, and 250 actions across dependent,
+  independent, mixed-input, and two-step signing models, four script sizes, and 25/100/250 ms
+  storage latency. Run it with `pnpm --filter @bsv/wallet-toolbox bench:action-batch`.
 - Release prep for `2.4.2`: transaction-pipeline, BEEF fetching, and binary transport
   performance improvements described below, published in lockstep for Node, browser, and mobile.
 - Transaction pipeline performance: reuse parsed BEEF through `createAction`/`signAction`, retain
@@ -34,7 +114,7 @@ attention to changes that materially alter behavior or extend functionality.
   `auth-express-middleware@2.1.1` likewise declares its `mime-types` runtime
   import so strict package managers do not fail when loading the built packages.
 
-- Release prep for `2.4.2`: proof completion now discovers every local
+ - Release prep for `2.4.2`: proof completion now discovers every local
    transaction row sharing the proven txid, repairs notification-set drift from
    concurrent multi-user `internalizeAction` calls, and idempotently completes
    any local copy omitted by a last-writer-wins notification update.

package/LICENSE.txt

@@ -0,0 +1,58 @@
+Open BSV License Version 6 – granted by BSV Association, Alpenstrasse 15, 6300
+Zug, Switzerland (CHE-427.008.338) ("Licensor"), to you as a user (henceforth
+"You", "User" or "Licensee").
+
+For the purposes of this license, the definitions below have the following
+meanings:
+
+"Bitcoin Protocol" means the protocol implementation, cryptographic rules,
+network protocols, and consensus mechanisms in the Bitcoin White Paper as
+described here https://protocol.bsvblockchain.org.
+
+"Bitcoin White Paper" means the paper entitled 'Bitcoin: A Peer-to-Peer
+Electronic Cash System' published by 'Satoshi Nakamoto' in October 2008.
+
+"BSV Blockchain" means:
+
+  (a) the Bitcoin blockchain containing block height #556767 with the hash
+      "000000000000000001d956714215d96ffc00e0afda4cd0a96c96f8d802b1662b" and
+      that contains the longest honest persistent chain of blocks which has been
+      produced in a manner which is consistent with the rules set forth in the
+      Network Access Rules; and
+  (b) the test blockchains that contain the longest honest persistent chains of
+      blocks which has been produced in a manner which is consistent with the
+      rules set forth in the Network Access Rules.
+
+"Network Access Rules" or "Rules" means the set of rules regulating the
+relationship between BSV Association and the nodes on BSV based on the Bitcoin
+Protocol rules and those set out in the Bitcoin White Paper, and available here
+https://bsvblockchain.org/network-access-rules.
+
+"Software" means the software the subject of this license, including any/all
+intellectual property rights therein and associated documentation files.
+
+BSV Association grants permission, free of charge and on a non-exclusive basis
+to any person obtaining a copy of the Software to deal in the Software, 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 and conditioned upon the following
+conditions:
+
+1 - The text "© BSV Association", and this license shall be included in all
+copies or substantial portions of the Software.
+
+2 - The Software, and any software that is derived from the Software or parts
+thereof, may only be used exclusively on the BSV Blockchain.
+
+For the avoidance of doubt, this license is granted subject to and conditioned
+upon your compliance with these terms only and is limited to uses on the BSV
+Blockchain. Any exercise of rights not compliant with these terms including
+use not for the BSV Blockchain is deemed outside the scope of the license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES REGARDING ENTITLEMENT,
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS THEREOF 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

@@ -14,17 +14,17 @@ BSV Desktop and BSV Browser are the BSV Association reference wallet application
 
 ### What's Inside
 
-| Module | Description |
-|--------|-------------|
-| **Wallet** | Full BRC-100 wallet — action creation, signing, certificate management, identity discovery, output tracking |
-| **Storage** | Pluggable persistence with three backends: **SQLite/MySQL** (via Knex), **IndexedDB** (browser/mobile), and **remote** (client/server over HTTP) |
-| **Services** | Network layer — ARC transaction broadcasting, chain tracking (Chaintracks), merkle proof verification, UTXO lookups via WhatsOnChain |
-| **Monitor** | Background daemon that watches pending transactions, rebroadcasts failures, handles chain reorganizations, and manages proof acquisition |
-| **Signer** | `WalletSigner` bridges any BRC-100 wallet to the SDK's `Transaction` signing interface |
-| **Key Management** | `PrivilegedKeyManager` for secure key storage with Shamir secret sharing and obfuscation; protocol-based key derivation per BRC-42/43 |
-| **Permissions** | `WalletPermissionsManager` for fine-grained per-app, per-protocol permission control with grouped approval flows |
-| **MockChain** | In-memory blockchain for testing — mock mining, UTXO tracking, and merkle proof generation without a network |
-| **Entropy** | `EntropyCollector` gathers mouse/touch entropy for high-quality randomness in browser environments |
+| Module             | Description                                                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Wallet**         | Full BRC-100 wallet — action creation, signing, certificate management, identity discovery, output tracking                                      |
+| **Storage**        | Pluggable persistence with three backends: **SQLite/MySQL** (via Knex), **IndexedDB** (browser/mobile), and **remote** (client/server over HTTP) |
+| **Services**       | Network layer — ARC transaction broadcasting, chain tracking (Chaintracks), merkle proof verification, UTXO lookups via WhatsOnChain             |
+| **Monitor**        | Background daemon that watches pending transactions, rebroadcasts failures, handles chain reorganizations, and manages proof acquisition         |
+| **Signer**         | `WalletSigner` bridges any BRC-100 wallet to the SDK's `Transaction` signing interface                                                           |
+| **Key Management** | `PrivilegedKeyManager` for secure key storage with Shamir secret sharing and obfuscation; protocol-based key derivation per BRC-42/43            |
+| **Permissions**    | `WalletPermissionsManager` for fine-grained per-app, per-protocol permission control with grouped approval flows                                 |
+| **MockChain**      | In-memory blockchain for testing — mock mining, UTXO tracking, and merkle proof generation without a network                                     |
+| **Entropy**        | `EntropyCollector` gathers mouse/touch entropy for high-quality randomness in browser environments                                               |
 
 ### Packages
 
@@ -63,11 +63,13 @@ const wallet = await SetupWallet({
 // Create a transaction
 const result = await wallet.createAction({
   description: 'Send payment',
-  outputs: [{
-    lockingScript: '76a914...88ac',
-    satoshis: 1000,
-    outputDescription: 'payment'
-  }]
+  outputs: [
+    {
+      lockingScript: '76a914...88ac',
+      satoshis: 1000,
+      outputDescription: 'payment'
+    }
+  ]
 })
 ```
 
@@ -79,6 +81,10 @@ See [Managed change, sweeping, and recovery](./docs/managed-change-policy.md)
 for the default-basket invariant, automatic funding policy, and supported
 `internalizeAction` repair paths.
 
+See [In-memory action batch planning](./docs/action-batch-planning.md) for
+capability-negotiated `noSend` planning, compact manifests, compressed binary
+pack transport, atomic commit, compatibility behavior, and retained benchmarks.
+
 The codebase has detailed JSDoc annotations throughout — these will surface inline in editors like VS Code.
 
 ### Horizontal Storage scaling
@@ -88,11 +94,7 @@ running multiple processes or replicas behind a non-sticky load balancer, use
 the shared Knex implementation against the same migrated wallet database:
 
 ```typescript
-import {
-  KnexSessionManager,
-  StorageKnex,
-  StorageServer
-} from '@bsv/wallet-toolbox'
+import { KnexSessionManager, StorageKnex, StorageServer } from '@bsv/wallet-toolbox'
 
 const storage = new StorageKnex(storageOptions)
 await storage.migrate(storageName, storageIdentityKey)
@@ -107,11 +109,36 @@ const server = new StorageServer(storage, {
   wallet,
   monetize: false,
   sessionManager,
+  // Optional: exact trusted proxy chain. Omit for direct-socket IPs.
+  trustProxy: 1,
+  // Per-IP before auth (default 300/minute).
+  preAuthRateLimit: { limit: 300, windowMs: 60_000 },
+  // Per-identity before payment/RPC work (default 1,000/minute).
+  rateLimit: { limit: 1_000, windowMs: 60_000 },
+  // Public CORS is the default. Supply exact origins to opt into a whitelist.
+  allowedOrigins: process.env.WALLET_ALLOWED_ORIGINS?.split(','),
+  // Optional CSP/security-header overrides for an embedding deployment.
+  securityHeaders: {
+    contentSecurityPolicy: "default-src 'none'"
+  },
   logRpcRequests: false
 })
 server.start()
 ```
 
+Both stages return HTTP 429 with `ERR_RATE_LIMITED`. For multi-process or
+multi-replica deployments, configure a shared `express-rate-limit` store in
+both options so limits are aggregate rather than per process. Never use a
+permissive trust-all proxy setting; use a known hop count, subnet, or trust
+predicate.
+
+The storage service is intentionally reachable by browser apps on previously
+unknown domains. With no origin configuration it uses public wildcard CORS
+without cookie credentials. Passing `allowedOrigins`, setting
+`WALLET_STORAGE_CORS_MODE=allowlist`, or setting the mode to `disabled`
+provides opt-in restriction. BRC-103 authentication and optional payment
+policy are unchanged by CORS mode.
+
 Every replica must share the same database and session TTL. Run
 `sessionManager.pruneExpiredSessions()` from one scheduled maintenance worker;
 reads exclude expired rows even before they are physically pruned. Once every
@@ -128,36 +155,71 @@ does not apply schema changes.
 git clone https://github.com/bsv-blockchain/ts-stack.git
 cd ts-stack
 pnpm install
-pnpm --filter @bsv/wallet-toolbox run build
+pnpm --filter @bsv/wallet-toolbox format:check
+pnpm --filter @bsv/wallet-toolbox lint
+pnpm --filter @bsv/wallet-toolbox typecheck
 pnpm --filter @bsv/wallet-toolbox test
+pnpm --filter @bsv/wallet-toolbox test:coverage
+pnpm --filter @bsv/wallet-toolbox pack:check
+pnpm --filter @bsv/wallet-toolbox-client test:browser
+pnpm --filter @bsv/wallet-toolbox-mobile test:mobile
 ```
 
-Tests use Jest. Files named `*.man.test.ts` are manual/integration tests excluded from CI — they require network access or long runtimes and are run locally by developers.
+Tests use Jest. The default and coverage suites are deterministic and must not
+depend on live third-party services. Files named `*.man.test.ts` are explicit
+manual/integration tests excluded from CI because they require credentials,
+network access, or long runtimes. Files named `*.live.test.ts` are public-network
+checks, also excluded from deterministic PR coverage. Run exactly one governed
+suite with `test:manual -- <path>` or `test:live -- <path>` after reviewing
+`governance/test-quality/policy.json`; never batch-run operator suites. CI
+merges four Wallet Toolbox coverage shards
+for reporting; the complete local `test:coverage` run currently measures
+69.12% statements, 59.09% branches, 72.83% functions, and 71.06% lines.
+
+Operational repair, migration, export, and long-running service procedures are
+not tests. They live under [`operator/`](./operator/README.md), produce an exact
+dry-run plan by default, and require explicit confirmation before they write
+state or artifacts. The exact manual-suite disposition inventory in
+`governance/test-quality/wallet-toolbox-manual-suites.json` prevents new
+operator procedures, fixture generators, diagnostics, or examples from being
+silently added as Jest suites.
+
+Reusable source recipes live under [`examples/`](./examples/README.md). Manual
+integration suites may validate an example against an explicitly configured
+environment, but the example implementation itself does not live inside a test
+body.
+
+`pack:check` installs the exact CommonJS tarball and verifies its public API.
+The browser and mobile commands build platform-specific packages and reject
+Node-only dependency leakage. Publishing and version changes are owned by the
+repository release workflow.
 
 ## Contributing
 
 We welcome bug reports, feature requests, and pull requests.
 
 1. Fork and clone the repository
-2. `npm install`
+2. `pnpm install` at the `ts-stack` repository root
 3. Create a feature branch
-4. Make your changes and ensure `npm test` passes
+4. Make your changes and run the relevant package checks above
 5. Open a pull request
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for full guidelines.
+See the
+[repository contribution guidelines](https://github.com/bsv-blockchain/ts-stack/blob/main/CONTRIBUTING.md)
+for the full stack-wide policy.
 
 ## Contributors
 
-| | Name | GitHub | Role |
-|---|------|--------|------|
-| | Tone Engel | [@tonesnotes](https://github.com/tonesnotes) | Lead developer, maintainer |
-| | Darren Kellenschwiler | [@sirdeggen](https://github.com/sirdeggen) | Core contributor |
-| | Brayden Langley | [@BraydenLangley](https://github.com/BraydenLangley) | Core contributor |
-| | Ty Everett | [@ty-everett](https://github.com/ty-everett) | Core contributor, reviewer |
-| | Jackie Lu | [@jackielu3](https://github.com/jackielu3) | Contributor |
-| | David Case | [@shruggr](https://github.com/shruggr) | Contributor |
-| | Stephen Thomson | [@Stephen-Thomson](https://github.com/Stephen-Thomson) | Contributor |
-| | Chance Barimbao | [@ChanceBarimbao](https://github.com/ChanceBarimbao) | Contributor |
+|     | Name                  | GitHub                                                 | Role                       |
+| --- | --------------------- | ------------------------------------------------------ | -------------------------- |
+|     | Tone Engel            | [@tonesnotes](https://github.com/tonesnotes)           | Lead developer, maintainer |
+|     | Darren Kellenschwiler | [@sirdeggen](https://github.com/sirdeggen)             | Core contributor           |
+|     | Brayden Langley       | [@BraydenLangley](https://github.com/BraydenLangley)   | Core contributor           |
+|     | Ty Everett            | [@ty-everett](https://github.com/ty-everett)           | Core contributor, reviewer |
+|     | Jackie Lu             | [@jackielu3](https://github.com/jackielu3)             | Contributor                |
+|     | David Case            | [@shruggr](https://github.com/shruggr)                 | Contributor                |
+|     | Stephen Thomson       | [@Stephen-Thomson](https://github.com/Stephen-Thomson) | Contributor                |
+|     | Chance Barimbao       | [@ChanceBarimbao](https://github.com/ChanceBarimbao)   | Contributor                |
 
 ## License
 

package/docs/README.md

@@ -9,7 +9,9 @@ The documentation is split into various pages, each covering a set of related fu
 - [Storage](./storage.md) — Wallet data persistent storage classes and related APIs.
 - [Services](./services.md) — Support for abstracted external network services.
 - [Monitor](./monitor.md) — Background task manager for wallet action validation and processing.
+- [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.
 
 ## Open API
 
@@ -83,4 +85,4 @@ const rw = await wallet.internalizeAction(args)
 console.log(rw.accepted)
 ```
 
-[Return to Top](#bsv-wallet-toolbox-api-documentation)
+[Return to Top](#bsv-wallet-toolbox-api-documentation)

package/docs/action-batch-planning.md

@@ -0,0 +1,220 @@
+# In-memory action batch planning
+
+Wallet Toolbox can plan a sequence of `noSend` actions in memory and commit it
+atomically when the application uses `sendWith`. This removes per-action storage
+round trips without changing the BRC-100 wallet interface, action arguments, or
+result shapes. Applications continue to create, sign, and send actions exactly as
+before.
+
+## Negotiation and compatibility
+
+`WalletArgs.actionBatchMode` accepts `auto` (the default) or `legacy`. In `auto`
+mode, the wallet asks its active storage provider for capabilities once. A provider
+advertising `actionBatch: { version: 1, ...limits }` enables local planning. A
+provider without that capability uses the existing persistence flow before any
+workspace begins. A workspace never mixes storage modes or changes active provider.
+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.
+
+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.
+
+The capability and its methods are Wallet Toolbox storage extensions. They do not
+extend `WalletInterface`, `CreateActionArgs`, `SignActionArgs`, `noSend`,
+`noSendChange`, `sendWith`, or their results.
+
+## Lifecycle
+
+1. The first `noSend` action begins a workspace, reserves the canonical funding
+   inputs needed for that action plus limited headroom, and returns their proof
+   data in one storage call. Format 2 sends only planning metadata and exact
+   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.
+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.
+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.
+
+Intermediate state is deliberately session-scoped. If the wallet process exits,
+the uncommitted transaction workspace is lost and its durable reservations expire
+or are released by cleanup. The final commit is the remote durability boundary.
+
+## Reservations and cleanup
+
+Reservations belong to individual outputs, not the wallet. Other wallet activity
+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.
+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
+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.
+
+## Atomic commit and payload transport
+
+The provider checks graph order, duplicate spends, scripts, TXIDs, signatures,
+fees, commissions, leases, and output metadata before persistence. Transactions,
+outputs, labels, tags, maps, and proof requests are written under one database
+transaction together with reservation consumption and release. Batch ID plus a
+semantic manifest digest makes persistence retries idempotent.
+
+Content-addressed raw transactions and the external dependency BEEF travel
+inline for batches up to the provider's inline limit (4 MiB by default). Larger
+format-2 workspaces prepare a compact digest-only manifest and upload only the
+content-addressed physical blobs the server reports missing. Multiple blobs
+share one `ABP1` binary pack, bounded by the provider's advertised request size
+and item count. Packs use the first mutually supported `CompressionStream`
+encoding (`gzip`, then optional Brotli) when it reduces bytes; otherwise they
+use identity encoding.
+
+The client sends no HTTP `Content-Encoding` header: a dedicated authenticated
+pack-encoding header describes the exact request body seen by BRC-103. The
+server bounds both compressed request bytes and decompressed pack bytes,
+validates the frame, every SHA-256 digest, prepared-manifest authorization,
+batch ownership, and hard lifetime, then inserts the pack in one storage
+transaction. The final JSON-RPC call sends only the batch ID and semantic
+manifest digest. The server commits the exact prepared manifest retained under
+that digest.
+
+Logical blobs are split at the provider's advertised limit (8 MiB by default),
+deduplicated by digest, and uploaded with at most four concurrent requests. The
+8 MiB value is a physical request target, not a logical transaction limit: one
+transaction or dependency BEEF may span any number of chunks. There is no
+consensus script-size limit in this path. Incomplete uploads remain scoped to
+their authenticated batch and expire with it.
+
+Allocation failure in a particular JavaScript host remains a local resource
+failure. It is reported as an operation/runtime failure rather than evidence that
+the transaction or script is consensus-invalid.
+
+The planner, validator, digest pipeline, browser IndexedDB store, and chunk
+assembler retain `Uint8Array` storage throughout this path. SQL adapters create
+buffer views only at the driver boundary. Atomic commit also preloads blob rows,
+external inputs, baskets, tags, and labels once per manifest instead of
+repeating those lookups for every action. It stores only the external input
+proof frontier for each persisted request and reuses the already validated
+complete BEEF graph for immediate/delayed share preparation. The full graph is
+still reconstructed and verified before persistence. These are storage
+implementation details; BRC-100 arguments and results are unchanged.
+
+Wallet and locally hosted storage construction can receive an optional
+`scriptVerifier`. Batch and ordinary action checks pass explicit consensus
+context and known source-output heights to that verifier. A provider with a
+packed Spend lane verifies all selected staged inputs in one backend scheduling
+pass, allowing a warm native/WASM implementation to handle large scripts without
+changing the wallet contract. If no verifier is supplied, the SDK TypeScript
+interpreter remains the default.
+
+Verifier configuration is process- or page-local. A browser or local wallet
+verifier accelerates checks performed by that wallet; it is not serialized over
+BRC-100 or storage RPC. A remote storage process must create, preload, and inject
+its own verifier into `StorageKnex` if server-side atomic-commit checks should use
+the same backend. Backend initialization, ABI, or memory failures propagate as
+operational failures and are never rewritten as invalid-script verdicts.
+
+## Deployment behavior for large scripts
+
+| Deployment | Before these changes | Current behavior |
+| --- | --- | --- |
+| Local Node wallet with Knex | TypeScript execution was the normal path; its default 32 MiB stack budget could turn local exhaustion into an invalid-action error. Repeated action persistence added storage round trips and row lookups. | A preloaded verifier can execute ordinary and batch checks in explicit consensus mode. Default JS execution has no arbitrary consensus stack cap. `noSend` chains plan in memory, bulk-load shared rows, and commit atomically. |
+| Browser wallet with IndexedDB | Large byte values were commonly boxed or hex/string copied, and validation stayed on the TypeScript interpreter. | Browser VeriFast uses the same consensus context and typed-byte paths. IndexedDB stores packed blobs in one transaction and the wallet receives the configured verifier. Host quota or memory exhaustion remains a browser resource failure, not consensus invalidity. |
+| Browser/Node wallet using remote Toolbox storage | The first large action and later commit values could encounter JSON/body limits; repeated scripts appeared in several JSON/manifest fields; every blob needed a request; and server verification could not be configured independently. | Compact bootstrap and format-2 manifests derive scripts from signed transactions. Manifest-authorized, compressed, multi-blob binary packs avoid JSON expansion and reduce request count. Digest-only commit makes the final request small. Client and server independently preload/inject verifiers, and server commit batches selected spends. |
+
+For latency-sensitive startup, call `await verifier.preload()` before constructing
+or first using the wallet. The default adaptive mode deliberately lets a cold
+first call use the TypeScript interpreter while WASM warms in the background;
+`mode: 'always'` instead waits for WASM. In a remote deployment, repeat that
+startup step in both the client runtime and every storage-server process.
+
+The remaining transport boundaries are resource and protocol facts rather than
+consensus limits. Raw action-batch pack requests stay bounded and logical values
+chunk around that bound. Cicada/Wallet Wire uses typed bytes and zero-copy frame
+handoffs. Browser XDM uses structured clone. HTTP JSON and React Native retain
+their existing BRC-100 encodings, so operators must configure infrastructure
+request limits for ordinary non-batched calls or use action batching for
+multi-megabyte transaction flows.
+
+The remote server derives the batch user ID and active-storage state from the
+BRC-103 authenticated identity for every management call and binary upload.
+Caller-supplied user IDs or active-state claims are never authoritative, and the
+JSON-RPC dispatcher exposes only the public remote-storage protocol rather than
+low-level provider methods. Authenticated RPC and blob requests are rate-limited
+by identity key without limiting the number of actions, transactions, or blobs
+in a workspace; operators can configure the rate and a shared multi-replica
+store through `WalletStorageServerOptions.rateLimit`.
+
+## Rollout and measurement roadmap
+
+The compatibility boundary permits a server-first rollout: deploy schema and
+provider support, then deploy clients in `auto` mode. Old clients ignore the
+capability; new clients fall back against old providers. Operators can use
+`actionBatchMode: 'legacy'` for controlled comparisons.
+
+The retained benchmark is the performance regression gate:
+
+```bash
+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
+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.
+
+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
+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
+track reservation conflicts, extensions, expiries, commit retries, pack
+compression, upload deduplication, commit duration, and broadcaster review
+outcomes by provider type.