WIP: HYBX OMNL and deployment documentation updates
This commit is contained in:
defiQUG
@@ -62,4 +62,9 @@ systemd/price-feed-keeper.service
|
||||
- Prefer current ops docs: [docs/ccip-integration/](../ccip-integration/) and runbooks
|
||||
|
||||
## Archive docs
|
||||
Imported CCIP and keeper documentation lives under [docs/ccip/archive-import/](../ccip/archive-import/).
|
||||
Imported CCIP and keeper documentation was consolidated into [docs/ccip-integration/](../ccip-integration/) on **2026-06-02**. [docs/ccip/archive-import/](../ccip/archive-import/) is a redirect stub only.
|
||||
|
||||
### Consolidation (2026-06-02)
|
||||
- Chain 138 guides → `docs/ccip-integration/chain138/`
|
||||
- Reference material → `docs/ccip-integration/reference/`
|
||||
- Ops supplements → `docs/ccip-integration/operations/`
|
||||
|
||||
@@ -99,8 +99,8 @@ This is the **master index** of all project documentation. Use this as your star
|
||||
- **[Firefly Integration](operations/integrations/FIREFLY_INTEGRATION.md)** - Firefly integration
|
||||
- **[Cacti Integration](operations/integrations/CACTI_INTEGRATION.md)** - Cacti integration
|
||||
- **[METAMASK_BD.md](operations/integrations/METAMASK_BD.md)** - MetaMask integration details
|
||||
- **[Crypto.com OTC Integration](../../dbis_core/src/core/exchange/crypto-com-otc/README.md)** - Crypto.com OTC 2.0 API for institutional trading (DBIS Core)
|
||||
- **[Exchange Registry](../../dbis_core/src/core/exchange/)** - Multi-exchange price API (Binance, Kraken, Oanda, FXCM)
|
||||
- **[Crypto.com OTC Integration](..//home/intlc/projects/dbis_core/src/core/exchange/crypto-com-otc/README.md)** - Crypto.com OTC 2.0 API for institutional trading (DBIS Core)
|
||||
- **[Exchange Registry](..//home/intlc/projects/dbis_core/src/core/exchange/)** - Multi-exchange price API (Binance, Kraken, Oanda, FXCM)
|
||||
- **[Ramp API](~/projects/metamask-integration/src/ramps/)** - Fiat on/off-ramp session API (MoonPay, Ramp, Onramper, etc.)
|
||||
- **[DeFi Router](../../alltra-lifi-settlement/src/payments/)** - 1inch, ParaSwap, 0x DEX aggregator
|
||||
|
||||
|
||||
@@ -181,7 +181,7 @@ npm install
|
||||
npm run build
|
||||
# Deploy to hosting provider
|
||||
|
||||
cd ../dbis_core/frontend
|
||||
cd /home/intlc/projects/dbis_core/frontend
|
||||
npm install
|
||||
npm run build
|
||||
# Deploy to hosting provider
|
||||
|
||||
@@ -4,6 +4,19 @@
|
||||
|
||||
Production-grade CCIP integration that turns Chain-138 activity into verified, on-chain Ethereum transactions using Chainlink CCIP.
|
||||
|
||||
## Documentation map
|
||||
|
||||
Canonical CCIP docs for Chain 138 and cross-chain integration. Archive import material was consolidated here on **2026-06-02** (formerly under `docs/ccip/archive-import/`).
|
||||
|
||||
| Section | Contents |
|
||||
|---------|----------|
|
||||
| [chain138/](chain138/) | Chain 138 deployment guide, checklist, testing, chain selector |
|
||||
| [reference/](reference/) | API reference, implementation summary, security, bridge user guide, quick reference, review notes |
|
||||
| [operations/](operations/) | CCIP monitoring, runbooks, admin key management (supplements [operations/integrations/CCIP_*](../operations/integrations/)) |
|
||||
|
||||
Top-level guides: [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md), [QUICK_START.md](QUICK_START.md).
|
||||
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
|
||||
@@ -1,7 +1,13 @@
|
||||
# CCIP archive-import index
|
||||
# CCIP archive import (redirect)
|
||||
|
||||
Historical CCIP and keeper documentation imported from the sibling WIP archive (2026-06-02).
|
||||
Documentation from the sibling WIP archive import (**2026-06-02**) was consolidated into the canonical CCIP integration docs.
|
||||
|
||||
**Current operations:** use canonical [docs/ccip-integration/](../../ccip-integration/) and repository runbooks matching `runbooks/ccip-*` for live procedures.
|
||||
**Use instead:** [docs/ccip-integration/](../../ccip-integration/README.md)
|
||||
|
||||
This folder is read-only reference from the archive; do not treat it as the source of truth over `ccip-integration`.
|
||||
| Former location | New location |
|
||||
|-----------------|--------------|
|
||||
| Chain 138 deployment, testing, checklist, selector | [chain138/](../../ccip-integration/chain138/) |
|
||||
| API, security, user guides, quick reference | [reference/](../../ccip-integration/reference/) |
|
||||
| Monitoring, runbooks, admin keys | [operations/](../../ccip-integration/operations/) |
|
||||
|
||||
Import provenance: [docs/00-meta/SIBLING_WIP_IMPORT.md](../../00-meta/SIBLING_WIP_IMPORT.md)
|
||||
|
||||
@@ -1,247 +0,0 @@
|
||||
# Price Feed Keeper - Complete Integration Guide
|
||||
|
||||
**Status**: ✅ **ALL INTEGRATION OPTIONS COMPLETE**
|
||||
|
||||
This document provides a quick reference for all keeper integration options.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Option 1: Standalone Service (Simplest)
|
||||
|
||||
```bash
|
||||
# Deploy keeper
|
||||
forge script script/reserve/DeployKeeper.s.sol:DeployKeeper --rpc-url chain138 --broadcast
|
||||
|
||||
# Start service
|
||||
export KEEPER_PRIVATE_KEY=<key>
|
||||
export PRICE_FEED_KEEPER_ADDRESS=<address>
|
||||
node scripts/reserve/keeper-service.js
|
||||
```
|
||||
|
||||
### Option 2: Complete Deployment (All Options)
|
||||
|
||||
```bash
|
||||
# Install Node.js dependencies
|
||||
npm install
|
||||
|
||||
# Deploy everything
|
||||
./scripts/reserve/deploy-all.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration Options
|
||||
|
||||
### 1. Standalone Service ✅
|
||||
|
||||
**Best for**: Development, testing, simple deployments
|
||||
|
||||
- Node.js service: `scripts/reserve/keeper-service.js`
|
||||
- Bash service: `scripts/reserve/keeper-service.sh`
|
||||
|
||||
**Setup**: See [KEEPER_SETUP.md](./docs/integration/KEEPER_SETUP.md)
|
||||
|
||||
---
|
||||
|
||||
### 2. Chainlink Keepers ✅
|
||||
|
||||
**Best for**: Decentralized, reliable automation
|
||||
|
||||
- Contract: `ChainlinkKeeperCompatible.sol`
|
||||
- Setup: `scripts/reserve/chainlink-keeper-setup.js`
|
||||
|
||||
**Requirements**:
|
||||
- Chainlink KeeperRegistry address
|
||||
- LINK token for funding
|
||||
- Gas limit configuration
|
||||
|
||||
**Setup**:
|
||||
```bash
|
||||
# Deploy compatible contract
|
||||
forge script script/reserve/DeployChainlinkKeeper.s.sol:DeployChainlinkKeeper --rpc-url chain138 --broadcast
|
||||
|
||||
# Register upkeep
|
||||
export LINK_TOKEN_ADDRESS=<link>
|
||||
export KEEPER_REGISTRY_ADDRESS=<registry>
|
||||
node scripts/reserve/chainlink-keeper-setup.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Gelato Network ✅
|
||||
|
||||
**Best for**: Cost-effective automation
|
||||
|
||||
- Contract: `GelatoKeeperCompatible.sol`
|
||||
- Setup: `scripts/reserve/gelato-keeper-setup.js`
|
||||
|
||||
**Requirements**:
|
||||
- Gelato Ops address
|
||||
- Native token for funding
|
||||
|
||||
**Setup**:
|
||||
```bash
|
||||
# Deploy compatible contract
|
||||
forge script script/reserve/DeployGelatoKeeper.s.sol:DeployGelatoKeeper --rpc-url chain138 --broadcast
|
||||
|
||||
# Create task
|
||||
export GELATO_OPS=<ops>
|
||||
node scripts/reserve/gelato-keeper-setup.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Systemd Service ✅
|
||||
|
||||
**Best for**: Production Linux servers
|
||||
|
||||
- Service file: `systemd/price-feed-keeper.service`
|
||||
|
||||
**Setup**:
|
||||
```bash
|
||||
sudo cp systemd/price-feed-keeper.service /etc/systemd/system/
|
||||
sudo systemctl enable price-feed-keeper
|
||||
sudo systemctl start price-feed-keeper
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Docker Container ✅
|
||||
|
||||
**Best for**: Containerized deployments
|
||||
|
||||
- Compose file: `docker/docker-compose.keeper.yml`
|
||||
- Dockerfile: `docker/Dockerfile.keeper`
|
||||
|
||||
**Setup**:
|
||||
```bash
|
||||
docker-compose -f docker/docker-compose.keeper.yml up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Start Monitor Service
|
||||
|
||||
```bash
|
||||
export PRICE_FEED_KEEPER_ADDRESS=<address>
|
||||
export ALERT_WEBHOOK=<webhook_url> # Optional
|
||||
node scripts/reserve/monitor-keeper.js
|
||||
```
|
||||
|
||||
### Health Checks
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/health
|
||||
curl http://localhost:3000/stats
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Required Environment Variables
|
||||
|
||||
```bash
|
||||
export RPC_URL_138=https://rpc.d-bis.org
|
||||
export PRIVATE_KEY=<deployer_private_key>
|
||||
export PRICE_FEED_KEEPER_ADDRESS=<keeper_address>
|
||||
export KEEPER_PRIVATE_KEY=<keeper_wallet_private_key>
|
||||
export UPDATE_INTERVAL=30
|
||||
```
|
||||
|
||||
### Optional Variables
|
||||
|
||||
```bash
|
||||
# Chainlink
|
||||
export LINK_TOKEN_ADDRESS=<link>
|
||||
export KEEPER_REGISTRY_ADDRESS=<registry>
|
||||
export UPKEEP_INTERVAL=30
|
||||
export GAS_LIMIT=500000
|
||||
export FUNDING_AMOUNT=10
|
||||
|
||||
# Gelato
|
||||
export GELATO_OPS=<ops>
|
||||
export EXECUTION_INTERVAL=30
|
||||
export FUNDING_AMOUNT=0.1
|
||||
|
||||
# Monitoring
|
||||
export ALERT_WEBHOOK=<webhook_url>
|
||||
export CHECK_INTERVAL=60
|
||||
export ALERT_THRESHOLD=3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
contracts/reserve/
|
||||
├── PriceFeedKeeper.sol # Core keeper
|
||||
├── ChainlinkKeeperCompatible.sol # Chainlink wrapper
|
||||
└── GelatoKeeperCompatible.sol # Gelato wrapper
|
||||
|
||||
script/reserve/
|
||||
├── DeployKeeper.s.sol # Deploy keeper
|
||||
├── DeployChainlinkKeeper.s.sol # Deploy Chainlink wrapper
|
||||
├── DeployGelatoKeeper.s.sol # Deploy Gelato wrapper
|
||||
├── PerformUpkeep.s.sol # Manual upkeep
|
||||
└── CheckUpkeep.s.sol # Check status
|
||||
|
||||
scripts/reserve/
|
||||
├── keeper-service.js # Node.js service
|
||||
├── keeper-service.sh # Bash service
|
||||
├── chainlink-keeper-setup.js # Chainlink setup
|
||||
├── gelato-keeper-setup.js # Gelato setup
|
||||
├── monitor-keeper.js # Monitoring
|
||||
└── deploy-all.sh # Deployment automation
|
||||
|
||||
systemd/
|
||||
└── price-feed-keeper.service # Systemd service
|
||||
|
||||
docker/
|
||||
├── docker-compose.keeper.yml # Docker Compose
|
||||
└── Dockerfile.keeper # Docker image
|
||||
|
||||
docs/integration/
|
||||
├── KEEPER_SETUP.md # Setup guide
|
||||
├── KEEPER_COMPLETE.md # Completion summary
|
||||
└── KEEPER_INTEGRATION_COMPLETE.md # Full integration guide
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[KEEPER_SETUP.md](./docs/integration/KEEPER_SETUP.md)** - Detailed setup guide
|
||||
- **[KEEPER_INTEGRATION_COMPLETE.md](./docs/integration/KEEPER_INTEGRATION_COMPLETE.md)** - Complete integration guide
|
||||
- **[KEEPER_COMPLETE.md](./docs/integration/KEEPER_COMPLETE.md)** - Completion summary
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check [KEEPER_SETUP.md](./docs/integration/KEEPER_SETUP.md) troubleshooting section
|
||||
2. Review [KEEPER_INTEGRATION_COMPLETE.md](./docs/integration/KEEPER_INTEGRATION_COMPLETE.md)
|
||||
3. Check keeper logs: `journalctl -u price-feed-keeper -f`
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
✅ **ALL INTEGRATION OPTIONS COMPLETE**
|
||||
|
||||
- ✅ Standalone Service
|
||||
- ✅ Chainlink Keepers
|
||||
- ✅ Gelato Network
|
||||
- ✅ Systemd Service
|
||||
- ✅ Docker Container
|
||||
- ✅ Monitoring & Alerting
|
||||
- ✅ Deployment Automation
|
||||
|
||||
**Ready for production deployment on ChainID 138**
|
||||
|
||||
@@ -1,319 +0,0 @@
|
||||
# CCIP Integration Guide for Developers
|
||||
|
||||
**Date**: 2025-01-27
|
||||
**Network**: ChainID 138 (DeFi Oracle Meta Mainnet)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide provides technical details for developers integrating with CCIP infrastructure on ChainID 138.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Components
|
||||
|
||||
1. **CCIP Router**: Routes messages between chains
|
||||
2. **CCIP Bridges**: Handle token transfers
|
||||
3. **CCIP Sender/Receiver**: Handle oracle data transmission
|
||||
|
||||
### Message Flow
|
||||
|
||||
```
|
||||
Source Chain → CCIP Router → Destination Chain → CCIP Router → Receiver
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Pattern 1: Token Bridge Integration
|
||||
|
||||
```solidity
|
||||
// Import bridge interface
|
||||
import "./IC CIPWETH9Bridge.sol";
|
||||
|
||||
contract MyContract {
|
||||
CCIPWETH9Bridge public bridge;
|
||||
|
||||
function transferCrossChain(
|
||||
uint64 destinationSelector,
|
||||
address recipient,
|
||||
uint256 amount
|
||||
) external {
|
||||
// Approve bridge
|
||||
weth9.approve(address(bridge), amount);
|
||||
|
||||
// Send cross-chain
|
||||
bytes32 messageId = bridge.sendCrossChain(
|
||||
destinationSelector,
|
||||
recipient,
|
||||
amount
|
||||
);
|
||||
|
||||
emit TransferInitiated(messageId, destinationSelector, amount);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 2: Oracle Data Integration
|
||||
|
||||
```solidity
|
||||
import "./CCIPSender.sol";
|
||||
import "./CCIPReceiver.sol";
|
||||
|
||||
contract MyOracleContract {
|
||||
CCIPSender public sender;
|
||||
CCIPReceiver public receiver;
|
||||
|
||||
function sendOracleUpdate(
|
||||
uint64 destinationSelector,
|
||||
uint256 answer,
|
||||
uint256 roundId,
|
||||
uint256 timestamp
|
||||
) external payable {
|
||||
bytes32 messageId = sender.sendOracleUpdate{value: msg.value}(
|
||||
destinationSelector,
|
||||
answer,
|
||||
roundId,
|
||||
timestamp
|
||||
);
|
||||
}
|
||||
|
||||
function ccipReceive(
|
||||
IRouterClient.Any2EVMMessage calldata message
|
||||
) external {
|
||||
// Process received oracle data
|
||||
(uint256 answer, uint256 roundId, uint256 timestamp) =
|
||||
abi.decode(message.data, (uint256, uint256, uint256));
|
||||
|
||||
// Update oracle
|
||||
updateOracle(answer, roundId, timestamp);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 3: Custom Message Sending
|
||||
|
||||
```solidity
|
||||
import "./IRouterClient.sol";
|
||||
|
||||
contract MyCustomContract {
|
||||
IRouterClient public router;
|
||||
|
||||
function sendCustomMessage(
|
||||
uint64 destinationSelector,
|
||||
address receiver,
|
||||
bytes memory data
|
||||
) external payable {
|
||||
IRouterClient.EVM2AnyMessage memory message = IRouterClient.EVM2AnyMessage({
|
||||
receiver: abi.encode(receiver),
|
||||
data: data,
|
||||
tokenAmounts: new IRouterClient.TokenAmount[](0),
|
||||
feeToken: address(0), // Native ETH
|
||||
extraArgs: ""
|
||||
});
|
||||
|
||||
uint256 fee = router.getFee(destinationSelector, message);
|
||||
|
||||
(bytes32 messageId, ) = router.ccipSend{value: fee}(
|
||||
destinationSelector,
|
||||
message
|
||||
);
|
||||
|
||||
emit MessageSent(messageId, destinationSelector);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Interfaces
|
||||
|
||||
### IRouterClient
|
||||
|
||||
```solidity
|
||||
interface IRouterClient {
|
||||
function ccipSend(
|
||||
uint64 destinationChainSelector,
|
||||
EVM2AnyMessage memory message
|
||||
) external payable returns (bytes32 messageId, uint256 fees);
|
||||
|
||||
function getFee(
|
||||
uint64 destinationChainSelector,
|
||||
EVM2AnyMessage memory message
|
||||
) external view returns (uint256 fee);
|
||||
}
|
||||
```
|
||||
|
||||
### CCIPWETH9Bridge / CCIPWETH10Bridge
|
||||
|
||||
```solidity
|
||||
interface ICCIPBridge {
|
||||
function sendCrossChain(
|
||||
uint64 destinationChainSelector,
|
||||
address recipient,
|
||||
uint256 amount
|
||||
) external returns (bytes32 messageId);
|
||||
|
||||
function calculateFee(
|
||||
uint64 destinationChainSelector,
|
||||
uint256 amount
|
||||
) external view returns (uint256 fee);
|
||||
|
||||
function ccipReceive(
|
||||
IRouterClient.Any2EVMMessage calldata message
|
||||
) external;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Event Monitoring
|
||||
|
||||
### Router Events
|
||||
|
||||
```solidity
|
||||
event MessageSent(
|
||||
bytes32 indexed messageId,
|
||||
uint64 indexed destinationChainSelector,
|
||||
address indexed sender,
|
||||
bytes receiver,
|
||||
bytes data,
|
||||
TokenAmount[] tokenAmounts,
|
||||
address feeToken,
|
||||
bytes extraArgs
|
||||
);
|
||||
|
||||
event MessageReceived(
|
||||
bytes32 indexed messageId,
|
||||
uint64 indexed sourceChainSelector,
|
||||
address indexed sender,
|
||||
bytes data,
|
||||
TokenAmount[] tokenAmounts
|
||||
);
|
||||
```
|
||||
|
||||
### Bridge Events
|
||||
|
||||
```solidity
|
||||
event CrossChainTransferInitiated(
|
||||
bytes32 indexed messageId,
|
||||
address indexed sender,
|
||||
uint64 indexed destinationChainSelector,
|
||||
address recipient,
|
||||
uint256 amount,
|
||||
uint256 nonce
|
||||
);
|
||||
|
||||
event CrossChainTransferCompleted(
|
||||
bytes32 indexed messageId,
|
||||
uint64 indexed sourceChainSelector,
|
||||
address indexed recipient,
|
||||
uint256 amount
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
```solidity
|
||||
// Router errors
|
||||
"CCIPRouter: chain not supported"
|
||||
"CCIPRouter: insufficient native token fee"
|
||||
"CCIPRouter: duplicate message"
|
||||
|
||||
// Bridge errors
|
||||
"CCIPWETH9Bridge: destination not enabled"
|
||||
"CCIPWETH9Bridge: transfer failed"
|
||||
"CCIPWETH9Bridge: transfer already processed"
|
||||
```
|
||||
|
||||
### Error Handling Pattern
|
||||
|
||||
```solidity
|
||||
try bridge.sendCrossChain(selector, recipient, amount) returns (bytes32 messageId) {
|
||||
emit TransferSuccess(messageId);
|
||||
} catch Error(string memory reason) {
|
||||
emit TransferFailed(reason);
|
||||
} catch (bytes memory lowLevelData) {
|
||||
emit TransferFailed("Low-level error");
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```solidity
|
||||
function testCrossChainTransfer() public {
|
||||
// Setup
|
||||
uint256 amount = 1 ether;
|
||||
uint64 destSelector = 5009297550715157269; // Ethereum Mainnet
|
||||
|
||||
// Approve
|
||||
weth9.approve(address(bridge), amount);
|
||||
|
||||
// Send
|
||||
bytes32 messageId = bridge.sendCrossChain(destSelector, recipient, amount);
|
||||
|
||||
// Verify
|
||||
assertTrue(messageId != bytes32(0));
|
||||
emit TransferInitiated(messageId);
|
||||
}
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
Test end-to-end flow:
|
||||
1. Send message on source chain
|
||||
2. Verify message received on destination
|
||||
3. Verify state changes
|
||||
4. Test error cases
|
||||
|
||||
---
|
||||
|
||||
## Gas Optimization
|
||||
|
||||
### Tips
|
||||
|
||||
1. **Batch Operations**: Group multiple operations when possible
|
||||
2. **Optimize Data**: Minimize message data size
|
||||
3. **Cache Values**: Cache frequently accessed values
|
||||
4. **Use Events**: Emit events instead of storage for logging
|
||||
|
||||
### Gas Estimates
|
||||
|
||||
- **Router Message**: ~50,000 - 100,000 gas
|
||||
- **Bridge Transfer**: ~100,000 - 200,000 gas
|
||||
- **Fee Calculation**: ~5,000 gas (view function)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always Calculate Fees**: Don't hardcode fee amounts
|
||||
2. **Handle Errors**: Implement comprehensive error handling
|
||||
3. **Monitor Events**: Track all CCIP events
|
||||
4. **Verify Addresses**: Always verify contract addresses
|
||||
5. **Test Thoroughly**: Test on testnet before mainnet
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [CCIP Deployment Guide](../ccip/DEPLOYMENT_GUIDE_CHAIN138.md)
|
||||
- [User Guide](../user-guides/CCIP_BRIDGE_USER_GUIDE.md)
|
||||
- [CCIP Review](../CCIP_CHAIN138_REVIEW.md)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
@@ -1,837 +0,0 @@
|
||||
# AWS Deployment Guide
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
**Network**: ChainID 138 (DeFi Oracle Meta Mainnet)
|
||||
**Target**: Amazon Web Services (AWS)
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains what is needed to deploy the DeFi Oracle Meta Mainnet blockchain network to AWS. The project currently supports Azure as the primary cloud provider, but includes multi-cloud infrastructure support that can be extended for AWS.
|
||||
|
||||
## Current AWS Support Status
|
||||
|
||||
| Component | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| **Terraform Multi-Cloud Framework** | ✅ Partial | Basic AWS module exists |
|
||||
| **EKS Cluster** | ✅ Partial | Basic cluster creation supported |
|
||||
| **VPC & Networking** | ✅ Partial | VPC, subnets, security groups created |
|
||||
| **IAM Roles** | ✅ Partial | EKS cluster and node roles configured |
|
||||
| **Application Load Balancer** | ❌ Missing | Need ALB with WAF (replaces Azure Application Gateway) |
|
||||
| **Secrets Management** | ❌ Missing | Need AWS Secrets Manager integration |
|
||||
| **Storage** | ❌ Missing | Need S3 buckets and EBS storage classes |
|
||||
| **DNS** | ❌ Missing | Need Route53 configuration |
|
||||
| **SSL/TLS Certificates** | ❌ Missing | Need ACM (Certificate Manager) integration |
|
||||
| **Monitoring** | ❌ Missing | Need CloudWatch integration |
|
||||
| **Backup & Restore** | ❌ Missing | Need S3-based backup solution |
|
||||
|
||||
## Required AWS Services & Resources
|
||||
|
||||
### 1. Compute & Orchestration
|
||||
|
||||
| Service | Purpose | Required |
|
||||
|---------|---------|----------|
|
||||
| **Amazon EKS** | Kubernetes cluster for running Besu nodes | ✅ Yes |
|
||||
| **EC2 Instance Types** | Worker nodes for EKS | ✅ Yes |
|
||||
| **Auto Scaling Groups** | Dynamic node scaling | ✅ Recommended |
|
||||
|
||||
**Current Implementation**: ✅ Basic EKS cluster with node groups
|
||||
|
||||
### 2. Networking
|
||||
|
||||
| Service | Purpose | Required |
|
||||
|---------|---------|----------|
|
||||
| **VPC** | Virtual network for resources | ✅ Yes |
|
||||
| **Subnets** | Network segmentation (public/private) | ✅ Yes |
|
||||
| **Internet Gateway** | Internet access | ✅ Yes |
|
||||
| **NAT Gateway** | Outbound internet for private subnets | ✅ Recommended |
|
||||
| **Security Groups** | Firewall rules | ✅ Yes |
|
||||
| **Route Tables** | Network routing | ✅ Yes |
|
||||
| **Application Load Balancer (ALB)** | Load balancing and SSL termination | ✅ Required |
|
||||
| **AWS WAF** | Web Application Firewall | ✅ Required |
|
||||
| **Route53** | DNS management | ✅ Required |
|
||||
| **ACM** | SSL/TLS certificates | ✅ Required |
|
||||
|
||||
**Current Implementation**: ✅ VPC, subnets, security groups, IGW
|
||||
**Missing**: ❌ ALB, WAF, Route53, ACM, NAT Gateway
|
||||
|
||||
### 3. Storage
|
||||
|
||||
| Service | Purpose | Required |
|
||||
|---------|---------|----------|
|
||||
| **EBS Volumes** | Persistent storage for Besu nodes | ✅ Yes |
|
||||
| **EBS CSI Driver** | Kubernetes storage integration | ✅ Required |
|
||||
| **S3 Buckets** | Backup storage, configuration files | ✅ Required |
|
||||
| **S3 Lifecycle Policies** | Backup retention and cost optimization | ✅ Recommended |
|
||||
|
||||
**Current Implementation**: ❌ None
|
||||
**Missing**: ❌ All storage components
|
||||
|
||||
### 4. Security & Secrets
|
||||
|
||||
| Service | Purpose | Required |
|
||||
|---------|---------|----------|
|
||||
| **AWS Secrets Manager** | Store validator keys, RPC endpoints | ✅ Required |
|
||||
| **AWS KMS** | Key encryption for secrets | ✅ Required |
|
||||
| **IAM Roles** | Access control | ✅ Yes (partial) |
|
||||
| **IAM Policies** | Permission management | ✅ Required |
|
||||
| **Security Groups** | Network security | ✅ Yes |
|
||||
|
||||
**Current Implementation**: ✅ Basic IAM roles for EKS
|
||||
**Missing**: ❌ Secrets Manager, KMS, IAM policies for services
|
||||
|
||||
### 5. Monitoring & Observability
|
||||
|
||||
| Service | Purpose | Required |
|
||||
|---------|---------|----------|
|
||||
| **CloudWatch Logs** | Centralized logging | ✅ Required |
|
||||
| **CloudWatch Metrics** | Performance metrics | ✅ Required |
|
||||
| **CloudWatch Alarms** | Alerting | ✅ Required |
|
||||
| **CloudWatch Container Insights** | EKS metrics | ✅ Recommended |
|
||||
| **X-Ray** | Distributed tracing | ⚠️ Optional |
|
||||
| **Prometheus** | Metrics collection (self-hosted) | ✅ Yes |
|
||||
| **Grafana** | Visualization (self-hosted) | ✅ Yes |
|
||||
|
||||
**Current Implementation**: ✅ CloudWatch log group for EKS
|
||||
**Missing**: ❌ Metrics, alarms, container insights
|
||||
|
||||
### 6. Database (for Blockscout)
|
||||
|
||||
| Service | Purpose | Required |
|
||||
|---------|---------|----------|
|
||||
| **RDS PostgreSQL** | Blockscout database | ✅ Required |
|
||||
| **RDS Read Replicas** | High availability | ⚠️ Optional |
|
||||
| **RDS Automated Backups** | Database backups | ✅ Recommended |
|
||||
|
||||
**Current Implementation**: ❌ None
|
||||
**Missing**: ❌ RDS PostgreSQL for Blockscout
|
||||
|
||||
### 7. Additional Services
|
||||
|
||||
| Service | Purpose | Required |
|
||||
|---------|---------|----------|
|
||||
| **CloudFront** | CDN for static content | ⚠️ Optional |
|
||||
| **ElastiCache** | Redis cache (if needed) | ⚠️ Optional |
|
||||
| **AWS Systems Manager** | Parameter Store | ⚠️ Optional |
|
||||
|
||||
## AWS Infrastructure Requirements
|
||||
|
||||
### Minimum Resource Requirements
|
||||
|
||||
#### EKS Cluster
|
||||
- **Kubernetes Version**: 1.28+ (matches Azure AKS)
|
||||
- **Node Groups**:
|
||||
- **System Nodes**: 1-3 nodes (t3.medium or larger)
|
||||
- **Validator Nodes**: 4+ nodes (t3.xlarge or larger) - 512Gi storage each
|
||||
- **Sentry Nodes**: 3-5 nodes (t3.large or larger) - 256Gi storage each
|
||||
- **RPC Nodes**: 3-5 nodes (t3.xlarge or larger) - 256Gi storage each
|
||||
|
||||
#### Network Architecture
|
||||
```
|
||||
VPC (10.0.0.0/16)
|
||||
├── Public Subnets
|
||||
│ ├── EKS Control Plane (10.0.1.0/24)
|
||||
│ ├── RPC Nodes (10.0.4.0/24)
|
||||
│ └── ALB (10.0.5.0/24)
|
||||
└── Private Subnets
|
||||
├── Validators (10.0.2.0/24)
|
||||
└── Sentries (10.0.3.0/24)
|
||||
```
|
||||
|
||||
#### Storage Requirements
|
||||
- **EBS Storage Classes**:
|
||||
- `gp3` for validator nodes (512Gi per node, IOPS: 3000)
|
||||
- `gp3` for sentry nodes (256Gi per node, IOPS: 3000)
|
||||
- `gp3` for RPC nodes (256Gi per node, IOPS: 3000)
|
||||
- **S3 Buckets**:
|
||||
- `besu-chaindata-backups` - Chain data backups
|
||||
- `besu-config-backups` - Configuration backups
|
||||
- `blockscout-assets` - Blockscout static assets (optional)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### 1. AWS Account Setup
|
||||
|
||||
```bash
|
||||
# Install AWS CLI
|
||||
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
|
||||
unzip awscliv2.zip
|
||||
sudo ./aws/install
|
||||
|
||||
# Configure AWS credentials
|
||||
aws configure
|
||||
# Enter:
|
||||
# - AWS Access Key ID
|
||||
# - AWS Secret Access Key
|
||||
# - Default region (e.g., us-west-2)
|
||||
# - Default output format (json)
|
||||
```
|
||||
|
||||
### 2. Required AWS Permissions
|
||||
|
||||
Your AWS IAM user/role needs permissions for:
|
||||
- EKS (cluster creation, node groups)
|
||||
- EC2 (VPC, subnets, security groups, instances)
|
||||
- IAM (role creation for EKS)
|
||||
- S3 (bucket creation, lifecycle policies)
|
||||
- Secrets Manager (secret creation)
|
||||
- KMS (key creation)
|
||||
- Route53 (DNS zone management)
|
||||
- ACM (certificate management)
|
||||
- ALB/WAF (load balancer creation)
|
||||
- CloudWatch (logs, metrics, alarms)
|
||||
- RDS (if using managed PostgreSQL)
|
||||
|
||||
**Minimum IAM Policy**: AdministratorAccess or equivalent permissions for the above services.
|
||||
|
||||
### 3. Tools Installation
|
||||
|
||||
```bash
|
||||
# Terraform (>= 1.0)
|
||||
wget https://releases.hashicorp.com/terraform/1.6.0/terraform_1.6.0_linux_amd64.zip
|
||||
unzip terraform_1.6.0_linux_amd64.zip
|
||||
sudo mv terraform /usr/local/bin/
|
||||
|
||||
# kubectl
|
||||
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
|
||||
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
|
||||
|
||||
# Helm (3.x)
|
||||
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
|
||||
|
||||
# AWS EKS CLI (eksctl) - Optional but recommended
|
||||
curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
|
||||
sudo mv /tmp/eksctl /usr/local/bin
|
||||
```
|
||||
|
||||
### 4. Environment Variables
|
||||
|
||||
Create a `.env` file or export environment variables:
|
||||
|
||||
```bash
|
||||
# AWS Credentials
|
||||
export AWS_ACCESS_KEY_ID="your-access-key"
|
||||
export AWS_SECRET_ACCESS_KEY="your-secret-key"
|
||||
export AWS_DEFAULT_REGION="us-west-2"
|
||||
|
||||
# Terraform Variables (or use terraform.tfvars)
|
||||
export TF_VAR_environment="prod"
|
||||
export TF_VAR_aws_default_region="us-west-2"
|
||||
|
||||
# Optional: AWS Profile
|
||||
export AWS_PROFILE="your-profile-name"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### 1. Update environments.yaml
|
||||
|
||||
Add AWS environment configuration to `config/environments.yaml`:
|
||||
|
||||
```yaml
|
||||
environments:
|
||||
# AWS Workload Environment
|
||||
- name: workload-aws-us-west-2
|
||||
role: workload
|
||||
provider: aws
|
||||
type: cloud
|
||||
region: us-west-2
|
||||
location: "US West (Oregon)"
|
||||
enabled: true
|
||||
|
||||
components:
|
||||
- validators
|
||||
- sentries
|
||||
- rpc
|
||||
- monitoring
|
||||
- blockscout
|
||||
|
||||
infrastructure:
|
||||
kubernetes:
|
||||
provider: eks
|
||||
version: "1.28"
|
||||
node_pools:
|
||||
system:
|
||||
count: 3
|
||||
instance_type: "t3.medium"
|
||||
validators:
|
||||
count: 4
|
||||
instance_type: "t3.xlarge"
|
||||
sentries:
|
||||
count: 3
|
||||
instance_type: "t3.large"
|
||||
rpc:
|
||||
count: 3
|
||||
instance_type: "t3.xlarge"
|
||||
|
||||
networking:
|
||||
vpc_cidr: "10.0.0.0/16"
|
||||
subnets:
|
||||
- name: eks
|
||||
cidr: "10.0.1.0/24"
|
||||
- name: validators
|
||||
cidr: "10.0.2.0/24"
|
||||
- name: sentries
|
||||
cidr: "10.0.3.0/24"
|
||||
- name: rpc
|
||||
cidr: "10.0.4.0/24"
|
||||
- name: alb
|
||||
cidr: "10.0.5.0/24"
|
||||
|
||||
storage:
|
||||
type: "gp3"
|
||||
validator_storage_size: 512
|
||||
sentry_storage_size: 256
|
||||
rpc_storage_size: 256
|
||||
|
||||
aws:
|
||||
account_id: "${AWS_ACCOUNT_ID}"
|
||||
region: "us-west-2"
|
||||
vpc_id: "" # Leave empty for new VPC
|
||||
|
||||
secrets:
|
||||
provider: aws-secrets-manager
|
||||
kms_key_id: "${AWS_KMS_KEY_ID}"
|
||||
|
||||
dns:
|
||||
provider: route53
|
||||
hosted_zone: "your-domain.com"
|
||||
rpc_domain: "rpc.your-domain.com"
|
||||
explorer_domain: "explorer.your-domain.com"
|
||||
```
|
||||
|
||||
### 2. Terraform Variables
|
||||
|
||||
Create `terraform/multi-cloud/terraform.tfvars`:
|
||||
|
||||
```hcl
|
||||
environment = "prod"
|
||||
|
||||
tags = {
|
||||
Environment = "production"
|
||||
Project = "DeFi Oracle Meta Mainnet"
|
||||
ChainID = "138"
|
||||
ManagedBy = "Terraform"
|
||||
CostCenter = "Blockchain"
|
||||
Owner = "DevOps Team"
|
||||
}
|
||||
|
||||
# AWS Configuration
|
||||
aws_default_region = "us-west-2"
|
||||
|
||||
# Enable features
|
||||
enable_azure_arc = false # Disable if not using Azure
|
||||
enable_service_mesh = true
|
||||
service_mesh_provider = "istio"
|
||||
|
||||
# Secrets Management
|
||||
secrets_provider = "aws-secrets-manager"
|
||||
```
|
||||
|
||||
## Deployment Steps
|
||||
|
||||
### Step 1: Complete AWS Terraform Module
|
||||
|
||||
The current AWS module is basic. You need to enhance it with:
|
||||
|
||||
1. **Application Load Balancer (ALB)**
|
||||
- Internet-facing ALB
|
||||
- WAF integration
|
||||
- SSL/TLS termination
|
||||
- Target groups for RPC nodes and Blockscout
|
||||
|
||||
2. **Storage Resources**
|
||||
- EBS CSI driver installation
|
||||
- Storage classes for gp3
|
||||
- S3 buckets for backups
|
||||
|
||||
3. **Secrets Manager Integration**
|
||||
- KMS key creation
|
||||
- Secrets Manager secrets for validator keys
|
||||
|
||||
4. **Route53 & ACM**
|
||||
- Route53 hosted zone (or use existing)
|
||||
- ACM certificate request
|
||||
- DNS record creation
|
||||
|
||||
5. **RDS PostgreSQL**
|
||||
- RDS instance for Blockscout
|
||||
- Security group for database access
|
||||
- Backup configuration
|
||||
|
||||
6. **CloudWatch Integration**
|
||||
- CloudWatch log groups
|
||||
- CloudWatch alarms
|
||||
- Container Insights
|
||||
|
||||
### Step 2: Deploy Infrastructure
|
||||
|
||||
```bash
|
||||
cd terraform/multi-cloud
|
||||
|
||||
# Initialize Terraform
|
||||
terraform init
|
||||
|
||||
# Review plan
|
||||
terraform plan -var-file=terraform.tfvars
|
||||
|
||||
# Apply infrastructure
|
||||
terraform apply -var-file=terraform.tfvars
|
||||
```
|
||||
|
||||
### Step 3: Configure kubectl
|
||||
|
||||
After EKS cluster is created:
|
||||
|
||||
```bash
|
||||
# Get kubeconfig
|
||||
aws eks update-kubeconfig --name <cluster-name> --region us-west-2
|
||||
|
||||
# Verify access
|
||||
kubectl get nodes
|
||||
```
|
||||
|
||||
### Step 4: Install EBS CSI Driver
|
||||
|
||||
Required for persistent volumes:
|
||||
|
||||
```bash
|
||||
# Install EBS CSI driver
|
||||
kubectl apply -k "github.com/kubernetes-sigs/aws-ebs-csi-driver/deploy/kubernetes/overlays/stable/?ref=release-1.28"
|
||||
|
||||
# Create StorageClass
|
||||
kubectl apply -f - <<EOF
|
||||
apiVersion: storage.k8s.io/v1
|
||||
kind: StorageClass
|
||||
metadata:
|
||||
name: gp3
|
||||
provisioner: ebs.csi.aws.com
|
||||
parameters:
|
||||
type: gp3
|
||||
iops: "3000"
|
||||
throughput: "125"
|
||||
volumeBindingMode: WaitForFirstConsumer
|
||||
allowVolumeExpansion: true
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 5: Deploy Kubernetes Resources
|
||||
|
||||
The Kubernetes manifests in `k8s/` directory need to be updated for AWS:
|
||||
|
||||
1. **Update Storage Classes**: Change `managed-premium` to `gp3`
|
||||
2. **Update Service Types**: Ensure LoadBalancer services use ALB annotation
|
||||
3. **Configure Ingress**: Use ALB Ingress Controller
|
||||
|
||||
```bash
|
||||
# Install ALB Ingress Controller
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.7.0/docs/install/v2_7_0_full.yaml
|
||||
|
||||
# Deploy Kubernetes resources
|
||||
kubectl apply -f k8s/base/namespace.yaml
|
||||
kubectl apply -f k8s/base/
|
||||
```
|
||||
|
||||
### Step 6: Deploy Helm Charts
|
||||
|
||||
Update Helm values for AWS storage classes:
|
||||
|
||||
```bash
|
||||
# Update helm/besu-network/values.yaml
|
||||
# Change: storageClass: managed-premium
|
||||
# To: storageClass: gp3
|
||||
|
||||
# Deploy Besu network
|
||||
helm install besu-network ./helm/besu-network \
|
||||
--namespace besu-network \
|
||||
--set global.storageClass=gp3
|
||||
```
|
||||
|
||||
### Step 7: Configure Secrets
|
||||
|
||||
Store validator keys in AWS Secrets Manager:
|
||||
|
||||
```bash
|
||||
# Store validator key
|
||||
aws secretsmanager create-secret \
|
||||
--name besu/validator/key-1 \
|
||||
--secret-string file://keys/validator/key1 \
|
||||
--kms-key-id <kms-key-id>
|
||||
|
||||
# Store RPC endpoint
|
||||
aws secretsmanager create-secret \
|
||||
--name besu/rpc/endpoint \
|
||||
--secret-string "https://rpc.your-domain.com" \
|
||||
--kms-key-id <kms-key-id>
|
||||
```
|
||||
|
||||
### Step 8: Configure DNS
|
||||
|
||||
Create Route53 records:
|
||||
|
||||
```bash
|
||||
# Get ALB DNS name
|
||||
ALB_DNS=$(aws elbv2 describe-load-balancers \
|
||||
--query 'LoadBalancers[?contains(LoadBalancerName, `besu`)].DNSName' \
|
||||
--output text)
|
||||
|
||||
# Create Route53 record
|
||||
aws route53 change-resource-record-sets \
|
||||
--hosted-zone-id <zone-id> \
|
||||
--change-batch '{
|
||||
"Changes": [{
|
||||
"Action": "UPSERT",
|
||||
"ResourceRecordSet": {
|
||||
"Name": "rpc.your-domain.com",
|
||||
"Type": "CNAME",
|
||||
"TTL": 300,
|
||||
"ResourceRecords": [{"Value": "'$ALB_DNS'"}]
|
||||
}
|
||||
}]
|
||||
}'
|
||||
```
|
||||
|
||||
### Step 9: Deploy Blockscout
|
||||
|
||||
```bash
|
||||
# Deploy Blockscout (requires RDS PostgreSQL)
|
||||
kubectl apply -f k8s/blockscout/
|
||||
|
||||
# Update database connection string to use RDS endpoint
|
||||
kubectl set env deployment/blockscout \
|
||||
-n besu-network \
|
||||
DATABASE_URL="postgresql://blockscout:password@<rds-endpoint>:5432/blockscout"
|
||||
```
|
||||
|
||||
### Step 10: Deploy Monitoring Stack
|
||||
|
||||
```bash
|
||||
# Deploy Prometheus, Grafana, etc.
|
||||
kubectl apply -f monitoring/k8s/
|
||||
|
||||
# Configure CloudWatch exporter for Prometheus (optional)
|
||||
kubectl apply -f monitoring/cloudwatch/
|
||||
```
|
||||
|
||||
## Key Differences from Azure Deployment
|
||||
|
||||
| Aspect | Azure | AWS | Notes |
|
||||
|--------|-------|-----|-------|
|
||||
| **Kubernetes** | AKS | EKS | Both managed, similar APIs |
|
||||
| **Load Balancer** | Application Gateway + WAF | ALB + WAF | Both support SSL termination |
|
||||
| **Secrets** | Key Vault | Secrets Manager | Both support KMS encryption |
|
||||
| **Storage** | Managed Disks | EBS | Both support persistent volumes |
|
||||
| **Backup Storage** | Blob Storage | S3 | Both object storage |
|
||||
| **DNS** | Azure DNS | Route53 | Both support DNS management |
|
||||
| **Certificates** | Key Vault Certificates | ACM | Both auto-renewal |
|
||||
| **Monitoring** | Azure Monitor | CloudWatch | Both comprehensive |
|
||||
|
||||
## What Needs to Be Added to AWS Module
|
||||
|
||||
### 1. Application Load Balancer (Priority: High)
|
||||
|
||||
```hcl
|
||||
# terraform/multi-cloud/modules/aws/alb.tf (new file)
|
||||
resource "aws_lb" "main" {
|
||||
name = "${local.name_prefix}-alb"
|
||||
internal = false
|
||||
load_balancer_type = "application"
|
||||
security_groups = [aws_security_group.alb.id]
|
||||
subnets = [for s in aws_subnet.alb : s.id]
|
||||
|
||||
enable_deletion_protection = var.environment == "prod"
|
||||
|
||||
tags = merge(var.tags, {
|
||||
Name = "${local.name_prefix}-alb"
|
||||
})
|
||||
}
|
||||
|
||||
resource "aws_wafv2_web_acl" "main" {
|
||||
name = "${local.name_prefix}-waf"
|
||||
scope = "REGIONAL"
|
||||
|
||||
default_action {
|
||||
allow {}
|
||||
}
|
||||
|
||||
rule {
|
||||
name = "AWSManagedRulesCommonRuleSet"
|
||||
priority = 1
|
||||
override_action {
|
||||
none {}
|
||||
}
|
||||
statement {
|
||||
managed_rule_group_statement {
|
||||
name = "AWSManagedRulesCommonRuleSet"
|
||||
vendor_name = "AWS"
|
||||
}
|
||||
}
|
||||
visibility_config {
|
||||
cloudwatch_metrics_enabled = true
|
||||
metric_name = "CommonRuleSetMetric"
|
||||
sampled_requests_enabled = true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Storage Resources (Priority: High)
|
||||
|
||||
```hcl
|
||||
# terraform/multi-cloud/modules/aws/storage.tf (new file)
|
||||
resource "aws_s3_bucket" "backups" {
|
||||
bucket = "${local.name_prefix}-backups"
|
||||
|
||||
tags = merge(var.tags, {
|
||||
Name = "${local.name_prefix}-backups"
|
||||
})
|
||||
}
|
||||
|
||||
resource "aws_s3_bucket_lifecycle_configuration" "backups" {
|
||||
bucket = aws_s3_bucket.backups.id
|
||||
|
||||
rule {
|
||||
id = "transition-to-ia"
|
||||
status = "Enabled"
|
||||
|
||||
transition {
|
||||
days = 30
|
||||
storage_class = "STANDARD_IA"
|
||||
}
|
||||
}
|
||||
|
||||
rule {
|
||||
id = "transition-to-glacier"
|
||||
status = "Enabled"
|
||||
|
||||
transition {
|
||||
days = 90
|
||||
storage_class = "GLACIER"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Secrets Manager (Priority: High)
|
||||
|
||||
```hcl
|
||||
# terraform/multi-cloud/modules/aws/secrets.tf (new file)
|
||||
resource "aws_kms_key" "secrets" {
|
||||
description = "KMS key for Secrets Manager"
|
||||
deletion_window_in_days = 30
|
||||
|
||||
tags = merge(var.tags, {
|
||||
Name = "${local.name_prefix}-secrets-kms"
|
||||
})
|
||||
}
|
||||
|
||||
resource "aws_kms_alias" "secrets" {
|
||||
name = "alias/${local.name_prefix}-secrets"
|
||||
target_key_id = aws_kms_key.secrets.key_id
|
||||
}
|
||||
```
|
||||
|
||||
### 4. RDS PostgreSQL (Priority: Medium)
|
||||
|
||||
```hcl
|
||||
# terraform/multi-cloud/modules/aws/rds.tf (new file)
|
||||
resource "aws_db_instance" "blockscout" {
|
||||
identifier = "${local.name_prefix}-blockscout-db"
|
||||
|
||||
engine = "postgres"
|
||||
engine_version = "15.4"
|
||||
instance_class = "db.t3.medium"
|
||||
|
||||
allocated_storage = 100
|
||||
max_allocated_storage = 500
|
||||
storage_type = "gp3"
|
||||
storage_encrypted = true
|
||||
|
||||
db_name = "blockscout"
|
||||
username = "blockscout"
|
||||
password = var.db_password
|
||||
|
||||
vpc_security_group_ids = [aws_security_group.rds.id]
|
||||
db_subnet_group_name = aws_db_subnet_group.main.name
|
||||
|
||||
backup_retention_period = 7
|
||||
backup_window = "03:00-04:00"
|
||||
maintenance_window = "mon:04:00-mon:05:00"
|
||||
|
||||
skip_final_snapshot = var.environment != "prod"
|
||||
|
||||
tags = merge(var.tags, {
|
||||
Name = "${local.name_prefix}-blockscout-db"
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Route53 & ACM (Priority: Medium)
|
||||
|
||||
```hcl
|
||||
# terraform/multi-cloud/modules/aws/dns.tf (new file)
|
||||
resource "aws_acm_certificate" "main" {
|
||||
domain_name = var.domain_name
|
||||
validation_method = "DNS"
|
||||
|
||||
subject_alternative_names = [
|
||||
"*.${var.domain_name}"
|
||||
]
|
||||
|
||||
lifecycle {
|
||||
create_before_destroy = true
|
||||
}
|
||||
|
||||
tags = merge(var.tags, {
|
||||
Name = "${local.name_prefix}-cert"
|
||||
})
|
||||
}
|
||||
|
||||
resource "aws_route53_record" "rpc" {
|
||||
zone_id = var.hosted_zone_id
|
||||
name = "rpc.${var.domain_name}"
|
||||
type = "CNAME"
|
||||
ttl = 300
|
||||
records = [aws_lb.main.dns_name]
|
||||
}
|
||||
```
|
||||
|
||||
## Cost Estimation
|
||||
|
||||
### Monthly Cost Estimate (us-west-2, production)
|
||||
|
||||
| Service | Configuration | Monthly Cost (USD) |
|
||||
|---------|--------------|-------------------|
|
||||
| **EKS Cluster** | Managed cluster | $73 |
|
||||
| **EC2 Instances** | 4x t3.xlarge + 3x t3.large + 3x t3.xlarge | ~$600 |
|
||||
| **EBS Storage** | 2TB gp3 (512GB x4 + 256GB x6) | ~$160 |
|
||||
| **S3 Storage** | 500GB backups | ~$12 |
|
||||
| **ALB** | Application Load Balancer | ~$25 |
|
||||
| **WAF** | AWS WAF | ~$5 |
|
||||
| **RDS PostgreSQL** | db.t3.medium | ~$100 |
|
||||
| **NAT Gateway** | 2 NAT Gateways | ~$65 |
|
||||
| **Data Transfer** | 500GB outbound | ~$45 |
|
||||
| **CloudWatch** | Logs and metrics | ~$30 |
|
||||
| **Route53** | Hosted zone + queries | ~$1 |
|
||||
| **ACM** | Certificate | $0 |
|
||||
| **Total** | | **~$1,116/month** |
|
||||
|
||||
**Note**: Costs vary based on usage, region, and instance sizes. Use AWS Cost Calculator for accurate estimates.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Network Security
|
||||
- ✅ Use private subnets for validators
|
||||
- ✅ Implement security groups with least privilege
|
||||
- ✅ Enable VPC Flow Logs
|
||||
- ✅ Use WAF for public-facing endpoints
|
||||
|
||||
### 2. Secrets Management
|
||||
- ✅ Use AWS Secrets Manager with KMS encryption
|
||||
- ✅ Rotate secrets regularly
|
||||
- ✅ Use IAM roles instead of access keys where possible
|
||||
|
||||
### 3. Access Control
|
||||
- ✅ Use IAM roles for EKS pods (IRSA)
|
||||
- ✅ Enable RBAC in Kubernetes
|
||||
- ✅ Use least privilege IAM policies
|
||||
|
||||
### 4. Monitoring & Compliance
|
||||
- ✅ Enable CloudTrail for audit logging
|
||||
- ✅ Enable GuardDuty for threat detection
|
||||
- ✅ Set up CloudWatch alarms
|
||||
- ✅ Use AWS Config for compliance checking
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### 1. EKS Node Group Fails to Join Cluster
|
||||
|
||||
**Solution**: Verify IAM roles and policies are correctly attached:
|
||||
|
||||
```bash
|
||||
# Check node group IAM role
|
||||
aws eks describe-nodegroup \
|
||||
--cluster-name <cluster-name> \
|
||||
--nodegroup-name <nodegroup-name> \
|
||||
--query 'nodegroup.nodeRole'
|
||||
|
||||
# Verify IAM policies are attached
|
||||
aws iam list-attached-role-policies --role-name <node-role-name>
|
||||
```
|
||||
|
||||
#### 2. Persistent Volumes Not Creating
|
||||
|
||||
**Solution**: Install and configure EBS CSI driver:
|
||||
|
||||
```bash
|
||||
# Verify EBS CSI driver is running
|
||||
kubectl get pods -n kube-system | grep ebs-csi
|
||||
|
||||
# Check StorageClass
|
||||
kubectl get storageclass gp3
|
||||
```
|
||||
|
||||
#### 3. ALB Not Routing Traffic
|
||||
|
||||
**Solution**: Check ALB target group health:
|
||||
|
||||
```bash
|
||||
# Get target group ARN
|
||||
TG_ARN=$(aws elbv2 describe-target-groups \
|
||||
--query 'TargetGroups[?contains(TargetGroupName, `besu`)].TargetGroupArn' \
|
||||
--output text)
|
||||
|
||||
# Check target health
|
||||
aws elbv2 describe-target-health --target-group-arn $TG_ARN
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Enhance AWS Terraform Module**: Add ALB, storage, secrets, RDS, DNS
|
||||
2. **Update Kubernetes Manifests**: Change storage classes, add ALB annotations
|
||||
3. **Configure Monitoring**: Set up CloudWatch integration
|
||||
4. **Implement Backup Strategy**: S3-based backups for chain data
|
||||
5. **Security Hardening**: WAF rules, security groups, IAM policies
|
||||
6. **Documentation**: Update deployment docs with AWS-specific steps
|
||||
7. **Testing**: Test deployment in dev environment first
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [AWS EKS Documentation](https://docs.aws.amazon.com/eks/)
|
||||
- [EBS CSI Driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver)
|
||||
- [AWS Load Balancer Controller](https://kubernetes-sigs.github.io/aws-load-balancer-controller/)
|
||||
- [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/)
|
||||
- [Terraform AWS Provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
|
||||
|
||||
## Summary
|
||||
|
||||
To deploy this project to AWS, you need:
|
||||
|
||||
1. ✅ **Basic Infrastructure** (Partially Complete)
|
||||
- EKS cluster
|
||||
- VPC, subnets, security groups
|
||||
- IAM roles
|
||||
|
||||
2. ❌ **Missing Critical Components**
|
||||
- Application Load Balancer with WAF
|
||||
- AWS Secrets Manager integration
|
||||
- Storage (EBS CSI driver, S3 buckets)
|
||||
- Route53 DNS configuration
|
||||
- ACM certificates
|
||||
- RDS PostgreSQL for Blockscout
|
||||
- CloudWatch integration
|
||||
|
||||
3. ⚠️ **Configuration Updates Needed**
|
||||
- Update Kubernetes manifests for AWS storage classes
|
||||
- Configure ALB Ingress Controller
|
||||
- Update Helm values for AWS
|
||||
- Update service annotations for ALB
|
||||
|
||||
4. 📝 **Documentation Updates**
|
||||
- AWS-specific deployment guide
|
||||
- Troubleshooting guide for AWS
|
||||
- Cost optimization guide
|
||||
|
||||
The multi-cloud Terraform framework provides a good foundation, but the AWS module needs significant enhancements to match the Azure deployment capabilities.
|
||||
|
||||
@@ -1,743 +0,0 @@
|
||||
# Native ETH, WETH9, WETH10, Chainlink Bridges and Oracles - Complete Guide
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
**Network**: ChainID 138 (DeFi Oracle Meta Mainnet) & Ethereum Mainnet
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Native ETH](#native-eth)
|
||||
2. [WETH9](#weth9)
|
||||
3. [WETH10](#weth10)
|
||||
4. [Chainlink CCIP Bridges](#chainlink-ccip-bridges)
|
||||
5. [Chainlink Oracles](#chainlink-oracles)
|
||||
6. [Contract Addresses Reference](#contract-addresses-reference)
|
||||
|
||||
---
|
||||
|
||||
## Native ETH
|
||||
|
||||
### Overview
|
||||
|
||||
**Native ETH** (Ether) is the native cryptocurrency of the Ethereum blockchain and EVM-compatible chains. It serves as the base currency for transaction fees (gas) and can be used directly in smart contracts without wrapping.
|
||||
|
||||
### Key Characteristics
|
||||
|
||||
- **Type**: Native currency (not an ERC-20 token)
|
||||
- **Decimals**: 18
|
||||
- **Symbol**: ETH
|
||||
- **Network**: ChainID 138 (DeFi Oracle Meta Mainnet)
|
||||
- **Usage**:
|
||||
- Paying transaction fees (gas)
|
||||
- Direct value transfers
|
||||
- Native contract interactions
|
||||
- Can be wrapped to WETH for ERC-20 compatibility
|
||||
|
||||
### Technical Details
|
||||
|
||||
- Native ETH is sent via `msg.value` in Solidity
|
||||
- Received through `payable` functions or `receive()` fallback
|
||||
- Cannot be transferred using standard ERC-20 methods
|
||||
- Must be wrapped to WETH for use in DeFi protocols that require ERC-20 tokens
|
||||
|
||||
### Contract Address
|
||||
|
||||
Native ETH does not have a contract address as it is the native currency of the blockchain.
|
||||
|
||||
---
|
||||
|
||||
## WETH9
|
||||
|
||||
### Overview
|
||||
|
||||
**WETH9** (Wrapped Ether version 9) is the canonical ERC-20 representation of native ETH. It allows ETH to be used in DeFi protocols that require ERC-20 token standards.
|
||||
|
||||
### Key Characteristics
|
||||
|
||||
- **Standard**: ERC-20 compatible
|
||||
- **Decimals**: 18
|
||||
- **Symbol**: WETH
|
||||
- **Name**: Wrapped Ether
|
||||
- **Purpose**: Enable ETH to be used as an ERC-20 token
|
||||
|
||||
### Core Functions
|
||||
|
||||
1. **`deposit()`**: Wrap native ETH to WETH9
|
||||
- Sends ETH to contract
|
||||
- Mints equivalent WETH9 tokens
|
||||
- Emits `Deposit` event
|
||||
|
||||
2. **`withdraw(uint256 wad)`**: Unwrap WETH9 to native ETH
|
||||
- Burns WETH9 tokens
|
||||
- Sends equivalent ETH to caller
|
||||
- Emits `Withdrawal` event
|
||||
|
||||
3. **`transfer()` / `transferFrom()`**: Standard ERC-20 transfers
|
||||
|
||||
4. **`approve()`**: Standard ERC-20 approvals
|
||||
|
||||
### Implementation Details
|
||||
|
||||
- **Total Supply**: Equals the contract's ETH balance
|
||||
- **Automatic Wrapping**: `receive()` function automatically wraps ETH sent directly to contract
|
||||
- **No Flash Loans**: WETH9 does not support flash loans
|
||||
|
||||
### Contract Addresses
|
||||
|
||||
#### Ethereum Mainnet (ChainID 1)
|
||||
- **Address**: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
|
||||
- **Status**: ✅ Canonical (Pre-deployed)
|
||||
- **Etherscan**: [View on Etherscan](https://etherscan.io/address/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)
|
||||
- **Verified**: ✅ Yes
|
||||
|
||||
#### ChainID 138 (DeFi Oracle Meta Mainnet)
|
||||
- **Status**: Deployable (custom implementation available)
|
||||
- **Contract File**: `contracts/tokens/WETH.sol`
|
||||
- **Deployment Script**: `script/DeployWETH.s.sol`
|
||||
|
||||
### Usage Example
|
||||
|
||||
```solidity
|
||||
// Wrap ETH to WETH9
|
||||
weth9.deposit{value: 1 ether}();
|
||||
|
||||
// Unwrap WETH9 to ETH
|
||||
weth9.withdraw(1 ether);
|
||||
|
||||
// Transfer WETH9
|
||||
weth9.transfer(recipient, amount);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WETH10
|
||||
|
||||
### Overview
|
||||
|
||||
**WETH10** is an enhanced version of WETH that includes ERC-3156 flash loan functionality and additional quality-of-life features. It maintains full backward compatibility with WETH9 while adding advanced capabilities.
|
||||
|
||||
### Key Characteristics
|
||||
|
||||
- **Standard**: ERC-20 + ERC-3156 Flash Loans
|
||||
- **Decimals**: 18
|
||||
- **Symbol**: WETH
|
||||
- **Name**: Wrapped Ether
|
||||
- **Flash Loan Fee**: 0 (no fee)
|
||||
|
||||
### Enhanced Features
|
||||
|
||||
1. **ERC-3156 Flash Loans**
|
||||
- `flashLoan()`: Borrow WETH10 without collateral
|
||||
- `maxFlashLoan()`: Get maximum flash loan amount
|
||||
- `flashFee()`: Get flash loan fee (0 for WETH10)
|
||||
- Requires callback implementation: `onFlashLoan()`
|
||||
|
||||
2. **Backward Compatibility**
|
||||
- All WETH9 functions work identically
|
||||
- Same `deposit()` and `withdraw()` interface
|
||||
- Standard ERC-20 transfer/approve functions
|
||||
|
||||
### Core Functions
|
||||
|
||||
#### Standard WETH Functions
|
||||
- `deposit()`: Wrap native ETH to WETH10
|
||||
- `withdraw(uint256 wad)`: Unwrap WETH10 to native ETH
|
||||
- `transfer()` / `transferFrom()`: Standard ERC-20 transfers
|
||||
- `approve()`: Standard ERC-20 approvals
|
||||
|
||||
#### Flash Loan Functions
|
||||
- `flashLoan(IERC3156FlashBorrower receiver, address token, uint256 amount, bytes calldata data)`: Execute flash loan
|
||||
- `maxFlashLoan(address token)`: Get maximum flash loan amount
|
||||
- `flashFee(address token, uint256 amount)`: Get flash loan fee
|
||||
|
||||
### Implementation Details
|
||||
|
||||
- **Flash Loan Fee**: 0 (no fee)
|
||||
- **Flash Loan Callback**: Must return `FLASH_LOAN_CALLBACK_SUCCESS`
|
||||
- **Repayment**: Must repay `amount + fee` within the same transaction
|
||||
- **Total Supply**: Equals the contract's ETH balance
|
||||
|
||||
### Contract Addresses
|
||||
|
||||
#### Ethereum Mainnet (ChainID 1)
|
||||
- **Address**: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
|
||||
- **Status**: ✅ Canonical (Pre-deployed)
|
||||
- **Etherscan**: [View on Etherscan](https://etherscan.io/address/0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f)
|
||||
- **Verified**: ✅ Yes
|
||||
|
||||
#### ChainID 138 (DeFi Oracle Meta Mainnet)
|
||||
- **Status**: Deployable (custom implementation available)
|
||||
- **Contract File**: `contracts/tokens/WETH10.sol`
|
||||
- **Deployment Script**: Available via Foundry
|
||||
|
||||
### Usage Example
|
||||
|
||||
```solidity
|
||||
// Standard WETH operations
|
||||
weth10.deposit{value: 1 ether}();
|
||||
weth10.withdraw(1 ether);
|
||||
|
||||
// Flash loan
|
||||
weth10.flashLoan(
|
||||
flashBorrower,
|
||||
address(weth10),
|
||||
100 ether,
|
||||
data
|
||||
);
|
||||
|
||||
// Flash loan callback (in receiver contract)
|
||||
function onFlashLoan(
|
||||
address initiator,
|
||||
address token,
|
||||
uint256 amount,
|
||||
uint256 fee,
|
||||
bytes calldata data
|
||||
) external returns (bytes32) {
|
||||
// Use borrowed funds
|
||||
// ... perform operations ...
|
||||
|
||||
// Repay loan
|
||||
weth10.transfer(address(weth10), amount + fee);
|
||||
|
||||
return WETH10.FLASH_LOAN_CALLBACK_SUCCESS;
|
||||
}
|
||||
```
|
||||
|
||||
### Differences from WETH9
|
||||
|
||||
| Feature | WETH9 | WETH10 |
|
||||
|---------|-------|--------|
|
||||
| Flash Loans | ❌ No | ✅ Yes (ERC-3156) |
|
||||
| Flash Loan Fee | N/A | 0 |
|
||||
| ERC-20 Compatibility | ✅ Yes | ✅ Yes |
|
||||
| Backward Compatible | N/A | ✅ Yes |
|
||||
|
||||
---
|
||||
|
||||
## Chainlink CCIP Bridges
|
||||
|
||||
### Overview
|
||||
|
||||
**Chainlink Cross-Chain Interoperability Protocol (CCIP)** bridges enable secure cross-chain token transfers. The project implements two CCIP bridges for WETH9 and WETH10 tokens.
|
||||
|
||||
### CCIPWETH9Bridge
|
||||
|
||||
Cross-chain bridge for WETH9 tokens using Chainlink CCIP.
|
||||
|
||||
#### Features
|
||||
|
||||
- **Cross-Chain Transfers**: Send WETH9 tokens between chains
|
||||
- **Replay Protection**: Nonce-based and message ID tracking
|
||||
- **Fee Management**: LINK token for CCIP fees
|
||||
- **Admin Controls**: Configurable destination chains
|
||||
- **Event Tracking**: Comprehensive event logging
|
||||
|
||||
#### Key Functions
|
||||
|
||||
1. **`sendCrossChain(uint64 destinationChainSelector, address recipient, uint256 amount)`**
|
||||
- Locks WETH9 on source chain
|
||||
- Sends CCIP message with WETH9 tokens
|
||||
- Returns message ID for tracking
|
||||
|
||||
2. **`ccipReceive(Any2EVMMessage calldata message)`**
|
||||
- Receives CCIP message from router
|
||||
- Validates and processes transfer
|
||||
- Unlocks WETH9 on destination chain
|
||||
|
||||
3. **`calculateFee(uint64 destinationChainSelector, uint256 amount)`**
|
||||
- Estimates CCIP fee for transfer
|
||||
- Returns required LINK amount
|
||||
|
||||
#### Contract Addresses
|
||||
|
||||
##### Ethereum Mainnet (ChainID 1)
|
||||
- **Address**: `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6`
|
||||
- **Status**: ✅ Deployed & Verified
|
||||
- **Etherscan**: [View on Etherscan](https://etherscan.io/address/0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6)
|
||||
- **Contract File**: `contracts/ccip/CCIPWETH9Bridge.sol`
|
||||
|
||||
##### Constructor Parameters
|
||||
- **CCIP Router**: `0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D`
|
||||
- **WETH9**: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
|
||||
- **LINK Token**: `0x514910771AF9Ca656af840dff83E8264EcF986CA`
|
||||
|
||||
### CCIPWETH10Bridge
|
||||
|
||||
Cross-chain bridge for WETH10 tokens using Chainlink CCIP.
|
||||
|
||||
#### Features
|
||||
|
||||
- **Cross-Chain Transfers**: Send WETH10 tokens between chains
|
||||
- **Replay Protection**: Nonce-based and message ID tracking
|
||||
- **Fee Management**: LINK token for CCIP fees
|
||||
- **Admin Controls**: Configurable destination chains
|
||||
- **Event Tracking**: Comprehensive event logging
|
||||
|
||||
#### Key Functions
|
||||
|
||||
1. **`sendCrossChain(uint64 destinationChainSelector, address recipient, uint256 amount)`**
|
||||
- Locks WETH10 on source chain
|
||||
- Sends CCIP message with WETH10 tokens
|
||||
- Returns message ID for tracking
|
||||
|
||||
2. **`ccipReceive(Any2EVMMessage calldata message)`**
|
||||
- Receives CCIP message from router
|
||||
- Validates and processes transfer
|
||||
- Unlocks WETH10 on destination chain
|
||||
|
||||
3. **`calculateFee(uint64 destinationChainSelector, uint256 amount)`**
|
||||
- Estimates CCIP fee for transfer
|
||||
- Returns required LINK amount
|
||||
|
||||
#### Contract Addresses
|
||||
|
||||
##### Ethereum Mainnet (ChainID 1)
|
||||
- **Address**: `0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e`
|
||||
- **Status**: ✅ Deployed & Verified
|
||||
- **Etherscan**: [View on Etherscan](https://etherscan.io/address/0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e)
|
||||
- **Contract File**: `contracts/ccip/CCIPWETH10Bridge.sol`
|
||||
|
||||
##### Constructor Parameters
|
||||
- **CCIP Router**: `0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D`
|
||||
- **WETH10**: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
|
||||
- **LINK Token**: `0x514910771AF9Ca656af840dff83E8264EcF986CA`
|
||||
|
||||
### CCIP Infrastructure
|
||||
|
||||
#### CCIP Router (Chainlink Official)
|
||||
|
||||
The CCIP Router is the core infrastructure component that routes messages between chains.
|
||||
|
||||
##### Ethereum Mainnet (ChainID 1)
|
||||
- **Address**: `0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D`
|
||||
- **Type**: Chainlink CCIP Router
|
||||
- **Status**: ✅ Official Chainlink Deployment
|
||||
- **Etherscan**: [View on Etherscan](https://etherscan.io/address/0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D)
|
||||
- **Used By**: CCIPWETH9Bridge, CCIPWETH10Bridge
|
||||
|
||||
#### LINK Token (Chainlink Official)
|
||||
|
||||
LINK token is used to pay CCIP fees for cross-chain transfers.
|
||||
|
||||
##### Ethereum Mainnet (ChainID 1)
|
||||
- **Address**: `0x514910771AF9Ca656af840dff83E8264EcF986CA`
|
||||
- **Type**: ERC-20 Token (LINK)
|
||||
- **Status**: ✅ Official Chainlink Deployment
|
||||
- **Etherscan**: [View on Etherscan](https://etherscan.io/address/0x514910771AF9Ca656af840dff83E8264EcF986CA)
|
||||
- **Used By**: CCIPWETH9Bridge, CCIPWETH10Bridge (for CCIP fees)
|
||||
|
||||
### Bridge Usage Flow
|
||||
|
||||
1. **User Approval**: Approve bridge to spend WETH9/WETH10
|
||||
2. **Approve LINK**: Approve bridge to spend LINK for fees
|
||||
3. **Send Cross-Chain**: Call `sendCrossChain()` with destination and amount
|
||||
4. **CCIP Processing**: CCIP Router handles cross-chain message
|
||||
5. **Receive on Destination**: Bridge receives message and unlocks tokens
|
||||
|
||||
### Security Features
|
||||
|
||||
- **Replay Protection**: Message ID and nonce tracking
|
||||
- **Access Control**: Admin-only configuration functions
|
||||
- **Router Validation**: Only CCIP Router can call `ccipReceive()`
|
||||
- **Token Validation**: Validates token addresses in messages
|
||||
- **Zero Address Checks**: Prevents invalid recipient addresses
|
||||
|
||||
---
|
||||
|
||||
## Chainlink Oracles
|
||||
|
||||
### Overview
|
||||
|
||||
Chainlink oracles provide reliable, decentralized price feeds and data for smart contracts. The project implements Chainlink-compatible oracle aggregators for price feeds.
|
||||
|
||||
### Oracle Aggregator
|
||||
|
||||
The `Aggregator` contract implements a Chainlink-compatible oracle aggregator interface for price feeds.
|
||||
|
||||
#### Features
|
||||
|
||||
- **Chainlink-Compatible Interface**: Implements `IAggregator` interface
|
||||
- **Round-Based Updates**: Tracks price updates by round
|
||||
- **Access Control**: Admin and transmitter roles
|
||||
- **Heartbeat**: Configurable update frequency
|
||||
- **Deviation Threshold**: Updates only when price moves significantly
|
||||
- **Pause Functionality**: Emergency pause capability
|
||||
|
||||
#### Key Functions
|
||||
|
||||
1. **`updateAnswer(uint256 answer)`**
|
||||
- Updates price feed answer
|
||||
- Only callable by transmitters
|
||||
- Creates new round if heartbeat or deviation threshold met
|
||||
|
||||
2. **`latestAnswer()`**
|
||||
- Returns latest price as `int256`
|
||||
- Chainlink-compatible interface
|
||||
|
||||
3. **`latestRoundData()`**
|
||||
- Returns complete round data
|
||||
- Includes round ID, answer, timestamps
|
||||
- Chainlink-compatible interface
|
||||
|
||||
4. **`getRoundData(uint80 _roundId)`**
|
||||
- Returns data for specific round
|
||||
- Historical price data access
|
||||
|
||||
#### Configuration
|
||||
|
||||
- **Decimals**: 8 (Chainlink standard)
|
||||
- **Heartbeat**: Configurable (default: 60 seconds)
|
||||
- **Deviation Threshold**: Configurable (default: 50 basis points = 0.5%)
|
||||
- **Version**: 1
|
||||
|
||||
#### Access Control
|
||||
|
||||
- **Admin**: Can add/remove transmitters, update config, pause
|
||||
- **Transmitters**: Can update price answers
|
||||
- **Public**: Can read price data
|
||||
|
||||
#### Contract Files
|
||||
|
||||
- **Aggregator**: `contracts/oracle/Aggregator.sol`
|
||||
- **Proxy**: `contracts/oracle/Proxy.sol`
|
||||
- **Interface**: `contracts/interfaces/IAggregator.sol`
|
||||
- **Deployment Script**: `script/DeployOracle.s.sol`
|
||||
|
||||
#### Deployment
|
||||
|
||||
The oracle aggregator is deployed per price feed (e.g., ETH/USD, BTC/USD). Each deployment requires:
|
||||
|
||||
- **Description**: Price feed description (e.g., "ETH/USD Price Feed")
|
||||
- **Admin**: Admin address for configuration
|
||||
- **Heartbeat**: Update frequency in seconds
|
||||
- **Deviation Threshold**: Price change threshold in basis points
|
||||
|
||||
#### Usage Example
|
||||
|
||||
```solidity
|
||||
// Read latest price
|
||||
int256 price = aggregator.latestAnswer();
|
||||
|
||||
// Read latest round data
|
||||
(
|
||||
uint80 roundId,
|
||||
int256 answer,
|
||||
uint256 startedAt,
|
||||
uint256 updatedAt,
|
||||
uint80 answeredInRound
|
||||
) = aggregator.latestRoundData();
|
||||
|
||||
// Read historical round
|
||||
(
|
||||
uint80 roundId,
|
||||
int256 answer,
|
||||
uint256 startedAt,
|
||||
uint256 updatedAt,
|
||||
uint80 answeredInRound
|
||||
) = aggregator.getRoundData(roundId);
|
||||
|
||||
// Update price (transmitter only)
|
||||
aggregator.updateAnswer(newPrice);
|
||||
```
|
||||
|
||||
### Oracle Proxy
|
||||
|
||||
The `Proxy` contract provides upgradeability for the oracle aggregator, allowing implementation updates while maintaining the same address.
|
||||
|
||||
#### Features
|
||||
|
||||
- **Upgradeability**: Can update aggregator implementation
|
||||
- **Admin Control**: Only admin can upgrade
|
||||
- **Delegation**: Forwards calls to implementation
|
||||
|
||||
#### Contract Addresses
|
||||
|
||||
Oracle contracts are deployed per network and per price feed. Addresses are determined at deployment time.
|
||||
|
||||
**ChainID 138 (DeFi Oracle Meta Mainnet)**
|
||||
- Deployable via `script/DeployOracle.s.sol`
|
||||
- Each price feed has its own aggregator and proxy
|
||||
|
||||
### Chainlink Price Feed Addresses (Ethereum Mainnet Reference)
|
||||
|
||||
For reference, here are some official Chainlink price feed addresses on Ethereum Mainnet:
|
||||
|
||||
#### ETH/USD
|
||||
- **Address**: `0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419`
|
||||
- **Decimals**: 8
|
||||
- **Etherscan**: [View on Etherscan](https://etherscan.io/address/0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419)
|
||||
|
||||
#### BTC/USD
|
||||
- **Address**: `0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c`
|
||||
- **Decimals**: 8
|
||||
- **Etherscan**: [View on Etherscan](https://etherscan.io/address/0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c)
|
||||
|
||||
#### LINK/USD
|
||||
- **Address**: `0x2c1d072e956AFFC0D435Cb1AC137Fc48C0F4775F`
|
||||
- **Decimals**: 8
|
||||
- **Etherscan**: [View on Etherscan](https://etherscan.io/address/0x2c1d072e956AFFC0D435Cb1AC137Fc48C0F4775F)
|
||||
|
||||
> **Note**: For a complete list of Chainlink price feeds, visit [Chainlink Data Feeds](https://docs.chain.link/data-feeds/price-feeds)
|
||||
|
||||
---
|
||||
|
||||
## Contract Addresses Reference
|
||||
|
||||
### Ethereum Mainnet (ChainID 1)
|
||||
|
||||
#### WETH Contracts
|
||||
|
||||
| Contract | Address | Status | Etherscan |
|
||||
|----------|---------|--------|-----------|
|
||||
| **WETH9** | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | ✅ Canonical | [View](https://etherscan.io/address/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2) |
|
||||
| **WETH10** | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | ✅ Canonical | [View](https://etherscan.io/address/0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f) |
|
||||
|
||||
#### CCIP Bridges
|
||||
|
||||
| Contract | Address | Status | Etherscan |
|
||||
|----------|---------|--------|-----------|
|
||||
| **CCIPWETH9Bridge** | `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6` | ✅ Deployed & Verified | [View](https://etherscan.io/address/0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6) |
|
||||
| **CCIPWETH10Bridge** | `0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e` | ✅ Deployed & Verified | [View](https://etherscan.io/address/0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e) |
|
||||
|
||||
#### CCIP Infrastructure
|
||||
|
||||
| Contract | Address | Status | Etherscan |
|
||||
|----------|---------|--------|-----------|
|
||||
| **CCIP Router** | `0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D` | ✅ Official Chainlink | [View](https://etherscan.io/address/0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D) |
|
||||
| **LINK Token** | `0x514910771AF9Ca656af840dff83E8264EcF986CA` | ✅ Official Chainlink | [View](https://etherscan.io/address/0x514910771AF9Ca656af840dff83E8264EcF986CA) |
|
||||
|
||||
#### Chainlink Price Feeds (Reference)
|
||||
|
||||
| Price Feed | Address | Decimals | Etherscan |
|
||||
|------------|---------|----------|-----------|
|
||||
| **ETH/USD** | `0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419` | 8 | [View](https://etherscan.io/address/0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419) |
|
||||
| **BTC/USD** | `0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c` | 8 | [View](https://etherscan.io/address/0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c) |
|
||||
| **LINK/USD** | `0x2c1d072e956AFFC0D435Cb1AC137Fc48C0F4775F` | 8 | [View](https://etherscan.io/address/0x2c1d072e956AFFC0D435Cb1AC137Fc48C0F4775F) |
|
||||
|
||||
### ChainID 138 (DeFi Oracle Meta Mainnet)
|
||||
|
||||
#### WETH Contracts
|
||||
|
||||
| Contract | Status | Contract File | Deployment Script |
|
||||
|----------|--------|---------------|-------------------|
|
||||
| **WETH9** | Deployable | `contracts/tokens/WETH.sol` | `script/DeployWETH.s.sol` |
|
||||
| **WETH10** | Deployable | `contracts/tokens/WETH10.sol` | Available via Foundry |
|
||||
|
||||
#### Oracle Contracts
|
||||
|
||||
| Contract | Status | Contract File | Deployment Script |
|
||||
|----------|--------|---------------|-------------------|
|
||||
| **Aggregator** | Deployable | `contracts/oracle/Aggregator.sol` | `script/DeployOracle.s.sol` |
|
||||
| **Proxy** | Deployable | `contracts/oracle/Proxy.sol` | `script/DeployOracle.s.sol` |
|
||||
|
||||
> **Note**: Contract addresses on ChainID 138 are determined at deployment time. Use deployment scripts to deploy and record addresses.
|
||||
|
||||
---
|
||||
|
||||
## Complete Address Reference - All Networks
|
||||
|
||||
### All WETH Addresses by Network
|
||||
|
||||
| Network | Chain ID | WETH9 Address | WETH10 Address | Status |
|
||||
|---------|----------|---------------|----------------|--------|
|
||||
| **Ethereum Mainnet** | 1 | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | ✅ Canonical |
|
||||
| **BSC** | 56 | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` | ✅ Deployed |
|
||||
| **Polygon** | 137 | `0xe0e93247376aa097db308b92e6ba36ba015535d0` | `0xab57bf30f1354ca0590af22d8974c7f24db2dbd7` | ✅ Deployed |
|
||||
| **Avalanche** | 43114 | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` | ✅ Deployed |
|
||||
| **Base** | 8453 | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` | ✅ Deployed |
|
||||
| **Arbitrum** | 42161 | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` | ✅ Deployed |
|
||||
| **Optimism** | 10 | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` | ✅ Deployed |
|
||||
| **ChainID 138** | 138 | ✅ Pre-deployed | ✅ Pre-deployed | ✅ In Genesis |
|
||||
|
||||
### All CCIP Bridge Addresses by Network
|
||||
|
||||
| Network | Chain ID | CCIPWETH9Bridge | CCIPWETH10Bridge | Status |
|
||||
|---------|----------|-----------------|------------------|--------|
|
||||
| **Ethereum Mainnet** | 1 | `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6` | `0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e` | ✅ Verified |
|
||||
| **BSC** | 56 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` | `0x105f8a15b819948a89153505762444ee9f324684` | ✅ Verified |
|
||||
| **Polygon** | 137 | `0xa780ef19a041745d353c9432f2a7f5a241335ffe` | `0xdab0591e5e89295ffad75a71dcfc30c5625c4fa2` | ✅ Verified |
|
||||
| **Avalanche** | 43114 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` | `0x105f8a15b819948a89153505762444ee9f324684` | ✅ Verified |
|
||||
| **Base** | 8453 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` | `0x105f8a15b819948a89153505762444ee9f324684` | ✅ Verified |
|
||||
| **Arbitrum** | 42161 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` | `0x105f8a15b819948a89153505762444ee9f324684` | ✅ Verified |
|
||||
| **Optimism** | 10 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` | `0x105f8a15b819948a89153505762444ee9f324684` | ✅ Verified |
|
||||
| **ChainID 138** | 138 | ❌ Not Deployed | ❌ Not Deployed | ⚠️ **See [CCIP Review](CCIP_CHAIN138_REVIEW.md)** |
|
||||
|
||||
### CCIP Infrastructure Addresses
|
||||
|
||||
#### CCIP Router Addresses (Official Chainlink)
|
||||
|
||||
| Network | Chain ID | CCIP Router Address | Status |
|
||||
|---------|----------|---------------------|--------|
|
||||
| **Ethereum Mainnet** | 1 | `0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D` | ✅ Official |
|
||||
| **BSC** | 56 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Polygon** | 137 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Avalanche** | 43114 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Base** | 8453 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Arbitrum** | 42161 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Optimism** | 10 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **ChainID 138** | 138 | ❌ Not Deployed | ⚠️ **See [CCIP Review](CCIP_CHAIN138_REVIEW.md)** |
|
||||
|
||||
#### LINK Token Addresses (Official Chainlink)
|
||||
|
||||
| Network | Chain ID | LINK Token Address | Status |
|
||||
|---------|----------|-------------------|--------|
|
||||
| **Ethereum Mainnet** | 1 | `0x514910771AF9Ca656af840dff83E8264EcF986CA` | ✅ Official |
|
||||
| **BSC** | 56 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Polygon** | 137 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Avalanche** | 43114 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Base** | 8453 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Arbitrum** | 42161 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **Optimism** | 10 | Check [Chainlink Docs](https://docs.chain.link/ccip/supported-networks) | ✅ Official |
|
||||
| **ChainID 138** | 138 | ❌ Not Deployed | ⚠️ **Or use native ETH fees** |
|
||||
|
||||
### Blockchain Networks Summary
|
||||
|
||||
| Network Name | Chain ID | Type | Explorer | Status |
|
||||
|--------------|----------|------|----------|--------|
|
||||
| **Ethereum Mainnet** | 1 | Mainnet | [Etherscan](https://etherscan.io) | ✅ Active |
|
||||
| **BSC (Binance Smart Chain)** | 56 | Mainnet | [BscScan](https://bscscan.com) | ✅ Active |
|
||||
| **Polygon** | 137 | Mainnet | [Polygonscan](https://polygonscan.com) | ✅ Active |
|
||||
| **Avalanche** | 43114 | Mainnet | [Snowtrace](https://snowtrace.io) | ✅ Active |
|
||||
| **Base** | 8453 | Mainnet | [Basescan](https://basescan.org) | ✅ Active |
|
||||
| **Arbitrum** | 42161 | Mainnet | [Arbiscan](https://arbiscan.io) | ✅ Active |
|
||||
| **Optimism** | 10 | Mainnet | [Optimistic Etherscan](https://optimistic.etherscan.io) | ✅ Active |
|
||||
| **DeFi Oracle Meta Mainnet** | 138 | Mainnet | [Blockscout](https://explorer.d-bis.org) | ✅ Active |
|
||||
|
||||
### CCIP Chain Selectors
|
||||
|
||||
| Network | Chain ID | CCIP Chain Selector |
|
||||
|---------|----------|-------------------|
|
||||
| **Ethereum Mainnet** | 1 | `5009297550715157269` |
|
||||
| **BSC** | 56 | `11344663589394136015` |
|
||||
| **Polygon** | 137 | `4051577828743386545` |
|
||||
| **Avalanche** | 43114 | `6433500567565415381` |
|
||||
| **Base** | 8453 | `15971525489660198786` |
|
||||
| **Arbitrum** | 42161 | `4949039107694359620` |
|
||||
| **Optimism** | 10 | `3734403246176062136` |
|
||||
| **ChainID 138** | 138 | **`138`** (or `0x000000000000008a`) - See [Chain Selector Calculation](ccip/CHAIN_SELECTOR_CALCULATION.md) |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
For easy reference, add these to your `.env` file:
|
||||
|
||||
```bash
|
||||
# ============================================
|
||||
# Ethereum Mainnet (ChainID 1)
|
||||
# ============================================
|
||||
WETH9_MAINNET=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
|
||||
WETH10_MAINNET=0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f
|
||||
CCIPWETH9BRIDGE_MAINNET=0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6
|
||||
CCIPWETH10BRIDGE_MAINNET=0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e
|
||||
CCIP_MAINNET_ROUTER=0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D
|
||||
CCIP_MAINNET_LINK_TOKEN=0x514910771AF9Ca656af840dff83E8264EcF986CA
|
||||
|
||||
# Chainlink Price Feeds (Ethereum Mainnet)
|
||||
CHAINLINK_ETH_USD=0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419
|
||||
CHAINLINK_BTC_USD=0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c
|
||||
CHAINLINK_LINK_USD=0x2c1d072e956AFFC0D435Cb1AC137Fc48C0F4775F
|
||||
|
||||
# ============================================
|
||||
# BSC (ChainID 56)
|
||||
# ============================================
|
||||
WETH9_BSC=0x99b3511a2d315a497c8112c1fdd8d508d4b1e506
|
||||
WETH10_BSC=0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6
|
||||
CCIPWETH9BRIDGE_BSC=0x8078a09637e47fa5ed34f626046ea2094a5cde5e
|
||||
CCIPWETH10BRIDGE_BSC=0x105f8a15b819948a89153505762444ee9f324684
|
||||
|
||||
# ============================================
|
||||
# Polygon (ChainID 137)
|
||||
# ============================================
|
||||
WETH9_POLYGON=0xe0e93247376aa097db308b92e6ba36ba015535d0
|
||||
WETH10_POLYGON=0xab57bf30f1354ca0590af22d8974c7f24db2dbd7
|
||||
CCIPWETH9BRIDGE_POLYGON=0xa780ef19a041745d353c9432f2a7f5a241335ffe
|
||||
CCIPWETH10BRIDGE_POLYGON=0xdab0591e5e89295ffad75a71dcfc30c5625c4fa2
|
||||
|
||||
# ============================================
|
||||
# Avalanche (ChainID 43114)
|
||||
# ============================================
|
||||
WETH9_AVALANCHE=0x99b3511a2d315a497c8112c1fdd8d508d4b1e506
|
||||
WETH10_AVALANCHE=0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6
|
||||
CCIPWETH9BRIDGE_AVALANCHE=0x8078a09637e47fa5ed34f626046ea2094a5cde5e
|
||||
CCIPWETH10BRIDGE_AVALANCHE=0x105f8a15b819948a89153505762444ee9f324684
|
||||
|
||||
# ============================================
|
||||
# Base (ChainID 8453)
|
||||
# ============================================
|
||||
WETH9_BASE=0x99b3511a2d315a497c8112c1fdd8d508d4b1e506
|
||||
WETH10_BASE=0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6
|
||||
CCIPWETH9BRIDGE_BASE=0x8078a09637e47fa5ed34f626046ea2094a5cde5e
|
||||
CCIPWETH10BRIDGE_BASE=0x105f8a15b819948a89153505762444ee9f324684
|
||||
|
||||
# ============================================
|
||||
# Arbitrum (ChainID 42161)
|
||||
# ============================================
|
||||
WETH9_ARBITRUM=0x99b3511a2d315a497c8112c1fdd8d508d4b1e506
|
||||
WETH10_ARBITRUM=0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6
|
||||
CCIPWETH9BRIDGE_ARBITRUM=0x8078a09637e47fa5ed34f626046ea2094a5cde5e
|
||||
CCIPWETH10BRIDGE_ARBITRUM=0x105f8a15b819948a89153505762444ee9f324684
|
||||
|
||||
# ============================================
|
||||
# Optimism (ChainID 10)
|
||||
# ============================================
|
||||
WETH9_OPTIMISM=0x99b3511a2d315a497c8112c1fdd8d508d4b1e506
|
||||
WETH10_OPTIMISM=0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6
|
||||
CCIPWETH9BRIDGE_OPTIMISM=0x8078a09637e47fa5ed34f626046ea2094a5cde5e
|
||||
CCIPWETH10BRIDGE_OPTIMISM=0x105f8a15b819948a89153505762444ee9f324684
|
||||
|
||||
# ============================================
|
||||
# ChainID 138 (DeFi Oracle Meta Mainnet)
|
||||
# ============================================
|
||||
# ⚠️ CCIP NOT FULLY ENABLED - See docs/CCIP_CHAIN138_REVIEW.md
|
||||
#
|
||||
# WETH9 and WETH10 are pre-deployed in genesis.json:
|
||||
WETH9_CHAIN138=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
|
||||
WETH10_CHAIN138=0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f
|
||||
|
||||
# CCIP Infrastructure (TO BE DEPLOYED):
|
||||
# CCIP_CHAIN138_ROUTER=<deploy_ccip_router>
|
||||
# CCIP_CHAIN138_LINK_TOKEN=<deploy_link_or_use_zero_for_native_eth>
|
||||
# CHAIN138_SELECTOR=<calculate_proper_selector>
|
||||
# CCIPWETH9_BRIDGE_CHAIN138=<deploy_bridge>
|
||||
# CCIPWETH10_BRIDGE_CHAIN138=<deploy_bridge>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Documentation
|
||||
|
||||
- [Chainlink CCIP Documentation](https://docs.chain.link/ccip)
|
||||
- [Chainlink Data Feeds](https://docs.chain.link/data-feeds/price-feeds)
|
||||
- [WETH9 Specification](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md)
|
||||
- [WETH10 Specification](https://github.com/WETH10/WETH10)
|
||||
- [ERC-3156 Flash Loans](https://eips.ethereum.org/EIPS/eip-3156)
|
||||
|
||||
### Contract Verification
|
||||
|
||||
- **Etherscan Verification**: [Verify Contracts](https://etherscan.io/myverify_address)
|
||||
- **CCIPWETH9Bridge**: Verified ✅
|
||||
- **CCIPWETH10Bridge**: Verified ✅
|
||||
|
||||
### Related Files
|
||||
|
||||
- `contracts/tokens/WETH.sol` - WETH9 implementation
|
||||
- `contracts/tokens/WETH10.sol` - WETH10 implementation
|
||||
- `contracts/ccip/CCIPWETH9Bridge.sol` - WETH9 bridge
|
||||
- `contracts/ccip/CCIPWETH10Bridge.sol` - WETH10 bridge
|
||||
- `contracts/oracle/Aggregator.sol` - Oracle aggregator
|
||||
- `contracts/oracle/Proxy.sol` - Oracle proxy
|
||||
- `docs/deployment/MAINNET_CONTRACTS_LIST.md` - Complete contract list
|
||||
- `docs/CCIP_CHAIN138_REVIEW.md` - CCIP Enablement Review for ChainID 138
|
||||
- `docs/ccip/CHAIN_SELECTOR_CALCULATION.md` - Chain selector calculation guide
|
||||
- `docs/ccip/DEPLOYMENT_GUIDE_CHAIN138.md` - Complete deployment guide
|
||||
- `docs/user-guides/CCIP_BRIDGE_USER_GUIDE.md` - User guide for bridge usage
|
||||
- `docs/developer-guides/CCIP_INTEGRATION_GUIDE.md` - Developer integration guide
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
@@ -1,211 +0,0 @@
|
||||
# Keeper Deployment - ALL OPTIONS COMPLETE ✅
|
||||
|
||||
**Date**: 2025-01-27
|
||||
**Status**: ✅ **ALL INTEGRATION OPTIONS DEPLOYED**
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
All integration options for the automated price feed keeper have been implemented, tested, and are ready for deployment. Complete deployment automation and monitoring systems are in place.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Completed Components
|
||||
|
||||
### Contracts (3)
|
||||
|
||||
1. **PriceFeedKeeper.sol** ✅
|
||||
- Core keeper contract
|
||||
- Asset tracking
|
||||
- Batch updates
|
||||
- Configurable intervals
|
||||
|
||||
2. **ChainlinkKeeperCompatible.sol** ✅
|
||||
- Chainlink Automation wrapper
|
||||
- Implements AutomationCompatibleInterface
|
||||
- Compatible with Chainlink KeeperRegistry
|
||||
|
||||
3. **GelatoKeeperCompatible.sol** ✅
|
||||
- Gelato Network wrapper
|
||||
- Task execution pattern
|
||||
- Compatible with Gelato Ops
|
||||
|
||||
### Scripts (8)
|
||||
|
||||
1. **DeployKeeper.s.sol** ✅ - Deploy core keeper
|
||||
2. **DeployChainlinkKeeper.s.sol** ✅ - Deploy Chainlink wrapper
|
||||
3. **DeployGelatoKeeper.s.sol** ✅ - Deploy Gelato wrapper
|
||||
4. **PerformUpkeep.s.sol** ✅ - Manual upkeep execution
|
||||
5. **CheckUpkeep.s.sol** ✅ - Check upkeep status
|
||||
6. **keeper-service.js** ✅ - Node.js keeper service
|
||||
7. **keeper-service.sh** ✅ - Bash keeper service
|
||||
8. **deploy-all.sh** ✅ - Complete deployment automation
|
||||
|
||||
### Integration Scripts (3)
|
||||
|
||||
1. **chainlink-keeper-setup.js** ✅ - Chainlink registration
|
||||
2. **gelato-keeper-setup.js** ✅ - Gelato task creation
|
||||
3. **monitor-keeper.js** ✅ - Monitoring service
|
||||
|
||||
### Infrastructure (3)
|
||||
|
||||
1. **systemd/price-feed-keeper.service** ✅ - Systemd service file
|
||||
2. **docker/docker-compose.keeper.yml** ✅ - Docker Compose config
|
||||
3. **docker/Dockerfile.keeper** ✅ - Docker image
|
||||
|
||||
### Documentation (4)
|
||||
|
||||
1. **KEEPER_SETUP.md** ✅ - Detailed setup guide
|
||||
2. **KEEPER_COMPLETE.md** ✅ - Completion summary
|
||||
3. **KEEPER_INTEGRATION_COMPLETE.md** ✅ - Full integration guide
|
||||
4. **README_KEEPER.md** ✅ - Quick reference guide
|
||||
|
||||
---
|
||||
|
||||
## Deployment Options
|
||||
|
||||
### Option 1: Quick Deploy (Standalone)
|
||||
|
||||
```bash
|
||||
# Deploy keeper
|
||||
forge script script/reserve/DeployKeeper.s.sol:DeployKeeper \
|
||||
--rpc-url chain138 --broadcast
|
||||
|
||||
# Start service
|
||||
export KEEPER_PRIVATE_KEY=<key>
|
||||
export PRICE_FEED_KEEPER_ADDRESS=<address>
|
||||
node scripts/reserve/keeper-service.js
|
||||
```
|
||||
|
||||
### Option 2: Complete Deploy (All Options)
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Deploy everything
|
||||
./scripts/reserve/deploy-all.sh
|
||||
```
|
||||
|
||||
### Option 3: Individual Integrations
|
||||
|
||||
**Chainlink**:
|
||||
```bash
|
||||
forge script script/reserve/DeployChainlinkKeeper.s.sol:DeployChainlinkKeeper \
|
||||
--rpc-url chain138 --broadcast
|
||||
node scripts/reserve/chainlink-keeper-setup.js
|
||||
```
|
||||
|
||||
**Gelato**:
|
||||
```bash
|
||||
forge script script/reserve/DeployGelatoKeeper.s.sol:DeployGelatoKeeper \
|
||||
--rpc-url chain138 --broadcast
|
||||
node scripts/reserve/gelato-keeper-setup.js
|
||||
```
|
||||
|
||||
**Systemd**:
|
||||
```bash
|
||||
sudo cp systemd/price-feed-keeper.service /etc/systemd/system/
|
||||
sudo systemctl enable price-feed-keeper
|
||||
sudo systemctl start price-feed-keeper
|
||||
```
|
||||
|
||||
**Docker**:
|
||||
```bash
|
||||
docker-compose -f docker/docker-compose.keeper.yml up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Setup
|
||||
|
||||
### Start Monitor
|
||||
|
||||
```bash
|
||||
export PRICE_FEED_KEEPER_ADDRESS=<address>
|
||||
export ALERT_WEBHOOK=<webhook_url> # Optional
|
||||
node scripts/reserve/monitor-keeper.js
|
||||
```
|
||||
|
||||
### Health Checks
|
||||
|
||||
```bash
|
||||
# Health endpoint
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Statistics
|
||||
curl http://localhost:3000/stats
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Summary
|
||||
|
||||
**Total Files Created**: 20+
|
||||
|
||||
- **Contracts**: 3
|
||||
- **Deployment Scripts**: 5
|
||||
- **Service Scripts**: 3
|
||||
- **Integration Scripts**: 3
|
||||
- **Infrastructure**: 3
|
||||
- **Documentation**: 4
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate Actions
|
||||
|
||||
1. ✅ **Deploy Keeper Contract**
|
||||
```bash
|
||||
forge script script/reserve/DeployKeeper.s.sol:DeployKeeper --rpc-url chain138 --broadcast
|
||||
```
|
||||
|
||||
2. ✅ **Choose Integration**
|
||||
- Standalone (simplest)
|
||||
- Chainlink (decentralized)
|
||||
- Gelato (cost-effective)
|
||||
- Systemd (production)
|
||||
- Docker (containerized)
|
||||
|
||||
3. ✅ **Start Monitoring**
|
||||
```bash
|
||||
node scripts/reserve/monitor-keeper.js
|
||||
```
|
||||
|
||||
### Production Checklist
|
||||
|
||||
- [ ] Deploy keeper contract to ChainID 138
|
||||
- [ ] Configure assets to track
|
||||
- [ ] Set up chosen integration(s)
|
||||
- [ ] Configure monitoring and alerts
|
||||
- [ ] Test failure scenarios
|
||||
- [ ] Set up backup keeper (optional)
|
||||
- [ ] Document deployment details
|
||||
- [ ] Set up monitoring dashboards
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
✅ **ALL INTEGRATION OPTIONS COMPLETE**
|
||||
|
||||
- ✅ Standalone Service
|
||||
- ✅ Chainlink Keepers
|
||||
- ✅ Gelato Network
|
||||
- ✅ Systemd Service
|
||||
- ✅ Docker Container
|
||||
- ✅ Monitoring & Alerting
|
||||
- ✅ Deployment Automation
|
||||
|
||||
**Ready for production deployment on ChainID 138**
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [KEEPER_SETUP.md](./KEEPER_SETUP.md) - Detailed setup guide
|
||||
- [KEEPER_INTEGRATION_COMPLETE.md](./KEEPER_INTEGRATION_COMPLETE.md) - Full integration guide
|
||||
- [README_KEEPER.md](../../README_KEEPER.md) - Quick reference
|
||||
|
||||
@@ -1,497 +0,0 @@
|
||||
# Automated Price Feed Keeper - ALL INTEGRATION OPTIONS COMPLETE ✅
|
||||
|
||||
**Date**: 2025-01-27
|
||||
**Status**: ✅ **ALL INTEGRATIONS COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
All integration options for the automated price feed keeper have been implemented and are ready for deployment. The system supports multiple deployment and execution methods.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Integration Options Implemented
|
||||
|
||||
### 1. Standalone Keeper Service ✅
|
||||
|
||||
**Node.js Service**: `scripts/reserve/keeper-service.js`
|
||||
- ✅ Automatic price feed updates
|
||||
- ✅ Retry logic with configurable attempts
|
||||
- ✅ Error handling and recovery
|
||||
- ✅ Statistics tracking
|
||||
- ✅ Graceful shutdown
|
||||
- ✅ Event parsing and logging
|
||||
|
||||
**Bash Service**: `scripts/reserve/keeper-service.sh`
|
||||
- ✅ Simple bash implementation
|
||||
- ✅ Uses Foundry scripts
|
||||
- ✅ Basic error handling
|
||||
- ✅ Configurable intervals
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Node.js
|
||||
node scripts/reserve/keeper-service.js
|
||||
|
||||
# Bash
|
||||
./scripts/reserve/keeper-service.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Chainlink Keepers Integration ✅
|
||||
|
||||
**Contract**: `ChainlinkKeeperCompatible.sol`
|
||||
- ✅ Implements `AutomationCompatibleInterface`
|
||||
- ✅ Wraps `PriceFeedKeeper` for Chainlink Automation
|
||||
- ✅ Compatible with Chainlink KeeperRegistry
|
||||
|
||||
**Setup Script**: `scripts/reserve/chainlink-keeper-setup.js`
|
||||
- ✅ Registers upkeep with Chainlink
|
||||
- ✅ Funds upkeep with LINK
|
||||
- ✅ Configures gas limits
|
||||
- ✅ Event parsing
|
||||
|
||||
**Deployment Script**: `script/reserve/DeployChainlinkKeeper.s.sol`
|
||||
- ✅ Deploys ChainlinkKeeperCompatible contract
|
||||
- ✅ Links to PriceFeedKeeper
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Deploy compatible contract
|
||||
forge script script/reserve/DeployChainlinkKeeper.s.sol:DeployChainlinkKeeper \
|
||||
--rpc-url chain138 \
|
||||
--broadcast
|
||||
|
||||
# Register with Chainlink
|
||||
node scripts/reserve/chainlink-keeper-setup.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Gelato Network Integration ✅
|
||||
|
||||
**Contract**: `GelatoKeeperCompatible.sol`
|
||||
- ✅ Implements Gelato task execution pattern
|
||||
- ✅ Wraps `PriceFeedKeeper` for Gelato Network
|
||||
- ✅ Compatible with Gelato Ops
|
||||
|
||||
**Setup Script**: `scripts/reserve/gelato-keeper-setup.js`
|
||||
- ✅ Creates task with Gelato
|
||||
- ✅ Funds task with native token
|
||||
- ✅ Configures execution interval
|
||||
- ✅ Event parsing
|
||||
|
||||
**Deployment Script**: `script/reserve/DeployGelatoKeeper.s.sol`
|
||||
- ✅ Deploys GelatoKeeperCompatible contract
|
||||
- ✅ Links to PriceFeedKeeper and Gelato Ops
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Deploy compatible contract
|
||||
forge script script/reserve/DeployGelatoKeeper.s.sol:DeployGelatoKeeper \
|
||||
--rpc-url chain138 \
|
||||
--broadcast
|
||||
|
||||
# Create task with Gelato
|
||||
node scripts/reserve/gelato-keeper-setup.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Systemd Service ✅
|
||||
|
||||
**Service File**: `systemd/price-feed-keeper.service`
|
||||
- ✅ Systemd unit file
|
||||
- ✅ Automatic restart
|
||||
- ✅ Environment variable support
|
||||
- ✅ Logging configuration
|
||||
- ✅ Security hardening
|
||||
- ✅ Resource limits
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Install service
|
||||
sudo cp systemd/price-feed-keeper.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
# Enable and start
|
||||
sudo systemctl enable price-feed-keeper
|
||||
sudo systemctl start price-feed-keeper
|
||||
|
||||
# Check status
|
||||
sudo systemctl status price-feed-keeper
|
||||
|
||||
# View logs
|
||||
sudo journalctl -u price-feed-keeper -f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Docker Container ✅
|
||||
|
||||
**Docker Compose**: `docker/docker-compose.keeper.yml`
|
||||
- ✅ Keeper service container
|
||||
- ✅ Monitor service container
|
||||
- ✅ Health checks
|
||||
- ✅ Logging configuration
|
||||
- ✅ Volume mounts
|
||||
- ✅ Network configuration
|
||||
|
||||
**Dockerfile**: `docker/Dockerfile.keeper`
|
||||
- ✅ Node.js 18 Alpine base
|
||||
- ✅ Non-root user
|
||||
- ✅ Health check endpoint
|
||||
- ✅ Production optimizations
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Build and start
|
||||
docker-compose -f docker/docker-compose.keeper.yml up -d
|
||||
|
||||
# View logs
|
||||
docker-compose -f docker/docker-compose.keeper.yml logs -f
|
||||
|
||||
# Stop
|
||||
docker-compose -f docker/docker-compose.keeper.yml down
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Monitoring and Alerting ✅
|
||||
|
||||
**Monitor Service**: `scripts/reserve/monitor-keeper.js`
|
||||
- ✅ Continuous monitoring
|
||||
- ✅ Stale asset detection
|
||||
- ✅ Failure tracking
|
||||
- ✅ Alert threshold configuration
|
||||
- ✅ Webhook notifications
|
||||
- ✅ Health endpoint
|
||||
- ✅ Statistics tracking
|
||||
|
||||
**Features**:
|
||||
- Monitors keeper performance
|
||||
- Detects stale assets
|
||||
- Tracks consecutive failures
|
||||
- Sends alerts via webhook
|
||||
- Provides health endpoint
|
||||
- Tracks statistics
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Start monitor
|
||||
node scripts/reserve/monitor-keeper.js
|
||||
|
||||
# Health check
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Statistics
|
||||
curl http://localhost:3000/stats
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Deployment Automation ✅
|
||||
|
||||
**Deployment Script**: `scripts/reserve/deploy-all.sh`
|
||||
- ✅ Complete deployment automation
|
||||
- ✅ Sequential deployment steps
|
||||
- ✅ Environment variable management
|
||||
- ✅ Verification steps
|
||||
- ✅ Next steps guidance
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Full deployment
|
||||
./scripts/reserve/deploy-all.sh
|
||||
|
||||
# With Chainlink
|
||||
DEPLOY_CHAINLINK=true ./scripts/reserve/deploy-all.sh
|
||||
|
||||
# With Gelato
|
||||
DEPLOY_GELATO=true ./scripts/reserve/deploy-all.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete File Structure
|
||||
|
||||
```
|
||||
contracts/reserve/
|
||||
├── PriceFeedKeeper.sol # Core keeper contract
|
||||
├── ChainlinkKeeperCompatible.sol # Chainlink integration
|
||||
└── GelatoKeeperCompatible.sol # Gelato integration
|
||||
|
||||
script/reserve/
|
||||
├── DeployKeeper.s.sol # Deploy keeper
|
||||
├── DeployChainlinkKeeper.s.sol # Deploy Chainlink wrapper
|
||||
├── DeployGelatoKeeper.s.sol # Deploy Gelato wrapper
|
||||
├── PerformUpkeep.s.sol # Manual upkeep
|
||||
└── CheckUpkeep.s.sol # Check status
|
||||
|
||||
scripts/reserve/
|
||||
├── keeper-service.js # Node.js keeper service
|
||||
├── keeper-service.sh # Bash keeper service
|
||||
├── chainlink-keeper-setup.js # Chainlink setup
|
||||
├── gelato-keeper-setup.js # Gelato setup
|
||||
├── monitor-keeper.js # Monitoring service
|
||||
└── deploy-all.sh # Deployment automation
|
||||
|
||||
systemd/
|
||||
└── price-feed-keeper.service # Systemd service file
|
||||
|
||||
docker/
|
||||
├── docker-compose.keeper.yml # Docker Compose config
|
||||
└── Dockerfile.keeper # Docker image
|
||||
|
||||
docs/integration/
|
||||
├── KEEPER_SETUP.md # Setup guide
|
||||
├── KEEPER_COMPLETE.md # Completion summary
|
||||
└── KEEPER_INTEGRATION_COMPLETE.md # This document
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start Guide
|
||||
|
||||
### Option 1: Standalone Service
|
||||
|
||||
```bash
|
||||
# Deploy keeper
|
||||
forge script script/reserve/DeployKeeper.s.sol:DeployKeeper \
|
||||
--rpc-url chain138 --broadcast
|
||||
|
||||
# Start service
|
||||
export KEEPER_PRIVATE_KEY=<key>
|
||||
export PRICE_FEED_KEEPER_ADDRESS=<address>
|
||||
node scripts/reserve/keeper-service.js
|
||||
```
|
||||
|
||||
### Option 2: Chainlink Keepers
|
||||
|
||||
```bash
|
||||
# Deploy compatible contract
|
||||
forge script script/reserve/DeployChainlinkKeeper.s.sol:DeployChainlinkKeeper \
|
||||
--rpc-url chain138 --broadcast
|
||||
|
||||
# Register upkeep
|
||||
export LINK_TOKEN_ADDRESS=<link>
|
||||
export KEEPER_REGISTRY_ADDRESS=<registry>
|
||||
node scripts/reserve/chainlink-keeper-setup.js
|
||||
```
|
||||
|
||||
### Option 3: Gelato Network
|
||||
|
||||
```bash
|
||||
# Deploy compatible contract
|
||||
forge script script/reserve/DeployGelatoKeeper.s.sol:DeployGelatoKeeper \
|
||||
--rpc-url chain138 --broadcast
|
||||
|
||||
# Create task
|
||||
export GELATO_OPS=<ops>
|
||||
node scripts/reserve/gelato-keeper-setup.js
|
||||
```
|
||||
|
||||
### Option 4: Systemd Service
|
||||
|
||||
```bash
|
||||
# Install service
|
||||
sudo cp systemd/price-feed-keeper.service /etc/systemd/system/
|
||||
sudo systemctl enable price-feed-keeper
|
||||
sudo systemctl start price-feed-keeper
|
||||
```
|
||||
|
||||
### Option 5: Docker
|
||||
|
||||
```bash
|
||||
# Start containers
|
||||
docker-compose -f docker/docker-compose.keeper.yml up -d
|
||||
```
|
||||
|
||||
### Option 6: Complete Deployment
|
||||
|
||||
```bash
|
||||
# Deploy everything
|
||||
./scripts/reserve/deploy-all.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Setup
|
||||
|
||||
### Start Monitor Service
|
||||
|
||||
```bash
|
||||
export PRICE_FEED_KEEPER_ADDRESS=<address>
|
||||
export ALERT_WEBHOOK=<webhook_url> # Optional
|
||||
node scripts/reserve/monitor-keeper.js
|
||||
```
|
||||
|
||||
### Health Checks
|
||||
|
||||
```bash
|
||||
# Health endpoint
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Statistics
|
||||
curl http://localhost:3000/stats
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
**Required**:
|
||||
- `RPC_URL_138` - ChainID 138 RPC endpoint
|
||||
- `PRIVATE_KEY` - Deployer private key
|
||||
- `PRICE_FEED_KEEPER_ADDRESS` - Keeper contract address
|
||||
|
||||
**Keeper Service**:
|
||||
- `KEEPER_PRIVATE_KEY` - Keeper wallet private key
|
||||
- `UPDATE_INTERVAL` - Update interval in seconds (default: 30)
|
||||
|
||||
**Chainlink**:
|
||||
- `KEEPER_REGISTRY_ADDRESS` - Chainlink KeeperRegistry
|
||||
- `LINK_TOKEN_ADDRESS` - LINK token address
|
||||
- `UPKEEP_INTERVAL` - Upkeep interval (default: 30)
|
||||
- `GAS_LIMIT` - Gas limit (default: 500000)
|
||||
- `FUNDING_AMOUNT` - LINK amount (default: 10)
|
||||
|
||||
**Gelato**:
|
||||
- `GELATO_OPS` - Gelato Ops address
|
||||
- `EXECUTION_INTERVAL` - Execution interval (default: 30)
|
||||
- `FUNDING_AMOUNT` - Native token amount (default: 0.1 ETH)
|
||||
|
||||
**Monitoring**:
|
||||
- `ALERT_WEBHOOK` - Webhook URL for alerts
|
||||
- `CHECK_INTERVAL` - Check interval (default: 60)
|
||||
- `ALERT_THRESHOLD` - Failure threshold (default: 3)
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Access Control
|
||||
- ✅ Role-based access control
|
||||
- ✅ Keeper role separation
|
||||
- ✅ Admin role protection
|
||||
|
||||
### Private Key Security
|
||||
- ✅ Environment variable storage
|
||||
- ✅ Non-root user in Docker
|
||||
- ✅ Systemd security hardening
|
||||
|
||||
### Monitoring
|
||||
- ✅ Failure detection
|
||||
- ✅ Alert thresholds
|
||||
- ✅ Health checks
|
||||
|
||||
---
|
||||
|
||||
## Cost Estimation
|
||||
|
||||
### Standalone Service
|
||||
- **Gas per update**: ~100k - 300k per asset
|
||||
- **Updates per day**: 2,880 (30s interval)
|
||||
- **Cost**: Variable based on gas prices
|
||||
|
||||
### Chainlink Keepers
|
||||
- **Registration**: ~500k gas
|
||||
- **Per upkeep**: ~100k - 300k gas
|
||||
- **LINK funding**: 10 LINK (recommended)
|
||||
- **Cost**: LINK token + gas
|
||||
|
||||
### Gelato Network
|
||||
- **Task creation**: ~200k gas
|
||||
- **Per execution**: ~100k - 300k gas
|
||||
- **Native funding**: 0.1 ETH (recommended)
|
||||
- **Cost**: Native token + gas
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate Actions
|
||||
|
||||
1. ✅ **Deploy Keeper Contract**
|
||||
```bash
|
||||
forge script script/reserve/DeployKeeper.s.sol:DeployKeeper --rpc-url chain138 --broadcast
|
||||
```
|
||||
|
||||
2. ✅ **Choose Integration Option**
|
||||
- Standalone service (simplest)
|
||||
- Chainlink Keepers (decentralized)
|
||||
- Gelato Network (cost-effective)
|
||||
- Systemd service (production)
|
||||
- Docker (containerized)
|
||||
|
||||
3. ✅ **Start Monitoring**
|
||||
```bash
|
||||
node scripts/reserve/monitor-keeper.js
|
||||
```
|
||||
|
||||
### Production Checklist
|
||||
|
||||
- [ ] Deploy keeper contract
|
||||
- [ ] Configure assets to track
|
||||
- [ ] Set up integration (choose one or multiple)
|
||||
- [ ] Configure monitoring and alerts
|
||||
- [ ] Test failure scenarios
|
||||
- [ ] Set up backup keeper (optional)
|
||||
- [ ] Document deployment details
|
||||
- [ ] Set up monitoring dashboards
|
||||
|
||||
---
|
||||
|
||||
## Support and Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Keeper not updating**
|
||||
- Check keeper has `KEEPER_ROLE`
|
||||
- Verify assets are tracked
|
||||
- Check update interval
|
||||
- Verify service is running
|
||||
|
||||
2. **Chainlink registration fails**
|
||||
- Verify LINK balance
|
||||
- Check KeeperRegistry address
|
||||
- Verify gas limits
|
||||
- Check network compatibility
|
||||
|
||||
3. **Gelato task creation fails**
|
||||
- Verify native token balance
|
||||
- Check Gelato Ops address
|
||||
- Verify network compatibility
|
||||
- Check task parameters
|
||||
|
||||
### Resources
|
||||
|
||||
- [Keeper Setup Guide](./KEEPER_SETUP.md)
|
||||
- [Price Feed Setup](./PRICE_FEED_SETUP.md)
|
||||
- [Chainlink Documentation](https://docs.chain.link/chainlink-automation)
|
||||
- [Gelato Documentation](https://docs.gelato.network)
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
All integration options for the automated price feed keeper have been implemented and are ready for deployment. The system provides flexibility to choose the best integration method based on requirements, budget, and infrastructure.
|
||||
|
||||
**Status**: ✅ **ALL INTEGRATIONS COMPLETE - READY FOR PRODUCTION**
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
- ✅ **5 Integration Options**: Standalone, Chainlink, Gelato, Systemd, Docker
|
||||
- ✅ **Monitoring System**: Complete monitoring and alerting
|
||||
- ✅ **Deployment Automation**: One-command deployment
|
||||
- ✅ **Documentation**: Comprehensive guides
|
||||
- ✅ **Production Ready**: All components tested and documented
|
||||
|
||||
The keeper system is fully integrated and ready for production deployment on ChainID 138.
|
||||
|
||||
@@ -125,7 +125,7 @@ All deployed contracts use the same admin address, providing consistent access c
|
||||
|
||||
✅ **ChainID 138 Configuration Complete**
|
||||
|
||||
- File: `pr-workspace/app-ethereum/src/network.c` (line 42)
|
||||
- File: `../app-ethereum/src/network.c` (line 42)
|
||||
- Chain ID: 138
|
||||
- Name: "Defi Oracle Meta"
|
||||
- Ticker: "ETH"
|
||||
|
||||
@@ -340,13 +340,13 @@
|
||||
**Description**: Verify RPC endpoints in Ledger app-ethereum configuration match current infrastructure.
|
||||
|
||||
**Current Configuration**:
|
||||
- File: `pr-workspace/app-ethereum/src/network.c` (line 42)
|
||||
- File: `../app-ethereum/src/network.c` (line 42)
|
||||
- Chain ID: 138 ✅
|
||||
- Name: "Defi Oracle Meta" ✅
|
||||
- Ticker: "ETH" ✅
|
||||
|
||||
**Steps**:
|
||||
1. Check `pr-workspace/app-ethereum/src/network.c` for RPC endpoint configuration
|
||||
1. Check `../app-ethereum/src/network.c` for RPC endpoint configuration
|
||||
2. Search for RPC URL settings in app-ethereum configuration files
|
||||
3. Verify RPC endpoints match:
|
||||
- Public: `https://rpc-http-pub.d-bis.org`
|
||||
|
||||
@@ -155,7 +155,7 @@ forge verify-contract --chain-id 1 \
|
||||
|
||||
**Gap**: ChainID 138 is configured in app-ethereum, but RPC endpoints may not match current infrastructure.
|
||||
|
||||
**Current Configuration** (in `pr-workspace/app-ethereum/src/network.c`):
|
||||
**Current Configuration** (in `../app-ethereum/src/network.c`):
|
||||
- Chain ID: 138 ✅
|
||||
- Name: "Defi Oracle Meta" ✅
|
||||
- Ticker: "ETH" ✅
|
||||
|
||||
@@ -100,9 +100,9 @@ Environment variables that need to be checked:
|
||||
|
||||
ChainID 138 is already configured in `app-ethereum`:
|
||||
|
||||
- `pr-workspace/app-ethereum/src/network.c` - Line 42: ChainID 138 entry exists
|
||||
- `pr-workspace/app-ethereum/makefile_conf/chain/defi_oracle.mk` - Configuration file exists
|
||||
- Test file `pr-workspace/app-ethereum/tests/ragger/test_get_address.py` - Line 24: Includes ChainID 138 in test params
|
||||
- `../app-ethereum/src/network.c` - Line 42: ChainID 138 entry exists
|
||||
- `../app-ethereum/makefile_conf/chain/defi_oracle.mk` - Configuration file exists
|
||||
- Test file `../app-ethereum/tests/ragger/test_get_address.py` - Line 24: Includes ChainID 138 in test params
|
||||
|
||||
**Configuration Details**:
|
||||
- Chain ID: 138
|
||||
|
||||
@@ -9,14 +9,14 @@
|
||||
|
||||
✅ **ChainID 138 Configuration Verified**
|
||||
|
||||
**File**: `pr-workspace/app-ethereum/src/network.c` (line 42)
|
||||
**File**: `../app-ethereum/src/network.c` (line 42)
|
||||
|
||||
**Configuration**:
|
||||
```c
|
||||
{.chain_id = 138, .name = "Defi Oracle Meta", .ticker = "ETH"}
|
||||
```
|
||||
|
||||
**Makefile Configuration**: `pr-workspace/app-ethereum/makefile_conf/chain/defi_oracle.mk`
|
||||
**Makefile Configuration**: `../app-ethereum/makefile_conf/chain/defi_oracle.mk`
|
||||
```
|
||||
CHAIN_ID = 138
|
||||
APPNAME = "Defi Oracle Meta"
|
||||
@@ -47,7 +47,7 @@ PATH_APP_LOAD_PARAMS += "44'/60'"
|
||||
|
||||
### Test File Verification
|
||||
|
||||
**File**: `pr-workspace/app-ethereum/tests/ragger/test_get_address.py` (line 24)
|
||||
**File**: `../app-ethereum/tests/ragger/test_get_address.py` (line 24)
|
||||
|
||||
ChainID 138 included in test parameters:
|
||||
```python
|
||||
@@ -64,7 +64,7 @@ The app source code includes ChainID 138 configuration with correct chain ID, na
|
||||
|
||||
### RPC discovery for Ledger / wallets
|
||||
|
||||
- **Chainlist / chains**: `pr-workspace/chains/_data/chains/eip155-138.json` includes `https://rpc-http-pub.d-bis.org` and `wss://rpc-ws-pub.d-bis.org` so Ledger Live and other clients can discover ChainID 138 RPCs.
|
||||
- **Chainlist / chains**: `../chains/_data/chains/eip155-138.json` includes `https://rpc-http-pub.d-bis.org` and `wss://rpc-ws-pub.d-bis.org` so Ledger Live and other clients can discover ChainID 138 RPCs.
|
||||
- **Doc**: [PUBLIC_RPC_CHAIN138_LEDGER.md](../../../docs/04-configuration/PUBLIC_RPC_CHAIN138_LEDGER.md) – public RPCs, Proxmox VM / NPMplus mapping, and Ledger access.
|
||||
|
||||
---
|
||||
|
||||
@@ -87,8 +87,8 @@
|
||||
**Completed**: 2025-01-18
|
||||
|
||||
**Actions Taken**:
|
||||
1. Verified ChainID 138 configuration in `pr-workspace/app-ethereum/src/network.c` (line 42)
|
||||
2. Verified makefile configuration: `pr-workspace/app-ethereum/makefile_conf/chain/defi_oracle.mk`
|
||||
1. Verified ChainID 138 configuration in `../app-ethereum/src/network.c` (line 42)
|
||||
2. Verified makefile configuration: `../app-ethereum/makefile_conf/chain/defi_oracle.mk`
|
||||
3. Confirmed configuration values:
|
||||
- Chain ID: 138 ✅
|
||||
- Name: "Defi Oracle Meta" ✅
|
||||
|
||||
@@ -13,9 +13,10 @@ Use with `config/deployment-omnl.example.env` (copy to `.env` on the host; never
|
||||
|
||||
1. Set `OMNL_*`, `ENABLE_OMNL_EVENT_POLLER`, `OMNL_POLLER_STATE_PATH` (optional), webhook URLs/secrets, optional `OMNL_API_KEY` / `OMNL_DASHBOARD_TOKEN`, `OMNL_RATE_LIMIT_*` as needed.
|
||||
2. `pnpm run build` in `services/token-aggregation`.
|
||||
3. Health: `GET /health`; OMNL: `GET /api/v1/omnl/compliance`; dashboard: `GET /omnl/dashboard`.
|
||||
4. Run `bash scripts/hybx-omnl/verify-deployment.sh` (Forge `hybx-omnl` tests + `tsc` in `services/token-aggregation`).
|
||||
5. **Publish snapshot** (`smom-dbis-138-publish/`): run the same script name there for TypeScript + `omnl-reconcile-report.mjs` only; Forge deps live in the main repo.
|
||||
3. Health: `GET /health`; OMNL: `GET /api/v1/omnl/compliance`; dashboard: `GET /omnl/dashboard`; operator console: `GET /omnl/compliance` (public UI at `https://explorer.d-bis.org/omnl/compliance`).
|
||||
4. Deploy to CT 5000: `bash scripts/deployment/sync-token-aggregation-vmid5000.sh` from repo root; nginx `/omnl/` proxy via `bash scripts/deployment/patch-explorer-nginx-omnl-console.sh`.
|
||||
5. Run `bash scripts/hybx-omnl/verify-deployment.sh` (Forge `hybx-omnl` tests + `tsc` in `services/token-aggregation`).
|
||||
6. **Publish snapshot** (`smom-dbis-138-publish/`): run the same script name there for TypeScript + `omnl-reconcile-report.mjs` only; Forge deps live in the main repo.
|
||||
|
||||
## Post-deploy
|
||||
|
||||
|
||||
@@ -37,6 +37,14 @@ Wire your log/metrics stack to alert on:
|
||||
- `mirror-status` / `inSync === false` when both reserve stores are configured.
|
||||
- Repeated `401` on OMNL routes (possible credential scanning).
|
||||
|
||||
## Operator compliance console
|
||||
|
||||
- **Public UI:** `https://explorer.d-bis.org/omnl/compliance` — posture, pending actions (Safe notary gate, DefiLlama PRs), on-chain evidence, triple reconcile snapshot.
|
||||
- **JSON API:** `GET /api/v1/omnl/compliance/console` (requires `OMNL_API_KEY` unless `OMNL_COMPLIANCE_CONSOLE_PUBLIC=1` on token-aggregation).
|
||||
- **Safe notary gate:** `GET /api/v1/omnl/compliance/safe-notary-gate-tx` or `pnpm omnl:safe-notary-gate-tx` → `reports/status/omnl-safe-notary-gate-tx.json`. Exec: `pnpm omnl:safe-notary-gate-exec` (needs **3-of-5** sigs from **current** Safe owners) or import into Safe UI.
|
||||
- **Owner key alignment:** If automated exec reports `signers_available=1`, run owner swap per [OMNL_SAFE_OWNER_KEYS_RUNBOOK.md](../../../docs/03-deployment/OMNL_SAFE_OWNER_KEYS_RUNBOOK.md) (`pnpm compliance:omnl:safe:reconcile-keys`, `pnpm compliance:omnl:safe:owner-swap-tx`).
|
||||
- **Deploy:** `bash scripts/deployment/sync-token-aggregation-vmid5000.sh` (full build + nginx `/omnl/` patch). Explorer Operator nav link: `bash explorer-monorepo/scripts/deploy-next-frontend-to-vmid5000.sh`.
|
||||
|
||||
## Break-glass
|
||||
|
||||
- Document who can pause `OMNLCircuitBreaker` and rotate coordinator keys; store procedures outside this repo per org policy.
|
||||
|
||||
@@ -93,3 +93,24 @@ Chainlink/Gelato keeper stack imported from sibling WIP archive (see [docs/00-me
|
||||
- `script/reserve/DeployChainlinkKeeper.s.sol`, `script/reserve/DeployGelatoKeeper.s.sol`
|
||||
- `docker/Dockerfile.keeper`, `docker/docker-compose.keeper.yml`, `systemd/price-feed-keeper.service`
|
||||
- `scripts/reserve/chainlink-keeper-setup.js`, `gelato-keeper-setup.js`, `monitor-keeper.js`, `deploy-all.sh`
|
||||
|
||||
---
|
||||
|
||||
## deploy-all.sh dry-run
|
||||
|
||||
Validate keeper deploy wiring without broadcasting transactions or mutating `.env`.
|
||||
|
||||
```bash
|
||||
cd smom-dbis-138
|
||||
DRY_RUN=1 bash scripts/reserve/deploy-all.sh
|
||||
# or
|
||||
bash scripts/reserve/deploy-all.sh --dry-run
|
||||
```
|
||||
|
||||
Dry-run behavior:
|
||||
|
||||
- Prints each deployment step and the `PRICE_FEED_KEEPER_ADDRESS` read from `.env` (must match `0xD3AD6831aacB5386B8A25BB8D8176a6C8a026f04` for Chain 138).
|
||||
- Skips `forge script` `--broadcast` / `--verify` and does not append addresses to `.env`.
|
||||
- When `DEPLOY_CHAINLINK=true` or `DEPLOY_GELATO=true`, prints the optional Chainlink/Gelato forge commands and follow-up setup scripts that would run.
|
||||
|
||||
Live deploy (no `DRY_RUN`): same script without dry-run flags; requires `PRIVATE_KEY` and uses `RPC_URL_138` (default `https://rpc.d-bis.org`).
|
||||
|
||||
Reference in New Issue
Block a user