README
¶
Ethergo
Overview
Ethergo is a comprehensive embedded test suite for Synapse, built using the Go programming language. It provides the functionality to deploy contracts to various backends, streamlining the testing process for different types of blockchain networks. The module is organized into several subdirectories, each dedicated to specific aspects of the testing process, such as backends, chain interaction, contract management, and signing utilities.
Some key components of Ethergo include:
- Backends: Ethergo supports different test backends for testing against various types of chains, including Anvil, Ganache, Geth, Preset, and Simulated backends.
- Chain: This subdirectory provides tools for chain interaction, such as a chain client, a chain watcher, a deterministic gas estimator, and a client interface for the chain watcher.
- Contracts: This section contains interfaces for working with contracts, including deployer and manager functionalities.
- Manager: The manager is responsible for handling contract deployments.
- Signer: Ethergo offers signing and transaction submission utilities, with various adapters for signing transactions and handling race conditions with nonces. It also includes a wallet interface capable of importing keys from seed phrases, private keys, and mnemonics.
To see a working example of Ethergo in action, refer to the example folder, which provides a complete demonstration of how to use the deployer and manager components. Please note that the APIs are subject to change.
Directory Structure
root ├── backends: Contains different test backends for testing against different types of chains │ ├── anvil: Contains the anvil backend. This is useful for fork testing and requires docker. It aloso contains cheatcodes for testing detailed [here](https://book.getfoundry.sh/anvil/) │ ├── ganache: Contains the ganache backend. This is useful for fork testing and requires docker. This is currently using an older version of ganache, but will be updated to use the latest version. See [here](https://github.com/trufflesuite/ganache) for details. │ ├── geth: Contains an embedded geth backend. This is useful for testing against a local geth instance without forking capabilities. This does not require docker and runs fully embedded in the go application, as such it is faster than the docker-based backends, but less versatile. Used when an rpc address is needed for a localnet. │ ├── preset: Contains a number of preset backends for testing. │ ├── simulated: The fastest backend, this does not expose an rpc endpoint and uses geth's [simulated backend](https://goethereumbook.org/en/client-simulated/) ├──chain: Contains a client for interacting with the chain. This will be removed in a future version. Please use [client](./client) going forward. │ ├── chainwatcher: Watches the chain for events, blocks and logs │ ├── client: Contains eth clients w/ rate limiting, workarounds for bugs in some chains, etc. │ ├── gas: Contains a deterministic gas estimator │ ├── watcher: Client interface for chain watcher.├── contracts: Contains interfaces for using contracts with the deployer + manager ├── client: Contains an open tracing compatible ethclient with batching. ├── examples: Contains a full featured example of how to use deployer + manager & a signer. ├── forker: Allows the use of fork tests in live chains without docker using an anvil binary. ├── listener: Drop-in contract listener ├── manager: Manages contract deployments. ├── mocks: Contains mocks for testing various data types (transactions, addresses, logs, etc) ├── parser: Parse hardhat deployments │ ├── hardhat: Parses hardhat deployments │ ├── abi: Parses abi function input │ ├── rpc: Parses rpc requests/responses ├── signer: Signing + tx submission utilities │ ├── nonce: Automatically handles race conditions with nonces, used in backends. │ ├── signer: Various adapters for signing transactions │ ├── awssigner: Use AWS KMS to sign transactions │ ├── gcpsigner: Use GCP Cloud KMS to sign transactions │ ├── localsigner: Use a local signer to sign transactions │ ├── wallet: Wallet contains a wallet interface. It is capable of importing keys from seed phrases, private keys, and mnemonics. ├── submitter: Generic tx submitter, currently not stable enough for general use. ├── util: various utilities used throughout the library
Directories
¶
| Path | Synopsis |
|---|---|
|
Package backends provides different kinds of backends you can test against that conform to a common interface thesse allow you to test eth functionality against a variety of backends
|
Package backends provides different kinds of backends you can test against that conform to a common interface thesse allow you to test eth functionality against a variety of backends |
|
anvil
Package anvil is an anvil test backend.
|
Package anvil is an anvil test backend. |
|
base
Package base contains a common interface to be used by multiple backends.
|
Package base contains a common interface to be used by multiple backends. |
|
geth
Package geth handles creating mock geth clients and simulated backends
|
Package geth handles creating mock geth clients and simulated backends |
|
preset
Package preset defines preset backends that can be used to create backends of different types
|
Package preset defines preset backends that can be used to create backends of different types |
|
simulated
Package simulated represents a simulated backend.
|
Package simulated represents a simulated backend. |
|
simulated/multibackend
Package multibackend contains a copy of https://github.com/ethereum/go-ethereum/blob/master/accounts/abi/bind/backends/simulated.go that allows use with multiple chains by exporting new methods.
|
Package multibackend contains a copy of https://github.com/ethereum/go-ethereum/blob/master/accounts/abi/bind/backends/simulated.go that allows use with multiple chains by exporting new methods. |
|
Package chain contains a common interface for running commands against evm rpc's.
|
Package chain contains a common interface for running commands against evm rpc's. |
|
chainwatcher
Package chainwatcher provides methods/interfaces for chain agnostic event tracking
|
Package chainwatcher provides methods/interfaces for chain agnostic event tracking |
|
client
Package client provides a common interface for eth-based clients used with chain It defines the minimum necessary methods to create a chain and implements a rate limiter and metrics around client usage- useful for monitoring and debugging.
|
Package client provides a common interface for eth-based clients used with chain It defines the minimum necessary methods to create a chain and implements a rate limiter and metrics around client usage- useful for monitoring and debugging. |
|
client/near
Package near contains workaround for the aurora rpc
|
Package near contains workaround for the aurora rpc |
|
gas
Package gas handles generating deterministic gas price estimates.
|
Package gas handles generating deterministic gas price estimates. |
|
gas/backend
Package backend contains the common oracle backend for gas estimators
|
Package backend contains the common oracle backend for gas estimators |
|
gas/londinium
Package londinium as the name implies, contains the pre-london version of the gas price estimation
|
Package londinium as the name implies, contains the pre-london version of the gas price estimation |
|
gas/london
Package london provides wrappers to deterministically generate a tip cap + fee cap for evm based chains.
|
Package london provides wrappers to deterministically generate a tip cap + fee cap for evm based chains. |
|
watcher
Package watcher watches the chain for events
|
Package watcher watches the chain for events |
|
Package chaindata provides the chain metadata.
|
Package chaindata provides the chain metadata. |
|
Package client implements the Ethereum RPC API client with tracing and batch requests.
|
Package client implements the Ethereum RPC API client with tracing and batch requests. |
|
Package contracts contains contract types
|
Package contracts contains contract types |
|
Package deployer contains utilities for deploying test contracts
|
Package deployer contains utilities for deploying test contracts |
|
examples
|
|
|
contracttests
Package example defines an example project that uses ethergo
|
Package example defines an example project that uses ethergo |
|
contracttests/counter
Code generated by synapse abigen DO NOT EDIT.
|
Code generated by synapse abigen DO NOT EDIT. |
|
signer-example
Package main provides the command line interface for the example signer.
|
Package main provides the command line interface for the example signer. |
|
signer-example/cmd
Package cmd provides the command line interface for the opbot.
|
Package cmd provides the command line interface for the opbot. |
|
signer-example/config
Package config provides configuration for the example signer.
|
Package config provides configuration for the example signer. |
|
signer-example/metadata
Package metadata provides a metadata service for the example signer.
|
Package metadata provides a metadata service for the example signer. |
|
Package forker allows a user to fork an arbitrary blockchain and make rpc calls against it.
|
Package forker allows a user to fork an arbitrary blockchain and make rpc calls against it. |
|
Package internal contains dev dependencies required for running developer tasks (coverage testing, etc) that are not required by the project itself.
|
Package internal contains dev dependencies required for running developer tasks (coverage testing, etc) that are not required by the project itself. |
|
testconsts
Package testconsts contains constants for testing
|
Package testconsts contains constants for testing |
|
Package listener is the listener used to pull in chain events
|
Package listener is the listener used to pull in chain events |
|
db
Package db provides the database layer for the chain listener.
|
Package db provides the database layer for the chain listener. |
|
Package manager manages deployers to make them as simple as possible
|
Package manager manages deployers to make them as simple as possible |
|
Package mocks mocks address, clients, etc for evm chains TODO: rename this package, as it's ignored by codecov.
|
Package mocks mocks address, clients, etc for evm chains TODO: rename this package, as it's ignored by codecov. |
|
parser
|
|
|
abiutil
Package abiutil contains helpers for parsing contract metadata
|
Package abiutil contains helpers for parsing contract metadata |
|
abiutil/internal
Package internal contains test data for the abi package
|
Package internal contains test data for the abi package |
|
hardhat
Package hardhat provides an interface for parsing hardhat deployments
|
Package hardhat provides an interface for parsing hardhat deployments |
|
rpc
Package rpc provides a parser for the RPC API requests.
|
Package rpc provides a parser for the RPC API requests. |
|
Package signer provides a common interface for signing
|
Package signer provides a common interface for signing |
|
config
Package config contains a canonical configuration for signer.
|
Package config contains a canonical configuration for signer. |
|
nonce
Package nonce is the nonce manager
|
Package nonce is the nonce manager |
|
signer/awssigner
Package awssigner contains a new signer that uses aws-kms as an hsm
|
Package awssigner contains a new signer that uses aws-kms as an hsm |
|
signer/awssigner/kmsmock
Package kmsmock sets up a mock kms server that is used for testing our kms driver TODO: we should consider moving this to a common testutils/mocking folder or something internal to avoid exporting
|
Package kmsmock sets up a mock kms server that is used for testing our kms driver TODO: we should consider moving this to a common testutils/mocking folder or something internal to avoid exporting |
|
signer/awssigner/kmsmock/internal
Package internal contains modules exported from local-kms in order to avoid rewriting code
|
Package internal contains modules exported from local-kms in order to avoid rewriting code |
|
signer/gcpsigner
Package gcpsigner utilizes the Key Management Service (KMS) from the Google Cloud Platform (GCP).
|
Package gcpsigner utilizes the Key Management Service (KMS) from the Google Cloud Platform (GCP). |
|
signer/gcpsigner/gcpmock
Package gcpmock provides a mock client for testing purposes.
|
Package gcpmock provides a mock client for testing purposes. |
|
signer/localsigner
Package localsigner is a local signer
|
Package localsigner is a local signer |
|
wallet
Package wallet contains utilities for importing/using eth wallets.
|
Package wallet contains utilities for importing/using eth wallets. |
|
Package submitter provides a simple interface for submitting txs to multiple chains and retrying.
|
Package submitter provides a simple interface for submitting txs to multiple chains and retrying. |
|
config
Package config provides a configuration struct and getters for the submitter.
|
Package config provides a configuration struct and getters for the submitter. |
|
db
Package db provides a database interface for the submitter.
|
Package db provides a database interface for the submitter. |
|
db/txdb
Package txdb provides a database implementation that simplements the submitter db service.
|
Package txdb provides a database implementation that simplements the submitter db service. |
|
Package util contains eth type utils
|
Package util contains eth type utils |
Click to show internal directories.
Click to hide internal directories.