Cashu Integration

Coco-Cashu Overview

Sovran uses Coco-Cashu as its core Cashu implementation. Coco is a modular, TypeScript-native library built on top of @cashu/cashu-ts.

Architecture

coco-cashu-core         # Core Cashu logic (Manager, APIs)
  ↓
coco-cashu-expo-sqlite  # SQLite repository layer for React Native
  ↓
coco-cashu-react        # React hooks (useManager, useBalance, etc.)
  ↓
Sovran app              # Composition layer (stores, custom hooks)

Never import from @cashu/cashu-ts directly. Always use coco packages. Coco wraps cashu-ts with better error handling, TypeScript types, and repository abstractions.

CocoManager Singleton

The CocoManager class is a singleton wrapper around Coco’s Manager that handles initialization, cleanup, and database management. helper/coco/manager.ts:38-749

Initialization Flow

The manager initializes in two phases: Phase 1: Blocking (happens during app startup) helper/coco/manager.ts:91-166

Open SQLite database (coco.db or coco-N.db)
Initialize repositories
Create seed getter (lazy - no crypto work yet)
Create NPC plugin (constructor only - no network)
Instantiate Manager

Phase 2: Non-blocking (happens after app is visible) helper/coco/manager.ts:173-227

Run initial NPC sync (fetch Lightning addresses from npubx.cash)
Enable mint quote watcher
Enable mint quote processor
Enable proof state watcher

This two-phase approach ensures the app becomes interactive quickly (less than 1 second) while background tasks continue.

Database Per Profile

Each profile gets its own SQLite database:

// Account 0 (backward compatible)
CocoManager.setAccountIndex(0);
await CocoManager.initialize(); // Uses 'coco.db'

// Account 1
CocoManager.setAccountIndex(1);
await CocoManager.initialize(); // Uses 'coco-1.db'

// Account N
CocoManager.setAccountIndex(N);
await CocoManager.initialize(); // Uses 'coco-N.db'

helper/coco/manager.ts:59-67 Each database contains:

Proofs table - Ecash proofs with state (ready, reserved, inflight, spent)
Mint quotes table - Lightning → Cashu mint operations
Melt quotes table - Cashu → Lightning melt operations
Keysets table - Mint public keys for each unit (sat, usd, eur, etc.)
Mint info table - Cached mint metadata

Cleanup & Profile Switching

When switching profiles, the manager must be cleaned up: helper/coco/manager.ts:250-289 This is called from the drawer layout before switching profiles: app/(drawer)/_layout.tsx:102-102

Proof Lifecycle

Proofs flow through several states:

State Definitions

State	Description	Can spend?
`ready`	Available for spending	✅
`reserved`	Reserved by an operation (send/melt)	❌
`inflight`	Submitted to mint, awaiting confirmation	❌
`spent`	Successfully spent, no longer usable	❌

Proof State Watcher

The proof state watcher monitors inflight proofs and updates their state based on mint responses:

// Automatically checks inflight proofs every 5 seconds
await manager.enableProofStateWatcher();

// When a proof is confirmed spent:
// inflight → spent

// When a proof is still unspent:
// inflight → ready (returned to spendable balance)

This prevents “stuck balance” where proofs remain inflight forever after a failed transaction.

Manual Proof Recovery

If proofs get stuck (e.g., due to a crash), users can manually free them: helper/coco/manager.ts:510-707 This is exposed in Settings → Storage → “Free Reserved Balance”.

Mint Operations

Adding a Mint

hooks/coco/useMintManagement.ts:33-51 Under the hood:

manager.mint.trustMint(url) fetches mint info
Stores keyset data in SQLite
Adds mint URL to trusted mints list
Returns mint metadata (name, icon, supported units)

Mint Info

Mint metadata is cached in SQLite:

const info = await manager.mint.getMintInfo(mintUrl);

// Returns:
interface MintInfo {
  name?: string;
  description?: string;
  icon_url?: string;
  contact?: { email?: string; nostr?: string };
  nuts: number[]; // Supported NUTs
}

Keyset Management

Keysets define the denominations and units a mint supports:

const keysets = await manager.mint.getKeysets(mintUrl);

// Returns array of keysets:
interface Keyset {
  id: string;        // Keyset ID (hash of keys)
  unit: string;      // 'sat', 'usd', 'eur', etc.
  active: boolean;   // Whether mint still issues this keyset
  keys: {
    [amount: string]: string; // amount → pubkey mapping
  };
}

Keysets are automatically refreshed on mint operations.

Receiving Ecash

Token Parsing

import { buildReceiveHistoryEntry } from '@/helper/coco/utils';

const token = 'cashuAeyJ0b2tlbiI6...';
const historyEntry = buildReceiveHistoryEntry(token);

// historyEntry contains:
// - token: original token string
// - amount: total value in smallest unit
// - unit: 'sat', 'usd', etc.
// - mint: mint URL
// - memo: optional memo from sender

Receiving Flow

// 1. User scans/pastes token
const token = 'cashuAeyJ0b2tlbiI6...';

// 2. Navigate to receive screen
router.navigate({
  pathname: '/(receive-flow)/receiveToken',
  params: { 
    receiveHistoryEntry: JSON.stringify(buildReceiveHistoryEntry(token)) 
  }
});

// 3. Receive screen calls Coco to redeem
const result = await manager.wallet.receive({
  token,
  preferences: {
    // Optional: specify which proofs to keep
    counter: 0
  }
});

// 4. Proofs are now in 'ready' state, added to balance

P2PK (Pay-to-Public-Key)

Sovran supports P2PK tokens that require a private key to unlock:

// Generate P2PK receiving key
const { privateKey, publicKey } = await manager.wallet.generateP2PKKey();

// Create locked token request
const quote = await manager.quotes.createMintQuote({
  mintUrl,
  amount,
  unit: 'sat',
  pubkey: publicKey // Lock to this pubkey
});

// Receiver needs the private key to unlock:
const result = await manager.wallet.receive({
  token,
  privkey: privateKey // Unlocks P2PK proofs
});

P2PK keys are managed in Settings → Keyring.

Sending Ecash

Send Operation

hooks/coco/useSendWithHistory.ts creates a send operation:

import { useSendWithHistory } from '@/hooks/coco/useSendWithHistory';

const { createOperation, finalize, rollback } = useSendWithHistory();

// 1. Create operation (reserves proofs)
const operation = await createOperation({
  mintUrl: 'https://mint.example.com',
  amount: 1000,
  unit: 'sat',
  memo: 'Coffee payment'
});

// 2. Finalize operation (creates token)
const token = await finalize(operation.id);

// 3. Share token with recipient
await Share.share({ message: token });

// If user cancels, rollback:
await rollback(operation.id); // Unreserves proofs

Send States

Pending Ecash Sweeper

Unredeemed sent tokens can be reclaimed:

// Get all pending sends
const pending = await manager.send.getPendingOperations();

// Rollback each one
for (const op of pending) {
  await manager.send.rollback(op.id);
  // Proofs: reserved → ready (returned to spendable balance)
}

This is used in app/pendingEcash.tsx to sweep unclaimed sent tokens.

Lightning Operations

Minting (Lightning → Cashu)

// 1. Create mint quote
const quote = await manager.quotes.createMintQuote({
  mintUrl: 'https://mint.example.com',
  amount: 10000, // sats
  unit: 'sat'
});

// quote contains:
// - quote: unique quote ID
// - request: Lightning invoice (BOLT11)
// - state: 'pending' | 'paid' | 'issued'
// - expiry: timestamp when quote expires

// 2. User pays invoice externally
await payLightningInvoice(quote.request);

// 3. Quote watcher detects payment, auto-mints proofs
// (or manually check and mint):
const proofs = await manager.quotes.mintTokens({
  mintUrl,
  quoteId: quote.quote
});

The mint quote watcher automatically checks pending quotes every 5 seconds and mints proofs when paid.

Melting (Cashu → Lightning)

hooks/coco/useMeltWithHistory.ts handles melt operations:

import { useMeltWithHistory } from '@/hooks/coco/useMeltWithHistory';

const { createOperation, finalize, rollback } = useMeltWithHistory();

// 1. Create melt quote
const quote = await manager.quotes.createMeltQuote({
  mintUrl: 'https://mint.example.com',
  request: 'lnbc10u1...', // BOLT11 invoice
  unit: 'sat'
});

// quote.amount is total cost (invoice amount + fee)

// 2. Create melt operation (reserves proofs)
const operation = await createOperation({
  mintUrl,
  quoteId: quote.quote,
  amount: quote.amount,
  unit: 'sat'
});

// 3. Finalize operation (pays invoice)
const result = await finalize(operation.id);

// result contains:
// - preimage: Lightning payment preimage (proof of payment)
// - state: 'paid' | 'failed'

// If failed, rollback:
await rollback(operation.id); // Unreserves proofs

Lightning Addresses

Lightning addresses (user@domain.com) are resolved via LNURL-pay:

import { isLightningAddress } from '@/helper/coco/utils';

if (isLightningAddress('user@domain.com')) {
  // 1. Fetch LNURL metadata
  const lnurl = await resolveLightningAddress('user@domain.com');
  
  // 2. Request invoice for amount
  const invoice = await lnurl.requestInvoice({ amount: 1000 });
  
  // 3. Create melt quote with invoice
  const quote = await manager.quotes.createMeltQuote({
    mintUrl,
    request: invoice,
    unit: 'sat'
  });
}

Payment Requests (NUT-18)

hooks/coco/useProcessPaymentString.ts:216-331 Payment requests allow requesting ecash over Nostr without Lightning:

import { decodePaymentRequest } from '@cashu/cashu-ts';

// creqA1234... format
const decoded = decodePaymentRequest('creqA1234...');

// decoded contains:
interface PaymentRequest {
  amount?: number;        // Requested amount
  unit?: string;          // 'sat', 'usd', etc.
  mints?: string[];       // Allowed mint URLs
  transport: {
    type: 'nostr';        // NUT-18 uses Nostr
    target: string;       // Nostr pubkey to send to
    tags?: string[][];    // Additional metadata
  }[];
}

// Sovran handles all routing automatically based on available data

Mint Swapping & Rebalancing

Swap Operation

// Swap ecash from one mint to another
const result = await manager.wallet.swap({
  fromMintUrl: 'https://mint1.example.com',
  toMintUrl: 'https://mint2.example.com',
  amount: 5000,
  unit: 'sat'
});

// Under the hood:
// 1. Reserve proofs from mint1 (send operation)
// 2. Melt to Lightning invoice from mint2
// 3. Pay invoice, mint new proofs at mint2
// 4. Return new proofs

Rebalance Planning

components/blocks/rebalance/rebalancePlanner.ts calculates optimal rebalance steps:

interface RebalanceStep {
  from: string;      // Source mint URL
  to: string;        // Destination mint URL
  via?: string[];    // Middleman mints (if direct swap unavailable)
  amount: number;    // Amount to transfer
  unit: string;
}

const plan = calculateRebalancePlan({
  currentDistribution: { 'mint1': 8000, 'mint2': 2000 },
  targetDistribution: { 'mint1': 5000, 'mint2': 5000 },
  swapEdges: [...],  // Available swap pairs from auditor
  minTransfer: 100   // Minimum transfer amount
});

// Returns array of steps to execute

Middleman Routing

If two mints don’t support direct swaps, Sovran can route through intermediary mints:

// Settings → Routing
const routingSettings = useSettingsStore(s => s.middlemanRouting);

interface MiddlemanRoutingSettings {
  maxHops: number;           // Max intermediaries (1 = A→via→B)
  maxFee: number;            // Max total fee in sats
  minSuccessRate: number;    // Min success rate (0-1)
  requireLastOk: boolean;    // Most recent swap must be OK
  trustMode: 'trusted_only' | 'allow_untrusted';
}

// Example: A → B (no direct swap)
// Route: A → via1 → B (1 hop)
// Route: A → via1 → via2 → B (2 hops)

components/blocks/rebalance/routing.ts implements the routing algorithm.

NPC Plugin (npubx.cash)

The NPC plugin integrates with npubx.cash for Lightning addresses:

// Configured in CocoManager initialization
const npcPlugin = new NPCPlugin(
  'https://npubx.cash',
  signerFunction,
  {
    syncIntervalMs: 30000,  // Sync every 30s
    useWebsocket: true      // Real-time updates
  }
);

// Plugin handles:
// 1. Claiming Lightning addresses (you@npubx.cash)
// 2. Receiving payments to your address
// 3. Auto-minting received payments

NPC sync runs in the non-blocking initialization phase.

React Hooks

coco-cashu-react provides hooks for common operations:

import { 
  useManager,         // Access Manager instance
  useBalance,         // Get balance per mint/unit
  useBalanceContext,  // Subscribe to balance changes
  useMints,           // Get trusted mints list
  useHistory          // Get transaction history
} from 'coco-cashu-react';

// Usage
const manager = useManager();
const { balance } = useBalanceContext();
const { trustedMints } = useMints();

Sovran wraps these in custom hooks in hooks/coco/:

Hook	Purpose
`useMintManagement`	Add/remove mints, get mint info
`useSendWithHistory`	Send operations with history tracking
`useMeltWithHistory`	Melt operations with history tracking
`useLightningOperations`	Lightning invoice operations
`useProcessPaymentString`	Parse and route payment strings (QR/NFC/paste)
`useHistoryWithMelts`	Combined history (sends + melts)
`useAuditedMint`	Fetch audit data for a mint
`useKYMMint`	Fetch KYM ratings for a mint

Best Practices

Always use Coco hooks in components

Never call Manager methods directly in components - use hooks:

// Good ✅
const { addMint, isLoading } = useMintManagement();
await addMint('https://mint.example.com');

// Bad ❌
const manager = useManager();
await manager.mint.trustMint('https://mint.example.com');

Handle proof state transitions

Always handle rollback when operations fail:

const { createOperation, finalize, rollback } = useSendWithHistory();

try {
  const op = await createOperation({ ... });
  const token = await finalize(op.id);
  // Success - proofs are spent
} catch (error) {
  await rollback(op.id); // Return proofs to spendable balance
}

Check keyset support before operations

Ensure the mint supports the unit you want to use:

const keysets = await manager.mint.getKeysets(mintUrl);
const supportsUnit = keysets.some(k => k.unit === 'usd' && k.active);

if (!supportsUnit) {
  throw new Error('Mint does not support USD');
}

Monitor quote states

Don’t assume quotes succeed immediately:

const quote = await manager.quotes.createMintQuote({ ... });

// Wait for payment
const checkQuote = async () => {
  const updated = await manager.quotes.checkMintQuote(quote.quote);
  if (updated.state === 'paid') {
    // Mint tokens
    await manager.quotes.mintTokens({ ... });
  }
};

// Or let the quote watcher handle it automatically

State Management

Learn about stores that complement Coco’s SQLite storage

Nostr Integration

See how Nostr payment requests integrate with Cashu

​Coco-Cashu Overview

​Architecture

​CocoManager Singleton

​Initialization Flow

​Database Per Profile

​Cleanup & Profile Switching

​Proof Lifecycle

​State Definitions

​Proof State Watcher

​Manual Proof Recovery

​Mint Operations

​Adding a Mint

​Mint Info

​Keyset Management

​Receiving Ecash

​Token Parsing

​Receiving Flow

​P2PK (Pay-to-Public-Key)

​Sending Ecash

​Send Operation

​Send States

​Pending Ecash Sweeper

​Lightning Operations

​Minting (Lightning → Cashu)

​Melting (Cashu → Lightning)

​Lightning Addresses

​Payment Requests (NUT-18)

​Mint Swapping & Rebalancing

​Swap Operation

​Rebalance Planning

​Middleman Routing

​NPC Plugin (npubx.cash)

​React Hooks

​Best Practices

​Related Documentation

State Management

Nostr Integration

Coco-Cashu Overview

Architecture

CocoManager Singleton

Initialization Flow

Database Per Profile

Cleanup & Profile Switching

Proof Lifecycle

State Definitions

Proof State Watcher

Manual Proof Recovery

Mint Operations

Adding a Mint

Mint Info

Keyset Management

Receiving Ecash

Token Parsing

Receiving Flow

P2PK (Pay-to-Public-Key)

Sending Ecash

Send Operation

Send States

Pending Ecash Sweeper

Lightning Operations

Minting (Lightning → Cashu)

Melting (Cashu → Lightning)

Lightning Addresses

Payment Requests (NUT-18)

Mint Swapping & Rebalancing

Swap Operation

Rebalance Planning

Middleman Routing

NPC Plugin (npubx.cash)

React Hooks

Best Practices

Related Documentation