Collator

Functionalities of the Collators

To resonate with the collator staking model, we reworked the tokenomics model to allow the collators and their backed users to share the block production rewards.

A short summary:

• 30% of the network's gas fees will be allocated as rewards for collator staking participants.

• This dynamic reward model ensures that rewards scale with network usage, incentivizing active participation and growth.

Requirements to run a collator

Hardware requirements

Same as the polkadot validator reference hardware

bonding requirements

There's a minimum (self)-bond to join the collator candidate pool and be eligible to get selected to author blocks. Currently it's set to 5000 HEI, you'll have to specify the bond amount when joining the candidate pool via parachainStaking.joinCandidates

whitelisting

Before we fully activate the DPoS model, the collator set is managed by the whitelist from the Heima team. It means you'll need to get your collator account whitelisted to be able to join the candidate pool.

How to run a collator

Currently collator is still the old "Litentry" version. The Heima new version doc update will come very soon.

using docker (preferred)

1. create a local directory to store the chain database:

mkdir /var/lib/litentry
# or use sudo if you don't have permission
sudo mkdir /var/lib/litentry

2. make sure the permission and ownership of the local directory are correctly set:

sudo chown -R $(id -u):$(id -g) /var/lib/litentry

3. run the following docker command, you can replace the --name="heima-node" with your own node name:

docker run -d --network=host -v /var/lib/litentry:/data \
    -u $(id -u):$(id -g) \
    litentry/litentry-collator:v0.9.22-02  \
    --base-path=/data \
    --chain=litentry \
    --name="litentry-collator" \
    --collator \
    --execution wasm \
    --state-cache-size 0 \
    -- \
    --execution wasm \
    --chain polkadot

litentry/litentry-collator:v0.9.22-02 is used as an example, please check github release page for the up-to-date releases

The command will run the docker container in the background and the container ID will be printed in the console. With docker logs -f <container-id> you should be able to see the node starts to sync:

node syncing

Wait until syncing is done. Depending on the hardware and network status it could take several days to fully sync the parachain and relaychain database.

4. generate a session key by sending an RPC call to the http endpoint of the parachain with the author_rotateKeys method:

curl http://127.0.0.1:9933 -H \
"Content-Type:application/json;charset=utf-8" -d \
  '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"author_rotateKeys",
    "params": []
  }'

An exemplary result:

{"jsonrpc":"2.0","result":"0x56066a71efc51e4a6f0f838cac959a08b238e22d478bd5dc0cdc2ac5b40d2e66","id":1}

Note down the result, this is your session key. In this case 0x56066a71efc51e4a6f0f838cac959a08b238e22d478bd5dc0cdc2ac5b40d2e66

Alternatively you could use author_insertKey to insert the pre-generated session key. The session key for heima-node is a sr25519 aura key.

5. bind your collator account to the generated session key, this includes:

• prepare a heima-node account. This account will be registered to receive block production rewards.

• bind this account to the session key generated in step 4 by submitting extrinsic session.setKeysfrom the collator account:

session.setKeys

parameters:

• keys: the hex string key from step 4

• proof: 0x

6. request to join the collator candidate by submitting extrinsic parachainStaking.joinCandidates from the collator account:

join the candidate pool

To be able to successfully join the collator candidates, you have to:

• stake the minimum bonds

• get added to the candidate whitelist by the admin (whitelisting will be removed once the DPoS is fully activated)

7. check your node actually starts to collate

Once the extrinsic is sent without errors, wait until the next round begins and you should be able to see your node starting to produce blocks:

new collator produces a block

You should see your node gets chosen from time to time to author blocks according to the emitted events:

the new collator is chosen

If the collator doesn't produce blocks after a long time (~12 hours) while you believe everything is correctly set, please try to restart the node.

Congratulations! You have managed to run a collator node that starts to produce blocks for the Heima parachain!

using binary

Running a collator node with the raw binary is very similar to the docker setup above, it only differs a bit in the command line arguments. So instead of steps 1-3 above, run:

./target/release/litentry-collator \
    --chain=litentry \
    --name="litentry-collator" \
    --collator \
    --execution wasm \
    --state-cache-size 0 \
    -- \
    --execution wasm \
    --chain polkadot

By default, the database is stored at ~/.local/share/, you can override it by using --base-path=<your-path>.

To get the binary, you could either download it directly from Heima's Github release page (Linux x86-64 only), or build it from the source.

The remaining steps to configure the session key and join the collation are the same as the docker method, so it's not repeated here.

How to update the client

Heima constantly works on improving the parachain client and following the upstream changes. Therefore, it's not uncommon to update the client to have the newest features and security patches. Updating the client is simple:

If using docker:

1. docker container stop <container-id>

2. run the docker command in step 3 in using docker (preferred) , with the desired docker image version

If using binary:

1. stop/kill the heima-node process

2. download the desired binary

3. start the new binary using the commands in # using binary