> For the complete documentation index, see [llms.txt](https://hub.bsvblockchain.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.bsvblockchain.org/bsv-code-academy/bsv-simple/simple-sdk/architecture.md).

# Architecture

## Design Principles

1. **One import, full access** — `createWallet()` returns a single object with every method attached.
2. **Modular internals** — Each feature (tokens, inscriptions, messagebox, etc.) is a separate module that can be understood independently.
3. **Browser/server parity** — Same API surface whether you're in the browser or on the server.
4. **Progressive complexity** — Simple things are simple (`wallet.pay()`), complex things are possible (`wallet.send()` with multi-output specs).

## Module Composition

The library uses a mixin pattern to compose wallet functionality:

```
WalletCore (abstract base)
  ├── _BrowserWallet (wraps WalletClient)
  └── _ServerWallet  (wraps ToolboxWallet)

Modules (mixed in via Object.assign):
  ├── tokens        → createToken, listTokenDetails, sendToken, redeemToken, ...
  ├── inscriptions  → inscribeText, inscribeJSON, inscribeFileHash, inscribeImageHash
  ├── messagebox    → certifyForMessageBox, sendMessageBoxPayment, ...
  ├── certification → acquireCertificateFrom, listCertificatesFrom, relinquishCert
  ├── overlay       → advertiseSHIP, advertiseSLAP, broadcastAction, withRetry
  ├── did           → getDID, resolveDID, registerDID
  └── credentials   → acquireCredential, listCredentials, createPresentation
```

When you call `createWallet()`, the library:

1. Creates a `WalletClient` and connects to the browser extension
2. Instantiates `_BrowserWallet` (which extends `WalletCore`)
3. Calls each module factory (`createTokenMethods(wallet)`, `createInscriptionMethods(wallet)`, etc.)
4. Merges all returned methods onto the wallet object via `Object.assign()`
5. Returns the composed wallet with the union type `BrowserWallet`

The same process happens for `ServerWallet.create()`, but with `ToolboxWallet` from `@bsv/wallet-toolbox` instead of `WalletClient`.

## WalletCore — The Base Class

`WalletCore` is an abstract class that provides:

* **Wallet info**: `getIdentityKey()`, `getAddress()`, `getStatus()`, `getWalletInfo()`
* **Key derivation**: `derivePublicKey()`, `derivePaymentKey()`
* **Core transaction methods**: `pay()`, `send()`, `fundServerWallet()`

Subclasses must implement `getClient(): WalletInterface` to provide the underlying wallet.

## Output Routing in `send()`

The `send()` method is the core primitive. It takes an array of output specifications and routes each one based on what fields are present:

| Fields Present | Output Type    | Result                          |
| -------------- | -------------- | ------------------------------- |
| `to` only      | **P2PKH**      | Standard payment to an address  |
| `data` only    | **OP\_RETURN** | Data inscription (0 satoshis)   |
| `to` + `data`  | **PushDrop**   | Encrypted token locked to a key |

```typescript
await wallet.send({
  outputs: [
    { to: key, satoshis: 500 },                           // → P2PKH
    { data: ['Hello!'] },                                   // → OP_RETURN
    { to: key, data: [{ v: 1 }], satoshis: 1 }            // → PushDrop
  ]
})
```

## Standalone Classes

Some classes work independently of any wallet:

| Class                   | Purpose                                              | Import                |
| ----------------------- | ---------------------------------------------------- | --------------------- |
| `DID`                   | Generate/parse/validate `did:bsv:` identifiers       | `@bsv/simple/browser` |
| `Certifier`             | Issue BSV certificates                               | `@bsv/simple/browser` |
| `Overlay`               | Create topic broadcasters and lookup resolvers       | `@bsv/simple/browser` |
| `CredentialSchema`      | Define and validate credential field schemas         | `@bsv/simple/browser` |
| `CredentialIssuer`      | Issue, verify, and revoke W3C Verifiable Credentials | `@bsv/simple/browser` |
| `MemoryRevocationStore` | In-memory revocation secret storage (browser/tests)  | `@bsv/simple/browser` |
| `FileRevocationStore`   | File-based revocation secret storage (server only)   | `@bsv/simple/server`  |

## Basket System

BSV wallets organize outputs into **baskets** — named groups that let you track and query outputs by category. Think of them as folders for your UTXOs.

```
my-payments/          → Payment outputs
my-tokens/            → PushDrop tokens
my-change/            → Recovered change outputs
text/                 → Text inscriptions
json/                 → JSON inscriptions
revocation-utxos/     → Credential revocation locks
```

Many methods accept a `basket` parameter to specify where outputs should be stored.

## Dependencies

| Package                      | Role                                                   | Environment      |
| ---------------------------- | ------------------------------------------------------ | ---------------- |
| `@bsv/sdk`                   | Core blockchain primitives, cryptography, WalletClient | Browser + Server |
| `@bsv/wallet-toolbox`        | ToolboxWallet, WalletSigner, StorageClient             | Server only      |
| `@bsv/wallet-toolbox-client` | Client-only wallet storage (browser-safe alternative)  | Browser          |
| `@bsv/message-box-client`    | PeerPayClient for P2P messaging                        | Browser + Server |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://hub.bsvblockchain.org/bsv-code-academy/bsv-simple/simple-sdk/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.