EO Chain contracts

Smart Contracts Design

1. Introduction

Purpose

This document provides a comprehensive explanation of EO's smart contract infrastructure design. This design aims to create a modular and programmable blockchain oracle platform capable of supporting the development of new blockchain oracles. This designs aims to provide a programmable layer that consists of operators management, different data types and aggregation methods.

Scope

This design document covers the architecture and implementation details of the smart contracts that will form the core of EO chain contracts. It takes into account the offchain components which are communicating with the EO chain.

2. Background and Motivation

Building new OVSs requires many pieces of infrastructure, specialized for managing operators, aggregating decentralized data and providing it to consumers.

The new smart contract infrastructure aims to achieve the following:

1. Modularity: Create a system where different parts can be easily added, removed, or updated without affecting the whole system.

   1. enable updating data feeds and data sources

   2. enable registering/deploying new OVSs

   3. enable registering/deploying new feeds

   4. enable registering new aggregators

2. Scalability: Design the system to handle more data sources, data feeds, aggregation methods.

3. Customizable Blockchain Oracle Services (OVS): Make it easy for partners to create and deploy their own custom blockchain oracle services according to specific needs

4. Enhanced Flexibility: Ensure the new system can easily manage the connection between data feeds/sources, feeds/OVS, feed/aggregators etc

3. System Overview

The system is designed to enable the construction of new blockchain oracles, referred to as blockchain Oracle Validated Services (OVS). Each OVS operates with its own set of registered operators who participate in the data aggregation and consensus processes specific to that OVS. Operators can request to join an OVS, and their participation is approved by the OVS Admin, who manages operator registration, data sources, and feeds within the OVS. The operators’ stake or voting power, registered to the EO network, is crucial for consensus on the data provided by each OVS. Every OVS contains feeds—data pipelines with input from one or more sources and an aggregator smart contract that processes the inputs to generate a single output. This output is distributed through the EO distribution system to target chains. The system’s modularity allows new blockchain oracles to be easily built by deploying a new OVS, configuring custom feeds, and allowing operators to opt-in for data updates, creating a scalable, customizable solution for diverse blockchain oracle use cases.

4. System Architecture

4.1 High-Level Architecture

This section will describe the core components of the system:

• Data Feed Management Module: Handles the configuration and management of data feeds.

• Operator Management Module: Manages operator registration, activation, and stake.

• Aggregation Engines: Combines data from different operators to create a unified result.

• OVS Module: Allows partners to build and customize their blockchain oracle services.

Diagram

5. System Roles

5.1 Roles Definitions

Role	Contract	Responsibilities
OVS_MANAGER	Registry (OVS module)	register/deploy OVSs, rigister/approve aggregators
FEED_MANAGER	Config	sources should be managed in Registry globally
OVS_ADMIN (OVS Admin)	OVS	admin, owner of OVS instance contract, manages other roles through AccessControl
OVS_PAUSER (for now it is OVS_ADMIN)	OVS	pause OVS
OVS_OPERATOR (for now it is OVS_ADMIN)	OVS	Approve Operators, add new feeds/sources to the OVS.

Registry

As an OPERATORS_MANAGER:

• activate operators and manage operators configuration

  • setStake()

  • Activate Operators

  • Add Operators to OVS

• manage aliases

  • changeAlias()

  • assignAlias()

As an OVS_MANAGER:

• register OVS

• register aggregator

• approve OVS

• approve aggregator

Config

As FEED_MANAGER:

• add/remove/update data sources

• track feed id and store basic feed info - Ovs and Aggregator

OVS contract

As an OVS Admin:

• grant/revoke other roles within smart contract

• deposit rewards

• approve/decline operators requests to opt-in to OVS

• add feeds to OVS (saved to aggregator)

As an operator:

• register/deregister from EO AVS

• register/deregister to OVS

• join to OVS

• declareAlias to each OVS

• updateFeedReport

Anyone:

• request register new Aggregator

• request register new OVS

6. System Components

Relations:

• Operator - OVS

  • each operator can be registered to many OVS

  • each OVS can have many operators

• OVS - Aggregator

  • each OVS can support many aggregators

  • each Aggregator can be used in several OVS as separate instance

• OVS - Feed

  • each OVS can contain many feeds

  • feed is related to one OVS only

• Feed - Source

  • feed can be fetched from several sources

  • sources can be used by several feeds

Flows

Feed management flow

Source management

Operators statuses in OVS

Opt-in to OVS

OVS flow

UpdateRateReport flow

Component Breakdown

OVS management

• actors

  • OVS_MANAGER

  • operator

  • guest

• storage

struct OVS {
		uint256 totalStake
		Feed[] feeds
		bool isActive
		registeredOperators[]
		requestedOperators[]
}

enum OVSOperatorStatus {
	Unknown,
	Requested,
	Approved,
	Declined
}

uint64 ovsAddresses[]
mapping(address ovsAddress => OVS) ovses;
mapping(address ovsAddress => mapping(address operator => OVSOperatorStatus)) ovsOperatorStatuses;
// ovsIds for each operator are stored in operator struct

• interfaces

// as anyone?
function requestRegisterOVS(???) // not v1
function requestRegisterAggregator() // not v1

// as operator(alias):
function registerOperatorToOVS(address ovs, address alias)// alias can be declared on this step
// but how to do it in batch?
function registerOperatorToOVSes(address[] ovses, , address[] aliases) // when operator is active. 
function updateFeedReport() // not needed if call directtly to OVS

//as OVS
function updateOperatorAsApproved(address operator)
function updateOperatorAsDeclined(address operator)

//as OVS_MANAGER
function approveOVS() //->deploys clone of OVS
function registerOVS() //- >deploys clone of OVS / OR whitelisting
function approveAgregator() // do we need to track all aggregators and approve them???
function registerAggregator()

Config

• Responsibilities: separate contract responsible for feeds tracking and sources management

• Interactions: can contain most of the storage which is used by other components

uint64 sourcesIds[]
mapping(uint64 sourceId => Source) sources;

function updateNextFeedId() external returns (uint256 feedId)
function updateNextSourceId() external returns (uint256 sourceId)

OVS instance (separate contract)

• storage

uint64 feedIds[];  // ranges for each OVS? 0-n 10000-n
mapping(uint64 feedId => Feed) feeds;

uint256 totalStake;
// other config ???
address[] registeredOperators; //  check if not redundant, 
// stored in OVS instance or in OVS module (part of Registry) ???

• interface

// as an Registry
function registerOperator(address operator, address alias)// alias can be declared on this step

// as OWS_OWNER
function addFeeds(Feed[] feeds)
// add to registeredOperators[] to Registry 
// + change OVSOperatorStatus to Approved + call _recalculateStake() 
function approveOperators(address[] operators) 
// change OVSOperatorStatus to Declined
function declineOperators(address[] operators) 
// updateOVS
// remove from registeredOperators[] (at Registry) 
// + change OVSOperatorStatus to Unknown + _recalculateStake()
function deleteOperators(address[] operators) 
function depositRewards()
function updateFeedReport()  // directly to each OVS but
//not to Registry.OVSModule single entry point?

function changeAlias(address newOperatorAlias)

Aggregator

Interface

function aggregate(Feed[] feeds) // feed.data should be decoded according to defined scheme in Aggregator

flowchart LR
    Aggregator-- "reads feeds config,
    thresholds" -->OVS
    Aggregator-- reads cached votes and stake -->OVS