Configuration

Wallet-Core is configured via YAML files with environment variable expansion.

Configuration Files

File	Purpose
config.yaml	Default development configuration
config.production.yaml	Production configuration

Loading Configuration

# Use specific config file
./wallet-core -config config.yaml

# Production
./wallet-core -config config.production.yaml

Complete Configuration Reference

# Server settings
server:
  host: "0.0.0.0"
  port: ${PORT:50051}
  max_concurrent_streams: 100
  keepalive_time: "30s"
  keepalive_timeout: "10s"

# Database connection
database:
  dsn: ${DATABASE_URL:postgres://user:pass@localhost:5432/olive}
  max_open_conns: 50
  max_idle_conns: 10
  conn_max_lifetime: "10m"

# TLS configuration
tls:
  enabled: false
  cert_file: ""
  key_file: ""
  ca_file: ""

# Ledger settings
ledger:
  request_id_ttl: "24h"
  max_transaction_amount: 10000000  # In smallest currency unit
  default_currency: "SLE"

# VULT integration
vult_integration:
  base_url: ${VULT_BASE_URL}
  api_key: ${VULT_API_KEY}
  timeout: "30s"
  reconciliation_enabled: true
  reconciliation_schedule: "0 2 * * *"  # 2 AM daily

# Logging
logging:
  level: "info"
  format: "json"
  output: "stdout"

# Metrics
metrics:
  enabled: true
  port: 9091

Environment Variable Overrides

Variable	Config Path	Description
PORT	server.port	gRPC server port
DATABASE_URL	database.dsn	PostgreSQL DSN
VULT_BASE_URL	vult_integration.base_url	VULT API URL
VULT_API_KEY	vult_integration.api_key	VULT API key

Configuration by Section

server:
  host: "0.0.0.0"               # Bind address
  port: 50051                    # gRPC port
  max_concurrent_streams: 100   # Max concurrent requests
  keepalive_time: "30s"         # Keepalive ping interval
  keepalive_timeout: "10s"      # Keepalive timeout

Development Configuration

server:
  port: 50051

database:
  dsn: "postgres://olive:olive@localhost:5432/olive?sslmode=disable"
  max_open_conns: 25

tls:
  enabled: false

logging:
  level: "debug"
  format: "pretty"

metrics:
  enabled: true
  port: 9091

Production Configuration

server:
  port: ${PORT:50051}
  max_concurrent_streams: 500
  keepalive_time: "30s"
  keepalive_timeout: "10s"

database:
  dsn: ${DATABASE_URL}
  max_open_conns: 100
  max_idle_conns: 20
  conn_max_lifetime: "10m"

tls:
  enabled: true
  cert_file: "/certs/server.crt"
  key_file: "/certs/server.key"
  ca_file: "/certs/ca.crt"

ledger:
  request_id_ttl: "24h"
  max_transaction_amount: 100000000

vult_integration:
  base_url: ${VULT_BASE_URL}
  api_key: ${VULT_API_KEY}
  timeout: "30s"
  reconciliation_enabled: true
  reconciliation_schedule: "0 2 * * *"

logging:
  level: "info"
  format: "json"

metrics:
  enabled: true
  port: 9091

TLS Configuration

Server-side TLS

tls:
  enabled: true
  cert_file: "/path/to/server.crt"
  key_file: "/path/to/server.key"

Mutual TLS (mTLS)

tls:
  enabled: true
  cert_file: "/path/to/server.crt"
  key_file: "/path/to/server.key"
  ca_file: "/path/to/ca.crt"  # Client CA for verification

Generating Certificates

# Generate CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key -out ca.crt

# Generate server cert
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -out server.crt

Database Configuration

Connection String Format

postgres://user:password@host:port/database?sslmode=MODE

SSL Modes

Mode	Description
disable	No SSL
require	SSL without verification
verify-ca	SSL with CA verification
verify-full	SSL with full verification

Connection Pool Tuning

database:
  max_open_conns: 50    # Based on expected concurrency
  max_idle_conns: 10    # Keep connections warm
  conn_max_lifetime: "10m"  # Prevent stale connections

Migrations

Migrations run automatically at startup. To disable:

database:
  auto_migrate: false

To run manually:

./wallet-core migrate -config config.yaml

Troubleshooting

Database connection failed

• Verify DSN format is correct
• Check network connectivity to database
• Ensure database exists
• Verify credentials

gRPC server failed to start

• Check if port is already in use
• Verify TLS certificates exist and are valid
• Check file permissions on cert files

Migrations failed

• Check database user has CREATE TABLE permissions
• Review migration logs for specific errors
• Ensure database is accessible

VULT integration errors

• Verify VULT_BASE_URL is correct
• Check VULT_API_KEY is valid
• Ensure network access to VULT API

Next Steps

Ledger

Transaction processing details

Deployment

Production deployment guide