Skip to content

storage-methods.md

Latest commit

 

History

History
226 lines (184 loc) · 6.48 KB

storage-methods.md

File metadata and controls

226 lines (184 loc) · 6.48 KB
Raw
title Key storage methods
description Learn about different methods for storing and accessing private keys in Aztec keystores, including inline keys, remote signers, JSON V3 keystores, and mnemonics.
displayed_sidebar operatorsSidebar

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.

:::warning 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

:::warning 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
  }
}

:::warning 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