From 9fe20e59e3d05e86b544f4f78ab14f19bd753d91 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Thu, 22 Aug 2024 18:26:41 -0400 Subject: [PATCH 01/18] execution client details --- lib/ethereum/README.md | 39 ++- lib/ethereum/geth-noderunners-docs.md | 236 ++++++++++++++++++ .../lighthouse-erigon-noderunners-docs.md | 236 ++++++++++++++++++ lib/ethereum/prysm-erigon-noderunners-docs.md | 236 ++++++++++++++++++ 4 files changed, 746 insertions(+), 1 deletion(-) create mode 100644 lib/ethereum/geth-noderunners-docs.md create mode 100644 lib/ethereum/lighthouse-erigon-noderunners-docs.md create mode 100644 lib/ethereum/prysm-erigon-noderunners-docs.md diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index 28751460..d0e08d40 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -89,7 +89,44 @@ We will use AWS Cloud9 to execute the subsequent commands. Follow the instructio **NOTE:** The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES` -3. Configure your setup +3. With the [Node Runners blueprints for Ethereum](https://github.com/aws-samples/aws-blockchain-node-runners/tree/main/lib/ethereum), you can deploy both single Ethereum nodes and multi-node high-availability configurations on AWS. Furthermore, Node Runners is designed to support client diversity, with configurations available for a variety of client combinations for the Execution Layer (EL) and Consensus Layer (CL). + +Configure your setup. + + + + + Execution Layer Client + + + + + + + + + Create your own copy of `.env` file and edit it: ```bash diff --git a/lib/ethereum/geth-noderunners-docs.md b/lib/ethereum/geth-noderunners-docs.md new file mode 100644 index 00000000..5256f319 --- /dev/null +++ b/lib/ethereum/geth-noderunners-docs.md @@ -0,0 +1,236 @@ + +# AWS Blockchain Node Runners + +[AWS Blockchain Node Runners (Node Runners)](https://aws-samples.github.io/aws-blockchain-node-runners/docs/intro) is an open-source initiative aimed at simplifying the deployment of self-managed blockchain nodes on AWS using vetted deployment blueprints and infrastructure configurations. Node Runners is designed to solve for the common challenges customers face in architecting and deploying blockchain nodes on AWS, such as identifying the optimal configurations for each specific blockchain protocol’s node client. + +## Architecture Overview + +This blueprint has two configuration options for running Ethereum nodes and supports several Ethereum client combinations. You can set up a single JSON RPC node or multiple nodes in highly-available setup using the instructions below. + +### Single RPC node setup +![Architecture-PoC](https://gist.github.com/user-attachments/assets/f5b3568a-8ea1-44fd-9039-401941833910) + +This setup is for small scale PoC or development environments. It deploys a single EC2 instance with both consensus and execution clients. The RPC port is exposed only to internal IP range of the VPC, while P2P ports allow external access to keep the clients synced. + +### Highly available setup +![Architecture](https://gist.github.com/user-attachments/assets/db08e30e-ed70-49bd-a15f-78bcb702f70e) + +1. An ongoing data synchronization process is configured with nodes in the Ethereum network with a sync node and RPC nodes. +2. The sync node is used to create a copy of node's state data in Amazon S3 bucket. +3. When new RPC nodes are provisioned, they copy state data from Amazon S3 bucket to speed up the initial sync process. +4. Applications and smart contract development tools access highly available RPC nodes behind the Application Load Balancer. + +## Well-Architected + +
+Review the for pros and cons of this solution. + +### Well-Architected Checklist + +This is the Well-Architected checklist for Ethereum nodes implementation of the AWS Blockchain Node Runner app. This checklist takes into account questions from the [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) which are relevant to this workload. Please feel free to add more checks from the framework if required for your workload. + +| Pillar | Control | Question/Check | Remarks | +|:------------------------|:----------------------------------|:---------------------------------------------------------------------------------|:-----------------| +| Security | Network protection | Are there unnecessary open ports in security groups? | Please note that Erigon snap sync port remains open for non-erigon clients, i.e. Port 42069 (TCP/UDP). | +| | | Traffic inspection | AWS WAF could be implemented for traffic inspection. Additional charges will apply. | +| | Compute protection | Reduce attack surface | This solution uses Amazon Linux 2 AMI. You may choose to run hardening scripts on it. | +| | | Enable people to perform actions at a distance | This solution uses AWS Systems Manager for terminal session, not ssh ports. | +| | Data protection at rest | Use encrypted Amazon Elastic Block Store (Amazon EBS) volumes | This solution uses encrypted Amazon EBS volumes. | +| | | Use encrypted Amazon Simple Storage Service (Amazon S3) buckets | This solution uses Amazon S3 managed keys (SSE-S3) encryption. | +| | Data protection in transit | Use TLS | The AWS Application Load balancer currently uses HTTP listener. Create HTTPS listener with self signed certificate if TLS is desired. | +| | Authorization and access control | Use instance profile with Amazon Elastic Compute Cloud (Amazon EC2) instances | This solution uses AWS Identity and Access Management (AWS IAM) role instead of IAM user. | +| | | Following principle of least privilege access | In sync node, root user is not used (using special user "ethereum" instead"). | +| | Application security | Security focused development practices | cdk-nag is being used with appropriate suppressions. | +| Cost optimization | Service selection | Use cost effective resources | AWS Graviton-based Amazon EC2 instances are being used, which are cost effective compared to Intel/AMD instances. | +| | Cost awareness | Estimate costs | One sync node with m7g.2xlarge for geth-lighthouse configuration (2048GB ssd) will cost around US$430 per month in the US East (N. Virginia) region. Additional charges will apply if you choose to deploy RPC nodes with load balancer. | +| Reliability | Resiliency implementation | Withstand component failures | This solution uses AWS Application Load Balancer with RPC nodes for high availability. If sync node fails, Amazon S3 backup can be used to reinstate the nodes. | +| | Data backup | How is data backed up? | Data is backed up to Amazon S3 using [s5cmd](https://github.com/peak/s5cmd) tool. | +| | Resource monitoring | How are workload resources monitored? | Resources are being monitored using Amazon CloudWatch dashboards. Amazon CloudWatch custom metrics are being pushed via CloudWatch Agent. | +| Performance efficiency | Compute selection | How is compute solution selected? | Compute solution is selected based on best price-performance, i.e. AWS Graviton-based Amazon EC2 instances. | +| | Storage selection | How is storage solution selected? | Storage solution is selected based on best price-performance, i.e. gp3 Amazon EBS volumes with optimal IOPS and throughput. | +| | Architecture selection | How is the best performance architecture selected? | s5cmd tool has been chosen for Amazon S3 uploads/downloads because it gives better price-performance compared to Amazon EBS snapshots (including Fast Snapshot Restore, which can be expensive). | +| Operational excellence | Workload health | How is health of workload determined? | Health of workload is determined via AWS Application Load Balancer Target Group Health Checks, on port 8545. | +| Sustainability | Hardware & services | Select most efficient hardware for your workload | This solution uses AWS Graviton-based Amazon EC2 instances which offer the best performance per watt of energy use in Amazon EC2. | + +
+ +## Solution Walkthrough + +### Open AWS CloudShell + +To begin, ensure you login to your AWS account with permissions to create and modify resources in IAM, EC2, EBS, VPC, S3, KMS, and Secrets Manager. + +From the AWS Management Console, open the [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html), a web-based shell environment. If unfamiliar, review the [2-minute YouTube video](https://youtu.be/fz4rbjRaiQM) for an overview and check out [CloudShell with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) that we'll use to test nodes API from internal IP address space. + +Once ready, you can run the commands to deploy and test blueprints in the CloudShell. + +### Clone this repository and install dependencies + +```bash +git clone https://github.com/aws-samples/aws-blockchain-node-runners.git +cd aws-blockchain-node-runners +npm install +``` + +> **NOTE:** *In this tutorial we will set all major configuration through environment variables, but you also can modify parameters in `config/config.ts`.* + +### Prepare to deploy nodes + +1. Make sure you are in the root directory of the cloned repository + +2. If you have deleted or don't have the default VPC, create default VPC + +```bash +aws ec2 create-default-vpc +``` + +> **NOTE:** *You may see the following error if the default VPC already exists: `An error occurred (DefaultVpcAlreadyExists) when calling the CreateDefaultVpc operation: A Default VPC already exists for this account in this region.`. That means you can just continue with the following steps.* + +> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* + +3. Configure your Node Runners Ethereum blueprint deployment + +To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Geth / Lighthouse node deployment is as follows, which uses a sample config from the repository: +```bash +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +cd lib/ethereum +pwd +cp ./sample-configs/.env-geth-lighthouse .env +nano .env +``` +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* + + +4. Deploy common components such as IAM role, and Amazon S3 bucket to store data snapshots + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-common +``` + +### Option 1: Single RPC Node + +1. Deploy Single RPC Node + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-single-node --json --outputs-file single-node-deploy.json +``` +> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* + +2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: + + - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) + - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. + +4. Once the initial synchronization is done, you should be able to access the RPC API of that node from within the same VPC. The RPC port is not exposed to the Internet. Turn the following query against the private IP of the single RPC node you deployed: + +```bash +INSTANCE_ID=$(cat single-node-deploy.json | jq -r '..|.node-instance-id? | select(. != null)') +NODE_INTERNAL_IP=$(aws ec2 describe-instances --instance-ids $INSTANCE_ID --query 'Reservations[*].Instances[*].PrivateIpAddress' --output text) +echo "NODE_INTERNAL_IP=$NODE_INTERNAL_IP" +``` + +Copy output from the last `echo` command with `NODE_INTERNAL_IP=` and open [CloudShell tab with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) to access internal IP address space. Paste `NODE_INTERNAL_IP=` into the new CloudShell tab. Then query the API: + +``` bash +# IMPORTANT: Run from CloudShell VPC environment tab +# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa +curl http://$NODE_INTERNAL_IP:8545 -X POST -H "Content-Type: application/json" \ +--data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' +``` + +The result should be like this (the actual balance might change): + +```javascript +{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} +``` + +### Option 2: Highly Available RPC Nodes + +1. Deploy Sync Node + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-sync-node --json --outputs-file sync-node-deploy.json +``` +**NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* + +2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: + + - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) + - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. + +Once synchronization process is over, the script will automatically stop both clients and copy all the contents of the `/data` directory to your snapshot S3 bucket. That may take from 30 minutes to about 2 hours. During the process on the dashboard you will see lower CPU and RAM utilization but high data disc throughput and outbound network traffic. The script will automatically start the clients after the process is done. + +> **Note:** *The snapshot backup process will automatically run every day at midnight of the time zone were the sync node runs. To change the schedule, modify `crontab` of the root user on the node's EC2 instance.* + +3. Configure and deploy 2 RPC Nodes + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-rpc-nodes --json --outputs-file rpc-node-deploy.json +``` + +4. Give the new RPC nodes about 30 minutes (up to 2 hours for Erigon(???)) to initialize and then run the following query against the load balancer behind the RPC node created + +```bash +export ETH_RPC_ABL_URL=$(cat rpc-node-deploy.json | jq -r '..|.alburl? | select(. != null)') +echo ETH_RPC_ABL_URL=$ETH_RPC_ABL_URL +``` + +```bash +# IMPORTANT: Run from CloudShell VPC environment tab +# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa +curl http://$ETH_RPC_ABL_URL:8545 -X POST -H "Content-Type: application/json" \ + --data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' +``` + +The result should be like this (the actual balance might change): + +```javascript +{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} +``` + + If the nodes are still starting and catching up with the chain, you will see the following repsonse: + +```HTML + + 503 Service Temporarily Unavailable + +

503 Service Temporarily Unavailable

+ +``` + +> **NOTE:** By default and for security reasons the load balancer is available only from within the default VPC in the region where it is deployed. It is not available from the Internet and is not open for external connections. Before opening it up please make sure you protect your RPC APIs. + +### Clearing up and undeploying everything + +Destroy RPC Nodes, Sync Nodes and Comon components + +```bash +# Setting the AWS account id and region in case local .env file is lost + export AWS_ACCOUNT_ID= + export AWS_REGION= + +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum + +# Destroy Single RPC Node +cdk destroy eth-single-node + +# Destroy RPC Nodes +cdk destroy eth-rpc-nodes + +# Destroy Sync Node +cdk destroy eth-sync-node + +# You need to manually delete an s3 bucket with a name similar to 'eth-snapshots-$accountid-eth-nodes-common' on the console,firstly empty the bucket,secondly delete the bucket,and then execute +# Delete all common components like IAM role and Security Group +cdk destroy eth-common +``` + diff --git a/lib/ethereum/lighthouse-erigon-noderunners-docs.md b/lib/ethereum/lighthouse-erigon-noderunners-docs.md new file mode 100644 index 00000000..b10ef31a --- /dev/null +++ b/lib/ethereum/lighthouse-erigon-noderunners-docs.md @@ -0,0 +1,236 @@ + +# AWS Blockchain Node Runners + +[AWS Blockchain Node Runners (Node Runners)](https://aws-samples.github.io/aws-blockchain-node-runners/docs/intro) is an open-source initiative aimed at simplifying the deployment of self-managed blockchain nodes on AWS using vetted deployment blueprints and infrastructure configurations. Node Runners is designed to solve for the common challenges customers face in architecting and deploying blockchain nodes on AWS, such as identifying the optimal configurations for each specific blockchain protocol’s node client. + +## Architecture Overview + +This blueprint has two configuration options for running Ethereum nodes and supports several Ethereum client combinations. You can set up a single JSON RPC node or multiple nodes in highly-available setup using the instructions below. + +### Single RPC node setup +![Architecture-PoC](https://gist.github.com/user-attachments/assets/f5b3568a-8ea1-44fd-9039-401941833910) + +This setup is for small scale PoC or development environments. It deploys a single EC2 instance with both consensus and execution clients. The RPC port is exposed only to internal IP range of the VPC, while P2P ports allow external access to keep the clients synced. + +### Highly available setup +![Architecture](https://gist.github.com/user-attachments/assets/db08e30e-ed70-49bd-a15f-78bcb702f70e) + +1. An ongoing data synchronization process is configured with nodes in the Ethereum network with a sync node and RPC nodes. +2. The sync node is used to create a copy of node's state data in Amazon S3 bucket. +3. When new RPC nodes are provisioned, they copy state data from Amazon S3 bucket to speed up the initial sync process. +4. Applications and smart contract development tools access highly available RPC nodes behind the Application Load Balancer. + +## Well-Architected + +
+Review the for pros and cons of this solution. + +### Well-Architected Checklist + +This is the Well-Architected checklist for Ethereum nodes implementation of the AWS Blockchain Node Runner app. This checklist takes into account questions from the [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) which are relevant to this workload. Please feel free to add more checks from the framework if required for your workload. + +| Pillar | Control | Question/Check | Remarks | +|:------------------------|:----------------------------------|:---------------------------------------------------------------------------------|:-----------------| +| Security | Network protection | Are there unnecessary open ports in security groups? | Please note that Erigon snap sync port remains open for non-erigon clients, i.e. Port 42069 (TCP/UDP). | +| | | Traffic inspection | AWS WAF could be implemented for traffic inspection. Additional charges will apply. | +| | Compute protection | Reduce attack surface | This solution uses Amazon Linux 2 AMI. You may choose to run hardening scripts on it. | +| | | Enable people to perform actions at a distance | This solution uses AWS Systems Manager for terminal session, not ssh ports. | +| | Data protection at rest | Use encrypted Amazon Elastic Block Store (Amazon EBS) volumes | This solution uses encrypted Amazon EBS volumes. | +| | | Use encrypted Amazon Simple Storage Service (Amazon S3) buckets | This solution uses Amazon S3 managed keys (SSE-S3) encryption. | +| | Data protection in transit | Use TLS | The AWS Application Load balancer currently uses HTTP listener. Create HTTPS listener with self signed certificate if TLS is desired. | +| | Authorization and access control | Use instance profile with Amazon Elastic Compute Cloud (Amazon EC2) instances | This solution uses AWS Identity and Access Management (AWS IAM) role instead of IAM user. | +| | | Following principle of least privilege access | In sync node, root user is not used (using special user "ethereum" instead"). | +| | Application security | Security focused development practices | cdk-nag is being used with appropriate suppressions. | +| Cost optimization | Service selection | Use cost effective resources | AWS Graviton-based Amazon EC2 instances are being used, which are cost effective compared to Intel/AMD instances. | +| | Cost awareness | Estimate costs | One sync node with m7g.2xlarge for geth-lighthouse configuration (2048GB ssd) will cost around US$430 per month in the US East (N. Virginia) region. Additional charges will apply if you choose to deploy RPC nodes with load balancer. | +| Reliability | Resiliency implementation | Withstand component failures | This solution uses AWS Application Load Balancer with RPC nodes for high availability. If sync node fails, Amazon S3 backup can be used to reinstate the nodes. | +| | Data backup | How is data backed up? | Data is backed up to Amazon S3 using [s5cmd](https://github.com/peak/s5cmd) tool. | +| | Resource monitoring | How are workload resources monitored? | Resources are being monitored using Amazon CloudWatch dashboards. Amazon CloudWatch custom metrics are being pushed via CloudWatch Agent. | +| Performance efficiency | Compute selection | How is compute solution selected? | Compute solution is selected based on best price-performance, i.e. AWS Graviton-based Amazon EC2 instances. | +| | Storage selection | How is storage solution selected? | Storage solution is selected based on best price-performance, i.e. gp3 Amazon EBS volumes with optimal IOPS and throughput. | +| | Architecture selection | How is the best performance architecture selected? | s5cmd tool has been chosen for Amazon S3 uploads/downloads because it gives better price-performance compared to Amazon EBS snapshots (including Fast Snapshot Restore, which can be expensive). | +| Operational excellence | Workload health | How is health of workload determined? | Health of workload is determined via AWS Application Load Balancer Target Group Health Checks, on port 8545. | +| Sustainability | Hardware & services | Select most efficient hardware for your workload | This solution uses AWS Graviton-based Amazon EC2 instances which offer the best performance per watt of energy use in Amazon EC2. | + +
+ +## Solution Walkthrough + +### Open AWS CloudShell + +To begin, ensure you login to your AWS account with permissions to create and modify resources in IAM, EC2, EBS, VPC, S3, KMS, and Secrets Manager. + +From the AWS Management Console, open the [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html), a web-based shell environment. If unfamiliar, review the [2-minute YouTube video](https://youtu.be/fz4rbjRaiQM) for an overview and check out [CloudShell with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) that we'll use to test nodes API from internal IP address space. + +Once ready, you can run the commands to deploy and test blueprints in the CloudShell. + +### Clone this repository and install dependencies + +```bash +git clone https://github.com/aws-samples/aws-blockchain-node-runners.git +cd aws-blockchain-node-runners +npm install +``` + +> **NOTE:** *In this tutorial we will set all major configuration through environment variables, but you also can modify parameters in `config/config.ts`.* + +### Prepare to deploy nodes + +1. Make sure you are in the root directory of the cloned repository + +2. If you have deleted or don't have the default VPC, create default VPC + +```bash +aws ec2 create-default-vpc +``` + +> **NOTE:** *You may see the following error if the default VPC already exists: `An error occurred (DefaultVpcAlreadyExists) when calling the CreateDefaultVpc operation: A Default VPC already exists for this account in this region.`. That means you can just continue with the following steps.* + +> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* + +3. Configure your Node Runners Ethereum blueprint deployment + +To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: +```bash +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +cd lib/ethereum +pwd +cp ./sample-configs/.env-erigon-lighthouse .env +nano .env +``` +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* + + +4. Deploy common components such as IAM role, and Amazon S3 bucket to store data snapshots + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-common +``` + +### Option 1: Single RPC Node + +1. Deploy Single RPC Node + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-single-node --json --outputs-file single-node-deploy.json +``` +> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* + +2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: + + - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) + - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. + +4. Once the initial synchronization is done, you should be able to access the RPC API of that node from within the same VPC. The RPC port is not exposed to the Internet. Turn the following query against the private IP of the single RPC node you deployed: + +```bash +INSTANCE_ID=$(cat single-node-deploy.json | jq -r '..|.node-instance-id? | select(. != null)') +NODE_INTERNAL_IP=$(aws ec2 describe-instances --instance-ids $INSTANCE_ID --query 'Reservations[*].Instances[*].PrivateIpAddress' --output text) +echo "NODE_INTERNAL_IP=$NODE_INTERNAL_IP" +``` + +Copy output from the last `echo` command with `NODE_INTERNAL_IP=` and open [CloudShell tab with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) to access internal IP address space. Paste `NODE_INTERNAL_IP=` into the new CloudShell tab. Then query the API: + +``` bash +# IMPORTANT: Run from CloudShell VPC environment tab +# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa +curl http://$NODE_INTERNAL_IP:8545 -X POST -H "Content-Type: application/json" \ +--data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' +``` + +The result should be like this (the actual balance might change): + +```javascript +{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} +``` + +### Option 2: Highly Available RPC Nodes + +1. Deploy Sync Node + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-sync-node --json --outputs-file sync-node-deploy.json +``` +**NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* + +2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: + + - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) + - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. + +Once synchronization process is over, the script will automatically stop both clients and copy all the contents of the `/data` directory to your snapshot S3 bucket. That may take from 30 minutes to about 2 hours. During the process on the dashboard you will see lower CPU and RAM utilization but high data disc throughput and outbound network traffic. The script will automatically start the clients after the process is done. + +> **Note:** *The snapshot backup process will automatically run every day at midnight of the time zone were the sync node runs. To change the schedule, modify `crontab` of the root user on the node's EC2 instance.* + +3. Configure and deploy 2 RPC Nodes + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-rpc-nodes --json --outputs-file rpc-node-deploy.json +``` + +4. Give the new RPC nodes about 30 minutes (up to 2 hours for Erigon(???)) to initialize and then run the following query against the load balancer behind the RPC node created + +```bash +export ETH_RPC_ABL_URL=$(cat rpc-node-deploy.json | jq -r '..|.alburl? | select(. != null)') +echo ETH_RPC_ABL_URL=$ETH_RPC_ABL_URL +``` + +```bash +# IMPORTANT: Run from CloudShell VPC environment tab +# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa +curl http://$ETH_RPC_ABL_URL:8545 -X POST -H "Content-Type: application/json" \ + --data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' +``` + +The result should be like this (the actual balance might change): + +```javascript +{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} +``` + + If the nodes are still starting and catching up with the chain, you will see the following repsonse: + +```HTML + + 503 Service Temporarily Unavailable + +

503 Service Temporarily Unavailable

+ +``` + +> **NOTE:** By default and for security reasons the load balancer is available only from within the default VPC in the region where it is deployed. It is not available from the Internet and is not open for external connections. Before opening it up please make sure you protect your RPC APIs. + +### Clearing up and undeploying everything + +Destroy RPC Nodes, Sync Nodes and Comon components + +```bash +# Setting the AWS account id and region in case local .env file is lost + export AWS_ACCOUNT_ID= + export AWS_REGION= + +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum + +# Destroy Single RPC Node +cdk destroy eth-single-node + +# Destroy RPC Nodes +cdk destroy eth-rpc-nodes + +# Destroy Sync Node +cdk destroy eth-sync-node + +# You need to manually delete an s3 bucket with a name similar to 'eth-snapshots-$accountid-eth-nodes-common' on the console,firstly empty the bucket,secondly delete the bucket,and then execute +# Delete all common components like IAM role and Security Group +cdk destroy eth-common +``` + diff --git a/lib/ethereum/prysm-erigon-noderunners-docs.md b/lib/ethereum/prysm-erigon-noderunners-docs.md new file mode 100644 index 00000000..43260d3e --- /dev/null +++ b/lib/ethereum/prysm-erigon-noderunners-docs.md @@ -0,0 +1,236 @@ + +# AWS Blockchain Node Runners + +[AWS Blockchain Node Runners (Node Runners)](https://aws-samples.github.io/aws-blockchain-node-runners/docs/intro) is an open-source initiative aimed at simplifying the deployment of self-managed blockchain nodes on AWS using vetted deployment blueprints and infrastructure configurations. Node Runners is designed to solve for the common challenges customers face in architecting and deploying blockchain nodes on AWS, such as identifying the optimal configurations for each specific blockchain protocol’s node client. + +## Architecture Overview + +This blueprint has two configuration options for running Ethereum nodes and supports several Ethereum client combinations. You can set up a single JSON RPC node or multiple nodes in highly-available setup using the instructions below. + +### Single RPC node setup +![Architecture-PoC](https://gist.github.com/user-attachments/assets/f5b3568a-8ea1-44fd-9039-401941833910) + +This setup is for small scale PoC or development environments. It deploys a single EC2 instance with both consensus and execution clients. The RPC port is exposed only to internal IP range of the VPC, while P2P ports allow external access to keep the clients synced. + +### Highly available setup +![Architecture](https://gist.github.com/user-attachments/assets/db08e30e-ed70-49bd-a15f-78bcb702f70e) + +1. An ongoing data synchronization process is configured with nodes in the Ethereum network with a sync node and RPC nodes. +2. The sync node is used to create a copy of node's state data in Amazon S3 bucket. +3. When new RPC nodes are provisioned, they copy state data from Amazon S3 bucket to speed up the initial sync process. +4. Applications and smart contract development tools access highly available RPC nodes behind the Application Load Balancer. + +## Well-Architected + +
+Review the for pros and cons of this solution. + +### Well-Architected Checklist + +This is the Well-Architected checklist for Ethereum nodes implementation of the AWS Blockchain Node Runner app. This checklist takes into account questions from the [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) which are relevant to this workload. Please feel free to add more checks from the framework if required for your workload. + +| Pillar | Control | Question/Check | Remarks | +|:------------------------|:----------------------------------|:---------------------------------------------------------------------------------|:-----------------| +| Security | Network protection | Are there unnecessary open ports in security groups? | Please note that Erigon snap sync port remains open for non-erigon clients, i.e. Port 42069 (TCP/UDP). | +| | | Traffic inspection | AWS WAF could be implemented for traffic inspection. Additional charges will apply. | +| | Compute protection | Reduce attack surface | This solution uses Amazon Linux 2 AMI. You may choose to run hardening scripts on it. | +| | | Enable people to perform actions at a distance | This solution uses AWS Systems Manager for terminal session, not ssh ports. | +| | Data protection at rest | Use encrypted Amazon Elastic Block Store (Amazon EBS) volumes | This solution uses encrypted Amazon EBS volumes. | +| | | Use encrypted Amazon Simple Storage Service (Amazon S3) buckets | This solution uses Amazon S3 managed keys (SSE-S3) encryption. | +| | Data protection in transit | Use TLS | The AWS Application Load balancer currently uses HTTP listener. Create HTTPS listener with self signed certificate if TLS is desired. | +| | Authorization and access control | Use instance profile with Amazon Elastic Compute Cloud (Amazon EC2) instances | This solution uses AWS Identity and Access Management (AWS IAM) role instead of IAM user. | +| | | Following principle of least privilege access | In sync node, root user is not used (using special user "ethereum" instead"). | +| | Application security | Security focused development practices | cdk-nag is being used with appropriate suppressions. | +| Cost optimization | Service selection | Use cost effective resources | AWS Graviton-based Amazon EC2 instances are being used, which are cost effective compared to Intel/AMD instances. | +| | Cost awareness | Estimate costs | One sync node with m7g.2xlarge for geth-lighthouse configuration (2048GB ssd) will cost around US$430 per month in the US East (N. Virginia) region. Additional charges will apply if you choose to deploy RPC nodes with load balancer. | +| Reliability | Resiliency implementation | Withstand component failures | This solution uses AWS Application Load Balancer with RPC nodes for high availability. If sync node fails, Amazon S3 backup can be used to reinstate the nodes. | +| | Data backup | How is data backed up? | Data is backed up to Amazon S3 using [s5cmd](https://github.com/peak/s5cmd) tool. | +| | Resource monitoring | How are workload resources monitored? | Resources are being monitored using Amazon CloudWatch dashboards. Amazon CloudWatch custom metrics are being pushed via CloudWatch Agent. | +| Performance efficiency | Compute selection | How is compute solution selected? | Compute solution is selected based on best price-performance, i.e. AWS Graviton-based Amazon EC2 instances. | +| | Storage selection | How is storage solution selected? | Storage solution is selected based on best price-performance, i.e. gp3 Amazon EBS volumes with optimal IOPS and throughput. | +| | Architecture selection | How is the best performance architecture selected? | s5cmd tool has been chosen for Amazon S3 uploads/downloads because it gives better price-performance compared to Amazon EBS snapshots (including Fast Snapshot Restore, which can be expensive). | +| Operational excellence | Workload health | How is health of workload determined? | Health of workload is determined via AWS Application Load Balancer Target Group Health Checks, on port 8545. | +| Sustainability | Hardware & services | Select most efficient hardware for your workload | This solution uses AWS Graviton-based Amazon EC2 instances which offer the best performance per watt of energy use in Amazon EC2. | + +
+ +## Solution Walkthrough + +### Open AWS CloudShell + +To begin, ensure you login to your AWS account with permissions to create and modify resources in IAM, EC2, EBS, VPC, S3, KMS, and Secrets Manager. + +From the AWS Management Console, open the [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html), a web-based shell environment. If unfamiliar, review the [2-minute YouTube video](https://youtu.be/fz4rbjRaiQM) for an overview and check out [CloudShell with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) that we'll use to test nodes API from internal IP address space. + +Once ready, you can run the commands to deploy and test blueprints in the CloudShell. + +### Clone this repository and install dependencies + +```bash +git clone https://github.com/aws-samples/aws-blockchain-node-runners.git +cd aws-blockchain-node-runners +npm install +``` + +> **NOTE:** *In this tutorial we will set all major configuration through environment variables, but you also can modify parameters in `config/config.ts`.* + +### Prepare to deploy nodes + +1. Make sure you are in the root directory of the cloned repository + +2. If you have deleted or don't have the default VPC, create default VPC + +```bash +aws ec2 create-default-vpc +``` + +> **NOTE:** *You may see the following error if the default VPC already exists: `An error occurred (DefaultVpcAlreadyExists) when calling the CreateDefaultVpc operation: A Default VPC already exists for this account in this region.`. That means you can just continue with the following steps.* + +> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* + +3. Configure your Node Runners Ethereum blueprint deployment + +To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: +```bash +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +cd lib/ethereum +pwd +cp ./sample-configs/.env-erigon-prysm .env +nano .env +``` +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* + + +4. Deploy common components such as IAM role, and Amazon S3 bucket to store data snapshots + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-common +``` + +### Option 1: Single RPC Node + +1. Deploy Single RPC Node + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-single-node --json --outputs-file single-node-deploy.json +``` +> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* + +2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: + + - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) + - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. + +4. Once the initial synchronization is done, you should be able to access the RPC API of that node from within the same VPC. The RPC port is not exposed to the Internet. Turn the following query against the private IP of the single RPC node you deployed: + +```bash +INSTANCE_ID=$(cat single-node-deploy.json | jq -r '..|.node-instance-id? | select(. != null)') +NODE_INTERNAL_IP=$(aws ec2 describe-instances --instance-ids $INSTANCE_ID --query 'Reservations[*].Instances[*].PrivateIpAddress' --output text) +echo "NODE_INTERNAL_IP=$NODE_INTERNAL_IP" +``` + +Copy output from the last `echo` command with `NODE_INTERNAL_IP=` and open [CloudShell tab with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) to access internal IP address space. Paste `NODE_INTERNAL_IP=` into the new CloudShell tab. Then query the API: + +``` bash +# IMPORTANT: Run from CloudShell VPC environment tab +# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa +curl http://$NODE_INTERNAL_IP:8545 -X POST -H "Content-Type: application/json" \ +--data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' +``` + +The result should be like this (the actual balance might change): + +```javascript +{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} +``` + +### Option 2: Highly Available RPC Nodes + +1. Deploy Sync Node + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-sync-node --json --outputs-file sync-node-deploy.json +``` +**NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* + +2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: + + - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) + - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. + +Once synchronization process is over, the script will automatically stop both clients and copy all the contents of the `/data` directory to your snapshot S3 bucket. That may take from 30 minutes to about 2 hours. During the process on the dashboard you will see lower CPU and RAM utilization but high data disc throughput and outbound network traffic. The script will automatically start the clients after the process is done. + +> **Note:** *The snapshot backup process will automatically run every day at midnight of the time zone were the sync node runs. To change the schedule, modify `crontab` of the root user on the node's EC2 instance.* + +3. Configure and deploy 2 RPC Nodes + +```bash +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +npx cdk deploy eth-rpc-nodes --json --outputs-file rpc-node-deploy.json +``` + +4. Give the new RPC nodes about 30 minutes (up to 2 hours for Erigon(???)) to initialize and then run the following query against the load balancer behind the RPC node created + +```bash +export ETH_RPC_ABL_URL=$(cat rpc-node-deploy.json | jq -r '..|.alburl? | select(. != null)') +echo ETH_RPC_ABL_URL=$ETH_RPC_ABL_URL +``` + +```bash +# IMPORTANT: Run from CloudShell VPC environment tab +# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa +curl http://$ETH_RPC_ABL_URL:8545 -X POST -H "Content-Type: application/json" \ + --data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' +``` + +The result should be like this (the actual balance might change): + +```javascript +{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} +``` + + If the nodes are still starting and catching up with the chain, you will see the following repsonse: + +```HTML + + 503 Service Temporarily Unavailable + +

503 Service Temporarily Unavailable

+ +``` + +> **NOTE:** By default and for security reasons the load balancer is available only from within the default VPC in the region where it is deployed. It is not available from the Internet and is not open for external connections. Before opening it up please make sure you protect your RPC APIs. + +### Clearing up and undeploying everything + +Destroy RPC Nodes, Sync Nodes and Comon components + +```bash +# Setting the AWS account id and region in case local .env file is lost + export AWS_ACCOUNT_ID= + export AWS_REGION= + +pwd +# Make sure you are in aws-blockchain-node-runners/lib/ethereum + +# Destroy Single RPC Node +cdk destroy eth-single-node + +# Destroy RPC Nodes +cdk destroy eth-rpc-nodes + +# Destroy Sync Node +cdk destroy eth-sync-node + +# You need to manually delete an s3 bucket with a name similar to 'eth-snapshots-$accountid-eth-nodes-common' on the console,firstly empty the bucket,secondly delete the bucket,and then execute +# Delete all common components like IAM role and Security Group +cdk destroy eth-common +``` + From bb7020b0d56ee2d1168184c4ec3a2eac992ec5a7 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Thu, 22 Aug 2024 18:33:47 -0400 Subject: [PATCH 02/18] execution client detail edits --- lib/ethereum/README.md | 51 ++++++++++++++++-------------------------- 1 file changed, 19 insertions(+), 32 deletions(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index d0e08d40..9a244bb5 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -93,39 +93,26 @@ We will use AWS Cloud9 to execute the subsequent commands. Follow the instructio Configure your setup. - - - - Execution Layer Client - - - - - - - - + + + + + + + Create your own copy of `.env` file and edit it: From bf14b52aa3b70ef5c62652ccd354d3ef0db4f230 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Thu, 22 Aug 2024 18:36:35 -0400 Subject: [PATCH 03/18] execution client detail edits 2 --- lib/ethereum/README.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index 9a244bb5..366fa7aa 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -95,14 +95,11 @@ Configure your setup. **Execution Layer Client Options** - +| Option | +| --- | +| [Geth Lighthouse](lib/ethereum/geth-noderunners-docs.md) | +| [Erigon Lighthouse](lib/ethereum/lighthouse-erigon-noderunners-docs.md) | +| [Erigon Prysm](lib/ethereum/prysm-erigon-noderunners-docs.md) | - - -Create your own copy of `.env` file and edit it: -```bash - # Make sure you are in aws-blockchain-node-runners/lib/ethereum - cd lib/ethereum - pwd - cp ./sample-configs/.env-geth-lighthouse .env - nano .env -``` - **NOTE:** You can find more examples inside the `sample-configs` directory. +| [Geth Lighthouse](../lib/ethereum/geth-noderunners-docs.md) | +| [Erigon Lighthouse](../lib/ethereum/lighthouse-erigon-noderunners-docs.md) | +| [Erigon Prysm](../lib/ethereum/prysm-erigon-noderunners-docs.md) | +Don’t see a client or client combination you would like supported? Open a GitHub [issue](https://github.com/aws-samples/aws-blockchain-node-runners/issues) or [Pull Request](https://github.com/aws-samples/aws-blockchain-node-runners/pulls), we encourage [contribution](https://github.com/aws-samples/aws-blockchain-node-runners/blob/main/CONTRIBUTING.md) to Node Runners! 4. Deploy common components such as IAM role, and Amazon S3 bucket to store data snapshots diff --git a/lib/ethereum/geth-noderunners-docs.md b/lib/ethereum/geth-noderunners-docs.md index 5256f319..1ec1d254 100644 --- a/lib/ethereum/geth-noderunners-docs.md +++ b/lib/ethereum/geth-noderunners-docs.md @@ -1,94 +1,5 @@ -# AWS Blockchain Node Runners - -[AWS Blockchain Node Runners (Node Runners)](https://aws-samples.github.io/aws-blockchain-node-runners/docs/intro) is an open-source initiative aimed at simplifying the deployment of self-managed blockchain nodes on AWS using vetted deployment blueprints and infrastructure configurations. Node Runners is designed to solve for the common challenges customers face in architecting and deploying blockchain nodes on AWS, such as identifying the optimal configurations for each specific blockchain protocol’s node client. - -## Architecture Overview - -This blueprint has two configuration options for running Ethereum nodes and supports several Ethereum client combinations. You can set up a single JSON RPC node or multiple nodes in highly-available setup using the instructions below. - -### Single RPC node setup -![Architecture-PoC](https://gist.github.com/user-attachments/assets/f5b3568a-8ea1-44fd-9039-401941833910) - -This setup is for small scale PoC or development environments. It deploys a single EC2 instance with both consensus and execution clients. The RPC port is exposed only to internal IP range of the VPC, while P2P ports allow external access to keep the clients synced. - -### Highly available setup -![Architecture](https://gist.github.com/user-attachments/assets/db08e30e-ed70-49bd-a15f-78bcb702f70e) - -1. An ongoing data synchronization process is configured with nodes in the Ethereum network with a sync node and RPC nodes. -2. The sync node is used to create a copy of node's state data in Amazon S3 bucket. -3. When new RPC nodes are provisioned, they copy state data from Amazon S3 bucket to speed up the initial sync process. -4. Applications and smart contract development tools access highly available RPC nodes behind the Application Load Balancer. - -## Well-Architected - -
-Review the for pros and cons of this solution. - -### Well-Architected Checklist - -This is the Well-Architected checklist for Ethereum nodes implementation of the AWS Blockchain Node Runner app. This checklist takes into account questions from the [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) which are relevant to this workload. Please feel free to add more checks from the framework if required for your workload. - -| Pillar | Control | Question/Check | Remarks | -|:------------------------|:----------------------------------|:---------------------------------------------------------------------------------|:-----------------| -| Security | Network protection | Are there unnecessary open ports in security groups? | Please note that Erigon snap sync port remains open for non-erigon clients, i.e. Port 42069 (TCP/UDP). | -| | | Traffic inspection | AWS WAF could be implemented for traffic inspection. Additional charges will apply. | -| | Compute protection | Reduce attack surface | This solution uses Amazon Linux 2 AMI. You may choose to run hardening scripts on it. | -| | | Enable people to perform actions at a distance | This solution uses AWS Systems Manager for terminal session, not ssh ports. | -| | Data protection at rest | Use encrypted Amazon Elastic Block Store (Amazon EBS) volumes | This solution uses encrypted Amazon EBS volumes. | -| | | Use encrypted Amazon Simple Storage Service (Amazon S3) buckets | This solution uses Amazon S3 managed keys (SSE-S3) encryption. | -| | Data protection in transit | Use TLS | The AWS Application Load balancer currently uses HTTP listener. Create HTTPS listener with self signed certificate if TLS is desired. | -| | Authorization and access control | Use instance profile with Amazon Elastic Compute Cloud (Amazon EC2) instances | This solution uses AWS Identity and Access Management (AWS IAM) role instead of IAM user. | -| | | Following principle of least privilege access | In sync node, root user is not used (using special user "ethereum" instead"). | -| | Application security | Security focused development practices | cdk-nag is being used with appropriate suppressions. | -| Cost optimization | Service selection | Use cost effective resources | AWS Graviton-based Amazon EC2 instances are being used, which are cost effective compared to Intel/AMD instances. | -| | Cost awareness | Estimate costs | One sync node with m7g.2xlarge for geth-lighthouse configuration (2048GB ssd) will cost around US$430 per month in the US East (N. Virginia) region. Additional charges will apply if you choose to deploy RPC nodes with load balancer. | -| Reliability | Resiliency implementation | Withstand component failures | This solution uses AWS Application Load Balancer with RPC nodes for high availability. If sync node fails, Amazon S3 backup can be used to reinstate the nodes. | -| | Data backup | How is data backed up? | Data is backed up to Amazon S3 using [s5cmd](https://github.com/peak/s5cmd) tool. | -| | Resource monitoring | How are workload resources monitored? | Resources are being monitored using Amazon CloudWatch dashboards. Amazon CloudWatch custom metrics are being pushed via CloudWatch Agent. | -| Performance efficiency | Compute selection | How is compute solution selected? | Compute solution is selected based on best price-performance, i.e. AWS Graviton-based Amazon EC2 instances. | -| | Storage selection | How is storage solution selected? | Storage solution is selected based on best price-performance, i.e. gp3 Amazon EBS volumes with optimal IOPS and throughput. | -| | Architecture selection | How is the best performance architecture selected? | s5cmd tool has been chosen for Amazon S3 uploads/downloads because it gives better price-performance compared to Amazon EBS snapshots (including Fast Snapshot Restore, which can be expensive). | -| Operational excellence | Workload health | How is health of workload determined? | Health of workload is determined via AWS Application Load Balancer Target Group Health Checks, on port 8545. | -| Sustainability | Hardware & services | Select most efficient hardware for your workload | This solution uses AWS Graviton-based Amazon EC2 instances which offer the best performance per watt of energy use in Amazon EC2. | - -
- -## Solution Walkthrough - -### Open AWS CloudShell - -To begin, ensure you login to your AWS account with permissions to create and modify resources in IAM, EC2, EBS, VPC, S3, KMS, and Secrets Manager. - -From the AWS Management Console, open the [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html), a web-based shell environment. If unfamiliar, review the [2-minute YouTube video](https://youtu.be/fz4rbjRaiQM) for an overview and check out [CloudShell with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) that we'll use to test nodes API from internal IP address space. - -Once ready, you can run the commands to deploy and test blueprints in the CloudShell. - -### Clone this repository and install dependencies - -```bash -git clone https://github.com/aws-samples/aws-blockchain-node-runners.git -cd aws-blockchain-node-runners -npm install -``` - -> **NOTE:** *In this tutorial we will set all major configuration through environment variables, but you also can modify parameters in `config/config.ts`.* - -### Prepare to deploy nodes - -1. Make sure you are in the root directory of the cloned repository - -2. If you have deleted or don't have the default VPC, create default VPC - -```bash -aws ec2 create-default-vpc -``` - -> **NOTE:** *You may see the following error if the default VPC already exists: `An error occurred (DefaultVpcAlreadyExists) when calling the CreateDefaultVpc operation: A Default VPC already exists for this account in this region.`. That means you can just continue with the following steps.* - -> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* - -3. Configure your Node Runners Ethereum blueprint deployment +# Configure your Node Runners Ethereum - Geth Lighthouse To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Geth / Lighthouse node deployment is as follows, which uses a sample config from the repository: ```bash @@ -98,139 +9,4 @@ pwd cp ./sample-configs/.env-geth-lighthouse .env nano .env ``` -> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* - - -4. Deploy common components such as IAM role, and Amazon S3 bucket to store data snapshots - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-common -``` - -### Option 1: Single RPC Node - -1. Deploy Single RPC Node - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-single-node --json --outputs-file single-node-deploy.json -``` -> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* - -2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: - - - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) - - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. - -4. Once the initial synchronization is done, you should be able to access the RPC API of that node from within the same VPC. The RPC port is not exposed to the Internet. Turn the following query against the private IP of the single RPC node you deployed: - -```bash -INSTANCE_ID=$(cat single-node-deploy.json | jq -r '..|.node-instance-id? | select(. != null)') -NODE_INTERNAL_IP=$(aws ec2 describe-instances --instance-ids $INSTANCE_ID --query 'Reservations[*].Instances[*].PrivateIpAddress' --output text) -echo "NODE_INTERNAL_IP=$NODE_INTERNAL_IP" -``` - -Copy output from the last `echo` command with `NODE_INTERNAL_IP=` and open [CloudShell tab with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) to access internal IP address space. Paste `NODE_INTERNAL_IP=` into the new CloudShell tab. Then query the API: - -``` bash -# IMPORTANT: Run from CloudShell VPC environment tab -# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa -curl http://$NODE_INTERNAL_IP:8545 -X POST -H "Content-Type: application/json" \ ---data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' -``` - -The result should be like this (the actual balance might change): - -```javascript -{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} -``` - -### Option 2: Highly Available RPC Nodes - -1. Deploy Sync Node - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-sync-node --json --outputs-file sync-node-deploy.json -``` -**NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* - -2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: - - - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) - - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. - -Once synchronization process is over, the script will automatically stop both clients and copy all the contents of the `/data` directory to your snapshot S3 bucket. That may take from 30 minutes to about 2 hours. During the process on the dashboard you will see lower CPU and RAM utilization but high data disc throughput and outbound network traffic. The script will automatically start the clients after the process is done. - -> **Note:** *The snapshot backup process will automatically run every day at midnight of the time zone were the sync node runs. To change the schedule, modify `crontab` of the root user on the node's EC2 instance.* - -3. Configure and deploy 2 RPC Nodes - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-rpc-nodes --json --outputs-file rpc-node-deploy.json -``` - -4. Give the new RPC nodes about 30 minutes (up to 2 hours for Erigon(???)) to initialize and then run the following query against the load balancer behind the RPC node created - -```bash -export ETH_RPC_ABL_URL=$(cat rpc-node-deploy.json | jq -r '..|.alburl? | select(. != null)') -echo ETH_RPC_ABL_URL=$ETH_RPC_ABL_URL -``` - -```bash -# IMPORTANT: Run from CloudShell VPC environment tab -# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa -curl http://$ETH_RPC_ABL_URL:8545 -X POST -H "Content-Type: application/json" \ - --data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' -``` - -The result should be like this (the actual balance might change): - -```javascript -{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} -``` - - If the nodes are still starting and catching up with the chain, you will see the following repsonse: - -```HTML - - 503 Service Temporarily Unavailable - -

503 Service Temporarily Unavailable

- -``` - -> **NOTE:** By default and for security reasons the load balancer is available only from within the default VPC in the region where it is deployed. It is not available from the Internet and is not open for external connections. Before opening it up please make sure you protect your RPC APIs. - -### Clearing up and undeploying everything - -Destroy RPC Nodes, Sync Nodes and Comon components - -```bash -# Setting the AWS account id and region in case local .env file is lost - export AWS_ACCOUNT_ID= - export AWS_REGION= - -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum - -# Destroy Single RPC Node -cdk destroy eth-single-node - -# Destroy RPC Nodes -cdk destroy eth-rpc-nodes - -# Destroy Sync Node -cdk destroy eth-sync-node - -# You need to manually delete an s3 bucket with a name similar to 'eth-snapshots-$accountid-eth-nodes-common' on the console,firstly empty the bucket,secondly delete the bucket,and then execute -# Delete all common components like IAM role and Security Group -cdk destroy eth-common -``` - +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* \ No newline at end of file diff --git a/lib/ethereum/lighthouse-erigon-noderunners-docs.md b/lib/ethereum/lighthouse-erigon-noderunners-docs.md index b10ef31a..1a9b1329 100644 --- a/lib/ethereum/lighthouse-erigon-noderunners-docs.md +++ b/lib/ethereum/lighthouse-erigon-noderunners-docs.md @@ -1,94 +1,4 @@ - -# AWS Blockchain Node Runners - -[AWS Blockchain Node Runners (Node Runners)](https://aws-samples.github.io/aws-blockchain-node-runners/docs/intro) is an open-source initiative aimed at simplifying the deployment of self-managed blockchain nodes on AWS using vetted deployment blueprints and infrastructure configurations. Node Runners is designed to solve for the common challenges customers face in architecting and deploying blockchain nodes on AWS, such as identifying the optimal configurations for each specific blockchain protocol’s node client. - -## Architecture Overview - -This blueprint has two configuration options for running Ethereum nodes and supports several Ethereum client combinations. You can set up a single JSON RPC node or multiple nodes in highly-available setup using the instructions below. - -### Single RPC node setup -![Architecture-PoC](https://gist.github.com/user-attachments/assets/f5b3568a-8ea1-44fd-9039-401941833910) - -This setup is for small scale PoC or development environments. It deploys a single EC2 instance with both consensus and execution clients. The RPC port is exposed only to internal IP range of the VPC, while P2P ports allow external access to keep the clients synced. - -### Highly available setup -![Architecture](https://gist.github.com/user-attachments/assets/db08e30e-ed70-49bd-a15f-78bcb702f70e) - -1. An ongoing data synchronization process is configured with nodes in the Ethereum network with a sync node and RPC nodes. -2. The sync node is used to create a copy of node's state data in Amazon S3 bucket. -3. When new RPC nodes are provisioned, they copy state data from Amazon S3 bucket to speed up the initial sync process. -4. Applications and smart contract development tools access highly available RPC nodes behind the Application Load Balancer. - -## Well-Architected - -
-Review the for pros and cons of this solution. - -### Well-Architected Checklist - -This is the Well-Architected checklist for Ethereum nodes implementation of the AWS Blockchain Node Runner app. This checklist takes into account questions from the [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) which are relevant to this workload. Please feel free to add more checks from the framework if required for your workload. - -| Pillar | Control | Question/Check | Remarks | -|:------------------------|:----------------------------------|:---------------------------------------------------------------------------------|:-----------------| -| Security | Network protection | Are there unnecessary open ports in security groups? | Please note that Erigon snap sync port remains open for non-erigon clients, i.e. Port 42069 (TCP/UDP). | -| | | Traffic inspection | AWS WAF could be implemented for traffic inspection. Additional charges will apply. | -| | Compute protection | Reduce attack surface | This solution uses Amazon Linux 2 AMI. You may choose to run hardening scripts on it. | -| | | Enable people to perform actions at a distance | This solution uses AWS Systems Manager for terminal session, not ssh ports. | -| | Data protection at rest | Use encrypted Amazon Elastic Block Store (Amazon EBS) volumes | This solution uses encrypted Amazon EBS volumes. | -| | | Use encrypted Amazon Simple Storage Service (Amazon S3) buckets | This solution uses Amazon S3 managed keys (SSE-S3) encryption. | -| | Data protection in transit | Use TLS | The AWS Application Load balancer currently uses HTTP listener. Create HTTPS listener with self signed certificate if TLS is desired. | -| | Authorization and access control | Use instance profile with Amazon Elastic Compute Cloud (Amazon EC2) instances | This solution uses AWS Identity and Access Management (AWS IAM) role instead of IAM user. | -| | | Following principle of least privilege access | In sync node, root user is not used (using special user "ethereum" instead"). | -| | Application security | Security focused development practices | cdk-nag is being used with appropriate suppressions. | -| Cost optimization | Service selection | Use cost effective resources | AWS Graviton-based Amazon EC2 instances are being used, which are cost effective compared to Intel/AMD instances. | -| | Cost awareness | Estimate costs | One sync node with m7g.2xlarge for geth-lighthouse configuration (2048GB ssd) will cost around US$430 per month in the US East (N. Virginia) region. Additional charges will apply if you choose to deploy RPC nodes with load balancer. | -| Reliability | Resiliency implementation | Withstand component failures | This solution uses AWS Application Load Balancer with RPC nodes for high availability. If sync node fails, Amazon S3 backup can be used to reinstate the nodes. | -| | Data backup | How is data backed up? | Data is backed up to Amazon S3 using [s5cmd](https://github.com/peak/s5cmd) tool. | -| | Resource monitoring | How are workload resources monitored? | Resources are being monitored using Amazon CloudWatch dashboards. Amazon CloudWatch custom metrics are being pushed via CloudWatch Agent. | -| Performance efficiency | Compute selection | How is compute solution selected? | Compute solution is selected based on best price-performance, i.e. AWS Graviton-based Amazon EC2 instances. | -| | Storage selection | How is storage solution selected? | Storage solution is selected based on best price-performance, i.e. gp3 Amazon EBS volumes with optimal IOPS and throughput. | -| | Architecture selection | How is the best performance architecture selected? | s5cmd tool has been chosen for Amazon S3 uploads/downloads because it gives better price-performance compared to Amazon EBS snapshots (including Fast Snapshot Restore, which can be expensive). | -| Operational excellence | Workload health | How is health of workload determined? | Health of workload is determined via AWS Application Load Balancer Target Group Health Checks, on port 8545. | -| Sustainability | Hardware & services | Select most efficient hardware for your workload | This solution uses AWS Graviton-based Amazon EC2 instances which offer the best performance per watt of energy use in Amazon EC2. | - -
- -## Solution Walkthrough - -### Open AWS CloudShell - -To begin, ensure you login to your AWS account with permissions to create and modify resources in IAM, EC2, EBS, VPC, S3, KMS, and Secrets Manager. - -From the AWS Management Console, open the [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html), a web-based shell environment. If unfamiliar, review the [2-minute YouTube video](https://youtu.be/fz4rbjRaiQM) for an overview and check out [CloudShell with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) that we'll use to test nodes API from internal IP address space. - -Once ready, you can run the commands to deploy and test blueprints in the CloudShell. - -### Clone this repository and install dependencies - -```bash -git clone https://github.com/aws-samples/aws-blockchain-node-runners.git -cd aws-blockchain-node-runners -npm install -``` - -> **NOTE:** *In this tutorial we will set all major configuration through environment variables, but you also can modify parameters in `config/config.ts`.* - -### Prepare to deploy nodes - -1. Make sure you are in the root directory of the cloned repository - -2. If you have deleted or don't have the default VPC, create default VPC - -```bash -aws ec2 create-default-vpc -``` - -> **NOTE:** *You may see the following error if the default VPC already exists: `An error occurred (DefaultVpcAlreadyExists) when calling the CreateDefaultVpc operation: A Default VPC already exists for this account in this region.`. That means you can just continue with the following steps.* - -> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* - -3. Configure your Node Runners Ethereum blueprint deployment +# Configure your Node Runners Ethereum - Erigon Lighthouse To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: ```bash @@ -98,139 +8,4 @@ pwd cp ./sample-configs/.env-erigon-lighthouse .env nano .env ``` -> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* - - -4. Deploy common components such as IAM role, and Amazon S3 bucket to store data snapshots - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-common -``` - -### Option 1: Single RPC Node - -1. Deploy Single RPC Node - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-single-node --json --outputs-file single-node-deploy.json -``` -> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* - -2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: - - - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) - - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. - -4. Once the initial synchronization is done, you should be able to access the RPC API of that node from within the same VPC. The RPC port is not exposed to the Internet. Turn the following query against the private IP of the single RPC node you deployed: - -```bash -INSTANCE_ID=$(cat single-node-deploy.json | jq -r '..|.node-instance-id? | select(. != null)') -NODE_INTERNAL_IP=$(aws ec2 describe-instances --instance-ids $INSTANCE_ID --query 'Reservations[*].Instances[*].PrivateIpAddress' --output text) -echo "NODE_INTERNAL_IP=$NODE_INTERNAL_IP" -``` - -Copy output from the last `echo` command with `NODE_INTERNAL_IP=` and open [CloudShell tab with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) to access internal IP address space. Paste `NODE_INTERNAL_IP=` into the new CloudShell tab. Then query the API: - -``` bash -# IMPORTANT: Run from CloudShell VPC environment tab -# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa -curl http://$NODE_INTERNAL_IP:8545 -X POST -H "Content-Type: application/json" \ ---data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' -``` - -The result should be like this (the actual balance might change): - -```javascript -{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} -``` - -### Option 2: Highly Available RPC Nodes - -1. Deploy Sync Node - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-sync-node --json --outputs-file sync-node-deploy.json -``` -**NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* - -2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: - - - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) - - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. - -Once synchronization process is over, the script will automatically stop both clients and copy all the contents of the `/data` directory to your snapshot S3 bucket. That may take from 30 minutes to about 2 hours. During the process on the dashboard you will see lower CPU and RAM utilization but high data disc throughput and outbound network traffic. The script will automatically start the clients after the process is done. - -> **Note:** *The snapshot backup process will automatically run every day at midnight of the time zone were the sync node runs. To change the schedule, modify `crontab` of the root user on the node's EC2 instance.* - -3. Configure and deploy 2 RPC Nodes - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-rpc-nodes --json --outputs-file rpc-node-deploy.json -``` - -4. Give the new RPC nodes about 30 minutes (up to 2 hours for Erigon(???)) to initialize and then run the following query against the load balancer behind the RPC node created - -```bash -export ETH_RPC_ABL_URL=$(cat rpc-node-deploy.json | jq -r '..|.alburl? | select(. != null)') -echo ETH_RPC_ABL_URL=$ETH_RPC_ABL_URL -``` - -```bash -# IMPORTANT: Run from CloudShell VPC environment tab -# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa -curl http://$ETH_RPC_ABL_URL:8545 -X POST -H "Content-Type: application/json" \ - --data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' -``` - -The result should be like this (the actual balance might change): - -```javascript -{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} -``` - - If the nodes are still starting and catching up with the chain, you will see the following repsonse: - -```HTML - - 503 Service Temporarily Unavailable - -

503 Service Temporarily Unavailable

- -``` - -> **NOTE:** By default and for security reasons the load balancer is available only from within the default VPC in the region where it is deployed. It is not available from the Internet and is not open for external connections. Before opening it up please make sure you protect your RPC APIs. - -### Clearing up and undeploying everything - -Destroy RPC Nodes, Sync Nodes and Comon components - -```bash -# Setting the AWS account id and region in case local .env file is lost - export AWS_ACCOUNT_ID= - export AWS_REGION= - -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum - -# Destroy Single RPC Node -cdk destroy eth-single-node - -# Destroy RPC Nodes -cdk destroy eth-rpc-nodes - -# Destroy Sync Node -cdk destroy eth-sync-node - -# You need to manually delete an s3 bucket with a name similar to 'eth-snapshots-$accountid-eth-nodes-common' on the console,firstly empty the bucket,secondly delete the bucket,and then execute -# Delete all common components like IAM role and Security Group -cdk destroy eth-common -``` - +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* \ No newline at end of file diff --git a/lib/ethereum/prysm-erigon-noderunners-docs.md b/lib/ethereum/prysm-erigon-noderunners-docs.md index 43260d3e..4c433d6d 100644 --- a/lib/ethereum/prysm-erigon-noderunners-docs.md +++ b/lib/ethereum/prysm-erigon-noderunners-docs.md @@ -1,94 +1,5 @@ -# AWS Blockchain Node Runners - -[AWS Blockchain Node Runners (Node Runners)](https://aws-samples.github.io/aws-blockchain-node-runners/docs/intro) is an open-source initiative aimed at simplifying the deployment of self-managed blockchain nodes on AWS using vetted deployment blueprints and infrastructure configurations. Node Runners is designed to solve for the common challenges customers face in architecting and deploying blockchain nodes on AWS, such as identifying the optimal configurations for each specific blockchain protocol’s node client. - -## Architecture Overview - -This blueprint has two configuration options for running Ethereum nodes and supports several Ethereum client combinations. You can set up a single JSON RPC node or multiple nodes in highly-available setup using the instructions below. - -### Single RPC node setup -![Architecture-PoC](https://gist.github.com/user-attachments/assets/f5b3568a-8ea1-44fd-9039-401941833910) - -This setup is for small scale PoC or development environments. It deploys a single EC2 instance with both consensus and execution clients. The RPC port is exposed only to internal IP range of the VPC, while P2P ports allow external access to keep the clients synced. - -### Highly available setup -![Architecture](https://gist.github.com/user-attachments/assets/db08e30e-ed70-49bd-a15f-78bcb702f70e) - -1. An ongoing data synchronization process is configured with nodes in the Ethereum network with a sync node and RPC nodes. -2. The sync node is used to create a copy of node's state data in Amazon S3 bucket. -3. When new RPC nodes are provisioned, they copy state data from Amazon S3 bucket to speed up the initial sync process. -4. Applications and smart contract development tools access highly available RPC nodes behind the Application Load Balancer. - -## Well-Architected - -
-Review the for pros and cons of this solution. - -### Well-Architected Checklist - -This is the Well-Architected checklist for Ethereum nodes implementation of the AWS Blockchain Node Runner app. This checklist takes into account questions from the [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) which are relevant to this workload. Please feel free to add more checks from the framework if required for your workload. - -| Pillar | Control | Question/Check | Remarks | -|:------------------------|:----------------------------------|:---------------------------------------------------------------------------------|:-----------------| -| Security | Network protection | Are there unnecessary open ports in security groups? | Please note that Erigon snap sync port remains open for non-erigon clients, i.e. Port 42069 (TCP/UDP). | -| | | Traffic inspection | AWS WAF could be implemented for traffic inspection. Additional charges will apply. | -| | Compute protection | Reduce attack surface | This solution uses Amazon Linux 2 AMI. You may choose to run hardening scripts on it. | -| | | Enable people to perform actions at a distance | This solution uses AWS Systems Manager for terminal session, not ssh ports. | -| | Data protection at rest | Use encrypted Amazon Elastic Block Store (Amazon EBS) volumes | This solution uses encrypted Amazon EBS volumes. | -| | | Use encrypted Amazon Simple Storage Service (Amazon S3) buckets | This solution uses Amazon S3 managed keys (SSE-S3) encryption. | -| | Data protection in transit | Use TLS | The AWS Application Load balancer currently uses HTTP listener. Create HTTPS listener with self signed certificate if TLS is desired. | -| | Authorization and access control | Use instance profile with Amazon Elastic Compute Cloud (Amazon EC2) instances | This solution uses AWS Identity and Access Management (AWS IAM) role instead of IAM user. | -| | | Following principle of least privilege access | In sync node, root user is not used (using special user "ethereum" instead"). | -| | Application security | Security focused development practices | cdk-nag is being used with appropriate suppressions. | -| Cost optimization | Service selection | Use cost effective resources | AWS Graviton-based Amazon EC2 instances are being used, which are cost effective compared to Intel/AMD instances. | -| | Cost awareness | Estimate costs | One sync node with m7g.2xlarge for geth-lighthouse configuration (2048GB ssd) will cost around US$430 per month in the US East (N. Virginia) region. Additional charges will apply if you choose to deploy RPC nodes with load balancer. | -| Reliability | Resiliency implementation | Withstand component failures | This solution uses AWS Application Load Balancer with RPC nodes for high availability. If sync node fails, Amazon S3 backup can be used to reinstate the nodes. | -| | Data backup | How is data backed up? | Data is backed up to Amazon S3 using [s5cmd](https://github.com/peak/s5cmd) tool. | -| | Resource monitoring | How are workload resources monitored? | Resources are being monitored using Amazon CloudWatch dashboards. Amazon CloudWatch custom metrics are being pushed via CloudWatch Agent. | -| Performance efficiency | Compute selection | How is compute solution selected? | Compute solution is selected based on best price-performance, i.e. AWS Graviton-based Amazon EC2 instances. | -| | Storage selection | How is storage solution selected? | Storage solution is selected based on best price-performance, i.e. gp3 Amazon EBS volumes with optimal IOPS and throughput. | -| | Architecture selection | How is the best performance architecture selected? | s5cmd tool has been chosen for Amazon S3 uploads/downloads because it gives better price-performance compared to Amazon EBS snapshots (including Fast Snapshot Restore, which can be expensive). | -| Operational excellence | Workload health | How is health of workload determined? | Health of workload is determined via AWS Application Load Balancer Target Group Health Checks, on port 8545. | -| Sustainability | Hardware & services | Select most efficient hardware for your workload | This solution uses AWS Graviton-based Amazon EC2 instances which offer the best performance per watt of energy use in Amazon EC2. | - -
- -## Solution Walkthrough - -### Open AWS CloudShell - -To begin, ensure you login to your AWS account with permissions to create and modify resources in IAM, EC2, EBS, VPC, S3, KMS, and Secrets Manager. - -From the AWS Management Console, open the [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html), a web-based shell environment. If unfamiliar, review the [2-minute YouTube video](https://youtu.be/fz4rbjRaiQM) for an overview and check out [CloudShell with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) that we'll use to test nodes API from internal IP address space. - -Once ready, you can run the commands to deploy and test blueprints in the CloudShell. - -### Clone this repository and install dependencies - -```bash -git clone https://github.com/aws-samples/aws-blockchain-node-runners.git -cd aws-blockchain-node-runners -npm install -``` - -> **NOTE:** *In this tutorial we will set all major configuration through environment variables, but you also can modify parameters in `config/config.ts`.* - -### Prepare to deploy nodes - -1. Make sure you are in the root directory of the cloned repository - -2. If you have deleted or don't have the default VPC, create default VPC - -```bash -aws ec2 create-default-vpc -``` - -> **NOTE:** *You may see the following error if the default VPC already exists: `An error occurred (DefaultVpcAlreadyExists) when calling the CreateDefaultVpc operation: A Default VPC already exists for this account in this region.`. That means you can just continue with the following steps.* - -> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* - -3. Configure your Node Runners Ethereum blueprint deployment +# Configure your Node Runners Ethereum - Erigon Prysm To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: ```bash @@ -98,139 +9,4 @@ pwd cp ./sample-configs/.env-erigon-prysm .env nano .env ``` -> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* - - -4. Deploy common components such as IAM role, and Amazon S3 bucket to store data snapshots - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-common -``` - -### Option 1: Single RPC Node - -1. Deploy Single RPC Node - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-single-node --json --outputs-file single-node-deploy.json -``` -> **NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* - -2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: - - - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) - - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. - -4. Once the initial synchronization is done, you should be able to access the RPC API of that node from within the same VPC. The RPC port is not exposed to the Internet. Turn the following query against the private IP of the single RPC node you deployed: - -```bash -INSTANCE_ID=$(cat single-node-deploy.json | jq -r '..|.node-instance-id? | select(. != null)') -NODE_INTERNAL_IP=$(aws ec2 describe-instances --instance-ids $INSTANCE_ID --query 'Reservations[*].Instances[*].PrivateIpAddress' --output text) -echo "NODE_INTERNAL_IP=$NODE_INTERNAL_IP" -``` - -Copy output from the last `echo` command with `NODE_INTERNAL_IP=` and open [CloudShell tab with VPC environment](https://docs.aws.amazon.com/cloudshell/latest/userguide/creating-vpc-environment.html) to access internal IP address space. Paste `NODE_INTERNAL_IP=` into the new CloudShell tab. Then query the API: - -``` bash -# IMPORTANT: Run from CloudShell VPC environment tab -# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa -curl http://$NODE_INTERNAL_IP:8545 -X POST -H "Content-Type: application/json" \ ---data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' -``` - -The result should be like this (the actual balance might change): - -```javascript -{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} -``` - -### Option 2: Highly Available RPC Nodes - -1. Deploy Sync Node - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-sync-node --json --outputs-file sync-node-deploy.json -``` -**NOTE:** *The default VPC must have at least two public subnets in different Availability Zones, and public subnet must set `Auto-assign public IPv4 address` to `YES`* - -2. After starting the node you need to wait for the inital syncronization process to finish. It may take from half a day to about 6-10 days depending on the client combination and the state of the network. You can use Amazon CloudWatch to track the progress. There is a script that publishes CloudWatch metrics every 5 minutes, where you can watch `sync distance` for consensus client and `blocks behind` for execution client. When the node is fully synced those two metrics shold show 0. To see them: - - - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) - - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. - -Once synchronization process is over, the script will automatically stop both clients and copy all the contents of the `/data` directory to your snapshot S3 bucket. That may take from 30 minutes to about 2 hours. During the process on the dashboard you will see lower CPU and RAM utilization but high data disc throughput and outbound network traffic. The script will automatically start the clients after the process is done. - -> **Note:** *The snapshot backup process will automatically run every day at midnight of the time zone were the sync node runs. To change the schedule, modify `crontab` of the root user on the node's EC2 instance.* - -3. Configure and deploy 2 RPC Nodes - -```bash -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -npx cdk deploy eth-rpc-nodes --json --outputs-file rpc-node-deploy.json -``` - -4. Give the new RPC nodes about 30 minutes (up to 2 hours for Erigon(???)) to initialize and then run the following query against the load balancer behind the RPC node created - -```bash -export ETH_RPC_ABL_URL=$(cat rpc-node-deploy.json | jq -r '..|.alburl? | select(. != null)') -echo ETH_RPC_ABL_URL=$ETH_RPC_ABL_URL -``` - -```bash -# IMPORTANT: Run from CloudShell VPC environment tab -# We query token balance of Beacon deposit contract: https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa -curl http://$ETH_RPC_ABL_URL:8545 -X POST -H "Content-Type: application/json" \ - --data '{"method":"eth_getBalance","params":["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],"id":1,"jsonrpc":"2.0"}' -``` - -The result should be like this (the actual balance might change): - -```javascript -{"jsonrpc":"2.0","id":1,"result":"0xe791d050f91d9949d344d"} -``` - - If the nodes are still starting and catching up with the chain, you will see the following repsonse: - -```HTML - - 503 Service Temporarily Unavailable - -

503 Service Temporarily Unavailable

- -``` - -> **NOTE:** By default and for security reasons the load balancer is available only from within the default VPC in the region where it is deployed. It is not available from the Internet and is not open for external connections. Before opening it up please make sure you protect your RPC APIs. - -### Clearing up and undeploying everything - -Destroy RPC Nodes, Sync Nodes and Comon components - -```bash -# Setting the AWS account id and region in case local .env file is lost - export AWS_ACCOUNT_ID= - export AWS_REGION= - -pwd -# Make sure you are in aws-blockchain-node-runners/lib/ethereum - -# Destroy Single RPC Node -cdk destroy eth-single-node - -# Destroy RPC Nodes -cdk destroy eth-rpc-nodes - -# Destroy Sync Node -cdk destroy eth-sync-node - -# You need to manually delete an s3 bucket with a name similar to 'eth-snapshots-$accountid-eth-nodes-common' on the console,firstly empty the bucket,secondly delete the bucket,and then execute -# Delete all common components like IAM role and Security Group -cdk destroy eth-common -``` - +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* \ No newline at end of file From 9ba6470fb13c844db22f3bd29a14275d03c8ed15 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Thu, 22 Aug 2024 18:51:02 -0400 Subject: [PATCH 05/18] execution and consensus layer options links --- lib/ethereum/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index db307d01..f5934f83 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -95,9 +95,9 @@ Configure your setup. | Execution and Consensus Layer Client Options | | --- | -| [Geth Lighthouse](../lib/ethereum/geth-noderunners-docs.md) | -| [Erigon Lighthouse](../lib/ethereum/lighthouse-erigon-noderunners-docs.md) | -| [Erigon Prysm](../lib/ethereum/prysm-erigon-noderunners-docs.md) | +| [Geth Lighthouse](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/geth-noderunners-docs.md) | +| [Erigon Lighthouse](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/lighthouse-erigon-noderunners-docs.md) | +| [Erigon Prysm](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/prysm-erigon-noderunners-docs.md) | Don’t see a client or client combination you would like supported? Open a GitHub [issue](https://github.com/aws-samples/aws-blockchain-node-runners/issues) or [Pull Request](https://github.com/aws-samples/aws-blockchain-node-runners/pulls), we encourage [contribution](https://github.com/aws-samples/aws-blockchain-node-runners/blob/main/CONTRIBUTING.md) to Node Runners! From 79d39e9e6f0bbbae3b294f7300dac1c6be50019e Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Thu, 22 Aug 2024 19:01:31 -0400 Subject: [PATCH 06/18] typo edits --- lib/ethereum/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index f5934f83..ba878385 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -125,7 +125,7 @@ Don’t see a client or client combination you would like supported? Open a GitH - Navigate to [CloudWatch service](https://console.aws.amazon.com/cloudwatch/) (make sure you are in the region you have specified for `AWS_REGION`) - Open `Dashboards` and select `eth-sync-node-` from the list of dashboards. -4. Once the initial synchronization is done, you should be able to access the RPC API of that node from within the same VPC. The RPC port is not exposed to the Internet. Tun the following query against the private IP of the single RPC node you deployed: +4. Once the initial synchronization is done, you should be able to access the RPC API of that node from within the same VPC. The RPC port is not exposed to the Internet. Turn the following query against the private IP of the single RPC node you deployed: ```bash INSTANCE_ID=$(cat single-node-deploy.json | jq -r '..|.node-instance-id? | select(. != null)') @@ -160,7 +160,7 @@ The result should be like this (the actual balance might change): Once synchronization process is over, the script will automatically stop both clients and copy all the contents of the `/data` directory to your snapshot S3 bucket. That may take from 30 minutes to about 2 hours. During the process on the dashboard you will see lower CPU and RAM utilization but high data disc throughput and outbound network traffic. The script will automatically start the clients after the process is done. -Note: the snapshot backup process will automatically run ever day at midnight time of the time zone were the sync node runs. To change the schedule, modify `crontab` of the root user on the node's EC2 instance. +Note: the snapshot backup process will automatically run ever day at midnight of the time zone were the sync node runs. To change the schedule, modify `crontab` of the root user on the node's EC2 instance. 3. Configure and deploy 2 RPC Nodes @@ -201,7 +201,7 @@ The result should be like this (the actual balance might change): ### Clearing up and undeploying everything -1. Undeploy RPC Nodes, Sync Nodes and Comon components +1. Undeploy RPC Nodes, Sync Nodes and Common components ```bash # Setting the AWS account id and region in case local .env file is lost From b29d88b39b9fc349135a68bc65416bbc2df34201 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Thu, 22 Aug 2024 19:15:00 -0400 Subject: [PATCH 07/18] client config --- lib/ethereum/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index ba878385..e4b93d69 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -99,6 +99,15 @@ Configure your setup. | [Erigon Lighthouse](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/lighthouse-erigon-noderunners-docs.md) | | [Erigon Prysm](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/prysm-erigon-noderunners-docs.md) | +**Execution and Consensus Layer Client Options** + +| Execution Layer Client | Consensus Layer Client | Documentation Link | +| --- | --- | --- | +| Geth | Lighthouse | [Geth Lighthouse Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/geth-noderunners-docs.md) | +| | Erigon | Lighthouse | [Erigon Lighthouse Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/lighthouse-erigon-noderunners-docs.md) | + + + Don’t see a client or client combination you would like supported? Open a GitHub [issue](https://github.com/aws-samples/aws-blockchain-node-runners/issues) or [Pull Request](https://github.com/aws-samples/aws-blockchain-node-runners/pulls), we encourage [contribution](https://github.com/aws-samples/aws-blockchain-node-runners/blob/main/CONTRIBUTING.md) to Node Runners! 4. Deploy common components such as IAM role, and Amazon S3 bucket to store data snapshots From f602f88e707611c1d28a662427588bed83a1a87a Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Thu, 22 Aug 2024 19:17:23 -0400 Subject: [PATCH 08/18] client config 2 --- lib/ethereum/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index e4b93d69..7f5cc8ee 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -104,7 +104,8 @@ Configure your setup. | Execution Layer Client | Consensus Layer Client | Documentation Link | | --- | --- | --- | | Geth | Lighthouse | [Geth Lighthouse Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/geth-noderunners-docs.md) | -| | Erigon | Lighthouse | [Erigon Lighthouse Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/lighthouse-erigon-noderunners-docs.md) | +| Erigon | Lighthouse | [Erigon Lighthouse Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/lighthouse-erigon-noderunners-docs.md) | +| Erigon | Prysm | [Erigon Prysm Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/prysm-erigon-noderunners-docs.md) | From 8b0488b74034ea5dccaaab7a7884817b8753ff29 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Thu, 22 Aug 2024 19:18:23 -0400 Subject: [PATCH 09/18] clean up --- lib/ethereum/README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index 7f5cc8ee..ed98a723 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -93,12 +93,6 @@ We will use AWS Cloud9 to execute the subsequent commands. Follow the instructio Configure your setup. -| Execution and Consensus Layer Client Options | -| --- | -| [Geth Lighthouse](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/geth-noderunners-docs.md) | -| [Erigon Lighthouse](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/lighthouse-erigon-noderunners-docs.md) | -| [Erigon Prysm](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/prysm-erigon-noderunners-docs.md) | - **Execution and Consensus Layer Client Options** | Execution Layer Client | Consensus Layer Client | Documentation Link | From 6a37a402dd9de135b7984fbca561837d26a60342 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Tue, 27 Aug 2024 16:10:39 -0400 Subject: [PATCH 10/18] Geth Lighthouse drop down --- lib/ethereum/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index ed98a723..08138df7 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -95,6 +95,12 @@ Configure your setup. **Execution and Consensus Layer Client Options** +
+ +Geth Lighthouse + +
+ | Execution Layer Client | Consensus Layer Client | Documentation Link | | --- | --- | --- | | Geth | Lighthouse | [Geth Lighthouse Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/geth-noderunners-docs.md) | From da32970643ca4c75c896972dfd40b70fe2d8c6f9 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Tue, 27 Aug 2024 16:14:25 -0400 Subject: [PATCH 11/18] Geth Lighthouse drop down 2 --- lib/ethereum/README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index 08138df7..94ad6c98 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -99,7 +99,17 @@ Configure your setup. Geth Lighthouse -
+To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Geth / Lighthouse node deployment is as follows, which uses a sample config from the repository: +```bash +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +cd lib/ethereum +pwd +cp ./sample-configs/.env-geth-lighthouse .env +nano .env +``` +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* + +
| Execution Layer Client | Consensus Layer Client | Documentation Link | | --- | --- | --- | From cc475316ae8c8df944dbba693bb550da69d8fd6a Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Tue, 27 Aug 2024 16:19:13 -0400 Subject: [PATCH 12/18] Execution and Consensus Layer Client Options drop down --- lib/ethereum/README.md | 44 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index 94ad6c98..b3e048f1 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -99,6 +99,8 @@ Configure your setup. Geth Lighthouse +**Configure your Node Runners Ethereum - Geth Lighthouse** + To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Geth / Lighthouse node deployment is as follows, which uses a sample config from the repository: ```bash # Make sure you are in aws-blockchain-node-runners/lib/ethereum @@ -111,11 +113,43 @@ nano .env
-| Execution Layer Client | Consensus Layer Client | Documentation Link | -| --- | --- | --- | -| Geth | Lighthouse | [Geth Lighthouse Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/geth-noderunners-docs.md) | -| Erigon | Lighthouse | [Erigon Lighthouse Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/lighthouse-erigon-noderunners-docs.md) | -| Erigon | Prysm | [Erigon Prysm Documentation](https://github.com/varnarmat/aws-blockchain-node-runners/blob/website/lib/ethereum/prysm-erigon-noderunners-docs.md) | +
+ +Erigon Lighthouse + +**Configure your Node Runners Ethereum - Erigon Lighthouse** + +To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: +```bash +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +cd lib/ethereum +pwd +cp ./sample-configs/.env-erigon-lighthouse .env +nano .env +``` +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* + +
+ +
+ +Erigon Prysm + +**Configure your Node Runners Ethereum - Erigon Prysm** + +To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: +```bash +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +cd lib/ethereum +pwd +cp ./sample-configs/.env-erigon-prysm .env +nano .env +``` +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* + +
+ + From fefea4c0587a68cca190db0f828b5f715d7ec2d5 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Tue, 27 Aug 2024 16:21:29 -0400 Subject: [PATCH 13/18] Execution and Consensus Layer Client Options drop down 2 --- lib/ethereum/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index b3e048f1..3cd89808 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -93,13 +93,13 @@ We will use AWS Cloud9 to execute the subsequent commands. Follow the instructio Configure your setup. -**Execution and Consensus Layer Client Options** +### Execution and Consensus Layer Client Options
Geth Lighthouse -**Configure your Node Runners Ethereum - Geth Lighthouse** +### Configure your Node Runners Ethereum - Geth Lighthouse To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Geth / Lighthouse node deployment is as follows, which uses a sample config from the repository: ```bash @@ -117,7 +117,7 @@ nano .env Erigon Lighthouse -**Configure your Node Runners Ethereum - Erigon Lighthouse** +### Configure your Node Runners Ethereum - Erigon Lighthouse To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: ```bash @@ -135,7 +135,7 @@ nano .env Erigon Prysm -**Configure your Node Runners Ethereum - Erigon Prysm** +### Configure your Node Runners Ethereum - Erigon Prysm To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: ```bash From 20a38cae646e74baa6832f6c2a073ccef1bd8622 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Tue, 27 Aug 2024 16:26:10 -0400 Subject: [PATCH 14/18] Execution and Consensus Layer Client Options drop down 3 --- lib/ethereum/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index 3cd89808..f91dca3b 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -98,6 +98,7 @@ Configure your setup.
Geth Lighthouse +
### Configure your Node Runners Ethereum - Geth Lighthouse From 4ccbdcfde33a61d491d3ae9b0788b747f8d0d28b Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Tue, 27 Aug 2024 16:33:10 -0400 Subject: [PATCH 15/18] Execution and Consensus Layer Client Options drop down 4 --- lib/ethereum/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index f91dca3b..f9a3283a 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -100,7 +100,7 @@ Configure your setup. Geth Lighthouse
-### Configure your Node Runners Ethereum - Geth Lighthouse +**Configure your Node Runners Ethereum - Geth Lighthouse** To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Geth / Lighthouse node deployment is as follows, which uses a sample config from the repository: ```bash @@ -117,8 +117,9 @@ nano .env
Erigon Lighthouse +
-### Configure your Node Runners Ethereum - Erigon Lighthouse +**Configure your Node Runners Ethereum - Erigon Lighthouse** To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: ```bash @@ -135,8 +136,9 @@ nano .env
Erigon Prysm +
-### Configure your Node Runners Ethereum - Erigon Prysm +**Configure your Node Runners Ethereum - Erigon Prysm** To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: ```bash From 6936e7f2e072b823a37e99631ac2599c95b6fed4 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Wed, 28 Aug 2024 10:03:09 -0400 Subject: [PATCH 16/18] getting rid of execution/consensus layer config pages --- lib/ethereum/geth-noderunners-docs.md | 12 ------------ lib/ethereum/lighthouse-erigon-noderunners-docs.md | 11 ----------- lib/ethereum/prysm-erigon-noderunners-docs.md | 12 ------------ 3 files changed, 35 deletions(-) delete mode 100644 lib/ethereum/geth-noderunners-docs.md delete mode 100644 lib/ethereum/lighthouse-erigon-noderunners-docs.md delete mode 100644 lib/ethereum/prysm-erigon-noderunners-docs.md diff --git a/lib/ethereum/geth-noderunners-docs.md b/lib/ethereum/geth-noderunners-docs.md deleted file mode 100644 index 1ec1d254..00000000 --- a/lib/ethereum/geth-noderunners-docs.md +++ /dev/null @@ -1,12 +0,0 @@ - -# Configure your Node Runners Ethereum - Geth Lighthouse - -To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Geth / Lighthouse node deployment is as follows, which uses a sample config from the repository: -```bash -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -cd lib/ethereum -pwd -cp ./sample-configs/.env-geth-lighthouse .env -nano .env -``` -> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* \ No newline at end of file diff --git a/lib/ethereum/lighthouse-erigon-noderunners-docs.md b/lib/ethereum/lighthouse-erigon-noderunners-docs.md deleted file mode 100644 index 1a9b1329..00000000 --- a/lib/ethereum/lighthouse-erigon-noderunners-docs.md +++ /dev/null @@ -1,11 +0,0 @@ -# Configure your Node Runners Ethereum - Erigon Lighthouse - -To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: -```bash -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -cd lib/ethereum -pwd -cp ./sample-configs/.env-erigon-lighthouse .env -nano .env -``` -> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* \ No newline at end of file diff --git a/lib/ethereum/prysm-erigon-noderunners-docs.md b/lib/ethereum/prysm-erigon-noderunners-docs.md deleted file mode 100644 index 4c433d6d..00000000 --- a/lib/ethereum/prysm-erigon-noderunners-docs.md +++ /dev/null @@ -1,12 +0,0 @@ - -# Configure your Node Runners Ethereum - Erigon Prysm - -To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Erigon / Prysm node deployment is as follows, which uses a sample config from the repository: -```bash -# Make sure you are in aws-blockchain-node-runners/lib/ethereum -cd lib/ethereum -pwd -cp ./sample-configs/.env-erigon-prysm .env -nano .env -``` -> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* \ No newline at end of file From 3b0bb575211d12b3cb3a6623343ae29c0daa2b80 Mon Sep 17 00:00:00 2001 From: Varsha Narmat Date: Wed, 28 Aug 2024 11:19:02 -0400 Subject: [PATCH 17/18] nethermind teku and besu teku --- lib/ethereum/README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index f9a3283a..0a601051 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -153,6 +153,46 @@ nano .env
+
+ +Nethermind Teku +
+ +**Configure your Node Runners Ethereum - Nethermind Teku** + +To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Geth / Lighthouse node deployment is as follows, which uses a sample config from the repository: +```bash +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +cd lib/ethereum +pwd +cp ./sample-configs/.env-nethermind-teku .env +nano .env +``` +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* + +
+ +
+ +Besu Teku +
+ +**Configure your Node Runners Ethereum - Besu Teku** + +To specify the Ethereum client combination you wish to deploy, create your own copy of `.env` file and edit it using your preferred text editor. The contents of your file for a Geth / Lighthouse node deployment is as follows, which uses a sample config from the repository: +```bash +# Make sure you are in aws-blockchain-node-runners/lib/ethereum +cd lib/ethereum +pwd +cp ./sample-configs/.env-besu-teku .env +nano .env +``` +> **NOTE:** *You can find more examples inside the `sample-configs` directory, which illustrate other Ethereum client combinations.* + +
+ + + From 5dae778fa5318c94c0a782e57c8bcc9c62a74103 Mon Sep 17 00:00:00 2001 From: Nikolay Vlasov Date: Thu, 29 Aug 2024 12:19:20 +1000 Subject: [PATCH 18/18] Fixed br tag in README.md Signed-off-by: Nikolay Vlasov --- lib/ethereum/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/ethereum/README.md b/lib/ethereum/README.md index d0e3ddfe..d61c6659 100644 --- a/lib/ethereum/README.md +++ b/lib/ethereum/README.md @@ -98,7 +98,7 @@ Configure your setup.
Geth Lighthouse -
+
**Configure your Node Runners Ethereum - Geth Lighthouse** @@ -117,7 +117,7 @@ nano .env
Erigon Lighthouse -
+
**Configure your Node Runners Ethereum - Erigon Lighthouse** @@ -136,7 +136,7 @@ nano .env
Erigon Prysm -
+
**Configure your Node Runners Ethereum - Erigon Prysm** @@ -156,7 +156,7 @@ nano .env
Nethermind Teku -
+
**Configure your Node Runners Ethereum - Nethermind Teku** @@ -175,7 +175,7 @@ nano .env
Besu Teku -
+
**Configure your Node Runners Ethereum - Besu Teku**