{"id":36494974,"url":"https://github.com/pantos-io/research-go-ethrelay","last_synced_at":"2026-01-12T02:00:15.221Z","repository":{"id":89507097,"uuid":"194891339","full_name":"pantos-io/research-go-ethrelay","owner":"pantos-io","description":"Go-library and command-line interface (CLI) to interact with the Testimonium prototype","archived":false,"fork":false,"pushed_at":"2022-04-11T08:51:24.000Z","size":14516,"stargazers_count":21,"open_issues_count":1,"forks_count":6,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-08-14T18:58:45.933Z","etag":null,"topics":["blockchain","blockchain-technology","cross-chain","cross-chain-communication","interoperability"],"latest_commit_sha":null,"homepage":"https://dsg.tuwien.ac.at/projects/tast/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pantos-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-07-02T15:36:58.000Z","updated_at":"2024-07-19T14:44:03.000Z","dependencies_parsed_at":"2023-07-14T22:56:13.931Z","dependency_job_id":null,"html_url":"https://github.com/pantos-io/research-go-ethrelay","commit_stats":null,"previous_names":["pantos-io/go-testimonium","pantos-io/go-ethrelay"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/pantos-io/research-go-ethrelay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantos-io%2Fresearch-go-ethrelay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantos-io%2Fresearch-go-ethrelay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantos-io%2Fresearch-go-ethrelay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantos-io%2Fresearch-go-ethrelay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pantos-io","download_url":"https://codeload.github.com/pantos-io/research-go-ethrelay/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantos-io%2Fresearch-go-ethrelay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28331499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","blockchain-technology","cross-chain","cross-chain-communication","interoperability"],"created_at":"2026-01-12T02:00:10.202Z","updated_at":"2026-01-12T02:00:15.193Z","avatar_url":"https://github.com/pantos-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go-ETH Relay\n\nThis project contains a Go library and a command-line interface (CLI) to interact with the [ETH Relay](https://github.com/pantos-io/ethrelay) prototype.\n\nETH Relay enables the cross-blockchain verification of transactions.\nThis makes it possible that a destination blockchain can verify if a certain transaction (or receipt, or state) is included\nin a different source blockchain without relying or trusting a third-party.\n\nDetailed information about how the prototype works can be found [here](https://dsg.tuwien.ac.at/projects/tast/pub/tast-white-paper-6.pdf).\n\n\u003e _Important: ETH Relay is a research prototype.\n    It represents ongoing work conducted within the [TAST](https://dsg.tuwien.ac.at/projects/tast/)\n    research project. Use with care._\n\n## Prerequisites\n\nYou need to have [Golang](https://golang.org/doc/install) and [Ganache](https://www.trufflesuite.com/ganache) (\u003e= 2.1.0) installed.\n\n## Get Started\n\n_The following setup will take you through the deployment of ETH Relay with a local Ethereum blockchain (Ganache)\nas the destination chain and the main Ethereum chain as the source chain.\nInformation on how to connect to other blockchains can be found [here](#Configuration)._\n\n1. Run `git clone https://github.com/pantos-io/go-ethrelay.git` to clone the repository on your local machine and then run `go get ./cmd/go-ethrelay` in the go-ethrelay folder to install the library and the CLI.\nCheck that the CLI was installed correctly by running `go-ethrelay`. In case `go-ethrelay` command is not found, have a look at the [Troubleshooting](#Troubleshooting) section.\nIf you want to install the library manually, you can simply clone this repository and run any command in the cloned directory with `go run ./cmd/go-ethrelay [command]`.\n\n2. Run `go-ethrelay init` to initialize the client.\nIf you encounter any problems calling this command, get sure the rights are properly adjusted so Go can create the ethrelay.yml config file in the current folder.\nIt is also possible to generate the file by hand or change the example config file under configs/ethrelay.example.yml contained in this repo.\n\n3. Start Ganache (should start on the default port 7545, if not, change this in the config file).\n\n4. Deploy the Ethash contract with `go-ethrelay deploy ethash`.\nThis deploys the contract responsible for verifying the Proof of Work (PoW) of a block.\n\n5. Submit the correct epoch data to the Ethash contract with `go-ethrelay submit epoch \u003cEPOCH_NO\u003e`.\nDepending on which block will be submitted as genesis block to the ETH Relay contract in the following step,\nthe correct epoch data can be calculated as `EPOCH_NO = BLOCK_NO / 30000` floored. This may take a while.\n    \u003e e.g., for genesis block 8084509, the correct epoch data is 269\n\n6. Deploy the ETH Relay contract with `go-ethrelay deploy ethrelay --genesis \u003cBLOCK_NO\u003e`.\nThis deploys the contract responsible for the verification of transactions (or receipts, or state).\nThe `genesis` parameter specifies the first block of the source chain which will be submitted to\nthe ETH Relay contract. Verifications will be possible for all subsequent blocks.\n\nETH Relay is now setup. In order to submit blocks, a stake has to be submitted first. After you deposited some stake, you can submit block data from the source chain to the destination chain,\nand request verifications of transactions, and dispute illegal blocks.\n\n## Usage\n\nThe CLI can be started with `go-ethrelay [command]` where `[command]` is one of the commands below.\n\nUse `go-ethrelay [command] --help` for more information about a command.\n\n---\n\n`init`: Initializes the client by creating an ethrelay.yml file in the current directory that acts as config file for all command calls.\n\n`account`: Prints the address of the current account\n\n`balance`: Prints the balance of the current account\n\n`deploy ethash`: Deploys the Ethash smart contract on a destination chain\n\n`deploy ethrelay`: Deploys the ETH Relay contract on a destination chain\n\n`dispute [blockHash]`: Disputes the submitted block header with the specified hash\n\n`generate [blockNumber]`: Generates and exports test data for the Ethrelay project\n\n`get block [blockHash]`: Retrieves the block with the specified hash\n\n`get transaction [txHash]`: Retrieves the transaction with the specified hash\n\n`get longestchainendpoint`: Retrieves the most recent block hash of the longest chain in the ETH Relay contract on a destination chain\n\n`stake get`: Retrieves the amount of stake deposited in the relay-contract on a destination chain\n\n`stake deposit [amountInWei]`: Deposits amountInWei stake of the account balance in the contract\n\n\u003e e.g. `stake deposit 25000000000000000000` deposits 25 ETH\n\n`stake withdraw [amountInWei]`: Withdraws the submitted stake back to the account balance. Remember that stake can be locked in the contract when a block was submitted and you have to wait until it is unlocked again.\n\n`submit block [blockNumber or blockHash]`: Submits the specified block header from a source chain to a destination chain\n\n`submit epoch [epoch]`: Sets the epoch data for the specified epoch on a destination chain\n\n`verify block [blockHash]`: Verifies a block from the source chain on a destination chain\n\n`verify transaction [txHash]`: Verifies a transaction from the source chain on a destination chain\n\n`verify receipt [txHash]`: Verifies a receipt from the source chain on a destination chain\n\n## Quick Setup\n\nThere is also a shell script in this repository, `scripts/setup-relay.sh`. This script helps researchers and developers to quickly setup\na working version of the relay with default-values and assuming a local Ganache instance. The call to this script is:\n\n`./scripts/setup-relay.sh [ganacheAccountPrivateKey] [genesisBlock] [stakeInETH]`\n\nExample call:\n\n```shell\n./scripts/setup-relay.sh 0x45b5ffd7266ec7131f31f94da843b99fd270b46d94bf01368ceeb936649dfc3b 11367417 25\n```\n\n## Configuration\n\nThe relay client uses a configuration file called `ethrelay.yml` file.\n\nThe default file looks like this:\n\n```yml\nchains:\n  sources:\n    mainnet:\n      type: wss\n      url: mainnet.infura.io/ws/v3/1e835672adba4b9b930a12a3ec58ebad\n  destinations:\n    local:\n      port: 7545\n      type: http\n      url: localhost\nprivatekey: 0x0\n```\n\nChain `mainnet` contains connection configuration for the main Ethereum chain (via Infura).\nChain `local` contains connection configuration for a local chain (e.g., run via Ganache).\n\nYou can configure the relay client for other Ethereum blockchains (there is no upper limit).\nJust manually add or edit a chain entry under the `sources` or `destinations` key.\nKey `type` refers to the connection type (e.g., http, https, ws, wss), `url` refers to the URL\nand `port` refers to the port number under which the specific chain is reachable. If no type is specified, https is used.\nIf no port is defined, it is determined by the default port of the type.\n\nIf you have already deployed the Ethash and ETH Relay contracts, you might find further entries, i.e.\n`ethashaddress` and `ethrelayaddress` under a specific chain config:\n\n```yml\nchains:\n  destinations:\n    local:\n      ethashaddress: 0x123abc...\n      ethrelayaddress: 0xabc123...\n```\n\nThese are the addresses that the client uses to interact with the ETH Relay smart contracts.\nIf you deployed the contracts manually, just add the entries.\n\n## Troubleshooting\n\n### Dispute causes error: \"VM Exception while processing transaction: revert\"\n\nIf disputing a certain block causes a generic revert exception, make sure you are running Ganache version \u003e= 2.1.0.\n\n### Some Go libraries or dependencies could not be found or have wrong naming/versions\n\nMaybe you have some old dependencies or versions installed and an error like the following occurs:\n\n```text\ngo: github.com/pantos-io/go-ethrelay@v0.1.0: parsing go.mod:\n    module declares its path as: github.com/pantos-io/go-testimonium\n    but was required as: github.com/pantos-io/go-ethrelay\n```\n\nTry to clean the modules folder of Go with `go clean -modcache` and install the modules with `go get` again.\n\n#### go-ethrelay command not found after installing from Github\n\nAdd the GOBIN and/or GOPATH to your PATH-variable. Find more information about GOBIN and GOPATH [here](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable).\n\n#### Client won't start because of Go problems\n\nGet sure your Go-path variables like GOHOME, GOPATH und GOBIN are set properly.\n\n#### Client won't work because issues to permissions or projectId (e.g. forbidden: project ID is required)\n\nIf you are using Infura, check that your url and protocol is correct and the permissions are properly set in the Infura admin panel.\n\n## How to Contribute\n\nETH Relay is a research prototype. We welcome anyone to contribute.\nFile a bug report or submit feature requests through the [issue tracker](https://github.com/pantos-io/go-ethrelay/issues).\nIf you want to contribute feel free to submit a pull request.\n\n## Useful resources\n\n* [Etherscan](https://etherscan.io)\n* [Ethereum Development with Go](https://goethereumbook.org)\n* [Solidity documentation](https://solidity.readthedocs.io)\n\n## Acknowledgement\n\nThe development of this prototype was funded by [Pantos](https://pantos.io/) within the [TAST](https://dsg.tuwien.ac.at/projects/tast/) research project.\n\n## Licence\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpantos-io%2Fresearch-go-ethrelay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpantos-io%2Fresearch-go-ethrelay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpantos-io%2Fresearch-go-ethrelay/lists"}