@bsv/wallet-toolbox 2.10.3 → 2.11.0

package/CHANGELOG.md

@@ -6,6 +6,74 @@ attention to changes that materially alter behavior or extend functionality.
 
 ## wallet-toolbox (unreleased)
 
+- Keep Argon2id-backed UMP v3 wallets available in React Native and other
+  runtimes without WebAssembly by falling back to an asynchronously yielding,
+  standards-compatible JavaScript implementation. The same KDF parameters and
+  derived bytes are preserved, so existing tokens require no migration and
+  WebAssembly-capable runtimes retain the faster path. The existing public
+  `hash-wasm`-compatible utility contract remains intact: secret-bearing,
+  non-binary-output, and non-byte-array requests stay on `hash-wasm` and are
+  never reinterpreted by a host backend or fallback. Native registration is
+  available from both mobile and client roots, concurrent cold callers share
+  one preload attempt, and both alternative implementations validate result
+  type and length. Unrelated validation errors propagate even without the
+  WebAssembly global. The current-main macOS
+  reference fixtures measure 1,690,925 raw / 398,461 gzip / 311,955 Brotli
+  bytes with Vite, 1,319,059 raw / 362,220 gzip / 291,206 Brotli bytes with
+  esbuild, 1,746,067 raw / 442,648 gzip / 343,342 Brotli bytes with Metro, and
+  3,542,034 raw / 1,419,515 gzip / 1,117,531 Brotli bytes as optimized Hermes
+  bytecode; hosted Linux measures 1,439,166 gzip bytes. The reviewed ceilings
+  advance to 1,693,000 / 400,000 / 314,000 Vite bytes, 1,321,000 / 364,000 /
+  293,000 esbuild bytes, 1,748,000 raw Metro bytes with the compressed ceilings
+  unchanged, and 3,547,000 / 1,441,000 / 1,123,000 Hermes bytes.
+
+- Extend the BRC-98/99/111 permission-module interface with an optional semantic
+  `handleRequest` hook. A module can now return a conforming BRC-100 result
+  directly or invoke the underlying wallet operation at most once, while
+  existing `onRequest`/`onResponse` transformation modules remain compatible.
+  The companion `@bsv/ecpm-permission-module` uses this hook to implement
+  `p ecpm` point multiplication without adding a BRC-100 method or wire call.
+
+- Add opt-in prepared BEEF storage for Knex-backed normal `createAction`
+  funding. COOK (Create Once, Output Kept) stores a user-scoped, exact,
+  independently verified and checksummed proof closure, merges valid hits
+  without invoking the canonical builder, and treats every miss or cache
+  failure as the existing canonical path. Missing roots and newly finalized
+  managed-change transactions are queued only after foreground action work is
+  complete; bounded writes, reads, and gradual backfill are separately
+  controlled and default off. Reorganizations stale derived artifacts, a
+  database proof epoch fences in-flight cross-process writes, purge removes
+  unused rows, and prepared data remains outside wallet sync. The
+  Knex worker is excluded from portable bundles. Reviewed Vite ceilings advance
+  to 1,610,250 raw / 379,750 gzip / 298,000 Brotli bytes and esbuild ceilings
+  to 1,255,000 raw / 346,250 gzip / 278,000 Brotli, covering local measurements
+  of 1,609,783 / 379,492 / 297,253 and 1,254,603 / 344,792 / 277,384 bytes;
+  hosted Linux Vite Brotli and esbuild gzip measured 297,585 and 345,711 bytes.
+  The Hermes raw / gzip ceilings advance to 3,374,500 / 1,369,000 bytes,
+  covering local measurements of 3,372,554 / 1,348,354 and hosted Linux
+  measurements of 3,373,560 / 1,368,128 bytes; Metro and Hermes Brotli
+  ceilings remain unchanged.
+- Add the built-in BRC-177 `p nosend expiry` module for seconds, Unix timestamp,
+  and block-height deadlines. Protected actions are prefunded through an
+  accepted transaction, contain no wallet change, and retain a pre-signed
+  reclaim across restarts, synchronized storage, devices, and keyless remote
+  monitors. Atomic lifecycle transitions, active-storage ownership,
+  fail-closed status checks, backoff-controlled recovery of terminally rejected
+  reclaims, quarantined race outputs, and locally validated proof finality
+  prevent duplicate reclaim activation and unsafe state regression. Wallet
+  Permissions Manager authorizes module use and spending
+  before prefunding, attributes the funding fee to the requesting originator,
+  and rechecks the current monthly ledger before releasing the protected
+  action. Existing actions and ordinary `noSend` calls are unchanged. The
+  current-main macOS reference fixtures measure 1,662,220 raw / 388,763 gzip /
+  305,307 Brotli bytes with Vite, 1,297,621 raw / 355,579 gzip / 285,031 Brotli
+  bytes with esbuild, 1,710,494 raw / 430,613 gzip / 334,490 Brotli bytes with
+  Metro, and 3,474,604 raw / 1,406,878 gzip / 1,090,948 Brotli bytes as
+  optimized Hermes bytecode. The reviewed ceilings advance to 1,665,000 /
+  390,000 / 307,000 Vite bytes, 1,300,000 / 357,000 / 287,000 esbuild bytes,
+  1,712,000 / 455,000 / 360,000 Metro bytes, and 3,480,000 / 1,410,000 /
+  1,095,000 Hermes bytes.
+
 - Report `listOutputs` `totalOutputs` as the size of the whole result set on
   every page, in both the IndexedDB and Knex storage providers. A short final
   page previously returned only that page's length, so a client paging a large

package/LICENSES/Open-BSV-License-4-wallet-pre-2026.txt

@@ -0,0 +1,28 @@
+# Open BSV License version 4
+
+Copyright (c) 2023 BSV Blockchain Association ("Bitcoin Association")
+ 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, 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 the following conditions:
+ 
+1 - The above copyright notice and this permission notice 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,
+can only be used on the Bitcoin SV blockchains. The Bitcoin SV blockchains are defined,
+for purposes of this license, as the Bitcoin blockchain containing block height #556767
+with the hash "000000000000000001d956714215d96ffc00e0afda4cd0a96c96f8d802b1662b" and
+that contains the longest persistent chain of blocks accepted by this Software and which are valid under the rules set forth in the Bitcoin white paper (S. Nakamoto, Bitcoin: A Peer-to-Peer Electronic Cash System, posted online October 2008) and the latest version of this Software available in this repository or another repository designated by Bitcoin Association,
+as well as the test blockchains that contain the longest persistent chains of blocks accepted by this Software and which are valid under the rules set forth in the Bitcoin whitepaper (S. Nakamoto, Bitcoin: A Peer-to-Peer Electronic Cash System, posted online October 2008) and the latest version of this Software available in this repository, or another repository designated by Bitcoin Association
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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

@@ -31,6 +31,15 @@ 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 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
+needs the underlying wallet operation, `next` is guarded so it can be invoked
+at most once. Existing transformation-only modules remain compatible. The
+standalone `@bsv/ecpm-permission-module` demonstrates this extension by
+implementing `p ecpm` point multiplication through `getPublicKey`, without a
+new BRC-100 method or wire message.
+
 Immediate actions prefer completed, then unproven, then sending change. A
 pathological settled plan is compared with pending alternatives by exact
 serialized BEEF plus transaction bytes; queued ancestry is used only when it is
@@ -56,6 +65,26 @@ requested at or past the end of the result set.
 
 ### UMP account continuity and phone changes
 
+Argon2id password derivation uses a proven-ready host backend when one is
+registered with `registerArgon2idBackend`. This lets React Native applications
+perform the memory-hard operation asynchronously in native code. Browser and
+Node runtimes prefer `hash-wasm`; when WebAssembly is unavailable, Wallet
+Toolbox falls back to an asynchronously yielding JavaScript implementation
+with the same parameters and output. Existing UMP v3 tokens remain
+interoperable and do not need migration; users do not need to enable a device
+or browser setting. A selected host backend is authoritative, so a derivation
+error or malformed output is surfaced instead of silently changing
+implementations. The existing `hash-wasm`-compatible utility export retains its
+full input and output contract; requests with `secret`, non-binary output, or
+non-`Uint8Array` input remain on `hash-wasm` rather than being reinterpreted by
+a backend with narrower capabilities. Registration and unregistration are also
+exported from the mobile and client package roots. Concurrent cold calls share
+one background preload attempt; later calls can retry after it settles. Hosts
+must make preload/readiness checks reentrant and cache permanent failures or
+apply retry backoff. Unrelated `hash-wasm` errors propagate even when the
+WebAssembly global is absent. Native and JavaScript results both pass the same
+byte-type and exact-length validation.
+
 `WalletAuthenticationManager` accepts an optional `umpTokenOutpoint` in the
 backward-compatible WAB authentication response. Normal verified lookup and
 lineage resolution always run first. The WAB pin is considered only when those
@@ -244,10 +273,21 @@ the 144-output / 5,000-satoshi defaults, gradual legacy-wallet migration,
 pending-parent policy, exact BEEF comparison, operator tuning, action-batch
 alignment, monitoring, and rollout guidance.
 
+See [Prepared BEEF (COOK)](./docs/prepared-beef.md) for the opt-in Knex cache
+that creates an exact, verified proof closure once and keeps it ready for a
+future `createAction`. Reads, writes, and bounded backfill are separately
+controlled and default off; cache misses and failures retain the canonical
+BEEF builder.
+
 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.
 
+See [Expiring `noSend` actions](./docs/no-send-expiry.md) for the built-in
+BRC-111 `p nosend expiry` module, exact label forms, prefunding, durable
+Node/browser/mobile monitoring, storage coordination, and proof-based race
+resolution.
+
 ### `createAction` performance telemetry
 
 Wallet Storage treats `inputBEEF` as proof data for the inputs declared in the
@@ -279,6 +319,13 @@ pnpm bench:create-action-funding
 pnpm bench:create-action-beef
 ```
 
+The proof-bearing benchmark includes a prepared-BEEF cohort and asserts that a
+prepared hit does not invoke the canonical BEEF builder. A representative
+local SQLite one-input run reported 8.04 ms on the cold canonical path and
+4.39 ms on the prepared path. Local timings are noise-bound; the intended
+production measurement is the authenticated remote/MySQL cohort, where
+repeated proof reconstruction has materially higher cost.
+
 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
@@ -449,4 +496,6 @@ for the full stack-wide policy.
 
 ## License
 
-Released under the [Open BSV License](./LICENSE.txt).
+This package is released under the [Open BSV License Version 6](./LICENSE.txt).
+The accompanying [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) and
+[LICENSES/](./LICENSES/) preserve the package's earlier Open BSV grant.

package/THIRD_PARTY_NOTICES.md

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

package/docs/README.md

@@ -22,9 +22,8 @@ The documentation is split into various pages, each covering a set of related fu
 
 ## Open RPC
 
-StorageClient implements the WalletStorageProvider interface over https using a JSON-RPC api which can be explored using the JSight UI.
-
-- [StorageClient JSight UI](https://bsv-blockchain.github.io/wallet-toolbox/open-rpc)
+`StorageClient` implements `WalletStorageProvider` over HTTPS using JSON-RPC.
+Its maintained API documentation is in the [Storage reference](./storage.md#class-storageclient).
 
 ## Getting Started
 

package/docs/managed-change-liquidity.md

@@ -216,6 +216,13 @@ unrelated action.
 
 ## Monitoring and rollout
 
+Wallet Storage can optionally prepare the exact verified BEEF closure for a
+managed-change source after the foreground action finishes. This COOK
+(Create Once, Output Kept) optimization does not alter funding selection,
+transaction state, or the canonical fallback. See
+[Prepared BEEF (COOK)](./prepared-beef.md) for the asynchronous timing
+contract, storage controls, proof-reorganization handling, and staged rollout.
+
 `TaskReviewUtxos.reviewManagedChangeByIdentityKey(identityKey)` is a read-only
 operator report. It returns:
 

package/docs/no-send-expiry.md

@@ -0,0 +1,167 @@
+# Expiring `noSend` actions (BRC-177)
+
+Wallet Toolbox implements the BRC-111 `nosend` module for wallet-enforced
+expiry of BRC-100 `noSend` actions. It is built into the Node, browser, and
+mobile Wallet Toolbox distributions; applications do not install a separate
+permission module.
+
+Use exactly one of these action labels:
+
+```text
+p nosend expiry seconds <duration>
+p nosend expiry timestamp <unixSeconds>
+p nosend expiry blockheight <height>
+```
+
+Values are canonical unsigned base-10 integers. A relative duration must be
+greater than zero. Absolute timestamps and block heights must still be in the
+future when the protected action is activated.
+
+```ts
+const offer = await wallet.createAction({
+  description: 'Offer valid for five minutes',
+  labels: ['p nosend expiry seconds 300', 'offer 42'],
+  outputs: [
+    {
+      satoshis: 1000,
+      lockingScript: recipientLockingScript,
+      outputDescription: 'Offer payment'
+    }
+  ],
+  options: {
+    noSend: true
+  }
+})
+```
+
+The caller must set `noSend: true` and must not use `sendWith`,
+`noSendChange`, or `returnTXIDOnly`. The wallet applies the same restrictions
+when a signable action is completed through `signAction`.
+
+When label permissions are enabled, Wallet Permissions Manager authorizes use
+of the built-in module and obtains a spending preflight before creating its
+on-chain funding transaction. Its normal amount-specific spending authorization
+still applies to the protected action and always rechecks the current spending
+ledger after prefunding. The funding transaction carries the same originator
+and calendar-month attribution as the protected action, while accounting only
+for its miner fee rather than its internal anchor output. This prevents an
+unauthorized application from imposing even the funding transaction's miner
+fee or evading monthly limits through repeated prefunding. The reserved labels
+cannot be overridden by a custom permission module or asserted through
+`internalizeAction`.
+
+## What the wallet does
+
+Before returning the protected action, Wallet Toolbox:
+
+1. calculates the exact wallet funding required by its requested outputs,
+   explicit inputs, and fee;
+2. creates and immediately broadcasts a normal funding transaction containing
+   a dedicated managed-change output;
+3. requires processor acceptance of that funding transaction;
+4. creates the protected transaction with that output as its only
+   automatically selected wallet input and with no wallet change; and
+5. signs and durably stores a one-input reclaim transaction to a fresh
+   `default`-basket output.
+
+The wallet returns the protected transaction to the caller but never
+broadcasts it. The funding transaction may have ordinary change because it is
+already on the network; significant wallet change is therefore not held inside
+the unbroadcast transaction.
+
+For `seconds`, activation occurs after prefunding and the absolute deadline is
+stored before the action is returned. Restarting the wallet does not restart
+the duration. A signable action is already active while it waits for
+`signAction`, but an unsigned expiry can release its anchor locally because no
+valid anchor signature has been exposed.
+
+After a signed action expires, the active storage monitor first requires both
+an explicit `unknown` target verdict and a conclusive unspent-anchor result.
+Service errors or ambiguous status defer action. The monitor then atomically
+activates the pre-signed reclaim and retries normal network submission. The
+reclaim output remains unavailable for wallet funding until a locally
+validated Merkle proof establishes that the reclaim won. A processor rejection
+does not release the anchor: the lifecycle remains quarantined for proof
+reconciliation because another submission may already have reached the network.
+If the reclaim was terminally rejected, the target has never been observed, and
+later checks still report the target as explicitly `unknown` and the anchor as
+conclusively unspent, the monitor revives and resubmits that same pre-signed
+reclaim after a persistent exponential backoff (30 seconds, doubling to one
+hour). It never creates a different spend or releases the anchor during
+recovery. A conclusive spent-anchor verdict is likewise quarantined; if the
+conflicting spend later disappears, reclaim resumes only after fresh explicit
+`unknown` target and unspent-anchor verdicts.
+
+Seeing the protected transaction as known or mined permanently stops a new
+reclaim and moves it into ordinary proof tracking. If a reclaim was already
+submitted when the target appears, the monitor stops further reclaim retries
+but retains both transactions for proof tracking. Only a locally validated
+proof finalizes either winner. A processor status by itself is never reported
+as final.
+
+An observed target's `broadcast` state is intentionally sticky: BRC-177 makes
+expiry a deadline for broadcast, not confirmation, so an automatic timeout
+must not later double-spend a target that a recipient submitted on time. If an
+operator establishes that `known` was a status-provider false positive, recovery
+is therefore an explicit, security-sensitive repair rather than a timer:
+
+1. stop every monitor and storage writer and snapshot each synchronized store;
+2. verify independently that neither target nor reclaim has a validated proof,
+   that trusted services report the target `unknown`, and that the anchor is an
+   unspent output on the canonical chain;
+3. remove or repair the provider that produced the false observation;
+4. change only the protected row's lifecycle from `broadcast` to `conflicted`
+   in the active store and every synchronized copy, leaving transaction status,
+   request records, `spentBy`, and output spendability untouched; and
+5. restart exactly one authoritative monitor and retain the snapshot until the
+   resulting race is proven.
+
+A stale synchronized copy still carrying the higher-ranked `broadcast` state
+can restore it during merge, so all copies must be repaired together. If any
+proof or anchor-spend evidence is ambiguous, do not reset the lifecycle; repair
+status/proof services and let ordinary reconciliation remain fail-closed.
+
+`abortAction` cancels an unreleased action locally. For a released action it
+durably requests immediate revocation through the same guarded reclaim path;
+it does not clear the anchor reservation. An already observed target is
+protected and returns `aborted: false`.
+
+## Storage, monitors, and upgrades
+
+Expiry metadata, the signed reclaim, and lifecycle state are synchronized with
+the action. State merging is monotonic, so a backup with a newer wall clock
+cannot revive an older lifecycle state. Only the provider named by the user's
+synchronized `activeStorage` value may activate a reclaim, and compare-and-set
+updates ensure that concurrent monitor processes intentionally create one
+reclaim record. Synchronized reclaim outputs remain quarantined unless the
+local lifecycle has proven the reclaim winner, even when transaction and output
+updates arrive from different devices.
+
+The default Wallet Toolbox monitor includes the expiry task. A remote active
+storage service owns monitoring; browser and mobile clients do not compete
+with it. Operators must migrate the active storage database and run the normal
+default monitor before accepting BRC-177 actions. The capability handshake
+rejects an older storage server before the wallet creates the funding
+transaction.
+
+Knex storage gains nullable transaction lifecycle columns plus expiry and
+reclaim-transaction indexes. IndexedDB schema version 5 adds the corresponding
+state and reclaim-transaction indexes. Existing actions and ordinary `noSend`
+behavior are unchanged; no data rewrite is required.
+
+Funding and reclaim network fees are paid by the wallet owner. Wallet Toolbox
+reserves reclaim fees at the greater of its configured fee rate or 1,000
+satoshis per kilobyte and rejects an anchor that would not leave an economic
+reclaim output.
+
+## Application responsibility
+
+Action labels are wallet metadata and are not committed into the transaction
+or automatically delivered in BEEF. An application that gives the transaction
+to a recipient must communicate the deadline separately. If the deadline must
+be authenticated, bind it to the transaction or anchor outpoint in the
+application protocol.
+
+Broadcast with enough margin for the wallet's configured status services to
+observe acceptance. Expiry starts a double-spend reclaim; consensus finality
+comes only from the transaction that is mined and proven.

package/docs/prepared-beef.md

@@ -0,0 +1,197 @@
+# Prepared BEEF (COOK)
+
+COOK stands for **Create Once, Output Kept**. It is the project name for an
+opt-in Wallet Storage optimization which builds reusable input proof material
+before a later `createAction` needs it.
+
+Production identifiers use `preparedBeef`, not cooking vocabulary. A
+**prepared BEEF** is already ready to use: it has been reduced to one root
+transaction and its exact dependency closure, independently verified,
+serialized, checksummed, and stored. It does not mean “waiting to be cooked.”
+
+## Latency contract
+
+The optimization does not replace the canonical BEEF builder or make a cache
+service a new dependency.
+
+1. `createAction` starts proof prefetch while its normal planning and database
+   work continue.
+2. With prepared reads enabled, a normal one-root call performs one user-scoped
+   indexed lookup. A fragmented call first runs a metadata-only aggregate and
+   bypasses prepared storage if matching BEEF blobs exceed `maxLookupBytes`.
+   Calls with more than 32 roots also bypass prepared storage. The canonical
+   builder therefore remains the bounded path for unusually broad actions.
+3. A valid hit is parsed and merged directly. A missing, stale, corrupt,
+   oversized, or unsupported artifact is treated as a miss and the existing
+   canonical builder runs for only those roots.
+4. The action result is completely assembled before any missing roots are
+   queued for preparation.
+5. Admission validates and retains only bounded user/root identifiers, never
+   the source BEEF. No graph traversal, hashing, verification, serialization,
+   or persistence occurs in the foreground.
+6. The bounded worker starts on a later event-loop turn. `createAction` and
+   `processAction` never await canonical reload, dependency selection,
+   verification, or persistence performed by that worker.
+
+Prepared reads therefore add an indexed lookup on a cold cache, but that lookup
+runs inside the existing early prefetch window and overlaps normal foreground
+work. Preparation itself is strictly background work. All controls default to
+off, so upgrading without enabling COOK preserves the existing normal-action
+execution path.
+
+`processAction` also queues a newly finalized transaction when it creates
+wallet-managed change. This prepares the source most likely to fund a future
+normal action without extending the current request.
+
+## Storage and validity
+
+Knex migrations add a `prepared_beefs` table keyed by `(userId, rootTxid)` and
+a singleton `prepared_beef_metadata` proof epoch used to serialize worker
+writes with reorganization invalidation. Artifacts are derived data, not wallet
+authority:
+
+- the authenticated storage user is part of every read and write key;
+- canonical transaction, proof, and output rows remain the source of truth;
+- proof rows received through authenticated RPC cannot establish global proof
+  authority on their own: the server recomputes the transaction ID and Merkle
+  root, checks the path position, and matches its active header/chain tracker.
+  In-process backup and conflict sync canonicalize hexadecimal identifiers and
+  apply the same active-chain validation before replacing an existing global
+  proof, so an orphaned backup cannot overwrite a repaired active proof. Any
+  inserted or replaced proof invalidates prepared artifacts in the same
+  storage transaction;
+- each artifact contains one root transaction plus only its recursive proof
+  dependencies;
+- the background worker verifies the exact BEEF against the configured chain
+  tracker before writing it;
+- reads enforce format version, state, checksum, byte length, size ceiling, and
+  a complete root transaction;
+- a reorganization notification first closes prepared reads synchronously in
+  that server process, then advances the shared proof epoch and marks ready
+  artifacts stale in one database transaction, before the aged replacement-
+  proof task performs network I/O. If invalidation fails, that process keeps
+  prepared reads closed and uses the canonical path until a later invalidation
+  succeeds (or the process restarts). A lookup whose
+  query begins after that transaction commits cannot read the old artifact. A
+  lookup overlapping the transaction may observe the preceding database
+  snapshot, as the canonical builder may, and is ordered before invalidation;
+- the proof epoch fences background writes rather than reads. It prevents an
+  in-flight worker in another server process from writing
+  pre-reorganization material after invalidation commits. Copying the epoch to
+  each artifact would not strengthen an ordinary snapshot read because both
+  the artifact and metadata can belong to the same preceding snapshot;
+- a failed verification leaves an unreadable rejection marker so optional
+  backfill does not hot-loop; a later canonical action can retry and replace
+  it organically;
+- storage purge removes artifacts once no matching unspent managed output
+  remains; and
+- prepared artifacts are deliberately excluded from wallet synchronization and
+  can always be rebuilt.
+
+Knex (SQLite and MySQL) is the persistence implementation. The option is not
+part of portable `StorageProvider` or IndexedDB configuration; those providers
+retain the normal canonical fallback and do not bundle the background worker.
+
+## Configuration
+
+`StorageKnex` and `Setup.createWalletKnex` accept the same `preparedBeef`
+settings:
+
+```ts
+const setup = await Setup.createWalletKnex({
+  ...args,
+  preparedBeef: {
+    // Roll out writes before reads so the first read cohort is warm.
+    writeEnabled: true,
+    readEnabled: false,
+    backfillEnabled: false,
+    maxQueueSize: 32,
+    maxQueueSizePerUser: 4,
+    maxArtifactBytes: 2 * 1024 * 1024,
+    maxLookupBytes: 2 * 1024 * 1024,
+    maxArtifactTransactions: 256,
+    backfillBatchSize: 32,
+    backfillIntervalMs: 100
+  }
+})
+```
+
+| Setting                   | Default | Meaning                                                                                               |
+| ------------------------- | ------: | ----------------------------------------------------------------------------------------------------- |
+| `writeEnabled`            | `false` | Queue and persist verified artifacts after foreground action work.                                    |
+| `readEnabled`             | `false` | Use valid artifacts on the `createAction` proof path.                                                 |
+| `backfillEnabled`         | `false` | Prepare eligible existing managed-change roots in bounded background passes. Requires writes.         |
+| `maxQueueSize`            |    `32` | Maximum roots queued or running globally. New work is safely dropped when full.                       |
+| `maxQueueSizePerUser`     |     `4` | Maximum roots queued or running for one user, preventing one tenant from consuming the shared worker. |
+| `maxArtifactBytes`        | `2 MiB` | Maximum estimated source and exact prepared-artifact size.                                            |
+| `maxLookupBytes`          | `2 MiB` | Maximum aggregate prepared BEEF bytes loaded for one fragmented foreground lookup.                    |
+| `maxArtifactTransactions` |   `256` | Maximum transactions in a source or exact prepared graph before expensive worker stages.              |
+| `backfillBatchSize`       |    `32` | Maximum roots selected in one backfill pass.                                                          |
+| `backfillIntervalMs`      |   `100` | Delay between low-priority backfill passes.                                                           |
+
+The queue is in-process and best effort. It retains bounded identifiers only,
+applies global and per-user admission quotas, and serializes preparation work.
+Before canonical reload, the worker first asks storage for the root's raw/proof
+byte length across every canonical-load status (including `unconfirmed`), so an
+oversized no-send `inputBEEF` is never loaded or parsed by
+COOK. It then applies estimated byte and transaction-count limits before
+dependency selection, verification, and exact serialization. A restart,
+full queue, resource rejection, verification failure, or persistence failure
+loses only an optimization opportunity. A later action can rebuild the same
+artifact from authoritative storage.
+
+## Rollout toward a 50 ms normal-action target
+
+Use a staged rollout rather than enabling all controls at once:
+
+1. Before release, run the additive migration against a disposable MySQL 8
+   schema. Confirm `prepared_beefs.beef` is a `LONGBLOB`, then exercise one
+   insert/upsert, prepared lookup, invalidation, and rebuild. This validates the
+   dialect-specific migration and basic Knex behavior even though all rollout
+   flags remain off.
+2. Deploy the migration with all flags off and confirm existing latency and
+   error rates are unchanged.
+3. Before enabling writes on PXC, run two storage processes against the same
+   non-production schema. Pause one worker after it reads the epoch, invalidate
+   from the other process, release the worker, and confirm it cannot commit the
+   old artifact. Also exercise concurrent upserts of the same root and record
+   any deadlock/retry behavior.
+4. Enable writes for a small server cohort. Watch preparation success,
+   rejection, artifact bytes, queue pressure, and database load.
+5. Once the normal managed-change roots are warm, enable reads for the same
+   cohort. Compare `createAction` p50/p95, prepared hit rate, canonical fetch
+   count, and returned BEEF bytes with the prior cohort.
+6. Enable bounded backfill only if organic writes do not warm the active pool
+   quickly enough. Keep it off during database pressure.
+7. Expand reads only while correctness fallbacks remain clean and the normal
+   one-input cohort moves toward the operator's 50 ms target.
+
+The target is an end-to-end service objective, not a guarantee from this cache
+alone. Authentication, HTTP, database commits, signing, and response
+serialization still contribute to remote latency. COOK specifically removes
+repeated canonical proof reconstruction from prepared hits.
+
+Telemetry uses bounded-cardinality spans:
+
+- `wallet.storage.prepared_beef.lookup` reports requested roots, hits, misses,
+  corrupt rows, bytes, and whether the lookup was bypassed by the root-count or
+  aggregate-byte foreground safety bound;
+- `wallet.storage.prepared_beef.prepare` reports attempted roots, prepared and
+  rejected counts, and bytes; and
+- `wallet.storage.prepared_beef.backfill` reports a failed backfill pass.
+
+The existing `wallet.storage.create_action.beef_prefetch` span also reports
+`beef.prepared_hit_count` and `beef.canonical_fetch_count`. No transaction ID,
+user identity, script, key, or payload is emitted as a telemetry attribute.
+
+## Rollback
+
+Set `readEnabled`, `writeEnabled`, and `backfillEnabled` to `false`. New actions
+immediately use the canonical path, queued work stops being accepted, and the
+derived rows can remain in place for a later re-enable on the same COOK-aware
+code or be removed by normal purge. Before downgrading to an older Wallet
+Toolbox version, delete the derived rows (or drop both additive tables); older
+code cannot advance the proof epoch during a reorganization. After returning
+to a COOK-aware version, warm artifacts with writes before enabling reads. No
+transaction, proof, output, synchronization, BRC-100, or Wallet Wire rollback
+is required.

package/docs/setup.md

@@ -343,6 +343,8 @@ export interface SetupWalletArgs {
     active?: WalletStorageProvider;
     backups?: WalletStorageProvider[];
     scriptVerifier?: SpendVerifierInterface;
+    managedChangePolicy?: ManagedChangePolicyOptions;
+    preparedBeef?: PreparedBeefOptions;
 }
 ```
 
@@ -384,6 +386,15 @@ Defaults to undefined.
 privilegedKeyGetter?: () => Promise<PrivateKey>
 ```
 
+###### Property preparedBeef
+
+Optional Knex prepared-BEEF (COOK) rollout controls. Reads, writes, and
+backfill default off. See [Prepared BEEF (COOK)](./prepared-beef.md).
+
+```ts
+preparedBeef?: PreparedBeefOptions
+```
+
 ###### Property scriptVerifier
 
 Optional high-performance verifier for internal wallet and locally hosted