# 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

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

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

### Step 2: Deploy Cacti

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

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

### Step 3: Deploy Tokenization Service

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

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

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

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

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

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

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

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

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

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

```python
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**:

```python
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**:

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

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

### Test Tokenization

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

```bash
# 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](https://hyperledger.github.io/firefly/)
- [Cacti Documentation](https://hyperledger.github.io/cacti/)
- [Besu Documentation](https://besu.hyperledger.org/)
- [Financial Tokenization Guide](FINANCIAL_TOKENIZATION.md)
- [Firefly Integration Guide](FIREFLY_INTEGRATION.md)
- [Cacti Integration Guide](CACTI_INTEGRATION.md)