Skip to content

Architecture

Witness is a content-private, accountless quorum timestamper. A client sends a SHA-256 digest rather than the document itself. A gateway obtains signatures from a configured witness set, verifies the result, and exposes signed attestations and optional proof layers.

This section describes the implementation in this repository. It is not a claim that the system is Byzantine-fault-tolerant or that the implementation has had an external security audit. Witness is pre-1.0 and unaudited.

Read this section

Page Subject
System overview Crates, binaries, trust boundaries, and the end-to-end shape
Protocol flow From hash submission to a signed result and proof bundle
Gateway Public API, admission, aggregation, and orchestration
Witness node Per-witness key custody and signing endpoint
Workers Durable leases, retries, batching, and asynchronous anchors
Storage model SQLite records, migrations, WAL, and local-disk requirements
Anchoring model Federation cross-anchors and external providers
Verification model Local verification, RFC 9162 proofs, and the auditor
Deployment modes Bare metal, Docker/nginx, Compose, and examples

Component map

       document                         public services
          |                                      |
          v                                      v
  SHA-256 hash + client                  +----------------+
          |                              | witness-gateway|
          +----------------------------->| API + SQLite   |
                                         +--------+-------+
                                                  |
                                  POST /v1/sign  |
                                   +--------------+--------------+
                                   |              |              |
                             +-----v----+   +-----v----+   +-----v----+
                             | node A   |   | node B   |   | node C   |
                             | key      |   | key      |   | key      |
                             +----------+   +----------+   +----------+
                                                  |
                                     signed attestation / proofs
                                                  |
                                  +---------------+---------------+
                                  | client / SDK / independent    |
                                  | auditor; verification locally |
                                  +-------------------------------+

The gateway is the coordinator and persistence owner. Witness nodes hold the signing keys. Clients and auditors do not need private keys.

Workspace map

The Cargo workspace contains these members:

  • witness-core: shared domain types, Ed25519 and BLS12-381 primitives, Merkle trees, RFC 9162 log types, and verification.
  • witness-node: the per-witness signing service.
  • witness-gateway: the main server, aggregation worker, storage, batching, federation, and external anchoring implementation.
  • witness-cli: the witness client binary.
  • witness-auditor: the independent RFC 9162 STH-chain auditor binary.
  • witness-client: a typed keyless client library used by the CLI and other consumers.
  • witness-core-wasm: a small verification-only WASM export of core verification functions.

The principal binaries are witness-gateway, witness-node, witness, and witness-auditor. The client and WASM crates are libraries, not signing services.

Main boundaries

  1. Signing boundary: only the gateway orchestration and witness node call signing operations. The private key is held by a witness node.
  2. Verification boundary: witness-core supplies the verifier used by the gateway, CLI, SDK, and auditor. A gateway response is not itself an independent verification result.
  3. Persistence boundary: the gateway writes the SQLite database. The database is durable application state, not by itself a tamper-evident log.
  4. External boundary: federation peers and anchor providers are optional outbound integrations. They add evidence or durability; they do not form a single consensus system.

Operating assumptions

The network configuration supplies witness IDs, public keys, endpoints, a threshold, and the selected signature scheme. Operational network.json files also contain bearer tokens and must be protected. The public NetworkVerificationConfig intentionally contains verification material, not those operational credentials.

For deployment and storage caveats, see deployment modes and storage model.