Skip to content

Protocol flow

The normal lifecycle has a synchronous HTTP admission step followed by background signing. A client may receive a pending job before a threshold has been collected.

client                 gateway                    witnesses
  | POST hash             |                          |
  |---------------------->|                          |
  |       job status      | reserve canonical tuple |
  |<----------------------|                          |
  |                       | lease job                |
  |                       |---- parallel /v1/sign -->|
  |                       |<--- verified shares -----|
  |                       | threshold + final verify |
  | GET job               |                          |
  |---------------------->|                          |
  |<-- confirmed + signed |                          |

1. Hash admission

POST /v1/attestations accepts a SHA-256 hash in the request model. The gateway performs a fast duplicate lookup and then repeats the lookup under an in-process per-hash lock. This avoids consuming a one-use optional Freebird admission token when the hash already has a canonical job.

The gateway applies per-IP admission limiting and, when configured, verifies a Freebird token. It then reserves a job in SQLite. The stored attestation tuple contains:

  • the 32-byte hash;
  • a wall-clock Unix timestamp in seconds;
  • the network ID; and
  • a monotonically allocated sequence number.

The hash is the database primary key used for canonical reservation. A repeat submission retrieves the existing job rather than creating another attestation for that hash.

2. Lease and witness collection

The reconciler claims one due job with an opaque random lease token and an expiry. It validates the network configuration, fans out the same attestation to configured witnesses, and accepts only responses that have:

  • the expected witness ID;
  • a unique signer ID; and
  • a signature that verifies under that witness's configured public key and scheme.

Requests are collected until the configured threshold or the attempt deadline. Failed or insufficient attempts become retryable; configuration invariant failures become terminal failures. The lease prevents a stale worker from overwriting a later attempt.

3. Signed result

For Ed25519, the gateway stores one signature record per witness. For BLS, it aggregates the valid signature bytes and stores the aggregate plus ordered signer IDs. Before marking the job confirmed, the gateway runs the same threshold verifier used by clients. A confirmed job exposes a SignedAttestation; pending, retryable, and failed jobs do not expose one as a verified result.

The main read endpoint is GET /v1/attestations/:hash. POST /v1/verify can check a supplied object at the gateway, but that response is the gateway's opinion. Clients should verify locally.

4. Batching and log commitment

The batch manager selects confirmed, unbatched attestations in (sequence, hash) order. It builds an RFC 9162 Merkle tree over the attestation hashes and stores the batch and inclusion positions transactionally. An attestation can be confirmed before it is included in a batch.

When a batch closes, the gateway also computes the global log root at that point and asks the same witness set to threshold-sign a synthetic attestation representing the Signed Tree Head (STH). The STH is persisted only after verification.

5. Proof retrieval and verification

The gateway exposes separate proof surfaces:

  • /v1/proof/:hash for batch inclusion information;
  • /v1/bundle/:hash for a self-contained bundle;
  • /v1/anchors/:hash for external-anchor records;
  • /v1/log/sth, /v1/log/sth/:tree_size, /v1/log/consistency, and /v1/log/proof for the RFC 9162 log; and
  • /v1/network for the secret-free verification configuration.

The client can verify the threshold signature first, then optional batch inclusion, peer cross-anchors, and the presence of external-anchor evidence. See verification model.