Skip to main content

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

ClientProtocolUse Case
GatewaygRPCAll API operations
Background JobsDirectReconciliation, cleanup
Admin ToolsgRPCReporting, maintenance

Key Features

Atomic Transactions

All financial operations are atomic with database transactions:
// Simplified transaction flow
tx, _ := db.Begin()

// Debit sender
tx.Exec("UPDATE accounts SET balance = balance - $1 WHERE user_id = $2", amount, senderID)

// Credit recipient  
tx.Exec("UPDATE accounts SET balance = balance + $1 WHERE user_id = $2", amount, recipientID)

// Insert transaction record
tx.Exec("INSERT INTO transactions (...) VALUES (...)")

// Insert audit log
tx.Exec("INSERT INTO audit_log (...) VALUES (...)")

tx.Commit()

Idempotency

All payments support idempotency via request_id:
message PaymentRequest {
  string request_id = 1;  // Client-provided unique ID
  string user_id = 2;
  string recipient_id = 3;
  int64 amount = 4;
  string currency = 5;
}
If a duplicate request_id is received, the existing transaction is returned.

Account Model

Accounts are stored per user and currency:
CREATE TABLE accounts (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  currency TEXT NOT NULL,
  balance BIGINT NOT NULL DEFAULT 0,
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  UNIQUE(user_id, currency)
);

gRPC Services

Wallet-Core exposes multiple gRPC services:
ServicePurpose
WalletServiceCore: payments, balances, transactions
SubscriberServiceUser registration and management
CardServiceNFC card operations
AgentServiceAgent/merchant operations
ComplianceServiceMonitoring and alerts
POSServicePOS terminal operations
AuditServiceAudit log operations
APIKeyServiceAPI key management
ProcessorServiceExternal processor integration
PEPAccessServicePrivileged access flows

Quick Start

With Docker Compose

docker compose up -d --build wallet-core

Build and Run Locally

cd wallet-core
go build -o wallet-core ./cmd/server
./wallet-core -config config.yaml

Test gRPC Connectivity

grpcurl -plaintext localhost:50051 wallet.WalletService/HealthCheck

Architecture

Project Structure

wallet-core/
├── cmd/
│   ├── server/
│   │   └── main.go       # Entry point
│   └── tools/            # CLI utilities
├── internal/
│   ├── config/           # Configuration loading
│   ├── database/         # DB connection & migrations
│   ├── ledger/           # Core transaction engine
│   ├── models/           # Domain models
│   ├── repository/       # Data access layer
│   ├── server/           # gRPC server adapters
│   └── services/         # Business logic (16 services)
├── pkg/                  # Shared packages
├── config.yaml           # Default configuration
└── Dockerfile

Data Model

Core Tables

TablePurposeKey Fields
subscribersUser profilesphone, kyc_level
accountsBalance by currencyuser_id, currency, balance
transactionsTransaction ledgerrequest_id, amount, status
nfc_cardsCard mappingsserial, subscriber_id
agentsAgent accountsfloat_balance
audit_logEvent audit trailevent_type, timestamp

Transaction Statuses

StatusDescription
PENDINGTransaction initiated
COMPLETEDSuccessfully processed
FAILEDProcessing failed
REVERSEDTransaction 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

Next Steps