Overview
A Wallet represents a financial account where you track money. This could be:
- Cash in your pocket
- Bank checking account
- Savings account
- Credit card (with negative balance)
- Investment account
Wallet Properties
| Property | Type | Description |
|---|
id | String | Local UUID (primary key) |
serverId | String? | Server-assigned ID after sync |
name | String | Display name (e.g., “Cash”, “Chase Checking”) |
currency | String | ISO 4217 currency code (e.g., “USD”, “EUR”) |
balance | double | Current balance |
syncStatus | SyncStatus | Current sync state |
Creating a Wallet
Using the Cache Manager
final cache = CacheManager.instance;
final wallet = await cache.createWallet(
name: 'Cash',
currency: 'USD',
initialBalance: 100.0,
);
print('Created wallet: ${wallet.id}');
Direct Repository Access
final wallet = Wallet(
id: cache.generateId(),
name: 'Chase Checking',
currency: 'USD',
balance: 1500.00,
createdAt: DateTime.now(),
updatedAt: DateTime.now(),
);
await cache.wallets.save(wallet);
Querying Wallets
Get All Wallets
final wallets = await cache.wallets.findAll();
Find by ID
final wallet = await cache.wallets.findById('wallet-uuid');
if (wallet != null) {
print('Balance: ${wallet.balance}');
}
Get Pending Sync
final pending = await cache.wallets.findPendingSync();
Updating Wallets
final wallet = await cache.wallets.findById(walletId);
if (wallet != null) {
final updated = wallet.copyWith(
name: 'Updated Name',
balance: wallet.balance + 50.0,
);
await cache.wallets.save(updated);
}
When you save an existing wallet, its syncStatus automatically changes to pendingUpdate (if it was synced).
Deleting Wallets
Soft Delete (Default)
Soft delete marks the wallet as deleted but keeps it locally until sync completes:
await cache.wallets.delete(walletId);
- Be marked with
isDeleted = true
- Get
syncStatus = pendingDelete
- Not appear in
findAll() results
- Sync to server
- Be hard-deleted after successful sync
Hard Delete
Hard delete removes the wallet immediately (use with caution):
await cache.wallets.delete(walletId, hardDelete: true);
Hard-deleted wallets cannot be recovered and will not sync to the server.
Currency Support
Zeus uses ISO 4217 currency codes. Common codes:
| Code | Currency |
|---|
| USD | US Dollar |
| EUR | Euro |
| GBP | British Pound |
| JPY | Japanese Yen |
| CAD | Canadian Dollar |
Best Practices
- Use descriptive names - “Chase Checking” is better than “Bank”
- Set initial balance - Track your starting point
- One wallet per account - Don’t mix different accounts
- Regular reconciliation - Compare with bank statements
