> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sovranBitcoin/sovran/llms.txt
> Use this file to discover all available pages before exploring further.

# Cashu Protocol & Ecash

> Understanding ecash and the Cashu protocol in Sovran

## 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

```typescript theme={null}
// 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

<Warning>
  Mints have custody of your Bitcoin. Only use mints you trust, and distribute your balance across multiple mints to reduce risk.
</Warning>

## Multi-Mint Architecture

Sovran supports multiple mints simultaneously, managed through `coco-cashu-react`:

```typescript theme={null}
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](/cashu/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](https://github.com/cashubtc/nuts/blob/main/18.md) for requesting payments with optional constraints:

```typescript theme={null}
// 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](/cashu/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

<Warning>
  **Mints have custody** - A malicious mint can:

  * Refuse to redeem valid proofs
  * Create unbacked proofs (detected via auditing)
  * Disappear with funds
</Warning>

**Mitigation strategies:**

1. Use multiple mints
2. Check [mint audits](/cashu/know-your-mint)
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:

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
import {
  isValidEcashToken,
  buildReceiveHistoryEntry,
  getLightningAmount,
  isLightningInvoice
} from '@/helper/coco/utils';
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Mint Management" icon="building-columns" href="/cashu/mint-management">
    Add, remove, and manage your mints
  </Card>

  <Card title="Know Your Mint" icon="shield-check" href="/cashu/know-your-mint">
    Audit mints and check community ratings
  </Card>

  <Card title="Mint Swapping" icon="arrow-right-arrow-left" href="/cashu/mint-swapping">
    Move ecash between mints via Lightning
  </Card>

  <Card title="Wallet Rebalancing" icon="scale-balanced" href="/cashu/wallet-rebalancing">
    Automatically distribute balance across mints
  </Card>
</CardGroup>