Signer State Backend

The signer state backend stores Containment Chamber control-plane state. It is separate from validator key storage and anti-slashing storage, even when all three use DynamoDB.

Use this page when enabling DynamoDB-backed keys, runtime auth policies and tokens, operator quorum seal/unseal, Nitro auto-unseal, or multiple signer replicas.

When You Need It

Deployment shape	State backend required?	Why
Filesystem-only signer with static auth	No	Keys and auth policy are loaded from local config at boot.
Runtime auth policies and tokens	Yes	Policy and token changes must survive restarts and propagate across replicas.
DynamoDB key source	Yes	The master key and operator ceremony state must survive restarts.
Operator quorum seal/unseal	Yes	Operator registration, encrypted shares, and quorum progress are persisted.
Nitro Enclave auto-unseal	Yes	The enclave auto-unseal blob and related state are stored here.
Multiple signer replicas	Yes for stateful features	Replicas use the backend to converge on seal state, auth changes, and rotation progress.

signer_state:
  backend: dynamodb
  table: containment-state
  refresh_interval_seconds: 1
  unseal_timeout_minutes: 30
  max_watcher_staleness_seconds: 3

Use a distinct DynamoDB table for signer state. Do not reuse the validator-key table or the anti-slashing table.

What It Stores

Data	Why it exists
Master-key metadata	KMS-wrapped Shamir shares and integrity data used during unseal
Operator quorum config	Operator names, threshold, and rotation staging
Operator credentials	Encrypted per-operator shares for passphrase or YubiKey unseal
Auth policies and tokens	Runtime access-control data
TEE auto-unseal blob	Nitro Enclave auto-unseal state

How It Differs From Other Storage

Storage	Holds	Used by
Key source	Validator private keys or encrypted key material	Signing and key-management operations
Signer state backend	Seal state, operator credentials, runtime auth records, and replica coordination state	Chamber control-plane operations
Anti-slashing backend	Slashing-protection history	Ethereum signing safety checks

The signer state backend does not store validator private keys. Those live in the configured key source. It does not store slashing-protection records. Those live in the anti-slashing backend.

Runtime Behavior

Every replica polls the state backend on signer_state.refresh_interval_seconds. That polling lets a fresh process observe:

• An initialization completed by another replica.
• KMS or TEE auto-unseal state.
• Auth policy and token changes.
• Quorum rotation progress.

Set the refresh interval low enough for operational changes to propagate at an acceptable speed. Avoid setting it to 0 in production unless you intentionally want to disable cross-replica refresh behavior.

signer_state.max_watcher_staleness_seconds (default 3) is a separate guard. If a replica’s watcher snapshot grows older than this bound — because the watcher stalls on a DynamoDB outage or a panic-recovery loop — the signing handler starts refusing requests with 503 rather than signing against possibly-stale seal state. refresh_interval_seconds sets how fast a replica observes a cluster-wide seal; max_watcher_staleness_seconds sets how fast signing fails if the watcher itself stops advancing. Set it to 0 to disable the freshness check.

Troubleshooting

Symptom	Check
Signer starts as uninitialized unexpectedly	The signer may be pointed at the wrong state table.
Auth edits do not propagate	Check refresh_interval_seconds and DynamoDB read permissions.
Unseal never reaches threshold	Confirm every operator credential row exists and belongs to the expected state table.
TEE auto-unseal never works	Confirm the TEE auto-unseal blob exists and that Nitro measurements still match.

Note

This page documents operator-facing behavior. Use the source code when changing row names or backend implementation details.

Next Steps

• DynamoDB Key Source — configure the key table that works alongside state
• Seal & Unseal Guide — run the operator ceremony that writes to the state backend
• Troubleshooting — diagnose state-backend propagation delays