Skip to main content

Relays & verification

A relay is a public window onto protocol data. DFOS runs one at relay.dfos.com — it serves identity chains, public profile documents, and the operation log, read-only, to anyone. No account, no key, no permission needed to read.

Try it:

curl https://relay.dfos.com/.well-known/dfos-relay

That returns the relay's own description — including its own protocol identity, because a relay is an identity too.

What you can fetch — the routes and rules behind all of it are specified in the relay specification:

  • Identity records — any identity's verified state and its full operation log, by DID. That includes identities DFOS didn't create: a third-party app that publishes its own signed chain in its app document gets it ingested and re-served here, so its DID resolves at the same relay as everyone else's.
  • Public profile documents — the signed profile content chains of identities that have turned their public profile on.
  • Public posts — the signed content chains (and documents) of publicly readable posts, gated the same way as public profiles.
  • Existence proofs — the signed content chains of members-only posts, when their space publishes them. They carry no read credential, so the chain resolves and its operations verify while the document is never served — a space anchored a post at a given moment, and nothing more. See Posts on the protocol.
  • A queryable index — /index/v0, a browse convenience for paging through what the relay holds; verification still happens against the signed records.
  • Revocation status — /revocations/v1, whether a given credential has been revoked, checkable independently of whoever served you the credential. A withdrawn post's read credential reads as revoked here rather than as unknown.
  • The operation log — the append-only feed of signed operations, which is how other relays mirror the data.

The relay can't fabricate any of this: every record is signed by the identity that made it and addressed by its own content hash. Verification happens on your side, with open tools — and the rules it checks against are published as the protocol specification.

The quickest way to see that for yourself is explore.dfos.com, a browser-based verifier with no backend of its own: give it a DID or a content id and it resolves from the relay and recomputes every check in your own tab.

Finding the relay​

You don't have to hard-code the address. The DFOS API publishes it — a GET /v1/protocol call returns the relay that serves the identity and content chains for the DIDs the API emits, so a tool can discover where to resolve them instead of assuming.

curl https://api.dfos.com/v1/protocol
{
  "relayUrl": "https://relay.dfos.com",
  "didMethod": "did:dfos",
  "specUrl": "https://protocol.dfos.com/spec",
  "endpoints": {
    "wellKnown": "https://relay.dfos.com/.well-known/dfos-relay",
    "identity": "https://relay.dfos.com/proof/v1/identities/{did}",
    "identityLog": "https://relay.dfos.com/proof/v1/identities/{did}/log",
    "content": "https://relay.dfos.com/proof/v1/content/{contentId}",
    "contentLog": "https://relay.dfos.com/proof/v1/content/{contentId}/log",
    "operation": "https://relay.dfos.com/proof/v1/operations/{cid}",
    "blob": "https://relay.dfos.com/content/{contentId}/blob",
    "indexContent": "https://relay.dfos.com/index/v0/content",
    "indexIdentities": "https://relay.dfos.com/index/v0/identities"
  }
}

endpoints holds URL templates for the relay's routes; fill them in with values from API responses rather than building relay paths yourself. Each field is described in Protocol discovery.

For developers​

Everything lives in the open-source repo at github.com/metalabel/dfos:

  • @metalabel/dfos-protocol — the primitives: create identities, sign and verify identity and content chains, issue and check credentials.
  • @metalabel/dfos-client — resolve and verify identities and content over any relay, and build the proofs Sign in with DFOS and signed API requests use. It holds no keys.
  • @metalabel/dfos-web-relay — the relay server itself. To run your own, see Deploy a relay.
  • The dfos CLI — a standalone binary for working with the protocol from your terminal: create your own self-custodied identity, publish content, issue credentials, talk to relays (including ours), or run a local relay with dfos serve.

An identity you create with the CLI is fully yours — your keys, on your machine. It lives on the same protocol DFOS identities do: the product and anything anyone else builds share one verifiable substrate.

The CLI also works against an identity you already have. dfos keys add runs the ceremony that puts a key you hold on your DFOS account's chain, so the account and the command line end up signing as the same identity — see Sessions & keys for the whole key model, and Key proof for the two API routes the ceremony uses.

One canonical relay​

relay.dfos.com is the canonical relay for this data. The protocol supports independent relays mirroring each other, and the relay software is published — so a mirror verifies against the same signed records rather than against us.