Skip to main content

​
What is Cashu?

Cashu is an open-source ecash protocol that enables instant, private, and near-zero-fee Bitcoin transactions. Sovran implements the Cashu protocol through the coco-cashu-core library, providing a production-ready ecash wallet.

​
Ecash Fundamentals

​
Tokens & Proofs

Ecash in Sovran consists of proofs - cryptographic tokens that represent satoshis. These proofs:
  • Are bearer instruments (whoever holds them can spend them)
  • Can be combined and split freely
  • Are issued and redeemed by mints
  • Can be transferred offline via QR codes, NFC, or text
// From coco-cashu-core
interface Proof {
  amount: number;
  secret: string;
  C: string; // Blinded signature from mint
  id: string; // Keyset ID
}

​
Mints

Mints are servers that:
  1. Issue ecash - Create proofs backed by Lightning payments
  2. Redeem ecash - Convert proofs back to Lightning
  3. Swap ecash - Exchange proofs without revealing amounts
Mints have custody of your Bitcoin. Only use mints you trust, and distribute your balance across multiple mints to reduce risk.

​
Multi-Mint Architecture

Sovran supports multiple mints simultaneously, managed through coco-cashu-react: 
import { useMints, useBalanceContext } from 'coco-cashu-react';

function WalletComponent() {
  const { trustedMints } = useMints();
  const { balance } = useBalanceContext();
  
  // trustedMints: Array of Mint objects
  // balance: Record<mintUrl, amount>
}

​
Balance Distribution

Sovran includes a balance distribution system that automatically spreads incoming funds across your mints based on configurable percentages:
  • Set distribution per currency unit (SAT, USD, EUR, etc.)
  • Configure using basis points (10,000 bp = 100%)
  • Automatic rebalancing when receiving payments
See Wallet Rebalancing for details.

​
Protocol Operations

​
Mint (Lightning → Ecash)

  1. Request Lightning invoice from mint
  2. Pay invoice with external wallet
  3. Mint issues ecash proofs
  4. Proofs stored locally in SQLite

​
Melt (Ecash → Lightning)

  1. Provide Lightning invoice to pay
  2. Mint creates melt quote with fees
  3. Submit proofs to mint
  4. Mint pays Lightning invoice
  5. Spent proofs removed from local storage

​
Send/Receive

Sending:
  1. Select amount and mint
  2. Create token from available proofs
  3. Token encoded as cashuA... string
  4. Share via QR, NFC, or Nostr DM
Receiving:
  1. Scan or paste token
  2. Verify mint is trusted (or add it)
  3. Redeem proofs with mint
  4. New proofs stored locally

​
Payment Requests (NUT-18)

Sovran implements NUT-18 for requesting payments with optional constraints: 
// Payment request structure
interface PaymentRequest {
  amount?: number;           // Optional amount in base unit
  unit?: string;             // 'sat', 'usd', etc.
  mints?: string[];          // Allowed mint URLs
  description?: string;
  transport: Transport[];    // How to deliver payment
}

​
Transport Types

  • Nostr - Send ecash via Nostr DM (recommended)
  • POST - HTTP callback URL
  • WebSocket - Real-time delivery
See Payment Requests for implementation details.

​
Security Model

​
Privacy

  • Blind signatures - Mints cannot link spending to receiving
  • No on-chain footprint - Ecash transfers are off-chain
  • Nostr integration - Optional identity layer

​
Trust Assumptions

Mints have custody - A malicious mint can:
  • Refuse to redeem valid proofs
  • Create unbacked proofs (detected via auditing)
  • Disappear with funds
Mitigation strategies:
  1. Use multiple mints
  2. Check mint audits
  3. Monitor community ratings
  4. Keep small balances
  5. Use established mints with reputation

​
Storage & Recovery

​
Local Database

Proofs are stored in SQLite via coco-cashu-expo-sqlite:
  • One database per Nostr profile
  • Encrypted device storage
  • Automatic proof state management (pending, spent, reserved)

​
Backup

Sovran uses NIP-04 encrypted events to backup:
  • Mint list
  • Preferences
  • Transaction history metadata
Proofs themselves are not backed up (use recovery flow).

​
Recovery

To restore funds after device loss: 
import { useMintManagement } from '@/hooks/coco/useMintManagement';

const { restoreMint } = useMintManagement();

// Scans mint for proofs derived from your seed
await restoreMint(mintUrl);

​
Supported NUTs (Standards)

Sovran implements these Cashu protocol standards:
  • NUT-00 - Base protocol (mint, melt, swap)
  • NUT-01 - Mint information
  • NUT-02 - Keysets
  • NUT-03 - Request minting
  • NUT-04 - Minting tokens
  • NUT-05 - Melting tokens
  • NUT-06 - Splitting tokens
  • NUT-07 - Token state check
  • NUT-08 - Overpaid fees
  • NUT-09 - Restore
  • NUT-10 - Spending conditions
  • NUT-11 - Pay to Public Key (P2PK)
  • NUT-12 - DLEQ proofs
  • NUT-18 - Payment requests

​
Developer Resources

​
Key Modules

// Core manager singleton
import { CocoManager } from 'helper/coco/manager';

const manager = CocoManager.getInstance();

// React hooks
import { 
  useManager,
  useMints,
  useBalanceContext,
  useReceive,
  useSend 
} from 'coco-cashu-react';

// Mint management
import { useMintManagement } from '@/hooks/coco/useMintManagement';

// Lightning operations
import { useLightningOperations } from '@/hooks/coco/useLightningOperations';

​
Helper Functions

import {
  isValidEcashToken,
  buildReceiveHistoryEntry,
  getLightningAmount,
  isLightningInvoice
} from '@/helper/coco/utils';

​
Next Steps

Mint Management

Add, remove, and manage your mints

Know Your Mint

Audit mints and check community ratings

Mint Swapping

Move ecash between mints via Lightning

Wallet Rebalancing

Automatically distribute balance across mints

Build docs developers (and LLMs) love

Get started for freeTalk to us