Overview

Wallet-Core is the authoritative financial engine for SmartPay, 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:

// 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:

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

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

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

Next Steps

Ledger

Transaction processing details

Architecture

Internal architecture

Configuration

config.yaml reference

API Reference

Complete endpoint docs