# arklabshq/wallet-sdk architecture

> Architecture diagram of the GitHub repository arklabshq/wallet-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arklabshq/wallet-sdk
- Repository: https://github.com/arklabshq/wallet-sdk

## Overview

##### Project type and purpose
- This is a TypeScript SDK library ("Ark Wallet SDK") for building Bitcoin wallets with support for on-chain and off-chain (Ark protocol) transactions.
- It exposes a programmatic API (Wallet, ServiceWorkerWallet, Identity) rather than a full-stack web application.

##### File structure
- Top-level directories:
- src/ – all TypeScript source code, organized by feature/module
- scripts/ – build/release helper scripts
- test/ – unit & integration tests plus fixtures
- .github/, Dockerfile, docker-compose.yml – CI/CD and containerization
- src/ submodules:
- identity/ – key management abstraction (InMemoryKey, external)
- wallet/ – core Wallet and ServiceWorkerWallet classes
- providers/ – onchain (Esplora) & offchain (Ark server) providers
- script/ – transaction‐script builders (base, tapscript, vhtlc, address, default)
- tree/ – vtxo tree creation, validation, signingSession orchestration
- musig2/ – MuSig2 key generation, nonce management, signing logic
- utils/ – coinselect, PSBT helper, txSizeEstimator, transactionHistory, bip21
- arknote/ – Ark‐specific off‐chain note handling
- types/, networks.ts – shared type and network definitions
- Config files (tsconfig, vitest.config, linting, formatting, workflows) indicate a mono-repo library with CI, testing, and release automation.

##### README for additional insights
- Core concepts: Wallet.create, getAddress, sendBitcoin (auto on/off chain), settle, getBalance, getTransactionHistory, getVtxos, getBoardingUtxos.
- Optional Service Worker mode: Worker.start(), ServiceWorkerWallet.create().
- Dependencies: Esplora API, optional Ark server API, BIP-21, PSBT, MuSig2.

##### Main components and interactions
a. Main components:
1. Client Application (your code that imports the SDK)
2. SDK Public API Layer
– Identity (InMemoryKey or custom signer)
– Wallet / ServiceWorkerWallet
3. Internal SDK Modules
– Providers (OnChainProvider ↔ Esplora API, ArkProvider ↔ Ark Server)
– Transaction Orchestrator
- script builder (script/)
- vtxo tree & validation (tree/)
- coin selector & PSBT utils (utils/)
- MuSig2 signer (musig2/)
– ArkNote manager (arknote/)
4. Persistence (browser IndexedDB via service worker)
5. External Services
– Esplora API (HTTP)
– Ark Server (HTTP)
– Bitcoin Network (via provider endpoints)
b. Relationships & data flows:
- Client → Wallet API (calls)
- Wallet → Identity.sign + script builder + coinselect → PSBT
- PSBT + MuSig2 → signed tx
- Wallet → Provider.sendTransaction → Esplora or Ark Server
- Provider.fetch UTXOs/transactions → Wallet → tree & history utils
- ServiceWorkerWallet: background thread ↔ IndexedDB ↔ main thread
c. Architectural patterns:
- Layered architecture (API → orchestration → low-level modules → external)
- Strategy/Provider pattern for on‐chain vs off‐chain logic
- Modular feature-based decomposition
- Optional service‐worker adapter
d. Key technologies and libraries:
- TypeScript, PSBT (BIP-174), MuSig2 Schnorr signatures, IndexedDB (service worker), Esplora HTTP API, Ark HTTP API

- Blue: public API layers (Client, Wallet, Identity)
- Green: core orchestration modules (script, tree, musig2, utils)
- Orange: providers and external services
- Gray: persistence (IndexedDB) and service worker
- Related modules inside a boundary labeled “SDK Core”

##### Essential elements
- Clear labels (component names, interfaces, protocols)
- Public API vs internal modules vs external systems vs persistence layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Application"]:::publicAPI

    subgraph "SDK Public API"
        Identity["Identity"]:::publicAPI
        Wallet["Wallet"]:::publicAPI
        SWWallet["ServiceWorkerWallet"]:::publicAPI
    end

    subgraph "SDK Core"
        script["Transaction Script Builders"]:::coreModules
        tree["VTXO Tree & Validation"]:::coreModules
        musig2["MuSig2 Module"]:::coreModules
        utils["Utility Functions"]:::coreModules
        arknote["ArkNote Manager"]:::coreModules
    end

    subgraph "Providers"
        ONCHAIN["On-Chain Provider"]:::providers
        ARKPROV["Off-Chain Provider"]:::providers
    end

    Esplora["Esplora API"]:::external
    ArkServer["Ark Server API"]:::external
    BitcoinNet["Bitcoin Network"]:::external

    ServiceWorker["Service Worker"]:::persistence
    IndexedDB["IndexedDB (Persistence)"]:::persistence

    Client -->|"import & create"| Wallet
    Client -->|"import & create"| SWWallet

    Wallet -->|"uses"| Identity
    SWWallet -->|"adapts to"| Wallet

    Wallet -->|"buildAddress()/sendBitcoin()"| script
    script -->|"generate scripts"| utils
    utils -->|"build PSBT"| musig2
    musig2 -->|"sign PSBT"| utils

    Wallet -->|"getVtxos()/getTransactionHistory()"| tree
    tree -->|"validate & session"| musig2
    Wallet -->|"arkNote()"| arknote

    Wallet -->|"sendTransaction()"| ONCHAIN
    Wallet -->|"sendTransaction()"| ARKPROV

    ONCHAIN -.->|"HTTP Request"| Esplora
    ARKPROV -.->|"HTTP Request"| ArkServer
    ONCHAIN -.-> BitcoinNet
    ARKPROV -.-> BitcoinNet

    SWWallet -->|"postMessage"| ServiceWorker
    ServiceWorker -->|"store/retrieve"| IndexedDB
    SWWallet -->|"retrieve UTXOs"| IndexedDB

    classDef publicAPI fill:#cfe2ff,stroke:#0366d6,color:#0366d6
    classDef coreModules fill:#d1e7dd,stroke:#116530,color:#116530
    classDef providers fill:#ffe5b4,stroke:#c96400,color:#c96400
    classDef external fill:#ffd966,stroke:#b38600,color:#b38600
    classDef persistence fill:#e0e0e0,stroke:#5a5a5a,color:#5a5a5a

    click Identity "https://github.com/arklabshq/wallet-sdk/blob/master/src/identity/index.ts"
    click Identity "https://github.com/arklabshq/wallet-sdk/blob/master/src/identity/inMemoryKey.ts"
    click Wallet "https://github.com/arklabshq/wallet-sdk/blob/master/src/wallet/index.ts"
    click Wallet "https://github.com/arklabshq/wallet-sdk/blob/master/src/wallet/wallet.ts"
    click SWWallet "https://github.com/arklabshq/wallet-sdk/blob/master/src/wallet/serviceWorker/wallet.ts"
    click ServiceWorker "https://github.com/arklabshq/wallet-sdk/blob/master/src/wallet/serviceWorker/worker.ts"
    click ServiceWorker "https://github.com/arklabshq/wallet-sdk/blob/master/src/wallet/serviceWorker/request.ts"
    click ServiceWorker "https://github.com/arklabshq/wallet-sdk/blob/master/src/wallet/serviceWorker/response.ts"
    click IndexedDB "https://github.com/arklabshq/wallet-sdk/blob/master/src/wallet/serviceWorker/db/vtxo/idb.ts"
    click ONCHAIN "https://github.com/arklabshq/wallet-sdk/blob/master/src/providers/onchain.ts"
    click ARKPROV "https://github.com/arklabshq/wallet-sdk/blob/master/src/providers/ark.ts"
    click script "https://github.com/arklabshq/wallet-sdk/blob/master/src/script/base.ts"
    click script "https://github.com/arklabshq/wallet-sdk/blob/master/src/script/address.ts"
    click script "https://github.com/arklabshq/wallet-sdk/blob/master/src/script/default.ts"
    click script "https://github.com/arklabshq/wallet-sdk/blob/master/src/script/tapscript.ts"
    click script "https://github.com/arklabshq/wallet-sdk/blob/master/src/script/vhtlc.ts"
    click tree "https://github.com/arklabshq/wallet-sdk/blob/master/src/tree/vtxoTree.ts"
    click tree "https://github.com/arklabshq/wallet-sdk/blob/master/src/tree/validation.ts"
    click tree "https://github.com/arklabshq/wallet-sdk/blob/master/src/tree/signingSession.ts"
    click musig2 "https://github.com/arklabshq/wallet-sdk/blob/master/src/musig2/index.ts"
    click musig2 "https://github.com/arklabshq/wallet-sdk/blob/master/src/musig2/keys.ts"
    click musig2 "https://github.com/arklabshq/wallet-sdk/blob/master/src/musig2/nonces.ts"
    click musig2 "https://github.com/arklabshq/wallet-sdk/blob/master/src/musig2/sign.ts"
    click utils "https://github.com/arklabshq/wallet-sdk/blob/master/src/utils/coinselect.ts"
    click utils "https://github.com/arklabshq/wallet-sdk/blob/master/src/utils/psbt.ts"
    click utils "https://github.com/arklabshq/wallet-sdk/blob/master/src/utils/txSizeEstimator.ts"
    click utils "https://github.com/arklabshq/wallet-sdk/blob/master/src/utils/transactionHistory.ts"
    click utils "https://github.com/arklabshq/wallet-sdk/blob/master/src/utils/bip21.ts"
    click arknote "https://github.com/arklabshq/wallet-sdk/blob/master/src/arknote/index.ts"
    click network "https://github.com/arklabshq/wallet-sdk/blob/master/src/networks.ts"
    click types "https://github.com/arklabshq/wallet-sdk/blob/master/src/types/bip68.d.ts"
```
