Setting Up Your Hyperchain

Overview

This guide shows you how to set up a Hyperchain using the Aeternity Hyperchains web app. It covers preparing your environment before using the web app and explains how to use the configuration files it generates.

Prerequisites

Before starting the configuration process, please ensure you've met the following requirements:

Hardware Requirements:

• Minimum 4GB RAM dedicated to Hyperchain operations
• 100GB available storage space
• Stable internet connection with minimum 10Mbps upload/download

Software Requirements:

• Node.js v23 or later (for running the Hyperchain Starter Kit configuration tools)
• Docker v27 or later (for node deployment)
• Git (for accessing repositories)
• Ubuntu 20.04 LTS or later

Access credentials:

• Parent chain wallet with sufficient funds for pinning operations
• Private keys for hyperchain staking operations

Node Requirements

Option 1: Use Public Nodes (Recommended for Most Users)

• Mainnet: https://mainnet.aeternity.io
  • Network ID: ae_mainnet
• Testnet: https://testnet.aeternity.io
  • Network ID: ae_uat

Hardware requirements for running a Hyperchain with public nodes:

• 4GB RAM
• 50GB storage
• Stable internet connection (5Mbps+)

Note: When using public nodes, be aware that your Hyperchain's performance may be affected by the node's availability and response times

Option 2: Run Your Own Parent Chain Node (Advanced)

Running your own parent chain node offers more control but requires considerable technical expertise and resources. If you choose this option, you'll need to modify your configuration to point to your own node's URL instead of public nodes.

When providing node URLs in Step 2 of the configuration process, use your own node's address:

https://user:password@your-node-address:port

The middleware and deployment steps in this guide remain the same regardless of whether you use public or private parent chain nodes—only the configuration URLs change.

Hardware Requirements for Running Your Own Node

The following requirements are in addition to the base Hyperchain requirements:

Minimum Requirements

• CPU: 2 cores @ 2.5GHz
• Memory: 4GB RAM
• Storage: 100GB SSD for lightweight node
• Bandwidth: 30KB/s up/down (approximately 156GB/month)

Recommended Requirements

• CPU: 2+ cores @ 3.0GHz
• Memory: 8GB RAM
• Storage: 500GB SSD for full node
• Bandwidth: 500KB/s for optimal performance

Note: Storage requirements grow by approximately 13.5GB per month for full nodes and 3GB for lightweight nodes.

Configuration Process

Step 1: Configure Your Hyperchain

In the first screen of the web interface, you'll set basic operational parameters for your Hyperchain:

1. Hyperchain ID: A Hyperchain ID acts as a unique identifier for your chain to be used in all network communications.
   • Example format: hk_3F2d4E7ffdrey764dygJUGeC89f

1. Hyperchain Block Time: The block time determines the frequency of block production in your chain. Valid range: 0-10,000 milliseconds with 3,000-6,500 milliseconds recommended for optimal performance.

Step 2: Configure Pinning Chain Connection

In the second page of the web app, you'll set the pinning chain parameters:

1. Pinning Chain Selection: Select one of the available pinning chain networks: Network options: ae_mainnet or ae_uat (Aeternity Mainnet or Testnet)

2. Node URLs

For public nodes, use one of the following URLs: Mainnet: https://mainnet.aeternity.io Testnet: https://testnet.aeternity.io For connecting with your own node, use the format: https://user:password@address:port where: user:password: Your authentication credentials address: Node's IP address or domain port: Default is 3013 for HTTP API

3. Parent Epoch Length

The parent epoch length affects synchronization frequency with the pinning (parent) chain, measured in blocks.

• Valid range: 0-100 blocks
• Recommended: 10-12 blocks for standard operation

Step 3: Set Token Economics

Configure the economic parameters that will govern your Hyperchain:

1. Block Reward Block rewards are tokens awarded to validators for block production to incentivize network participation.

2. Example: 2.5 tokens per block

3. Pinning Reward: Pinning rewards are tokens awarded for successful pinning operations that should cover parent chain transaction costs plus margin.

4. Example: 0.1 tokens per pinning action

Step 4: Set Validator Requirements

Define the parameters for network validators:

1. Number of Validators: While validators can be added later, configuring them during setup streamlines the initialization process. Enter the number of validators you wish to pre-configure with your Hyperchain. This creates the necessary accounts and keys automatically.

2. Example: 10 validators

3. Validator Balance: The required token balance for validator participation must be sufficient to ensure committed participation in network operations.

4. Example: 1000 tokens

5. Minimum Staking Amount: The minimum validator stake requirement establishes the entry threshold for participating as a network validator, denominated in the native tokens of your Hyperchain.

   • Example: 100 tokens (native Hyperchain tokens)

After completing the web app configuration steps, you'll receive your Hyperchain Configuration File (init.yaml) which contains core network parameters and should be stored securely and backed up.

Post-Configuration Steps

1. Prepare Your Environment:

Open your terminal to begin the setup process. First, update your system's package list and install all required software dependencies:

sudo apt-get update
sudo apt-get install -y docker.io nodejs npm git

Next, create a dedicated directory for your hyperchain and make a backup folder for safety:

mkdir -p ~/hyperchain/backups
cd ~/hyperchain

Verify your installations worked correctly by checking versions:

node --version
docker --version
npm --version
git --version

These commands should display version numbers for each tool. If any command fails, try reinstalling that specific package. Your environment is ready when all three commands show version numbers successfully.

2. Install the Hyperchains Starter Kit

Now that your environment is ready, you'll need to install the Hyperchains starter kit. Begin by opening your terminal and cloning the starter kit repository from GitHub:

git clone -b v0.1.0 https://github.com/aeternity/hyperchain-starter-kit
cd hyperchain-starter-kit
npm install
npm run dev

Next, initialize your Hyperchain configuration directory:

npm run dev init hc_test

Note: Throughout this guide, replace "hc_test" with your chosen Hyperchain directory name (no spaces or special characters) in all commands and file paths.

Finally, locate the init.yaml file you downloaded from the web app and copy it into your newly created directory:

cp /path/to/downloaded/init.yaml hc_test/

Replace /path/to/downloaded/ with the actual path to where your browser saved the init.yaml file.

3. Generate Keys and Setup Economy

This step will automatically generate all required accounts and keys:

npm run dev retrieve-contracts hc_test
npm run dev gen-economy hc_test
npm run dev gen-node-conf hc_test

This creates an economy-unencrypted.yaml file containing:

• Faucet account credentials
• Treasury account credentials
• Validator account credentials
• Pinner account credentials

Important: Store these credentials securely - While the node can operate without these keys, these private keys are your only means of accessing the funds in these accounts. If lost, the funds will be permanently inaccessible.

Important Configuration Note for v7.3.0-rc5

If you're using Aeternity node version v7.3.0-rc5 or later, you must manually edit the generated aeternity.yaml file to add the required child_block_production_time parameter. Open the file in a text editor:

nano hc_test/nodeConfig/aeternity.yaml

Locate the config: section under the consensus configuration and add:

child_block_production_time: 500

This parameter is required due to breaking changes in RC5 and ensures your Hyperchain functions correctly.

4. Deploy Your Hyperchain

You now have two options for deploying your Hyperchain:

Option A: Deploy Middleware (Required for Web App Validator/Delegator Features)

Aeternity Middleware (AeMdw) is required to use the validator and delegator portions of the web app. Middleware provides essential monitoring and reporting capabilities, and you'll need the middleware URL for the validator addition flow in the web app.

Important: Middleware includes its own node instance, so you don't need to run a separate node container.

First, create a Docker network to allow containers to communicate with each other:

docker network create hyperchain

Then deploy middleware with your Hyperchain configuration:

docker run -d --name ae_mdw_hc_test --network hyperchain \
    -p 3013:3013 -p 4000:4000 -p 4001:4001 -p 3113:3113 -p 3014:3014 \
    -v ${PWD}/hc_test/nodeConfig/aeternity.yaml:/home/aeternity/.aeternity/aeternity/aeternity.yaml \
    -v ${PWD}/hc_test/nodeConfig/hc_test_accounts.json:/home/aeternity/node/data/aecore/hc_test_accounts.json \
    -v ${PWD}/hc_test/nodeConfig/hc_test_contracts.json:/home/aeternity/node/data/aecore/hc_test_contracts.json \
    aeternity/ae_mdw:latest

Note:

• We use the -d flag to run the container in detached mode (in the background).
• To view logs and monitor the middleware in real-time, you can use docker logs ae_mdw_hc_test -f
• Replace hc_test in both the container name and file paths with your chosen Hyperchain directory name

Port Reference:

• 3013: Node HTTP API
• 3113: Node internal API
• 4000: Middleware HTTP API
• 4001: Middleware WebSocket API
• 3014: Additional node access

Verify your middleware is running with:

curl -s localhost:4000/v3/status | jq

Option B: Deploy Node Only (For Testing Without Web App Features)

If you're just testing a Hyperchain and don't plan to use the validator or delegator features of the web app, you can run just a node without middleware:

docker run -d --name node_only \
    -p 3013:3013 \
    -v ${PWD}/hc_test/nodeConfig/aeternity.yaml:/home/aeternity/.aeternity/aeternity/aeternity.yaml \
    -v ${PWD}/hc_test/nodeConfig/hc_test_accounts.json:/home/aeternity/node/data/aecore/hc_test_accounts.json \
    -v ${PWD}/hc_test/nodeConfig/hc_test_contracts.json:/home/aeternity/node/data/aecore/hc_test_contracts.json \
    aeternity/aeternity:v7.3.0-rc5

Note: To view logs and monitor the node in real-time, you can use docker logs node_only -f

Verify your node is running with:

curl -s localhost:3013/v3/status | jq

Adding Data Persistence (Recommended)

For data persistence across container restarts, add volume mounts for the databases:

For Middleware (Option A):

mkdir -p data/mnesia data/mdw.db
chown 1000:1000 data/mnesia data/mdw.db  # Ensure proper permissions

docker run -d --name ae_mdw_hc_test --network hyperchain \
    -p 3013:3013 -p 4000:4000 -p 4001:4001 -p 3113:3113 -p 3014:3014 \
    -v ${PWD}/hc_test/nodeConfig/aeternity.yaml:/home/aeternity/.aeternity/aeternity/aeternity.yaml \
    -v ${PWD}/hc_test/nodeConfig/hc_test_accounts.json:/home/aeternity/node/data/aecore/hc_test_accounts.json \
    -v ${PWD}/hc_test/nodeConfig/hc_test_contracts.json:/home/aeternity/node/data/aecore/hc_test_contracts.json \
    -v ${PWD}/data/mnesia:/home/aeternity/node/data/mnesia \
    -v ${PWD}/data/mdw.db:/home/aeternity/node/data/mdw.db \
    aeternity/ae_mdw:latest

For Node Only (Option B):

mkdir -p data/mnesia
chown 1000:1000 data/mnesia  # Ensure proper permissions

docker run -d --name node_only \
    -p 3013:3013 \
    -v ${PWD}/hc_test/nodeConfig/aeternity.yaml:/home/aeternity/.aeternity/aeternity/aeternity.yaml \
    -v ${PWD}/hc_test/nodeConfig/hc_test_accounts.json:/home/aeternity/node/data/aecore/hc_test_accounts.json \
    -v ${PWD}/hc_test/nodeConfig/hc_test_contracts.json:/home/aeternity/node/data/aecore/hc_test_contracts.json \
    -v ${PWD}/data/mnesia:/home/aeternity/node/data/mnesia \
    aeternity/aeternity:v7.3.0-rc5

5. Deploy Additional Node (Optional for Middleware Users)

If you deployed middleware (Option A) and want to run an additional standalone node alongside your middleware instance (for redundancy or specific testing), you'll need to configure it to connect to your existing Hyperchain network without duplicating validator functionality.

First, you'll need to determine the peer key of your existing middleware node. You can find this by running:

curl -s localhost:3013/v3/status | jq -r '.peer_pubkey'

Then, you'll need to create a modified configuration for the additional node:

# Create a copy of the config for the second node
cp hc_test/nodeConfig/aeternity.yaml hc_test/nodeConfig/aeternity_node2.yaml

# Edit the file to add peer configuration and remove validators
nano hc_test/nodeConfig/aeternity_node2.yaml

Make the following important modifications to the configuration file:

1. Add the peers section to connect to the existing node:

   peers:
   - aenode://PEER_KEY@ae_mdw_hc_test:3015
   

   Replace PEER_KEY with the peer pubkey you obtained earlier.

2. Important: Remove the stakers and pinners sections from the configuration. This prevents the additional node from trying to act as a validator, which would cause conflicts with your existing validator node. The additional node will operate as a read-only node that verifies and follows the blockchain but does not participate in block production or pinning.

Now deploy the additional node with this modified configuration:

docker run -d --name node_only --network hyperchain \
    -p 3014:3013 \
    -v ${PWD}/hc_test/nodeConfig/aeternity_node2.yaml:/home/aeternity/.aeternity/aeternity/aeternity.yaml \
    -v ${PWD}/hc_test/nodeConfig/hc_test_accounts.json:/home/aeternity/node/data/aecore/hc_test_accounts.json \
    -v ${PWD}/hc_test/nodeConfig/hc_test_contracts.json:/home/aeternity/node/data/aecore/hc_test_contracts.json \
    aeternity/aeternity:v7.3.0-rc5

Important: Never run multiple nodes with the same validator configuration. Each validator should only be running on a single node at any time. Running the same validator configuration on multiple nodes could lead to conflicting block production and network instability.

Verify this additional node is running with:

curl -s localhost:3014/v3/status | jq

Important: This peer configuration is essential. Without it, the new node would start a completely separate Hyperchain instead of joining your existing one.

Verify this additional node is running with:

curl -s localhost:3014/v3/status | jq

Important Note on Public Chain Configuration

When using a public chain (testnet or mainnet) as your pinning chain, the system automatically sets the start_height to [current block height + 10]. Since blocks on these networks are produced every ~3 minutes, this creates a ~30 minute delay before your Hyperchain becomes active.

Before transacting on your Hyperchain, either:

• Wait approximately 30 minutes for the parent chain to reach the configured start height, or
• Manually decrease the start_height value in your configuration

6. Managing Your Hyperchain

Container Management Commands

Once your Hyperchain is running, you can use these commands to manage the container:

Check container logs:

# For middleware
docker logs ae_mdw_hc_test

# For standalone node
docker logs node_only

# Follow logs in real-time (add -f flag)
docker logs -f ae_mdw_hc_test

Check container status:

docker ps -a

Stop container:

# For middleware
docker stop ae_mdw_hc_test

# For standalone node
docker stop node_only

Restart container:

# For middleware
docker start ae_mdw_hc_test

# For standalone node
docker start node_only

Monitoring Your Hyperchain

With middleware installed, you can monitor your Hyperchain effectively using various endpoints and tools.

Available Endpoints

• HTTP API: http://localhost:4000/ - The main middleware API for querying blockchain data
• WebSocket API: ws://localhost:4001/websocket - For real-time notifications
• Node HTTP API: http://localhost:3013/ - Direct access to the node's public API
• Node Internal API: http://localhost:3113/ - Access to the node's internal API functions
• API Specification: http://localhost:4000/v3/api - The OpenAPI specification

Useful Monitoring Endpoints

• Chain Status: http://localhost:4000/v3/status - Middleware status including node info
• Node Status: http://localhost:3013/v3/status - Direct node status information
• Latest Key Blocks: http://localhost:4000/v3/key-blocks?limit=10
• Transactions: http://localhost:4000/v3/transactions?limit=10
• Validators: http://localhost:4000/v3/hyperchain/validators

Adding Additional Validators

The simplest way to add additional validators to your Hyperchain is through the web app's validator interface at init.hyperchains.ae/validate. The app will guide you through the complete process of setting up a new validator.

When using the web app to register additional validators, you'll need to provide the middleware URL to connect to your existing Hyperchain network:

• For external access: If your middleware is publicly accessible, use http://your-server-ip:4000
• For Docker network internal access: If deploying validator nodes in the same Docker network as your middleware, use http://ae_mdw_hc_test:4000 (using the container name as the hostname)

Important for Docker deployments: When setting up additional validator nodes that need to connect to your middleware within the same Docker network, the URL should be ae_mdw_hc_test:4000 (not localhost). This is because containers in the same Docker network can reference each other by container name.

Each new validator must:

1. Have its own unique staker and pinner accounts (different from any existing validators)
2. Be configured to connect to the existing Hyperchain network as a peer
3. Register with the staking contract using its unique credentials

Critical Note: Never run multiple nodes with the same validator credentials. Each validator account combination should only be running on a single node at any time. Running duplicate validators will cause consensus conflicts and network instability.

For advanced users or those who want to understand the complete manual process, refer to the Setting Up a Validator Node for an Existing Hyperchain guide, which covers the detailed steps of creating accounts, configuring nodes, and registering with the staking contract.

Regular Maintenance Monitoring

Regular monitoring should include:

1. Chain synchronization status
2. Validator performance metrics
3. Pinning operation success rate
4. Network participation levels

Monitoring Node Status

Check your node's current status and connection to the parent chain:

# For middleware's embedded node
curl http://localhost:3013/v3/status | jq
curl http://localhost:3013/v3/headers/top | jq

# For standalone node (if you deployed one)
curl http://localhost:3014/v3/status | jq
curl http://localhost:3014/v3/headers/top | jq

Monitor block production by checking the latest blocks:

# For middleware's embedded node
curl http://localhost:3013/v3/blocks/top | jq
curl http://localhost:3013/v3/blocks/pending | jq

# For standalone node (if you deployed one)
curl http://localhost:3014/v3/blocks/top | jq
curl http://localhost:3014/v3/blocks/pending | jq

Monitoring Middleware Status

The middleware has its own status endpoint that provides valuable information about synchronization:

curl http://localhost:4000/v3/status | jq

In the middleware status response, pay attention to these critical fields:

• mdw_gens_per_minute - Must be greater than 0 for a healthy system
• mdw_height - Should be close to or the same as node_height
• mdw_synced - Shows if middleware is synced with the node
• mdw_syncing - Should be true during normal operation (false indicates the syncing process has failed)

A properly functioning middleware will show ongoing synchronization activity and generation processing.

Troubleshooting

If you encounter issues with your Hyperchain deployment, review the container logs:

# View middleware logs
docker logs ae_mdw_hc_test

# Follow middleware logs in real-time
docker logs -f ae_mdw_hc_test

# View standalone node logs (if deployed)
docker logs node_only

Common issues to watch for:

1. Parent chain connection failures: Check if your node can connect to the parent chain nodes
2. Pinning failures: Verify that your pinning accounts have sufficient funds on the parent chain
3. Middleware synchronization issues: If middleware shows mdw_syncing: false, restart the container
4. Block production delays: Check validator status and network connectivity

For persistent issues, you may need to restart your containers:

# Restart middleware
docker restart ae_mdw_hc_test

# Restart standalone node (if deployed)
docker restart node_only

Congratulations! Your Hyperchain is now operational. These monitoring tools will help you maintain your network's health and performance over time.