Skip to content

Witnesses

Role

A witness node is a separately operated signing service. It holds one private Ed25519 key or BLS secret key and exposes:

  • POST /v1/sign for authenticated signing;
  • GET /v1/info for its ID, public key, and network ID; and
  • GET /health for liveness.

The gateway sends the same attestation to configured witnesses in parallel. A valid response identifies the witness and carries its signature. The gateway checks the witness ID, signature scheme, public key, and signature before it counts the response.

Signing requests require a bearer token, compared in constant time. The node also applies a per-IP signing rate limit (60 requests per minute in the current server), checks clock skew, and requires the configured network ID. Current and previous signing tokens can overlap during rotation. Private key material and tokens are operational secrets in the node configuration; configuration cleanup zeroizes key material and tokens.

Implemented behavior

Witnesses are signers, not consensus participants. They do not vote on a global state, exchange proposals, or decide which timestamp wins. The gateway gathers their independent signatures and applies the network threshold.

The default scheme is Ed25519. In BLS mode, witnesses independently sign and the gateway aggregates their signatures into one BLS signature while retaining the list of signer IDs.

Assumptions

The public keys in the verification configuration correspond to the intended witness operators, private keys are generated with a secure random source, and bearer tokens are high-entropy and kept private. “Independent” is an operator and deployment assumption, not something the protocol proves.

Non-goals

Witness nodes do not see the submitted document content: the signing request contains the attestation and its hash only. They do not provide anonymity for the network connection, and a compromised gateway or operator can still observe request metadata.

TODO — maintainer review

Clarify the recommended physical and administrative separation of witnesses, and specify whether the BLS terminology should consistently say “aggregate of independent signatures” rather than imply a distributed threshold-key setup.