Skip to content

Timestamping

Implemented behavior

An attestation contains:

  • hash: a 32-byte SHA-256 digest supplied by the client;
  • timestamp: Unix seconds captured when the gateway creates the attestation;
  • network_id: the signing network identifier; and
  • sequence: a monotonic gateway sequence used for ordering.

The canonical signing message is:

hash (32) || timestamp (8 LE) || network_id_len (4 LE) || network_id || sequence (8 LE)

The length prefix makes the network identifier unambiguous. Witnesses sign this exact byte sequence; clients verify it through witness-core.

Creation is a durable job workflow. POST /v1/attestations validates a hash, deduplicates by hash, and atomically reserves the canonical tuple. A new or unconfirmed job is accepted for asynchronous processing. Lease-based workers retry witness calls with bounded backoff, and a confirmed response contains the threshold-signed attestation. A failed job is terminal. A duplicate confirmed job returns the existing attestation.

The reservation timestamp is immutable; retries do not take a new timestamp. Witnesses reject timestamps outside max_clock_skew (300 seconds by default). After a prolonged outage, a reservation can therefore age beyond every witness's skew window and become impossible to confirm: the retry is terminal in effect even though the generic quorum failure path may continue to report the job as retryable. Operators must not interpret a later retry as refreshing the attestation's timestamp.

Each witness rejects a request whose timestamp is outside its configured clock skew (300 seconds by default) or whose network ID is wrong. This is a sanity check, not a distributed clock protocol.

For newly created jobs, the gateway also immediately broadcasts the lowercase digest and reserved timestamp on /ws/events. This event is sent before witness confirmation and is unauthenticated unless WITNESS_WS_AUTH_TOKEN is set.

Assumptions

The statement supported by the signed object is that the configured witnesses signed this hash, network, sequence, and timestamp. Clients must obtain and trust the correct verification configuration; /v1/network is the public, secret-free configuration endpoint, while /v1/config is informational and is not itself a trust anchor.

Non-goals

An attestation is not proof of the original content, authorship, ownership, or the exact physical time at which content was created. It does not prove that a gateway was honest beyond the signatures and data a verifier can check. A hash also does not hide a low-entropy or publicly guessable document.

TODO — maintainer review

Document the intended precision and legal meaning of timestamp, and decide whether the API should expose the distinction between reservation time, confirmation time, and batch-commit time more prominently.