Add multi-currency ledger support for GHS and NGN

.env.config.example

@@ -1,82 +1,47 @@
-# Configuration Guide - Environment Variables
-
-# This file documents all environment variables that can override configuration.
-# Copy this to .env and modify as needed for your environment.
-
-# Environment
-NODE_ENV=development
-
-# Database
-DATABASE_URL=postgresql://localhost/mobile_money_dev
-
-# Redis
-REDIS_URL=redis://localhost:6379
-
-# ===== PROVIDER LIMITS (XAF) =====
-# MTN Provider
-MTN_MIN_AMOUNT=100
-MTN_MAX_AMOUNT=500000
-MTN_CALLBACK_SECRET=your_mtn_callback_secret
-MTN_CALLBACK_SIGNATURE_HEADER=X-Callback-Signature
-
-# Airtel Provider
-AIRTEL_MIN_AMOUNT=100
-AIRTEL_MAX_AMOUNT=1000000
-
-# Orange Provider
-ORANGE_MIN_AMOUNT=500
-ORANGE_MAX_AMOUNT=750000
-
-# ===== TRANSACTION LIMITS BY KYC LEVEL (XAF) =====
-LIMIT_UNVERIFIED=10000
-LIMIT_BASIC=100000
-LIMIT_FULL=1000000
-
-# ===== GENERAL TRANSACTION LIMITS (XAF) =====
-MIN_TRANSACTION_AMOUNT=100
-MAX_TRANSACTION_AMOUNT=1000000
-
-# ===== TRANSACTION TIMEOUTS & TTL =====
-TRANSACTION_TIMEOUT_MINUTES=30
-IDEMPOTENCY_KEY_TTL_HOURS=24
-
-# ===== AUTHENTICATION =====
-MAX_LOGIN_ATTEMPTS=5
-ADMIN_API_KEY=dev-admin-key
-
-# ===== CACHE SETTINGS =====
-SLOW_QUERY_THRESHOLD_MS=1000
-ENABLE_SLOW_QUERY_LOGGING=false
-
-# ===== STELLAR CONFIGURATION =====
-# Stellar network configuration
-STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
-# Single URL or comma-separated list (primary first, then fallbacks) for
-# automatic Horizon node rotation/failover.
-STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
-
-# ===== THIRD-PARTY INTEGRATIONS =====
-# AWS S3
-AWS_ACCESS_KEY_ID=your_access_key
-AWS_SECRET_ACCESS_KEY=your_secret_key
-AWS_REGION=us-east-1
-AWS_S3_BUCKET=your_bucket
-
-# SendGrid Email
-SENDGRID_API_KEY=your_sendgrid_key
-
-# Sentry Error Tracking
-SENTRY_DSN=your_sentry_dsn
-
-# DataDog APM
-DATADOG_API_KEY=your_datadog_key
-
-# PagerDuty
-PAGERDUTY_API_KEY=your_pagerduty_key
-
 # ===== NOTES =====
 # - All provider limits are in XAF (West African CFA franc)
 # - KYC transaction limits should follow: unverified <= basic <= full
 # - Min transaction amount should be <= max transaction amount
 # - Cache TTLs are in seconds or milliseconds as indicated
 # - See docs/CENTRALIZED_CONFIG.md for complete configuration reference
+#
+# Grafana Azure AD setup checklist:
+#   1. Create an App Registration in Azure Portal (Authentication blade)
+#   2. Under "Redirect URIs", select "Web" and add:
+#      <GF_SERVER_ROOT_URL>/login/azuread
+#      (e.g. http://localhost:3001/login/azuread for local dev)
+#   3. Under "API permissions", grant Microsoft Graph "User.Read" (delegated)
+#   4. Set "Supported account types" based on your needs (single vs multi-tenant)
+#   5. Copy the Application (client) ID → GF_AUTH_AZUREAD_CLIENT_ID
+#   6. Create a client secret under "Certificates & secrets" → GF_AUTH_AZUREAD_CLIENT_SECRET
+#   7. For production, set GF_AUTH_AZUREAD_ALLOWED_DOMAINS or GF_AUTH_AZUREAD_ALLOWED_GROUPS
+
+# ===== PAGERDUTY (alert routing for balance shortfalls and provider errors) =====
+# PagerDuty Events API V2 integration key. REQUIRED to enable PagerDuty alert
+# routing. Without this, the service starts in disabled mode (no-op).
+PAGERDUTY_INTEGRATION_KEY=
+
+# Prefix used for all dedup_keys. Each alert appends a contextual suffix
+# (e.g. "-mtn-XAF-balance-shortfall") so incidents are grouped per asset.
+PAGERDUTY_DEDUP_KEY=mobile-money
+
+# ----- Balance Shortfall Tier Escalation Matrix (issue #1018) -----
+# Three strictly-ordered tiers map a shortfall percentage to a PagerDuty
+# severity + escalation path:
+#
+#   | Tier     | shortfallPct range                                    | Severity  | Escalation path              |
+#   |----------|-------------------------------------------------------|-----------|------------------------------|
+#   | minor    | >= BALANCE_SHORTFALL_MINOR_PCT    and < _MODERATE_PCT  | warning   | team-notification             |
+#   | moderate | >= BALANCE_SHORTFALL_MODERATE_PCT and < _CRITICAL_PCT | error     | operational-escalation        |
+#   | critical | >= BALANCE_SHORTFALL_CRITICAL_PCT                     | critical  | immediate-escalation          |
+#   | (none)   | <  BALANCE_SHORTFALL_MINOR_PCT                        | n/a       | no PagerDuty alert (noise)    |
+#
+# INVARIANT: tiers MUST satisfy 0 < MINOR_PCT < MODERATE_PCT < CRITICAL_PCT < 100.
+# If misconfigured (out-of-order, equal, NaN, out-of-range), the service logs
+# a warning at startup and falls back to safe defaults (10/25/50). The active
+# tier matrix is logged once per process start so on-call can verify routing.
+#
+# Defaults (used when env vars are unset): minor=10, moderate=25, critical=50.
+BALANCE_SHORTFALL_CRITICAL_PCT=50
+BALANCE_SHORTFALL_MODERATE_PCT=25
+BALANCE_SHORTFALL_MINOR_PCT=10

.env.example

@@ -230,6 +230,8 @@ AIRTEL_CURRENCY=NGN
 # and a merchant web portal session must be maintained by the backend.
 AIRTEL_MODE=direct
 AIRTEL_WEB_BASE_URL=https://airtel-money.example
+AIRTEL_DIRECT_BASE_URL=your_airtel_direct_base_url
+AIRTEL_SANDBOX_BASE_URL=your_airtel_sandbox_base_url
 AIRTEL_USERNAME=your_airtel_portal_username
 AIRTEL_PASSWORD=your_airtel_portal_password
 AIRTEL_LOGIN_PATH=/login
@@ -499,12 +501,26 @@ MOCK_WEBHOOK_LATENCY_MS=3000
 MOCK_WEBHOOK_LATENCY_ENABLED=true
 
 # ---------------------------------------------------------------------------
-# Provider Health Check
+# Provider Health Check & Circuit Breaker
 # ---------------------------------------------------------------------------
 # Cron schedule for provider health checks (default: every 5 minutes)
 PROVIDER_HEALTH_CHECK_CRON=*/5 * * * *
 # Webhook URLs for provider health alerts (comma-separated or individual)
 PROVIDER_HEALTH_WEBHOOK_URL=
+#
+# Number of consecutive ping failures before the health-check circuit breaker
+# opens for a provider (default: 3)
+PROVIDER_HEALTH_FAILURE_THRESHOLD=3
+#
+# Duration (ms) to keep the health-check circuit breaker open before allowing
+# a retry (default: 60000 = 1 minute)
+PROVIDER_HEALTH_OPEN_DURATION_MS=60000
+#
+# Optional per-provider override for the opossum circuit breaker failure
+# threshold (number of failures in the rolling window before opening).
+# When set, takes precedence over PROVIDER_CIRCUIT_BREAKER_VOLUME_THRESHOLD
+# for the specified provider.
+# Example: VODACOM_CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
 
 # ---------------------------------------------------------------------------
 # PII Encryption (AES-256-GCM)
@@ -581,5 +597,58 @@ LOG_SHARD_RETENTION_DAYS=7
 # ---------------------------------------------------------------------------
 # Dedicated Sandbox Environment
 # ---------------------------------------------------------------------------
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your_aws_access_key_id
+AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
+AWS_S3_BUCKET=mobile-money-kyc-documents
+
+# KYC Provider Configuration
+KYC_API_URL=https://api.entrust.com
+KYC_API_KEY=your_kyc_api_key
+KYC_WEBHOOK_SECRET=your_webhook_secret
+
+# --- Twilio Configuration ---
+TWILIO_ACCOUNT_SID=your_twilio_account_sid
+TWILIO_AUTH_TOKEN=your_twilio_auth_token
+TWILIO_PHONE_NUMBER=your_twilio_sms_number
+SMS_PROVIDER=twilio # 'twilio' or 'none'
+
+# WhatsApp Official API (Twilio)
+WHATSAPP_ENABLED=false
+TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886
+TWILIO_WHATSAPP_TRANSACTION_TEMPLATE_SID=HX...
+TWILIO_WHATSAPP_OTP_TEMPLATE_SID=HX...
+USE_HTTP2=false  # Set to true with valid certs to enable HTTP/2
+
+# Intercom Configuration
+INTERCOM_ACCESS_TOKEN=your_intercom_access_token
+# Optional: Admin ID for sending messages
+INTERCOM_ADMIN_ID=
+
+# Support API Timeout and Retry Configuration
+SUPPORT_API_TIMEOUT_MS=10000
+SUPPORT_RETRY_ATTEMPTS=3
+SUPPORT_RETRY_DELAY_MS=1000
+
+# Refresh Token 
+REFRESH_TOKEN_EXPIRES_IN=
+REFRESH_TOKEN_SECRET=
+REFRESH_TOKEN_ISSUER=
+
+# ---------------------------------------------------------------------------
+# IP Blacklisting
+# ---------------------------------------------------------------------------
+# Comma-separated list of individual IPs to block at the worker/middleware layer.
+# Example: IP_BLACKLIST_IPS=203.0.113.42,198.51.100.7
+IP_BLACKLIST_IPS=
+
+# Comma-separated list of CIDR ranges to block at the worker/middleware layer.
+# Example: IP_BLACKLIST_CIDRS=203.0.113.0/24,198.51.100.0/24
+IP_BLACKLIST_CIDRS=
+
+# Dynamic blacklist entries can also be managed at runtime via Redis keys:
+#   Exact IP  — SET ip:blacklist:<ip> 1 [EX <ttl>]
+#   CIDR set  — SADD ip:blacklist:cidrs <cidr>
+# ---------------------------------------------------------------------------
 IS_SANDBOX=false
-SANDBOX_DATABASE_URL=postgresql://user:password@localhost:5432/mobile_money_sandbox?schema=public
+SANDBOX_DATABASE_URL=postgresql://user:password@localhost:5432/mobile_money_sandbox?schema=public

.github/workflows/markdownlint.yml

@@ -0,0 +1,37 @@
+name: Markdown Lint
+
+on:
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - "**/*.md"
+
+jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Get changed markdown files
+        id: changed-files
+        run: |
+          files=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }} -- '*.md' | tr '\n' ' ')
+          echo "files=${files}" >> $GITHUB_OUTPUT
+
+      - name: Lint changed markdown files
+        run: |
+          if [ -n "${{ steps.changed-files.outputs.files }}" ]; then
+            npx markdownlint ${{ steps.changed-files.outputs.files }}
+          else
+            echo "No markdown files changed, skipping."
+          fi

.gitignore

@@ -5,6 +5,7 @@ node_modules/
 dist/
 contracts/target/
 *.tsbuildinfo
+.docusaurus/
 
 # Kotlin SDK build artifacts
 sdk/build/

.kilo/kilo.json

@@ -1,3 +1,4 @@
 {
+  "$schema": "https://app.kilo.ai/config.json",
   "snapshot": false
 }

.markdownlint.json

@@ -0,0 +1,17 @@
+{
+  "default": true,
+  "MD004": { "style": "asterisk" },
+  "MD009": { "br_spaces": 2 },
+  "MD013": false,
+  "MD024": { "allow_different_nesting": true },
+  "MD029": { "style": "ordered" },
+  "MD030": { "ol_multi": 1, "ul_multi": 1 },
+  "MD033": false,
+  "MD040": false,
+  "MD041": false,
+  "MD046": { "style": "fenced" },
+  "MD047": true,
+  "MD048": { "style": "backtick" },
+  "MD058": false,
+  "MD060": false
+}

benchmarks/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "soroban-gas-benchmark"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+soroban-sdk = { version = "25.3.0", features = ["testutils"] }
+escrow = { path = "../contracts/escrow" }
+htlc = { path = "../contracts/htlc" }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"