Skip to content

Anchoring model

Anchoring happens after a home gateway has confirmed attestations and closed a batch. The anchored object is batch metadata and its Merkle root, not the original document or its content.

confirmed attestations
          |
          v
   batch Merkle root
          |
    +-----+------------------+
    |                        |
    v                        v
peer gateways          external providers
cross-anchor            archive / log / DNS / chain
    |                        |
    +-----------+------------+
                v
        proof records in SQLite

Anchoring is asynchronous. Provider or peer outages do not invalidate a home-network threshold-signed attestation. They only reduce the additional evidence available for that batch.

Federation cross-anchoring

For each configured peer, the federation client submits an AttestationBatch to POST /v1/federation/anchor. The peer signs an attestation whose hash is the batch's Merkle root and whose network_id is the peer network's own ID. The resulting CrossAnchor carries:

  • the referenced batch;
  • the witnessing network ID;
  • the peer's complete threshold-signed attestation; and
  • a creation timestamp.

Verification checks that the root, batch, home network, peer network, and signature all agree, using the peer's secret-free verification configuration. The home configuration can require a number of distinct verified peer networks for a federated verification level.

Federation is not Byzantine-fault-tolerant consensus. It does not establish a global order, make networks one committee, or protect against collusion by enough witnesses or operators. Its value depends on accurate public configurations and meaningful operational independence between peers.

External providers

The gateway currently implements these provider types:

Provider Current operation
Internet Archive Sends a deterministic data URL containing network, batch, root, period, and count to the Save API.
Trillian/Tessera Adds a JSON batch entry to a configured log and records returned tree/index/inclusion data.
DNS TXT Requests a TXT record named _witness-<batch>.<domain> containing batch ID, root, network, period, and count.
Blockchain / Ethereum Sends a zero-value transaction to itself with the raw 32-byte Merkle root as input data and waits for a receipt.

Each provider returns an ExternalAnchorProof with a provider type, local creation timestamp, provider-specific JSON, and sometimes the anchored bytes. The anchor manager runs enabled providers in parallel and stores successful proofs only when minimum_required successes are reached.

Ethereum anchoring additionally needs an RPC URL, a signing wallet, gas, and protected credentials. The gateway's outbound clients use SSRF validation; the Ethereum receipt is evidence of a mined successful transaction, not a universal finality guarantee.

Verification limits

Anchor records are exposed by /v1/anchors/:hash and included in proof bundles. The current offline proof-bundle verifier reports external-anchor presence but does not independently validate every provider-specific proof. Operators and verifiers must apply the external service's own retention and finality semantics conservatively.