Collator

Functionalities of collators

The Litentry collators retain all necessary information to collate and execute transactions to create an unsealed block and provide it, together with a proof of state transition, to one or more relaychain validators responsible for proposing a parachain block.

Collators will also watch the progress of block-producing and consensus protocols in BABE and build on what they think is the latest relay chain block that will be finalized. Collators do not directly participate in the consensus for the relaychain and therefore never stake DOT.

To become a collator and start to author blocks, one has to possess a valid session key, which is either set in the initial genesis config as invulnerable or by selection via the parachain-staking pallet.

Litentry collator model

Litentry uses a Delegated Proof of Stake(DPoS) collation model, where users of the network vote and elect delegates to author the next block. Using DPoS, instead of running a collator to earn rewards, you can vote on delegates by staking your tokens to a particular delegate. When the selected delegate manages to produce blocks, you will share the block production reward as well.

Litentry takes a phased approach to roll out the collator setup. Basically speaking, there are 5 phases:

1. migrate the collator selection mechanism and the genesis collators (replacecollator-selection pallet withparachain-staking pallet)

2. initial collator set expansion: open a few extra collator slots and observe the block production

3. adjust tokenomics to prepare for the staking functionality

4. enable delegation with staking

5. extend the collator set size (to 16 or 32 collators, depending on the network status)

You can follow the rollout progress in this GitHub issue.

Block production rewards

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:

• Target a 1.5% annual inflation rate in the first 1,296,000 blocks (~= 6 months) after staking is enabled on chain, 0.5% goes towards incentivizing collators, 1% is for users that stake their LIT tokens

• After block 1,296,001 a 2.5% annual inflation rate will be applied, 0.5% goes towards incentivizing collators, 2% is for users that stake their LIT tokens

• 568,750 LIT will be burnt from the ecosystem wallet each quarter and continues for eight quarters (two years)."

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 LIT, 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 Litentry team. It means you'll need to get your collator account whitelisted to be able to join the candidate pool. Please refer to Litentry collator model for more details.

How to run a collator

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="litentry-collator" with your own node name:

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

litentry/litentry-parachain:v0.9.11 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 litentry-parachain is a sr25519 aura key.

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

• prepare a litentry-parachain 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, please refer to Litentry collator model

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 litentry 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 Litentry'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

Litentry 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 litentry-collator process

2. download the desired binary

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