# 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](#overview)
- [Oracle Publisher Service](#oracle-publisher-service)
- [CCIP Monitor Service](#ccip-monitor-service)
- [Financial Tokenization Service](#financial-tokenization-service)
- [Service Deployment](#service-deployment)
- [Service Monitoring](#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

```bash
# 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

```bash
# 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**
   ```bash
   # Set environment variables
   export RPC_URL="https://rpc.d-bis.org"
   export AGGREGATOR_ADDRESS="0x..."
   export PRIVATE_KEY="0x..."
   ```

2. **Deploy Services**
   ```bash
   # 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**
   ```bash
   # 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:

```bash
# 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:

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

## Service Configuration

### Oracle Publisher Configuration

```yaml
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

```yaml
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](ARCHITECTURE.md)
- [Oracle Operations Runbook](../../runbooks/oracle-operations.md)
- [CCIP Operations Runbook](../../runbooks/ccip-operations.md)
- [Monitoring Setup Guide](../operations/MONITORING_SETUP_GUIDE.md)

---

**Last Updated**: 2025-01-27