Validators

This page outlines the changes affecting existing and new validators:

• RPC API node software changes from Hyperledger Besu to Polygon Edge
• New staking process for validators
• Validator block reward changes
• How to to become a validator

Validators’ stakes are set up on Ethereum (which requires MATIC). Validators receive staking rewards on Palm network in PALM tokens.

Palm is transitioning to become a L2, and the Polygon Edge software includes a built-in bridge relayer to Ethereum. The relayer node owned by Palm will submit these transactions and cover the Ethereum mainnet gas costs for these.

System requirements

The system requirements for your node may vary from what was required for Hyperledger Besu. Please refer to the following which outlines the minimum and recommended specs for running the Polygon Edge node client:

• https://wiki.polygon.technology/docs/supernets/operate/supernets-requirements/

Component	Minimum Requirement	Recommended
Processor	4-core CPU	8-core CPU
Memory	8 GB RAM	16 GB RAM
Storage	200 GB SSD [1]	1 TB SSD
Network	High-speed internet connection	Dedicated server with gigabit connection

[1] As of August 2023, Palm Mainnet currently requires 150 GB of storage, so the minimum storage requirement may need to be adjusted accordingly

Installation

• Install Go at version 1.20 from https://go.dev/dl/ (1.21 is not currently compatible)
• Clone the repo here https://github.com/gateway-fm/polygon-edge
• Check out the branch palm-migration
• At the root of the repo run make build
• You now have a binary called polygon-edge at the root of the repo
• Copy this file where you plan to run the node
• Create a new empty directory that will serve as the data-dir for the node
• Copy the genesis file for the shadowfork to your data-dir and name it genesis.json.
• Genesis files for various instances of the Palm network can be found in the root folder of called genesis-xxxxx.json

Alternatively there are binary downloads available at https://github.com/gateway-fm/polygon-edge/releases

Docker images are also built alongside the binary releases and are available at gatewayfm/polygon-edge. Each version will have 3 tags assigned for the different environments, these are:

• testnet-[version]
• mainnet-[version]
• testnet-shadowfork-[version]

Please ensure you use the correct tag for your environment as the genesis file is contained inside the image for each environment.

To prepare your environment for running the node you will need to ensure the following ports are configured:

• 8545 - JSON RPC - can be left closed if you don’t intend on exposing the RPC
• 9632 - GRPC (for intercommunication between the validators) - this will need to be open for validators although an IP allowlist configured at the firewall level is recommended
• 30302 - devp2p port - needs to be open to join the old Besu network
• 30301 - libp2p port - needs to be open to allow discovery on the libp2p network
• 30401 - egress needed to communicate with the Besu node (better yet, have all egress available as this port could change)

If you run other nodes within the same subnet you may need to update the ports above so that your node has exclusive use of them.

Operating your node

To keep the network healthy and producing blocks at the correct rate you should keep your node active and connected to the network at all times, failing to do so will cause the network to increase the round count and choose another validator slowing down block production. The validator nodes are also slower to catch up to the tip of the chain so at a minimum you should not let your node be inactive for more than 5 minutes.

Monitoring the latest block and checking the timestamp to determine how far behind your node is can be useful to see if block production has halted for any reason and prompt an investigation into the node. There is also a healthcheck endpoint to ensure that the node is alive available at http://your-address:8545/health a GET request to this endpoint will return a status 200 response with a body of OK if the node is healthy.

Upgrading the version of Polygon Edge is a simple procedure. Build the new binary and replace the existing version with this new binary and restart the node with the same flags as before.

Staking requirements & validator awards

As Palm network transitions to Proof-of-Stake, validators are required to stake 1 MATIC with the stake manager contract on Ethereum - see below for the instructions. Validators receive a portion of the epoch reward for each signed block in the epoch, the reward pool is 246.4 PALM per epoch (2160 blocks) on the Palm network. This keeps rewards in line with the existing setup using IBFT consensus. A 6 month supply of PALM is premined at the fork point to cover validator rewards.

Validators can use the private keys associated with their nodes to retrieve the PALM from the accounts (e.g. by importing them to MetaMask).

Since the start of the Palm network 13,478,746 blocks have been created at the time of writing (Sept 11, 2023) with a block reward of 0.114085402 PALM. This has increased the initial 1bn supply by 1,537,728

Bad actors, or validators who’s nodes aren’t meeting the uptime requirements of the network, can have their stake slashed to 0 effectively removing their voting power and removing them as a validator from the network

Contract addresses

The two important contract addresses for the rootchain can be found in the genesis file in the engine > polybft > bridge section. These are:

• customSupernetManagerAddr
• stakeManagerAddr
• stakeTokenAddr

Becoming a validator

The Palm Foundation will help co-ordinate the process of becoming a new validator. Please contact them here:

Step 1 - Setup an AWS account

You will need an AWS account to securely store your account secrets. Polygon Edge will generate these for you and store them in your AWS account under Systems Manager > Parameter Store.

Once you have your account created you will need to set up an IAM user with a secure password and ensure this user has the following permissions for Systems Manager:

• GetParameter
• GetParameters
• GetParametersByPath
• PutParameter

Once this is setup head to your newly created IAM user and under the Security Credentials tab head down to Access Keys and click on the Create access key button. Choose CLI in the list of available options and check the box to state you understand there are alternative options. Securely store both the Access Key and Secret Access Key values.

Step 2 - Create your keys

Create a json file named config.jsonwith contents like the following. Adjust the Name and ssm-parameter-path values as you see fit to suit your needs:

{
 "Type": "aws-ssm",
 "Name": "palm-validator-1",
 "Extra":
  {
   "region": "eu-north-1",
   "ssm-parameter-path": "/palm-network"
  }
}

Set the following environment variables ensuring the values match those from AWS and in the config.json file you just created:

AWS_DEFAULT_REGION=eu-north-1
AWS_SECRET_ACCESS_KEY=xxx
AWS_ACCESS_KEY_ID=xxx

Now you are ready to generate and store your keys in AWS by running the following:

./polygon-edge polybft-secrets \
--config config.json \
--json > output.json

This will create the output.json file with the public properties of the account just created, including the public key address for the validator which you will need later.

Step 3 - Run your node and sync to the tip of the chain

Syncing to the tip of the chain will help when you join the network as a validator as you won’t be asked to produce a block that is higher up the chain than your current position, and will keep the network producing blocks at the correct rate. You will need the config.json file you created in the earlier step to define where the secrets are stored. Ensure you use the same file.

./polygon-edge server \
--data-dir=./new-validator \
--secrets-config config.json \
--libp2p "0.0.0.0:30301" \
--devp2p "0.0.0.0:30302" \
--grpc-address="0.0.0.0:9632"

Step 4 - Request to be whitelisted

Once you have synced to the tip you can request to be added to the validator whitelist. After this, which point your account will be enabled on the rootchain to be permitted to stake and register as a validator. Once you have received notification that this has been done you can progress to step 5.

Step 5 - Register with the supernet manager contract

The next step is to register the node with the supernet manager contract on the root chain, i.e on Ethereum mainnet. The account associated with your node (see the output.json file for the address) will need some ETH for gas fees for this transaction. The register-validator step below uses around 320,000 gas units. With a typical gas price of 35 gwei, this equates to 0.0112 ETH.

./polygon-edge polybft register-validator \
--config config.json \
--supernet-manager [address of customSupernetManagerAddr from the genesis file] \
--jsonrpc https://eth-mainnet.public.blastapi.io

Step 6 - Stake with the stake manager

This step also requires that your node account on Ethereum mainnet has some ETH for gas. There are two transactions initiated, Approve and Stake. These use 29,000 and 130,000 gas units respectively. At 35 Gwei gas price, this would require 0.005565 ETH.

./polygon-edge polybft stake \
--config config.json \
--jsonrpc https://eth-mainnet.public.blastapi.io \
--supernet-id 1 \
--amount 1000000000000000000 \
--stake-token [address of stakeTokenAddr] \
--stake-manager [address of stakeManagerAddr]

The validator is now staked and can launch their node to become an active participant in the network.

Step 7 - Start your node as a validator

./polygon-edge server \
--data-dir=./new-validator \
--secrets-config config.json \
--chain=/path/to/your/genesis.json \
--seal \
--num-block-confirmations 128 \
--libp2p "0.0.0.0:30301" \
--devp2p "0.0.0.0:30302"

Congratulations! you are now running a validator node on the Palm supernet. After a few hours, you should see in the logs the occasional message “we are the proposer” to confirm that you are creating blocks for the network.

Reward Withdrawal

Rewards per epoch are held the reward pool smart contract. To remove your rewards and transfer these to your account you can run the following command.

These will be withdrawn to the account on Palm mainnet. Your account will be topped up with some PALM to allow for the initial withdrawal gas fees.

./polygon-edge polybft withdraw-rewards \
--config config.json \
--jsonrpc http://127.0.0.1:8545 \
--data-dir=./new-validator