How cashubtc/cashu-ts works
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