@bopen-io/wallet-toolbox 2.15.0-bopen.2 → 2.15.0

package/CHANGELOG.md

@@ -4,6 +4,189 @@ This document captures the history of significant changes to the wallet-toolbox
 The git commit history contains the details but is unable to draw
 attention to changes that materially alter behavior or extend functionality.
 
+## wallet-toolbox 2.15.0
+
+- Adds a `regtest` `Chain` for Teranode regression-network deployments
+  (go-chaincfg `RegressionNetParams`). `genesisHeader('regtest')` returns the
+  canonical regtest genesis header; `ChaintracksServiceClient` and
+  `GoChaintracksServiceClient` accept a service that reports its chain as
+  `regtest`; Arcade and ChainTracks endpoints come from `REGTEST_ARCADE_URL` and
+  `REGTEST_CHAINTRACKS_URL` (`regtestArcadeUrl`, `regtestChaintracksUrl`). Like
+  TTN, the default regtest services use Arcade as broadcaster and Merkle-path
+  provider and register no legacy ARC fallback; like `tstn`, no WhatsOnChain
+  provider is registered.
+- Header proof-of-work and chain-work checks take an optional `chain`, and the
+  new `proofOfWorkLimitBits(chain)` reports the limit it selects. Only
+  `regtest` raises it, to `0x207fffff`. Every other chain, and every check that
+  names no chain, keeps the mainnet limit of `0x1d00ffff`, so no existing
+  validation is relaxed. Every ChainTracks client, storage, ingestor, bulk-file
+  path and Monitor header check now passes its configured chain.
+- `tstn` is unchanged: it keeps go-chaincfg's `TeraScalingTestNetParams`
+  genesis and proof-of-work limit. A deployment that runs regtest parameters
+  should configure `regtest`, not `tstn`.
+- A WhatsOnChain instance for a network with no WhatsOnChain service (`tstn`,
+  `regtest`) now refuses every request (`isAvailable` is `false`) instead of
+  sending it to a relative URL, which a browser resolves against the page's
+  origin. `Services.hashToHeader` no longer falls back to WhatsOnChain on those
+  networks, so their headers come only from ChainTracks.
+- `WalletPermissionsManager` passes `signAction` through the permission modules
+  that handled the action's `createAction`, both for a caller's `signAction`
+  and for the signing step of a one-call `createAction`. Modules receive it via
+  `onRequest` and `onResponse` with method `signAction` and may add `spends`
+  for inputs they supplied. Both calls carry `action` (`reference`, the
+  signable `transaction`, `noSend` and `createArgs`, the `createAction`
+  arguments as the modules returned them), so a module keeps no state between
+  `createAction` and `signAction`. A module request failure aborts the action; a
+  module response failure is thrown without aborting the signed action. A
+  module that rejects unknown methods must accept `signAction`.
+- `encryptMetadata(wallet, plaintext, originator?)` and
+  `maybeDecryptMetadata(wallet, value, originator?)` are exported. They encrypt
+  and decrypt metadata as a permissions manager with `encryptWalletMetadata`
+  does, so a permission module can store and read its own baskets' custom
+  instructions through the underlying wallet. The manager uses the same
+  functions.
+- `createAction` encrypts P-basket output custom instructions after the
+  permission modules run, as `internalizeAction` already does, so instructions a
+  module adds or replaces are stored encrypted.
+- New `listOutputs` special operation `specOpBasketPrefixOutputs`: with a
+  basket namespace such as `p color` in tag 0, it lists outputs from every
+  basket in that namespace that are unspent or reserved as an input of a
+  pending action (`spendable` false), ordered by txid and vout. Spent outputs
+  are excluded. The permissions manager reserves it for the admin originator.
+- `listOutputs` rejects a `balance p <module> <basket>` query with
+  `WERR_INVALID_PARAMETER`, as BRC-112 requires: the satoshi sum of a BRC-99
+  module basket is never reported past its module. `balance <basket>` on other
+  baskets is unchanged, and a module may offer `p <module> balance <basket>`.
+- `WalletPermissionsManager.getVersion` advertises the BRC-205 capability
+  attributes of the configured permission modules: a `PermissionsModule` may
+  declare `capabilities` (attribute key to value), appended to the underlying
+  version string as `base; key=value;` in scheme-id and key order, merged with
+  attributes the wallet already reports and never repeating a key. The built-in
+  BRC-177 module advertises `brc177-nosend=2`. `withBrc205Capabilities` is
+  exported.
+- `createAction` locks the known inputs it marks spent on MySQL and Postgres,
+  so of two concurrent actions spending the same input, the second sees it spent
+  and fails with the existing double-spend or unspendable-input error instead of
+  overwriting `spentBy`. SQLite and IndexedDB already serialize these writes.
+- Callers that count `listOutputs` results narrow `totalOutputs` to a number
+  with the exported `numericTotalOutputs`, following the `@bsv/sdk` change that
+  lets BRC-112 module balance queries return decimal text.
+- `@bsv/sdk` 4.0.0 is accepted as a peer alongside the existing 2.x and 3.x
+  ranges.
+
+## wallet-toolbox 2.14.10
+
+- Live `syncToWriter` / `syncFromReader` compare reader and writer
+  `TableSettings.chain` before any chunk moves and throw `WERR_NETWORK_CHAIN`
+  on mismatch. The class remains a public sdk export with its deserializer and
+  JSON round-trip. Portable BRC-38 import still throws a generic `Error`.
+  Custom `processSyncChunk` writers may set `ProcessSyncChunkResult.error`;
+  both live-sync loops throw that error and stop. First-party providers still
+  throw. No API or schema migration is required.
+
+## wallet-toolbox 2.14.9
+
+- Complete per-transaction broadcast results when the refreshed request is
+  already `unmined` or `completed`, preserving that durable state. Successful
+  first receipt without a mining proof no longer throws an internal unknown
+  status error on shared storage or when another worker advances the request.
+  Negative broadcast results and competing-transaction evidence remain negative;
+  they do not authorize recipient output credit. Repeated successful receipt
+  remains idempotent, and valid mined payments retain the proof path.
+- SQL storage uses a durable, leased user/TXID receipt claim to keep a second
+  pod from crediting a pending first receipt. Completed claims remain as
+  coordination keys; expired claims can be recovered, and an old owner cannot
+  finalize after its claim is replaced. The migration preserves historical
+  transactions and outputs, including duplicates. No API or wire migration.
+  Back up and preflight SQL storage, then coordinate all storage instances in
+  the protected rollout; this source candidate does not deploy hosted storage.
+
+## wallet-toolbox 2.14.8
+
+- `WalletPermissionsManager.internalizeAction` stores basket `customInstructions`
+  with one metadata encryption when `encryptWalletMetadata` is enabled.
+  A normal basket on a call that also carries a registered `p <scheme>` label
+  was encrypted before the permission module ran and again afterwards, so
+  `listOutputs` (which decrypts once) returned ciphertext. The after-module
+  pass now encrypts only permission-module baskets, matching `createAction`'s
+  once-only rule.- Preserve bounded pre-construction double-spend reviews from remote storage.
+  An empty attempted TXID is accepted only with one doubleSpend result, empty
+  send results, absent constructed-action fields and nonempty competing evidence.
+  Consumers must validate the evidence and synchronize the winning transaction
+  before rebuilding a save. The existing JSON transport carries this evidence;
+  binary wire framing is unchanged. No database or call migration is required.
+
+- Confirmed `internalizeAction` resolves the block header before the storage
+  writer opens. IndexedDB otherwise finished that transaction during the
+  asynchronous lookup and rejected a valid mined payment before storing the
+  proven transaction, transaction, or requested output. A missing or malformed
+  header, or an invalid proof, still rejects with no partial records. Upgrade
+  the active storage implementation, including the browser client; no API, wire,
+  or schema migration is required.
+
+- Restart-safe WAB registration checkpoints preserve the original wallet root
+  across interrupted faucet redemption and UMP publication. Persist through
+  `pendingRegistrationTokenSaver`, reload with `loadPendingRegistrationToken`
+  before authentication, and retain the checkpoint until an authenticated
+  snapshot is saved and `hasPendingRegistrationToken()` returns false. Recover
+  older pending registrations without checkpoints using their original wallet
+  state. WAB wire behavior is unchanged.
+
+- Profile additions and deletions change the local list only when the replacement
+  UMP token is published. Failed factor retrieval or publication preserves the
+  list for retry. A failed active-profile deletion attempts to restore that
+  profile without masking the update error.
+- Concurrent profile creation reserves case-insensitive names until the attempt
+  settles, preventing duplicate names while preserving retry after failure.
+- If restoring the active wallet fails after publication, the committed token
+  and profile list remain in place. Inspect `listProfiles()` before retrying.
+  The underlying factor-decryption failure still requires separate diagnosis.
+
+## wallet-toolbox 2.14.7
+
+- Internalization broadcasts unproven transactions new to the receiving user,
+  including shared-storage no-send payments. A rejected broadcast stores no
+  recipient outputs; proven transactions are not rebroadcast. Upgrade active
+  storage; no API, wire or schema migration is required.
+
+- IndexedDB empty certificate certifier/type, transaction status and output-tag
+  ID arrays mean no optional filter, matching Knex. Nonempty arrays, partial
+  predicates and user ownership remain enforced; no schema migration is required.
+
+- BEEF requests and schema-declared storage response bytes use the existing
+  negotiated compact binary JSON codec. Legacy peers retain numeric-array
+  JSON and identical transaction/proof bytes. Existing authentication and
+  payload ceilings remain unchanged; no API or database migration is required.
+
+- BRC-177 anchors cover both the protected action and an economic reclaim.
+  Protected actions keep their only managed input bound to the named anchor,
+  create no wallet change, and pay the bounded reclaim surplus as miner fee.
+  Ordinary actions retain their existing change planning. No API, wire or
+  database migration is required.
+
+## wallet-toolbox 2.14.6
+
+- UMP support pins anchor verified update lineage. Password and token updates
+  supersede the pinned predecessor, including multi-hop updates and recovery-hash
+  continuity. Unrelated historical continuations cannot override the anchor.
+  Competing descendants remain indeterminate rather than falling back to a spent
+  pin. No API or schema migration is required.
+
+- Every retained token spend proves control through its unlocking script,
+  including confirmed updates and presentation/recovery-hash rotation. Funding
+  paths do not establish a token-update lineage.
+
+- Explicit overlay history is linked past confirmed Merkle anchors. Deploy the
+  UMP history decider and engine retention fix with this client patch; missing
+  pin ancestry remains indeterminate rather than selecting an unrelated continuation.
+
+- WAB faucet redemption accepts the local signer's independently validated
+  service charge and derived change, with exact SDK transaction binding. Empty
+  wallets no longer reject legitimate fee outputs financed by the faucet input.
+  Upgrade the SDK alongside the toolbox to enable the new capability. Older SDK
+  peers retain strict behavior; serialization discards local output authority.
+  Signup interruption/retry persistence remains unchanged.
+
 ## wallet-toolbox 2.14.5
 
 - `WalletPermissionsManager` retires no-send transaction ownership and reference

package/README.md

@@ -6,6 +6,30 @@
 
 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.
 
+## Receiving already-broadcast payments
+
+The 2.14.9 source candidate completes broadcast results even when storage
+already marks the request `unmined` or `completed`. This fixes first receipt
+without a mining proof on shared storage, and the same result path when another
+storage worker advances the request before the broadcast result refresh. The
+stored advanced state remains intact; unsuccessful provider results still
+reject receipt and do not credit new recipient outputs. Repeated successful
+receipt remains idempotent. A payment carrying its valid mining proof follows
+the existing proof path without rebroadcast.
+
+SQL storage now serializes receipt ownership across independent processes
+through a durable user/TXID claim. The migration preserves legacy transaction
+and output rows, including historical duplicates, while adding the claim table.
+Ambiguous historical receipts still require separate reconciliation; this
+change prevents a new same-recipient overlap from creating another local credit.
+Back up and preflight the database before rollout, then upgrade all storage
+instances together; an older instance can bypass the new receipt claim.
+Pending claims recover after their database-timed lease expires. No
+public API or wire migration is required. Browser IndexedDB does not use the
+SQL receipt claim. Source versions are candidates until published through the
+protected release workflow; upgrading an app alone does not upgrade its remote
+storage server.
+
 ## Backup and recovery: keep both keys and wallet data
 
 **A root key or seed alone is not a complete BRC-100 wallet backup.** Users
@@ -372,6 +396,22 @@ retained privately, outside this repository.
 page for both Knex and IndexedDB storage, including short final pages and pages
 requested at or past the end of the result set.
 
+### Profile update failures
+
+`CWIStyleWalletManager.addProfile` and `deleteProfile` commit the local profile
+list when the replacement UMP token is published. A factor-decryption or
+publication failure preserves the previous list, so a failed creation can be
+retried with the same name. Concurrent creations reserve names without regard
+to case until each attempt settles. A failed deletion of the active profile
+attempts to restore that profile and preserves the original update error if
+restoration also fails.
+
+Restoring the active wallet can fail after publication has succeeded. In that
+case, the token and profile list already contain the change, and the default
+profile may remain active. Inspect `listProfiles()` before retrying and switch
+to an available profile as needed. This bookkeeping fix does not correct the
+underlying factor-decryption error; diagnose that error separately.
+
 ### UMP account continuity and phone changes
 
 Argon2id password derivation uses a proven-ready host backend when one is
@@ -395,11 +435,24 @@ 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
-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.
+backward-compatible WAB authentication response. When verified lookup returns
+competing records, the pin anchors its own update lineage. A password or token
+update that consumes the pinned outpoint supersedes it, including a multi-hop
+update whose old pin is available only in authenticated token ancestry.
+Each token input must prove spend authorization, including across confirmation;
+ordinary funding inputs do not establish token lineage. Unmined updates also
+require complete funding ancestry. A truncated input reference cannot override
+the verified pin. An unrelated historical continuation
+cannot override that lineage. A pin cannot
+introduce an unverified token or resolve competing descendants of a spent pin.
+Clients link explicit overlay history past confirmed Merkle anchors. UMP hosts
+must request retained token lineage with a history decider and preserve it in
+lookup BEEF (`@bsv/overlay` 2.6.4 and `@bsv/overlay-topics` 2.0.1, or equivalent
+custom hosting). If an older host names an absent pin but omits its authenticated
+source, lookup remains indeterminate instead of choosing an unrelated continuation.
+Ordinary lineage resolution still applies when no pin relationship is present.
+Operators should clear redundant pins after unpinned lookup independently returns
+the correct current token; pinning is a recovery measure for remaining forks.
 
 UMP renewal consumes only the exact canonical predecessor returned for its
 outpoint. Its signed fields, presentation/recovery hashes, and locally derived
@@ -413,21 +466,49 @@ 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
-publication has not happened. After publishing the UMP token, the manager
-finalizes WAB idempotently. A lost finalization response is non-fatal: the next
-verified login finds the published token and repairs the pending state. Missing
-or invalid lifecycle metadata remains fail-closed for established accounts, and
-older WAB servers and clients retain their existing wire behavior.
+script and bounded amount are authorized before signing. With a compatible SDK,
+its local signer also authorizes independently validated storage commission and
+locally derived change, bound to exact output indices, scripts and amounts. The
+permissions wrapper preserves this private decision; serialized results or
+unknown wallet adapters do not gain this authority. Other unrequested outputs
+cannot consume the faucet input.
+
+Upgrade wallet-toolbox to 2.14.6 and the SDK to a release exposing
+`completeBoundAction.outputAuthorizationVersion=1` together. Older SDK peers retain
+the existing strict behavior and cannot redeem a fee-bearing faucet input for an
+empty wallet. Main currently carries the separate SDK3.1 candidate; SDK2 hosts
+need an additive backport or the documented SDK3 migration.
+
+The signed action is staged locally, labeled, and recorded in a recovery basket
+before broadcast. Internalization clears the output's custom instructions, and
+standard `listActions` does not return them. A retry with the same wallet root
+can recover the prior faucet action; missing, substituted, ambiguous, or
+result-only recovery evidence fails closed. Preserve the wallet's storage when
+reconciling an interrupted signup.
+
+For restart-safe WAB registrations, store an unpublished UMP token checkpoint
+before faucet redemption. Pass `pendingRegistrationTokenSaver` in
+`WalletAuthenticationManagerOptions` and synchronously verify that the token
+bytes are stored before the callback resolves. On app restart, call
+`loadPendingRegistrationToken(bytes)` before starting authentication. The token
+contains encrypted UMP fields and no plaintext wallet root, snapshot key, or on-chain
+outpoint. Keep it through failed funding and logout; clear it only after a
+successful authenticated snapshot has been stored and
+`hasPendingRegistrationToken()` returns false. If an older pending WAB
+registration has no checkpoint, the manager refuses to redeem its faucet output
+again. Recover that registration using its original wallet state instead of
+creating a new root. A checkpoint for another presentation key does not block
+login to an already published wallet; retain that checkpoint until its own
+registration is reconciled.
+
+A WAB that advertises `registrationStatus: "pending"` lets a verified retry
+reuse the stored presentation key when a clean UMP lookup confirms that
+publication has not happened. The loaded checkpoint reconstructs the original
+root, so the wallet can recover its prior faucet action. After publishing the
+UMP token, the manager finalizes WAB idempotently. A lost finalization response
+is non-fatal: the next verified login finds the published token and repairs the
+pending state. Missing or invalid lifecycle metadata remains fail-closed for
+established accounts; WAB wire behavior is unchanged.
 
 Authenticated applications can verify a phone number and roll the presentation
 key, including when the user enters the same phone number:
@@ -506,11 +587,22 @@ 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
+The supported chain identifiers are `main`, `test`, `stn`, `ttn`, `tstn`, and
+`regtest` (`mock` remains available for test utilities). STN, Terra Scaling
+TestNet, and regtest do not have operator-independent public endpoints: set
+`STN_CHAINTRACKS_URL`, `TSTN_CHAINTRACKS_URL`, or `REGTEST_CHAINTRACKS_URL`, use
+the matching Arcade environment variable, or inject an explicit
+`ChaintracksClientApi`. Like TTN, the default regtest services use Arcade
+(`REGTEST_ARCADE_URL`) as broadcaster and Merkle-path provider and register no
+legacy ARC fallback.
+
+`regtest` is Teranode's regression network (go-chaincfg `RegressionNetParams`):
+the canonical regtest genesis header and a proof-of-work limit of `0x207fffff`.
+Only a caller that names `regtest` gets that limit; every other chain, and every
+header check that names no chain, keeps the mainnet limit of `0x1d00ffff`.
+Regtest proof of work costs nothing to produce, so a regtest wallet trusts its
+ChainTracks service for the header chain. Use it for private test deployments
+only. 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.
@@ -1122,3 +1214,13 @@ for the full stack-wide policy.
 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.
+
+## Pre-construction conflict recovery
+
+The 2.14.7 candidate preserves remote storage's empty attempted-TXID sentinel
+only for a bounded double-spend review before transaction construction. It does
+not authorize a retry. Applications must verify complete competing transactions
+against the requested explicit inputs, synchronize the accepted winner, then
+read fresh state before rebuilding. Upgrade the application SDK alongside the
+wallet parser. Use the existing JSON wallet API for structured review errors;
+the binary wire format is unchanged. No database or call migration is required.