Ethereum Network Automation
Ethereum Network Automation (ethereum-network-automation
) is a comprehensive package designed for the setup and management of Ethereum networks, particularly focusing on the Clique consensus algorithm for Proof of Authority (PoA). Unlike tools that rely on virtualization of the Ethereum Virtual Machine (EVM), such as @ethereumjs/vm (used by Hardhat and Remix), this package facilitates a more authentic environment for testing the interoperability between smart contracts across different EVM networks.
Introduction
The primary goal of ethereum-network-automation
is to enable developers and blockchain enthusiasts to easily deploy and manage Ethereum networks. By leveraging both Geth for direct blockchain interactions and Docker for containerized environments, it offers a versatile toolkit for experimenting with Ethereum's PoA consensus and beyond.
Prerequisites
Before you begin deploying networks with this package, it's crucial to have the necessary tools and environments set up. Here are the prerequisites based on your deployment method:
Local Deployments Using Geth
For deploying Ethereum networks locally using Geth, you'll need:
- Geth: Version 1.13.14-stable or later installed on your system. Geth is the Go Ethereum client and is essential for running nodes on the Ethereum network.
Docker Deployments
For deploying networks within Docker containers, you'll need:
- Docker: Ensure Docker is installed and running on your system. This package uses the
ethereum/client-go:stable
Docker image for deployments, providing a standardized Ethereum client environment.
Windows Users
This package is optimized for Linux-based environments, including macOS and Linux distributions. Windows users can still utilize this package by setting up WSL (Windows Subsystem for Linux), which allows you to run a Linux environment directly on Windows, without the overhead of a traditional virtual machine.
Setting Up WSL
To use this package on Windows, follow these steps to set up WSL:
- Enable WSL: Open PowerShell as Administrator and run:
wsl --install
. This command enables WSL on Windows and installs the Ubuntu Linux distribution by default.
- Restart your computer if required by the installation process.
- Launch WSL: After installation, open the Ubuntu app from the Start menu to set up your new Linux distribution, including creating a user account and password.
- Install Prerequisites: Inside the WSL environment, install Geth and Docker following the Linux installation instructions. Note that Docker Desktop for Windows now supports integration with WSL 2, enabling you to run Docker containers directly within your WSL distribution.
Important Notes
- When running commands for this package in a Windows environment, ensure you're operating within the WSL terminal to avoid compatibility issues.
- Due to the use of Linux-specific features and filesystem permissions, running this package directly on Windows (outside of WSL) is not supported and may lead to unexpected behavior.
Security Notice
This package comes with predefined wallets intended solely for local development and testing purposes. These wallets are not secure for user or production use. While the package provides functionality to create new accounts and node accounts, it's essential to handle such operations with caution. Any use of these features is at the user's own risk.
Quick Start
Install the package using npm:
npm i ethereum-network-automation
Below we can see a simple example of how to deploy networks using Docker and Geth.
const { pethPoa } = require('ethereum-network-automation')
async function startDockerNetwork(chainId) {
await pethPoa.docker.initAndDeployNetwork(chainId);
}
async function startLocalNetwork(chainId) {
await pethPoa.geth.initAndStartNetwork(chainId);
}
startLocalNetwork(54321);
startDockerNetwork(666777);
Predefined Node Addresses
The package comes equipped with predefined addresses for initializing networks quickly. These addresses are as follows:
- Bootstrap Node Address:
"0xCeB5ca48b5DE1839379FAEDD0572F7D59B279749"
- Signer Node Address:
"0x64fB496Bbfd447Dba254aFe4E28a325cb19ec25f"
- RPC Node Address:
"0x46198b00f237407133da9CcFb2D567dF159284D4"
- Member Node Address:
"0xBa551f402cfC912482cB15466641E6FC3B2D63f2"
Additionally, the package currently includes three addresses for each node type:
- Bootstrap:
"0xCeB5ca48b5DE1839379FAEDD0572F7D59B279749"
"0x3DACb6190a02bB8762b769fA3805A53ced2daecD"
"0xeA9c0401958De72D6ccED22dA3134e296282fc1b"
- Signer:
"0x64fB496Bbfd447Dba254aFe4E28a325cb19ec25f"
"0x6D327167519f708706CaA82c22A51f9170E3dE0F"
"0x593137Db85160Ae8E9047f539141DD04d5251381"
- RPC:
"0x46198b00f237407133da9CcFb2D567dF159284D4"
"0xec326126b342dbEa16FFe17c401bE6560B524d69"
"0xEEA50912a99B1F8D4E94565f9e44c30A1a961caa"
- Member:
"0xBa551f402cfC912482cB15466641E6FC3B2D63f2"
"0x8D9711f5793A1122dB151568FA67DacCC16B2326"
"0x46B7954f9FA8992bE5B27c3de46A87F83314Bb25"
Please note, these accounts are included for development and testing purposes only and should not be used for production or with real assets due to security considerations. It is recommended to create new accounts and nodes for personal or production use.
Functionalities and Methods
ethereum-network-automation
provides a variety of methods to manage Ethereum networks and nodes:
Account Management
pethPoa.accounts.createAccount(accountName, password)
: Creates a new account with the specified name and password.
Genesis Creation
pethPoa.genesis.createGenesis(chainId, signers, alloc)
: Generates a genesis file for the specified chain ID, including signer addresses and pre-allocated balances.
Network Configuration
pethPoa.network.getConfig(chainId)
: Retrieves the current network configuration.
Geth Deployment
pethPoa.geth.initAndStartNode(chainId, nodeType, nodeAddress)
: Initializes and starts a Geth node of the specified type.
pethPoa.geth.initAndStartNetwork(chainId)
: Initializes and starts a local network for the specified chain ID.
Docker Deployment
pethPoa.docker.initAndDeployNode(chainId, nodeType, nodeAddress)
: Initializes and deploys a Docker node of the specified type.
pethPoa.docker.initAndDeployNetwork(chainId)
: Initializes and deploys a Docker network for the specified chain ID.
pethPoa.docker.removeNodeContainer(chainId, nodeAddress)
: Removes a Docker container for a specified node.
pethPoa.docker.removeNetwork(chainId)
: Removes all containers associated with a specified Docker network.
Future Plans
Short-term goals for ethereum-network-automation
include:
- CLI Tool: Introduction of a command-line interface (CLI) tool for executing network and node operations directly from the shell.
- Kubernetes Support: Expansion into Kubernetes for network deployment to facilitate scalable and distributed network management.
- Consensus Exploration: Exploration and support for other consensus algorithms beyond PoA.
Through these enhancements, ethereum-network-automation
aims to become an even more powerful and accessible tool for Ethereum network development and management.
Contributing
We warmly welcome contributions, including feature enhancements, documentation improvements, and bug reports.
This README aims to serve as a comprehensive guide to getting started with Ethereum Network Automation. As the project evolves, the updates to this document will ensure it remains a valuable resource.