@bopen-io/wallet-toolbox 2.0.5-idb-fix.2 → 2.1.21-parity-fix.0

package/CHANGELOG.md

@@ -4,6 +4,190 @@ 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.
 
+## @bopen-io/wallet-toolbox 2.1.21-parity-fix.0
+
+StorageIdb aligned with StorageKnex canon. Six functional divergences fixed.
+
+- **CRIT** `filterOutputTagMaps` user-scope filter was dead code (`&& r.txid` on a table with no txid field). `getOutputTagMapsForUser` leaked rows across accounts. Fixes cross-account sync chunk contamination.
+- **HIGH** `filterOutputs` / `filterTransactions` no longer treat an empty `txStatus` / `status` array as a reject-all filter. Matches Knex.
+- **HIGH** `filterX` methods now throw `WERR_INVALID_PARAMETER` on undefined values in `partial`. Matches Knex's `Undefined binding(s) detected`. Surfaces mergeFind bugs that used to present as misleading "Result must be unique."
+- **MED** Truthiness guards on integer-ID / string partial fields swept to `!== undefined` across every filter method (~106 replacements). Fixes silent filter skip for `lockTime=0`, `version=0`, empty strings.
+- **MED** `updateIdb` returns actual affected-row count instead of always `1`.
+- **LOW** `filterProvenTxReqs` drops the `&& r.txid` user-scope bypass (same shape as CRIT finding; latent unless a row lacks a txid).
+
+Based on 2.1.21 content; published to `@bopen-io` npm scope pending canonical review (PR bsv-blockchain/wallet-toolbox#151).
+
+## wallet-toolbox 2.1.21
+
+- Fix spending authorization bypass in querySpentSince, PR#150
+
+## wallet-toolbox 2.1.20
+
+- Update cdn.projectbabbage.com valid blockheaders file hash.
+- 
+## wallet-toolbox 2.1.19
+
+- Merge PR#146. GenerateChange change to better handle dust situations. Redundant trimInputBeef knownTxids safety check.
+- recovery-key-and-password fix
+
+## wallet-toolbox 2.1.18
+
+- fix provideRecoveryKey guard blocking recovery-key-and-password mode
+- set authenticationFlow to existing-user after recovery key token lookup
+
+## wallet-toolbox 2.1.17
+
+- add admin web server for visibility into storage and monitor by operations admin
+- add recentlyActiveUsers to StorageProvider with optimized override in StorageKnex
+
+## wallet-toolbox 2.1.16
+
+- update Services getStatusForTxids to internally handle provider batch limit
+
+## wallet-toolbox 2.1.15
+
+- audit fix
+ 
+## wallet-toolbox 2.1.14
+
+- fix update timestamp on all updated currencies
+
+## wallet-toolbox 2.1.13
+
+- update all supported currencies in single exchangeratesapi.io request.
+
+## wallet-toolbox 2.1.12
+
+- Add fundWalletFromP2PKHOutpoints
+
+## wallet-toolbox 2.1.11
+
+- Add UMP v3 token support with Argon2id password key derivation.
+- Introduce `derivePasswordKey()` abstraction that dispatches to Argon2id for v3 tokens and PBKDF2-SHA512 (7777 rounds) for legacy tokens.
+- Use `hash-wasm` for password-key derivation support in browser/webview-compatible contexts.
+- Extend `UMPToken` with optional `umpVersion` and `passwordKdf` metadata fields.
+- Update `buildAndSend` to write v3 KDF metadata fields (`umpVersion`, `kdfAlgorithm`, `kdfParams`) to on-chain tokens.
+- Update `parseLookupAnswer`, `serializeUMPToken`, and `deserializeUMPToken` to parse and round-trip v3 KDF metadata.
+- Export `ARGON2ID_DEFAULT_*` constants (`iterations`, `memoryKiB`, `parallelism`, `hashLength`).
+- Keep legacy token behavior unchanged.
+
+## wallet-toolbox 2.1.10
+
+- TaskReviewUtxos added
+- TaskReviewProvenTxs added
+- TaskReviewDoubleSpends added
+- exchangeratesapi.io api key removed from Services. Defaults changed to rely on public chaintracks service which has private api key.
+- Fix bugs in TaskSendWaiting
+- Add Task namespace with all monitor tasks exports.
+- adminStats now splits out abandoned transactions from failed.
+- admin site support changes.
+
+## wallet-toolbox 2.1.9
+
+- Fix batch sending bug in TaskSendWaiting 
+
+## wallet-toolbox 2.1.8
+
+- Drop no longer required verifyAndRepairBeef method
+- Simplify collectCommission tests in offsetKey.test.ts
+- Remove duplicate BulkFileDataReader class.
+- Reorg createDefault*ChaintracksOptions to reduce duplicated code.
+- Reorg auth-method-interactors
+- Flip waitForAuthentication grouped permission request event (now first) and activation (now second)
+
+## wallet-toolbox 2.1.7
+
+- Sonarqube recommended changes...
+
+## wallet-toolbox 2.1.6
+
+- Improve change-making algorithm: cap change outputs per transaction to 8 (gradual UTXO pool build-up, smaller BEEFs). Enforce dynamic dust floor so no change output is worth less than 2× the fee to spend it.
+
+## wallet-toolbox 2.1.5
+
+- Update deps, docs, lint
+
+## wallet-toolbox 2.1.4
+
+- Change `Monitor`: Add SSE event hooks.
+- Add `ArcSSEClient` to drive SSE event hooks on mobile
+
+## wallet-toolbox 2.1.3
+
+- Change `Monitor`: no retry for invalid beefs in TaskSendWaiting. Cleanup logging.
+
+## wallet-toolbox 2.1.2
+
+- Fix Chaintracks no longer hangs if bulk ingestor fails to reach chain tip.
+
+## wallet-toolbox 2.1.1
+
+### Add `teratest` and `mock` chain types
+
+- Change `Chain` type from `'main' | 'test'` to `'main' | 'test' | 'teratest' | 'mock'`.
+
+**`teratest` chain:**
+
+- Add ARC URL `https://arc-teratest.taal.com` for the teratest network.
+- Chaintracks URL follows existing `${chain}net-chaintracks.babbage.systems` pattern.
+- WhatsOnChain URL follows existing `https://api.whatsonchain.com/v1/bsv/${network}` pattern.
+- Bitails is not available on teratest (only `main` and `test`).
+
+**`mock` chain — full self-contained mock blockchain:**
+
+- Add new `src/mockchain/` module with `MockServices`, `MockChainTracker`, `MockMiner`, `MockChainStorage`, and merkle tree utilities.
+- `MockServices` implements the `WalletServices` interface against a local SQLite database (3 tables: `mockchain_block_headers`, `mockchain_transactions`, `mockchain_utxos`).
+- Transactions are validated with full script execution via `@bsv/sdk` `Transaction.verify()`.
+- Coinbase maturity rule enforced (100 block confirmations required before spending).
+- On-demand block mining via `MockServices.mineBlock()`.
+- Chain reorganization simulation via `MockServices.reorg()` with `txidMap` for controlling which transactions land in which new blocks.
+- Add `TaskMineBlock` monitor task for periodic mining (10 minutes) with `mineNow` static flag for on-demand triggering.
+- `Monitor.services` type widened from `Services` to `Services | WalletServices` to support mock chain.
+- `Services` class, `createDefaultWalletServicesOptions`, and external service providers (`WhatsOnChain`, `Bitails`) throw explicit errors if instantiated with `'mock'` chain.
+
+**Explicit chain handling across codebase:**
+
+- Convert chain-dependent ternaries to explicit switch statements in `toWalletNetwork`, `genesisHeader`, `Bitails` constructor, WoC WebSocket ingestors, and `ChaintracksStorageNoDb`.
+- Each chain value (`main`, `test`, `teratest`, `mock`) is handled explicitly rather than falling through a catch-all else branch.
+
+## wallet-toolbox 2.0.24
+
+Optimize createAction (fewer db transactions)
+Add postBeef services soft timeout failover
+PR 130 randomBytesHex in Setup
+
+## wallet-toolbox 2.0.23
+
+Add output table indices to speed up listOutputs and createAction
+
+## wallet-toolbox 2.0.20
+
+Add BRC-115 new manifest specs to support group and counterparty permissions.
+
+## wallet-toolbox 2.0.19
+
+Add BRC-114 action time labels for filtering actions by creation time.
+
+## wallet-toolbox 2.0.18
+
+Update bsv/auth-express-middleware 2.0.4
+
+## wallet-toolbox 2.0.17
+
+Update @bsv/sdk to 2.0.4 to fix StorageServer failing from stale AuthFetch sessions.
+
+## wallet-toolbox 2.0.9
+
+Added support for more currency types.
+
+## wallet-toolbox 2.0.8
+
+Add check for cross session signAction errors.
+
+## wallet-toolbox 2.0.7
+
+Add StorageClient.man.test.ts to stress test storage.babbage.systems
+
 ## wallet-toolbox 2.0.5
 
 Change sqlite support to better-sqlite3, all tests resolved. Support for existing databases confirmed.
@@ -276,7 +460,7 @@ Changes to improve computing balances (sum of satoshis) over various sets of wal
 ## wallet-toolbox 1.3.29
 
 - add verifyUnlockScripts to both createAction and signAction flows
-  
+
 ## wallet-toolbox 1.3.28
 
 - adminStats now includes monitorStats and servicesStats of type ServicesCallHistory (wallet-toolbox/src/sdk/WalletServices.interfaces.ts)
@@ -307,7 +491,7 @@ New outputs created by `createAction` / `signAction` that are NOT assigned to a
 Implications:
 
 - Outputs transferred to a second party, either through internalizeAction or custom means, MUST NOT be assigned to a basket
-as this allows them to be spent without your wallet being notified that they are no longer spendable. This is a usage guideline, it is not enforced.
+  as this allows them to be spent without your wallet being notified that they are no longer spendable. This is a usage guideline, it is not enforced.
 - These outputs will NOT be returned by `listOutputs`, as it only returns spendable outputs.
 - These outputs WILL be returned by `listActions` with the includeOutputs option set to true.
 - Your wallet will mark any output you include as inputs in your own transactions as spent at the time of transaction creation.

package/README.md

@@ -1,43 +1,126 @@
-# BSV WALLET TOOLBOX
+# BSV Wallet Toolbox
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/bsv-blockchain/wallet-toolbox/push.yaml?branch=master&label=build)](https://github.com/bsv-blockchain/wallet-toolbox/actions)
+[![npm version](https://img.shields.io/npm/v/@bsv/wallet-toolbox)](https://www.npmjs.com/package/@bsv/wallet-toolbox)
+[![npm downloads](https://img.shields.io/npm/dm/@bsv/wallet-toolbox)](https://www.npmjs.com/package/@bsv/wallet-toolbox)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=bugs)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
+[![CodeQL](https://github.com/bsv-blockchain/wallet-toolbox/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/bsv-blockchain/wallet-toolbox/actions/workflows/github-code-scanning/codeql)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=bsv-blockchain_wallet-toolbox&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=bsv-blockchain_wallet-toolbox)
+[![License](https://img.shields.io/github/license/bsv-blockchain/wallet-toolbox)](./LICENSE.txt)
+
+A [BRC-100](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0100.md) conforming wallet implementation for the BSV blockchain, built on the [BSV SDK](https://bsv-blockchain.github.io/ts-sdk). Provides persistent storage, protocol-based key derivation, transaction monitoring, chain tracking, and signing — everything needed to build wallet-powered applications on BSV.
+
+## 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.
+
+### What's Inside
+
+| Module | Description |
+|--------|-------------|
+| **Wallet** | Full BRC-100 wallet — action creation, signing, certificate management, identity discovery, output tracking |
+| **Storage** | Pluggable persistence with three backends: **SQLite/MySQL** (via Knex), **IndexedDB** (browser/mobile), and **remote** (client/server over HTTP) |
+| **Services** | Network layer — ARC transaction broadcasting, chain tracking (Chaintracks), merkle proof verification, UTXO lookups via WhatsOnChain |
+| **Monitor** | Background daemon that watches pending transactions, rebroadcasts failures, handles chain reorganizations, and manages proof acquisition |
+| **Signer** | `WalletSigner` bridges any BRC-100 wallet to the SDK's `Transaction` signing interface |
+| **Key Management** | `PrivilegedKeyManager` for secure key storage with Shamir secret sharing and obfuscation; protocol-based key derivation per BRC-42/43 |
+| **Permissions** | `WalletPermissionsManager` for fine-grained per-app, per-protocol permission control with grouped approval flows |
+| **MockChain** | In-memory blockchain for testing — mock mining, UTXO tracking, and merkle proof generation without a network |
+| **Entropy** | `EntropyCollector` gathers mouse/touch entropy for high-quality randomness in browser environments |
+
+### Packages
+
+The toolbox publishes three npm packages from this repo:
+
+- **[`@bsv/wallet-toolbox`](https://www.npmjs.com/package/@bsv/wallet-toolbox)** — Full package with all storage backends (SQLite, MySQL, IndexedDB, remote)
+- **[`@bsv/wallet-toolbox-client`](https://www.npmjs.com/package/@bsv/wallet-toolbox-client)** — Browser build; excludes Node-only backends (Knex/SQLite/MySQL)
+- **[`@bsv/wallet-toolbox-mobile`](https://www.npmjs.com/package/@bsv/wallet-toolbox-mobile)** — Mobile build; IndexedDB and remote storage only
+
+## Getting Started
+
+### Installation
+
+```bash
+# Full (Node.js servers, CLIs)
+npm install @bsv/wallet-toolbox
+
+# Browser apps
+npm install @bsv/wallet-toolbox-client
+
+# React Native / mobile
+npm install @bsv/wallet-toolbox-mobile
+```
+
+### Quick Example
+
+```typescript
+import { SetupWallet } from '@bsv/wallet-toolbox'
+
+// Create a wallet with SQLite storage and default mainnet services
+const wallet = await SetupWallet({
+  env: 'main',
+  endpointUrl: 'https://your-storage-server.example.com'
+})
+
+// Create a transaction
+const result = await wallet.createAction({
+  description: 'Send payment',
+  outputs: [{
+    lockingScript: '76a914...88ac',
+    satoshis: 1000,
+    outputDescription: 'payment'
+  }]
+})
+```
 
-BSV BLOCKCHAIN | BRC100 Conforming Wallet, Wallet Storage and Wallet Signer Components
-
-## Objective
-
-The BSV Wallet Toolbox builds on the [SDK](https://bsv-blockchain.github.io/ts-sdk).
-
-It aims to support building sophisticated applications and services on the BSV Blockchain technology stack.
+## Documentation
 
-By providing interlocking building blocks for persistent storage and protocol based key derivation, it serves as an essential toolbox for developers looking to build on the BSV Blockchain.
+[Full API documentation](https://bsv-blockchain.github.io/wallet-toolbox) is available on GitHub Pages.
 
-## Documentation
+The codebase has detailed JSDoc annotations throughout — these will surface inline in editors like VS Code.
 
-[The Docs](https://bsv-blockchain.github.io/wallet-toolbox) are available here on Github pages.  
+## Development
 
-The Toolbox is richly documented with code-level annotations. This should show up well within editors like VSCode.  
+```bash
+git clone https://github.com/bsv-blockchain/wallet-toolbox.git
+cd wallet-toolbox
+npm install
+npm run build
+npm test
+```
 
-## Contribution Guidelines
+Tests use Jest. Files named `*.man.test.ts` are manual/integration tests excluded from CI — they require network access or long runtimes and are run locally by developers.
 
-We're always looking for contributors to help us improve the SDK. Whether it's bug reports, feature requests, or pull requests - all contributions are welcome.
+## Contributing
 
-1. **Fork & Clone**: Fork this repository and clone it to your local machine.
-2. **Set Up**: Run `npm install` to install all dependencies.
-3. **Make Changes**: Create a new branch and make your changes.
-4. **Test**: Ensure all tests pass by running `npm test`.
-5. **Commit**: Commit your changes and push to your fork.
-6. **Pull Request**: Open a pull request from your fork to this repository.
-For more details, check the [contribution guidelines](./CONTRIBUTING.md).
+We welcome bug reports, feature requests, and pull requests.
 
-## Support & Contacts
+1. Fork and clone the repository
+2. `npm install`
+3. Create a feature branch
+4. Make your changes and ensure `npm test` passes
+5. Open a pull request
 
-Project Owners: Thomas Giacomo and Darren Kellenschwiler
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for full guidelines.
 
-Development Team Lead: Ty Everett
+## Contributors
 
-For questions, bug reports, or feature requests, please open an issue on GitHub or contact us directly.
+| | Name | GitHub | Role |
+|---|------|--------|------|
+| | Tone Engel | [@tonesnotes](https://github.com/tonesnotes) | Lead developer, maintainer |
+| | Darren Kellenschwiler | [@sirdeggen](https://github.com/sirdeggen) | Core contributor |
+| | Brayden Langley | [@BraydenLangley](https://github.com/BraydenLangley) | Core contributor |
+| | Ty Everett | [@ty-everett](https://github.com/ty-everett) | Core contributor, reviewer |
+| | Jackie Lu | [@jackielu3](https://github.com/jackielu3) | Contributor |
+| | David Case | [@shruggr](https://github.com/shruggr) | Contributor |
+| | Stephen Thomson | [@Stephen-Thomson](https://github.com/Stephen-Thomson) | Contributor |
+| | Chance Barimbao | [@ChanceBarimbao](https://github.com/ChanceBarimbao) | Contributor |
 
 ## License
 
-The license for the code in this repository is the Open BSV License. Refer to [LICENSE.txt](./LICENSE.txt) for the license text.
-
-Thank you for being a part of the BSV Blockchain Libraries Project. Let's build the future of BSV Blockchain together!
+Released under the [Open BSV License](./LICENSE.txt).