AWS Database Blog

Deploy an Ethereum development environment using Amazon EC2 and Amazon Managed Blockchain

In this post, you learn how to deploy a cloud-based development environment with which to build, test, and deploy smart contracts on the public Ethereum Goerli testnet via a dedicated Ethereum full node managed using Amazon Managed Blockchain. You can also use the steps outlined in this post to create a development environment on the Ethereum mainnet and other public testnets supported on Managed Blockchain.

Every developer that wishes to create a decentralized application (dApp) that utilizes the Ethereum network, inclusive of both on-chain components like smart contracts and off-chain components such as a React frontend application, needs to utilize industry-standard developer tools such as Ethers.js and Hardhat. However, setting up a development environment to begin building can take a non-marginal amount of time, particularly for those who are just getting started using these tools.

Solution Overview

  • Amazon EC2 – Amazon Elastic Compute Cloud (Amazon EC2) offers secure and resizable compute capacity for virtually any workload. It offers a wide variety of compute instance families to cater to your specific use case. In this post, an EC2 instance running Amazon Linux 2 serves as the primary compute for your Ethereum development environment and connects to your Ethereum full node on Managed Blockchain.
  • Visual Studio Code – Visual Studio Code is a popular desktop integrated development environment (IDE) that is used to develop, test, and debug code in virtually any programming language. With a VS Code plugin, you can connect your VS Code IDE directly to a remote EC2 instance, which will allow you to write code in VS Code and test it directly on your EC2 instance.
  • Amazon Managed Blockchain – Managed Blockchain is a fully managed service that allows you quickly deploy production-grade blockchain infrastructure with a few clicks, including single-tenant Ethereum nodes with which to interact with the public Ethereum mainnet and testnets. With a dedicated full node to connect to public Ethereum networks (Mainnet, Goerli, and Rinkeby), you can read data from the blockchain, broadcast transactions, and subscribe to events on the blockchain. Managed Blockchain for Ethereum does the heavy lifting of spinning up and maintaining Go-ethereum (geth) nodes for your applications, eliminating the requirement for you to manage instance configuration, software patching, and node health checks.
  • Ethers.js – Ethers.js is an industry-standard library that provides a complete and compact library for interacting with the Ethereum Blockchain and its ecosystem.
  • Hardhat – Hardhat provides a suite of Ethereum development environment tools to develop and test Solidity smart contracts. In this post, we use Hardhat to deploy our smart contracts and write tests for them.

Ethereum developer tools interact with the blockchain through your node through its JSON-RPC API, which serves as an interface for common blockchain interactions. There are two methodologies for access to your Ethereum node’s JSON RPC API when using Managed Blockchain: Signature Version 4 (SigV4) and Token-based Access (TBA).

SigV4 is a hash-based message authentication code (HMAC) mechanism that is used to authenticate AWS SDK calls. It provides several security guarantees, including request expiration timestamping at signing time, payload signature per request, and more.

Although SigV4 has been the main way to authorize requests, it poses interoperability challenges with established community tools (such as Ethers.js, Hardhat, Foundry, and so on) that rely on a direct connection to an Ethereum RPC endpoint and aren’t designed to create and append an AWS SigV4 signature to requests. As a result, customers have relied on middleware or custom proxies that were capable of signing mid-flight requests from applications using Ethereum developer tools to nodes hosted on Managed Blockchain.

Token-based access, a new access method for Ethereum nodes on Managed Blockchain, presents a solution to this interoperability problem by allowing you to optionally use a token (accessor) to access your node rather than a SigV4 signature. Accessors can now be provided as part of the request object when communicating with the JSON RPC API for your Ethereum nodes. For a quick-start guide on how to create and use accessors to access these Ethereum JSON RPC API methods, refer to Introducing token-based access to Ethereum node APIs on Amazon Managed Blockchain.

The following figure illustrates the solution architecture.

The following sections outline how to configure, deploy, and test your cloud-based Ethereum development environment on the public Ethereum Goerli testnet. This guide utilizes the AWS Cloud Development Kit (AWS CDK) to provide a templated deployment that automates much of the process of deploying the environment in a repeatable manner.

Prerequisites

To follow the steps in this post, you need to install a few dependencies and prepare your local environment to use AWS CDK and deploy resources in your AWS account. Complete the following steps:

  1. Install the AWS Command Line Interface (AWS CLI).
    The AWS CLI allows you to interact with AWS services from a terminal session. Make sure you have the latest version of the AWS CLI installed on your system, which you can install using the following methods:

    • Windows – MSI installer (64-bit)
    • Linux, macOS, or Unix – Bundled installer

    To use the AWS CLI to interact with AWS services, you must configure it with your AWS credentials and default region.

  2. In a terminal session, run the command aws configure, then follow the prompts to add your AWS access key ID, secret access key, and default Region. Leave the prompt for the default output format blank.
  3. To run the CDK application, you need to install Node.js with a version >=8.12.0. It is recommended that you use Node Version Manager (NVM) because it makes it easy to change your Node.js version on the fly for testing purposes. For instructions, refer to Installing and Updating.
  4. To access the EC2 instance that you create as your development environment, you need to create an EC2 key pair that you can use for SSH access to the instance:
    • On the Amazon EC2 console, in the navigation pane, under Network & Security, choose Key Pairs.
    • Choose Create key pair.
    • For Name, enter a descriptive name for the key pair.

Amazon EC2 associates the public key with the name that you specify as the key name. A key name can include up to 255 ASCII characters. It can’t include leading or trailing spaces.

  1. For Key pair type, choose either RSA or ED25519.
  2. For Private key file format, choose the format in which to save the private key. To save the private key in a format that can be used with OpenSSH, select pem. To save the private key in a format that can be used with PuTTY, select ppk.
  3. To add a tag to the public key, choose Add tag, and enter the key and value for the tag. Repeat for each tag.
  4. Choose Create key pair.

The private key file is automatically downloaded by your browser. The base file name is the name that you specified as the name of your key pair, and the file name extension is determined by the file format that you chose.

  1. Save the private key file in a safe place.
  2. If you will use an SSH client on a macOS or Linux computer to connect to your Linux instance, use the following command to set the permissions of your private key file so that only you can read it:
chmod 400 <key-pair-name>.pem

Install the AWS SDK

To deploy the AWS services that will be used for your Ethereum development environment, such as a node on Managed Blockchain and an EC2 instance, you use the AWS CDK. The AWS CDK accelerates cloud development using common programming languages to model your applications, translating code into AWS CloudFormation templates to repeatably deploy your applications and architectures in AWS. In this example, you write an AWS CDK application in Typescript, an extension of JavaScript using a Node.js runtime. Therefore, you need to install the AWS CDK Toolkit for Node.js using Node Package Manager (NPM).

To install the AWS CDK Toolkit, a command-line utility that allows you to work with AWS CDK apps, open a terminal session and run the following command:

npm install -g aws-cdk

Note that on Windows, you’ll need to run this as an administrator. On POSIX/UNIX systems, you may need to run this with sudo.

You can check the toolkit version by running the command:

cdk --version

Download and run the AWS CDK application

Next, you download the repository that contains the AWS CDK application for the Ethereum development environment deployment.

  1. First, run the git command to retrieve the repository to your local machine: 
    git clone https://github.com/aws-samples/automated-goerli-development-environment
  2. Change directories to automated-goerli-development-environment/ to configure your AWS CDK application: 
    cd automated-goerli-development-environment
  3. Configure the application for deployment in your preferred IDE (for example, VSCode) or using a command line editor like Vim. For example, to use Vim to edit your config file, run the following commands from the main project directory: 
    cp ./configs/config_template.json ./configs/config.json
vim ./configs/config.json
  4. In the Vim editor, choose i to enter Insert mode, which you use to modify a few key properties: 
    {
"stackName": "BlogGoerliStack",
"ec2Name": "AMB_Dev",
"nickName": "AMB_Dev",
"ec2Class": "t3",
"ec2Size": "xlarge",
"keyName": "<YOUR KEY NAME HERE>",
"keyFile": "<./Key/YOURKEY.pem>",
"userDataFile": "./Scripts/startup_user.sh",
"cdkOut": "cdk-outputs.json",
"timeBomb": "30",
"awsConfig": "~/.aws",
"clientIpAddr": "<Please add the CIDR IP address of client connecting to EC2>",
"Mnemonic": "<your test 12 word seed phrase>“ **SEE IMPORTANT WARNING BELOW
}

Replace the keyName and keyFile properties with the name and path to your saved EC2 key file, respectively. Replace the placeholder for clientIpAddr with your IP address, which will restrict access to your development environment instance to only your IP address. You should also create a burner Ethereum wallet that you’ll use to test with, which you import into this development environment using a mnemonic seed phrase (12 words) for a test wallet that doesn’t have mainnet funds.

***Note that you should not import an Ethereum wallet mnemomic seed phrase with funds or any wallet that you use on mainnet, because you risk losing your assets.

  1. After you have made your updates to the configuration file, save your changes in Vim by entering :wq and choosing Enter or Return on your keyboard.

This will write-quit, saving changes you made in Vim. Now you’re ready to deploy your AWS CDK application and create your environment.

  1. To deploy the application, run the following commands from your project directory: 
    npm install 
cdk bootstrap
cdk deploy

The initial deployment will take about 3 minutes to complete, but due to sync times for the public Ethereum testnet, the Ethereum node on Managed Blockchain will not be usable for approximately 35 minutes while the blockchain data is synced. When the deployment is complete, an EC2 instance with the tools required to develop, test, compile, and deploy smart contracts on Ethereum will be available to you. This includes the creation of resources required to access the Ethereum node as well, including the VPC, accessor token, and necessary security policies.

Use your Ethereum development environment using SSH

After your AWS CDK application is deployed and your Ethereum node on Managed Blockchain is synced, in a new terminal tab, run the following command to connect to your EC2 instance via SSH:

ssh -i ./Key/YOURKEYNAME.pem ec2-user@INSTANCE_IP_ADDRESS

You can find the value of the variable INSTANCE_IP_ADDRESS in the output of the cdk deploy command run in the previous steps.

When you’re connected to the EC2 instance, you can find boilerplate Solidity code for a simple smart contract along with node.js code to connect to the blockchain, compile the smart contract, deploy the smart contract, and run methods on the smart contract via blockchain transactions. Furthermore, the industry-standard developer tooling for Ethereum, Hardhat, is pre-installed with a sample script for testing the smart contract.

The following directory structure is created:

decentralized-app-for-goerli-nodejs/ 
├─ artifacts/
├─ cache/
├─ contracts/
│ ├─ CountPerAccount.sol
├─ DemoApps/
├─ test/

The directories are described as follows:

  • decentralized-app-for-goerli-nodejs – Parent directory
  • artifacts – Directory used by compiler
  • cache – Directory used by compiler
  • contracts – Solidity code for the smart contract
    • CountPerAccount.sol – a sample smart contract
  • DemoApps – node.js code for blockchain and smart contract access
  • test – Directory containing scripts to run some sample tests on the smart contract using Hardhat

Run the following command to run the static tests on the smart contract using Hardhat before deploying:

cd decentralized-app-for-goerli-nodejs
npx hardhat test

If you desire, you can use other Hardhat tools and commands in this directory.

To connect to the blockchain to deploy the smart contract, you will run the node.js application code in DemoApps. First, you will connect to the Ethereum Goerli testnet via your Managed Blockchain Ethereum node and the app will get the balances of several accounts derived from your mnemonic seed phrase that was imported in earlier steps. Then, it will perform a transaction to transfer the native cryptocurrency with which to pay fees, gEth (Goerli Ether), from one account to another.

cd DemoApps
node demoBlockChainAccess

Next, you call the node.js application method to compile and deploy the smart contract:

node demoContract

Once deployed to the blockchain, the address of the deployed smart contract is automatically saved to the environment for smart contract access. The demoContractAccess method uses this smart contract address to run a transaction to call a method on the smart contract and return the results:

node demoContractAccess

The above method is to access the smart contract. In this method, the transactions are signed and sent to the blockchain through your Amazon Managed Blockchain Ethereum testnet node, and the result is printed to the terminal.

You have now set up your Ethereum development environment on AWS and compiled, deployed, and tested a smart contract. You’re ready to build your own Ethereum application on top of this boilerplate example. Alternatively, you may also use an IDE like Visual Studio Code to connect to your EC2 instance.

OPTIONAL: Connect to your development environment via VS Code

Optionally, you can connect via VS Code:

  1. Go to the Visual Studio downloads website and download the VS Code for your appropriate environment. For detailed instructions, refer to the following based on your OS:
  2. Install the Remote Development Extension for Visual Studio Code.
  3. To configure the SSH config file, go to VS Code Command Palette by choosing Shift+Command+P (macOS) or Ctrl+Shift+P (Windows).
  4. Enter remote and choose Remote-SSH: Open SSH Configuration File 4.

VS Code will present few locations for the configuration file.

  1. Choose the file in your /Users (macOS) or C:\Users (Windows) folder.
  2. Enter the following in the SSH config file: 
    Host AMB_DEV_ENV
HostName _INSTANCE_IP_ADDRESS
User ec2-user
IdentityFile [location where the pem file you downloaded] (whole path like: "/users/…/Key/YOURKEY.pem"
  3. After the SSH configuration is saved, connect to EC2 instance by choosing the green icon at the bottom of the VS Code page.
  4. Choose Connect to Host and choose AMB_DEV_ENV on the drop-down menu.

Once connected to the EC2 instance, you may use the same steps as you followed in “Use Your Ethereum development environment via SSH” from the terminal within VS Code.

Cleanup

To remove the AWS resources you created during the preceding steps, run the following AWS CDK command:

cdk destroy

This command may take a few minutes to complete. Remember to back up any code updates or files you may have created in your environment before running this command, if desired.

Conclusion

In this post, we showed you how to deploy a cloud-based IDE with which to build, test, and deploy smart contracts on the public Ethereum Goerli testnet via a dedicated Ethereum full node managed using Managed Blockchain. With this cloud-based development environment, developers can more easily build and test Ethereum smart contracts without having to manage an Ethereum node or manually configure an environment on their local machine.

To learn more about Token-Based Access, a new interoperability feature for Ethereum nodes on Amazon Managed Blockchain, read Introducing token-based access to Ethereum node APIs on Amazon Managed Blockchain.

About the authors

Forrest Colyer is a blockchain specialist Solutions Architect at AWS. Through his experience with private blockchain solutions led by consortia and public blockchain use cases like NFTs and DeFi, Forrest helps enable customers to identify and implement high-impact blockchain solutions.

Mukesh is a Blockchain Global Senior Partner Solutions Architect at AWS. In this role Mukesh owns technical relationship with Blockchain ISV partners and is their trusted advisor, helping them design their Blockchain solutions most optimally on AWS Cloud. Mukesh is a deep technologist with a focus on driving the adoption of blockchain, Digital Assets and other innovative technologies in the public and private sectors, he is proficient in designing high-impact blockchain solutions, and guiding the development and implementation of blockchain applications in the industry. Mukesh lives in the windy city of Chicago, enjoys exploring new travel destinations and picking up new skills, whether it be a new coding language or whipping up a new Indian dish in the kitchen!