@bsv/wallet-toolbox 2.4.4 → 2.4.20

package/CHANGELOG.md

@@ -6,6 +6,49 @@ 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

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/action-batch-planning.md

@@ -13,6 +13,16 @@ mode, the wallet asks its active storage provider for capabilities once. A provi
 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`,
@@ -22,10 +32,15 @@ extend `WalletInterface`, `CreateActionArgs`, `SignActionArgs`, `noSend`,
 
 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.
+   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 and content-addressed locking-script blobs avoid retaining
-   repeated ancestry and script copies.
+   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.
@@ -77,12 +92,81 @@ 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, dependency BEEF, and locking scripts travel
+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
-workloads prepare a manifest, upload only missing blobs through authenticated raw
-binary requests, and commit by 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. Incomplete uploads expire with their batch.
+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.
@@ -106,12 +190,31 @@ The retained benchmark is the performance regression gate:
 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. Production rollout should additionally track reservation
-conflicts, extensions, expiries, commit retries, upload deduplication, commit
-duration, and broadcaster review outcomes by provider type.
+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.