> For the complete documentation index, see [llms.txt](https://services.validexis.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://services.validexis.com/validator-security-our-approach-and-protection-measures/tmkms-for-remote-signing/tmkms-for-celestia-v10-and-fibre.md).

# 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](https://github.com/iqlusioninc/tmkms/blob/main/CHANGELOG.md)). 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](https://services.validexis.com/validator-security-our-approach-and-protection-measures/tmkms-for-remote-signing). For upgrading an existing Celestia signer see [TMKMS Update v0.15.0](https://services.validexis.com/validator-security-our-approach-and-protection-measures/tmkms-for-remote-signing/tmkms-update-v0.15.0).

### Requirements from Celestia

celestia-app `v10.4.0` accepts any KMS that meets both requirements ([release notes](https://github.com/celestiaorg/celestia-app/blob/v10.4.0/docs/release-notes/release-notes.md#key-management-systems-kms)):

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

```bash
git clone https://github.com/iqlusioninc/tmkms.git $HOME/tmkms
cd $HOME/tmkms
git checkout v0.15.0
cargo build --release --features=softsign
cargo install --path . --features=softsign
tmkms version
```

#### LUKS volume for keys and state

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

```bash
sudo cryptsetup luksFormat /dev/<key_volume>
sudo cryptsetup open /dev/<key_volume> tmkms-keys
sudo mkfs.ext4 /dev/mapper/tmkms-keys
sudo mkdir -p /srv/tmkms
sudo mount /dev/mapper/tmkms-keys /srv/tmkms
sudo chown -R tmkms:tmkms /srv/tmkms && sudo chmod 700 /srv/tmkms
```

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

```toml
[[chain]]
id = "celestia"
key_format = { type = "bech32", account_key_prefix = "celestiapub", consensus_key_prefix = "celestiavalconspub" }
state_file = "/srv/tmkms/celestia/state/celestia-consensus.json"

[[providers.softsign]]
chain_ids = ["celestia"]
key_type = "consensus"
path = "/srv/tmkms/celestia/secrets/celestia-consensus.key"

[[validator]]
chain_id = "celestia"
addr = "tcp://<validator_node_id>@<validator_private_ip>:26658"
secret_key = "/srv/tmkms/celestia/secrets/kms-identity.key"
protocol_version = "v0.38"
reconnect = true
```

* 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](https://services.validexis.com/celestia-infrastructure/key-custody-and-signer-change).

#### Validator side

`config/config.toml` on the validator:

```toml
priv_validator_laddr = "tcp://<validator_private_ip>:26658"
```

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

#### systemd

```ini
[Unit]
Description=TMKMS for Celestia
After=network-online.target srv-tmkms.mount
Requires=srv-tmkms.mount

[Service]
User=tmkms
ExecStart=/usr/local/bin/tmkms start -c /srv/tmkms/celestia/tmkms.toml
Restart=always
RestartSec=10
LimitNOFILE=1024

[Install]
WantedBy=multi-user.target
```

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

   ```bash
   journalctl -u tmkms -f -o cat
   ```
2. **Latency** — on the validator's Prometheus endpoint:

   ```bash
   curl -s http://127.0.0.1:26660/metrics | grep cometbft_privval_signing_latency_median_seconds
   ```

   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

* [TMKMS changelog — 0.15.0](https://github.com/iqlusioninc/tmkms/blob/main/CHANGELOG.md) · [tmkms.toml.example](https://github.com/iqlusioninc/tmkms/blob/main/tmkms.toml.example)
* [celestia-app v10.4.0 release notes — KMS](https://github.com/celestiaorg/celestia-app/blob/v10.4.0/docs/release-notes/release-notes.md#key-management-systems-kms)
* [Run a Fibre server — prerequisites](https://docs.celestia.org/operate/consensus-validators/fibre/#prerequisites)
* Configuration templates: [github.com/validexisinfra/Celestia/tree/main/tmkms](https://github.com/validexisinfra/Celestia/tree/main/tmkms)
