The goal of this project is to ease the process of bootstrapping an Aeternity hyperchain.
Table of Contents
The Hyperchains Starter Kit simplifies the process of bootstrapping an Aeternity Hyperchain node for the 0.9 beta release. While Hyperchains are designed to be lightweight and resource-efficient, the setup process involves multiple components and careful configuration. This tool automates key setup tasks including economy generation, and contract and node configuration.
Note: This tool is currently in beta development alongside Hyperchains 0.9. While functional, you may encounter warnings or minor issues as we continue improving stability and user experience.
The toolkit provides automated workflows for:
- Generating Hyperchain economy configuration parameters (initial accounts and balances)
- Preparing contract configurations for genesis block deployment
- Creating validator account configurations
- Preparing pinning operation parameters
Each component generates configuration output that the Aeternity node will use during initialization and genesis block creation.
-
Clone and install the starter kit:
git clone https://github.com/aeternity/hyperchain-starter-kit cd hyperchain-starter-kit npm install npm run dev -
Initialize your Hyperchain configuration:
npm run dev init your_chain_name
-
Set up contracts:
npm run dev retrieve-contracts your_chain_name
-
Generate the economy:
npm run dev gen-economy your_chain_name
-
Generate node configuration:
npm run dev gen-node-conf your_chain_name
See the Aeternity Node Documentation for detailed setup instructions.
Important Notes:
- Back up all generated keys and configuration files
- Fund all pinner accounts on the parent chain before starting your node
- When using a public parent chain, the start height is set to current block + 10
The tool generates a default configuration in init.yaml:
childBlockTime: 3000
childEpochLength: 600
enablePinning: true
networkId: 'hc_test'
parentChain:
epochLength: 10
networkId: 'ae_uat'
nodeURL: 'https://testnet.aeternity.io'
type: 'AE2AE'
pinningReward: 1000000000000000000000
validators:
count: 3
validatorMinStake: 1000000000000000000000000This configuration can be customized based on your requirements. See the Hyperchains documentation) for more detailed parameter explanations.
While this starter kit aims to simplify Hyperchain deployment, it is not:
- A comprehensive tutorial on blockchain concepts
- A complete guide to Aeternity node operation
- A production-ready deployment solution
- A replacement for understanding basic blockchain operations
For learning these concepts, we recommend:
- Aeternity Documentation for blockchain fundamentals
- Hyperchains Whitepaper for deep technical understanding
- Aeternity Forum for community learning resources
For using this tool:
For using the generated output:
- An Aeternity node (v6.7.0 or later) install location where you will place the generated configurations
- Minimum 4GB RAM dedicated to Hyperchain operations
- 100GB available storage space
- Stable internet connection (minimum 10Mbps upload/download)
- Hyperchain: A blockchain that runs on æternity software. It is a separate blockchain with its own economy distinct from the main æternity blockchains. The tokens in this network are not AE tokens, and the operator can decide how to name them.
- Hyperchain node: The instance of the æternity software running the hyperchain with special configuration. While you can start with a single node, a production network should have multiple nodes for decentralization and resilience.
- Parent chain and Parent chain node: Can be the main æternity blockchain, Bitcoin, or Dogecoin. This is the network where our hyperchain posts commitments for security purposes, preventing retroactive history changes.
- Child Chain: Another term for Hyperchain, emphasizing its relationship with the parent chain.
- Commitment: A hash of the current top block that is posted to the parent chain as proof of the hyperchain's state.
- Pinning: The process of anchoring the hyperchain's state to the parent chain by posting cryptographic commitments. This creates an immutable record of the hyperchain's history and prevents long-range attacks.
- Validator: An account on our hyperchain authorized to sign blocks according to consensus rules. A node can operate multiple validators if it has their private keys.
- Pinner: A validator responsible for executing pinning operations to anchor the Hyperchain state to the parent chain.
- Staker or Delegator: An account that stakes tokens with a validator to increase their voting power. Validators typically share block rewards with their stakers.
- Genesis block: The first block of the blockchain, containing initial accounts and token balances.
- Faucet: An account and faucet service that distributes tokens to users, typically for free on testnets. Example: æternity testnet faucet.
- Staking UI: A web application that allows users to stake their tokens with validators and manage their staking positions.
- Wallet: A web application for managing accounts, tokens, and transactions on the hyperchain network. Popular options include Superhero and Base æpp.
- Explorer: A web application for viewing blockchain state and transactions. Example: æScan.
- Middleware or MDW: An indexing service that enables wallets to retrieve transaction history and serves as the backend for Explorers and some wallet features.
Common issues you might encounter:
- Node Not Starting
- Verify all configuration files are in correct locations
- Check node logs for specific errors
- Ensure parent chain connection is configured correctly
- Pinning Issues
- Confirm pinner accounts are funded on parent chain
- Verify pinning configuration is enabled
- Check parent chain connection status
- Validator Setup
- Ensure validator keys are properly configured
- Verify minimum stake requirements are met
- Check staking contract deployment status
For additional support, please open an issue or join the Aeternity Forum.