Polygon Edge AWS Terraform

Polygon Edge is a modular and extensible framework for building Ethereum-compatible blockchain networks.

To find out more about Polygon, visit the official website.

Documentation 📝

If you'd like to learn more about the Polygon Edge, how it works and how you can use it for your project, please check out the Polygon Edge Documentation.

Terraform deployment

This is a fully automated Polygon Edge blockchain infrastructure deployment for AWS cloud provider.

High level overview of the resources that will be deployed:

• Dedicated VPC
• 4 validator nodes (which are also boot nodes)
• 4 NAT gateways to allow nodes outbound internet traffic
• Lambda function used for generating the first (genesis) block and starting the chain
• Dedicated security groups and IAM roles
• S3 bucket used for storing genesis.json file
• Application Load Balancer used for exposing the JSON-RPC endpoint

Prerequisites

Two variables that must be provided, before running the deployment:

• alb_ssl_certificate - the ARN of the certificate from AWS Certificate Manager to be used by ALB for https protocol.
  The certificate must be generated before starting the deployment, and it must have Issued status.
• premine - the account/s that will receive pre mined native currency. Value must follow the official CLI flag specification.

Fault tolerance

Only regions that have 4 availability zones are required for this deployment. Each node is deployed in a single AZ.

By placing each node in a single AZ, the whole blockchain cluster is fault-tolerant to a single node (AZ) failure, as Polygon Edge implements IBFT consensus which allows a single node to fail in a 4 validator node cluster.

Command line access

Validator nodes are not exposed in any way to the public internet (JSON-PRC is accessed only via ALB) and they don't even have public IP addresses attached to them.
Nodes command line access is possible only via AWS Systems Manager - Session Manager.

Base AMI upgrade

This deployment uses ubuntu-focal-20.04-amd64-server AWS AMI. It will not trigger EC2 redeployment if the AWS AMI gets updated.

If, for some reason, base AMI is required to get updated, it can be achieved by running terraform taint command for each instance, before terraform apply.
Instances can be tainted by running the terraform taint module.instances[<instance_number>].aws_instance.polygon_edge_instance command.

Example:

terraform taint module.instances[0].aws_instance.polygon_edge_instance
terraform taint module.instances[1].aws_instance.polygon_edge_instance
terraform taint module.instances[2].aws_instance.polygon_edge_instance
terraform taint module.instances[3].aws_instance.polygon_edge_instance
terraform apply

Resources cleanup

When cleaning up all resources by running terraform destory, the only thing that needs to be manually deleted are validator keys from AWS SSM Parameter Store as they are not stored via Terraform, but with polygon-edge process itself.

Requirements

Name	Version
terraform	>= 1.3.0
aws	>= 4.22.0
awscc	>= 0.27.0
external	>= 2.2.2
local	>= 2.2.3
null	>=3.1.1

Providers

Name	Version
aws	>= 4.22.0
null	>=3.1.1

Modules

Name	Source	Version
alb	./modules/alb	n/a
instances	./modules/instances	n/a
lambda	terraform-aws-modules/lambda/aws	>=3.3.1
s3	terraform-aws-modules/s3-bucket/aws	>= 3.3.0
security	./modules/security	n/a
user_data	./modules/user-data	n/a
vpc	aws-ia/vpc/aws	>= 3.0.1

Resources

Name	Type
null_resource.download_package	resource
aws_availability_zones.current	data source
aws_caller_identity.current	data source
aws_iam_policy_document.genesis_s3	data source
aws_iam_policy_document.genesis_ssm	data source
aws_region.current	data source
null_data_source.downloaded_package	data source

Inputs

Name	Description	Type	Default	Required
alb_ssl_certificate	SSL certificate ARN for JSON-RPC loadblancer	string	n/a	yes
premine	Premine the accounts with the specified ammount. Format: account:ammount,account:ammount	string	n/a	yes
alb_sec_gr_name_tag	External security group name tag	string	"Polygon Edge External"	no
block_gas_limit	Set the block gas limit	string	""	no
block_gas_target	Sets the target block gas limit for the chain	string	""	no
block_time	Set block production time in seconds	string	""	no
chain_data_ebs_name_tag	The name of the chain data EBS volume.	string	"Polygon_Edge_chain_data_volume"	no
chain_data_ebs_volume_size	The size of the chain data EBS volume.	number	30	no
chain_id	Set the Chain ID	string	""	no
chain_name	Set the name of chain	string	""	no
consensus	Sets consensus protocol.	string	""	no
dns_name	Sets the DNS name for the network package	string	""	no
ebs_device	The ebs device path. Defined when creating EBS volume.	string	"/dev/nvme1n1"	no
ebs_root_name_tag	The name tag for the Polygon Edge instance root volume.	string	"Polygon_Edge_Root_Volume"	no
epoch_size	Set the epoch size	string	""	no
instance_interface_name_tag	The name of the instance interface.	string	"Polygon_Edge_Instance_Interface"	no
instance_name	The name of Polygon Edge instance	string	"Polygon_Edge_Node"	no
instance_type	Polygon Edge nodes instance type.	string	"t3.medium"	no
internal_sec_gr_name_tag	Internal security group name tag	string	"Polygon Edge Internal"	no
lambda_function_name	The name of the Lambda function used for chain init	string	"polygon-edge-init"	no
lambda_function_zip	The lambda function code in zip archive	string	"https://raw.githubusercontent.com/Trapesys/polygon-edge-assm/aws-lambda/artifacts/main.zip"	no
max_slots	Sets maximum slots in the pool	string	""	no
max_validator_count	The maximum number of stakers able to join the validator set in a PoS consensus.	string	""	no
min_validator_count	The minimum number of stakers needed to join the validator set in a PoS consensus.	string	""	no
nat_address	Sets the NAT address for the networking package	string	""	no
node_name_prefix	The name prefix that will be used to store secrets	string	"node"	no
nodes_alb_name_prefix	ALB name	string	"jrpc-"	no
nodes_alb_name_tag	ALB name tag	string	"Polygon Edge JSON-RPC ALB"	no
nodes_alb_targetgroup_name_prefix	ALB target group name	string	"jrpc-"	no
polygon_edge_dir	The directory to place all polygon-edge data and logs	string	"/home/ubuntu/polygon"	no
pos	Use PoS IBFT consensus	bool	false	no
price_limit	Sets minimum gas price limit to enforce for acceptance into the pool	string	""	no
prometheus_address	Enable Prometheus API	string	""	no
s3_bucket_prefix	Name prefix for new S3 bucket	string	"polygon-edge-shared-"	no
s3_force_destroy	Delete S3 bucket on destroy, even if the bucket is not empty	bool	true	no
s3_key_name	Name of the file in S3 that will hold configuration	string	"chain-config"	no
ssm_parameter_id	The id that will be used for storing and fetching from SSM Parameter Store	string	"polygon-edge-validators"	no
vpc_cidr_block	CIDR block for VPC	string	"10.250.0.0/16"	no
vpc_name	Name of the VPC	string	"polygon-edge-vpc"	no

Outputs

Name	Description
jsonrpc_dns_name	The dns name for the JSON-RPC API