@bopen-io/wallet-toolbox 2.1.21-parity-fix.2 → 2.6.2-brc153.1

package/README.md

@@ -1,37 +1,30 @@
 # BSV Wallet Toolbox
 
-[![Build Status](https://img.shields.io/github/actions/workflow/status/bsv-blockchain/wallet-toolbox/push.yaml?branch=master&label=build)](https://github.com/bsv-blockchain/wallet-toolbox/actions)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/bsv-blockchain/ts-stack/ci.yml?branch=main&label=build)](https://github.com/bsv-blockchain/ts-stack/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@bsv/wallet-toolbox)](https://www.npmjs.com/package/@bsv/wallet-toolbox)
 [![npm downloads](https://img.shields.io/npm/dm/@bsv/wallet-toolbox)](https://www.npmjs.com/package/@bsv/wallet-toolbox)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
-[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
-[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
-[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
-[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
-[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=bugs)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
-[![CodeQL](https://github.com/bsv-blockchain/wallet-toolbox/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/bsv-blockchain/wallet-toolbox/actions/workflows/github-code-scanning/codeql)
-[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
-[![License](https://img.shields.io/github/license/bsv-blockchain/wallet-toolbox)](./LICENSE.txt)
-
-A [BRC-100](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0100.md) conforming wallet implementation for the BSV blockchain, built on the [BSV SDK](https://bsv-blockchain.github.io/ts-sdk). Provides persistent storage, protocol-based key derivation, transaction monitoring, chain tracking, and signing — everything needed to build wallet-powered applications on BSV.
+
+A [BRC-100](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0100.md) conforming wallet implementation for the BSV blockchain, built on the [BSV SDK](https://bsv-blockchain.github.io/ts-stack/packages/sdk/). Provides persistent storage, protocol-based key derivation, transaction monitoring, chain tracking, and signing — everything needed to build wallet-powered applications on BSV.
 
 ## Overview
 
 The Wallet Toolbox is the reference implementation of the BRC-100 wallet interface. It connects the BSV SDK's cryptographic primitives to real storage backends, network services, and signing flows so that application developers don't have to wire these layers together themselves.
 
+BSV Desktop and BSV Browser are the BSV Association reference wallet applications built around this interface. Vendor distributions, including Babbage's Metanet Desktop / Metanet Explorer and Hudos Browser, can implement the same BRC-100 interface against their own product packaging and service defaults.
+
 ### 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
 
@@ -41,6 +34,34 @@ The toolbox publishes three npm packages from this repo:
 - **[`@bsv/wallet-toolbox-client`](https://www.npmjs.com/package/@bsv/wallet-toolbox-client)** — Browser build; excludes Node-only backends (Knex/SQLite/MySQL)
 - **[`@bsv/wallet-toolbox-mobile`](https://www.npmjs.com/package/@bsv/wallet-toolbox-mobile)** — Mobile build; IndexedDB and remote storage only
 
+### ChainTracks sources and networks
+
+Wallet services do not require a WhatsOnChain key for ChainTracks. Mainnet,
+testnet, and TerraTestNet use the public Arcade/go-chaintracks v2 HTTP and SSE
+surfaces by default. Bulk batches still pass through local serialization, hash,
+continuity, and genesis checks; providers are tried in priority order; and a
+synchronized tracker can continue serving its last-good checked data during a
+provider outage. WhatsOnChain remains a mainnet/testnet fallback and anonymous
+requests are serialized below its documented public rate.
+
+The supported chain identifiers are `main`, `test`, `stn`, `ttn`, and `tstn`
+(`mock` remains available for test utilities). STN and Terra Scaling TestNet do
+not have operator-independent public endpoints: set `STN_CHAINTRACKS_URL` or
+`TSTN_CHAINTRACKS_URL`, use the matching Arcade environment variable, or inject
+an explicit `ChaintracksClientApi`. URLs ending in `/v2` use the reconnecting
+go-chaintracks client; existing legacy v1 URLs and explicit clients remain
+compatible. Browser and mobile distributions expose the same fetch/SSE client
+without Node `Buffer` or filesystem dependencies.
+
+Arcade is the browser-safe HTTPS/SSE gateway for Teranode-backed header data.
+Direct Teranode P2P is not included in browser/mobile artifacts.
+
+Core ChainTracks factories accept a final source-options argument when an
+application must override the defaults. Set `disableChaintracks`, `disableCdn`,
+or `disableWhatsOnChain` to `true` to opt out of an automatic source, or pass an
+explicit `chaintracks` client to retain an existing deployment topology. All
+earlier positional arguments remain unchanged.
+
 ## Getting Started
 
 ### Installation
@@ -70,56 +91,224 @@ 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'
+    }
+  ]
 })
 ```
 
+Completed `createAction` and `signAction` results from the public Wallet
+interface return Atomic BEEF in `tx` as a numeric array. This preserves the
+historical BRC-100 shape across plain JSON bridges; parse it with
+`Transaction.fromAtomicBEEF(result.tx)`. The `AtomicBEEF` type and binary Wallet
+Wire transports also support `Uint8Array`.
+
 ## Documentation
 
 [Full API documentation](https://bsv-blockchain.github.io/wallet-toolbox) is available on GitHub Pages.
 
+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.
+
+### `createAction` performance telemetry
+
+With the optional SDK telemetry sink enabled, legacy `createAction` reports
+bounded-cardinality spans for input validation, record/output persistence,
+funding candidate selection, fee-aware planning, atomic input claiming, input
+assembly, proof fetch, BEEF merge, and final trim/serialization.
+Only counts, byte sizes, fee totals, retry counts, and durations are reported;
+transaction IDs, scripts, payloads, keys, and identities are not attributes.
+
+The planner uses the same exact / least-over / largest-under selection policy
+as the historical allocator, but proves economic sufficiency before writing a
+transaction and claims every selected input in one database transaction. Knex
+storage automatically adds a composite funding-selection index on migration;
+IndexedDB schema version 3 adds corresponding user/basket and outpoint indexes
+and resolves transaction-status eligibility in one indexed pass.
+
+The retained fragmented-funding benchmark is runnable with:
+
+```bash
+pnpm bench:create-action-funding
+pnpm bench:create-action-beef
+```
+
+Against unmodified commit `c212b5ee7`, a representative 102-input SQLite plan
+fell from 622 queries, 102 database transactions, and 107.3 ms to 17 queries,
+one transaction, and 8.8 ms. Query and transaction counts remain flat when the
+selected input count grows; networked database deployments should benefit most.
+
+The proof-bearing benchmark also exercises the authenticated remote wallet,
+real BRC-103 storage RPC, BRC-29 signing, packed WASM digest verification, and
+24-level proofs grouped by block. On the PXC staging topology, 20 independent
+153-input samples measured 376.0 ms p50 and 461.6 ms p95; the corresponding
+direct storage cohort measured 99.3 ms p50 and 137.4 ms p95. A normal one-input
+authenticated cohort measured 78.6 ms p50 and 105.6 ms p95. All 3,080 signature
+verdicts passed. A selective production-shaped database copy with 110 fragmented
+inputs measured 75.5 ms p50 and 155.4 ms p95 for direct storage. The benchmark
+captures client, server HTTP, authentication, RPC, storage, signing,
+verification, and serialization spans and retains gates of 100 ms p50 / 150 ms
+p95 for the normal cohort and 500 ms p95 for the 153-input cohort. These are
+regression gates, not universal hardware guarantees.
+
+Trace context remains local to the telemetry carrier and sink. Wallet Toolbox
+does not add telemetry headers to AuthFetch, so BRC-103/104, Auth Express
+Middleware, AuthSocket, JSON-RPC, and mixed-version remote storage behavior are
+unchanged.
+
 The codebase has detailed JSDoc annotations throughout — these will surface inline in editors like VS Code.
 
+### Horizontal Storage scaling
+
+`StorageServer` uses an in-process BRC-103 session manager by default. Before
+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'
+
+const storage = new StorageKnex(storageOptions)
+await storage.migrate(storageName, storageIdentityKey)
+await storage.makeAvailable()
+
+const sessionManager = new KnexSessionManager(storage.knex, {
+  ttlMs: 24 * 60 * 60 * 1000,
+  // Optional. Set to 0 when every authenticated use must update the row.
+  touchIntervalMs: 60 * 1000
+})
+
+const server = new StorageServer(storage, {
+  port: 3000,
+  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()
+```
+
+Shared Knex sessions immediately persist authentication, nonce, identity, and
+certificate-state transitions. For an already-authenticated row, the default
+manager coalesces only timestamp-only usage touches for up to one minute. This
+avoids a synchronous replicated write on every RPC while keeping durable expiry
+within a bounded minute of the most recent use. Use `touchIntervalMs: 0` to
+retain exact per-request timestamp persistence.
+
+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
+replica uses the shared manager, authenticated requests no longer require
+client-IP or cookie affinity.
+
+Run `StorageKnex.migrate(...)` before constructing the manager during an
+upgrade. `makeAvailable()` validates and loads an already-migrated database; it
+does not apply schema changes.
+
 ## Development
 
 ```bash
-git clone https://github.com/bsv-blockchain/wallet-toolbox.git
-cd wallet-toolbox
-npm install
-npm run build
-npm test
+git clone https://github.com/bsv-blockchain/ts-stack.git
+cd ts-stack
+pnpm install
+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.