Polygon Supernets: Architecture & Local Setup
In this article we are going to cover-
- What arePolygon Supernets?
- What are modules used by Polygon Supernets?
- Polygon Supernets local setup from scratch
What are Polygon Supernets?
Supernets are application-specific chains that operate on the Polygons Edge consensus client with PolyBFT consensus. They leverage a native bridge to connect with an associated rootchain, namely, Polygon PoS mainnet, enabling them to inherit its security and capabilities. Additionally, Supernets extend the block space available on the rootchain, providing scalability and interoperability for decentralized applications. With on-chain governance mechanisms, Supernets empower communities to make decisions and upgrade the network in a transparent and compliant manner.
Modules offered by Polygon Supernets
Polygon Supernets offers wide range of modules that developers can customize depending on their needs.
- Blockchain
Coordinates everything in the system, curates state transitions, and is responsible for state changes when a new block is added to the chain. - Consensus
PolyBFT serves as the consensus mechanism of Polygon Supernets and consists of a consensus engine, IBFT 2.0, and a consensus protocol that includes the bridge, staking, and other utilities. - libp2p
Libp2p provides the basis for the underlying network layer and provides the networking layer for Supernets and is designed for peer-to-peer network architectures. - Bridge
An in-built bridging mechanism enabled by PolyBFT that allows message passing between a Supernet and another Proof-of-Stake blockchain without mapping. - Mempool
Enables multiple validators to aggregate their signatures to create a single, aggregated signature representing all validators in the pool. - TxPool
Tx Pool layer pools the transactions from different parts of the system and it is closely linked with other modules in the system, as transactions can be added from multiple entry points. - JSON-RPC
The JSON RPC layer is an API layer that allows developers use to communicate with the blockchain. - Networking(gRPC)
GRPC layer is vital for operator interactions. It leverages the communications between nodes which helps node operators interact easily with the client.
Polygon Supernet local setup
So, after having a look at the architecture and the modules used by Polygon Supernet. Let us set the Polygon Supernet network locally on a linux machine running ubuntu . Before going for the further steps, let us discuss the pre-requisites-
- Go >=1.18 (Recommended) on your local machine
sudo snap install go --channel=1.19/stable --classic - Docker Engine
- Polygon-Edge Binary (0.9.0)
After you are done with the prerequisites, we can install the Polygon Edge binary using go build -o polygon-edge.
In your terminal paste this command-
tar -xvzf polygon-edge-0.9.0.tar.gzThis should extract the content of polygon-edge into current directory
cd polygon-edge-0.9.0
go build -o polygon-edge The binary file after this command will be located in your current directory.
After this you can confirm your installation by typing ./polygon-edge in your terminal.
Now we will setup working polygon-edge blockchain network working with polyBFT consensus protocol.
The blockchain network shown in the above image consist of 4 nodes of whom all 4 are validator nodes, and as such are eligible for both proposing block, and validating blocks that came from other proposers.
For our article we will work with a four nodes who will be acting both as the validators and will also propose new block.
NOTE : There is no minimum to the number of nodes in a cluster, which means clusters with only 1 validator node are possible. Keep in mind that with a single node cluster, there is no crash tolerance and no BFT guarantee.
Therefore, the minimum recommended number of nodes for achieving a BFT guarantee is 4 — since in a 4 node cluster, the failure of 1 node can be tolerated, with the remaining 3 functioning normally.
For generating a fully functional polyBFT cluster we need to follow below steps-
1. Node preparation
(i) Initializing data directories
The polygon-edge polybft-secrets command is used to generate account secrets for validators. The command initializes private keys for the consensus client (validators + networking) to a Secrets Manager config file.
./polygon-edge polybft-secrets --insecure --data-dir node-app-chain- --num 4node-app-chain- here acts as a prefix for node directory and — num flag is used to specify the number of node directory to be generated. You can name it as per your convenience.
The above commands prints the validator key and the node ID. We will require node ID for the next step.
You should also see a folder created by the node name that you would have specified.
(ii) Prepare the multiaddr connection string for the bootnode
If a node wants to establish a successful connection, it must know which bootnode server to connect to in order to gain information about all the remaining nodes on the network.
Since we are going with a four node for our demo, the first 2 nodes will be acting as the bootnode as every polygon-supernet node can serve as a bootnode but in case of multiple nodes, every polygon-supernet node needs to have a set of bootnode specified which will be contacted to provide information on how to connect with all remaining nodes in the network.
NOTE : At least one bootnode is required, so other nodes in the network can discover each other. More bootnodes are recommended, as they provide resilience to the network in case of outages.
To create the connection string for specifying the bootnode, we will need to conform to the multiaddr format.
/ip4/<ip_address>/tcp/<port>/p2p/<node_id>Here,
ip_address :127.0.0.1 (as we are running on localhost)
port :10001
node_id : 16Uiu2HAmD4NEvMCTdcr3aMiWSfvQcwJLPDgnwxBCmHcDdRX7HXaJ
You may have a different node_id, so replace it with yours.
/ip4/127.0.0.1/tcp/10001/p2p/16Uiu2HAmD4NEvMCTdcr3aMiWSfvQcwJLPDgnwxBCmHcDdRX7HXaJ(iii) Generate the genesis file with two bootnodes
./polygon-edge genesis --block-gas-limit 10000000 --epoch-size 10 \
--validators "/ip4/127.0.0.1/tcp/30301/p2p/16Uiu2HAmD4NEvMCTdcr3aMiWSfvQcwJLPDgnwxBCmHcDdRX7HXaJ:0xb1C611804B62c05424C194ef9Ed0758822C2d6A3:2c63964d0bb2016f4926cfbb9dfd2b31eae33fddbc2d498b573c3574b9f40dc42e483134a32208eeafe116aa9a860b68eb0539af22142fb4a781ae42db4673c81306752b212990a611885cdb9bd819b89d2a1f2959f5625c87adb6d9349745d927ab150e6bdde208f039977e090be1ed2fd5774e4c6c1571e044a2ff0fb09bee" \
--validators "/ip4/127.0.0.1/tcp/30302/p2p/16Uiu2HAmA2vA8sYqmSUJmqzu5Byjh5vj2b7EWuFLkUZQYfCNHZid:0x2760e02E1DeaE5b7641c73A98764A4c10E567417:2f24e6c88c091d1d5df14c574c8e0c02dbafc4caac8bb1e44c0a55d39aae1bf02cdbbfa1717b52ded2a6e918810bff20742aa24628ddeb69c81ee2016610dfc52102be5dfebd8c89da2717fccddd0b0ca75397b913ebf1aec10dcc8e96ede6db2c048a94b4a58c124ae48196412234dc9139042a54214dfcf0d73262569189e5" \
--consensus polybft \
--reward-wallet 0xb1C611804B62c05424C194ef9Ed0758822C2d6A3:1000000 \
--transactions-allow-list-admin 0xb1C611804B62c05424C194ef9Ed0758822C2d6A3,0x2760e02E1DeaE5b7641c73A98764A4c10E567417 \
--transactions-allow-list-enabled 0xb1C611804B62c05424C194ef9Ed0758822C2d6A3,0x2760e02E1DeaE5b7641c73A98764A4c10E567417we can also premine some balance to our account address using — premine flag. You can take any address from your Metamask and provide some ethers.
./polygon-edge genesis --block-gas-limit 10000000 --epoch-size 10 \
--validators "/ip4/127.0.0.1/tcp/30301/p2p/16Uiu2HAmD4NEvMCTdcr3aMiWSfvQcwJLPDgnwxBCmHcDdRX7HXaJ:0xb1C611804B62c05424C194ef9Ed0758822C2d6A3:2c63964d0bb2016f4926cfbb9dfd2b31eae33fddbc2d498b573c3574b9f40dc42e483134a32208eeafe116aa9a860b68eb0539af22142fb4a781ae42db4673c81306752b212990a611885cdb9bd819b89d2a1f2959f5625c87adb6d9349745d927ab150e6bdde208f039977e090be1ed2fd5774e4c6c1571e044a2ff0fb09bee" \
--validators "/ip4/127.0.0.1/tcp/30302/p2p/16Uiu2HAmA2vA8sYqmSUJmqzu5Byjh5vj2b7EWuFLkUZQYfCNHZid:0x2760e02E1DeaE5b7641c73A98764A4c10E567417:2f24e6c88c091d1d5df14c574c8e0c02dbafc4caac8bb1e44c0a55d39aae1bf02cdbbfa1717b52ded2a6e918810bff20742aa24628ddeb69c81ee2016610dfc52102be5dfebd8c89da2717fccddd0b0ca75397b913ebf1aec10dcc8e96ede6db2c048a94b4a58c124ae48196412234dc9139042a54214dfcf0d73262569189e5" \
--consensus polybft \
--reward-wallet 0xb1C611804B62c05424C194ef9Ed0758822C2d6A3:1000000 \
--transactions-allow-list-admin 0xb1C611804B62c05424C194ef9Ed0758822C2d6A3,0x2760e02E1DeaE5b7641c73A98764A4c10E567417 \
--transactions-allow-list-enabled 0xb1C611804B62c05424C194ef9Ed0758822C2d6A3,0x2760e02E1DeaE5b7641c73A98764A4c10E567417 \
--premine <YOUR_METAMASK_ADDRESS>:<AMOUNT_IN_WEI> 
As you can see, I have premined 1000 ETH to my account address and our genesis file is now successfully created.
2. Rootchain configuration
In this section, we’ll configure the associated rootchain of the Supernet and deploy the necessary rootchain core contracts.
(i) Deploy and initialize rootchain.
To start the root chain paste this command in your terminal -
./polygon-edge rootchain serverThe polygon-edge rootchain server command starts an ethereum/client-go container, which runs a new Geth node on the default JSON-RPC port of 8545.
(ii) Initialize rootchain Contracts.
To deploy the rootchain contracts, we use the polygon-edge rootchain deploy command.
./polygon-edge rootchain deploy \
--genesis ./genesis.json \
--json-rpc http://127.0.0.1:8545 \
--testthe — test flag runs the deployment in test mode and use the test account provided by the Geth dev instance as the depositor.
These smart contracts will be used to manage validators on the root chain.
(iii) Funding validators on the rootchain
It’s crucial to have enough funds in the validator account, as they need to cover the gas fees associated with their transactions on the rootchain.
To fund the validators’ accounts on the rootchain, we use the polygon-edge rootchain fund command. When executed with the appropriate flags, it will:
- Retrieve the validator account from the secrets manager.
- Send a transaction to fund the validator account on the rootchain with a value of 10,000 $token (the network’s native token).
- Repeat steps 1 and 2 for each validator.
./polygon-edge rootchain fund --data-dir ./node-app-chain-1 --amount 10000000000000000000000 \
--native-root-token 0x6FE03c2768C9d800AF3Dedf1878b5687FE120a27 --mint 
3. Validator Whitelisting and Registration in CustomSupernetManager Contract
(i) Whitelist validators on the rootchain
The CustomSupernetManager contract on the rootchain is responsible for managing the PolyBFT network.
Before validators can be registered on the CustomSupernetManager contract on the rootchain, they need to be allowlisted by the deployer of the CustomSupernetManager contract.
This can be done using the polygon-edge polybft whitelist-validators command.
./polygon-edge polybft whitelist-validators \
--private-key aa75e9a7d427efc732f8e4f1a5b7646adcc61fd5bae40f80d13c8419c9f43d6d \
--addresses 0xb1C611804B62c05424C194ef9Ed0758822C2d6A3,0x2760e02E1DeaE5b7641c73A98764A4c10E567417 \
--supernet-manager 0x75aA024A2292A3FD3C17d67b54B3d00435437246 \
--jsonrpc http://127.0.0.1:8545The — private-key flag is used to specify the hex encoded private key of the CustomSupernetManager Contract Deployer.
for the demo geth instance, the test account private key has been hardcoded:
aa75e9a7d427efc732f8e4f1a5b7646adcc61fd5bae40f80d13c8419c9f43d6d.
(ii) Register validators on the rootchain
Each validator needs to register themselves on the CustomSupernetManager contract. This is done using the polygon-edge polybft register-validator command.
./polygon-edge polybft register-validator --data-dir ./node-app-chain-1 \
--supernet-manager 0x75aA024A2292A3FD3C17d67b54B3d00435437246 \
--jsonrpc http://127.0.0.1:8545 
Repeating the above for each validator will register the validator address in the CustomSupernetManager contract.
4. Staking
(i) Initial staking on the rootchain
Each validator needs to perform initial staking on the rootchain StakeManager contract. This is done using the polygon-edge polybft stake command.
./polygon-edge polybft stake --data-dir ./node-app-chain-1 --chain-id 1 --amount 10000000000000000 \
--stake-manager 0x811068e4106f7A70D443684FF4927eC3940439Ec --native-root-token 0x6FE03c2768C9d800AF3Dedf1878b5687FE120a27 \
--jsonrpc http://127.0.0.1:8545
In the following example command, we use the validator key and the rootchain StakeManager contract address that were generated earlier. We also set the staking amount to 10000000000000000 which is equivalent to 0.01 token. The --native-root-token flag is used to specify the address of the native token of the root chain.
Repeating the above command for each validator will allow the validators to self stake on the rootchain StakeManager contract.
(ii) Finalize validator set on the rootchain
After all validators from the genesis block have performed initial staking on the rootchain, the final step required before starting the chain is to finalize the genesis validator set on the SupernetManager contract on the rootchain. This can be done using the polygon-edge polybft supernet command.
./polygon-edge polybft supernet --private-key aa75e9a7d427efc732f8e4f1a5b7646adcc61fd5bae40f80d13c8419c9f43d6d \
--genesis ./genesis.json \
--supernet-manager 0x75aA024A2292A3FD3C17d67b54B3d00435437246 \
--stake-manager 0x811068e4106f7A70D443684FF4927eC3940439Ec \
--finalize-genesis-set --enable-staking \
--jsonrpc http://127.0.0.1:8545If the --enable-staking flag is provided, validators will be able to continue staking on the rootchain. If not, genesis validators will not be able to update their stake or unstake, nor will newly registered validators after genesis be able to stake tokens on the rootchain.
The — finalize-genesis-set flag is used to finalize the genesis state.
5. Start the Nodes
Now that we have set up the rootchain and created the chain configuration, we can run the Supernet cluster of Edge clients. In this example, we’ll run a cluster of four Edge clients.
For our first node we have-
5001 : gRPC server
30301 : libp2p server
10001 : JSON-RPC server
Now let’s start the node using command-
./polygon-edge server --data-dir ./node-app-chain-1 --chain genesis.json --grpc-address :5001 --libp2p :30301 --jsonrpc :10001 --seal --log-level DEBUGSimilarly the command for other validators —
./polygon-edge server --data-dir ./test-chain-2 --chain genesis.json --grpc-address :5002 --libp2p :30302 --jsonrpc :10002 --seal --log-level DEBUG
./polygon-edge server --data-dir ./test-chain-3 --chain genesis.json --grpc-address :5003 --libp2p :30303 --jsonrpc :10003 --seal --log-level DEBUG
./polygon-edge server --data-dir ./test-chain-4 --chain genesis.json --grpc-address :5004 --libp2p :30304 --jsonrpc :10004 --seal --log-level DEBUGYou can also provide block time that you want to set for the creation of blocks using the flag — block-time. By default the block time is 2 sec.
Your terminal must have been running now, you can now go and check in your browser by typing your JSON-RPC URL.
If you see something similar to what’s been described, congratulations! You’ve successfully initiated your Polygon Supernet cluster. This marks the conclusion of this guide. It’s my hope that it has provided you with all the necessary information to begin your adventure with Polygon Supernet.
Happy programming!
Should you have any questions or concerns, feel free to reach out to me via this link: LinkedIn — https://www.linkedin.com/in/adityarola/
References
