Core Concepts
Understand the fundamental building blocks of Phoenix Wallet
Phoenix Wallet is built on proven financial system principles. Understanding these concepts will help you design effective integrations.
Overview
Wallets
Containers for user balances
Assets
Types of value (currencies, points)
Lots
Balance tranches with policies
Policies
Rules controlling operations
Reservations
Holds and authorizations
Ledger
Immutable transaction record
Multi-Tenancy
Data isolation architecture
How They Work Together
The following diagram shows how Phoenix Wallet concepts relate to each other:
┌─────────────────────────────────────────────────────────────────┐
│ TENANT │
│ (Isolated environment for your application) │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ WALLET │ │
│ │ (Container for a user's balances) │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ LOT #1 │ │ LOT #2 │ │ LOT #3 │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Amount: 100 │ │ Amount: 50 │ │ Amount: 25 │ │ │
│ │ │ Asset: USD │ │ Asset: USD │ │ Asset: PTS │ │ │
│ │ │ Policy: P1 │ │ Policy: P2 │ │ Policy: P1 │ │ │
│ │ │ Expires: -- │ │ Expires: 7d │ │ Expires: 30d│ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ Total USD: 150 (available) + reservations │ │
│ │ Total PTS: 25 (available) + reservations │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ LEDGER │ │
│ │ (Immutable record of all transactions) │ │
│ │ │ │
│ │ Entry #1: Credit LOT#1 +100 USD (deposit) │ │
│ │ Entry #2: Credit LOT#2 +50 USD (bonus) │ │
│ │ Entry #3: Credit LOT#3 +25 PTS (reward) │ │
│ │ Entry #4: Reserve LOT#1 -20 USD (auth hold) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘Data Flow
When a transaction occurs, Phoenix Wallet follows this flow:
- Request received - API call specifies wallet, amount, asset, and intent
- Policy evaluation - System finds matching lots and validates against policies
- Reservation (optional) - For two-phase operations, funds are held first
- Ledger entry - Double-entry accounting records the transaction
- Balance update - Wallet balances are recalculated
- Event emission - Webhooks notify your systems of the change
Next Steps
Start with Wallets to understand the primary container for user funds, then explore the other concepts as needed for your integration.