@bsv/wallet-toolbox 1.1.0

package/.env.template

@@ -0,0 +1,22 @@
+# set to empty if MySQL is available for testing and database schemas exist, set to 1 to not test against MySQL
+NOMYSQL = 1
+# set to empty to not run slow and long running tests. set to 1 to run them.
+RUNSLOWTESTS =
+
+# this will be getEnv('main').identityKey property value
+MY_MAIN_IDENTITY = '028cb1d772b59157ee2d72cce30c515e4c3312e5e73ea111ff689dac88d93aaeb8'
+# this will be getEnv('main').userId property value
+MY_MAIN_USERID = 83
+
+# this will be getEnv('test').identityKey property value
+MY_TEST_IDENTITY = '03ac2d10bdb0023f4145cc2eba2fcd2ad3070cb2107b0b48170c46a9440e4cc3fe'
+# this will be getEnv('test').userId property value
+MY_TEST_USERID = 6
+
+# JSON.stringified of object who's keys are identityKey values and the values are corresponding private keys.
+DEV_KEYS = '{
+    "03ac2d10bdb0023f4145cc2eba2fcd2ad3070cb2107b0b48170c46a9440e4cc3fe": "<private key as 32 hex bytes>"
+}'
+
+NOMYSQL = 1
+RUNSLOWTESTS =

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug Report
+about: Report a bug or an issue you've found with `@bsv/sdk`.
+title: "[BUG]"
+labels: bug
+assignees: ''
+
+---
+
+## Bug Description
+
+Briefly describe the bug/issue you've encountered.
+
+## Steps to Reproduce
+
+1. Step 1
+2. Step 2
+3. ...
+
+## Expected Behavior
+
+What should have happened if the bug hadn't occurred?
+
+## Actual Behavior
+
+What actually happened?
+
+## Stack Traces or Screenshots
+
+If applicable, add screenshots or stack traces to help explain the issue.
+
+## Environment
+
+- OS: [e.g. MacOS, Windows]
+- Node version: [e.g. 12.20]
+- `@bsv/sdk` version: [e.g. 1.2.3]
+
+## Additional Information
+
+Provide any additional context or information about the bug.

package/.github/ISSUE_TEMPLATE/discussion.md

@@ -0,0 +1,24 @@
+---
+name: Discussion
+about: Propose a discussion or seek clarification about a feature or topic.
+title: "[DISCUSSION]"
+labels: discussion
+assignees: ''
+
+---
+
+## Summary
+
+Briefly describe the topic you'd like to discuss.
+
+## Motivation
+
+Why do you believe this to be important?
+
+## Description
+
+Provide a detailed description or elaborate on your topic.
+
+## Additional References
+
+Provide any additional articles, links, or context that would help facilitate the discussion.

package/.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Description of Changes
+
+Provide a brief description of the changes you've made.
+
+## Linked Issues / Tickets
+
+Reference any related issues or tickets, e.g. "Closes #123".
+
+## Testing Procedure
+
+Describe the tests you've added or any testing steps you've taken.
+
+- [ ] I have added new unit tests
+- [ ] All tests pass locally
+- [ ] I have tested manually in my local environment
+
+## Checklist:
+
+- [ ] I have performed a self-review of my own code
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have updated `CHANGELOG.md` with my changes
+- [ ] I have run `npm run doc` and `npm run lint` one final time before requesting a review
+- [ ] I have run `npm version patch` so that my changes will trigger a new version to be released when they are merged

package/.github/workflows/push.yaml

@@ -0,0 +1,66 @@
+on: [push, pull_request]
+name: Build and Test
+jobs:
+  test:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: Cache node_modules
+      id: cache-modules
+      uses: actions/cache@v1
+      with:
+        path: node_modules
+        key: ${{ matrix.node-version }}-${{ runner.OS }}-build-${{ hashFiles('package.json') }}
+    - name: Build
+      if: steps.cache-modules.outputs.cache-hit != 'true'
+      run: npm install
+    - name: Test
+      run: npm run test
+  publish:
+    name: Publish
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    steps:
+    - name: Authenticate with registry
+      run: echo "//registry.npmjs.org/:_authToken=$NODE_AUTH_TOKEN" > ~/.npmrc
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.BSV_NPM_TOKEN }}
+    - uses: actions/checkout@v3
+    - name: Use Node.js 20.x
+      uses: actions/setup-node@v1
+      with:
+        node-version: 20.x
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.BSV_NPM_TOKEN }}
+    - name: Cache node_modules
+      id: cache-modules
+      uses: actions/cache@v3
+      with:
+        path: node_modules
+        key: 20.x-${{ runner.OS }}-build-${{ hashFiles('package.json') }}
+    - name: Install deps
+      if: steps.cache-modules.outputs.cache-hit != 'true'
+      run: npm install
+    - name: Build
+      run: npm run build
+    - name: Publish to NPM (expected to fail if version was not bumped manually)
+      run: npm publish --provenance --access public
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.BSV_NPM_TOKEN }}
+    - name: Publish client to NPM (expected to fail if version was not bumped manually)
+      run: npm publish --provenance --access public
+      working-directory: client
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.BSV_NPM_TOKEN }}

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "arrowParens": "avoid",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "endOfLine": "lf"
+}

package/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# CONTRIBUTING to `@bsv/wallet-toolbox`
+
+Thank you for considering contributing to the BSV Blockchain Libraries Project! This document outlines the processes and practices we expect contributors to adhere to.
+
+## Table of Contents
+
+- [CONTRIBUTING to `@bsv/wallet-toolbox`](#contributing-to-bsvwallet-toolbox)
+  - [Table of Contents](#table-of-contents)
+  - [General Guidelines](#general-guidelines)
+  - [Code of Conduct](#code-of-conduct)
+    - [Posting Issues and Comments](#posting-issues-and-comments)
+    - [Coding and PRs](#coding-and-prs)
+  - [Getting Started](#getting-started)
+  - [Pull Request Process](#pull-request-process)
+  - [Coding Conventions](#coding-conventions)
+  - [Documentation and Testing](#documentation-and-testing)
+  - [Contact \& Support](#contact--support)
+
+## General Guidelines
+
+- **Issues First**: If you're planning to add a new feature or change existing behavior, please open an issue first. This allows us to avoid multiple people working on similar features and provides a place for discussion.
+  
+- **Stay Updated**: Always pull the latest changes from the main branch before creating a new branch or starting on new code.
+  
+- **Simplicity Over Complexity**: Your solution should be as simple as possible, given the requirements.
+
+## Code of Conduct
+
+### Posting Issues and Comments
+
+- **Be Respectful**: Everyone is here to help and grow. Avoid any language that might be considered rude or offensive.
+  
+- **Be Clear and Concise**: Always be clear about what you're suggesting or reporting. If an issue is related to a particular piece of code or a specific error message, include that in your comment.
+  
+- **Stay On Topic**: Keep the conversation relevant to the issue at hand. If you have a new idea or unrelated question, please open a new issue.
+
+### Coding and PRs
+
+- **Stay Professional**: Avoid including "fun" code, comments, or irrelevant file changes in your commits and pull requests.
+
+## Getting Started
+
+1. **Fork the Repository**: Click on the "Fork" button at the top-right corner of this repository.
+  
+2. **Clone the Forked Repository**: `git clone https://github.com/YOUR_USERNAME/wallet-toolbox.git`
+
+3. **Navigate to the Directory**: `cd wallet-toolbox`
+
+4. **Install Dependencies**: Since we maintain all code within this library, there shouldn't be any runtime dependencies. Nevertheless, always run `npm install` after pulling to ensure tooling is up to date.
+
+## Pull Request Process
+
+1. **Create a Branch**: For every new feature or bugfix, create a new branch.
+  
+2. **Commit Your Changes**: Make your changes and commit them. Commit messages should be clear and concise to explain what was done.
+  
+3. **Run Tests**: Ensure all tests pass using Jest: `npm test`.
+  
+4. **Documentation**: All code must be fully annotated with comments. Update the documentation by running `npm run doc` before creating a pull request.
+  
+5. **Push to Your Fork**: `git push origin your-new-branch`.
+  
+6. **Open a Pull Request**: Go to your fork on GitHub and click "New Pull Request". Fill out the PR template, explaining your changes.
+  
+7. **Code Review**: At least two maintainers must review and approve the PR before it's merged. Address any feedback or changes requested.
+  
+8. **Merge**: Once approved, the PR will be merged into the main branch.
+
+## Coding Conventions
+
+- **Code Style**: We use `ts-standard` for our TypeScript coding style. Run `npm run lint` to ensure your code adheres to this style.
+  
+- **No Runtime Dependencies**: All code should be maintained within this library. Do not introduce external dependencies.
+  
+- **Testing**: Always include tests for new code or changes. We aim for industry-standard levels of test coverage.
+  
+- **Documentation**: All functions, classes, and modules should be documented. Use annotation comments to describe the purpose, parameters, and return values.
+
+## Documentation and Testing
+
+- **Documentation**: Update the documentation whenever you add or modify the code. Run `npm run doc` to generate the latest docs.
+  
+- **Testing**: We use Jest for all tests. Write comprehensive tests, ensuring edge cases are covered. All PRs should maintain or improve the current test coverage.
+
+## Contact & Support
+
+If you have any questions or need assistance with your contributions, feel free to reach out. Remember, we're here to help each other grow and improve the `@bsv/wallet-toolbox`.
+
+Thank you for being a part of this journey. Your contributions help shape the future of the BSV Blockchain Libraries Project!

package/LICENSE.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

@@ -0,0 +1,124 @@
+# BSV WALLET TOOLBOX
+
+BSV BLOCKCHAIN | BRC100 Conforming Wallet, Wallet Storage and Wallet Signer Components
+
+The BSV Wallet Toolbox builds on the [SDK](https://bitcoin-sv.github.io/ts-sdk) to add support for:
+
+    - Persistent UTXO and transaction history management
+    - Standardized key derivation protocols.
+
+# Table of Contents
+
+  - [Objective](#objective)
+  - [Getting Started](#getting-started)
+  - [Features \& Deliverables](#features--deliverables)
+  - [Documentation](#documentation)
+  - [Contribution Guidelines](#contribution-guidelines)
+  - [Support \& Contacts](#support--contacts)
+  - [License](#license)
+
+## Objective
+
+The BSV Wallet Toolbox Project aims to support building sophisticated applications and services on the BSV Blockchain technology stack.
+
+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.
+
+## Getting Started
+
+### Installation
+
+To install the toolbox, run:
+
+```bash
+npm install @bsv/wallet-toolbox
+```
+
+### Basic Usage
+
+Here's a simple example of using the toolbox to create and fund a testnet wallet using SQLite for persistent storage:
+
+```javascript
+import { InternalizeActionArgs, PrivateKey, Utils } from '@bsv/sdk'
+import { test } from '@bsv/wallet-toolbox'
+
+const rootKeyHex = PrivateKey.fromRandom().toString()
+console.log(`MAKE A SECURE COPY OF YOUR WALLET PRIVATE ROOT KEY: ${rootKeyHex}`)
+
+const { wallet } = await test._tu.createSQLiteTestWallet({
+    filePath: './myTestWallet.sqlite',
+    databaseName: 'myTestWallet',
+    chain: 'test',
+    rootKeyHex
+})
+
+// Obtain a Wallet Payment for your new wallet from a testnet funding faucet.
+// Update or replace the values in the following example object with your actual funding payment.
+// Note that the values below will not be accepted as they are not intended for your new wallet.
+const r = {
+    senderIdentityKey: '03ac2d10bdb0023f4145cc2eba2fcd2ad3070cb2107b0b48170c46a9440e4cc3fe',
+    vout: 0,
+    txid: '942f094cee517276182e5857369ea53d64763a327d433489312a9606db188dfb',
+    derivationPrefix: 'jSlU588BWkw=',
+    derivationSuffix: 'l37vv/Bn4Lw=',
+    atomicBEEF: '01010101942f094cee517...a914b29d56273f6c1df90cd8f383c8117680f2bdd05188ac00000000'
+}
+
+const args: InternalizeActionArgs = {
+    tx: Utils.toArray(r.atomicBEEF, 'hex'),
+    outputs: [
+        {
+            outputIndex: r.vout,
+            protocol: 'wallet payment',
+            paymentRemittance: {
+                derivationPrefix: r.derivationPrefix,
+                derivationSuffix: r.derivationSuffix,
+                senderIdentityKey: r.senderIdentityKey
+            }
+        }
+    ],
+    description: 'from faucet'
+}
+
+const rw = await wallet.internalizeAction(args)
+console.log(rw.accepted)
+```
+
+For a more detailed tutorial and advanced examples, check our [Documentation](#documentation).
+
+## Features & Deliverables
+
+- **Feature1**: Summary of feature1.
+
+## Documentation
+
+[The Docs](https://bitcoin-sv.github.io/wallet-toolbox) are available here on Github pages.  
+[Example code](https://docs.bsvblockchain.org/guides/sdks/ts/examples) is available over on our gitbook.  
+
+The Toolbox is richly documented with code-level annotations. This should show up well within editors like VSCode.  
+
+## Contribution Guidelines
+
+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.
+
+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).
+
+## Support & Contacts
+
+Project Owners: Thomas Giacomo and Darren Kellenschwiler
+
+Development Team Lead: Ty Everett
+
+For questions, bug reports, or feature requests, please open an issue on GitHub or contact us directly.
+
+## 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!
+

package/docs/README.md

@@ -0,0 +1,15 @@
+# BSV Wallet Toolbox API Documentation
+
+The documentation is split into various pages, each covering a set of related functionality. The pages are as follows:
+
+- [Wallet](./wallet.md) — 
+- [Client](./client.md) — 
+- [Storage](./storage.md) — 
+- [Services](./services.md) — 
+- [Monitor](./monitor.md) — 
+
+## Swagger
+
+[BRC-100](https://brc.dev/100) defines a Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface which is implemented in this library within the WalletClient class. The API is laid out here as a swagger openapi document to offer a fast-track to understanding the interface which is implemented across multiple substrates. The JSON api is generally considered a developer friendly introduction to the WalletClient, where an binary equivalent ABI may be preferred for production use cases.
+
+- [Wallet JSON API Swagger](https://bitcoin-sv.github.io/ts-sdk/swagger)