Filesystem Keystores

Containment Chamber loads validator keys from YAML descriptor files placed in one or more directories. Each .yaml file describes a single key, either as a raw hex secret or a reference to an encrypted EIP-2335 keystore.

Both formats are Web3Signer-compatible. If you already have EIP-2335 keystores from another signer, you just need to create the YAML descriptors alongside them.

Directory Structure

Point key_sources.filesystem.paths at one or more directories. Containment Chamber scans each directory for .yaml files at startup:

key_sources:
  filesystem:
    paths:
      - /var/lib/containment-chamber/keystores
      - /var/lib/containment-chamber/more-keystores

A typical directory looks like this:

/var/lib/containment-chamber/keystores/
├── 5d79146c...373c.yaml          # raw key descriptor
├── 93695ab2...044d.yaml          # encrypted key descriptor
├── 93695ab2...044d.json          # EIP-2335 keystore (PBKDF2 or Scrypt)
└── 93695ab2...044d.password      # plaintext password file

Files are matched by the YAML descriptor, not by filename. You can name files however you want, but the convention is to use the validator’s public key (96-char hex, no 0x prefix) as the base name.

Key Formats

The simplest format. The private key is stored directly in the YAML file as a 64-character hex string (no 0x prefix):

type: "file-raw"
keyType: "BLS"
privateKey: "5d79146c27a33cea86a97080f377c2f5eef0e3fdbdc4436b82f8d23abc7a373c"

One file, no dependencies. Good for development, testing, or environments where secrets are injected into the filesystem by an external tool (Vault, Kubernetes secrets, etc.).

References an EIP-2335 keystore encrypted with PBKDF2. You need three files:

Descriptor (93695ab2...044d.yaml):

type: "file-keystore"
keyType: "BLS"
keystoreFile: "93695ab2...044d.json"
keystorePasswordFile: "93695ab2...044d.password"

Keystore (93695ab2...044d.json): Standard EIP-2335 JSON keystore with "function": "pbkdf2" KDF.

Password (93695ab2...044d.password): Plaintext file containing the keystore password.

The keystoreFile and keystorePasswordFile paths are relative to the directory containing the YAML descriptor.

Same structure as PBKDF2, but the EIP-2335 keystore uses Scrypt as the key derivation function:

Descriptor (a267d0fb...a163.yaml):

type: "file-keystore"
keyType: "BLS"
keystoreFile: "a267d0fb...a163.json"
keystorePasswordFile: "a267d0fb...a163.password"

Keystore (a267d0fb...a163.json): Standard EIP-2335 JSON keystore with "function": "scrypt" KDF.

Password (a267d0fb...a163.password): Plaintext file containing the keystore password.

Scrypt is more memory-hard than PBKDF2, which provides stronger brute-force resistance. The tradeoff is slower decryption at startup.

Migrating from Web3Signer

If you’re coming from Web3Signer, your existing EIP-2335 keystores work without modification. Create a YAML descriptor for each keystore:

type: "file-keystore"
keyType: "BLS"
keystoreFile: "my-validator.json"
keystorePasswordFile: "my-validator.password"

Drop the descriptor alongside your existing .json and .password files, point key_sources.filesystem.paths at the directory, and you’re done.

Runtime Key Management

You can also import and remove EIP-2335 keystores at runtime through the Key Manager API (/eth/v1/keystores) without restarting the signer. Keys imported this way are persisted to the first key_sources.filesystem.paths directory. See the API Reference for details.