1 of 22

EO

Quickstart

What is EO?

At its core, EO is an open infrastructure platform that empowers developers to build secure blockchain oracles backed by Ethereum's battle-tested security model. EO creates a foundation for specialized data services that combine deep domain expertise with unmatched cryptoeconomic security.

Smart contracts are powerful tools for executing transparent, immutable logic. However, to reach their full potential, they need reliable access to real-world data. Blockchain oracles serve as the critical bridge between blockchain systems and external data sources, enabling smart contracts to interact with the world beyond their native blockchain.

Two essential principles guide EO's protocol:

Trust Minimization

Trust minimization is achieved through a decentralized network of 100+ staked-backed operators, an immutable data layer, and a coordination system allowing different unrelated entities to take part and contribute while putting stakes at risk through an infrastructure that is designed to maintain trusted, reliable data operation for decentralized data machines.

Permissionless Innovation

The EO stack provides a comprehensive platform that anyone can use to build specialized blockchain oracle services without permission or gatekeeping. Domain experts can leverage our infrastructure to deliver high-quality data solutions for their specific use cases, focusing on what they do best. With EO handling the complex security and coordination challenges, builders can freely innovate within their expertise – whether it's financial data, real-world events, or computational services – and deploy their solutions immediately.

This open architecture creates a vibrant marketplace where specialized blockchain oracle services thrive through competition and innovation. The ecosystem benefits from a rich diversity of secure data solutions, each optimized for specific use cases while maintaining rigorous security standards. This permissionless approach unlocks Web3's true potential by giving users and applications access to an ever-expanding landscape of secure, specialized data services – all protected by Ethereum-grade security.

EO Vision

How does the eOracle protocol compare to a typical oracle?

The Current Reality

Today's blockchain oracle landscape is dominated by a small group of companies that must build and maintain everything: infrastructure, security, node networks, and data solutions. This "do-it-all" approach has created an unsustainable bottleneck in blockchain innovation.

Why Traditional Blockchain Oracles Fall Short

When diving deep into solving the blockchain oracle problem, two layers of complexity emerge that make any centralized solution fundamentally insufficient.

First is the inherent complexity of data itself. Each domain demands its own specialized understanding. Financial data requires sub-second updates and sophisticated anomaly detection. Social media data demands extreme throughput and ability to track emerging patterns in real-time. Risk and cyber analysis require complex prediction models and automated decision-making. Each domain comes with its own patterns, failure modes, and expertise requirements. A solution perfect for one becomes fundamentally flawed for another.

But that's only half the challenge. Building infrastructure for trustless data delivery - with high reliability, consistent uptime, and true decentralization - requires solving deep problems in cryptography, game theory, and distributed systems. The technical complexity here rivals that of the base layer blockchains themselves.

Complex coordination problems of this scale cannot be solved by any single entity. Instead, they require the power of free market innovation, where diverse participants can contribute their specialized knowledge and compete to deliver the best solutions. Just as no single provider can solve every blockchain's unique challenges, no single blockchain oracle provider can possess all the expertise needed to bring the world's data on-chain.

The Two-Layer Solution

EO introduces a fundamental shift: separating blockchain oracle services into distinct layers:

The security layer (EO) handles infrastructure and cryptographic guarantees
The data layer (OVS) enables specialists to focus purely on their domain expertise

This separation represents the natural evolution of a maturing market - where different participants can specialize and perfect their part of the solution, resulting in better outcomes for everyone.

The EO stack creates the foundation for a marketplace of blockchain oracle services where specialized knowledge can flourish and compete. Through this marketplace, the blockchain oracle problem will solve itself through the distributed efforts of countless builders and innovators, secured by Ethereum itself.

Understand EO

EO Trust Model

If you are unfamiliar with the concept of a blockchain oracle, reference the Ethereum Foundation's documentation on blockchain oracles

As blockchain technology gains widespread adoption and the usage of its applications expands, the economic significance and security requirements of blockchain oracles must grow with it.

Ethereum's Proof of Stake has established the gold standard for economic security, trust minimization, and decentralized validation. Through EigenLayer's shared security, this proven model now extends beyond Ethereum's core consensus, enabling a new generation of blockchain oracle services that inherit the same security guarantees.

Access to the largest pool of staked funds

Staked ETH is orders of magnitudes larger than the staking of all other traditional blockchain oracles combined. A blockchain oracle network with access to staked ETH inherits the established security instead of creating another pool. This access provides a more economically secure and capital-efficient way to build blockchain oracle networks.

Native staking

EO's security backing, ETH, is independent of EO operations. This makes it robust against issues that other blockchain oracles who use their token for staking, such as temporal drops in token value and death spirals. Blockchain , leading to security reduction and vice versa.

Slashing for malicious behavior

EO's system is designed to deter and address malicious activities. Utilizing , EO can initiate procedures that may lead to the slashing of an attacker's staked funds. Slashing completes EO's incentive model, matching Ethereum's security apparatus.

Distributed validation

Validators worldwide verify data accuracy, making the network robust against localized disruptions. This approach ensures that no single point of failure can compromise the system, enhancing both security and reliability. Additionally, the diverse geographic distribution of validators contributes to a more resilient and fault-tolerant network capable of withstanding various types of attacks and ensuring continuous neutrality and operations.

Economic and diverse Trust

Economic trust is the amount of capital at stake (quantity), while diverse trust is the variety and balance of nodes involved (quality).

For a protocol to achieve security and liveness in a decentralized manner, it needs a sufficient amount of economic trust and a diverse, well-balanced set of nodes. Only Ethereum has reached sufficient economic and diverse trust.

With restaking via Eigenlayer, a blockchain oracle design containing these elements is enabled, providing a practical path to achieving sufficient trust via diverse and economically trusted Ethereum validators.

Architecture Overview

If you are unfamiliar with the concept of a blockchain oracle, reference the Ethereum Foundation's documentation on blockchain oracles.

The following is a brief overview of the core components that define the EO protocol, to contextualize the data aggregation process.

Ethereum Eigenlayer Integration

A on Ethereum that help connect Ethereum validators to EO via . These contracts manage the network's cryptographic identity, stake records, operator set and enable EO to slash validators.

EO-Chain

Ideally, the best infrastructure for blockchain oracle operations would be Ethereum itself, but the high costs and latency of on-chain processes make this infeasible. To address this, the EO-chain is operated with a subset of the Ethereum validator set using the This chain is used to aggregate and produce cryptographically verifiable data. The EO-Chain is at the center of EO operations, offloading computation from the base layer, which reduces costs and latency. The EO-Chain creates immutable records of all EO activity. These records are used to cryptographically prove operator rewards and slashing.

Validator Clients

are responsible for observing real-world data, validating it, and reporting it to the EO chain. are responsible for maintaining the consensus of the EO chain. Together, these roles operate the EO protocol.

Aggregator Modules

Smart contracts on the EO-chain that enable aggregation and verification of data submitted by validators. These smart contracts produce digitally signed, verifiable data by aggregating the signatures of , accounting for their respective voting power.

EO Endpoints

EO provides to use EO data as a pull blockchain oracle. Coupled with the , dapps can automate their data usage with or

Target Network Contracts

Smart contracts can be on consumer blockchains to integrate EO data. These contracts can verify the validity of signatures produced by the EO protocol and enable dapps to read and use their desired data.

Data Processing

EO operators connect, compute, validate, and publish off-chain data to Dapps securely, permissionlessly and transparently.

Reporting

Any publicly accessible real-world data can be added to the EO network, where EO operators will begin reporting on it. Reports are sourced from different endpoints, such as a WebSocket or an API. The frequency of reporting and the values to be extracted are programmable by the user. Once the operator obtains the data, it signs it and sends it in a transaction to the EO-chain. Any operator with an above-threshold stake can participate in reporting, weighing each report by their stake. A report for a specific operator cannot be faked by another party, and their participation is an immutable part of the EO-chain state once received.

Validation & Aggregation

Operators running an EO node receive transactions with signed reports. The node then verifies the reporter's identity via their cryptographic signature. Due to the protocol's permissionless nature, reports are censorship-resistant. Periodically, smart contracts aggregate the verified reports with dedicated schemes ().

Dapps can use EO's standard aggregations, which employ advanced algorithms and protocols to identify and discard outliers, or custom aggregations defined for a specific use case. For consensus and security, the computation is distributed among the validators and verified by them.

The computational aggregation process and its result become an immutable part of the EO-chain. The decentralized, transparent, and permissionless nature of this process ascertains that the reports and the aggregation results are authentic, accurate, and verifiable. Those results are then eligible for publication.

Publication

Publication is the process of posting EO aggregated data onto a target blockchain. A target blockchain is any blockchain network where dapps wish to use EO data. To provide EO data, each target blockchain has a smart contract that verifies, parses, and approves data signed and produced by the EO-chain.

For gas costs and efficiency, the aggregated data is hashed to a leaf of a Merkle tree, mapped to the EO state, and signed by the current valid EO Validator set. EO uses the BLS digital signature scheme, enabling large quorum participation efficiently through threshold signing and . This cryptographic scheme allows for securing desired assets with a scalable signature scheme.

Consumption

Dapps, individuals, and institutions can easily interface with EO in the smart contract layer by using the EO Solidity SDK and reading their required aggregated data on-chain.

Users interested in low-latency or tailored updates can also use the EO REST-API. This enables users to receive all the components to prove the validity of data on-chain, and then execute a dependent transaction. All cryptography, encoding, and parsing

Off-chain infrastructure can use our WebSocket interface to cache aggregated data and provide a smooth and low-latency user experience, enabling instant integration and execution available on user-facing services. Our low-latency interface makes on-chain security and transparency accessible to provide a seamless user experience.

Conclusion

Process Overview

Reporting is permissionless, transparent, and unfalsifiable.
Aggregation is decentralized, programmable, secure, modular, immutable, and easily verifiable.
Publishing is efficient, interoperable, permissionless, and censorship-resistant.

In summary, the EO platform enables users with customizable requirements, dynamic security needs, niche data dependencies, and more to define their data flow. By defining the data type, sources, aggregation logic, and other desired variables, users can programmatically and comprehensively satisfy all workflow requirements to provide data and computation on-chain.

Any party can interface with the EO network for a given data need, and retrieve the proof components, a BLS-signed Merkle root & Merkle path. This can be used to prove the validity of data cross-chain. The signed Merkle root component enables the verification of a valid EO Validator Set, while the Merkle path can then be used to prove the inclusion of aggregated data. Due to the transparent and verifiable nature of the process, users are always assured of the authenticity of the computation, operator participation, and staked security.

Security

The following sections outline security aspects of the EO protocol

Cryptoeconomic Security

While traditional blockchain oracles rely on their proprietary tokens to maintain ecosystem health and secure operations, EO introduces a novel security approach with its dual-token design. The model synergizes the specific advantages of a protocol-dedicated token with the enhanced security and economic stability provided by a well-established token like ETH, used for staking purposes.

This dual-token approach marks a notable shift from the single token model. By incorporating ETH for staking purposes, EO connects to a broader and more resilient economic base. This strategy effectively mitigates risks associated with blockchain protocols that rely on protocol-specific tokens.

The following sections provide a mathematical analysis, showing the enhanced security and stability of such a system.

Measuring Cryptoeconomic Security

Cryptoeconomic security (CES) is a useful measure for analysis, consider the following;

Given a set of colluding validators that we henceforth term the attacker, we assume that the attacker has the ability to corrupt the majority of the validators. Therefore, the attacker possesses the power to manipulate the consensus process, potentially leading to double-spending, censoring transactions, or altering the integrity of the blockchain's state.

To assess whether attacking is beneficial, the attacker must take into account two elements: the Cost of Corruption () and the Profit from Corruption ().

encompasses the total resources the attacker must invest to successfully manipulate the protocol, i.e., slashing of their stake, technical resources required for the attack and other associated expenses. Since we focus on assessing the efficacy of stake slashing as a deterrent and its influence on the CES, we assume that the primarily involves the loss of the attacker's staked assets, while other costs will be disregarded.

signifies the potential gains the attacker would achieve post-successful manipulation. Our analysis requires a more subtle approach towards , and thus we divide into two sources as follows:

Profit from Manipulation () is the internal profit the attacker can gain by manipulating the protocol. For instance, for blockchain Oracle protocols, it is the profit that could be extracted by a malicious price update. The is upper-bounded by the protocol's Total Value Secured (TVS).
Profit from Depreciation () addresses the external profit the attacker can gain from betting on price volatility or depreciation through, e.g., derivative markets or short selling.

Notice that . A rational attacker will only attack if .

We capture this in the following definition.

Definition (CES Margin). A protocol has a -crypto-economic security margin, or a -CES margin, if

In what follows, we explicitly assume that increasing the CES margin implies a more crypto-economically (CE) secure protocol and say that a protocol is CE-secure or CE-vulnerable, referring to a positive or negative CES margin, respectively.

Profit from Short Selling

We now discuss the ingredient and suggest a (stylized and simplified) way to quantify it. Crucially, it does not rely on any property of a protocol and refers to any asset, be it cryptocurrency, fiat, or stock.

Consider a token we call $TOK, and assume that the attacker can short $TOK. Since we assume the attack is relatively quick, we neglect the shorting fees. The amount of short positions is bounded by $TOK's short interest. Namely, the percentage of $TOK's free float market cap that the attacker could short sell, which we denote by . We stress that typically . Further, let denote $TOK's total market cap (in USD). We therefore assume the attacker can open a short position of USD. Next, let denote the percentage of depreciation due to the attack, for . A short seller can thus earn for every $TOK they short. All in all, a successful short trade will grant the attacker a profit of USD.

CES: A Tale of Two Blockchain Oracles

To demonstrate how the CES margin is affected by the nature of the protocol's token, we compare the following two scenarios:

EnshrinedBlockchainOracle, which relies on the base-layer's token that we denote by $ETH.
TraditionalBlockchainOracle, relying on its own token that we denote by $TRD.

We assume that the only difference between EnshrinedBlockchainOracle and the TraditionalBlockchainOracle is the token used for staking. In both scenarios, the market cap of the stake is equal and worth (measured in USD); however, as we show shortly, the two scenarios imply different CES margins. The reason is that an attack's ramifications are different.

The value and utility of $ETH are independent of EnshrinedBlockchainOracle's activities, unlike $TRD, whose value is closely tied to the operations of TraditionalBlockchainOracle.

Resilience to Attacks

For Traditional Blockchain Oracle ($TRD), a successful attack on the TraditionalBlockchainOracle will affect the $TRD value, as the $TRD's inherent value is tied to the operations of TraditionalBlockchainOracle. The attacker can gain USD by shorting $TRD prior to the attack; hence, in TraditionalBlockchainOracle's case .

For EnshrinedBlockchainOracle ($ETH), as the value and utility of $ETH are unrelated to the EnshrinedBlockchainOracle protocol the price of $ETH will not be affected. Thus, the equals 0 for EnshrinedBlockchainOracle.

. If the TraditionalBlockchainOracle, which relies on its own token $TRD, has a -CES margin, then EnshrinedBlockchainOracle, which relies on the base-layer's token $ETH, has a -CES margin.

Observation 1 is illuminating. To illustrate, assume that the TraditionalBlockchainOracle is a medium-sized decentralized service ( billion USD) with a reasonable short interest ().

Under a severe attack (), its CES margin is smaller by 70-100 million USD compared to EnshrinedBlockchainOracle.

Under the same attack, the EnshrinedBlockchainOracle is far more cryptoeconomically secure, as the underlying stake is not derived from the operations of the EnshrinedBlockchainOracle. In contrast, such an attack would devastate the cryptoeconomic security of the TraditionalBlockchainOracle.

Divergences in the Cost of Corruption

External, unforeseen events can break the CES of the TraditionalBlockchainOracle. A crucial observation is that the , which is the stake of the validators, is always smaller than $TRD's market cap . Let denote the proportion of $TRD market cap used for staking in the protocol, namely . We use this formulation to analyze the robustness of the protocol and suggest it is susceptible to a death spiral.

For any real number , the TraditionalBlockchainOracle could be CE-vulnerable even if the cost of corruption is times the profit of manipulation, i.e., .

The above observation means that attacks might be executed even if the is negligible, provided that the attacker can gain from a $TRD price decrease after the attack. The component should thus reflect not only the TVS (through ) but also the short interest (through ).

Being able to short $TRD based on the TraditionalBlockchainOracle's operations increases the potential profit from attack, whereas there is no such benefit for attacking EnshrinedBlockchainOracle

Market Fluctuation Impact

Next, we analyze the ramifications of a sudden decrease of $TRD market cap. Such a change in valuation could result from the volatile nature of the crypto space or the unintended fault of the protocol.

Assume the protocol is CE-secure. Any fluctuation in $TRD market cap can make the protocol CE-vulnerable.

This observation is demonstrated using an example.

Example 1:

We analyze the CES of TraditionalBlockchainOracle after a major price drop, which occurs due to, e.g., a major crypto volatility event. We denote by the time of the price drop. We assume that the stake proportion is the attacker's foreseen price drop is , and the short interest is .

Before the attack at , we assume the market cap of $TRD is (all monetary quantities are given in million USD terms). Consequently, , and Additionally, we assume that before time the potential profit from manipulation is

The event at , which occurs due to a major crypto volatility event, causes the market cap of all crypto tokens to decrease. Particularly, we assume that $TRD drops by and that the more stable$ETH drops by . Furthermore, such a market cap change also decreases the . TraditionalBlockchainOracle's TVS is comprised of different tokens, for instance in $ETH, wrapped versions of $BTC, stable coins ($USDT/$USDC ), and more. Some of those tokens are more volatile than others, and some do not fluctuate at all. We thus assume that, on average, the drops on the same scale as $ETH, namely by

The figure below depicts the situation before and after , as we formally analyze next.

Let us analyze the CES margin. Before , we see that the CES margin is positive, since

After , which occurs due to a major crypto volatility event, the market cap of $TRD drops by and becomes . As a result, the falls to and the drops to . Furthermore, the market cap of all crypto market drops and, as noted above, the drops by . Overall, the CES margin becomes negative, since

Thus, the event at that sparked a price drop made the TraditionalBlockchainOracle CE vulnerable.

Next, we analyze EnshrinedBlockchainOracle, relying on the independent $ETH token. The CES margins of EnshrinedBlockchainOracle before the event is

The event at affects EnshrinedBlockchainOracle's CES margin as well. First, EnshrinedBlockchainOracle has no as it relies on an independent token; thus, the attacker cannot gain from betting on price drops. Secondly, EnshrinedBlockchainOracle's decreases due to the drop of $ETH, by to become. Thirdly, as in the case of TraditionalBlockchainOracle, the drops by , becoming . Overall, the CES margins of EnshrinedBlockchainOracle after the event is

The figure below depicts the change in the CES margin of EnshrinedBlockchainOracle due to the same event. Importantly, under precisely the same event, EnshrinedBlockchainOracle remains CE secure.

The TraditionalBlockchainOracle CE security is far more susceptible to market fluctuations, whereas EnshrinedBlockchainOracle's security is resilient to external market forces.

Beyond Profit from Depreciation

Until now, we have focused on , an element that plays a crucial role in the TraditionalBlockchainOracle but not in EnshrinedBlockchainOracle. The analysis assisted in understanding how an independent token ($TRD) decreases the CES margin (Observation 1), making the protocol susceptible to attacks even if the is orders of magnitude greater than the (Observation 2), and could result in vulnerabilities in times of price fluctuations (Observation 3). But relying on a dedicated token $TRD bares other weaknesses. In the next section, we extend our analysis to challenges in the , particularly around issues of scaling and cost of capital.

Scaling Cost of Corruption with Total Value Secured

Assume that both protocols gain traffic and usage, resulting in a ten-fold increase in the TVS. The higher the TVS, the higher the ; hence, the CES margin decreases dramatically. For simplicity, we shall assume that the is a constant fraction of the TVS. How can the protocols regain their CE security?

To keep the CES margin positive, the should scale linearly with the TVS.

Recall that for TraditionalBlockchainOracle, where is the staked proportion of $TRD and is $TRD market cap. The TraditionalBlockchainOracle can hence increase its in two ways:

Passively, due to an increase in $TRD market cap.
Actively, by increasing the staked proportion .

Let us examine these two solutions. For the passive approach of experiencing an increase in $TRD market cap, note that the TraditionalBlockchainOracle cannot (legally) control the price and ensure a positive CES margin. Particularly, if the TVS fluctuation and the price fluctuation are not identical (correlation is not enough in this case), the TraditionalBlockchainOracle could become CES-vulnerable (a scenario similar to that in Observation 3). The active approach is also challenging, as it requires the TraditionalBlockchainOracle to call capital on demand while not being connected to an independent pool of capital.

EnshrinedBlockchainOracle can mitigate a TVS increase by controlling the stake, allowing the CoC to scale accordingly.

Cost of Capital

TraditionalBlockchainOracle's security scheme demands stakers hold $TRD , thus, stakers have to posses a token with relatively small market cap that depends on the protocol's performance. In contrast, EnshrinedBlockchainOracle could accept stake in $ETH, the base-layer's token. $ETH is less volatile, does not suffer from inflation, and is a multi-purpose token. These differences allow EnshrinedBlockchainOracleto demand less of its stakers compared to TraditionalBlockchainOracle's stakers, who may demand a premium for the additional risks they take (possessing $TRD and being exposed to a potential turbulent macroeconomic environment). Additionally, since EnshrinedBlockchainOracle's stakers could be re-stakers through Eigenlayer, their capital efficiency is maximized.

The Dual Token Model

An independent token makes EnshrinedBlockchainOracle significantly more CE secure than its counterparts utilizing a staking token. However, blockchain oracle sovereign tokens offer other advantages if decoupled from the CES risks.

By rewarding validators with a token, an incentive structure can be designed to increase the rate of rewards. Factors such as uptime, accuracy , and longevity of validators may increase their rewards earned. This achieves both incentivization of higher quality validation, and alignment of validators with the interests of the protocol.

A token vesting mechanism requires validators to be aligned with the network by locking their rewards and ensuring the commitment of the validators during the vesting period. This enhances the stability and security of the network.

A sovereign token design also allows for creating a punishment structures , where rewards can be revoked on non-malicious misbehavior. To avoid slashing Beacon Chain ETH , all non-malicious behavior will addressed with sovereign token punishments.

Implementing all of these mechanisms while having stake rooted in $ETH retains the CES benefits of EnshrinedBlockchainOracle while avoiding the CES vunerabilities of TraditionalBlockchainOracle's.

Proofs

Proof of Observation 1.

The TraditionalBlockchainOracle satisfies , with . EnshrinedBlockchainOraclehas the same and , but zero since it relies on the independent $ETH token. Its CES margin is thus .

Proof of Observation 2.

Assume that , namely that . Therefore,

The attack is thus beneficial as long as . Specifically, if the short interest is greater or equal to the stake proportion , the protocol becomes CE-vulnerable if the attacker expects a price drop of . This vulnerability still remains even if , since could potentially reach 1 and for any

Proof of Observation 3.

Assume that before the event, the market cap satisfies ; thus, the protocol is CE-secure since

Assume that the does not depend on the market cap . This is the case for, e.g., lending markets that mostly offer contracts in $ETH, etc. Since , there exists a real number , for , such that . Denote by the market cap of $TRD after the event. Consequently, if , it holds that

thus, the protocol is CE-vulnerable. In other words, if the is not affected by the event, a market cap decrease can spark an attack.

Proof of Observation 4.

For the sake of this proof, we use the subscript to refer to objects in time ; for instance, is the at time . The CES margin at time is given by

Assume at time the CES margin is positive and equals . Further, assume by contradiction that , where is the . Our assumption about the being a constant fraction of the TVS implies that also holds. By definition, there exists a time for which , and hence

therefore, the protocol is CE-vulnerable at time .

End Notes

In practice, the attacker would buy leveraged contracts and employ trading strategies. We focus on short positions, ensuring our model is simple yet aligned with reality.

Aegis - Validator Set Configuration

EO Validator Sets are integrated into the Ethereum PoS Validator Set through the Aegis protocol, enabling Ethereum validators to participate freely in the EO network permissionlessly.

Validator Set Membership

EO is an expansion chain that derives its cryptoeconomic security from Ethereum staking and benefits from the stability of ETH. Through innovative infrastructure provided by Eigenlayer, Ethereum Validators are able to participate in the EO blockchain as part of Validator Set. Validators can initiate a withdrawal from the Validator Set, and membership can be revoked for misbehavior, within Ethereum.

Operators

Installation

Prepare your system to run the EO operator.

Prerequisites

Registered EigenLayer Operator Account: Ensure you have a fully registered EigenLayer operator account. If you don't have one, follow the steps in the EigenLayer Operator Guide to create and fund your account.

Operator System Requirements

Operating System: Linux AMD x64
vCPUs: 2
Memory: 4 GiB
Storage: 100 GB

Prepare Local EO data validator

Clone repo

Registration

A guide to registering as an operator.

Generate a BLS pair

The registration process requires two sets of private keys: an ECDSA private key and a BLS private key. We recommend creating a new BLS pair for security reasons. Please generate one that will be dedicated to EO operations.

Encrypt your private keys

Encrypt your private keys. The encrypted private keys will be stored using the EO_KEYSTORE_PATH field. This is the recommended approach. If you encrypt a pasted private key it will never be saved as is anywhere.

Register with EO AVS

Operators need to have a minimum of 32 ETH delegated to them to opt-in to EO. Execute the following command:

The output should look like:

Generating an alias ECDSA address

Operators must declare another ECDSA address to use within the EO client. This isolates the Ethereum EigenLayer operator private key from EO operations, protecting access to Ethereum assets. You can import a private key or generate a new private key. To import, add --ecdsa-private-key <value> to the following command.

The output should look like:

Declaring an alias for the EO-chain

After generating the ECDSA alias address to use in EO-chain, declare it using your Ethereum EigenLayer identity, verifying the link between the two.

The output should look like:

Advance Settings and Troubleshooting

The following sections explain how to review status of the operator, troubleshoot registration issues or how to work with plain text private key (discourage)

Checking the status of EO operator AVS

The following command will print the status of the operator:

The output should look like:

Troubleshooting the register command

salt already spent - if you get the following error:

Add EO_SALT=<salt_in_hex> field to your .env file and retry running the register command.

(*) the EO_SALT should be in the following format EO_SALT=0x04 (even length hex number, and could be any number but must be even length)

Deregister from EO AVS

The following command will unregister and opt you out of the EO AVS:

The output should look like:

Work with plain text private keys (discouraged)

If you don't want to encrypt your private keys, update them in the data-validator/.env file. As this approach is highly discouraged, we recommend encrypting the private keys and never saving them anywhere on any machine.

Troubleshoot the declare-alias command

Contact our support in discord If you receive

Troubleshoot the data-validator execution

The following error, represent that your alias was not activated. Please contact our support in discord to activate your alias

Running the Client

Running your data validator and start signing transactions.

Running an EO AVS data validator

EO operator activation: Ensure your account has been activated. To check your current status, run the following (1 is activated, 0 is not).

Follow us on X (formerly known as Twitter) to see activation windows and more helpful info. For technical issues, please contact the EO team here on the operators-technical-help channel.

Note: Access to our client source code is currently restricted; however, interested parties may contact [email protected] to review the client for security reasons.

Run using docker

Navigate to the data validator directory.

Run the docker.

The command will start the data validator container. If you execute docker ps you should see an output indicating the eo-data-validator container has the " Up " status with ports assigned. You may view the container logs using

Data Validator V1 logs

The following example log messages confirm that your EO data validator software is up and running. Please ensure that your alias is declared and activated.

Data Validator V2 logs

The following example log messages confirm that your EO data validator software is up and running. Please ensure that your alias is declared and activated.

Stop EO data validator

To bring the containers down, run the following command:

Upgrade EO data validator

Upgrade the AVS software for your EO data validator by following the steps below:

Pull the latest repo

Merge .env changes. Go over .example_env or .example_env_holesky and merge new fields that do not appear in your local .env file
1. The structure of .example_env* have been changed to support data validator V2

Stop the existing services

Start your services again. If any specific instructions need to be followed for any upgrade, those instructions will be given with the specific release notes. Please check the latest on Github and follow the instructions before starting the services again.

Monitoring

Monitoring the health of your operator setup.

Monitoring, Metrics, Grafana dashboards

Quickstart

Here you'll find a quick start guide to run the Prometheus, Grafana, and Node exporter stack. Check out the README for more details. If you want to manually set this up, follow the steps below.

Metrics

Check the data validator metrics

Replace the EO_PROMETHEUS_PORT with the value of EO_PROMETHEUS_PORT from the data-validator/.env

Troubleshooting

If you see the following error:
Use the same command by prepending sudo in front of it.

Grafana

We use Grafana to visualize the metrics from the EO AVS.

You can use for it or any other Dashboard provider.

You should be able to navigate to http://<ip>:3000 and log in with admin/admin. This container of Grafana has a Prometheus data source setup using port 9090. If you change the Prometheus port, you need to add a new data source or update the existing data source. You can do this by navigating to http://<ip>:3000/datasources

Useful Dashboards

The EO Data Validator dashboard can be used to monitor performance, issues and data source statuses. Explaining each panel on below -

Score

The score panel shows the gauge metric eigen_performance_scorebetween 0-100 which is calculated based on the performance of the AVS operator and the performance of the backing services.

RPC Req

The RPC Req panel shows the counter and histogram of the total number of json-rpc <method>requests from the execution client.

EO Errors & EO Errors Avg 5 min

The EO Errors panel shows the counter for the number of errors encountered by the execution client.

Update Rate Duration (s)

The Update Rate duration panel helps visualize the frequency of updates in seconds. For example, in the above chart 91% of the submitted transactions were processed within 0.1 seconds.

EO Chain Performance (s)

The EO chain panel helps visualize the time between blocks on the EO chain. As per the above dashboard, the majority of the blocks are produced within 0.005 seconds.

Data Providers All

The Data providers panel shows the connection status of each data source that the validator pings for price feeds. If one of the sources shows 'FAIL' instead of 'OK', it means the connection to that source is broken.

You can find the json file to import the above dashboard . Once you have Grafana set up, feel free to import the dashboards.

Node exporter

The EO data validator emits EO specific metrics. However, it's also important to keep track of the node's health. For this, we will use which is a Prometheus exporter for hardware and OS metrics exposed by *NIX kernels, written in Go with pluggable metric collectors. By default, it is installed and started when you start the entire monitoring stack. If you want to modify the stack, you can install the binary or use docker to it.

In Grafana dashboards screen, import the node-exporter to see host metrics.

VMAgent

The vmagent is the docker that submits data validator metrics to EO central monitoring. This allow us to help you in troubleshoot your operator.

If you don't want to share with us the metrics, remove the vmagent from the docker-compose.yml in the data-validator/monitoring folder

🔍Concepts

EigenLayer

EigenLayer is a protocol built on Ethereum that introduces restaking, a new primitive in cryptoeconomic security. This primitive enables the reuse of consensus layer ETH. Users that stake ETH natively can opt-in to EigenLayer smart contracts to restake their ETH and extend cryptoeconomic security to additional applications on the network to earn additional rewards.

Reusing ETH to provide security across many services reduces capital costs for a staker to participate and significantly increases the trust guarantees to individual services.

EigenLayer allows services to slash validators based on malicious behavior or coordinated attacks, extending Ethereum's security guarantees to additional protocols.

See Eigenlayer's documentation for more details.

Data Validators

Data validators operate EO software to report data to the EO network. They are globally dispersed and are unaffiliated with EO. Data validators receive rewards and are subject to slashing via . Validation behavior is tracked, monitored, and cryptographically provable. This assures the EO network's security, as all validation activity is attributable and immutable , and forms the basis of rewards and slashing mechanisms which are applied to data validators.

Data validators retrieve data through an internet connection and provide cryptographic assurance of what they observe. They accomplish this assurance by submitting a . This signature is part of a highly secure cryptographic scheme optimized for threshold signatures.

Chain Validators

Chain validators operate the EO-Chain node software, creating blocks and processing transactions from Data Validators. They are globally dispersed and are unaffiliated with EO.

Chain Validators enable aggregation modules (smart contracts) to receive, validate, and aggregate data. They store all the cryptographic proof of actions that occurred on the EO-Chain and make that information accessible to the public.

Chain validators are critical to providing neutral aggregation and cryptographic attestations of validation. They provide the distributed infrastructure for an open, programmable, and efficient verifiable data layer.

eBFT

EO Byzantine Fault Tolerance (eBFT)

eBFT is a secure and novel network employed by EO. It consists of a consensus engine (IBFT) and External Validator Set Configuration Protocol (Aegis). eBFT utilizes the to seal blocks, provide specific network capabilities, and govern the network. EO EigenLayer-integrated smart contracts on Ethereum work in tandem with the consensus engine, fully implementing the Aegis Protocol.

eBFT's External Validator Set Configuration Protocol (Aegis) is implemented through a set of core smart contracts adhering to the Aegis protocol's specification. These contracts integrate restaking functionality, configure the validator set, and record commitments of the EO state.

OVS

The term OVS (Blockchain Oracle Validated Service) refers to custom blockchain oracle builders who develop their blockchain oracles on top of EO's infrastructure. By providing a platform for diverse participants to create specialized blockchain oracles, EO aims to foster a more competitive market that enhances the quality and reliability of data available to smart contracts. This approach not only democratizes access to data services but also ensures that blockchain applications can benefit from the expertise of a wide range of data and computation providers.

EO Chain

Expansion Chain

Expansion chains are blockchains that rely on a primary chain for security. They can be implemented using EigenLayer, Avalanche subnets and Polygon 2.0. Compared to a new blockchain, an expansion chain is easier to bootstrap, as it can rely on the security of the primary chain. Nodes can be required to stake on the primary chain, using its tokens as collateral to ensure their good behavior. Due to the established security of the primary chain, the value of its tokens is more stable, and the nodes are more likely to remain correct.

Aegis - Validator Set Configuration

EO-Chain as an Expansion Chain

In creating the architecture for a fully decentralized blockchain oracle network, EO aims to build a system inherently aware of its operational dynamics, ensuring comprehensive tracking of participant actions and outcomes within a transparent and immutable framework. Ideally, the best blockchain oracle infrastructure would be Ethereum itself, but the high costs and latency of on-chain processes make this infeasible. To address this, we established the "EO-Chain," a dedicated Proof-of-Stake (PoS) blockchain operated by Eigen operators—Ethereum validators restaking their ETH to secure the network.

The EO-chain offloads computation from the main blockchain, reducing costs and latency while maintaining decentralized incentives for blockchain oracle operators. This setup allows all calculations to occur on-chain, ensuring transparency and security.

Cryptoeconomic Security

The following sections provide a mathematical analysis, showing the enhanced security and stability of such a system.

Measuring Cryptoeconomic Security

Cryptoeconomic security (CES) is a useful measure for analysis, consider the following;

To assess whether attacking is beneficial, the attacker must take into account two elements: the Cost of Corruption () and the Profit from Corruption ().

signifies the potential gains the attacker would achieve post-successful manipulation. Our analysis requires a more subtle approach towards , and thus we divide into two sources as follows:

Profit from Manipulation () is the internal profit the attacker can gain by manipulating the protocol. For instance, for blockchain Oracle protocols, it is the profit that could be extracted by a malicious price update. The is upper-bounded by the protocol's Total Value Secured (TVS).
Profit from Depreciation () addresses the external profit the attacker can gain from betting on price volatility or depreciation through, e.g., derivative markets or short selling.

Notice that . A rational attacker will only attack if .

We capture this in the following definition.

Definition (CES Margin). A protocol has a -crypto-economic security margin, or a -CES margin, if

Profit from Short Selling

CES: A Tale of Two Blockchain Oracles

To demonstrate how the CES margin is affected by the nature of the protocol's token, we compare the following two scenarios:

EnshrinedBlockchainOracle, which relies on the base-layer's token that we denote by $ETH.
TraditionalBlockchainOracle, relying on its own token that we denote by $TRD.

The value and utility of $ETH are independent of EnshrinedBlockchainOracle's activities, unlike $TRD, whose value is closely tied to the operations of TraditionalBlockchainOracle.

Resilience to Attacks

. If the TraditionalBlockchainOracle, which relies on its own token $TRD, has a -CES margin, then EnshrinedBlockchainOracle, which relies on the base-layer's token $ETH, has a -CES margin.

Observation 1 is illuminating. To illustrate, assume that the TraditionalBlockchainOracle is a medium-sized decentralized service ( billion USD) with a reasonable short interest ().

Under a severe attack (), its CES margin is smaller by 70-100 million USD compared to EnshrinedBlockchainOracle.

Divergences in the Cost of Corruption

For any real number , the TraditionalBlockchainOracle could be CE-vulnerable even if the cost of corruption is times the profit of manipulation, i.e., .

Being able to short $TRD based on the TraditionalBlockchainOracle's operations increases the potential profit from attack, whereas there is no such benefit for attacking EnshrinedBlockchainOracle

Market Fluctuation Impact

Assume the protocol is CE-secure. Any fluctuation in $TRD market cap can make the protocol CE-vulnerable.

This observation is demonstrated using an example.

Example 1:

The figure below depicts the situation before and after , as we formally analyze next.

Let us analyze the CES margin. Before , we see that the CES margin is positive, since

Thus, the event at that sparked a price drop made the TraditionalBlockchainOracle CE vulnerable.

Next, we analyze EnshrinedBlockchainOracle, relying on the independent $ETH token. The CES margins of EnshrinedBlockchainOracle before the event is

The figure below depicts the change in the CES margin of EnshrinedBlockchainOracle due to the same event. Importantly, under precisely the same event, EnshrinedBlockchainOracle remains CE secure.

The TraditionalBlockchainOracle CE security is far more susceptible to market fluctuations, whereas EnshrinedBlockchainOracle's security is resilient to external market forces.

Beyond Profit from Depreciation

Scaling Cost of Corruption with Total Value Secured

To keep the CES margin positive, the should scale linearly with the TVS.

Recall that for TraditionalBlockchainOracle, where is the staked proportion of $TRD and is $TRD market cap. The TraditionalBlockchainOracle can hence increase its in two ways:

Passively, due to an increase in $TRD market cap.
Actively, by increasing the staked proportion .

EnshrinedBlockchainOracle can mitigate a TVS increase by controlling the stake, allowing the CoC to scale accordingly.

Cost of Capital

The Dual Token Model

Proofs

Proof of Observation 1.

The TraditionalBlockchainOracle satisfies , with . EnshrinedBlockchainOraclehas the same and , but zero since it relies on the independent $ETH token. Its CES margin is thus .

Proof of Observation 2.

Assume that , namely that . Therefore,

Proof of Observation 3.

Assume that before the event, the market cap satisfies ; thus, the protocol is CE-secure since

thus, the protocol is CE-vulnerable. In other words, if the is not affected by the event, a market cap decrease can spark an attack.

Proof of Observation 4.

For the sake of this proof, we use the subscript to refer to objects in time ; for instance, is the at time . The CES margin at time is given by

therefore, the protocol is CE-vulnerable at time .

End Notes

In practice, the attacker would buy leveraged contracts and employ trading strategies. We focus on short positions, ensuring our model is simple yet aligned with reality.

EO

Quickstart

What is EO?

hashtagTwo essential principles guide EO's protocol:

hashtagTrust Minimization

hashtagPermissionless Innovation

EO Vision

hashtagThe Current Reality

hashtagWhy Traditional Blockchain Oracles Fall Short

hashtagThe Two-Layer Solution

Understand EO

EO Trust Model

Architecture Overview

hashtag Ethereum Eigenlayer Integration

hashtagEO-Chain

hashtagValidator Clients

hashtagAggregator Modules

hashtagEO Endpoints

hashtagTarget Network Contracts

Data Processing

hashtagReporting

hashtagValidation & Aggregation

hashtagPublication

hashtagConsumption

hashtagConclusion

Security

Cryptoeconomic Security

hashtagMeasuring Cryptoeconomic Security

hashtagProfit from Short Selling

hashtagCES: A Tale of Two Blockchain Oracles

hashtagResilience to Attacks

hashtagDivergences in the Cost of Corruption

hashtagMarket Fluctuation Impact

hashtagExample 1:

hashtagBeyond Profit from Depreciation

hashtagScaling Cost of Corruption with Total Value Secured

hashtagCost of Capital

hashtagThe Dual Token Model

hashtagProofs

hashtagProof of Observation 1.

hashtagProof of Observation 2.

hashtagProof of Observation 3.

hashtagProof of Observation 4.

hashtagEnd Notes

Aegis - Validator Set Configuration

hashtagValidator Set Membership

Operators

Installation

hashtagPrerequisites

hashtagOperator System Requirements

hashtag​Prepare Local EO data validator

hashtagClone repo

Registration

hashtagGenerate a BLS pair

hashtagEncrypt your private keys

hashtagRegister with EO AVS

hashtagGenerating an alias ECDSA address

hashtagDeclaring an alias for the EO-chain

hashtagAdvance Settings and Troubleshooting

Running the Client

hashtagRunning an EO AVS data validator

hashtagRun using docker

hashtagStop EO data validator

hashtagUpgrade EO data validator

Monitoring

hashtagMonitoring, Metrics, Grafana dashboards

hashtagQuickstart

hashtagMetrics

hashtagCheck the data validator metrics

hashtagTroubleshooting

hashtagGrafana

hashtagNode exporter

hashtagVMAgent

🔍Concepts

EigenLayer

Data Validators

Chain Validators

eBFT

hashtagEO Byzantine Fault Tolerance (eBFT)

OVS

Two essential principles guide EO's protocol:

Trust Minimization

Permissionless Innovation

The Current Reality

Why Traditional Blockchain Oracles Fall Short

The Two-Layer Solution

Ethereum Eigenlayer Integration

EO-Chain

Validator Clients

Aggregator Modules

EO Endpoints

Target Network Contracts

Reporting

Validation & Aggregation

Publication

Consumption

Conclusion

Measuring Cryptoeconomic Security

Profit from Short Selling

CES: A Tale of Two Blockchain Oracles

Resilience to Attacks

Divergences in the Cost of Corruption

Market Fluctuation Impact

Example 1:

Beyond Profit from Depreciation

Scaling Cost of Corruption with Total Value Secured

Cost of Capital

The Dual Token Model

Proofs

Proof of Observation 1.

Proof of Observation 2.

Proof of Observation 3.

Proof of Observation 4.

End Notes

Validator Set Membership

Prerequisites

Operator System Requirements

Prepare Local EO data validator

Clone repo

Generate a BLS pair

Encrypt your private keys

Register with EO AVS

Generating an alias ECDSA address

Declaring an alias for the EO-chain

Advance Settings and Troubleshooting

Running an EO AVS data validator

Run using docker

Stop EO data validator

Upgrade EO data validator

Monitoring, Metrics, Grafana dashboards

Quickstart

Metrics

Check the data validator metrics

Troubleshooting

Grafana

Node exporter

VMAgent

EO Byzantine Fault Tolerance (eBFT)

OVS

Expansion Chain

EO-Chain as an Expansion Chain

Reporting

Validation & Aggregation

Publication

Consumption

Conclusion

Two essential principles guide EO's protocol:

Trust Minimization

Permissionless Innovation

The Current Reality

Why Traditional Blockchain Oracles Fall Short

The Two-Layer Solution

Ethereum Eigenlayer Integration

EO-Chain

Validator Clients

Aggregator Modules

EO Endpoints

Target Network Contracts

Validator Set Membership

OVS