smom-dbis-138/docs/architecture/SERVICES_ARCHITECTURE.md

Services Architecture

Last Updated: 2025-01-27
Status: Active

This document describes the architecture of off-chain services that support the DeFi Oracle Meta Mainnet.

Table of Contents

• Overview
• Oracle Publisher Service
• CCIP Monitor Service
• Financial Tokenization Service
• Service Deployment
• Service Monitoring

Overview

The network includes several off-chain services that provide critical functionality:

1. Oracle Publisher - Fetches and publishes oracle data
2. CCIP Monitor - Monitors CCIP cross-chain messages
3. Financial Tokenization - Tokenization service for financial assets

Oracle Publisher Service

Purpose

The Oracle Publisher service fetches price data from multiple sources, aggregates it, and publishes updates to the blockchain oracle aggregator contract.

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Data Source │────▶│   Oracle    │────▶│  Aggregator │
│     1       │     │  Publisher  │     │  Contract   │
└─────────────┘     └─────────────┘     └─────────────┘
┌─────────────┐           │
│ Data Source │───────────┘
│     2       │
└─────────────┘

Components

• Data Fetcher: Fetches data from multiple sources
• Aggregator: Calculates median from sources
• Publisher: Publishes updates to blockchain
• Metrics: Prometheus metrics for monitoring

Configuration

Environment Variables:

• RPC_URL - Blockchain RPC endpoint
• AGGREGATOR_ADDRESS - Oracle aggregator contract address
• PRIVATE_KEY - Private key for signing transactions
• HEARTBEAT - Update frequency (seconds)
• DEVIATION_THRESHOLD - Price deviation threshold (%)

Deployment

# Deploy oracle publisher
kubectl apply -f services/oracle-publisher/k8s/deployment.yaml

# Verify deployment
kubectl get pods -l app=oracle-publisher -n besu-network

Monitoring

• Metrics: Available on port 8000
• Logs: Available via kubectl logs
• Health: HTTP health endpoint

CCIP Monitor Service

Purpose

The CCIP Monitor service monitors cross-chain messages sent via Chainlink CCIP, tracks message status, and provides alerts for failed messages.

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  CCIP Router│────▶│   CCIP      │────▶│  Alerting  │
│  Contract   │     │   Monitor   │     │  System    │
└─────────────┘     └─────────────┘     └─────────────┘

Features

• Message tracking
• Status monitoring
• Failure detection
• Alert generation
• Metrics collection

Deployment

# Deploy CCIP monitor
kubectl apply -f services/ccip-monitor/k8s/deployment.yaml

Financial Tokenization Service

Purpose

The Financial Tokenization service provides tokenization capabilities for financial assets, integrating with Firefly and Cacti for cross-chain operations.

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Financial  │────▶│   Firefly   │────▶│  Blockchain │
│   Assets    │     │ (Tokenize)  │     │  (ChainID  │
└─────────────┘     └─────────────┘     │    138)     │
                                         └─────────────┘

Features

• Asset tokenization
• ISO-20022 support
• SWIFT FIN integration
• Cross-chain bridging via Cacti

Service Deployment

Prerequisites

• Kubernetes cluster running
• RPC endpoint accessible
• Private keys configured
• Environment variables set

Deployment Steps

1. Configure Environment

   # Set environment variables
   export RPC_URL="https://rpc.d-bis.org"
   export AGGREGATOR_ADDRESS="0x..."
   export PRIVATE_KEY="0x..."
   

2. Deploy Services

   # Deploy all services
   kubectl apply -f services/oracle-publisher/k8s/
   kubectl apply -f services/ccip-monitor/k8s/
   kubectl apply -f services/financial-tokenization/k8s/
   

3. Verify Deployment

   # Check service status
   kubectl get pods -n besu-network -l app=oracle-publisher
   kubectl get pods -n besu-network -l app=ccip-monitor
   

Service Monitoring

Metrics

All services expose Prometheus metrics:

• Oracle Publisher: oracle_updates_sent_total, oracle_update_errors_total
• CCIP Monitor: ccip_messages_tracked, ccip_message_failures
• Financial Tokenization: tokenization_requests, tokenization_success

Logs

View service logs:

# Oracle Publisher logs
kubectl logs -l app=oracle-publisher -n besu-network -f

# CCIP Monitor logs
kubectl logs -l app=ccip-monitor -n besu-network -f

Health Checks

All services include health check endpoints:

# Check service health
kubectl exec -n besu-network <pod-name> -- curl http://localhost:8080/health

Service Configuration

Oracle Publisher Configuration

apiVersion: v1
kind: ConfigMap
metadata:
  name: oracle-config
  namespace: besu-network
data:
  RPC_URL: "https://rpc.d-bis.org"
  AGGREGATOR_ADDRESS: "0x..."
  HEARTBEAT: "60"
  DEVIATION_THRESHOLD: "0.5"

CCIP Monitor Configuration

apiVersion: v1
kind: ConfigMap
metadata:
  name: ccip-monitor-config
  namespace: besu-network
data:
  RPC_URL: "https://rpc.d-bis.org"
  CCIP_ROUTER_ADDRESS: "0x..."
  MONITORING_INTERVAL: "30"

Troubleshooting

Service Not Starting

1. Check pod status: kubectl get pods -n besu-network
2. Check logs: kubectl logs <pod-name> -n besu-network
3. Check events: kubectl get events -n besu-network
4. Verify configuration: kubectl get configmap -n besu-network

Service Not Updating

1. Check RPC connectivity
2. Verify contract addresses
3. Check private key access
4. Review service logs

Related Documentation

• Architecture Documentation
• Oracle Operations Runbook
• CCIP Operations Runbook
• Monitoring Setup Guide

---

Last Updated: 2025-01-27