Skip to content

Adding Collators

Jump to bottom
Wil Wade edited this page Nov 10, 2022 · 21 revisions

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_rotateKey, 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. Remember that the node should be able to peer with others, but access to HTTP and WebSocket RPCs should be restricted
  3. Wait until the relay chain and parachain are up to date and synced
  4. Generate a new Controller Account aura key: subkey generate
    • If you want a password, you can add that subkey generate --password [password here]
  5. Generate a new Session Key
    • Node Generated
      • Use author_rotateKey ("unsafe" RPC required)
      • Returns the new public key
    • Manually Generated via subkey generate
      • Add to the node with author_insertKey ("unsafe" RPC required)
  6. Register a session key
    • 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

Chain Setup

  1. Once the Collator is setup, take the Controller Account Address
  2. Set the new list of invulnerables:
    • Sudo (Rococo, Mainnet for now)
      • sudo.sudo(call)
      • collatorSelection.setInvulnerables
        • SUPER IMPORTANT: List all current invulnerables
        • Add the new Controller Account Address to the end of the list
    • Frequency Council (Mainnet)
      • 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

Detailed Key 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://locahost:9933' \
--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://locahost:9933' \
--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://locahost:9933' \
--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
Clone this wiki locally