smom-dbis-138/docs/guides/INTEGRATION_GUIDE.md

Integration Guide: Besu, Firefly, and Cacti

Overview

This guide covers the integration of Hyperledger Besu, Firefly, and Cacti for the DeFi Oracle Meta Mainnet (ChainID 138). This integration enables:

• Tokenization: Financial file tokenization using Firefly
• Cross-Chain Interoperability: Cross-chain transactions using Cacti
• Asset Management: Token and NFT management via Firefly
• Blockchain Connectivity: Seamless connection between Besu and other blockchains

Architecture

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Besu      │────────▶│   Firefly   │────────▶│    Cacti    │
│  (ChainID   │         │ (Tokenization│         │ (Cross-Chain│
│    138)     │         │  & Assets)  │         │   Bridge)   │
└─────────────┘         └─────────────┘         └─────────────┘
      │                        │                        │
      │                        │                        │
      └────────────────────────┴────────────────────────┘
                    Financial Tokenization
                      Service (ISO-20022,
                        SWIFT FIN)

Components

1. Hyperledger Besu

• Role: Blockchain network (ChainID 138)
• Consensus: QBFT 2.0
• RPC Endpoints: HTTP and WebSocket
• Integration Points:
  • Firefly connects via RPC
  • Cacti connects via Besu connector plugin

2. Hyperledger Firefly

• Role: Tokenization and asset management
• Features:
  • Token pool management
  • NFT minting
  • Data storage (IPFS)
  • Blockchain abstraction
• Integration Points:
  • Connects to Besu via RPC
  • Provides API for tokenization service
  • Integrates with Cacti for cross-chain

3. Hyperledger Cacti

• Role: Cross-chain interoperability
• Features:
  • Multi-blockchain connectors
  • Cross-chain bridges
  • Asset transfers
• Integration Points:
  • Connects to Besu via connector plugin
  • Integrates with Firefly for token management
  • Enables cross-chain transactions

Deployment

Prerequisites

• Besu network deployed and running
• Kubernetes cluster (AKS)
• RPC endpoints accessible
• Required secrets configured

Step 1: Deploy Firefly

# Deploy Firefly
./scripts/deployment/deploy-firefly.sh

# Verify deployment
kubectl get pods -n firefly
kubectl get svc -n firefly

Step 2: Deploy Cacti

# Deploy Cacti
./scripts/deployment/deploy-cacti.sh

# Verify deployment
kubectl get pods -n cacti
kubectl get svc -n cacti

Step 3: Deploy Tokenization Service

# Deploy tokenization service
./scripts/deployment/deploy-tokenization-service.sh

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

Step 4: Setup Integration

# Setup Firefly-Cacti integration
./scripts/integration/setup-firefly-cacti.sh

# Test connectors
./scripts/integration/test-connectors.sh

Configuration

Firefly Configuration

Firefly is configured via ConfigMap and environment variables:

# k8s/firefly/configmap.yaml
blockchain:
  type: ethereum
  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

Cacti is configured via ConfigMap:

# 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

Tokenization service connects to Firefly:

# 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"

Usage

Tokenize Financial Files

Tokenize ISO-20022 Message

curl -X POST http://financial-tokenization-service:8080/api/v1/tokenize/iso20022 \
  -H "Content-Type: application/json" \
  -d '{
    "xml_content": "<?xml version=\"1.0\"?>...",
    "file_name": "pacs008_001.xml"
  }'

Tokenize SWIFT FIN Message

curl -X POST http://financial-tokenization-service:8080/api/v1/tokenize/swift-fin \
  -H "Content-Type: application/json" \
  -d '{
    "swift_message": "{1:F01...}",
    "file_name": "mt103_001.txt"
  }'

Create Token Pool (Firefly)

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": "FinancialFiles",
    "symbol": "FF",
    "type": "fungible"
  }'

Register Besu Ledger (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:8545",
      "ws": "ws://besu-rpc-service:8546"
    }
  }'

Cross-Chain Transfer (Cacti + Firefly)

curl -X POST http://cactus-api.cacti.svc.cluster.local:4000/api/v1/plugins/ledger-connector/bridge/transfer \
  -H "Content-Type: application/json" \
  -d '{
    "tokenPoolId": "pool-id",
    "amount": "1000",
    "targetNetwork": "ethereum-mainnet",
    "recipient": "0x..."
  }'

Connectors

Besu-Firefly Connector

The Besu-Firefly connector (connectors/besu-firefly/connector.py) provides:

• Network registration
• Contract deployment
• Status monitoring

Usage:

from connectors.besu_firefly import BesuFireflyConnector

connector = BesuFireflyConnector(
    besu_rpc_url="http://besu-rpc-service:8545",
    firefly_api_url="http://firefly-api:5000",
    firefly_api_key="YOUR_API_KEY"
)

# Register network
result = connector.register_besu_network("besu-chain-138", 138)

# Deploy ERC20 contract
contract = connector.deploy_erc20_contract("MyToken", "MTK", 1000000)

Besu-Cacti Connector

The Besu-Cacti connector (connectors/besu-cacti/connector.py) provides:

• Ledger registration
• Contract deployment
• Contract invocation

Usage:

from connectors.besu_cacti import BesuCactiConnector

connector = BesuCactiConnector(
    besu_rpc_url="http://besu-rpc-service:8545",
    cactus_api_url="http://cactus-api:4000"
)

# Register ledger
result = connector.register_besu_ledger("besu-chain-138", 138)

# Deploy contract
contract = connector.deploy_contract(abi, bytecode, constructor_args)

# Invoke contract
result = connector.invoke_contract(
    contract_address,
    abi,
    "transfer",
    ["0x...", "1000"]
)

Firefly-Cacti Connector

The Firefly-Cacti connector (connectors/firefly-cacti/connector.py) provides:

• Cross-chain bridge creation
• Token transfers
• Bridge status monitoring

Usage:

from connectors.firefly_cacti import FireflyCactiConnector

connector = FireflyCactiConnector(
    firefly_api_url="http://firefly-api:5000",
    firefly_api_key="YOUR_API_KEY",
    cactus_api_url="http://cactus-api:4000"
)

# Create bridge
bridge = connector.create_cross_chain_bridge(
    "besu-chain-138",
    "ethereum-mainnet"
)

# Transfer tokens
result = connector.transfer_tokens_cross_chain(
    token_pool_id="pool-id",
    amount="1000",
    target_network="ethereum-mainnet",
    recipient="0x..."
)

Testing

Test Connectors

# Test all connectors
./scripts/integration/test-connectors.sh

Test Tokenization

# Test ISO-20022 parser
cd services/financial-tokenization
pytest tests/test_iso20022_parser.py

# Test SWIFT FIN parser
pytest tests/test_swift_fin_parser.py

Test Integration

# Test Firefly connection
curl http://firefly-api.firefly.svc.cluster.local:5000/api/v1/status

# Test Cacti connection
curl http://cactus-api.cacti.svc.cluster.local:4000/api/v1/api-server/healthcheck

# Test tokenization service
curl http://financial-tokenization-service:8080/api/v1/health

Troubleshooting

Firefly Not Connecting to Besu

1. Check Besu RPC endpoints are accessible
2. Verify chain ID is correct (138)
3. Check Firefly logs: kubectl logs -n firefly -l app=firefly-core

Cacti Connector Not Working

1. Verify Besu connector is deployed
2. Check Cacti API is accessible
3. Verify ledger registration: curl http://cactus-api:4000/api/v1/plugins/ledger-connector/besu/status

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

References

• Firefly Documentation
• Cacti Documentation
• Besu Documentation
• Financial Tokenization Guide
• Firefly Integration Guide
• Cacti Integration Guide