Creating Sequencer Keystores

Overview

Keystores are configuration files that store the cryptographic keys and addresses your sequencer node needs to operate on the Aztec network. This guide shows you how to create keystores using the Aztec CLI's validator-keys commands.

A keystore contains:

• Attester keys: Your sequencer's identity (Ethereum and BLS keys for signing proposals and attestations)
• Publisher keys: Keys used to submit blocks to L1 (requires ETH for gas)
• Fee recipient: Aztec address for L2 transaction fees (currently not used)
• Coinbase address: Ethereum address receiving L1 block rewards (optional, defaults to attester address)

Prerequisites

Before creating keystores, ensure you have:

• Basic understanding of Ethereum addresses and private keys
• Access to an Ethereum L1 RPC endpoint
• Foundry toolkit installed (for creating publisher addresses)

Installing the Aztec CLI

First, install the Aztec CLI using the official installer:

VERSION=6.0.0 bash -i <(curl -sL https://install.aztec.network/6.0.0)

Verify your CLI installation:

aztec --version

Recommended Setup: Multiple Validators with Shared Publisher

This approach creates multiple sequencer identities (validators) that share a single publisher address for submitting transactions to L1. This is the recommended configuration for production deployments.

Step 1: Create Publisher Address and Set RPC Endpoint

First, set your Ethereum mainnet L1 RPC endpoint:

export ETH_RPC=https://ethereum-rpc.publicnode.com

Or use your preferred Ethereum RPC provider (Infura, Alchemy, etc.).

Then generate a separate address for publishing transactions to L1 using the Foundry toolkit:

cast wallet new-mnemonic --words 24

Example output:

Successfully generated a new mnemonic.
Phrase:
word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 word16 word17 word18 word19 word20 word21 word22 word23 word24

Accounts:
- Account 0:
Address:     0xE434A95e816991E66bF7052955FD699aEf8a286b
Private key: 0x7988a4a7...79f058a0

Critical: Save Your Publisher Mnemonic

The 24-word mnemonic is the only way to recover your publisher private key. Store it securely offline (not on the server running the node).

Save from the output:

• ✅ The 24-word mnemonic (for recovery)
• ✅ The private key (you'll use this in the next step)
• ✅ The address (you'll fund this with ETH)

Step 2: Generate Your Keystores with Publisher

Generate 5 validators with the publisher private key from Step 1:

aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xa92ecFD0E70c9cd5E5cd76c50Af0F7Da93567a4f \
  --l1-rpc-urls $ETH_RPC \
  --count 5 \
  --publishers 0x7988a4a779f058a0

Replace 0x7988a4a779f058a0 with your actual publisher private key from Step 1.

What this command does:

• Generates a new mnemonic for your validator keys (save this securely!)
• Creates 5 sequencer identities (validators) with Ethereum and BLS keys
• Configures all validators to use the same publisher address for L1 submissions
• Generates public keystore data for the staking dashboard
• Saves files to ~/.aztec/keystore/

Example output:

No mnemonic provided, generating new one...
Using new mnemonic:

absent city nephew garment million badge front text memory grape two lizard

Wrote validator keystore to /Users/your-name/.aztec/keystore/key1.json
Wrote staker output for 5 validator(s) to /Users/your-name/.aztec/keystore/key1_staker_output.json

acc1:
  attester:
    eth: 0x8E76a8B8D66E0A56E241F2768fD2ad4eba07E565
    bls: 0x29eaf46e4699e33a1abe7300258567c624a7304a2134e31aa2609437f281d81d
  publisher:
    - 0x7988a4a779f058a0
acc2:
  attester:
    eth: 0x2037b472537a4246B1A7325f327028EF450ba0Ef
    bls: 0x8d7eb7d9436ac6cb9b8f1c211673ea228c7f438882e6438b2caefca753df28e8
  publisher:
    - 0x7988a4a779f058a0
acc3:
  attester:
    eth: 0x0c14593f7465DeDbb86d68982374BB05F4C60386
    bls: 0xad1cccf512d2f180238af795831344445f7ac47e2d623f3dac854e93e5b1e76d
  publisher:
    - 0x7988a4a779f058a0
acc4:
  attester:
    eth: 0x4D213928988f0123f6b3B4A377F856812F08E831
    bls: 0xa90f5889dddd4cd6bc5a28db5e0db60d3cbf5147eb6e82b313024b2d0634110e
  publisher:
    - 0x7988a4a779f058a0
acc5:
  attester:
    eth: 0x29f147Da38d5F66bB84e791969b365c796829c92
    bls: 0x0d683001c2ce866e322f0c7509f087a909508787d125336931aa9168d2a1f95b
  publisher:
    - 0x7988a4a779f058a0

Note: The publisher value shown is the private key (truncated in this example). All validators share the same publisher private key.

Staker outputs:
[
  {
    "attester": "0x8E76a8B8D66E0A56E241F2768fD2ad4eba07E565",
    "publicKeyG1": { "x": "0x...", "y": "0x..." },
    "publicKeyG2": { "x0": "0x...", "x1": "0x...", "y0": "0x...", "y1": "0x..." },
    "proofOfPossession": { "x": "0x...", "y": "0x..." }
  },
  ... (4 more validators)
]

Critical: Save Both Mnemonics

You now have two separate mnemonics to secure:

1. Validator mnemonic (shown above, 12 words) - Regenerates your attester keys
2. Publisher mnemonic (from Step 1, 24 words) - Regenerates your publisher key

Both must be stored securely offline. Losing either mnemonic means losing access to those keys.

Files created:

• ~/.aztec/keystore/key1.json - Private keystore with all 5 validators and publisher configured
• ~/.aztec/keystore/key1_staker_output.json - Public keystore for staking dashboard

Step 3: Fund the Publisher Address

Your publisher address needs ETH to pay for L1 gas when submitting proposals.

Funding requirement: At least 0.3 ETH for 5 validators (rule of thumb: 0.1 ETH per validator)

Transfer ETH to the publisher address from Step 1. You can check the balance with:

cast balance 0xE434A95e816991E66bF7052955FD699aEf8a286b --rpc-url $ETH_RPC

Replace the address with your actual publisher address.

Monitor Publisher Balance

Set up monitoring to alert when the publisher balance falls below 0.5 ETH to prevent failed block publications.

Step 4: Upload Keystore to Your Node

Now you're ready to spin up your sequencer node!

Upload the private keystore to your server:

The key1.json file contains your private keys and must be uploaded to your sequencer node.

For standard server deployments:

# Upload to your server's keystore directory
scp ~/.aztec/keystore/key1.json user@your-server:/path/to/aztec-sequencer/keys/keystore.json

For dAppNode deployments:

• Upload key1.json to the dAppNode keystore folder
• Rename it to keystore.json

Keep the Public Keystore Local

Keep key1_staker_output.json on your local machine - you'll need it for registration on the staking dashboard. Do not upload this to your server.

Step 5: Start Your Node

Start your sequencer node following the Sequencer Setup guide.

When your node starts successfully, you'll see output similar to:

Started validator with addresses: 0x8E76a8B8D66E0A56E241F2768fD2ad4eba07E565, 0x2037b472537a4246B1A7325f327028EF450ba0Ef, 0x0c14593f7465DeDbb86d68982374BB05F4C60386, 0x4D213928988f0123f6b3B4A377F856812F08E831, 0x29f147Da38d5F66bB84e791969b365c796829c92

These are your validator attester addresses - they match the addresses shown when you generated your keys.

Step 6: Register Your Validators

Use the public keystore (key1_staker_output.json) to register your validators on the staking dashboard. See Registering a Sequencer for details.

---

Quick Setup Summary

By following the recommended setup, you've accomplished:

✅ Generated a dedicated publisher address with its own 24-word mnemonic ✅ Created 5 validator identities with a separate 12-word mnemonic ✅ Configured all validators to use the shared publisher for L1 transactions ✅ Funded the publisher with at least 0.3 ETH for gas costs ✅ Uploaded the private keystore (key1.json) to your sequencer node ✅ Started your node and verified validator addresses in the output ✅ Ready to register using the public keystore (key1_staker_output.json)

Two mnemonics to keep secure:

1. Publisher mnemonic (24 words) - Recovers publisher private key
2. Validator mnemonic (12 words) - Recovers all 5 validator attester keys

Alternative: Single Validator Setup

For testing or simpler setups, you can create a single validator that uses its attester key as the publisher.

Basic Single Validator

aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xa92ecFD0E70c9cd5E5cd76c50Af0F7Da93567a4f \
  --l1-rpc-urls $ETH_RPC

This creates:

• One validator with attester keys
• No separate publisher (attester key used for publishing)
• Private keystore at ~/.aztec/keystore/keyN.json
• Public keystore at ~/.aztec/keystore/keyN_staker_output.json

When to Use Single Validator

Use single validator setup for:

• Testing and development
• Simple deployments with one sequencer identity
• When you don't need to isolate attester and publisher keys

Understanding Keystore Structure

Private Keystore Format

The private keystore (key1.json) contains sensitive private keys:

{
  "schemaVersion": 1,
  "validators": [
    {
      "attester": {
        "eth": "0x...",  // Ethereum private key - sequencer identifier
        "bls": "0x..."   // BLS private key - signs proposals and attestations
      },
      "publisher": ["0x..."],  // Publisher private key(s) for L1 submissions
      "feeRecipient": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "coinbase": "0x..."  // Optional: custom address for L1 rewards
    }
  ]
}

Field descriptions:

• attester.eth: Derives the address that serves as your sequencer's unique identifier
• attester.bls: Signs proposals and attestations, used for staking operations
• publisher: Array of private keys for submitting signed messages to L1 (pays gas)
• feeRecipient: L2 fee recipient (not currently used, set to all zeros)
• coinbase: L1 block reward recipient (optional, defaults to attester address)

Public Keystore Format

The public keystore (key1_staker_output.json) contains only public information safe to share:

[
  {
    "attester": "0xYOUR_ATTESTER_ADDRESS",
    "publicKeyG1": {
      "x": "0x...",
      "y": "0x..."
    },
    "publicKeyG2": {
      "x0": "0x...",
      "x1": "0x...",
      "y0": "0x...",
      "y1": "0x..."
    },
    "proofOfPossession": {
      "x": "0x...",
      "y": "0x..."
    }
  }
]

This file is used for registration on the staking dashboard and contains no private keys.

Advanced Options

Providing Your Own Mnemonic

For deterministic key generation or to recreate keys from an existing mnemonic:

aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xa92ecFD0E70c9cd5E5cd76c50Af0F7Da93567a4f \
  --l1-rpc-urls $ETH_RPC \
  --mnemonic "your existing twelve word mnemonic phrase here" \
  --count 5 \
  --publishers 0x7988a4a779f058a0

This regenerates the same validators if you've used this mnemonic before, or creates new ones at the next derivation indices.

BLS Keys and the Proof-of-Possession Gas Cap

When a validator registers, L1 checks the proof of possession of its BLS key within a fixed gas cap. The cost of that check depends on the key, and for a small fraction of keys it could exceed the cap, so those keys could never register. aztec validator-keys new, aztec validator-keys add and aztec generate-bls-keypair estimate that cost for every BLS key they derive, locally and without RPC calls. The v6 upgrade sets the GSE's proofOfPossessionGasLimit to 300,000 gas, and the default budget is 270,000 gas, that cap minus a 10% margin. About 1 key in 170,000 estimates over the budget:

• No flag: the command keeps the key at the usual derivation path. If its check could exceed the gas cap, the command stops with an error before writing anything and suggests one of the flags below. If the command generated and printed the mnemonic itself, re-running without --mnemonic generates a new one; pass the mnemonic back with --mnemonic to keep it.
• --bls-key-derivation-v6: a key whose check could exceed the gas cap is replaced by the next candidate, derived from the same mnemonic at <path>/1, <path>/2, and so on, until one fits. Keys that already fit are unchanged, and the ETH attester and publisher keys never change.
• --bls-key-derivation-max-gas <gas>: a stricter budget of your choice, between 137,790 (the lowest estimate any key can have) and 270,000. With --bls-key-derivation-v6, candidates are tried until one fits this budget; without it, a key over the budget is an error.
• --skip-bls-key-gas-check: the command keeps the key at the usual path without checking it. Use this to regenerate a key created by an earlier CLI version, for example one that is already registered. You cannot combine it with --bls-key-derivation-v6 or --bls-key-derivation-max-gas.

When a key comes from a candidate other than 0, the summary shows its full derivation path, for example bls derivation path: m/12381/3600/0/0/384795/1 (candidate 1), followed by the max gas when --bls-key-derivation-max-gas was set. With --json, the output lists these keys under blsKeyCandidates. Encrypted BLS keystore files record the derivation path of each key the command derived in their path field. When aztec validator-keys add --password encrypts plaintext BLS keys that were already in the keystore, it cannot know where they came from, so it leaves their path empty.

Governance can change proofOfPossessionGasLimit at any time. aztec validator-keys staker and aztec validator-keys new --staker-output read the current value from the GSE and stop with an error naming every attester whose BLS key is estimated to need more gas, before writing any output. To replace those BLS keys, regenerate the validators with aztec validator-keys new, the same mnemonic or IKM and indices, and --bls-key-derivation-v6. If the current limit minus 10% is below 270,000, also pass --bls-key-derivation-max-gas set to that value. The error names the exact flags.

Regenerating keys

To regenerate keys from your mnemonic, run the command with the same --bls-key-derivation-v6 and --bls-key-derivation-max-gas values you used to create them. A different max gas can select a different candidate. Without --bls-key-derivation-v6, the command stops with an error for a key that came from a later candidate; with --skip-bls-key-gas-check, it returns the original candidate 0 key instead.

Custom Output Location

Specify custom directory and filename:

aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xa92ecFD0E70c9cd5E5cd76c50Af0F7Da93567a4f \
  --l1-rpc-urls $ETH_RPC \
  --count 5 \
  --publishers 0x7988a4a779f058a0 \
  --data-dir ~/my-sequencer/keys \
  --file sequencer1.json

This creates keystores at:

• ~/my-sequencer/keys/sequencer1.json (private keystore)
• ~/my-sequencer/keys/sequencer1_staker_output.json (public keystore)

Default behavior (if you don't specify --data-dir or --file):

• Directory: ~/.aztec/keystore/
• Filename: key1.json, key2.json, etc. (auto-increments)

Encrypted Keystore Passwords

Use --password, --password-file, or AZTEC_KEYSTORE_PASSWORD to write encrypted ETH JSON V3 and BLS EIP-2335 keystore files with a shared password. To use different passwords, provide role-specific sources such as --eth-password and --bls-password.

export AZTEC_KEYSTORE_PASSWORD='your-secure-password'
aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --count 5 \
  --publishers 0x7988a4a779f058a0 \
  --encrypted-keystore-dir ~/.aztec/keystore/encrypted

For each key type, role-specific sources take precedence over shared sources: --eth-password, --eth-password-file, and AZTEC_ETH_KEYSTORE_PASSWORD for ETH keystores; --bls-password, --bls-password-file, and AZTEC_BLS_KEYSTORE_PASSWORD for BLS keystores. Shared sources use --password, --password-file, then AZTEC_KEYSTORE_PASSWORD. Passwords cannot be empty. When the command generates a mnemonic while writing encrypted keystores, it does not print the mnemonic to stdout; provide --mnemonic if you need deterministic recovery.

Verifying Your Keystore

Verify the keystore is valid JSON:

cat ~/.aztec/keystore/key1.json | jq .

Check validator count:

jq '.validators | length' ~/.aztec/keystore/key1.json

Verify BLS keys are present:

jq '.validators[0].attester.bls' ~/.aztec/keystore/key1.json

Extract attester addresses:

# Get attester ETH private key (to derive address)
jq -r '.validators[0].attester.eth' ~/.aztec/keystore/key1.json

Troubleshooting

If you encounter issues during keystore creation or management, see the Troubleshooting and Best Practices Guide for:

• Keystore creation issues (RPC, permissions, invalid JSON, legacy BLS keys)
• Runtime and operational issues (node startup, remote signers, nonce conflicts)
• Comprehensive security best practices
• Complete CLI reference

Next Steps

Now that you've created your keystores:

For Sequencer Operators

1. Fund publisher addresses - At least 0.1 ETH per validator
2. Set up your node - See Sequencer Management
3. Register validators - Use the public keystore with the staking dashboard
4. Monitor operations - Track attestations and publisher balance

Advanced Configurations

• Advanced Keystore Patterns - Multiple validators, high availability, remote signers
• Key Storage Methods - Encrypted keystores, HSMs, key management systems
• Troubleshooting and Best Practices - Common issues, security best practices, and CLI reference

Getting Help

• Review the Operator FAQ for common questions
• Join the Aztec Discord for operator support
• Check the CLI reference for all available commands