Adding Collators - LibertyDSNP/frequency GitHub Wiki

We currently are only using "invulnerable" collators, however much of this will still apply when we switch to open collators sometime in 2023.

Key Structure

There are five keys that matter for a collator node:

1. The Networking Key
   • Collator: Can be auto-generated
   • Can be set via CLI with --node-key or --node-key-file, usually for public bootnodes
     • Remember that --node-key-file reads the file bytes, so do not have trailing new lines or other whitespace.
   • Used by libp2p for secure node communications and is the public key at the end of the node multiaddr
2. The Controller Account Key (Sometimes referred to as the Account ID)
   • Account used to control the collator
   • When an invulnerable collator, should be set as one of the "invulnerable keys"
3. The Invulnerable Address Key
   • The controller account's address
   • Must be added to the invulnerables using collatorSelection.setInvulnerables
4. The Stash Account Key (Sometimes referred to as the Validator ID)
   • Not used with collator selection
   • Should be the same as the controller account
5. The Session Aura Key
   • "Owned" by the the controller account
   • Does the actual work of signing blocks
   • Can be rotated by generating a new key on the node with author_rotateKeys, then calling session.setKeys from the controller account

Collator Setup

1. Create a new full node and match or exceed the official collator requirements
2. Download (or use docker) with use the most recent release from GitHub Releases
3. Remember that the node MUST be able to peer with others, but access to HTTP and WebSocket RPCs SHOULD be restricted.
   • Required flags
     • --collator Telling your node to run as a collator
   • Suggested Flags
     • --base-path Change where the data is stored
     • --name Name your node for easy discovery on https://telemetry.polkadot.io and https://telemetry.frequency.xyz
   • Situational Flags
     • Need to run author_rotateKeys or other protected calls, but no ability to originate HTTP calls from localhost. Port MUST be protected from the public Internet
       • --rpc-external External RPC calls accepted
       • --rpc-methods=Unsafe System commands like author_rotateKeys accepted externally
       • --rpc-port=9944 RPC port, 9944 is default
   • Example:

     ./frequency --collator --base-path=/data --name="FooBar Collator 42"
     
     

   • Additional flags are documented with --help
   • Flags applied after a -- are applied to built in relay chain node.
     • Example:

     ./frequency --collator -- --rpc-port=9945
     
     

4. Generate a new Controller Account aura key: subkey generate
   • If you want a password, you can add using subkey generate --password [password here]
5. Generate a new Session Key
   • Node Generated
     • Use author_rotateKey (localhost or "unsafe" RPC required)
     • Returns the new public key
   • Manually Generated via subkey generate
     • Add to the node with author_insertKey (localhost or "unsafe" RPC required)
6. Register a session key (Requires Tokens, send contact your Controller Account address to gain enough tokens to do this)
   • Submit the Extrinsic: session.setKeys
     • Sender: The Controller Account
     • keys: Address of the new Session Key
     • proof: 0x (Yes, it is empty)
   • New session keys do not become active until the next session (every ~6h)
   • It is also possible for your session key to match your Controller Account, but not suggested for production
7. Wait until the relay chain and parachain are up to date and synced
8. (Pre-Public Collator Registration)
   • Send the Controller Account Address to the Frequency Chain Governance
   • The Frequency Council will add your Controller Account Address to the list of invulnerables
9. Collator should begin collating about 6 hours after the on-chain governance approves
10. Request on the Frequency Discord to join the private collator channel for assistance (if not already invited).

Governance Steps

1. Once the Collator is setup, and the Controller Account Address is received
2. Set the new list of invulnerables:
   • Rococo (sudo)
     • sudo.sudo(call)
     • collatorSelection.setInvulnerables
       • SUPER IMPORTANT: List all current invulnerables
       • Add the new Controller Account Address to the end of the list
   • Mainnet (Frequency Council)
     • New Council motion
     • collatorSelection.setInvulnerables
       • SUPER IMPORTANT: List all current invulnerables
       • Add the new Controller Account Address to the end of the list
     • Passes with at least 3/5ths of the vote
     • Voting and passing
3. Wait until the next session (sessions are ~6 hours long)

End State

• Secure in a Wallet
  • Controller Keys
• Listed in the invulnerables
  • All controller addresses
• On a Collator
  • Session key registered to the controller address

Helpful Links and References

• https://wiki.polkadot.network/docs/maintain-guides-how-to-validate-polkadot#set-session-keys
• https://wiki.polkadot.network/docs/learn-keys

Detailed Key Generation

• Suggested: Subkey https://support.polkadot.network/support/solutions/articles/65000180519-how-to-create-an-account-in-subkey
  • macOS Prereq
    • rust https://rustup.rs/
    • protobuf brew install protobuf
• Alternatives: https://wiki.polkadot.network/docs/learn-account-generation

Curl command for inserting a new Session Key

Usually only used for changing servers or initial setup

Params:

• Key Type: "aura"
• Secret Phrase
• Hex Public Key

curl --location --request POST 'http://localhost:99' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "author_insertKey",
    "params": ["aura", "secret phrase would go here but this is not one", "0x4252d29a65087ceddb645ebac744628009b51c8e60fff750d99ba6ce1f1cf366"],
    "id": 1
}'

Curl command for rotating to a new Session Key

Returns the new public key that would be used for rotating the session key on chain

curl --location --request POST 'http://localhost:9944' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "author_rotateKeys",
    "params": [],
    "id": 1
}'

Curl command for testing that the node has a key

Params:

• Hex Public Key
• Key Type: "aura"

curl --location --request POST 'http://localhost:9944' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "author_hasKey",
    "params": ["0x4252d29a65087ceddb645ebac744628009b51c8e60fff750d99ba6ce1f1cf366", "aura"],
    "id": 1
}'

Troubleshooting

Logs

• -lcumulus-collator=trace Trouble with collating and forming blocks
• -lsync=trace Trouble with syncing and peers