1fb7266469
- Introduced Aggregator.sol for Chainlink-compatible oracle functionality, including round-based updates and access control. - Added OracleWithCCIP.sol to extend Aggregator with CCIP cross-chain messaging capabilities. - Created .gitmodules to include OpenZeppelin contracts as a submodule. - Developed a comprehensive deployment guide in NEXT_STEPS_COMPLETE_GUIDE.md for Phase 2 and smart contract deployment. - Implemented Vite configuration for the orchestration portal, supporting both Vue and React frameworks. - Added server-side logic for the Multi-Cloud Orchestration Portal, including API endpoints for environment management and monitoring. - Created scripts for resource import and usage validation across non-US regions. - Added tests for CCIP error handling and integration to ensure robust functionality. - Included various new files and directories for the orchestration portal and deployment scripts.
383 lines
9.2 KiB
Markdown
383 lines
9.2 KiB
Markdown
# 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)
|
|
|