ETH Relay
This project contains Ethereum smart contracts that enable the verification of transactions of a "target" blockchain on a different "verifying" blockchain in a trustless and decentralized way.
This means a user can send a request to the verifying chain asking whether or not a certain transaction has been included in the target chain and is verified. The verifying chain then provides a reliable and truthful answer without relying on any third party trust.
The ability to verify transactions "across" different blockchains is vital to enable applications such as cross-blockchain token transfers.
Important: ETH Relay is a research prototype. It represents ongoing work conducted within the TAST research project. Use with care.
Get Started
ETH Relay is best enjoyed through the accompanying go-ethrelay CLI tool that can be found
here.
However, if you want to deploy the contracts manually, follow the steps below.
Installation
The following guide will walk you through the deployment of ETH Relay with a local blockchain (Ganache) as the verifying chain and the main Ethereum blockchain as the target blockchain. This means blocks from the main Ethereum blockchain (source) are forwarded to the ETH Relay contract on the local blockchain (destination).
Direct installation
In this section, we describe how to install ETH Relay directly based on Node.js and Truffle. You can find an alternative installation guide based on Docker below.
Direct installation: prerequisites
You need to have the following tools installed:
- Node.js (version >= 10.1)
- Truffle (version >= 5.2.0)
- Ganache (version >= 2.1)
- Solidity (0.9 > version >= 0.8.4)
For simply running the tests, it is not necessarily required to use Ganache as Truffle provides an integrated blockchain that is used for automatic testing.
Direct installation: deployment
- Clone the repository:
git clone [email protected]:pantos-io/ethrelay.git - Change into the project directory:
cd ethrelay/ - Install all dependencies:
npm install - Deploy contracts:
truffle migrate --reset
Direct installation: testing
Run the tests with truffle test.
Docker installation
As an alternative to the direct installation method described above, you can install ETH Relay with Docker.
Docker installation: prerequisites
You need to have
- Docker (version >= 19)
installed.
Docker installation: deployment
There are two different ways how to deploy ETH Relay with Docker. First alternative:
- Run Ganache:
docker run --network=host trufflesuite/ganache-cli -p 7545(alternatively, you can also run the GUI variant of Ganache without Docker) - Deploy contracts:
docker run --network=host pantosio/ethrelay migrate --reset
Second alternative:
- Clone the repository:
git clone [email protected]:pantos-io/ethrelay.git - Change into the project directory:
cd ethrelay/ - Run Ganache and deploy contracts:
docker-compose up
Docker installation: testing
Run the tests with docker run --network=host pantosio/ethrelay test.
Export contract
For the export script to work correctly,
you should set the GOETHRELAY environment variable to the project root of go-ethrelay on your machine, e.g.,
export GOETHRELAY=~/code/.../go-ethrelay/. By default, it exports to ${GOPATH}/src/github.com/pantos-io/go-ethrelay.
To generate the Go contract files and export them to the go-ethrelay project run ./export.sh
How it works
Users can query the ETH Relay contract living on the verifying blockchain by sending requests like "Is transaction tx in block b part of the target blockchain?" For the contract to answer the request it has to verify two things.
- Verify that block b is part of the target blockchain.
- Verify that transaction tx is part of block b.
The way this is achieved is the following:
1. Verifying Blocks
To verify that a block b is part of the target blockchain, the ETH Relay contract on the verifying chain needs to know about the state of the target blockchain.
For that, clients continuously submit block headers of the target chain to the ETH Relay contract. For each block header that the contract receives, it performs a kind of light validation:
- Verify that the block's parent already exists within the contract.
- Verify that the block's number is exactly one higher than its parent.
- Verify that the block's timestamp is correct.
- Verify that the block's gas limit is correct.
If these checks are successful, the contract accepts the block and stores it internally.
The contract does not verify the Proof of Work (PoW) for each block it receives, as validating the PoW for every block becomes very expensive. Instead, the contract assigns a dispute period to newly added blocks. Within this period, clients have the possibility to dispute any block they think is illegal.
In case of a dispute, the full PoW verification is carried out. If the verification fails, the block and all its successors are removed from the contract.
This way, the target chain is replicated within the ETH Relay contract on the verifying chain, so that the contract can reliably provide an answer to the question whether or not a block b is part of the target blockchain.
2. Verifying Transactions
So now the contract knows whether or not a block b is part of the target blockchain. It now needs to verify that the transaction tx is part of block b.
Whenever a client sends a transaction verification request to the contract, it needs to generate a Merkle Proof first. The Merkle Proof is sent with the request and is then verified by the contract. If the proof validation is successful, transaction tx is part of block b. If the validation fails, tx is not part of b.
A more detailed explanation of the inner workings can be found here.
Troubleshooting
Wrong Compiler Version
Error: Source file requires different compiler version (current compiler is 0.6.12+commit.27d51765.Linux.g++) - note that nightly builds are considered to be strictly less than the released version
--> contracts/Ethrelay.sol:2:1:
|
2 | pragma solidity >=0.7.0 <0.9.0;
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Make sure the recommended Solidity compiler version (0.9 > version >= 0.7) is used with solc --version.
Legacy Access Request Rate Exceeded Error
When running the tests you might run into the following error: Returned error: legacy access request rate exceeded or Returned error: project ID is required.
To fix this error, create an account with Infura and create a new Infura project.
Then in file ./constants.js change the constant INFURA_ENDPOINT to the mainnet URL from your Infura project (e.g. https://mainnet.infura.io/v3/ab050ca78686478a9e9b06dfc4b2f069).
Wrong Truffle Version
When running the tests you might run into the following error: TypeError: param.substring is not a function.
To fix this error, make sure the recommended Truffle version is used, i.e. v5.1.29.
How to contribute
ETH Relay is a research prototype. We welcome anyone to contribute. File a bug report or submit feature requests through the issue tracker. If you want to contribute feel free to submit a pull request.
Acknowledgements
- The development of this prototype was funded by Pantos within the TAST research project.
- The original code for the Ethash contract that is partly used in this project comes from the smartpool project.
- The code for the RLPReader contract that is partly used in this project comes from Hamdi Allam with parts of it taken from Andreas Olofsson.
Licence
This project is licensed under the MIT License.