Concepts Overview
Quick overview of Phoenix Wallet core concepts
Before diving into the API, understand these key concepts:
Wallet
A wallet is a container that holds balances for a specific owner (user, player, customer). Each wallet can hold multiple assets and tracks both available and reserved balances.
Asset
An asset represents a type of value (currency, points, tokens). Each asset has a code (e.g., USD, POINTS) and a decimal scale for precision.
Lot
A lot is a tranche of balance with specific attributes. When you credit a wallet, you create or add to a lot. Lots can have:
- Expiry dates - Automatic expiration of unused balance
- Policy rules - Restrictions on how the balance can be used
- Attributes - Custom metadata for tracking
Policy
A policy defines rules for operations on lots. Policies control:
- Which operations are allowed (transfer, consume, etc.)
- What intents are valid for the operation
- Validation rules for attributes and context
Reservation
A reservation is a hold on funds. Use reservations for authorization patterns where you need to:
- Reserve (hold) funds
- Later commit (capture) or release (cancel) the reservation
Ledger
The ledger is an immutable, append-only record of all value movements. Every operation creates ledger entries using double-entry accounting principles.
For detailed explanations, see Core Concepts.