feat(polygon): add Polygon PoS blueprint with Erigon

Add Polygon PoS Full Node blueprint under lib/polygon/ using Erigon
(0xpolygon/erigon:v3.4.0) as a single-container all-in-one client.

Stacks:
- polygon-common: IAM role with SSM and CloudWatch policies
- polygon-single-node: single EC2 instance (reuses SingleNodeConstruct)
- polygon-ha-nodes: ALB + ASG multi-AZ HA (reuses HANodesConstruct)

Why Erigon over Heimdall+Bor:
- Heimdall v1->v2 migration breaks P2P for v1 clients on both networks
- Heimdall v2 Docker image has init bugs (reported: 0xPolygon/heimdall-v2#568)
- Erigon connects to Polygon official Heimdall API endpoint instead
- Built-in OtterSync for torrent-based snapshot sync

Includes:
- Config with mainnet and amoy sample .env files
- Security group: P2P (30303), torrent (42069) public; RPC (8545) VPC-only
- User-data: Docker install, EBS volume detection, Erigon startup, CloudWatch cron
- README with deployment guide and Well-Architected checklist
- Website docs page
- Jest tests (3/3 passing), cdk-nag compliant
- package.json for CI integration
- Removed polygon from CI test exclusion list

Deployment verified on Graviton m7g.xlarge in us-east-1.

Closes #7
Refs #233

Author: snese

lib/polygon/.gitignore

@@ -0,0 +1,8 @@
+*.js
+!jest.config.js
+*.d.ts
+node_modules
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out

lib/polygon/.npmignore

@@ -0,0 +1,6 @@
+*.ts
+!*.d.ts
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out

lib/polygon/README.md

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import 'dotenv/config'
+import "source-map-support/register";
+import * as cdk from "aws-cdk-lib";
+import * as nag from "cdk-nag";
+import * as config from "./lib/config/node-config";
+
+import { PolygonSingleNodeStack } from "./lib/single-node-stack";
+import { PolygonHaNodesStack } from "./lib/ha-nodes-stack";
+import { PolygonCommonStack } from "./lib/common-stack";
+
+const app = new cdk.App();
+cdk.Tags.of(app).add("Project", "AWSPolygon");
+
+new PolygonCommonStack(app, "polygon-common", {
+    stackName: `polygon-nodes-common`,
+    env: { account: config.baseConfig.accountId, region: config.baseConfig.region },
+});
+
+new PolygonSingleNodeStack(app, "polygon-single-node", {
+    stackName: `polygon-single-node-${config.baseConfig.network}`,
+    env: { account: config.baseConfig.accountId, region: config.baseConfig.region },
+    network: config.baseConfig.network,
+    erigonImage: config.baseConfig.erigonImage,
+    heimdallApiUrl: config.baseConfig.heimdallApiUrl,
+    instanceType: config.singleNodeConfig.instanceType,
+    instanceCpuType: config.singleNodeConfig.instanceCpuType,
+    dataVolume: config.singleNodeConfig.dataVolumes[0],
+});
+
+new PolygonHaNodesStack(app, "polygon-ha-nodes", {
+    stackName: `polygon-ha-nodes-${config.baseConfig.network}`,
+    env: { account: config.baseConfig.accountId, region: config.baseConfig.region },
+    network: config.baseConfig.network,
+    erigonImage: config.baseConfig.erigonImage,
+    heimdallApiUrl: config.baseConfig.heimdallApiUrl,
+    instanceType: config.haNodeConfig.instanceType,
+    instanceCpuType: config.haNodeConfig.instanceCpuType,
+    numberOfNodes: config.haNodeConfig.numberOfNodes,
+    albHealthCheckGracePeriodMin: config.haNodeConfig.albHealthCheckGracePeriodMin,
+    heartBeatDelayMin: config.haNodeConfig.heartBeatDelayMin,
+    dataVolume: config.haNodeConfig.dataVolumes[0],
+});
+
+cdk.Aspects.of(app).add(
+    new nag.AwsSolutionsChecks({
+        verbose: false,
+        reports: true,
+        logIgnores: false,
+    })
+);

lib/polygon/app.ts

@@ -0,0 +1,32 @@
+{
+  "app": "npx ts-node --prefer-ts-exts app.ts",
+  "watch": {
+    "include": ["**"],
+    "exclude": ["README.md", "cdk*.json", "**/*.d.ts", "**/*.js", "tsconfig.json", "package*.json", "yarn.lock", "node_modules", "test"]
+  },
+  "context": {
+    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
+    "@aws-cdk/core:checkSecretUsage": true,
+    "@aws-cdk/core:target-partitions": [
+      "aws",
+      "aws-cn"
+    ],
+    "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
+    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
+    "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
+    "@aws-cdk/aws-iam:minimizePolicies": true,
+    "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
+    "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
+    "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
+    "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
+    "@aws-cdk/aws-apigateway:disableCloudWatchRole": true,
+    "@aws-cdk/core:enablePartitionLiterals": true,
+    "@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
+    "@aws-cdk/aws-iam:standardizedServicePrincipals": true,
+    "@aws-cdk/aws-ecs:disableExplicitDeploymentControllerForCircuitBreaker": true,
+    "@aws-cdk/aws-iam:importedRoleStackSafeDefaultPolicyName": true,
+    "@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true,
+    "@aws-cdk/aws-route53-patters:useCertificate": true,
+    "@aws-cdk/customresources:installLatestAwsSdkDefault": false
+  }
+}

lib/polygon/cdk.json

@@ -0,0 +1,8 @@
+module.exports = {
+  testEnvironment: 'node',
+  roots: ['<rootDir>/test'],
+  testMatch: ['**/*.test.ts'],
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest'
+  },
+};

lib/polygon/doc/assets/.gitkeep

@@ -0,0 +1,143 @@
+#!/bin/bash
+set -euo pipefail
+
+# Variables injected by CDK via Fn::Sub
+REGION="${_REGION_}"
+ASSETS_S3_PATH="${_ASSETS_S3_PATH_}"
+POLYGON_NETWORK="${_POLYGON_NETWORK_}"
+POLYGON_ERIGON_IMAGE="${_POLYGON_ERIGON_IMAGE_}"
+POLYGON_HEIMDALL_API_URL="${_POLYGON_HEIMDALL_API_URL_}"
+STACK_NAME="${_STACK_NAME_}"
+DATA_VOLUME_TYPE="${_DATA_VOLUME_TYPE_}"
+DATA_VOLUME_SIZE="${_DATA_VOLUME_SIZE_}"
+
+# Map network name to Erigon chain name
+case "$POLYGON_NETWORK" in
+    mainnet) POLYGON_CHAIN_NAME="bor-mainnet" ;;
+    amoy)    POLYGON_CHAIN_NAME="amoy" ;;
+    *)       POLYGON_CHAIN_NAME="bor-mainnet" ;;
+esac
+
+echo "========== Polygon Node Setup Starting =========="
+echo "Network: $POLYGON_NETWORK (chain: $POLYGON_CHAIN_NAME)"
+echo "Erigon Image: $POLYGON_ERIGON_IMAGE"
+
+# Install dependencies
+yum update -y
+yum install -y docker jq aws-cfn-bootstrap amazon-cloudwatch-agent cronie
+
+# Start Docker
+systemctl enable docker
+systemctl start docker
+
+# Install docker-compose
+ARCH=$(uname -m)
+curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$ARCH" -o /usr/local/bin/docker-compose
+chmod +x /usr/local/bin/docker-compose
+
+# Format and mount data volume
+# Note: CloudFormation VolumeAttachment may take several minutes after instance launch.
+# We poll for up to 10 minutes for the device to appear.
+DATA_DIR="/data"
+mkdir -p "$DATA_DIR"
+if [ "$DATA_VOLUME_TYPE" != "instance-store" ]; then
+    echo "Waiting for EBS data volume to be attached..."
+    WAIT_SECONDS=0
+    MAX_WAIT=600
+    DEVICE=""
+    while [ $WAIT_SECONDS -lt $MAX_WAIT ]; do
+        # Look for unformatted nvme device larger than 100GB (skip root volume)
+        DEVICE=$(lsblk -lnb | awk '{if ($7 == "" && $4 > 100000000000) {print "/dev/"$1}}' | grep nvme | sort | head -1)
+        if [ -n "$DEVICE" ]; then
+            echo "Found data volume: $DEVICE after $WAIT_SECONDS seconds"
+            break
+        fi
+        # Also check traditional device names
+        for dev in /dev/sdf /dev/xvdf; do
+            if [ -e "$dev" ]; then DEVICE="$dev"; break 2; fi
+        done
+        sleep 10
+        WAIT_SECONDS=$((WAIT_SECONDS + 10))
+        echo "Waiting for data volume... ($WAIT_SECONDS seconds/$MAX_WAIT seconds)"
+    done
+
+    if [ -n "$DEVICE" ]; then
+        echo "Using device: $DEVICE"
+        if ! blkid "$DEVICE" 2>/dev/null; then
+            mkfs.xfs "$DEVICE"
+        fi
+        mount "$DEVICE" "$DATA_DIR"
+        VOLUME_UUID=$(blkid -s UUID -o value "$DEVICE")
+        echo "UUID=$VOLUME_UUID $DATA_DIR xfs defaults,nofail 0 2" >> /etc/fstab
+    else
+        echo "WARNING: No data volume found after $MAX_WAIT seconds. Using root volume for data."
+    fi
+fi
+
+# Create data directory
+mkdir -p "$DATA_DIR/erigon"
+chmod -R 777 "$DATA_DIR/erigon"
+
+# Create docker-compose file
+cat > /home/ec2-user/docker-compose.yml << COMPOSEOF
+services:
+  erigon:
+    image: $POLYGON_ERIGON_IMAGE
+    container_name: erigon
+    restart: always
+    command:
+      - --chain=$POLYGON_CHAIN_NAME
+      - --bor.heimdall=$POLYGON_HEIMDALL_API_URL
+      - --datadir=/var/lib/erigon/data
+      - --http
+      - --http.api=eth,debug,net,trace,web3,erigon,txpool,bor
+      - --http.addr=0.0.0.0
+      - --http.vhosts=*
+      - --torrent.download.rate=512mb
+      - --metrics
+      - --metrics.addr=0.0.0.0
+      - --maxpeers=100
+    ports:
+      - "8545:8545"
+      - "30303:30303/tcp"
+      - "30303:30303/udp"
+      - "42069:42069/tcp"
+      - "42069:42069/udp"
+    volumes:
+      - $DATA_DIR/erigon:/var/lib/erigon/data
+COMPOSEOF
+
+# Start services
+cd /home/ec2-user
+/usr/local/bin/docker-compose up -d
+
+# Setup sync checker cron (publish metrics to CloudWatch every 5 min)
+cat > /home/ec2-user/sync-checker.sh << 'CHECKEREOF'
+#!/bin/bash
+INSTANCE_ID=$(curl -s http://169.254.169.254/latest/meta-data/instance-id)
+
+# Check if Erigon is syncing
+SYNCING=$(curl -s -X POST -H "Content-Type: application/json" \
+    --data '{"method":"eth_syncing","params":[],"id":1,"jsonrpc":"2.0"}' \
+    http://localhost:8545 2>/dev/null | jq -r '.result')
+
+BLOCK_HEX=$(curl -s -X POST -H "Content-Type: application/json" \
+    --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' \
+    http://localhost:8545 2>/dev/null | jq -r '.result // "0x0"')
+BLOCK=$((BLOCK_HEX))
+
+IS_SYNCING=1
+if [ "$SYNCING" = "false" ]; then IS_SYNCING=0; fi
+
+aws cloudwatch put-metric-data --namespace "Polygon/Node" --dimensions InstanceId="$INSTANCE_ID" \
+    --metric-data "[{\"MetricName\":\"ErigonBlockHeight\",\"Value\":$BLOCK,\"Unit\":\"Count\"},{\"MetricName\":\"ErigonSyncing\",\"Value\":$IS_SYNCING,\"Unit\":\"Count\"}]" 2>/dev/null || true
+CHECKEREOF
+
+chmod +x /home/ec2-user/sync-checker.sh
+echo "*/5 * * * * /home/ec2-user/sync-checker.sh" | crontab -
+
+# Note: cfn-signal is not used because CreationPolicy is disabled
+# (avoids circular dependency with VolumeAttachment).
+# Node health is monitored via CloudWatch metrics instead.
+
+echo "========== Polygon Node Setup Complete =========="

lib/polygon/jest.config.js

@@ -0,0 +1,52 @@
+import * as cdk from "aws-cdk-lib";
+import * as cdkConstructs from "constructs";
+import * as iam from "aws-cdk-lib/aws-iam";
+import * as s3Assets from "aws-cdk-lib/aws-s3-assets";
+import * as path from "path";
+import * as nag from "cdk-nag";
+
+export class PolygonCommonStack extends cdk.Stack {
+    constructor(scope: cdkConstructs.Construct, id: string, props?: cdk.StackProps) {
+        super(scope, id, props);
+
+        const region = cdk.Stack.of(this).region;
+        const asset = new s3Assets.Asset(this, "assets", {
+            path: path.join(__dirname, "assets"),
+        });
+
+        const instanceRole = new iam.Role(this, `node-role`, {
+            assumedBy: new iam.ServicePrincipal("ec2.amazonaws.com"),
+            managedPolicies: [
+                iam.ManagedPolicy.fromAwsManagedPolicyName("AmazonSSMManagedInstanceCore"),
+                iam.ManagedPolicy.fromAwsManagedPolicyName("CloudWatchAgentServerPolicy"),
+            ],
+        });
+
+        instanceRole.addToPolicy(
+            new iam.PolicyStatement({
+                resources: ["*"],
+                actions: ["cloudformation:SignalResource"],
+            })
+        );
+
+        new cdk.CfnOutput(this, "Instance Role ARN", {
+            value: instanceRole.roleArn,
+            exportName: "PolygonNodeInstanceRoleArn",
+        });
+
+        nag.NagSuppressions.addResourceSuppressions(
+            this,
+            [
+                {
+                    id: "AwsSolutions-IAM4",
+                    reason: "AmazonSSMManagedInstanceCore and CloudWatchAgentServerPolicy are restrictive enough",
+                },
+                {
+                    id: "AwsSolutions-IAM5",
+                    reason: "Can't target specific stack: https://github.com/aws/aws-cdk/issues/22657",
+                },
+            ],
+            true
+        );
+    }
+}

lib/polygon/lib/assets/user-data/node.sh

@@ -0,0 +1,15 @@
+import * as configTypes from "../../../constructs/config.interface";
+
+export type PolygonNetwork = "mainnet" | "amoy";
+
+export interface PolygonDataVolumeConfig extends configTypes.DataVolumeConfig {}
+
+export interface PolygonBaseConfig extends configTypes.BaseConfig {
+    network: PolygonNetwork;
+    erigonImage: string;
+    heimdallApiUrl: string;
+}
+
+export interface PolygonSingleNodeConfig extends configTypes.SingleNodeConfig {}
+
+export interface PolygonHaNodeConfig extends configTypes.HaNodesConfig {}