Setting Up a Validator Node

NOTICE: This documentation covers beta functionality intended for testing purposes only.

Introduction

After establishing a Hyperchain, you need to add validators to maintain the network, produce blocks, perform pinning operations, and increase security on your chain. This guide demonstrates the complete process of configuring and registering a new validator on your existing Hyperchain.

Prerequisites

Before beginning, ensure:

• You have your own or access to a running Hyperchain network
• Middleware has been installed on this Hyperchain (if it is your hyperchain and you haven't done that yet, find installation instructions in the Hyperchains Initiator Web App How-to Guide or the middleware documentation
• You understand that new validators require approximately 2 hours before they begin producing blocks
• Make sure you have the accounts.json and contracts.json files, which were either generated when you initiated your own Hyperchain or obtained from the initiator/owner of the Hyperchain you are joining (these files are not provided by the web app)
• You have access to the minimum staking requirements, which you must verify with the Hyperchain's owner if it's not yours
• You're prepared to create and manage two separate accounts (for staking on the hyperchain and for pinning to the pinning/parent chain)

Using the Hyperchain Web App

Before setting up your validator node, you'll need to use the Hyperchain web application to gather necessary information and generate configuration files.

Step 1: Connect to Your Hyperchain

1. Open the Hyperchain Validator Set Up App in your browser

2. On the first screen "Tell us about the hyperchain", you'll need to enter three URLs:

   • Node URL: The API endpoint of a node in the Hyperchain network for syncing and block updates. Usually at port 3013 (e.g.,
     https://demo.hyperchains.aeternity.io/ if using the public demo Hyperchain)
   • Node AE-Chatter URL (WebSocket): The URL to the Aeternity node of the Hyperchain network used for the ae protocol. Usually at port 3015 (e.g., mainnet.aeternity.io:3014)
   • Middleware URL: The URL to the Middleware of the Hyperchain network (e.g., https://demo.hyperchains.aeternity.io:8443/)

Notes for users:

If you're connecting to an existing Hyperchain network, use the node and middleware URLs provided by the network administrator For validators, you'll need to ensure your node is properly configured to participate in the Hyperchain The example URLs above are for demonstration purposes; replace them with the actual endpoints for your target Hyperchain network

1. Finding These URLs:

   • For your own Hyperchain, these would be the URLs configured during initialization
   • If joining someone else's Hyperchain, request these URLs from the Hyperchain operator
   • For a local Hyperchain, the default URLs would typically be:
     • Node URL: http://localhost:3013/
     • Node AE-Chatter URL: localhost:3015
     • Middleware URL: http://localhost:4000/

2. Click "Next" after entering the URLs.

Step 2: Verify Requirements

On the "Check the Requirements" screen, you'll need to confirm that you meet all the necessary prerequisites:

• Sufficient tokens: Ensure you have more than the required amount of tokens on the Hyperchain to become a validator
• Parent chain account: Verify you have an account with funds on the æternity chain (usually ae_uat for testnet)
• Parent chain access: Confirm you have access to a node of the æternity chain
• Configuration files: Make sure you have the accounts and contracts JSON files for the Hyperchain

Once you've confirmed all requirements by checking the boxes, click "Next" to proceed.

The web application will then generate the necessary validator configuration file that you'll need to download and modify in the later steps of this guide.

Important Decision: Staking Validator vs. Delegated Staking Validator

Before proceeding, you must decide whether this validator will be:

• Staking Validator: Using only your own funds for staking
• Delegated Staking Validator: Accepting stake from other users (including yourself)

This decision is permanent. Once a validator is set up as one type, it cannot be converted to the other type. If you later want to change your validator type, you will need to set up a completely new validator. The steps to set up both kinds of validators are the same until Step 5. After that, you can choose PATH A for a Staking Validator or PATH B for a Delegated Staking Validator.

A validator can only be one type, not both. Once a validator is set up as a staking validator, it cannot be reconfigured to accept delegated stake. If you wish to have a validator that accepts delegated stake in the future, you will need to set up a new, separate validator. You can choose to either keep the existing staking validator running or abandon it.

Key Differences:

Choose carefully based on your long-term plans for this validator.

Step 1: Install aeternity CLI

The aeternity Command Line Interface (CLI) is essential for managing wallets and interacting with smart contracts.

npm install --global @aeternity/aepp-cli@7
aecli --version

You should see a version output confirming successful installation.

Step 2: Create Required Accounts

A validator requires two distinct accounts:

• Staker Account: Holds funds for staking in the Hyperchain consensus. The staker account will use the native tokens of the Hyperchain (the token name will depend on what the Hyperchain creator named it).
• Pinner Account: Executes pinning transactions on the parent chain. The pinner account must be funded with AE tokens on the parent chain for pinning operations.

2.1: Create a Staker Account

aecli account create hc_test/wallets/staker.json

You'll be prompted to enter a password to encrypt this account. Remember this password as you'll need it later.

Expected output:

✔ Enter your password ...
Address  ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU
Path     /path/to/hyperchain-starter-kit/configs/hc_test/wallets/staker.json

This creates an encrypted wallet file containing your staker account. The address shown (starting with ak_) is your public key.

2.2: Extract the Staker Private Key

You'll need the private key for your node configuration:

aecli account address --secretKey hc_test/wallets/staker.json

Expected output:

✔ Are you sure you want print your secret key? ... yes
✔ Enter your password ...
Address            ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU
Secret Key         sk_2KaWrN7mJ5yfj5yikQwepSaPXksgjuYda7QoXtjfVhRfFVDJvs
Secret Key in hex  ade11d353b3b02f9602aa7073683a1c2b2a5d95c73b99d8fc40eafa82b02e957df8a07444f1195795a2f92915e655696a3a6a330015c58673ae9f73a1abff374

IMPORTANT: Make note of the hex version of the Secret Key. You'll need this for the node configuration later. Handle this key securely - anyone with this key could control your staked funds.

2.3: Create a Pinner Account

The pinner account will execute transactions on the pinning/parent chain (current version of Hypercahins uses æternity as parent/pinning chain):

aecli account create hc_test/wallets/pinner.json

You'll again be prompted for a password.

Expected output:

✔ Enter your password ...
Address  ak_2CQQctWm267tfHMUcZf7YX5uVHE6T9t3bg4UNpWnpn8qog6MZ
Path     /path/to/hyperchain-starter-kit/configs/hc_test/wallets/pinner.json

2.4: Extract the Pinner Private Key

aecli account address --secretKey hc_test/wallets/pinner.json

Expected output:

✔ Are you sure you want print your secret key? ... yes
✔ Enter your password ...
Address            ak_2CQQctWm267tfHMUcZf7YX5uVHE6T9t3bg4UNpWnpn8qog6MZ
Secret Key         sk_X8YAj8XRzTEsAdQJZDt6n3baCcCs2mHRwiT4rtBYEE8baBLfX
Secret Key in hex  4469eb651fa54025ccecf2bfe462a2051e690f7b2bb23ea0f49e6f77a7b1763c02b7910b1a543221b15f14b196ed1ba3212031d817a9c09ac200387ab5631a25

IMPORTANT:

• The pinner account must be funded on the parent chain before starting your validator node
• For testnet deployment, use the testnet faucet to obtain funds
• Make note of the hex version of the Secret Key for later configuration

Step 3: Configure the Validator Node

The web app will generate a validator configuration file for you, typically named validator2.yaml. Please download this file. Once downloaded, you will need to modify the validator2.yaml file to configure your validator with your specific account details and contract addresses.

Important: It is essential that the accounts.json and contracts.json files (which were generated during the Hyperchain initiation flow) are copied to the same folder where you save the validator2.yaml file. This ensures that the node can locate these files during startup.

CRITICAL WARNING: Never run multiple nodes with the same validator credentials (the same staker and pinner account combination). Each validator should only be active on a single node at any time. If you need to move your validator to a new server, ensure you shut down the old node completely before starting the new one. Running duplicate validators with the same keys on multiple nodes will cause consensus conflicts and network instability.

If you need multiple nodes for redundancy, configure additional nodes without validator credentials as read-only participants that don't produce blocks or perform pinning operations.

peers:
  # Connect to existing Hyperchain network
  - aenode://pp_2ZX5Pae6a9L5UFm8VcCNsB39pn3EK7ZQZpp3dfF1WDNFXZ9p3b@ae_mdw_hc_test:3015

chain:
  consensus:
    '0':  
      config:    
        child_block_time: 3000
        child_block_production_time: 500    # Add this line
        child_epoch_length: 600    
        contract_owner: 'ak_11111111111111111111111111111115rHyByZ'    
        default_pinning_behavior: true    
        election_contract: 'ct_LRbi65kmLtE7YMkG6mvG5TxAXTsPJDZjAtsPuaXtRyPA7gnfJ'    
        fixed_coinbase: 100000000000000000000
        parent_chain:      
          consensus:        
            network_id: 'ae_uat'        
            type: 'AE2AE'      
          parent_epoch_length: 10      
          polling:        
            fetch_interval: 500      
            nodes:        
              - 'https://testnet.aeternity.io'      
          start_height: 1064939  
        pinners:    
          - parent_chain_account:        
              owner: 'ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU'        
              priv: '4469eb651fa54025ccecf2bfe462a2051e690f7b2bb23ea0f49e6f77a7b1763c02b7910b1a543221b15f14b196ed1ba3212031d817a9c09ac200387ab5631a25'        
              pub: 'ak_2CQQctWm267tfHMUcZf7YX5uVHE6T9t3bg4UNpWnpn8qog6MZ'        
        pinning_reward_value: 1000000000000000000000        
        rewards_contract: 'ct_KJgjAXMtRF68AbT5A2aC9fTk8PA4WFv26cFSY27fXs6FtYQHK'  
        stakers:    
          - hyper_chain_account:        
              priv: 'ade11d353b3b02f9602aa7073683a1c2b2a5d95c73b99d8fc40eafa82b02e957df8a07444f1195795a2f92915e655696a3a6a330015c58673ae9f73a1abff374'        
              pub: 'ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU'        
        staking_contract: 'ct_KJgjAXMtRF68AbT5A2aC9fTk8PA4WFv26cFSY27fXs6FtYQHK'  
      type: 'hyperchain'

  hard_forks:
    '6':  
      accounts_file: 'hc_test_accounts.json'  
      contracts_file: 'hc_test_contracts.json'  
      height: 0

fork_management:
  network_id: 'hc_test'

mining:
  autostart: true

http:
  endpoints:
    dry-run: true
    hyperchain: true

Key Configuration Details and Required Modifications:

You must replace the placeholder values in the pinners and stakers sections with your own account information:

pinners Section: Configures your pinner account.

• owner: Replace 'ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU' with your staker account's public key (the ak_... address).
• priv: Replace '4469eb651fa54025ccecf2bfe462a2051e690f7b2bb23ea0f49e6f77a7b1763c02b7910b1a543221b15f14b196ed1ba3212031d817a9c09ac200387ab5631a25' with your pinner account's private key in hexadecimal format (the sk_... key converted to hex).
• pub: Replace 'ak_2CQQctWm267tfHMUcZf7YX5uVHE6T9t3bg4UNpWnpn8qog6MZ' with your pinner account's public key (the ak_... address).

stakers Section: Configures your staker account.

• priv: Replace 'ade11d353b3b02f9602aa7073683a1c2b2a5d95c73b99d8fc40eafa82b02e957df8a07444f1195795a2f92915e655696a3a6a330015c58673ae9f73a1abff374' with your staker account's private key in hexadecimal format.
• pub: Replace 'ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU' with your staker account's public key.

contract addresses: Ensure that the election_contract, rewards_contract, and staking_contract addresses (ct_... values) match the contract addresses from your initiator node. These addresses are crucial for your validator to interact correctly with the Hyperchain.

child block production time If using Aeternity node version v7.3.0-rc5 or later, you must include the child_block_production_time parameter (as shown in the configuration example). This parameter controls how much time the node allocates for creating a block and is typically set to a value like 500 (milliseconds).

Important Notes:

• Private Keys: Handle your private keys (priv) with extreme care. Do not share them with anyone.
• Hex Format: The private keys must be in hexadecimal format. You will obtain this format when extracting the private keys using the aeternity CLI (as shown in Step 2).
• Contract Addresses: Verify the contract addresses against those used by your initiator node to ensure compatibility and proper functioning.

By replacing the placeholder values with your actual account information and confirming the contract addresses, you will correctly configure your validator node.

Token Requirements:

• Make sure your pinner account (the account in the parent_chain_account section) has sufficient AE tokens on the parent chain to perform pinning operations
• Your staker account will need the Hyperchain's native tokens for staking and transaction fees

Step 4: Start the Validator Node

This example assumes you're using Docker as in the earlier setup. Before running the following command, ensure you are in the directory that contains the hc_test folder. The ${PWD} in the command represents your current working directory. The hyperchain Docker network must already be created (usually done during the initial Hyperchain setup).

docker run --rm -it -p 33013:3013 \
    --network hyperchain \
    -v ${PWD}/hc_test/nodeConfig/validator2.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

Explanation:

• -p 33013:3013: Maps port 33013 on your host machine to port 3013 inside the Docker container. We use 33013 for the API to avoid conflicts with the initiator node running on port 3013.
• --network hyperchain: Connects the container to the existing hyperchain Docker network.
• -v ...: Mounts the configuration files from your local machine into the Docker container.
• aeternity/aeternity:v7.3.0-rc5: Specifies the aeternity node Docker image to use. Docker will automatically download this image if it's not already present.

To run the node in the background, you can add the -d flag to the docker run command.

To view the node's logs, use docker logs <container_id> (you can find the container ID using docker container ls).

4.1: Verify the Node is Running

After starting the validator node with the Docker command in Step 4, it's crucial to verify that it's running correctly and connected to the Hyperchain network. You can do this by querying the node's status endpoint.

1. Open a Terminal: Open a new terminal window or tab on your computer.
2. Run the curl Command: Execute the following command in your terminal:

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

Expected output:

{
  "difficulty": 0,
  "genesis_key_block_hash": "kh_7dm2zSo6NsnEDMYBYdXA9QvkJvvk7TenT68HxW5BSrRSz3WV6",
  "hashrate": 0,
  "listening": true,
  "network_id": "hc_test",
  "node_revision": "57bc00b760dbb3ccd10be51f447e33cb3a2f56e3",
  "node_version": "7.3.0-rc5",
  "peer_connections": {
    "inbound": 0,
    "outbound": 1
  },
  "peer_count": 1,
  "peer_pubkey": "pp_ENJfMAPXWbZruYgexnGCNEwCBwdLcEiR8F541CuzCkgtFQ5jt",
  "pending_transactions_count": 0,
  "protocols": [
    {
      "effective_at_height": 0,
      "version": 6
    }
  ],
  "solutions": 0,
  "sync_progress": 100,
  "syncing": false,
  "top_block_height": 35
}

Verify that:

• genesis_key_block_hash matches the initiator node
• network_id matches the initiator node
• peer_count is at least 1 (confirming connection to the network)
• top_block_height is greater than 0 (confirming block sync)
• sync_progress is 100% (confirming full synchronization)

Step 5: Register the Validator with the Hyperchain

Next you need to register it as an active validator within the Hyperchain consensus. This process differs depending on whether you're setting up a staking validator or a delegated staking validator.

5.1: Configure CLI to Connect to Hyperchain

First, you need to tell the aeternity CLI which node to connect to. In this case, it's your initiator node.

aecli select-node http://localhost:3013/

Explanation:

• aecli select-node: This command instructs the aeternity CLI to set the target node.
• http://localhost:3013/: This is the URL of your initiator node. Remember, 3013 is the default port for the initiator node's API.

Verify the configuration: Confirm that the CLI is configured correctly:

aecli config

Expected output:

Node http://localhost:3013/ network id hc_test, version 7.3.0-rc5, protocol 6 (Ceres)
Compiler https://v8.compiler.aepps.com/ version 8.0.0

Verification Checks:

• Node http://localhost:3013/: Ensure this matches the URL of your initiator node.
• network id hc_test: Verify that the network ID is correct for your Hyperchain.
• version 7.3.0-rc5: Check that the node version matches the one you're using.

Path A: Setting Up a Staking Validator

Follow these steps if you choose to create a validator that uses only your own funds for staking.

5.2A: Fund the Staker Account

Your staker account needs at least the minimum staking amount of the Hyperchain's native token required by the Hyperchain plus additional tokens for transaction fees. For this example, we will create a new treasury account to fund your staker account. We'll send 1,000,100 of the Hyperchain's native tokens, with 1,000,000 being the staking amount and 100 for potential fees. Adjust these amounts based on your Hyperchain's specific requirements and token denomination.

(Note: This step demonstrates how to create a treasury account. If you already have the treasury account created, skip to the "Send funds to your staker account" command which follows.)

If you need to create the treasury account: To set up a Treasury account, run this command:

aecli account create hc_test/wallets/treasury.js 9ab3bb473a0ec30d4f75f877ee9de0145fbd883e07edab2e4555e156a729be5619bd0a236a9ebd4a47e5fc3961b59ea215515109c007e2ce844b1f543d4e9598

Expected output:

✔ Enter your password ...
Address  ak_CLTKb9tdvXGwpgUBW8GytW7kXv9r1eJyY4YtgKKWtKcY3poQf
Path     /path/to/hyperchain-starter-kit/configs/hc_test/wallets/treasury.js

Explanation:

• aecli account create: Creates a new account.
• hc_test/wallets/treasury.js: Specifies the file path where the account's wallet will be stored.
• 9ab3bb473a0ec30d4f75f877ee9de0145fbd883e07edab2e4555e156a729be5619bd0a236a9ebd4a47e5fc3961b59ea215515109c007e2ce844b1f543d4e9598: This is the pre-generated private key of the treasury account for this example. In a real-world scenario, you should generate your own secure private key.

Verify the treasury balance: Check that the treasury account has the expected balance:

aecli inspect ak_CLTKb9tdvXGwpgUBW8GytW7kXv9r1eJyY4YtgKKWtKcY3poQf

Expected output:

Account ID       ak_CLTKb9tdvXGwpgUBW8GytW7kXv9r1eJyY4YtgKKWtKcY3poQf
Account balance  1000000000000000000000000000000ae
Account nonce    0
No pending transactions

Send funds to your staker account: Now, transfer 1,000,100 AE from the treasury account to your staker account:

aecli spend hc_test/wallets/treasury.js ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU 1000100ae

Explanation:

• aecli spend: Initiates a transfer of AE tokens.
• hc_test/wallets/treasury.js: Specifies the wallet file of the sender (treasury account).
• ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU: The address of the recipient (your staker account).
• 1000100ae: The amount to send (1,000,100 AE).

Expected output:

Cost of SpendTx execution ≈ 1000100.0000169ae
✔ Enter your password ...
Transaction mined
Transaction hash   th_2JLcgQkpD4Rz42L3rmKsLoZ2fomGuoVNpoJjnAMxTcbmoznjbb
Block hash         mh_2uWKDfDj5evXncvJd6V7c76pQdhYuKWDUjxP2jqr5cj7BW9b99
Block height       2052 (about now)
Signatures         ["sg_BYKqfbZej3CPUHz9sJfHRM5o8YLevTjhoU3JAHivU8d8wv9L8TuA2kx74vm5xTHSmFQxo2d4uDBJKWuz9K5QmTDCUNDLc"]
Transaction type   SpendTx (ver. 1)
Sender address     ak_CLTKb9tdvXGwpgUBW8GytW7kXv9r1eJyY4YtgKKWtKcY3poQf
Recipient address  ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU
Amount             1000100ae
Payload            ba_Xfbg4g==
Fee                0.0000169ae
Nonce              1
TTL                2053 (about now)

The output confirms your staker account now has 1,000,100 AE, which includes the minimum staking amount (1,000,000 AE) plus extra for transaction fees.

5.3A: Register the Staking Validator with the Staking Contract

The final step in activating your staking validator is to register it with the Hyperchain's staking contract.

Understanding the Function Signature: The staking contract has a function called new_validator that we need to call. Its Sophia function signature looks like this:

payable stateful entrypoint new_validator(owner : address, sign_key : address, restake : bool) : StakingValidator

Explanation of the Parameters:

• payable: Indicates this function call can include sending AE tokens.
• stateful: Means this function can modify the contract's state.
• entrypoint: Identifies this as a function that can be called from outside the contract.
• new_validator(owner : address, sign_key : address, restake : bool): The function name and its parameters:
  • owner : address: The address of the account that owns the staked funds (your staker account).
  • sign_key : address: The address used to sign blocks (also your staker account in this case).
  • restake : bool: A boolean value indicating whether rewards should be automatically restaked.
• : StakingValidator: The return type of the function.

Executing the Contract Call: Now, execute the contract call using the following aecli command. Replace the placeholder contract address and your staker address with your actual values:

aecli contract call new_validator '["ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU", "ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU", false]' hc_test/wallets/staker.json --contractAddress ct_KJgjAXMtRF68AbT5A2aC9fTk8PA4WFv26cFSY27fXs6FtYQHK --contractAci hc_test/contracts/MainStaking.aci.json --amount 1000000ae

Expected output:

Cost of ContractCallTx execution ≈ 1000000.000236691ae
✔ Enter your password ...
Transaction hash  th_4VXdLJjpAXAnGMe7RRfwKtPguXGWJaLVLoKR7EgcVe1w2MGtk
Block hash        mh_2XhasD3FXo4RSyKdrkUMw8NQdDx2bkXKhZJfV1idwXjUeFHPEk
Block height      2512 (about now)
Signatures        ["sg_R5STDGXkZyCejyiyahzJJLGN8GThrZsCH3hY6e7GkLb8eebz8sHbj8ECe21tscXw2Eh2zDvaryyuy9fnCvNX8wewciXER"]
Transaction type  ContractCallTx (ver. 1)
Caller address    ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU
Contract address  ct_KJgjAXMtRF68AbT5A2aC9fTk8PA4WFv26cFSY27fXs6FtYQHK
Gas               53031 (0.000053031ae)
Gas price         0.000000001ae
Call data         cb_KxFuGm1JO58AoN+KB0RPEZV5Wi+SkV5lVpajpqMwAVxYZzrp9zoav/N0nwCg34oHRE8RlXlaL5KRXmVWlqOmozABXFhnOun3Ohq/83R/GCn/XQ==
ABI version       3 (Fate)
Amount            1000000ae
Fee               0.00018366ae
Nonce             1
TTL               2514 (in 6 minutes)
----------------------Call info-----------------------
Gas used                42425 (0.000042425ae)
Return value (encoded)  cb_nwKgZYU1vdfnMJUPDrJIhcZ5xLhgivcS2Y7lZhl77npIApLx8dm1
Return value (decoded)  ct_miCfZgeT2fEE9E7XpFikAUReP62QJtZizypJGvw38SYuXJNHN

Verifying the Registration: The return value (in this example ct_miCfZgeT2fEE9E7XpFikAUReP62QJtZizypJGvw38SYuXJNHN) is your validator contract address. This confirms your validator has been successfully registered with the Hyperchain consensus. Note this address for your records.

You can now proceed to Step 6.

Path B: Setting Up a Delegated Staking Validator

Follow these steps if you choose to create a validator that can accept stake from other users (delegated staking).

5.2B: Fund Your Staker Account

Unlike a standard staking validator that requires the full stake amount upfront, a delegated staking validator primarily receives its stake from delegators. However, you still need:

• Enough of the Hyperchain's native tokens to cover transaction fees for contract deployment and registration
• Initial stake in the Hyperchain's native token to bootstrap your validator (can be much smaller than the full validator stake requirement)
• Ensure your pinner account has sufficient AE tokens on the parent chain for pinning operations

Ensure your staker account has at least the minimum amount required for delegation (which could be the same as the validator_min_stake) plus extra for transaction fees. You can send these funds from the treasury account or any other account with sufficient balance.

aecli spend hc_test/wallets/treasury.js ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU 1000100ae

Verify your staker account's balance to ensure the funds were received:

aecli inspect ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU

5.3B: Deploy the DelegatedStaking Contract

Unlike standard staking validators, delegated staking validators require deploying a separate contract that will manage delegated stakes. This contract will interact with the main staking contract while providing additional functionality for delegators.

5.3B.1: Download the DelegatedStaking Contract

First, download the DelegatedStaking contract from the official aeternity repository:

curl -o DelegatedStaking.aes https://raw.githubusercontent.com/aeternity/aeternity/v7.3.0-rc3/test/contracts/DelegatedStaking.aes

IMPORTANT: The DelegatedStaking contract has undergone comprehensive functional testing to verify its core operations, including delegation, reward distribution, and withdrawal mechanisms. However, as this represents a newer feature in the Hyperchain ecosystem, deploying delegated staking in production environments should be approached with appropriate caution and monitoring.

5.3B.2: Configure Deployment Parameters

Before deploying, you need to decide on several key parameters:

Important Notes:

1. Address Formatting: All addresses must be properly formatted (ak_ for account addresses, ct_ for contract addresses)

2. Token Amounts: All token amounts should be expressed in aettos (the smallest unit, similar to wei in Ethereum). For example, 1,000,000 tokens would be expressed as 1000000000000000000000000

3. Parameter Order: The order of parameters matters and must match exactly as shown

4. Minimum Values: Setting values below contract minimums will cause the deployment to fail

5. Finding Parameter Values:

   • For contract addresses, check your validator2.yaml configuration file
   • For token amounts, consult with the Hyperchain initiator for the minimum requirements

5.3B.3: Deploy the Contract

Deploy the DelegatedStaking contract with your chosen parameters:

aecli contract deploy \ 
--contractSource DelegatedStaking.aes \ 
--amount <YOUR_INITIAL_STAKE_AMOUNT> \ 
hc_test/wallets/staker.json \ 
'["<YOUR_VALIDATOR_ADDRESS>", "<MAIN_STAKING_CONTRACT_ADDRESS>", "<MIN_DELEGATION_AMOUNT>", <MAX_DELEGATORS>, <MIN_DELEGATION_DURATION>, <MAX_WITHDRAWAL_QUEUE_LENGTH>]'

This contract deployment includes your initial stake, so ensure your staker account has sufficient funds for both the transaction fee and the stake amount.

Replace the placeholders with your specific values:

# Example with sample values (replace with your actual values):
aecli contract deploy \
    --contractSource DelegatedStaking.aes \
    --amount 1000000000000000000000000 \
    hc_test/wallets/staker.json \
    '["ak_2hT1UTevtPkEpocjEcbbBi14gS1Ba1unHQBrtXupHnKHxk26kU", "ct_KJgjAXMtRF68AbT5A2aC9fTk8PA4WFv26cFSY27fXs6FtYQHK", "1000000000000000000000000", 30, 5, 10]'

Expected output: You'll see deployment confirmation details including:

• Transaction hash
• Block hash
• Contract address (this is your DelegatedStaking contract address)

Make note of the contract address returned in the deployment output. This is your DelegatedStaking contract address that you'll share with potential delegators.

5.3B.4: Information for Delegators

Once your delegated staking validator is registered, you'll need to share the following information with potential delegators:

• Your DelegatedStaking contract address (the address returned when you deployed the contract)
• The minimum delegation amount (the value you set for MinDelegationAmount)
• The minimum delegation duration (the value you set for MinDelegationDuration)

Provide these instructions to users who want to delegate their stake to your validator:

To delegate stake to this validator:

aecli contract call delegate_stake '[]' YOUR_WALLET_FILE \
  --contractSource DelegatedStaking.aes \
  --contractAddress DELEGATED_STAKING_CONTRACT_ADDRESS \
  --amount AMOUNT_TO_STAKE

To request reward withdrawals:

aecli contract call request_withdraw_rewards '[]' YOUR_WALLET_FILE \
  --contractSource DelegatedStaking.aes \
  --contractAddress DELEGATED_STAKING_CONTRACT_ADDRESS

To unstake your delegation:

aecli contract call request_unstake_delegated_stakes '[]' YOUR_WALLET_FILE \
  --contractSource DelegatedStaking.aes \
  --contractAddress DELEGATED_STAKING_CONTRACT_ADDRESS

To check your queued withdrawals:

aecli contract call get_all_queued_withdrawals_by_owner '["YOUR_ADDRESS"]' YOUR_WALLET_FILE \
  --contractSource DelegatedStaking.aes \
  --contractAddress DELEGATED_STAKING_CONTRACT_ADDRESS

Example with sample values:

# Example to delegate stake (replace with actual values)
aecli contract call delegate_stake '[]' hc_test/wallets/delegator.json \
  --contractSource DelegatedStaking.aes \
  --contractAddress ct_2ngxzhAJbgsx996j5twtWWwq8btCjFXD3m5Cr1aWPL4JczzsH \
  --amount 1000000000000000000000000

Note that delegators will need to have the Hyperchain's native token to delegate to your validator, not AE tokens from the parent chain.

Note that delegators will need to have the Hyperchain's native token to delegate to your validator, not AE tokens from the parent chain.

You can now proceed to Step 6.

Step 6: Wait for Activation

IMPORTANT: Your new validator will not immediately start producing blocks. The Hyperchain system requires a waiting period before a new validator becomes fully active in the consensus process. This delay is typically around 2 hours, which corresponds to 4 epochs or 2400 blocks in the example configuration used in this document.

Why the Delay?

This waiting period is a security measure. It allows the network to recognize the new validator, propagate its information, and ensure stability before it actively participates in block production. It also gives the network time to adjust to the new validator's presence and prevent any potential disruptions.

What to Do During the Waiting Period

While waiting for your validator to become active, it's crucial to monitor its status and ensure everything is running smoothly. Here are the key actions you should take:

Monitor Validator Node Logs: Regularly check the logs of your validator node for any errors or warnings. This will help you identify and resolve potential issues early. To view the logs, use the command:

docker logs <container_id>

where <container_id> is the ID of your validator's Docker container (you can find this using docker container ls). Look for any error messages or unusual behavior in the logs. If you see anything concerning, investigate it further and take corrective action.

Verify Network Connectivity: It's crucial to ensure your validator node remains connected to the Hyperchain network. To check this, you can periodically query the node's status endpoint using the curl command as described in Step 4.1.

Specifically, confirm that the output shows:

• "listening": true and "peer_count" greater than 0.

If the node loses connection, investigate your network settings and ensure there are no connectivity issues.

Monitor Validator Status: You can check your validator's status and other validators in the network using the middleware API endpoint:

curl http://localhost:4000/v3/hyperchain/validators | jq

This will show the complete list of validators for each epoch and their current status.

Check Pinner Account Balance: Verify that your pinner account on the parent chain (aeternity mainnet or testnet) has sufficient funds for pinning operations. Pinning transactions require AE tokens to pay for transaction fees. Insufficient funds will prevent your validator from performing pinning operations correctly once it becomes active.

You can use the aeternity CLI to inspect your pinner account's balance using the command:

aecli inspect <pinner_account_address>

Be Patient: Remember that the activation delay is expected. Do not be alarmed if your validator doesn't immediately produce blocks. The 2-hour or 2400-block waiting period is a standard part of the process. Allow the system to complete its necessary checks and adjustments.

What Happens After the Waiting Period?

Once the waiting period is over, your validator should automatically start participating in the consensus process and producing blocks. You can monitor its activity through the node logs and by checking the top_block_height in the status endpoint output.