hyperchains
Introduction
This document describes the Aeternity Hyperchain architecture and provides configuration guidance for deploying a Hyperchain node. It includes configuration parameters, setup requirements, and step-by-step deployment instructions.
Hyperchains represent an evolution in blockchain architecture that combines Proof-of-Work (PoW) security with Proof-of-Stake (PoS) efficiency. Through a child chain that periodically synchronizes with a parent PoW chain, Hyperchains enable scalable blockchain networks while maintaining strong security guarantees. This hybrid approach significantly reduces energy consumption compared to traditional PoW systems.
The 0.9 beta release provides developers who are already running Aeternity nodes with the foundation to test and validate Hyperchain functionality. This release focuses on establishing the parent-child chain relationship, implementing chain synchronization, and managing validator operations. This documentation will guide you through the essential configuration parameters and setup requirements needed to participate in the beta testing phase.
Before You Begin
This guide assumes you have:
A running Aeternity node (v6.7.0 or later)
Experience managing blockchain nodes
Access to sufficient funds for pinning operations
Understanding of node validator operations
Important:
Back up your existing node configuration before making any changes
Store all private keys securely
Verify all prerequisites before proceeding
Prerequisites Checklist
Required Infrastructure
Running Aeternity node (v6.7.0 or later)
Minimum 4GB RAM dedicated to Hyperchain operations
100GB available storage space
Stable internet connection with minimum 10Mbps upload/download
Required Technical Knowledge
Experience running and maintaining Aeternity nodes
Basic understanding of blockchain concepts
Familiarity with command-line operations
Understanding of YAML configuration files
Required Accounts and Keys
Access to parent chain (Aeternity) wallet with sufficient funds for pinning
Private key for hyperchain staking operations
Private key for parent chain pinning operations
Setup Process Overview
Time Investment
Initial setup: 2-3 hours
Configuration testing: 1-2 hours
Initial sync time: 2-4 hours (depends on network conditions)
Resource Requirements
Parent chain wallet must maintain minimum balance of X AE for pinning operations
Continuous monitoring during first 24 hours of operation
Regular maintenance windows for updates and optimizations
Implementation Steps
Configure parent chain connection
Set up and configure Hyperchain node
Complete validation period (24-48 hours)
Begin network participation
Configuring Your Own Hyperchain Node
Setting up a Hyperchain requires careful configuration and several specific steps. To simplify this process, Aeternity provides the hyperchain-starter-kit tool, which automates many of the complex configuration tasks. See hyperchain-starter-kit (from Aeternity GitHub org)
Please note that this tool is currently in development. While functional, you may encounter some warnings or minor issues as we continue to improve its stability and user experience
Requirements:
A running Aeternity node installation (following the installation instructions)
Git version control system installed to download the starter kit code
Node.js installed to run the
hyperchain-starter-kitJq installed for JSON formatting
Note: These instructions use Unix/Linux/MacOS shell commands. Windows users will need to adjust paths and commands accordingly.
1. Install the Hyperchains Starter Kit
2. Tool configuration
Our Hyperchain (configuration) will be named hc_test for this example. A directory with the same name will be created in the root directory of the tool where generated files will end up.
This command creates an init.yaml file in the root of your hc_test directory. It contains parameters and settings for your hyperchain. It looks like:
This is the default setup that uses Aeternity testnet as parent chain and appropriate block time and epoch length for it. The configuration can be changed as needs following the rules in the Configuration Details.
3. Set Up Contracts
To prepare the Hyperchain contracts run the following:
This will download the standard contracts from the latest Aeternity release and compile them in contracts sub-directory.
4. Generate the Economy
To generate your Hyperchain "economy" according to init.yaml run the following:
This command will generate random keypairs for all accounts that are needed:
Faucet: can be used to fund other accounts in an automated way
Treasury: the same purpose as Faucet but manual funding
Validators: pre-funded (Stakers) accounts used to initialized the Hyperchain
Pinners: a list of accounts used for pinning
Please note that you have to somehow fund all pinners accounts on the parent chain prior starting your node/validator.
You can inspect the outcome of this in the hc_test/economy-unencrypted.yaml file:
Example output:
5. Generate Configuration Files
To generate all the configuration files needed to run a Hyperchain, run:
This will create 3 files in nodeConfig directory:
aeternity.yamlhc_test_accounts.jsonhc_test_contracts.json
Don't forget to fund all pinners accounts on the parent chain prior starting your node/validator.
IMPORTANT: If you used a known public chain (testnet or mainnet) as parent chain, the tool will set the start_height as current block + 10, that is 30 minutes in future. Keep that in mind when verifying your chain, either decrease the number or wait until that block is produced on the parent chain before you start transacting on the Hyperchain.
6. Run a Node
Docker
To allow inter-container connections between nodes, i.e. adding more nodes to the setup later, a Docker network should be created first:
A container name initiator is also used to allow docker network access to the container later.
Use Docker volumes to install the configuration files and run the node at once:
Verify your node is running with:
Expected output:
For more details refer to dedicated Docker section.
Tarball Installation
Copy all of the above files to their node corresponding directory, i.e. assuming it's in ~/aeternity/node:
then run your node:
Verify your node is running with:
Expected output:
If the output is Node is not running! check node logs for errors to debug it further.
7. Begin Operations
After your Hyperchain node is running and producing blocks, you can begin interacting with the chain. The recommended next steps are:
Connect supporting tools to your chain:
Block explorer (e.g., Aescan)
Wallet interface (e.g., Superhero Wallet or Base app)
Import your test accounts:
Access the account mnemonics from
hc_test/economy-unencrypted.yamlImport these into your preferred wallet (e.g., Superhero Wallet)
Configure your wallet's network settings:
Node address (e.g., localhost)
HTTP API port (default: 3013)
Network ID (
hc_testin this example)
You can now begin testing transactions and interactions with your Hyperchain deployment.
Happy Hyperchaining :)
Configuring New Validator
NOTICE: This documentation covers beta functionality intended for testing purposes only.
After establishing a Hyperchain, you can add additional validators or join an existing Hyperchain as a validator. This guide demonstrates how to configure a new validator on a Hyperchain using the Aeternity blockchain as the parent chain.
Important Notes:
The process requires approximately 2 hours before the new validator begins producing blocks
A minimum stake of 1000000AE is required
Both a staker account (for the child chain) and a pinner account (for the parent chain) are needed
Install Aeternity CLI
The Aeternity Command Line Interface (CLI) is required to manage wallets and interact with smart contracts. Install it using npm:
Account Setup
Two accounts are required for validator operation:
Staker Account: Holds funds for staking in the Hyperchain consensus (child chain)
Pinner Account: Executes pinning transactions on the parent chain
Create a Staker Account
First we need to create a staker account, that's the account that will hold the funds used to stake in the Hyperchain PoS consensus.
Expected output:
Once the account is created, the private key should be extracted as it's needed in the node configuration afterwards:
Expected output:
Note the public and private keys of the account, it will be used below.
Create a Pinner Account
Important: The pinner account must be funded on the parent chain before starting your validator node. For testnet deployment, use the testnet faucet.
If the validator pinning is enabled, a parent chain account will be needed as well to execute it:
Expected output:
Once the account is created, the private key should be extracted as it's needed in the node configuration afterwards:
Expected output:
Note the public and private keys of the account, it will be used below.
Configure the Validator Node
The new validator node needs at least one peer to connect to an existing Hyperchain network. As this example assuming an already running local node, the peer key can be obtained from its status API endpoint:
Expected output:
This example assumes your initiator runs in a docker container from the example above and its address would be initiator (the container name). If the initiator node runs outside docker container, the address will be localhost.
So, the peer URL is: aenode://pp_2ZX5Pae6a9L5UFm8VcCNsB39pn3EK7ZQZpp3dfF1WDNFXZ9p3b@initiator:3015 That will be configured under the peers configuration key below.
The accounts.json and contracts.json will be reused from the previous example, but one can duplicate them as well in new directory as needed.
Copy the node configuration from the previous example:
The validator2.yaml configuration must be changed to remove the initial stakers and pinners and replace it with the new accounts created above and add peers, everything else should stay intact:
Note that account addresses, account keys and peer keys will be different on different runs, make sure to copy the correct ones!
Start the Node
This example assumes you have a Hyperchain validator node (initiator) already running on localhost in a Docker container within a network named hyperchain. Since the node's API ports are exposed to the host, we need to use alternative ports to prevent conflicts. In this example, we will remap port 3013 to 33013 while keeping the default port in the node configuration.
Verify the new validator node is running with:
Expected output:
Make sure that:
genesis_key_block_hashis the same as the status output of the initiator nodenetwork_idis the same as the status output of the initiator nodepeer_countis more than 0top_block_heightis more than 0sync_progressis 100
The above should confirm the new validator is up, running and connected to the initiator Hyperchain network!
Register New Validator
Once the new node is running it's time to register it as validator with the Hyperchain consensus.
CLI Node Config
First the CLI have to be configured to work with the locally running Hyperchain network created in this example:
Verify the configuration by running:
Expected output:
Funding
The staker account must be funded with at least the minimum staking amount (1000000AE in this example) and some extra for transacting. In this example the treasury account can be used by loading it in a wallet
With the help of the CLI the treasury secret key is imported then used to send tokens to the new staker account:
Output:
Verify the treasury balance:
Output:
Fund the staker account from the treasury wallet:
Output:
Validator Registration
The registration happens with a contract call to the staking_contract address, in this example: ct_KJgjAXMtRF68AbT5A2aC9fTk8PA4WFv26cFSY27fXs6FtYQHK.
For a reference (not shell command), the Sophia function signature that needs to be called is:
The same address (ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU) will be used for owner and sign_key, restake will be set to false.
Output:
Now the new validator is registered as part of the consensus! The return value ct_miCfZgeT2fEE9E7XpFikAUReP62QJtZizypJGvw38SYuXJNHN is the validator contact address.
Please note that the new validator will start producing blocks after 4 epochs (2400 blocks), that's after 2 hours in this example!
Configuration Explained
An Aeternity Hyperchain node is built on a standard Aeternity release with specific consensus configuration. After completing the installation and basic configuration, you'll need to add the following Hyperchain-specific configurations to your aeternity.yaml or .json file. Please follow the installation instructions and do basic configuration. Then adopt and add the additional configuration below to your aternity.yaml or (.json).
Parent chain
To configure your parent chain connection, you'll need to specify several key parameters. Start by setting the chain connector to AE2AE and network ID to ae_uat. Next, configure your parent chain node address using the parent node's HTTP API port, not the external port. When setting the fetch interval, ensure it's frequent enough to capture all state changes on the parent chain. Finally, specify a future block height on the parent chain as your starting point. This height determines when your child chain will begin its operations, including block production and pinning. This configuration creates a deliberate delay, allowing for proper initialization and synchronization:
Block times and epochs
The initial "speed" of the Hyperchain is defined by the epoch and block production parameters. These will be different for each Hyperchain, depending on the desired transactional characteristics of the chain. The values below are useful for testing purposes, and when running on Aeternity testnet. Please see the main Hyperchain documentation for more information in how to optimize block and epoch parameters per application and parent chain characteristics.
First a parent chain epoch length should be picked. That should be long enough to statistically easy any block time fluctuations. In this example with Aeternity testnet as parent chain, 10 blocks should be enough.
This version of Hyperchains supports block times as low as 3 seconds for various reasons (i.e. network latency, disk latency, etc.) That can be set as (in milliseconds):
And lastly, but very important is the child epoch length. It is mandatory to have equal parent and child epoch length in wall clock times:
In this example the Aeternity testnet is having 180s block times, so:
Stakers
We define three stakers, that need to have accounts and funds to stake on the Hyperchain. Once a staker becomes leader, their private key is used to sign produced blocks by the node.
Accounts
When starting a Hyperchain it needs some pre-funded accounts as most other chains and types. At least the staker's accounts must be funded so that they can be registered with some initial stake to boot the consensus. In this example there are 3 stakers pre-funded with 3100000000000000000000000000 each so they can be registered at genesis time. Also some additional accounts like Faucet (ak_WNkJkmaEoyScVRaeZeDvvmCqLn1HkfNnQDy1oSJp6Jm5YPpAq) and Treasury (ak_CLTKb9tdvXGwpgUBW8GytW7kXv9r1eJyY4YtgKKWtKcY3poQf) are also funded for easing the chain usage.
Contracts
Hyperchains operate through FATE contracts which must be compiled and provided to the node. These contracts require initialization during the first (genesis) block of the Hyperchain, which involves specific contract calls. While this configuration can be manually set in contracts.json, the process is technically complex. We recommend using our purpose-built CLI tools to handle contract deployment and initialization.
In this example two contracts are deployed: MainStaking.aes and HCElection.aes then there are three contract calls to register the stakers/validators, 3 in this example.
Please refer to the hyperchain-starter-kit documentation above how to generate the files.
Once the contracts are generated they have to be also added in the node consensus configuration. Current configuration expect 3 separate contracts:
However, the current implementation is using the staking contract instance for rewards distribution, thus the addresses are the same.
Finally the contract owner should be set the same as the owner of the contract deployment in the contracts.json:
This ensures that the protocol methods can be called only by the protocol and not other accounts. In this example the so called "zero" address is used for that.
Pinning
Currently only a single pinning behavior is supported. Validators will automatically pin the Hyperchain state to the parent chain when they are leaders of the last block of the epoch using their mapped parent account credentials. It can be enabled by:
That feature also needs pinning accounts configuration, it's map of staker to pinning account, for example:
To encourage validators to pin epoch states to the parent chain, the system provides rewards in the Hyperchain's native currency. The reward amount for each successful pinning operation can be configured to align with your Hyperchain's economic model. This value represents the compensation validators receive for performing verifiable pinning operations for each epoch.
Complete configuration example
Addendum 1: Hyperchain-specific confguration reference
chain.consensus: object
The consensus algorithms used for validating blocks. Ignored if 'fork_management > network_id' has value 'ae_mainnet' or 'ae_uat'.
Properties (Pattern)
consensus algorithm gets activated. By default from genesis Cuckoo cycle based BitcoinNG is used.
yes
chain.consensus.<height>: object
Configuration parameters for the selected consensus algorithm (Hyperchain).
Properties
type
string
The type of the consensus algorithm used at the given height (ex. pow_cuckoo, smart_contract
or hyperchain)
Default: "hyperchain"
yes
Example
chain.consensus.<height>.config: object
Configuration for the given consensus algorithm
Properties
contract_owner
string
Owner of the smart contracts that controls the consensus.
election_contract
string
The address of the smart contract that will be used for leader elections. For a new chain this contract should be loaded at genesis
rewards_contract
string
The address of the smart contract that will be used for reward distributions. For a new chain this contract should be loaded at genesis
genesis_start_time
integer
Timestamp for genesis
Default: 0
child_block_time
integer
The average time in milliseconds between two key blocks on the hyperchain
Default: 3000
child_block_production_time
integer
The time in milliseconds to produce a hyperchain block
child_epoch_length
integer
The number of blocks in an epoch on the hyperchain
pinning_reward_value
integer
The initial value of the Pinning reward. It can later be changed through consensus
Default: 0
default_pinning_behavior
boolean
Use the default pinning behavior, where in each epoch, if the last leader has defined pinning/parent chain credentials, they will pin
Default: false
fixed_coinbase
integer
The coinbase reward specifies the fixed amount of newly minted tokens allocated to block producers as an incentive for validating and adding blocks to the chain.
Default: 0
Example
chain.consensus.<height>.config.parent_chain: object
Details of how this node will connect to a parent chain if this is a hyperchain.
Properties
start_height
integer
Height on the parent chain that this hyperchain will start posting commitments and start creating blocks
Default: 0
finality
integer
The number of blocks on the parent chain to reach finality.
parent_epoch_length
integer
The number of blocks in an epoch on the parent chain.
acceptable_sync_offset
integer
The maximum amount of time the parent chain block generation can be off the expected time.
Default: 60000
Additional Properties: not allowed Example
chain.consensus.<height>.config.parent_chain.consensus: object
Details of the parent chain.
Properties
network_id
string
The network Id of the parent chain if it has one
Default: "ae_mainnet"
type
string
The type of parent network connection. Currently only AE, Bitcoin and Dogecoin are implemented
Default: "AE2AE"
Enum: "AE2AE", "AE2BTC", "AE2DOGE"
Additional Properties: not allowed Example
chain.consensus.<height>.config.parent_chain.polling: object
Parent chain connection configuration
Properties
fetch_interval
integer
The interval between polls of the parent chain looking for a new block (milliseconds)
Default: 500
retry_interval
integer
The amount of time in milliseconds to wait before retrying a check for a block on the parent chain.
Default: 1000
cache_size
integer
Size of local cache for parent chain
Default: 200
Additional Properties: not allowed Example
chain.consensus.<height>.config.parent_chain.polling.nodes[]: array
List of parent chain nodes to poll for new blocks
Items
URL address of the API - ://:@:
Item Type: string
chain.consensus.<height>.config.stakers[]: array
List of hyperchain accounts
Items
Hyperchain account pair
Item Properties
Item Additional Properties: not allowed Example
chain.consensus.<height>.config.stakers[].hyper_chain_account: object
Hyper chain validator/staking account(s)
Properties
pub
string
Public key
Default: ""
priv
string
Private key
Default: ""
Additional Properties: not allowed Example
chain.consensus.<height>.config.pinners[]: array
List of parent chain accounts. Relevant only to Aeternity parent chains. For BTC and Doge, each node relies on a local wallet setup with accounts and funds.
Items
Hyperchain parent accounts.
Item Properties
Item Additional Properties: not allowed Example
chain.consensus.<height>.config.pinners[].parent_chain_account: object
Parent chain account for executing pinning (spend) transactions
Properties
pub
string
Public key
Default: ""
priv
string
Private key
Default: ""
owner
string
Public key of Hyperchain account owner. Needs to correspond to an account defined in stakers
Default: ""
Additional Properties: not allowed Example
Last updated