Wallet-Core Overview
Wallet-Core is the authoritative financial engine for OLIVE, managing accounts, executing payments and transfers, enforcing compliance, logging audits, and integrating with external processors.Purpose
Ledger
Atomic transaction processing with database transactions and audit logs
Accounts
Multi-currency account management with balance tracking
Compliance
Transaction monitoring, alerts, and compliance rules
Reconciliation
External processor reconciliation with VULT
Who Uses It
| Client | Protocol | Use Case |
|---|---|---|
| Gateway | gRPC | All API operations |
| Background Jobs | Direct | Reconciliation, cleanup |
| Admin Tools | gRPC | Reporting, maintenance |
Key Features
Atomic Transactions
All financial operations are atomic with database transactions:Idempotency
All payments support idempotency viarequest_id:
request_id is received, the existing transaction is returned.
Account Model
Accounts are stored per user and currency:gRPC Services
Wallet-Core exposes multiple gRPC services:| Service | Purpose |
|---|---|
WalletService | Core: payments, balances, transactions |
SubscriberService | User registration and management |
CardService | NFC card operations |
AgentService | Agent/merchant operations |
ComplianceService | Monitoring and alerts |
POSService | POS terminal operations |
AuditService | Audit log operations |
APIKeyService | API key management |
ProcessorService | External processor integration |
PEPAccessService | Privileged access flows |
Quick Start
With Docker Compose
Build and Run Locally
Test gRPC Connectivity
Architecture
Project Structure
Data Model
Core Tables
| Table | Purpose | Key Fields |
|---|---|---|
subscribers | User profiles | phone, kyc_level |
accounts | Balance by currency | user_id, currency, balance |
transactions | Transaction ledger | request_id, amount, status |
nfc_cards | Card mappings | serial, subscriber_id |
agents | Agent accounts | float_balance |
audit_log | Event audit trail | event_type, timestamp |
Transaction Statuses
| Status | Description |
|---|---|
PENDING | Transaction initiated |
COMPLETED | Successfully processed |
FAILED | Processing failed |
REVERSED | Transaction reversed |
Security
- gRPC TLS: Enable for production environments
- mTLS: Mutual TLS between Gateway and Wallet-Core
- Audit Logging: All operations logged
- Access Control: Service-level authentication