How arklabshq/wallet-sdk works
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