smom-dbis-138/docs/deployment/DEPLOYMENT_FIREFLY_CACTI.md

Deployment Guide: Firefly and Cacti

Overview

This guide covers the deployment of Hyperledger Firefly and Cacti on the DeFi Oracle Meta Mainnet (ChainID 138).

Prerequisites

• Besu network deployed and running
• Kubernetes cluster (AKS) with kubectl configured
• Helm 3.x installed
• RPC endpoints accessible from Kubernetes cluster

Deployment Options

Option 1: Using Deployment Scripts (Recommended)

# Deploy Firefly
make -f Makefile.integration deploy-firefly

# Deploy Cacti
make -f Makefile.integration deploy-cacti

# Deploy Tokenization Service
make -f Makefile.integration deploy-tokenization

# Setup Integration
make -f Makefile.integration setup-integration

Option 2: Using Helm Charts

# Deploy Firefly
helm install firefly ./helm/firefly -n firefly --create-namespace

# Deploy Cacti
helm install cacti ./helm/cacti -n cacti --create-namespace

Option 3: Using Kubernetes Manifests

# Deploy Firefly
kubectl apply -f k8s/firefly/

# Deploy Cacti
kubectl apply -f k8s/cacti/

# Deploy Tokenization Service
kubectl apply -f services/financial-tokenization/k8s/deployment.yaml

Firefly Deployment

Step 1: Create Namespace

kubectl create namespace firefly

Step 2: Create Secrets

# Generate secrets
kubectl create secret generic firefly-secrets \
  --from-literal=db-password=firefly \
  --from-literal=admin-key=YOUR_ADMIN_KEY \
  --from-literal=private-key=YOUR_PRIVATE_KEY \
  -n firefly

Step 3: Deploy PostgreSQL

kubectl apply -f k8s/firefly/postgres.yaml

Step 4: Deploy IPFS

kubectl apply -f k8s/firefly/ipfs.yaml

Step 5: Deploy Firefly Core

kubectl apply -f k8s/firefly/firefly-core.yaml

Step 6: Verify Deployment

# Check pods
kubectl get pods -n firefly

# Check services
kubectl get svc -n firefly

# Check logs
kubectl logs -n firefly -l app=firefly-core

Cacti Deployment

Step 1: Create Namespace

kubectl create namespace cacti

Step 2: Deploy Cactus API

kubectl apply -f k8s/cacti/cactus-api.yaml

Step 3: Deploy Besu Connector

kubectl apply -f k8s/cacti/besu-connector.yaml

Step 4: Verify Deployment

# Check pods
kubectl get pods -n cacti

# Check services
kubectl get svc -n cacti

# Check logs
kubectl logs -n cacti -l app=cactus-api

Tokenization Service Deployment

Step 1: Build Docker Image

cd services/financial-tokenization
docker build -t financial-tokenization-service:latest .

Step 2: Deploy Service

kubectl apply -f services/financial-tokenization/k8s/deployment.yaml

Step 3: Verify Deployment

# Check pods
kubectl get pods -n besu-network -l app=financial-tokenization-service

# Check logs
kubectl logs -n besu-network -l app=financial-tokenization-service

Configuration

Firefly Configuration

Update k8s/firefly/configmap.yaml:

blockchain:
  rpc:
    http: http://besu-rpc-service.besu-network.svc.cluster.local:8545
    ws: ws://besu-rpc-service.besu-network.svc.cluster.local:8546
  chainId: 138

Cacti Configuration

Update k8s/cacti/configmap.yaml:

besu:
  rpc:
    http: http://besu-rpc-service.besu-network.svc.cluster.local:8545
    ws: ws://besu-rpc-service.besu-network.svc.cluster.local:8546
  chainId: 138

Tokenization Service Configuration

Update services/financial-tokenization/k8s/deployment.yaml:

env:
  - name: FIREFLY_API_URL
    value: http://firefly-api.firefly.svc.cluster.local:5000
  - name: BESU_RPC_URL
    value: http://besu-rpc-service:8545
  - name: CHAIN_ID
    value: "138"

Integration Setup

Step 1: Register Besu Network with Firefly

curl -X POST http://firefly-api.firefly.svc.cluster.local:5000/api/v1/networks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "besu-chain-138",
    "type": "ethereum",
    "chainId": 138,
    "rpc": {
      "http": "http://besu-rpc-service.besu-network.svc.cluster.local:8545",
      "ws": "ws://besu-rpc-service.besu-network.svc.cluster.local:8546"
    }
  }'

Step 2: Register Besu Ledger with Cacti

curl -X POST http://cactus-api.cacti.svc.cluster.local:4000/api/v1/plugins/ledger-connector/besu \
  -H "Content-Type: application/json" \
  -d '{
    "ledgerId": "besu-chain-138",
    "chainId": 138,
    "rpc": {
      "http": "http://besu-rpc-service.besu-network.svc.cluster.local:8545",
      "ws": "ws://besu-rpc-service.besu-network.svc.cluster.local:8546"
    }
  }'

Step 3: Setup Firefly-Cacti Integration

./scripts/integration/setup-firefly-cacti.sh

Testing

Test Firefly

# Health check
curl http://firefly-api.firefly.svc.cluster.local:5000/api/v1/status

# Create token pool
curl -X POST http://firefly-api.firefly.svc.cluster.local:5000/api/v1/tokens/pools \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "TestToken",
    "symbol": "TTK",
    "type": "fungible"
  }'

Test Cacti

# Health check
curl http://cactus-api.cacti.svc.cluster.local:4000/api/v1/api-server/healthcheck

# Get ledger status
curl http://cactus-api.cacti.svc.cluster.local:4000/api/v1/plugins/ledger-connector/besu/status?ledgerId=besu-chain-138

Test Tokenization Service

# Health check
curl http://financial-tokenization-service.besu-network.svc.cluster.local:8080/api/v1/health

# Tokenize ISO-20022
curl -X POST http://financial-tokenization-service.besu-network.svc.cluster.local:8080/api/v1/tokenize/iso20022 \
  -H "Content-Type: application/json" \
  -d '{
    "xml_content": "<?xml version=\"1.0\"?>...",
    "file_name": "pacs008.xml"
  }'

Troubleshooting

Firefly Not Starting

1. Check PostgreSQL is running: kubectl get pods -n firefly -l app=firefly-postgres
2. Check IPFS is running: kubectl get pods -n firefly -l app=firefly-ipfs
3. Check Firefly logs: kubectl logs -n firefly -l app=firefly-core
4. Verify database connection string in ConfigMap

Cacti Not Connecting to Besu

1. Check Besu RPC endpoints are accessible
2. Verify chain ID is correct (138)
3. Check Cacti logs: kubectl logs -n cacti -l app=cactus-api
4. Verify Besu connector is deployed: kubectl get pods -n cacti -l app=cactus-besu-connector

Tokenization Service Errors

1. Check Firefly API is accessible
2. Verify API key is set correctly
3. Check service logs: kubectl logs -n besu-network -l app=financial-tokenization-service
4. Verify parsers are working: pytest services/financial-tokenization/tests/

Cleanup

Remove Firefly

kubectl delete namespace firefly

Remove Cacti

kubectl delete namespace cacti

Remove Tokenization Service

kubectl delete deployment financial-tokenization-service -n besu-network
kubectl delete service financial-tokenization-service -n besu-network

References

• Firefly Documentation
• Cacti Documentation
• Integration Guide
• Firefly Integration
• Cacti Integration