Witness concepts

Witness is a content-private, accountless quorum timestamper. A client submits a 32-byte SHA-256 hash, not the content. A configured network of witness nodes signs an attestation, and the gateway accepts it only after the configured threshold is met.

These pages describe the behavior currently represented in the Rust workspace. They are concepts, not a protocol specification or security audit.

In one request

1. The client sends a hash to POST /v1/attestations.
2. The gateway reserves a durable job containing the hash, a wall-clock Unix timestamp, the network ID, and a monotonic sequence number.
3. The gateway asks witness nodes to sign the same attestation.
4. It verifies the responses and persists a confirmed result only when the configured threshold is met.
5. A later batch can commit attestation hashes to an RFC 9162 Merkle tree. Optional federation and external anchors add independent commitments.

The gateway is asynchronous: a new job normally returns 202 Accepted, and a client polls until the job is confirmed. A duplicate confirmed hash returns the existing job rather than creating another attestation.

Concepts

• Timestamping — the signed attestation and job lifecycle.
• Witnesses — node roles, keys, and signing requests.
• Quorum — configurable m-of-n acceptance and its limits.
• Threshold signatures — Ed25519 multi-signatures and BLS aggregation.
• Merkle batches — batch roots and the RFC 9162 log.
• Proof bundles — layered, offline-verifiable evidence.
• External anchoring — optional provider commitments.
• Federation — peer-network cross-anchors.
• Light clients — verification without a full history.
• Privacy model — what hashing does and does not hide.

Current boundary

Implemented: Ed25519 multi-signatures, BLS12-381 aggregate signatures, configurable witness thresholds, hash-only submission, batch Merkle proofs, RFC 9162 Signed Tree Heads and consistency verification, optional peer cross-anchoring, and optional Internet Archive, Trillian, DNS TXT, and Ethereum/blockchain anchors.

Assumptions: Operators publish and clients use the correct secret-free NetworkVerificationConfig; witness keys and operational tokens are protected; production traffic uses HTTPS; and independent operators are actually independent enough for the selected threshold to be meaningful.

Non-goals: Witness does not implement Byzantine-fault-tolerant consensus, global ordering across independent networks, authorship or ownership proofs, or anonymity against network and service operators.

TODO — maintainer review: Confirm which claims in these conceptual pages should become versioned protocol requirements, especially timestamp semantics, external-provider proof validation, and operational guarantees.