@bopen-io/wallet-toolbox 2.0.5-idb-fix.2 → 2.1.8-spending-fix.1

package/CHANGELOG.md

@@ -4,6 +4,108 @@ 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.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 +378,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 +409,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).