Skip to content

Adding Collators

Jump to bottom
Wil Wade edited this page Oct 23, 2024 · 21 revisions

Collator Status

  • Mainnet
    • Incentive: None Currently
    • Approval Requirements: Frequency Council Approval
  • Testnet
    • Incentive: None
    • Approval Requirements: None

Key Structure

There are five keys that matter for a collator node:

  1. The Networking Key
    • Collator: Auto-generated default is OK
    • 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"
    • Needs some tokens to call session.setKeys and collatorSelection.registerAsCandidate
  3. The Stash Account Key (Sometimes referred to as the Validator ID)
    • Only used with incentives
    • Can be the same as the controller account
  4. 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
    • Does NOT need tokens

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
    • Make sure to download the correct binary/docker image. Different binaries are generated for Mainnet, Testnet, and Local development.
  3. Remember that the node MUST be able to peer with others, but access to HTTP and WebSocket RPCs SHOULD be restricted.
    • Required flags
      • --validator Telling your node to run as a collator
    • Suggested Flags
    • 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)
    • Testnet: Get tokens from the Testnet Faucet: https://faucet.testnet.frequency.xyz
    • 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. Becoming Live
    • Mainnet
      • Send the Controller Account Address to the Frequency Chain Governance
      • The Frequency Council will add your Controller Account Address to the list of invulnerables
      • See below for more details on the Governance actions
    • Testnet
      • Call Extrinsic: collatorSelection.registerAsCandidate()
  9. Collator should begin collating about 6 hours after the registration / approval.
  10. Request on the Frequency Discord to join the private collator channel for assistance (if not already invited).

Mainnet: Steps for Governance

  1. Setup the Collator using a Mainnet binary
  2. Send the Controller Account Address to someone on the Frequency Council
  3. Frequency Council must pass a motion to add the new collator:
    • Council Member should go to the motions for the council on Polkadotjs
    • Select "Propose Motion"
    • Motion is collatorSelection.addInvulnerable
      • Parameter: the new Controller Account Address
    • Default threshold is fine (Passes with at least 3/5ths of the vote)
    • Motion creator should visit Polkassembly Motions and update the motion with the information of who the new collator is.
    • Voting and enacting
  4. Wait until the next session (sessions are ~6 hours long)

Mainnet 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://localhost:9944' \
--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

Common Logs

  • -lcumulus-collator=trace Trouble with collating and forming blocks
  • -lsync=trace Trouble with syncing and peers
Clone this wiki locally