Tool documentation

How to read a PLC directory history

What the PLC directory is, the fields of a did:plc operation (rotation keys, verification methods, aliases, services, prev, sig), nullification and tombstones.

What the PLC directory is

did:plc is the DID method that almost every Bluesky account uses. Its registry, the PLC directory (plc.directory), is a public service that keeps, for each identity, the signed list of every change ever made to it. Anyone can read it: the current document at GET /{did}, the full log at GET /{did}/log/audit.

sh
curl https://plc.directory/did:plc:z72i7hdynmk6r22z27h6tvur/log/audit

The answer is a list of entries, oldest first. Each entry wraps one signed operation with what the directory adds: cid (the operation's content hash), nullified and createdAt (when the directory received it).

The fields of an operation

A plc_operation holds the whole state of the identity, not only what changed: to find the change, compare it with the operation before it, as the viewer does.

FieldWhat it holds
rotationKeysThe keys allowed to sign the next operation, the first one with the highest priority. Usually your server's key, sometimes your own recovery key.
verificationMethodsThe keys of the account itself; atproto is the signing key that signs your posts and records.
alsoKnownAsThe aliases: the first at:// entry is the handle.
servicesWhere the account lives: atproto_pds is its server (PDS); a labeler adds atproto_labeler.
prevThe CID of the operation this one replaces, null for the first one.
sigThe signature of the operation by one of the previous rotationKeys.
json
{
  "type": "plc_operation",
  "rotationKeys": ["did:key:zQ3sh…"],
  "verificationMethods": { "atproto": "did:key:zQ3sh…" },
  "alsoKnownAs": ["at://alice.example.com"],
  "services": {
    "atproto_pds": {
      "type": "AtprotoPersonalDataServer",
      "endpoint": "https://pds.example.com"
    }
  },
  "prev": "bafyrei…",
  "sig": "…"
}

The oldest identities started with a legacy create operation of 2022, with signingKey, recoveryKey, handle and service fields. The viewer reads it the way the reference implementation does: the signing key becomes the atproto method, [recoveryKey, signingKey] the rotation keys, the handle an at:// alias and the service the atproto_pds.

Nullification and recovery

The rotation keys are ordered by priority. For 72 hours after an operation, a key with a higher priority than the one that signed it can sign another operation with the same prev: the directory then marks the first one nullified: true and the identity follows the new one. This is how a recovery key takes an identity back after an unwanted change.

A nullified operation stays in the log, so the viewer keeps it in the timeline with a "Nullified" badge, and compares the operations after it with the last valid one.

Tombstones

A plc_tombstone deactivates the identity in the registry: it has no state, only prev and sig. Like any operation, it can be nullified within 72 hours by a rotation key with a higher priority than the one that signed it, which brings the identity back. Once that window has passed, the DID no longer resolves to a document and no operation can follow. The viewer shows the identity as "Deactivated", and a nullified tombstone with its "Nullified" badge.

How a migration reads

When an account moves to another server, its new server takes over the identity in one operation, signed by the old server's rotation key:

  • services.atproto_pds.endpoint changes to the new server;
  • verificationMethods.atproto changes to the new server's signing key;
  • rotationKeys changes, the old server's key replaced by the new one's.

So a server move with new rotation keys within a day is what a migration looks like, and also what an account takeover looks like: the viewer adds a note when it sees one. If you did not move your account, contact the host of your server. To give a bot a recognisable handle without moving it, see Get your handle.

PLC history viewer

Every handle change, server move and key change of an account.