Skip to main content
Version: Ignition (v2.1.9)

Key storage methods

Overview​

The keystore supports four methods for storing and accessing private keys. These methods can be mixed within a single configuration.

Private keys (inline)​

The simplest method is to include private keys directly in the keystore. The validator-keys new command generates keystores in this format by default:

{
  "schemaVersion": 1,
  "validators": [
    {
      "attester": {
        "eth": "0xef17bcb86452f3f6a73678c01bee757e9d46d1cd0050f043c10cfc953b17bad2",
        "bls": "0x20f2f5989b66462b39229900948c7846403768fec5b76d1c2937d64e04aac4b9"
      },
      "feeRecipient": "0x0000000000000000000000000000000000000000000000000000000000000000"
    }
  ]
}

Note that the attester field now contains both Ethereum (eth) and BLS (bls) private keys. Both are required for sequencer operation.

Not for Production Use

Inline private keys are convenient for testing but should be avoided in production. Use remote signers or encrypted keystores for production deployments.

Remote signers (Web3Signer)​

Remote signers keep private keys in a separate, secure signing service. This is the recommended approach for production environments for Ethereum keys.

The keystore supports Web3Signer endpoints for Ethereum keys. The keystore automatically detects whether a value is a private key or an address based on string length:

  • 66 characters (0x + 64 hex characters): Interpreted as a private key (stored inline)
  • 42 characters (0x + 40 hex characters): Interpreted as an address and uses the nearest remoteSignerUrl
BLS Keys Do Not Support Remote Signers

BLS keys must always be stored as private keys directly in the keystore. The keystore does not check remoteSignerUrl for BLS keys. Web3Signer's BLS support is designed for Ethereum consensus layer operations and is not compatible with Aztec's BLS key requirements.

Remote signers can be configured at three levels:

Global level (applies to all ETH keys):

{
  "schemaVersion": 1,
  "remoteSigner": "https://signer.example.com:8080",
  "validators": [
    {
      "attester": {
        "eth": "0x1234567890123456789012345678901234567890",
        "bls": "0x20f2f5989b66462b39229900948c7846403768fec5b76d1c2937d64e04aac4b9"
      },
      "feeRecipient": "0x1234567890123456789012345678901234567890123456789012345678901234"
    }
  ]
}

In this example, the Ethereum attester address (42 characters) is managed by the remote signer, while the BLS key (66 characters) is a private key stored directly in the keystore.

Validator (sequencer) block level (applies to all ETH keys in a sequencer configuration):

{
  "schemaVersion": 1,
  "validators": [
    {
      "attester": {
        "eth": "0x1234567890123456789012345678901234567890",
        "bls": "0x20f2f5989b66462b39229900948c7846403768fec5b76d1c2937d64e04aac4b9"
      },
      "feeRecipient": "0x1234567890123456789012345678901234567890123456789012345678901234",
      "remoteSigner": "https://signer.example.com:8080"
    }
  ]
}

Account level (applies to a specific ETH key):

{
  "schemaVersion": 1,
  "validators": [
    {
      "attester": {
        "eth": {
          "address": "0x1234567890123456789012345678901234567890",
          "remoteSignerUrl": "https://signer.example.com:8080"
        },
        "bls": "0x20f2f5989b66462b39229900948c7846403768fec5b76d1c2937d64e04aac4b9"
      },
      "feeRecipient": "0x1234567890123456789012345678901234567890123456789012345678901234"
    }
  ]
}

Client certificate authentication​

For remote signers requiring client certificates:

{
  "schemaVersion": 1,
  "remoteSigner": {
    "remoteSignerUrl": "https://signer.example.com:8080",
    "certPath": "/path/to/client-cert.p12",
    "certPass": "certificate-password"
  },
  "validators": [...]
}

JSON V3 encrypted keystores​

JSON V3 keystores provide standard Ethereum-compatible encrypted key storage.

Single file:

{
  "schemaVersion": 1,
  "validators": [
    {
      "attester": {
        "path": "/path/to/keystore.json",
        "password": "keystore-password"
      },
      "feeRecipient": "0x1234567890123456789012345678901234567890123456789012345678901234"
    }
  ]
}

Directory of keystores:

{
  "schemaVersion": 1,
  "validators": [
    {
      "attester": {
        "eth": "0x1234567890123456789012345678901234567890123456789012345678901234",
        "bls": "0x2345678901234567890123456789012345678901234567890123456789012345"
      },
      "publisher": {
        "path": "/path/to/keystores/",
        "password": "shared-password"
      },
      "feeRecipient": "0x1234567890123456789012345678901234567890123456789012345678901234"
    }
  ]
}

All .json files in the directory will be loaded using the provided password.

Mnemonics (BIP44 derivation)​

Mnemonics derive multiple keys from a single seed phrase using BIP44 paths.

Single key (default path m/44'/60'/0'/0/0):

{
  "schemaVersion": 1,
  "validators": [
    {
      "attester": {
        "eth": "0x1234567890123456789012345678901234567890123456789012345678901234",
        "bls": "0x2345678901234567890123456789012345678901234567890123456789012345"
      },
      "publisher": {
        "mnemonic": "test test test test test test test test test test test junk"
      },
      "feeRecipient": "0x1234567890123456789012345678901234567890123456789012345678901234"
    }
  ]
}

Multiple sequential keys:

{
  "publisher": {
    "mnemonic": "test test test test test test test test test test test junk",
    "addressCount": 4
  }
}

Generates 4 keys at paths m/44'/60'/0'/0/0 through m/44'/60'/0'/0/3.

Custom derivation paths:

{
  "publisher": {
    "mnemonic": "test test test test test test test test test test test junk",
    "accountIndex": 5,
    "addressIndex": 3,
    "addressCount": 2
  }
}
Not for Production Use

Mnemonics are convenient for testing but should be avoided in production. Use remote signers or encrypted keystores for production deployments.

Next steps​