bsv-blockchain · sirdeggen · Feb 20, 2026 · Feb 23, 2026 · Feb 23, 2026 · Feb 23, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.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.
diff --git a/.github/ISSUE_TEMPLATE/discussion.md b/.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.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,25 @@
+## 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 fixed all linter errors to ensure these changes are compliant with `ts-standard`
+- [ ] I have run `npm version patch` so that my changes will trigger a new version to be released when they are merged
diff --git a/.github/workflows/push.yaml b/.github/workflows/push.yaml
@@ -0,0 +1,71 @@
+name: Build and Test
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  id-token: write  # Required for OIDC
+  contents: read
+
+jobs:
+  test:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22, 24]
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        registry-url: 'https://registry.npmjs.org'
+    - run: npm ci
+    - run: npm run lint:ci --if-present
+    - run: npm run test:coverage --if-present
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: ./coverage/lcov.info
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+  publish:
+    name: Publish
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '24'
+        registry-url: 'https://registry.npmjs.org'
+    - run: npm ci
+    - run: npm run build
+    - name: Check if version already published
+      id: check-version
+      run: |
+        PACKAGE_NAME=$(node -p "require('./package.json').name")
+        PACKAGE_VERSION=$(node -p "require('./package.json').version")
+
+        echo "Package: $PACKAGE_NAME@$PACKAGE_VERSION"
+
+        # Check if this version exists on npm
+        if npm view "$PACKAGE_NAME@$PACKAGE_VERSION" version 2>/dev/null; then
+          echo "Version $PACKAGE_VERSION already published"
+          echo "should_publish=false" >> $GITHUB_OUTPUT
+        else
+          echo "Version $PACKAGE_VERSION not yet published"
+          echo "should_publish=true" >> $GITHUB_OUTPUT
+        fi
+    - name: Publish to npm
+      if: steps.check-version.outputs.should_publish == 'true'
+      run: npm publish
+    - name: Skip publishing
+      if: steps.check-version.outputs.should_publish == 'false'
+      run: echo "Skipping publish - version already exists on npm"
diff --git a/README.md b/README.md
@@ -0,0 +1,59 @@
+# @bsv/simple
+
+A high-level TypeScript library that makes BSV blockchain development simple. Build wallets, send payments, create tokens, issue credentials, and more — in just a few lines of code.
+
+## What is @bsv/simple?
+
+`@bsv/simple` wraps the low-level `@bsv/sdk` into a clean, modular API. Instead of manually constructing locking scripts, managing key derivation, and handling transaction internalization, you call methods like `wallet.pay()`, `wallet.createToken()`, and `wallet.inscribeText()`.
+
+## What can you build?
+
+| Feature | Description |
+|---------|-------------|
+| **Payments** | Send BSV to any identity key via BRC-29 peer-to-peer payments |
+| **Multi-Output Transactions** | Combine P2PKH payments, OP_RETURN data, and PushDrop tokens in a single transaction |
+| **Encrypted Tokens** | Create, transfer, and redeem PushDrop tokens with encrypted payloads |
+| **Inscriptions** | Write text, JSON, or file hashes permanently to the blockchain |
+| **MessageBox P2P** | Send and receive payments and tokens peer-to-peer via MessageBox |
+| **Certification** | Issue and manage BSV certificates with a standalone Certifier |
+| **Verifiable Credentials** | W3C-compatible VCs backed by BSV certificates, with on-chain revocation |
+| **DIDs** | Generate and resolve `did:bsv:` Decentralized Identifiers |
+| **Overlay Networks** | Broadcast to and query SHIP/SLAP overlay services |
+| **Server Wallet** | Run a backend wallet for automated operations and funding flows |
+
+## Browser vs Server
+
+The library has two entry points:
+
+- **`@bsv/simple`** (default) — Browser-safe. Uses `WalletClient` from `@bsv/sdk` to connect to the user's wallet on the client side. Will not pull in any server-only dependencies.
+- **`@bsv/simple/server`** — Uses `@bsv/wallet-toolbox` to run a server-side wallet from a private key. Used for agents, or servers receiving payments.
+
+Both entry points provide the same API surface — the only difference is how they connect to the underlying wallet.
+
+## A taste of the API
+
+```typescript
+import { createWallet } from '@bsv/simple/browser'
+
+// Connect to the user's wallet
+const wallet = await createWallet()
+
+// Send a payment
+await wallet.pay({ to: recipientKey, satoshis: 1000, memo: 'Coffee' })
+
+// Create an encrypted token
+await wallet.createToken({ data: { type: 'loyalty', points: 50 }, basket: 'rewards' })
+
+// Inscribe text on-chain
+await wallet.inscribeText('Hello BSV!')
+
+// Get your DID
+const did = wallet.getDID()
+// { id: 'did:bsv:02abc...', ... }
+```
+
+## Next Steps
+
+- [Quick Start](docs/quick-start.md) — Get running in 5 minutes
+- [Installation](docs/installation.md) — Detailed setup instructions
+- [Architecture](docs/architecture.md) — How the library is built
diff --git a/docs/README.md b/docs/README.md
@@ -10,7 +10,7 @@ A high-level TypeScript library that makes BSV blockchain development simple. Bu
 
 | Feature | Description |
 |---------|-------------|
-| **Payments** | Send BSV to any identity key with optional memos and change recovery |
+| **Payments** | Send BSV to any identity key via BRC-29 peer-to-peer payments |
 | **Multi-Output Transactions** | Combine P2PKH payments, OP_RETURN data, and PushDrop tokens in a single transaction |
 | **Encrypted Tokens** | Create, transfer, and redeem PushDrop tokens with encrypted payloads |
 | **Inscriptions** | Write text, JSON, or file hashes permanently to the blockchain |
@@ -25,8 +25,8 @@ A high-level TypeScript library that makes BSV blockchain development simple. Bu
 
 The library has two entry points:
 
-- **`@bsv/simple/browser`** — Uses `WalletClient` from `@bsv/sdk` to connect to the user's browser wallet extension (MetaNet Client). No private keys in the browser.
-- **`@bsv/simple/server`** — Uses `@bsv/wallet-toolbox` to run a wallet from a private key on the server. Used for automated operations, payment processing, and funding flows.
+- **`@bsv/simple`** (default) — Browser-safe. Uses `WalletClient` from `@bsv/sdk` to connect to the user's wallet on the client side. Will not pull in any server-only dependencies.
+- **`@bsv/simple/server`** — Uses `@bsv/wallet-toolbox` to run a server-side wallet from a private key. Used for agents, or servers receiving payments.
 
 Both entry points provide the same API surface — the only difference is how they connect to the underlying wallet.
 
@@ -57,3 +57,44 @@ const did = wallet.getDID()
 - [Quick Start](quick-start.md) — Get running in 5 minutes
 - [Installation](installation.md) — Detailed setup instructions
 - [Architecture](architecture.md) — How the library is built
+
+# Table of Contents
+
+* [Introduction](README.md)
+* [Quick Start](quick-start.md)
+* [Installation](installation.md)
+* [Architecture](architecture.md)
+
+## Guides
+
+* [Browser Wallet](guides/browser-wallet.md)
+* [Server Wallet](guides/server-wallet.md)
+* [Payments](guides/payments.md)
+* [Tokens](guides/tokens.md)
+* [Inscriptions](guides/inscriptions.md)
+* [MessageBox & P2P](guides/messagebox.md)
+* [Certification](guides/certification.md)
+* [DID (Decentralized Identity)](guides/did.md)
+* [Verifiable Credentials](guides/credentials.md)
+* [Overlay Networks](guides/overlay.md)
+* [Next.js Integration](guides/nextjs-integration.md)
+
+## API Reference
+
+* [WalletCore](api-reference/wallet-core.md)
+* [BrowserWallet](api-reference/browser-wallet.md)
+* [ServerWallet](api-reference/server-wallet.md)
+* [Tokens Module](api-reference/tokens.md)
+* [Inscriptions Module](api-reference/inscriptions.md)
+* [MessageBox Module](api-reference/messagebox.md)
+* [Certification Module](api-reference/certification.md)
+* [DID Module](api-reference/did.md)
+* [Credentials Module](api-reference/credentials.md)
+* [Overlay Module](api-reference/overlay.md)
+* [Types](api-reference/types.md)
+* [Errors](api-reference/errors.md)
+
+## Advanced
+
+* [Gotchas & Pitfalls](gotchas.md)
+* [MCP Server](mcp-server.md)
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
diff --git a/docs/api-reference/browser-wallet.md b/docs/api-reference/browser-wallet.md
@@ -49,7 +49,6 @@ console.log(wallet.getIdentityKey()) // '02abc...'
 
 // With custom defaults
 const wallet = await createWallet({
-  changeBasket: 'my-change',
   network: 'main',
   registryUrl: '/api/identity-registry'
 })
@@ -61,7 +60,7 @@ const wallet = await createWallet({
 
 | Source | Methods |
 |--------|---------|
-| [WalletCore](wallet-core.md) | `getIdentityKey()`, `getAddress()`, `getStatus()`, `getWalletInfo()`, `getClient()`, `derivePublicKey()`, `derivePaymentKey()`, `pay()`, `send()`, `fundServerWallet()`, `reinternalizeChange()` |
+| [WalletCore](wallet-core.md) | `getIdentityKey()`, `getAddress()`, `getStatus()`, `getWalletInfo()`, `getClient()`, `derivePublicKey()`, `derivePaymentKey()`, `pay()`, `send()`, `fundServerWallet()` |
 | [Tokens](tokens.md) | `createToken()`, `listTokenDetails()`, `sendToken()`, `redeemToken()`, `sendTokenViaMessageBox()`, `listIncomingTokens()`, `acceptIncomingToken()` |
 | [Inscriptions](inscriptions.md) | `inscribeText()`, `inscribeJSON()`, `inscribeFileHash()`, `inscribeImageHash()` |
 | [MessageBox](messagebox.md) | `certifyForMessageBox()`, `getMessageBoxHandle()`, `revokeMessageBoxCertification()`, `sendMessageBoxPayment()`, `listIncomingPayments()`, `acceptIncomingPayment()`, `registerIdentityTag()`, `lookupIdentityByTag()`, `listMyTags()`, `revokeIdentityTag()` |

diff --git a/docs/api-reference/messagebox.md b/docs/api-reference/messagebox.md
@@ -79,8 +79,7 @@ Remove all registered handles for this wallet from the identity registry.
 ```typescript
 async sendMessageBoxPayment(
   to: string,
-  satoshis: number,
-  changeBasket?: string
+  satoshis: number
 ): Promise<any>
 ```
 
@@ -90,7 +89,6 @@ Send a payment via MessageBox P2P messaging.
 |-----------|------|---------|-------------|
 | `to` | `string` | *required* | Recipient's identity key |
 | `satoshis` | `number` | *required* | Amount to send |
-| `changeBasket` | `string` | `defaults.changeBasket` | Reinternalize change |
 
 **Returns:**
 
@@ -99,14 +97,12 @@ Send a payment via MessageBox P2P messaging.
   txid: string
   amount: number
   recipient: string
-  reinternalized?: ReinternalizeResult
 }
 ```
 
 **What happens:**
 1. Creates a payment token via `PeerPayClient.createPaymentToken()`
 2. Sends the token to `payment_inbox` message box
-3. If `changeBasket` is provided, reinternalizes change from the payment transaction
 
 ### listIncomingPayments()
 

diff --git a/docs/api-reference/server-wallet.md b/docs/api-reference/server-wallet.md
@@ -116,7 +116,7 @@ The typical server wallet funding flow:
 ```
 1. Server: wallet.createPaymentRequest({ satoshis: 50000 })
        ↓ (send PaymentRequest to client via API)
-2. Client: wallet.fundServerWallet(request, 'funding', 'change')
+2. Client: wallet.fundServerWallet(request, 'funding')
        ↓ (send tx bytes back to server via API)
 3. Server: wallet.receivePayment({ tx, senderIdentityKey, ... })
 ```