Documentation Index
Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
Use this file to discover all available pages before exploring further.
Wallet-Core 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
Database
TLS
Ledger
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
database:
dsn: "postgres://user:pass@localhost:5432/olive?sslmode=disable"
max_open_conns: 50 # Max open connections
max_idle_conns: 10 # Max idle connections
conn_max_lifetime: "10m" # Connection max lifetime
tls:
enabled: true
cert_file: "/certs/server.crt"
key_file: "/certs/server.key"
ca_file: "/certs/ca.crt" # For mTLS
ledger:
request_id_ttl: "24h" # Idempotency window
max_transaction_amount: 10000000
default_currency: "SLE"
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
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
./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
- Check database user has CREATE TABLE permissions
- Review migration logs for specific errors
- Ensure database is accessible
- 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
