@bsv/wallet-toolbox 2.12.0 → 2.13.2

package/README.md

@@ -6,12 +6,109 @@
 
 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.
 
+## Backup and sync: tested results
+
+**Live E2E testing used a large wallet in the native desktop client**, covering
+complete local copies, restart recovery, and repeat sync. Transfer size and oversized-record recovery were
+measured separately with synthetic fixtures. The latest proof-recovery follow-up
+has synthetic HTTP and read-only source-data validation; its live full-backup
+retest is pending.
+
+| Test                         | Verified result                                                                                                                                         |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Full native desktop restores | **Two complete copies; identical entity counts.** Second run: **12m 50s vs 16m 30s (22.3% less time)**.                                                 |
+| Retained local backup        | Completed after cancellation, a connectivity pause, and restart recovery; all **12 entity-store counts preserved** on another restart.                  |
+| Local reads and repeat sync  | Transaction/output reads passed; sampled transaction bytes matched; repeat sync made **0 inserts, 0 updates**.                                          |
+| Transfer size                | **62.7% smaller** encoded byte payload in a synthetic fixture.                                                                                          |
+| Oversized single record      | **7 MiB restored in real browser IndexedDB**, matching SHA-256; interrupted upload resumed, corrupt download rejected, repeat sync unchanged.           |
+| Automated integration        | Authenticated HTTP backup/restore, interrupted pages, lost acknowledgements, binary byte round-trips, user isolation, and legacy compatibility covered. |
+
+Timing compares successive candidates, not a controlled comparison against upstream
+`main`. Byte verification was sampled, not database-wide. See
+[test methods and limits](#sync-performance-and-recovery) for details.
+
+### SQLite migration recovery
+
+The unpublished 2.13.2 candidate runs SQLite migration DDL and the migration
+journal update transactionally. Foreign-key enforcement is disabled before the
+migration transaction for table rebuilds and restored after success or failure.
+Failed migrations can be retried after reopening the database without partial
+schema objects from that attempt. MySQL's existing transaction configuration
+is unchanged.
+
+This prevents future partial migrations. It does not automatically repair a
+store already left with unjournaled schema objects by an older version. Preserve
+the database and verified backups and reconcile the exact schema and migration
+journal before recovery; do not delete journal rows or wallet data blindly.
+
 ## 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.
 
+### Local contact trust
+
+Applications may install a `ContactSource` on `WalletArgs` to resolve identities from the user's
+local contacts before querying the certificate overlay. Installing that source is an explicit
+personal trust-policy decision: a saved contact is locally authoritative in the same sense as a
+self-signed certificate or locally installed trust anchor. Its default infinite trust means “the
+user's independent validation overrides third-party trust thresholds,” not “an external certifier
+proved this identity.”
+
+The authority is scoped to the wallet user who saved the identity-key association and to that
+wallet's local labels and metadata. Authentication or encryption of the contact store proves that
+the wallet retained the user's decision; it does not independently prove the real-world identity,
+and the infinite-trust value must not be exported as a universal claim for other users.
+
+Contact results retain the discovery result shape for compatibility, but default to type `contact`
+and carry empty serial, signature, and revocation-outpoint fields. Consumers must not present those
+fields as third-party certification. Connect `ContactSource` only to local, authenticated storage
+whose records the user has deliberately saved or validated; never populate it directly from
+unauthenticated network data. Pass `forceRefresh: true` to identity discovery when the application
+specifically needs to bypass local contact authority and query the overlay.
+
+### Fiat exchange-rate trust boundary
+
+Wallet Toolbox treats exchange-rate providers and custom service adapters as
+untrusted financial inputs. Rates must use the supported currency codes, be
+finite, positive, and bounded, use USD base with an exact USD rate of 1, and
+carry a valid timestamp no more than five minutes in the future. Malformed or
+missing requested rates are never merged into the wallet cache.
+
+The default provider transport accepts only credential-free public HTTPS,
+pins validated DNS answers in Node.js, rejects redirects and private/special
+addresses, and enforces a 15-second deadline plus a 256 KiB response limit.
+`fiatExchangeRatesFetch` is an explicitly trusted escape hatch for tests or
+controlled local development; production applications should retain the
+default transport.
+
+### ARC and Arcade provider configuration
+
+ARC-compatible broadcaster configuration is snapshotted when the provider is
+constructed. API keys, callback tokens, deployment IDs, callback URLs, and
+custom headers therefore keep the exact reviewed values even if the caller
+later mutates its configuration object. Custom headers must be a plain
+accessor-free own-data map with valid HTTP token names and bounded string
+values; inherited fields and getters are rejected without being used.
+
+The provider URL and an injected `httpClient` remain explicit application or
+operator trust decisions. Do not derive them from transaction, peer, or other
+untrusted input. Reconstruct the provider to rotate credentials or headers;
+mutating the original configuration object does not change a live provider.
+
+### Importing legacy P2PKH outputs
+
+`Setup.fundWalletFromP2PKHOutpoints` and its client equivalent validate each
+canonical outpoint, fetched transaction ID, P2PKH ownership script, atomic
+signing target, and final wallet transaction before reporting success. Provider
+downloads are deadline-bound, redirect-free, and size-bounded; recursive BEEF
+construction also limits depth, graph size, aggregate source bytes, and the
+number of requested outpoints. If an application already has authenticated
+BEEF, pass it explicitly to avoid relying on public transaction-data services.
+Do not accept a wallet result that omits the transaction bytes needed for this
+binding.
+
 ### What's Inside
 
 | Module             | Description                                                                                                                                      |
@@ -31,6 +128,19 @@ broadcast, so permission approval does not inherit network-broadcast latency.
 The funding planner prefers settled change and uses queued permission ancestry
 only as a last resort, keeping the application path fast without hiding funds.
 
+Permission-token basket membership and tags are discovery hints, not authority.
+Before using a stored token, the manager binds it to its exact BEEF outpoint and
+one-satoshi output, verifies the canonical PushDrop field signature and locally
+derived locking key, strictly decodes every signed grant field, and rechecks the
+requested filters against that signed content. Unsigned, foreign-wallet,
+substituted, malformed, or mislabeled rows grant no permission. Token issuance,
+renewal, coalescing, and revocation also bind every requested input and output to
+the final wallet transaction; a partial-action reference never authorizes a
+different transaction. When the underlying Wallet Toolbox signer adds a storage
+service charge, its exact wallet-funded amount is carried locally into the
+spending check so the charge is visible and counted in authorization. This
+metadata is deliberately not a BRC-100 wire extension.
+
 Permission modules may transform calls with `onRequest` and `onResponse`, or
 own a P-scheme's semantics with the optional `handleRequest(request, next)`
 hook. A semantic handler can return the normal BRC-100 result directly; if it
@@ -46,6 +156,19 @@ serialized BEEF plus transaction bytes; queued ancestry is used only when it is
 necessary or smaller. Pending change is never withheld, so queued
 work cannot strand the balance behind a large reserved input.
 
+`sendWith` transaction IDs form one atomic broadcast set: the wallet never
+silently slices that set into separately submitted groups. A set is limited to
+1,000 unique transactions, including a transaction created or signed by the
+current call. Oversized or noncanonical requests are rejected before storage
+commit. The background monitor bounds both discovery and re-expansion of older
+queued batches; an oversized legacy batch is skipped as a whole and reported
+for operator recovery rather than partially broadcast.
+
+`Setup.makeEnv()` returns a development `.env` template containing newly
+generated private keys but never prints it. Callers must deliberately write the
+returned text to a protected local file and must not route it through ordinary
+application, CI, or shared terminal logs.
+
 ### Packages
 
 The toolbox publishes three npm packages from this repo:
@@ -54,10 +177,155 @@ 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; remote wallet storage plus portable local ChainTracks components and adapter contracts
 
+### Sync performance and recovery
+
+Sync pages start at 64 records and adapt after successful commits toward a
+five-second page budget. Proof-bearing pages cap growth at 128 records; cheap
+metadata pages can grow to 1,000, while provider byte/item ceilings still apply.
+The server checks at most eight proofs concurrently and waits for all started
+checks to settle on failure before rejecting the page. Every proof still passes
+transaction, Merkle path, active-root and active-header validation before a merge.
+An authenticated HTTP regression covers 250 synthetic proofs and confirms that
+an invalid follow-up page cannot change the committed checkpoint. Stale proofs
+can be reconciled through another provider, but only after the replacement passes
+the same transaction, membership and active-chain checks. Transaction bytes,
+wallet references and source cursor timestamps are preserved. Corrected destination
+proofs receive a fresh local timestamp for incremental replication. Unverifiable replacements
+stop the page with a recovery message; no record is silently skipped.
+
+A read-only deployment-host sample of 250 proofs took 42.6 seconds with sequential
+validation and 5.58 seconds with bounded concurrency, with the same 250 root and
+250 header checks. This measures validation only, not full-copy throughput.
+Timeouts remain possible during dependency outages; writes are never blindly
+replayed, and resumed sync rereads durable destination progress.
+
+The adaptive page controller and optional validated-proof lookup add a small
+client bundle cost. The [artifact measurements and limits](./docs/sync-transfer.md#artifact-cost-requiring-review)
+include the combined upstream security fixes. These are explicit feature costs;
+the RPC validation coordinator remains excluded from browser/mobile bundles.
+
+The transfer extension is an **unpublished 2.13.0 candidate**. Published 2.12.0
+has no record-transfer methods. Check exact build provenance and authenticated
+runtime capabilities, not a version label alone. An oversized record on a legacy
+source cannot be rescued by upgrading only its destination; upgrade the source
+before retrying. Records exceeding the negotiated 64 MiB frame limit fail safely
+without being skipped or advancing their checkpoint.
+
+Large individual records can use the negotiated
+[bounded transfer protocol](./docs/sync-transfer.md), with durable staging,
+integrity verification and checkpoint replay protection. Its authenticated
+HTTP/SQLite/IndexedDB regression exercises a 7 MiB binary record, an interrupted
+upload across client/server restart, a lost part acknowledgement, corrupted
+download rejection and a verified restore followed by an unchanged resync.
+The current frame limit is 64 MiB; legacy providers must be upgraded to use it.
+It also passes with a one-second delay on every authenticated transport send;
+that models added latency, not a measured bandwidth limit or a real mobile network.
+These synthetic regressions are separate from the large-wallet timing evidence above.
+
 Wallet storage replication applies each received page and its durable sync
 checkpoint in one provider transaction. IndexedDB and Knex therefore avoid
 per-record transaction startup, and a failed page rolls back without advancing
-the checkpoint. The sync wire format and persisted schemas are unchanged.
+the checkpoint. Sources fill each bounded page with adaptive, size-aware reads,
+and Knex storage adds user-scoped proof lookup indexes. Clients may set
+`includeTotals` on a sync-chunk request to receive optional source record totals
+for exact progress reporting. Older providers ignore the hint, and totals are
+not counted unless requested. New clients also send the writer-local sync-state
+identifier selected during provider registration. New providers use it to
+disambiguate legacy duplicate checkpoints, while either side remains compatible
+with older protocol peers. When a provider rejects a sync page because its
+serialized RPC response exceeds the service ceiling, remote clients retry the
+read-only request with a smaller chunk budget and remember the working limit
+for the rest of the session.
+
+Output synchronization requires a local mapping for every non-null source basket
+ID. A missing mapping rejects the page so its transaction and checkpoint can roll
+back; retry after transferring the missing basket. Newer source updates apply
+basket changes, including explicit removal. Same-time or older updates preserve
+local relinquishment. Previously unbasketed records require a verified newer
+source update to repair; no heuristic rewrites existing wallet state.
+
+`StorageKnex.getRawTxOfKnownValidTransaction()` can read a cold store while the
+caller holds a transaction, including SQLite's single-connection pool. Settings
+are read through that transaction without entering the shared cache or starting
+prepared-BEEF background work; ordinary `makeAvailable()` remains the explicit
+store-wide startup operation. An absent optional `inputBEEF` does not prevent
+returning stored raw transaction bytes.
+
+IndexedDB schema version 6 adds a non-unique transaction-ID/user index. Sync
+identity lookups, commissions, and relation maps use selective indexes or exact
+keys instead of scanning the growing wallet for each row. Proof batch checks
+resolve requested transaction IDs through the existing index, preserving primary-key
+ordering, pagination, and proof-validation rules. Existing bytes and
+legacy duplicate transaction IDs are preserved. Databases upgrade automatically;
+older clients that open schema version 5 cannot reopen an upgraded database, so
+keep a compatible client when retaining a local backup.
+
+Updated servers advertise `syncCheckpointVersion: 1` in runtime settings.
+Compatible clients fetch a compact checkpoint once, then use the checkpoint
+returned by each committed page. The complete ID mapping remains durable on
+the writer and is no longer downloaded before every page. Older providers use
+the existing full-state path; authentication, gateway, and malformed checkpoint
+errors remain failures rather than compatibility fallbacks. A retry starts
+from the writer's durable checkpoint. `includeNextCheckpoint` is optional, and
+legacy requests retain their existing response shape.
+
+When a reader negotiates binary JSON, large schema-defined sync byte fields
+are encoded as base64 instead of decimal number arrays. Legacy readers retain
+the existing arrays; unrelated numeric fields are never reinterpreted as bytes.
+Clients with `binaryRequests: true` use the same compact representation for
+sync uploads after the server negotiates binary request support. The default
+request setting is unchanged.
+Binary JSON parsing preserves the existing marker and escaping rules while
+avoiding a JavaScript reviver callback for every scalar byte. The SDK also
+prevents certificate work or session recovery from dispatching another request
+after the caller's authentication deadline has expired. This does not cancel a
+write already received by a server or automatically replay failed writes.
+
+Run the authenticated candidate-provider sync benchmark with:
+
+```sh
+pnpm bench:storage-sync
+```
+
+Set `WALLET_TOOLBOX_BENCH_MYSQL=true`, `MYSQL_CONNECTION`, and optionally
+`WALLET_TOOLBOX_BENCH_MYSQL_DATABASE` to exercise the same fixture through a
+MySQL-backed provider. The benchmark reports HTTP p50/p95 latency and the
+source-query limits used to fill a 250-record page; it is observational rather
+than a cross-machine latency SLA. It also compares the old reviver with the
+current parser on identical synthetic data and measures checkpoint size. On
+one local Node 24 run, a 1 MiB numeric-array fixture (3.74 MB of JSON) measured
+501.2 ms versus 10.1 ms median parsing time across nine alternating samples.
+A synthetic 50,000-entry mapping occupied 678,850 bytes; its compact checkpoint
+occupied 432 bytes. These are CPU and payload measurements, not a claim of the
+same end-to-end network speedup. Encoding the synthetic byte field through
+the negotiated sync codec reduced its JSON payload from 3,743,771 to 1,398,163
+bytes (62.7%).
+
+Retained integration tests cover authenticated HTTP backup and complete restore
+into a fresh IndexedDB store, multipage progression, no-change resync,
+interruption/resume, user isolation, malformed checkpoints, and legacy-provider
+fallback. Live deployment results must be reported separately with the tested
+revision and scope; a partial page sample is not a full restore verification.
+
+A native desktop integration run against candidate runtime
+`a88d18abf14b75a3227016bfd947d5a08b3ee236` completed a full remote-to-local
+copy in 769.5 seconds, compared with 990.3 seconds for the preceding candidate
+run with identical entity counts. Remote reads took 619.2 seconds, local writes
+146.0 seconds, and measurement 4.1 seconds. Proof-page writes fell from 75.7 to
+9.8 seconds after indexed preflight lookup. These are sequential observations,
+not a controlled full-wallet comparison against upstream main. The all-state
+100 ms timer probe reported p95 delay of 908 ms; foreground focus was not recorded,
+so this does not establish foreground UI latency. Separate 90-second native
+foreground probes during a retained backup measured p95 delays of 5 ms for
+transactions, 8 ms for outputs, 10 ms for heavier output pages, and 5 ms for
+proof requests. Their maxima were 60, 51, 298, and 62 ms respectively; these
+samples are not a whole-copy latency guarantee. The retained-backup test also
+verified cancellation at a page boundary and automatic checkpoint recovery after
+a full native app restart. Development testing required refreshing Vite's cached
+linked dependencies to load the candidate schema consistently. See
+[PR486](https://github.com/bsv-blockchain/ts-stack/pull/486) for final integration
+completion and release evidence. Personal deployment and wallet details are
+retained privately, outside this repository.
 
 `listOutputs` reports `totalOutputs` as the full matching result count on every
 page for both Knex and IndexedDB storage, including short final pages and pages
@@ -92,6 +360,25 @@ checks leave multiple valid UMP tokens, and only when the pinned outpoint is
 present in the verified candidates. A pin cannot introduce an outpoint that the
 wallet did not independently retrieve and validate.
 
+UMP renewal consumes only the exact canonical predecessor returned for its
+outpoint. Its signed fields, presentation/recovery hashes, and locally derived
+admin-token locking key are verified before the old token is signed. The manager
+locates the predecessor at its actual input index and accepts the completed
+action only when it preserves every authorized input and output, contains one
+exact one-satoshi replacement token, and reports the transaction's real ID.
+
+WAB faucet funding is subject to the same action-completion binding. The faucet
+response must contain the exact declared Atomic BEEF target and output zero must
+commit to the supplied nonzero R-puzzle scalar. The manager signs that outpoint
+at its actual wallet input index and sends the fee-adjusted balance only to an
+explicit BRC-29 output derived for the authenticated wallet. That output's exact
+script and bounded amount are authorized before signing; an unrequested wallet
+output cannot consume the faucet input. The signed action is staged locally,
+labeled, and recorded in a recovery basket before broadcast. A retry recovers
+and internalizes that exact transaction, or recognizes its already-internalized
+managed output, instead of authorizing a second destination. Missing, reordered,
+substituted, ambiguous, or result-only transactions fail closed.
+
 New WAB registrations are interruption-safe across the off-chain/on-chain
 boundary. A WAB that advertises `registrationStatus: "pending"` lets a verified
 retry reuse the stored presentation key when a clean UMP lookup confirms that
@@ -139,11 +426,31 @@ HTTPS. Plain HTTP is accepted only for explicit loopback hosts during local
 development. Arcade SSE dependency debug logging remains disabled because its
 request URL and headers carry wallet callback credentials.
 
+Remote storage responses must also complete BRC-103 mutual authentication;
+ordinary HTTP fallback responses are rejected. Without an explicit
+`serverIdentityKey`, the first authenticated server identity reached through
+the configured HTTPS endpoint is authoritative for that client instance and
+cannot change during its lifetime. Applications that independently provision
+or validate the server key should pass it as `serverIdentityKey` to pin the
+expected peer from the first response. In either mode, the
+`storageIdentityKey` returned by the authenticated `makeAvailable()` response
+is authoritative for that client instance. It may be distinct from the server
+transport identity; applications that independently provision it can pin it
+with the separate `storageIdentityKey` option. JSON-RPC responses are accepted
+only when their version and request ID match and they contain exactly one of
+`result` or `error`.
+
 Certificate signatures fail closed at every wallet trust boundary. Direct and
 issuer-mediated acquisition require an affirmative certifier-signature result
 before storage, and identity discovery verifies each untrusted overlay
 certificate before decryption or trust scoring.
 
+BRC-100 originators may include a numeric port for compatibility, including
+local-development ports. Permission and administrator authority is deliberately
+scoped to the normalized lowercase hostname: all ports on one hostname are the
+same originator. Existing authenticated permission tokens that recorded a port
+are discovered through a bounded compatibility lookup and compared by hostname.
+
 ### ChainTracks sources and networks
 
 Wallet services do not require a WhatsOnChain key for ChainTracks. Node
@@ -167,6 +474,86 @@ 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.
 
+The configured ChainTracks endpoint remains the authority for the selected
+chain view. Its transport bytes are not trusted blindly: JSON and binary reads
+remain under one deadline and fixed byte ceilings, redirects are rejected, SSE
+events have byte and idle-time limits, and every returned header is canonical,
+proof-of-work-valid, and bound to the requested network, height, or hash before
+use. Binary batches must be exact 80-byte linked sequences. The additive
+`GoChaintracksServiceClientOptions` limits can be lowered for constrained hosts.
+Live metadata is accepted only as a complete record with positive local
+identities. Reorganization deactivation lists are bounded by their declared
+depth, start at the old tip, contain no duplicates, and form one descending
+linked chain before wallet monitor callbacks receive them. Remote diagnostic
+text is reduced to bounded single-line output. The monitor repeats these checks
+at its own trust boundary for custom event adapters, requires every configured
+chain source to match the wallet network, and retains at most 4,096 unique
+deactivated headers by default. `MonitorOptions.maxQueuedDeactivatedHeaders`
+can lower that ceiling. Prepared-proof invalidations are coalesced and drained
+during teardown; partial event subscriptions and rejected application
+callbacks are contained and reported through bounded monitor events.
+The legacy `BHServiceClient` applies the same endpoint, whole-body deadline,
+byte, range, hash, linkage, and proof-of-work checks. Its historical public
+`cache` property remains for source compatibility but is diagnostic only:
+neither callers nor old or rejected roots can make it authoritative, and every
+Merkle-root verdict resolves the current canonical header again so
+reorganizations remain visible.
+Local ChainTracks instances also validate and copy submitted headers, ignore
+duplicate pending submissions, and retain at most 4,096 by default; the live
+SSE adapter applies the same default queue ceiling. Construction rejects
+unsupported networks, unsafe recursion/queue limits, and malformed ingestor
+collections. Library logging is silent by default; applications that need
+operational output must provide the existing optional `logging` callback.
+Startup methods await initialization and surface failures; a failed attempt can
+be retried, while `destroy()` drains sources and releases storage even if the
+instance never became available. Header and reorganization subscriptions are
+bounded, deleted on unsubscribe, and receive isolated snapshots so one listener
+cannot alter another listener's event.
+
+Local persistence treats both stored metadata and adapter calls as integrity
+boundaries. Memory-backed trackers are instance-isolated; IndexedDB and Knex
+require one active tip and one active header per height, reject nonconsecutive
+parent links, bound ancestor walks, and fail closed on malformed state. Knex
+serializes tip mutation with an internal transaction lock row. Run every
+ChainTracks Knex migration before serving traffic. On MySQL, the migration
+changes hex identifiers to `VARCHAR(64)` and cached header bytes to `LONGBLOB`;
+because the former `VARBINARY(32)` representation could irreversibly truncate
+live identifiers, the derived live-header cache is cleared and rebuilt from
+authenticated bulk data during that migration.
+
+To downgrade to code that predates the repair migration, first stop every
+ChainTracks writer and take a verified database backup together with the
+authenticated bulk-header data needed to rebuild the live cache. Using the
+current `ChaintracksKnexMigrations` source, run a targeted `knex.migrate.down`
+for only
+`2026-09-17-001 repair MySQL live-header encodings and bulk blob`. Its `down`
+is intentionally a schema no-op: it removes that migration's ledger entry but
+must leave the repaired `VARCHAR(64)` identifier columns, `LONGBLOB` bulk data,
+the `chaintracks_state` lock row, and authenticated bulk files intact. Validate
+that retained schema and data against the older code in a non-production copy
+before starting it. Never roll down the initial migration, recreate the tables,
+or convert the identifiers back to truncating `VARBINARY(32)` columns.
+
+Bulk-file additions and extensions reach durable storage before becoming
+visible in memory. Reconciliation and any replacement spanning multiple files
+commit atomically in the built-in Knex and IndexedDB adapters, preserve stored
+bytes omitted from an update, and restore the prior manager state on failure.
+Custom `ChaintracksStorageBulkFileApi` implementations remain source compatible,
+but must implement the additive `replaceBulkFiles` method before the manager
+will perform a multi-file replacement; this fail-closed rule prevents a restart
+from observing gaps or overlapping stale rows.
+
+WhatsOnChain is authoritative only when an application deliberately enables it
+as a fallback chain source. URLs returned by its resource manifest are not
+local/operator configuration: they are treated as untrusted locators and must
+remain credential-free public HTTPS. Node downloads resolve, approve, and pin a
+public address into the TLS connection; browser downloads retain HTTPS,
+redirect, CORS, deadline, and byte controls. Resource manifests, recent-header
+JSON, binary files, and legacy WebSocket frames are bounded and strictly
+validated. WebSocket history is admitted in ordered chunks, live queues are
+capped, and every candidate header is canonical and proof-of-work-valid before
+its declared target can affect chain-work selection.
+
 Browser, mobile, and Node applications can instead make a persisted local
 ChainTracks instance their primary SDK `ChainTracker`. Immutable checkpoint
 assets are read through `BulkFileDataCacheApi` before any network request;
@@ -178,13 +565,29 @@ verification through a bounded worker pool; browser and mobile builds retain
 the portable `InlineBulkFileDataValidator`. Filesystem deployments can combine
 the content-addressed, quarantining `BulkFileDataCacheFs` with
 `DurableFileBulkFileDownloadBudget`, which flushes a conservative reservation
-before every physical attempt and preserves the allowance across restarts.
+before every physical attempt, serializes replicas through the shared state
+file, and preserves the allowance across restarts. A crash-abandoned
+`<stateFile>.lock` is deliberately not reclaimed automatically: after proving
+that no writer is active, an operator must remove that narrow lock directory or
+choose a fresh ledger path. Cache files are read only up to their advertised
+size plus one rejection byte and writes must match the advertised SHA-256.
+Cache replacement, promotion, and quarantine are serialized through a
+per-object `<digest>.headers.lock` directory with the same fail-closed,
+operator-confirmed abandoned-lock procedure. Callers may release or reuse their
+input buffers immediately because the cache snapshots identity metadata and
+bytes before waiting for that lock.
 `LocalChainTracker` reserves remote clients
 for explicit remote-only mode, local exceptions, and quorum-backed consistency
 or recovery checks. See
 [Local-first ChainTracks](./docs/local-first-chaintracks.md) for packaging,
 background synchronization, migration, and advanced-settings requirements.
 
+Legacy filesystem import/export is restricted to path-free manifest and data
+filenames beneath the caller-selected root. A missing manifest is created only
+for a definite not-found error; permission, size, parse, and integrity failures
+remain visible. Local files must form a contiguous genesis-anchored chain and
+all reads, writes, reader buffers, and queued lock operations are bounded.
+
 Arcade is the HTTPS/SSE gateway for Teranode-backed header data. Its v2 edge
 must allow browser origins and OPTIONS before browser defaults can use it;
 direct Teranode P2P is not included in browser/mobile artifacts.
@@ -222,6 +625,70 @@ cannot restore the failed transaction; recovery requires a mined status and a
 Merkle proof validated by the configured chain tracker. Arcade SSE events are
 acknowledged in order only after their storage update and cursor persistence
 succeed, so a transient storage failure is retried instead of skipped.
+The SSE client validates and owns every status record, retains at most 64 events
+and 4 MiB by default, and enforces a 256 KiB ceiling per event. The additive
+`maxEventBytes`, `maxPendingEvents`, and `maxPendingBytes` options may lower
+those limits. A malformed, excessive, or failed event closes the stream and
+prevents queued successors from advancing beyond the last durable cursor.
+Client logging is silent unless `log` is supplied, and transport errors never
+forward credential-bearing EventSource objects. Monitor startup awaits its
+ChainTracks subscriptions and retries transient setup failures; removal and
+teardown close Arcade SSE before storage is destroyed. Monitor operational
+logging is likewise opt-in through `MonitorOptions.logging`.
+
+### Transaction-status authentication
+
+Transaction-status providers are untrusted observations, not permission to
+change an arbitrary wallet transaction. Every result is copied and accepted
+only when its txid is one of the exact requested ids and its depth agrees with
+`mined`, `known`, or `unknown`. Terminal and input-conflict evidence is allowed
+only on an internally consistent unknown lifecycle result. Competing txids and
+diagnostics are bounded, and the durable provider name comes from local
+configuration rather than the remote response.
+
+A malformed provider response is recorded as that provider's failure and the
+service tries the next configured source. Arcade additionally binds the whole
+`GET /tx/{txid}` response to the request before interpreting lifecycle or proof
+fields. Provider errors and omitted results remain unknown; they never become
+mined, known, terminal, or input-conflict evidence by default.
+
+### Raw transaction acquisition
+
+Raw-transaction providers must return an accessor-free result whose declared
+txid exactly matches the request. Transaction data is accepted only as a
+nonempty dense byte array no larger than 32 MiB, copied before hashing, and
+returned as wallet-owned bytes. The computed transaction hash must still match
+the request. Provider attribution comes from local configuration, and an
+invalid result is discarded before the next provider is tried.
+
+### Merkle-proof authentication
+
+Wallet proof providers are untrusted inputs. An ordinary `getMerklePath`
+success is accepted only when a bounded, copied path contains an explicit leaf
+for the requested transaction, computes the supplied header's Merkle root at
+the same height, and the complete header resolves through the wallet's
+proof-of-work-valid chain service. The monitor independently asks its configured
+ChainTracks source to affirm that root and height before persisting proof state
+or restoring a failed transaction. Raw transaction bytes must also hash to the
+same txid.
+
+Custom ordinary proof providers must return both a `MerklePath` and complete
+`BlockHeader`; a path-only result is treated as unavailable. The additive
+`getValidatedMerklePath` compatibility hook still permits a path-only custom
+provider when its caller-supplied validator independently resolves and
+authenticates the header. No proof-provider response, mined status label, or
+non-null path alone is authority to release wallet funds.
+
+Every configured proof provider is treated as untrusted. Wallet Toolbox checks
+transaction membership, header/root agreement, and the active ChainTracks root
+before a proof can be persisted; a stale orphan proof is rejected and the next
+provider is tried. The lagged proven-transaction review retains unresolved
+reorg heights and bounds retry work per run while its forward cursor continues,
+so temporary provider lag cannot turn one failed repair attempt into a
+permanent checkpoint skip. Failed retries rotate behind waiting heights, and
+temporarily ineligible heights remain queued when the chain tip retreats.
+Compound proofs may mark multiple transactions; validation checks membership
+of the requested transaction. No consumer or database migration is required.
 
 Invalid-change review applies the same positive-evidence rule. Only an
 explicit successful `isUtxo: false` result is considered spent; a provider
@@ -235,6 +702,36 @@ positively spent subset while retaining and reporting unknowns. Each confirmed
 spent output is rechecked for ownership and allocation state under the write
 lock, and every release or blocked release records bounded audit evidence.
 
+Provider responses are copied as accessor-free data, capped at 4,096 detail
+rows, and bound to the requested outpoint whenever details are supplied. A
+configured UTXO provider remains a locally chosen operational oracle: these
+structural checks prevent response confusion but do not turn non-membership
+claims into cryptographic proofs. Whole-wallet compatibility reviews stop
+before provider work when more than 10,000 candidates would be inspected;
+operators should use the bounded Monitor Admin pages for larger wallets. Manual
+review inputs require canonical compressed identity keys and exact modes,
+booleans, page sizes, and offsets. A release rechecks the exact user, txid,
+vout, value, basket, and allocation state under the write lock.
+
+Transaction-history and broadcast providers are locally selected operational
+oracles, but their response objects are never trusted as wallet-owned state.
+Script-history observations are bound to the exact normalized script hash and
+endianness, copied into a dense 4,096-entry maximum, and checked for canonical
+transaction IDs, safe heights, duplicates, and conflicts. WhatsOnChain calls
+have a 30-second whole-request deadline by default; the additive
+`requestTimeoutMsecs` option may be set from 1 through 3,600,000 milliseconds.
+
+Broadcast accepts at most 1,000 unique requested transactions in a 64 MiB BEEF.
+Each provider receives its own strict reparse and copied txid list. Results must
+contain exactly one invariant-consistent entry for each request; provider names
+come from local registration, competing transactions and diagnostics are
+bounded, and raw transaction, BEEF, endpoint, and txid-list diagnostics are not
+retained. In `UntilSuccess` mode, malformed, throwing, or soft-timed-out
+providers remain inconclusive and the next provider is tried. A provider's
+double-spend assertion becomes terminal only when the wallet independently
+gets conclusive spent evidence for at least one exact input; an unavailable or
+unknown UTXO oracle cannot quarantine funds by itself.
+
 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
@@ -399,7 +896,10 @@ 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
+  touchIntervalMs: 60 * 1000,
+  // Optional global and per-identity rolling bounds for unsigned claims.
+  maxInitialRequestNonces: 100_000,
+  maxInitialRequestNoncesPerIdentity: 100_000
 })
 
 const server = new StorageServer(storage, {
@@ -413,6 +913,8 @@ const server = new StorageServer(storage, {
   preAuthRateLimit: { limit: 300, windowMs: 60_000 },
   // Per-identity before payment/RPC work (default 1,000/minute).
   rateLimit: { limit: 1_000, windowMs: 60_000 },
+  // Bound database/cursor work caused by list and sync offsets.
+  maxRpcListOffset: 1_000_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.
@@ -424,6 +926,33 @@ const server = new StorageServer(storage, {
 server.start()
 ```
 
+Run `storage.migrate(...)` before enabling this manager on any replica. The
+additive `2026-09-16-001 add auth message replay claims` migration creates the
+`auth_message_nonces` uniqueness table used to atomically consume every signed
+BRC-103 message nonce and identity-scoped initial-request nonce across replicas.
+Missing the migration causes authentication processing to fail closed. All
+replicas must share this table; a per-process or per-replica table does not
+provide replay protection during load-balanced routing.
+
+Signed per-session nonce claims fail closed at their configured bound and are
+retained across sliding TTL extensions for the full active session. Unsigned
+initial-request claims instead use global and per-identity rolling windows: when
+either window is full, its oldest claim is evicted. Expired claims are removed
+across identities during admission. This preserves exact replay rejection
+within the configured TTL/cardinality windows without allowing unauthenticated
+nonces to grow storage without bound or disable all future handshakes.
+
+Schema migration is an operator-owned server lifecycle step. Authenticated
+remote `StorageClient.migrate(...)` and `destroy()` RPCs are compatibility
+no-ops; wallet tenants cannot run global DDL or close the shared provider.
+
+The standard resource profile rejects list, find, and sync offsets above
+1,000,000 before storage access (`WALLET_STORAGE_RPC_MAX_LIST_OFFSET`). Small
+and high-throughput profiles default to 100,000 and 10,000,000 respectively.
+Operators with legitimately larger wallet histories can raise the bound; use
+`-1` only when all tenants are trusted and the database has an independent
+workload guard.
+
 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
@@ -456,6 +985,24 @@ does not apply schema changes.
 
 ## Development
 
+### Overlay identity verification
+
+Final identity discovery copies bounded resolver receipts, verifies their
+transaction graph and canonical anchors with the wallet's existing
+`Services.getChainTracker()`, and then validates the standard subject-signed
+identity envelope and certificate. The wallet finally re-binds each verified
+certificate to the requested subject or to every requested public attribute,
+so a lookup host cannot substitute a different valid identity. Transaction and certificate reuse remain
+bounded and canonical evidence is rechecked before cached results are used;
+fresh provider tokens bracket asynchronous anchor checks where the configured
+tracker supplies them. Invalid candidate evidence is dropped, while typed
+limit/timeout outcomes propagate to the caller.
+Direct `identityUtils` callers must supply a canonical `ChainTracker`; missing
+context or invalid evidence produces no overlay identities. Local contacts
+retain their separate policy. Inclusion does not establish unspentness or
+freshness. See [identity verification](docs/identity-verification.md) for
+current C01/C02/C03 contracts, compatibility characterization, and limits.
+
 ```bash
 git clone https://github.com/bsv-blockchain/ts-stack.git
 cd ts-stack
@@ -477,9 +1024,12 @@ network access, or long runtimes. Files named `*.live.test.ts` are public-networ
 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.
+merges four Wallet Toolbox coverage shards for reporting. The C01 local
+`test:coverage --runInBand` run passed 225 suites and 2,188 tests, with one
+pre-existing skipped test. Its all-files totals were 45.75% statements, 38.86%
+branches, 42.57% functions, and 45.46% lines; that collection includes imported
+`out/src` code as well as source files. Use the exact run's coverage report,
+rather than comparing unlike source-only and combined collections.
 
 Operational repair, migration, export, and long-running service procedures are
 not tests. They live under [`operator/`](./operator/README.md), produce an exact