Ethereum Oracle

Author: ezeike

cmd/cli/main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"flag"
@@ -15,6 +16,8 @@ import (
 	"time"
 
 	"github.com/canopy-network/canopy/cmd/rpc"
+	"github.com/canopy-network/canopy/cmd/rpc/oracle"
+	"github.com/canopy-network/canopy/cmd/rpc/oracle/eth"
 	"github.com/canopy-network/canopy/controller"
 	"github.com/canopy-network/canopy/fsm"
 	"github.com/canopy-network/canopy/lib"
@@ -75,6 +78,10 @@ func Start() {
 		l.Infof("Sleeping until %s", untilTime.String())
 		time.Sleep(untilTime)
 	}
+	// create a shared context for oracle and ethereum block provider
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	
 	// initialize and start the metrics server
 	metrics := lib.NewMetricsServer(validatorKey.PublicKey().Address(), config.MetricsConfig)
 	// create a new database object from the config
@@ -87,8 +94,24 @@ func Start() {
 	if err != nil {
 		l.Fatal(err.Error())
 	}
+	// create a seperate logger for the oracle and all oracle components
+	oracleLogger := lib.NewOracleLogger(lib.LoggerConfig{Level: config.GetLogLevel()}, config.OracleConfig.LogPath)
+	// create a new ethereum disk storage instance for the oracle order store
+	oracleStorage, e := oracle.NewOracleDiskStorage(config.OracleConfig.OrderStorePath, oracleLogger)
+	if e != nil {
+		l.Fatal(e.Error())
+	}
+	// create the ethereum block provider
+	ethBlockProvider := eth.NewEthBlockProvider(config.EthBlockProviderConfig, oracleLogger)
+	// create a new oracle instance and pass the ethereum block provider with shared context
+	oracle, e := oracle.NewOracle(ctx, config.OracleConfig, ethBlockProvider, oracleStorage, oracleLogger)
+	if e != nil {
+		l.Fatal(e.Error())
+	}
+	// start the oracle with shared context
+	oracle.Start(ctx)
 	// create a new instance of the application
-	app, err := controller.New(sm, config, validatorKey, metrics, l)
+	app, err := controller.New(sm, oracle, config, validatorKey, metrics, l)
 	if err != nil {
 		l.Fatal(err.Error())
 	}
@@ -102,6 +125,10 @@ func Start() {
 	rpcServer.Start()
 	// block until a kill signal is received
 	waitForKill()
+	// cancel the shared context to stop oracle components
+	cancel()
+	// gracefuly stop oracle
+	oracle.Stop()
 	// gracefully stop the app
 	app.Stop()
 	// gracefully stop the metrics server

cmd/rpc/oracle/README.md

@@ -0,0 +1,209 @@
+# Oracle Package
+
+The Oracle package provides cross-chain transaction witnessing and validation capabilities for the Canopy blockchain system. It implements a chain-agnostic oracle that coordinates between external blockchains (like Ethereum) and the Canopy nested chain to facilitate cross-chain order execution and validation.
+
+## Overview
+
+The Oracle package is designed to handle:
+- Witnessing transactions on external blockchains containing Canopy lock & close orders
+- Validating and storing witnessed orders in a local order store
+- Participating in the BFT consensus process by providing witnessed orders for block proposals
+- Synchronizing with the root chain order book to maintain consistency
+- Managing persistent state for reliable order processing
+
+## Core Components
+
+### Oracle
+
+The main entry point for the Transaction Oracle system. It manages the overall cross-chain witnessing process, including:
+- Receiving blocks from external blockchain providers
+- Validating witnessed orders against the root chain order book
+- Persisting witnessed orders to local storage
+- Coordinating with the BFT consensus mechanism
+- Maintaining synchronization with root chain state
+
+### BlockProvider Integration
+
+The Oracle integrates with external blockchain providers through the `BlockProvider` interface. It provides:
+- Real-time block monitoring from external chains
+- Transaction parsing and order extraction
+- Height management and state persistence
+- Graceful startup and shutdown capabilities
+
+### Order Store Management
+
+The Oracle manages witnessed orders through a persistent store that:
+- Stores validated lock and close orders separately
+- Provides atomic read/write operations for order data
+- Maintains submission history for resubmission logic
+- Supports cleanup operations based on root chain updates
+
+## Sequence Diagram
+
+The following sequence diagram illustrates the core interactions in the Oracle package:
+
+```mermaid
+sequenceDiagram
+    participant EXT as External Chain
+    participant BP as BlockProvider
+    participant O as Oracle
+    participant OS as OrderStore
+    participant BFT as BFT Consensus
+    participant RC as Root Chain
+
+    %% Block Processing Flow
+    Note over EXT,BP: Block Witnessing
+    EXT->>BP: New Block with Transactions
+    BP->>O: Block via BlockCh
+    O->>O: Process Block
+    O->>OS: Validate & Store Orders
+    O->>O: Save Block Height
+
+    %% BFT Integration Flow
+    Note over BFT,O: Consensus Participation
+    BFT->>O: WitnessedOrders(orderBook, height)
+    O->>OS: Read Witnessed Orders
+    O->>BFT: Return Lock/Close Orders
+    BFT->>O: ValidateProposedOrders(orders)
+    O->>OS: Verify Orders Exist
+    O->>BFT: Validation Result
+
+    %% Root Chain Sync Flow
+    Note over RC,O: State Synchronization
+    RC->>O: UpdateRootChainInfo(info)
+    O->>O: Update Local OrderBook
+    O->>OS: Cleanup Stale Orders
+```
+
+## Technical Details
+
+### Cross-Chain Transaction Witnessing
+
+The Oracle system uses a block-based monitoring approach to witness transactions on external chains. This is achieved by:
+
+- **Block Provider Integration**: Connects to external blockchain nodes through configurable providers
+- **Transaction Parsing**: Extracts Canopy-specific order data from external chain transactions
+- **Order Validation**: Performs comprehensive validation against root chain order book data
+- **State Persistence**: Maintains reliable state storage for witnessed orders and processing height
+
+The system works like a specialized blockchain monitor that specifically looks for transactions containing Canopy order data, validates them against known orders, and stores them for later use in the consensus process.
+
+State persistence ensures that the Oracle can recover from interruptions without losing witnessed orders or reprocessing previously seen blocks.
+
+### BFT Consensus Integration
+
+The Oracle system uses a dual-phase approach to participate in Byzantine Fault Tolerant consensus:
+
+1. **Proposal Phase**: When acting as a proposer, the Oracle queries its witnessed order store to find orders that should be included in the next block proposal
+2. **Validation Phase**: When validating block proposals from other nodes, the Oracle verifies that all proposed orders exist in its local witnessed order store
+3. **Resubmission Logic**: Implements intelligent resubmission timing to handle cases where orders aren't immediately included in blocks
+
+This ensures that only orders witnessed by a majority of validator nodes are included in the blockchain, providing strong guarantees about cross-chain transaction validity.
+
+### Order Book Synchronization
+
+The Oracle system implements several synchronization mechanisms to maintain consistency with the root chain:
+
+- **Order Book Updates**: Receives periodic updates of the complete root chain order book state
+- **Stale Order Cleanup**: Automatically removes witnessed orders that are no longer relevant (locked orders, completed orders)
+- **State Validation**: Ensures witnessed orders match current order book entries before including them in block proposals
+- **Atomic Operations**: Uses mutex protection to ensure thread-safe access to shared order book state
+
+This synchronization acts like a cache invalidation system, where the Oracle maintains local copies of relevant data but periodically synchronizes with the authoritative root chain state.
+
+## Component Interactions
+
+### 1. Block Processing: External Chain Monitoring
+
+When a new block arrives from an external blockchain, the Oracle system performs comprehensive processing:
+
+- **Block Reception**: Receives blocks through a channel-based interface from the configured BlockProvider
+- **Height Persistence**: Saves the current block height to disk before processing to enable recovery
+- **Transaction Analysis**: Examines each transaction in the block for Canopy-specific order data
+- **Order Validation**: Validates witnessed orders against the current root chain order book
+- **Storage Operations**: Persists valid orders to the local order store with appropriate metadata
+
+This process is similar to how a blockchain indexer works, but with specific focus on cross-chain order validation and storage.
+
+### 2. Consensus Participation: BFT Integration
+
+The Oracle participates in the BFT consensus process through two key interfaces:
+
+- **WitnessedOrders**: Called during block proposal to provide witnessed orders that should be included in the next block
+- **ValidateProposedOrders**: Called during block validation to verify that proposed orders were actually witnessed by this node
+- **Resubmission Logic**: Implements timing controls to handle cases where orders aren't immediately included in blocks
+- **State Updates**: Maintains submission history to prevent duplicate submissions and enable intelligent resubmission
+
+This is analogous to how a validator node participates in consensus, but with specialized logic for cross-chain order validation.
+
+### 3. Root Chain Synchronization: State Management
+
+The Oracle system implements comprehensive state management for maintaining consistency with the root chain:
+
+- **Order Book Updates**: Receives and processes complete order book state from the root chain
+- **Cleanup Operations**: Removes witnessed orders that are no longer needed based on root chain state
+- **Consistency Validation**: Ensures witnessed orders still match their corresponding root chain entries
+- **Thread Safety**: Uses mutex protection to ensure atomic updates to shared state
+
+This synchronization system works like a distributed cache, where the Oracle maintains local copies of relevant data but periodically synchronizes with the authoritative source.
+
+## Cross-Chain Security Features
+
+The Oracle system implements several security mechanisms to ensure reliable cross-chain operation:
+
+- **Comprehensive Validation**: Performs strict validation of all witnessed order fields against root chain data
+- **Atomic State Management**: Uses file-based persistence with atomic operations to prevent data corruption
+- **Graceful Recovery**: Implements startup logic that can recover from interruptions without data loss
+- **Error Isolation**: Continues processing even when individual orders fail validation
+
+These features combine to create a robust system that can handle the challenges of cross-chain communication while maintaining strong security guarantees.
+
+## Usage
+
+To use the Oracle package:
+
+1. Configure the Oracle with appropriate blockchain providers and storage systems
+2. Initialize the Oracle with context, configuration, and dependencies
+3. Start the Oracle to begin monitoring external chains
+
+```go
+// Example usage
+ctx := context.Background()
+config := lib.OracleConfig{
+    StateSaveFile: "/path/to/state.txt",
+    OrderResubmitDelay: 10,
+}
+
+oracle, err := NewOracle(ctx, config, blockProvider, orderStore, logger)
+if err != nil {
+    log.Fatal(err)
+}
+
+oracle.Start(ctx)
+defer oracle.Stop()
+```
+
+## Configuration
+
+The Oracle accepts configuration through `lib.OracleConfig` with the following parameters:
+
+- `StateSaveFile`: File path for persisting the last processed block height
+- `OrderResubmitDelay`: Number of blocks to wait before resubmitting an order to consensus
+
+## Error Handling
+
+The Oracle implements comprehensive error handling patterns:
+
+- **Graceful Degradation**: Continues processing even when individual operations fail
+- **Detailed Logging**: Provides extensive logging for debugging and monitoring
+- **State Recovery**: Can recover from interruptions by reading persisted state
+- **Validation Errors**: Distinguishes between validation failures and system errors
+
+## Performance Considerations
+
+The Oracle is designed for high-throughput operation with several optimizations:
+
+- **Concurrent Processing**: Uses goroutines for non-blocking block processing
+- **Efficient State Management**: Minimizes disk I/O through strategic state persistence
+- **Memory Management**: Uses read-write mutexes to allow concurrent reads while protecting writes
+- **Batched Operations**: Processes multiple orders per block to improve throughput

cmd/rpc/oracle/error.go

@@ -0,0 +1,109 @@
+package oracle
+
+import (
+	"fmt"
+	"math"
+
+	"github.com/canopy-network/canopy/lib"
+)
+
+const (
+	NoCode lib.ErrorCode = math.MaxUint32
+
+	// Oracle Module
+	OracleModule lib.ErrorModule = "oracle"
+
+	// Oracle Module Error Codes
+	CodeReadHeightFile   lib.ErrorCode = 1
+	CodeParseHeight      lib.ErrorCode = 2
+	CodeWriteHeightFile  lib.ErrorCode = 3
+	CodeCreateDirectory  lib.ErrorCode = 4
+	CodeGetHomeDirectory lib.ErrorCode = 5
+	CodeUnmarshalOrder   lib.ErrorCode = 6
+	CodeMarshalOrder     lib.ErrorCode = 7
+	CodeOrderNotFound    lib.ErrorCode = 8
+	CodeGetOrderBook     lib.ErrorCode = 9
+	CodeAmountMismatch   lib.ErrorCode = 10
+	CodeOrderNotVerified lib.ErrorCode = 11
+	CodeOrderValidation  lib.ErrorCode = 12
+
+	// OrderStore Module
+	OrderStoreModule lib.ErrorModule = "order_store"
+
+	// OracleStore Module Error Codes
+	CodeValidateOrder lib.ErrorCode = 1
+	CodeVerifyOrder   lib.ErrorCode = 2
+	CodeReadOrder     lib.ErrorCode = 3
+	CodeRemoveOrder   lib.ErrorCode = 4
+	CodeWriteOrder    lib.ErrorCode = 5
+)
+
+// Error functions for Order Store module
+func ErrValidateOrder(err error) lib.ErrorI {
+	return lib.NewError(CodeValidateOrder, OrderStoreModule, "failed to validate order: "+err.Error())
+}
+
+func ErrVerifyOrder(err error) lib.ErrorI {
+	return lib.NewError(CodeVerifyOrder, OrderStoreModule, "failed to verify order: "+err.Error())
+}
+
+func ErrReadOrder(err error) lib.ErrorI {
+	return lib.NewError(CodeReadOrder, OrderStoreModule, "failed to read order: "+err.Error())
+}
+
+func ErrRemoveOrder(err error) lib.ErrorI {
+	return lib.NewError(CodeRemoveOrder, OrderStoreModule, "failed to remove order: "+err.Error())
+}
+
+func ErrWriteOrder(err error) lib.ErrorI {
+	return lib.NewError(CodeWriteOrder, OrderStoreModule, "failed to write order: "+err.Error())
+}
+
+// Error functions for Oracle module
+func ErrReadHeightFile(err error) lib.ErrorI {
+	return lib.NewError(CodeReadHeightFile, OracleModule, "failed to read height file: "+err.Error())
+}
+
+func ErrParseHeight(err error) lib.ErrorI {
+	return lib.NewError(CodeParseHeight, OracleModule, "failed to parse height: "+err.Error())
+}
+
+func ErrWriteHeightFile(err error) lib.ErrorI {
+	return lib.NewError(CodeWriteHeightFile, OracleModule, "failed to write height file: "+err.Error())
+}
+
+func ErrCreateDirectory(err error) lib.ErrorI {
+	return lib.NewError(CodeCreateDirectory, OracleModule, "failed to create directory: "+err.Error())
+}
+
+func ErrGetHomeDirectory(err error) lib.ErrorI {
+	return lib.NewError(CodeGetHomeDirectory, OracleModule, "failed to get home directory: "+err.Error())
+}
+
+func ErrUnmarshalOrder(err error) lib.ErrorI {
+	return lib.NewError(CodeUnmarshalOrder, OracleModule, "failed to unmarshal order: "+err.Error())
+}
+
+func ErrMarshalOrder(err error) lib.ErrorI {
+	return lib.NewError(CodeMarshalOrder, OracleModule, "failed to marshal order: "+err.Error())
+}
+
+func ErrOrderNotFoundInOrderBook(orderId string) lib.ErrorI {
+	return lib.NewError(CodeOrderNotFound, OracleModule, "order not found in order book: "+orderId)
+}
+
+func ErrGetOrderBook(err error) lib.ErrorI {
+	return lib.NewError(CodeGetOrderBook, OracleModule, "failed to get order book: "+err.Error())
+}
+
+func ErrAmountMismatch(transferAmount, orderAmount uint64) lib.ErrorI {
+	return lib.NewError(CodeAmountMismatch, OracleModule, fmt.Sprintf("transfer amount %d does not match order amount %d", transferAmount, orderAmount))
+}
+
+func ErrOrderNotVerified(s string, err error) lib.ErrorI {
+	return lib.NewError(CodeOrderNotVerified, OracleModule, "order not verified: "+err.Error())
+}
+
+func ErrOrderValidation(s string) lib.ErrorI {
+	return lib.NewError(CodeOrderValidation, OracleModule, "order validation failure: "+s)
+}