Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

TMKMS for Celestia v10 and Fibre (SignRawBytes)

Latest Version Tag: v0.15.0

From app version 10, Celestia validators sign more than consensus messages. Fibre asks the validator to sign arbitrary bytes with the consensus key — payment-promise endorsements and the Fibre server's TLS identity. A remote signer therefore has to support the privval SignRawBytes request.

TMKMS added this in v0.15.0 ("Support for Celestia's extension to sign raw bytes with consensus keys", changelog). This page describes how VALIDEXIS runs TMKMS v0.15.0 with softsign for Celestia Mainnet Beta and Mocha, with Fibre on a separate server.

For a first TMKMS installation see TMKMS for Remote Signing. For upgrading an existing Celestia signer see TMKMS Update v0.15.0.

Requirements from Celestia

celestia-app v10.4.0 accepts any KMS that meets both requirements (release notes):

  1. Arbitrary-byte signing — the KMS supports privval SignRawBytes.

  2. Signing latency — median signing latency stays at or below 10 ms. The node exposes cometbft_privval_signing_latency_* metrics and logs a warning when the median of the last 50 signatures exceeds 10 ms.

KMS software is third-party; an incorrect setup can cause double signing and slashing. The procedures below are how we keep that risk controlled.

Signing path

Fibre ──privval gRPC (mTLS)──► Validator ──existing TMKMS connection──► TMKMS (softsign, LUKS)
          SignRawBytes                       forwards request                signs, returns
  • TMKMS dials the validator. The validator listens on priv_validator_laddr; TMKMS opens the secret connection and reconnects automatically. The signer exposes no listening service.

  • Fibre never connects to TMKMS. It talks to the validator's privval gRPC endpoint; the validator forwards SignRawBytes over the same TMKMS connection used for votes and proposals.

  • One key, one place. The consensus key exists online only on the signer.

Signer server

Item
Setting

Role

Dedicated server, one per network (Mainnet, Mocha)

Network

Private VLAN only; outbound connection to its validator; no inbound public services

Software

TMKMS v0.15.0, built with --features=softsign

Key storage

softsign key file on a LUKS-encrypted volume, mounted only on the signer

Access

Key-only SSH from admin addresses; no other users

Build

LUKS volume for keys and state

The key and the signing state live on an encrypted volume, separate from the OS disk:

The volume is unlocked by an operator after a reboot. The passphrase is never stored on the server.

Configuration

/srv/tmkms/celestia/tmkms.toml (Mainnet shown; Mocha uses mocha-5 and its own validator):

  • Pinning the validator's node ID in addr makes TMKMS verify the validator's identity on the secret connection.

  • state_file is the double-sign protection: TMKMS refuses to sign at a height/round/step lower than the last one it recorded. It must never be deleted or reset casually — see Key Custody and Signer Change.

Validator side

config/config.toml on the validator:

Firewall on the validator: 26658/tcp accepted only from the signer's VLAN address.

systemd

Requires=srv-tmkms.mount keeps TMKMS from starting before the encrypted volume is unlocked and mounted.

Verify

  1. Connection — TMKMS log shows the secret connection to the validator and signed votes:

  2. Latency — on the validator's Prometheus endpoint:

    Our target is below 5 ms; the Celestia requirement is 10 ms.

  3. Raw-byte signing — once Fibre is running, its startup log shows a successful TLS identity endorsement, and fibre.server.sign.duration reports successful payment-promise signatures.

  4. Failures — cometbft_privval_signing_failures_total stays flat.

Operating rules

  • One active signer per key. Never run two TMKMS instances, or TMKMS and a local priv_validator_key.json, for the same key at the same time.

  • Upgrade Mocha first. Every TMKMS change is applied to the Mocha signer before the Mainnet signer.

  • No automatic failover. softsign is not an HSM or a threshold cluster. Moving signing to another server is a manual, reviewed procedure.

  • Horcrux is part of our history (2025). Celestia's release notes describe it as under-maintained; our current setup uses TMKMS.

Sources

Last updated