# cashubtc/cashu-ts architecture

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

- Interactive diagram: https://gitdiagram.com/cashubtc/cashu-ts
- Repository: https://github.com/cashubtc/cashu-ts

## Overview

##### Project Type and Purpose
- Cashu TS is a TypeScript library (SDK) for interacting with Cashu mints and building wallet functionality.
- It provides wallet operations (mint, melt, send, receive), implements Cashu NUT protocols (NUT-00…NUT-25), supports BOLT11/BOLT12 invoices, and offers a fluent builder API for transaction composition.

##### File Structure Analysis
- Top-level directories:
- src/ – primary TypeScript source code, organized into sub-modules: auth, crypto, mint, model, transport, wallet, logger, utils, legacy.
- examples/ – usage examples and Docker comps.
- test/ – unit and integration tests.
- Key config: tsconfig.json, vite.config.ts, api-extractor.json.
- CI workflows live under .github/workflows.
- README.md details usage, features, and architecture notes.

##### Main Components
a. Public API Layer
- index.ts – exports Wallet, Mint, P2PKBuilder, utility functions (getEncodedTokenV4, getDecodedToken).
b. Wallet Module (src/wallet)
- Wallet.ts – orchestrates all operations: loadMint, send, receive, mint, melt.
- WalletOps.ts – fluent builder for send/receive/mint/melt.
- CounterSource and WalletEvents – manage deterministic counters and subscriptions.
c. Mint Module (src/mint)
- Mint.ts – handles mint-specific calls (createQuote, checkQuote, mintProofs, meltProofs).
d. Transport Layer (src/transport)
- HTTP requests (fetch RPC) and WSConnection – handles REST and WebSocket.
e. Crypto Layer (src/crypto)
- Implements NUT protocols (NUT01..NUT25) and core cryptographic operations.
f. Model Layer (src/model)
g. Authentication (src/auth)
- OIDCAuth, AuthManager – optional for mints requiring OAuth2/OIDC.
h. Utilities (src/utils) and Logger (src/logger)
- Helpers for base64, CBOR, bytes, CLI logging interfaces.
i. External Dependencies
- Mint server (HTTP/WS)
- Lightning network (for BOLT11/BOLT12 invoices)

##### Relationships and Data Flow
- Wallet → Transport → Mint Server (HTTP endpoints for quotes, proof swaps)
- WalletOps uses Crypto to build and split proofs, Model to structure payloads.
- Transport WSConnection subscribes to real-time quote/melt updates → WalletEvents emits updates to client.
- WalletOps builder hooks (onCountersReserved, onChangeOutputsCreated) tie into CounterSource and WalletEvents.
- For melt/send, Wallet uses external Lightning node by paying invoices (outside library scope).

##### Architectural Patterns
- Layered architecture: Public API → Wallet/Mint modules → Transport → External services
- Fluent Builder Pattern (WalletOps) for composable transactions
- Event-driven subscriptions via Observable/Async Iterators (WalletEvents)
- Modular NUT implementations in crypto layer for protocol extensibility

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Cashu-TS Library"
    A1["Public API\n(index.ts)"]:::internal
    subgraph "Wallet Module"
      W1["Wallet"]:::internal
      W2["WalletOps"]:::internal
      W3["CounterSource"]:::internal
      W4["WalletEvents"]:::internal
      W5["P2PKBuilder"]:::internal
      W6["SelectProofs"]:::internal
      W7["KeyChain"]:::internal
      W8["Keyset"]:::internal
      W9["WalletCounters"]:::internal
    end
    subgraph "Mint Module"
      M1["Mint"]:::internal
      M2["types/index.ts"]:::internal
      M3["types/payloads.ts"]:::internal
      M4["types/responses.ts"]:::internal
    end
    subgraph "Transport Layer"
      T1["request.ts"]:::transport
      T2["index.ts"]:::transport
      T3["WSConnection"]:::transport
      T4["ws.ts"]:::transport
    end
    subgraph "Crypto Layer"
      C0["index.ts"]:::crypto
      C1["NUT01"]:::crypto
      C2["NUT11"]:::crypto
      C3["NUT12"]:::crypto
      C4["NUT13"]:::crypto
      C5["NUT20"]:::crypto
      C6["core"]:::crypto
    end
    subgraph "Model Layer"
      D1["BlindedMessage"]:::model
      D2["BlindedSignature"]:::model
      D3["MintInfo"]:::model
      D4["OutputData"]:::model
      D5["PaymentRequest"]:::model
      D6["Split"]:::model
      D7["Errors"]:::model
      D8["types/index.ts"]:::model
      D9["types/blinded.ts"]:::model
      D10["types/jsonrpc.ts"]:::model
      D11["types/keyset.ts"]:::model
      D12["types/proof.ts"]:::model
      D13["types/proof-state.ts"]:::model
      D14["types/token.ts"]:::model
      D15["types/token.v4.ts"]:::model
    end
    subgraph "Auth Module"
      AU1["AuthManager"]:::internal
      AU2["AuthProvider"]:::internal
      AU3["OIDCAuth"]:::internal
      AU4["createAuthWallet"]:::internal
      AU5["index.ts"]:::internal
    end
    subgraph "Utils & Logger"
      U1["Bytes"]:::util
      U2["base64"]:::util
      U3["cbor"]:::util
      U4["core"]:::util
      U5["index.ts"]:::util
      L1["Logger"]:::logger
      L2["ConsoleLogger"]:::logger
      L3["NullLogger"]:::logger
      L4["helpers"]:::logger
      L5["index.ts"]:::logger
    end
  end

  E1["Cashu Mint Server\n(HTTP REST, WebSocket)"]:::external
  E2["Lightning Network"]:::external
  E3["Client App / DB"]:::datastore

  A1 --> W1
  W1 --> T2
  T2 -->|"HTTP calls"| E1
  W1 --> T3
  T3 -->|"WS subscriptions"| E1
  W2 --> C0
  W2 --> D8
  W1 --> U1
  W1 --> L1
  W4 -->|"events"| E3
  W3 --> W4
  W1 --> AU1
  AU4 --> W1
  W1 -->|"invoice settlement"| E2

  click A1 "https://github.com/cashubtc/cashu-ts/blob/main/src/index.ts"
  click W1 "https://github.com/cashubtc/cashu-ts/blob/main/src/wallet/Wallet.ts"
  click W2 "https://github.com/cashubtc/cashu-ts/blob/main/src/wallet/WalletOps.ts"
  click W3 "https://github.com/cashubtc/cashu-ts/blob/main/src/wallet/CounterSource.ts"
  click W4 "https://github.com/cashubtc/cashu-ts/blob/main/src/wallet/WalletEvents.ts"
  click W5 "https://github.com/cashubtc/cashu-ts/blob/main/src/wallet/P2PKBuilder.ts"
  click W6 "https://github.com/cashubtc/cashu-ts/blob/main/src/wallet/SelectProofs.ts"
  click W7 "https://github.com/cashubtc/cashu-ts/blob/main/src/wallet/KeyChain.ts"
  click W8 "https://github.com/cashubtc/cashu-ts/blob/main/src/wallet/Keyset.ts"
  click W9 "https://github.com/cashubtc/cashu-ts/blob/main/src/wallet/WalletCounters.ts"
  click M1 "https://github.com/cashubtc/cashu-ts/blob/main/src/mint/Mint.ts"
  click M2 "https://github.com/cashubtc/cashu-ts/blob/main/src/mint/types/index.ts"
  click M3 "https://github.com/cashubtc/cashu-ts/blob/main/src/mint/types/payloads.ts"
  click M4 "https://github.com/cashubtc/cashu-ts/blob/main/src/mint/types/responses.ts"
  click T1 "https://github.com/cashubtc/cashu-ts/blob/main/src/transport/request.ts"
  click T2 "https://github.com/cashubtc/cashu-ts/blob/main/src/transport/index.ts"
  click T3 "https://github.com/cashubtc/cashu-ts/blob/main/src/transport/WSConnection.ts"
  click T4 "https://github.com/cashubtc/cashu-ts/blob/main/src/transport/ws.ts"
  click C0 "https://github.com/cashubtc/cashu-ts/blob/main/src/crypto/index.ts"
  click C1 "https://github.com/cashubtc/cashu-ts/blob/main/src/crypto/NUT01.ts"
  click C2 "https://github.com/cashubtc/cashu-ts/blob/main/src/crypto/NUT11.ts"
  click C3 "https://github.com/cashubtc/cashu-ts/blob/main/src/crypto/NUT12.ts"
  click C4 "https://github.com/cashubtc/cashu-ts/blob/main/src/crypto/NUT13.ts"
  click C5 "https://github.com/cashubtc/cashu-ts/blob/main/src/crypto/NUT20.ts"
  click C6 "https://github.com/cashubtc/cashu-ts/blob/main/src/crypto/core.ts"
  click D1 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/BlindedMessage.ts"
  click D2 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/BlindedSignature.ts"
  click D3 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/MintInfo.ts"
  click D4 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/OutputData.ts"
  click D5 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/PaymentRequest.ts"
  click D6 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/Split.ts"
  click D7 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/Errors.ts"
  click D8 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/types/index.ts"
  click D9 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/types/blinded.ts"
  click D10 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/types/jsonrpc.ts"
  click D11 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/types/keyset.ts"
  click D12 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/types/proof.ts"
  click D13 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/types/proof-state.ts"
  click D14 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/types/token.ts"
  click D15 "https://github.com/cashubtc/cashu-ts/blob/main/src/model/types/token.v4.ts"
  click AU1 "https://github.com/cashubtc/cashu-ts/blob/main/src/auth/AuthManager.ts"
  click AU2 "https://github.com/cashubtc/cashu-ts/blob/main/src/auth/AuthProvider.ts"
  click AU3 "https://github.com/cashubtc/cashu-ts/blob/main/src/auth/OIDCAuth.ts"
  click AU4 "https://github.com/cashubtc/cashu-ts/blob/main/src/auth/createAuthWallet.ts"
  click AU5 "https://github.com/cashubtc/cashu-ts/blob/main/src/auth/index.ts"
  click U1 "https://github.com/cashubtc/cashu-ts/blob/main/src/utils/Bytes.ts"
  click U2 "https://github.com/cashubtc/cashu-ts/blob/main/src/utils/base64.ts"
  click U3 "https://github.com/cashubtc/cashu-ts/blob/main/src/utils/cbor.ts"
  click U4 "https://github.com/cashubtc/cashu-ts/blob/main/src/utils/core.ts"
  click U5 "https://github.com/cashubtc/cashu-ts/blob/main/src/utils/index.ts"
  click L1 "https://github.com/cashubtc/cashu-ts/blob/main/src/logger/Logger.ts"
  click L2 "https://github.com/cashubtc/cashu-ts/blob/main/src/logger/ConsoleLogger.ts"
  click L3 "https://github.com/cashubtc/cashu-ts/blob/main/src/logger/NullLogger.ts"
  click L4 "https://github.com/cashubtc/cashu-ts/blob/main/src/logger/helpers.ts"
  click L5 "https://github.com/cashubtc/cashu-ts/blob/main/src/logger/index.ts"

  classDef internal fill:#AED6F1,stroke:#1F618D,color:#0B2161
  classDef transport fill:#F9E79F,stroke:#B7950B
  classDef crypto fill:#F5B7B1,stroke:#943126
  classDef model fill:#D2B4DE,stroke:#6C3483
  classDef util fill:#ABEBC6,stroke:#1D8348
  classDef logger fill:#D5DBDB,stroke:#566573
  classDef external fill:#A9DFBF,stroke:#196F3D
  classDef datastore fill:#FADBD8,stroke:#78281F
```
