Skip to content

How It Works

This page explains the core concepts behind Diogenes: the attestation model, the transparency log, the endorsement-based trust layer, and multi-layer verification.

The Attestation DAG

At the heart of Diogenes is a directed acyclic graph (DAG) of attestations. Each attestation is a cryptographic signature over a document manifest, made by a registered key holder.

graph TD
    A["Author Attestation"] --> E["Editor Attestation"]
    A --> R["Reviewer Attestation"]
    E --> P["Publisher Attestation"]
    R --> P

Each attestation type represents a different role in the document lifecycle:

Type Description
Authorship The signer claims to have authored or co-authored the document.
Editorial Review The signer attests to having reviewed and approved the document editorially.
Peer Review The signer attests to having reviewed the document for scholarly or technical accuracy.
Publication The signer (typically an institution) attests to publishing the document.

A manifest binds the document's content hash to its attestation graph. Manifests are JSON documents that include the document metadata, content hash, and all attestations.

The Transparency Log

Every significant event in Diogenes is recorded on the transparency log -- an append-only, hash-chained sequence of entries. The log records:

  • Key registrations -- When a new public key is registered.
  • Key successions -- When a key is replaced by a successor.
  • Key revocations -- When a key is revoked.
  • Attestation events -- When a document is signed.
  • Endorsement events -- When one key endorses another.

Each log entry contains:

{
  "id": 42,
  "timestamp": "2026-01-15T10:30:00Z",
  "event_type": "key_registration",
  "payload": { "...event-specific data..." },
  "previous_hash": "sha256:abc...",
  "entry_hash": "sha256:def..."
}

The previous_hash field links each entry to its predecessor, forming a hash chain. Anyone can verify the integrity of the entire log by recomputing each entry's hash and checking that the chain is unbroken.

Temporal Anchoring

Log entries can be anchored to Bitcoin via OpenTimestamps. This provides a tamper-evident timestamp that does not depend on any single server's clock. An OpenTimestamps proof for a log entry's hash proves that the entry existed at or before a certain Bitcoin block time.

Merkle Tree Heads

The log also supports signed tree heads -- Merkle tree roots over the log entries -- for efficient third-party audit. Auditors can verify that specific entries are included in the tree without downloading the entire log.

The Endorsement Model

Trust in Diogenes is not granted by a central authority. Instead, participants build trust through mutual endorsements.

Endorsement Lifecycle

  1. Offer -- An endorser offers an endorsement to another key holder. Categories include human_attestation (personal knowledge of the key holder) and institutional_endorsement (organizational verification).
  2. Accept -- The endorsed party accepts the offer, making the endorsement active.
  3. Withdraw -- The endorser can withdraw their endorsement at any time.
  4. Revoke acceptance -- The endorsed party can revoke their acceptance.

Endorsements have an activation delay -- they do not become active immediately, providing a window to detect and respond to compromised accounts.

Sybil Defense

To prevent trust gaming, Diogenes implements endorsement capacity scaling. Each key has a limited number of endorsements it can issue, scaled by the trust it has accumulated. Keys that over-endorse have their endorsements discounted.

Three-Layer Verification

When a document is verified, Diogenes performs three independent layers of checks:

Layer 1: Cryptographic Verification

  • Is the signature over the manifest mathematically valid?
  • Does the content hash in the manifest match the source document?
  • Are the attestation signatures consistent with the registered public keys?

Layer 2: Key Status Verification

  • Is the signing key still active (not revoked or expired)?
  • Was the key registered before the attestation was made?
  • If the key has been succeeded, is the successor chain valid?

Layer 3: Subjective Trust Assessment

  • Does the verifier trust the signing key, either directly or through a chain of endorsements?
  • How deep is the endorsement chain? (Trust decays with depth.)
  • Do the endorsements meet the verifier's configured trust policy?

Layer 3 is subjective -- each verifier can configure their own trust anchors, required depth, and decay parameters. There is no single "trusted" or "untrusted" verdict; it depends on the verifier's perspective.

Key Lifecycle

Keys in Diogenes follow a defined lifecycle:

stateDiagram-v2
    [*] --> Active
    Active --> Succeeded : succession
    Active --> Revoked : revocation
    Active --> Expired : expiration
  • Active -- The key can sign documents and endorse other keys.
  • Succeeded -- The key has been replaced by a new key. The old key remains valid for verifying historical signatures.
  • Revoked -- The key has been explicitly revoked by its owner. Signatures made before revocation remain verifiable.
  • Expired -- The key has passed its expiration date. Expired keys can be recovered through a succession process.