Skip to content

Session keys ​

Session keys sign blocks. They are not the stash account. The stash holds the bond and pays; the keys live only on the node. Rotating keys does not move funds.

Figures below were measured on a local node (2026-10-26) and against the live testnet. This is not copied from generic Substrate docs.

1. Generate on your own node ​

Do not generate keys on someone else’s node. The private material stays where it is created.

The RPC is unsafe on purpose. Enable it on localhost only:

sh
empoorio-node --base-path /path/to/data --rpc-port 9944 --rpc-methods unsafe

Then, on the same machine:

sh
curl -s -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"author_rotateKeys","params":[]}' \
  http://127.0.0.1:9944

--rpc-methods unsafe does not leave localhost. Anyone who can reach the port can call author_rotateKeys or author_insertKey. Public testnet RPC runs Safe and rejects these methods.

Return value: 128 hex characters = 64 bytes = two keys of 32. Aura (authoring) and GRANDPA (finality). Those 64 bytes are public. They go on chain in step 3. The secret never leaves the node.

2. Check the node has them before registering ​

sh
curl -s -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"author_hasSessionKeys","params":["0x<128 hex>"]}' \
  http://127.0.0.1:9944

Must return true. false means you registered keys this node cannot use: you produce no blocks.

  • Wrong length → "Session keys are not encoded correctly" (code 1040), not false.
  • On disk: <base-path>/chains/<network>/keystore/. First 8 hex chars of the filename: 61757261 = "aura", 6772616e = "gran". If only one file exists, a key is missing.

3. Register on chain ​

From the stash account: session.setKeys(keys, proof) with keys = the 64 bytes and proof empty (0x).

The stash signs this, not the node. The account needs funds. Today an external validator stalls here: bond is 50,000 DRACMA, genesis dust is 10,000.

Against the public RPC, pass the stash as prefix 42 or hex. See Accounts and SS58.

4. Check storage, not logs ​

The node log says what the node believes. Storage says what the chain stores.

Measured on the live testnet 2026-10-26:

StorageWhat it hadMeaning
Session.Validators2in session now
Session.NextKeys2 entriesone per validator; your account appears here after setKeys
Session.QueuedKeys193 byteskeys that enter next session
Session.CurrentIndex4 bytes (u32)session number

193 bytes is the arithmetic check that keys are 64 bytes: 2 validators × (32 account + 64 keys) + 1 compact prefix = 193. That kills the rumour of a third session key.

Storage key: twox128("Session") || twox128("NextKeys"). twox128 must be little-endian. A big-endian digest returns empty storage with no error.

Vectors: docs/03_DEVELOPMENT/vectores_conformidad.json in the node repo.

5. Rotate ​

Same procedure: author_rotateKeys replaces keys on disk; a new setKeys announces them. They enter the next session, not instantly. One session = 2,400 blocks = 4 hours.

English technical docs. Marketing lives at empooriochain.com.