Skip to content

Commit

Permalink
add missing files
Browse files Browse the repository at this point in the history
  • Loading branch information
brenzi committed Jun 21, 2024
1 parent 58e673a commit b6d6610
Show file tree
Hide file tree
Showing 3 changed files with 123 additions and 0 deletions.
60 changes: 60 additions & 0 deletions src/infrastructure-collator-setup.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Collator Setup

Collators are parachain [full nodes](./infrastructure-full-node-setup.md) which additionally collect pending transactions, order them and propose new blocks on Encointer Network. Their operation is critical for availability, but not for security. The latter is provided by the validators of the Kusama relay chain.

### Who can run collators?

Encointer’s aura consensus is based on a quasi-static set of authorities which can be mutated every 6 hours. This collator set consists of permanent, *invulnerable* nodes and a dynamic, unpermissioned set of nodes. Invulnerables are currently run by the Encointer Association and partners. Anyone can join the set of unpermissioned collators by submitting a candidacy and bonding some stake in KSM. Candidates are selected based on their stake until the desired set is full.

#### Requirements

* a full node running with high availability
* 5 KSM to bond

#### Incentives

As Encointer is a systemchain on Kusama, collator operators can join the [IBP](https://ibp.network/) and get rewarded from the Kusama Treasury, subject to multiple conditions.

Moreover, collators collect extrinsic fees on the network. On Encointer, fees are paid in either KSM or any of the community currencies. As a collator you will, therefore, also receive community currencies from all around the world.

We encourage members of Encointer communities to run their own collators to ensure the network is decentralized and censorship-resistant. Communities who don't run their own collators rely on others to do so who could in theory de-prioritize, delay or even censor transactions for a particular community. Collecting fees in their own community currency is added benefit.

### Run a Collator Node

See the above chapter on how to [run a full node](./infrastructure-full-node-setup.md). There is only one difference: The parachain CLI (the part before the `--`) needs the `--collator` flag.

### Generate an Authority Key

Collators need to manage two types of keys:
* A *session key* which is used to sign blocks. this key must always be online and is therefore not considered highly secure. It should be rotated regularly.
* An *authority key* which used to submit candidacy, bond funds and change session keys. This key isn't needed very often and should be kept secure.

To generate an authority key, please choose a [polkadot wallet](https://polkadot.network/ecosystem/wallets/) and follow the steps to generate and secure a new account. In the following, we assume that you use a browser extension to keep your authority key safe.

### Rotate Session Key

The best way to rotate session keys is to let the collator itself do this. The `author_rotateKeys` rpc call will generate a new key and print the public key. On your collator machine, run the following command:

```bash
curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "author_rotateKeys", "params":[]}' http://localhost:9944
```

Take note of the fresh public key in hex format which is returned returned as json response.

### Register Session Key

Use the [session.setKeys](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fsys.ibp.network%2Fencointer-kusama#/extrinsics/decode/0x1600000000000000000000000000000000000000000000000000000000000000000000 ) call to register your key.
* `keys`: your session key in hex format with `0x` prefix
* `proof`: not needed. just put `0x`

### Submit Candidacy

Use your authority key to call [collatorSelection.registerAsCandidate](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fsys.ibp.network%2Fencointer-kusama#/extrinsics/decode/0x1503). This will bond 5 KSM. Please make sure your free balance is higher than that.

Your collator should appear on the [collator dashboard](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fsys.ibp.network%2Fencointer-kusama#/collators). In any case, you'll need to wait for the next session (up to 6 hours)

When there are more candidates than desired nodes, preference will be given to the candidates with highest bonds. If you wish to update your bond, please call [collatorSelection.updateBond](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fsys.ibp.network%2Fencointer-kusama#/extrinsics/decode/0x150700000000000000000000000000000000)

Should you be selected into the set of active collators, any downtime can lead to degraded block times. Should your node fail to propose blocks, you may be removed for the upcoming session.


59 changes: 59 additions & 0 deletions src/infrastructure-full-node-setup.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Full Node Setup

This document describes how to set up a full Encointer node. A full node is a node that validates the entire blockchain history. Interacting with a full node you run yourself is the most secure and most privacy-preserving way to interact with the Encointer network.

## HW requirements

Full nodes can be run on very affordable HW. The minimum requirements are
* 1TB NVMe SSD
* 16GB RAM (8GB currently works, but is not recommended)
* CPU won't matter much, but go for maximum single-core performance rather than many cores.

## OS requirements

In the following, we'll assume you're using ubuntu 22.04

## Install dependencies

The recommended way to setup a full node is to start with the [ansible setup](https://github.com/w3f/polkadot-validator-setup) provided
by w3f.

Should you wish to do it manually, we'll redirect you to the polkadot docs
* [run a validator](https://wiki.polkadot.network/docs/maintain-guides-how-to-validate-polkadot)
* [secure validator](https://wiki.polkadot.network/docs/maintain-guides-secure-validator)

## systemd service

We assume you'd like to use your node for rpc queries from outside and monitor it with prometheus

```
[Unit]
Description=Encointer Kusama Collator
[Service]
User=encointer
Group=collators
ExecStart=/home/encointer/encointer-kusama/encointer-collator \
--rpc-cors all \
--name <a name that will appear in telemetry>> \
--telemetry-url 'wss://telemetry.polkadot.io/submit 1' \
--base-path <your large volume> \
--state-pruning archive \
--blocks-pruning archive \
--chain=encointer-kusama \
--rpc-methods=Unsafe \
--prometheus-external \
--enable-offchain-indexing true \
-- \
--sync=warp \
--chain kusama \
--prometheus-external \
--base-path <your large volume> \
Restart=always
RestartSec=60
[Install]
WantedBy=multi-user.target
```
4 changes: 4 additions & 0 deletions src/infrastructure.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Infrastructure

Encointer needs IT infrastructure to operate. All infrastructure can be run by anyone, thereby contributing to the network availability and decentralization.

0 comments on commit b6d6610

Please sign in to comment.