author_rotateKeys - Kusama RPC Method

Generate a new set of session keys on Kusama. This method creates fresh cryptographic keys for all session key types (e.g., BABE, GRANDPA, ImOnline, ParaValidator, AuthorityDiscovery) and stores them in the node's local keystore. The returned concatenated public keys must be registered on-chain via session.setKeys.

Why Kusama? Build on Polkadot's canary network for real-world testing with live economic conditions with 7-day governance cycles (vs 1 month on Polkadot), lower bonding requirements, live KSM token economy, and first-to-market feature testing.

When to Use This Method

author_rotateKeys is critical for experimental dApp developers, parachain teams, and early adopters validating new features:

• Validator Setup — Generate initial session keys when setting up a new validator on parachain experimentation, early feature deployment, and production-grade testing with real value
• Key Rotation — Periodically rotate keys for operational security best practices
• Recovery — Generate replacement keys after a potential key compromise or node migration
• Validator Upgrades — Produce new keys when moving a validator to new hardware

Code Examples

Common Use Cases

1. Complete Validator Setup Workflow

Full end-to-end validator setup on Kusama:

async function setupValidator(api, stashAccount) {
  // Step 1: Generate session keys
  const keys = await api.rpc.author.rotateKeys();
  console.log('Generated session keys:', keys.toHex());

  // Step 2: Register keys on-chain
  const setKeysTx = api.tx.session.setKeys(keys, '0x');
  await new Promise((resolve, reject) => {
    setKeysTx.signAndSend(stashAccount, ({ status, events }) => {
      if (status.isFinalized) {
        const success = events.some(({ event }) =>
          api.events.system.ExtrinsicSuccess.is(event)
        );
        if (success) {
          console.log('Session keys registered successfully');
          resolve();
        } else {
          reject(new Error('setKeys transaction failed'));
        }
      }
    });
  });

  // Step 3: Verify registration
  const nextKeys = await api.query.session.nextKeys(stashAccount.address);
  console.log('Keys registered for next session:', nextKeys.isSome);
}

2. Scheduled Key Rotation

Automate periodic key rotation for security:

async function scheduleKeyRotation(api, validatorAccount, intervalDays = 30) {
  const intervalMs = intervalDays * 24 * 60 * 60 * 1000;

  async function rotateAndRegister() {
    try {
      const newKeys = await api.rpc.author.rotateKeys();
      console.log(`Rotated keys at ${new Date().toISOString()}`);

      const tx = api.tx.session.setKeys(newKeys, '0x');
      await tx.signAndSend(validatorAccount);
      console.log('New keys registered — active next session');
    } catch (error) {
      console.error('Key rotation failed:', error.message);
    }
  }

  // Initial rotation
  await rotateAndRegister();

  // Schedule future rotations
  setInterval(rotateAndRegister, intervalMs);
}

Validator Setup Workflow

1. Generate keys — Call author_rotateKeys on your validator node
2. Register on-chain — Submit session.setKeys(keys, proof) extrinsic from your stash account
3. Wait for session — Keys become active at the start of the next session
4. Verify — Query session.nextKeys to confirm registration

Security Considerations

• Local access only — Only call this method on your own validator node via localhost
• Never expose publicly — This RPC method is marked as unsafe and should not be accessible from the internet
• Keystore security — Session keys are stored in the node's keystore directory on disk
• Rotate regularly — Follow a key rotation schedule to limit exposure from potential compromises
• Backup awareness — New keys replace old ones in the keystore; old keys cannot be recovered

Error Handling

Related Methods

• author_hasSessionKeys — Check if session keys exist in the keystore
• author_submitExtrinsic — Submit the setKeys transaction
• author_pendingExtrinsics — View pending transactions
• session_nextKeys — Query registered session keys on-chain