Merge pull request #14 from oasisprotocol/rube/multichain

feat: multichain header oracle

Author: rube-de

.env.example

@@ -1,40 +1,102 @@
-# Common configuration (all modes)
-SOURCE_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_API_KEY
+# ROFL Header Oracle - Multi-Chain Configuration
+# ===============================================
+# Each chain runs as a separate container (oracle-base, oracle-eth, oracle-arb).
+# To enable/disable a chain, comment/uncomment its service in compose.yaml.
+# If a chain's service is enabled, its RPC URL is REQUIRED.
+
+# ===========================================
+# SHARED CONFIGURATION (all chains)
+# ===========================================
 TARGET_RPC_URL=https://testnet.sapphire.oasis.io
-ROFL_ADAPTER_ADDRESS=YOUR_ROFL_ADAPTER_ADDRESS  # ROFLAdapter contract address on Sapphire
-REQUEST_TIMEOUT=30  # HTTP request timeout in seconds
-RETRY_COUNT=3  # Number of retry attempts for failed operations
+ROFL_ADAPTER_ADDRESS=YOUR_ROFL_ADAPTER_ADDRESS
 
 # Oracle mode: event_listener, push, watcher, or token_watcher
 ORACLE_MODE=event_listener
 
-# Logging configuration
-LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
-JSON_LOGS=false  # Enable JSON-formatted structured logging (recommended for production)
-
-# Event Listener Mode Configuration (ORACLE_MODE=event_listener)
-SOURCE_CONTRACT_ADDRESS=0x85BfE05492aFC3D04Ff3B2ca6771ACF6f853d90d  # BlockHeaderRequester contract
-POLLING_INTERVAL=12  # Seconds between event checks
-LOOKBACK_BLOCKS=100  # Blocks to look back on startup
-
-# Push Mode Configuration (ORACLE_MODE=push)
-PUSH_INTERVAL=60  # Seconds between block pushes
-PUSH_BATCH_SIZE=20  # Max blocks to push per iteration
-
-# Watcher Mode Configuration (ORACLE_MODE=watcher)
-WATCH_ADDRESSES=0xAddress1,0xAddress2  # Comma-separated addresses to watch
-SCAN_INTERVAL=60  # Seconds between scanning for interactions
-WATCHER_BATCH_SIZE=50  # Max blocks to scan per iteration
-# LOOKBACK_BLOCKS=100  # Also used in watcher mode
-ENABLE_INTERNAL_TX_DETECTION=false  # Enable internal transaction detection (requires archive node with debug API)
-
-# Token Watcher Mode Configuration (ORACLE_MODE=token_watcher)
-TOKEN_ADDRESSES=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48  # Comma-separated ERC20 token contract addresses (e.g., USDC, USDT)
-RECIPIENT_ADDRESSES=0xYourAddress1,0xYourAddress2  # Comma-separated recipient addresses to watch for
-SCAN_INTERVAL=5  # Seconds between scans (default: 5 for fast detection)
-# Note: On first startup, begins monitoring from current block (no historical scan)
-# Note: Scans all new blocks since last check (no batch size limit)
-
-# Local mode configuration (for testing without ROFL)
-# Only required when running with --local flag or compose.local.yaml
-LOCAL_PRIVATE_KEY=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+# HTTP settings
+REQUEST_TIMEOUT=30
+RETRY_COUNT=3
+
+# Logging
+LOG_LEVEL=INFO
+JSON_LOGS=false
+
+# ===========================================
+# BASE CHAIN (Chain ID: 8453) → oracle-base
+# ===========================================
+BASE_SOURCE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
+
+# Event listener mode only
+# BASE_SOURCE_CONTRACT_ADDRESS=0x...  # BlockHeaderRequester on Base
+# BASE_POLLING_INTERVAL=2
+# BASE_LOOKBACK_BLOCKS=100
+
+# Watcher mode only
+# BASE_WATCH_ADDRESSES=0xAddress1,0xAddress2
+# BASE_SCAN_INTERVAL=2
+# BASE_WATCHER_BATCH_SIZE=50
+# BASE_ENABLE_INTERNAL_TX_DETECTION=false
+
+# Push mode only
+# BASE_PUSH_INTERVAL=2
+# BASE_PUSH_BATCH_SIZE=20
+
+# Token watcher mode only (also uses SCAN_INTERVAL from watcher)
+# BASE_TOKEN_ADDRESSES=0xTokenAddress
+# BASE_RECIPIENT_ADDRESSES=0xRecipient1,0xRecipient2
+# BASE_MAX_BLOCKS_PER_SCAN=10
+
+# ===========================================
+# ETHEREUM (Chain ID: 1) → oracle-eth
+# ===========================================
+ETH_SOURCE_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
+
+# Event listener mode only
+# ETH_SOURCE_CONTRACT_ADDRESS=0x...  # BlockHeaderRequester on Ethereum
+# ETH_POLLING_INTERVAL=12
+# ETH_LOOKBACK_BLOCKS=100
+
+# Watcher mode only
+# ETH_WATCH_ADDRESSES=0xAddress1,0xAddress2
+# ETH_SCAN_INTERVAL=12
+# ETH_WATCHER_BATCH_SIZE=50
+# ETH_ENABLE_INTERNAL_TX_DETECTION=false
+
+# Push mode only
+# ETH_PUSH_INTERVAL=12
+# ETH_PUSH_BATCH_SIZE=20
+
+# Token watcher mode only (also uses SCAN_INTERVAL from watcher)
+# ETH_TOKEN_ADDRESSES=0xTokenAddress
+# ETH_RECIPIENT_ADDRESSES=0xRecipient1,0xRecipient2
+# ETH_MAX_BLOCKS_PER_SCAN=10
+
+# ===========================================
+# ARBITRUM (Chain ID: 42161) → oracle-arb
+# ===========================================
+ARB_SOURCE_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY
+
+# Event listener mode only
+# ARB_SOURCE_CONTRACT_ADDRESS=0x...  # BlockHeaderRequester on Arbitrum
+# ARB_POLLING_INTERVAL=1
+# ARB_LOOKBACK_BLOCKS=100
+
+# Watcher mode only
+# ARB_WATCH_ADDRESSES=0xAddress1,0xAddress2
+# ARB_SCAN_INTERVAL=1
+# ARB_WATCHER_BATCH_SIZE=50
+# ARB_ENABLE_INTERNAL_TX_DETECTION=false
+
+# Push mode only
+# ARB_PUSH_INTERVAL=1
+# ARB_PUSH_BATCH_SIZE=20
+
+# Token watcher mode only (also uses SCAN_INTERVAL from watcher)
+# ARB_TOKEN_ADDRESSES=0xTokenAddress
+# ARB_RECIPIENT_ADDRESSES=0xRecipient1,0xRecipient2
+# ARB_MAX_BLOCKS_PER_SCAN=10
+
+# ===========================================
+# LOCAL MODE (testing without ROFL)
+# ===========================================
+LOCAL_PRIVATE_KEY=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef