Agicash Wallet Documentation
Transaction Types
| Type | Direction | Entity | Flow |
|---|---|---|---|
| Cashu Lightning | Send | CashuSendQuote | Melt proofs → pay Lightning invoice |
| Cashu Lightning | Receive | CashuReceiveQuote | Pay Lightning invoice → mint proofs |
| Cashu Token | Send | CashuSendSwap | Swap proofs → encode token → share |
| Cashu Token | Receive | CashuReceiveSwap | Parse token → swap proofs into account |
| Cashu Token | Receive (cross-account) | CashuReceiveQuote or SparkReceiveQuote | Melt from source → Lightning → mint/receive on LN payment completed |
| Spark Lightning | Send | SparkSendQuote | Pay Lightning invoice directly |
| Spark Lightning | Receive | SparkReceiveQuote | Generate invoice → receive payment |
| Lightning Address | Receive | CashuReceiveQuote or SparkReceiveQuote | Server-side: LNURL discovery → invoice → payment |
All operations create a corresponding Transaction entity for UI display.
Core Concepts
Entities
- •Quote = Payment request lifecycle (Lightning operations with Cashu mints or Spark)
- •Swap = Peer-to-peer proof exchange (Cashu tokens)
- •Transaction = User-facing record (1:1 with Quote or Swap via
transactionId) - •Proof = Cryptographic ecash token with
amount,id,secret,C
Cashu Protocol Terms
- •Proof/Input = Ecash token sent to mint for swap/melt
- •BlindedMessage/Output = Blinded secret sent to mint for signing
- •BlindSignature/Promise = Mint's signature, unblinded to get Proof
- •Mint = Create proofs by paying Lightning
- •Melt = Spend proofs to pay Lightning
- •Swap = Exchange proofs for new proofs
Reference Files
| Flow | Reference |
|---|---|
| Entity relationships & cross-cutting patterns | references/entities.md |
| Cashu Lightning Send (melt) | references/cashu-lightning-send.md |
| Cashu Lightning Receive (mint) | references/cashu-lightning-receive.md |
| Cashu Token Send | references/cashu-send-swap.md |
| Cashu Token Receive | references/cashu-receive-swap.md |
| Spark Lightning (send/receive) | references/spark-operations.md |
| Cross-account token claim | references/cross-account-claim.md |
| Public token receive (unauthenticated) | references/public-token-receive.md |
| Lightning Address (LNURL-pay) | references/lightning-address.md |
| Background task processing | references/task-processing.md |
File Structure
code
app/features/{send|receive}/
├── {entity}.ts # Type definitions (discriminated unions)
├── {entity}-service.ts # Business logic, state transitions
├── {entity}-repository.ts # Database access, encryption
└── {entity}-hooks.ts # TanStack Query hooks
Import hierarchy (never reverse): lib/components → features → routes
Key Invariants
- •All state transitions are idempotent - safe to retry
- •All Quote/Swap entities have
version- check before updates (optimistic locking). Transaction does not have a version field. - •All sensitive data encrypted - handled transparently by repository
- •Proofs are RESERVED when quote/swap created - released on failure/expiry
- •Only one client runs background tasks - leader election via
take_leadRPC