The did:vh DID Method -- DID + Verifiable History (Editors Draft)
Light Dark System Issues
The did:vh DID Method -- DID + Verifiable History (Editors Draft)

The did:vh DID Method
v0.1 / Editors Draft
§

Specification Status: Editors Draft

Specification Version: v0.1 (see Changelog)

Source of Latest Draft: https://github.com/decentralized-identity/didvh

Editors:
Stephen Curran
Participate:
GitHub repo
File a bug
Commit history
Related Specifications:
did:webvh — the web-located DID method from which did:vh is derived.

IPR Status

This document was produced by a group operating under the W3C Patent Policy. An individual who has actual knowledge of a patent that the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.


Abstract§

DID + Verifiable History (did:vh) is a DID Method that gives a Decentralized Identifier (DID) a cryptographically verifiable history without tying it to any location. It is the location-independent sibling of did:webvh: a did:vh DID is simply

did:vh:<SCID>

where <SCID> is the self-certifying identifier derived from the DID’s first DID log entry. Unlike did:webvh, a did:vh DID contains no domain name or path, and so is not bound to any location where its DID Log is published.

Because the DID carries no location, sourcing the DID Log is separated from resolving the DID. A did:vh Resolver implements the standard DID Resolution resolve(did, resolutionOptions) function: the client passes the DID Log and witness proofs directly, or by reference in the srcLog and srcWitness options, as resolution options, and the Resolver verifies the log and returns the DIDDoc. How a client sources the DID Log beforehand — getting the log itself or a reference to it, because it is known in context, from a watcher, exchanged peer-to-peer, or from a web location — is described non-normatively, and a DID Log sourced in any of these ways is verified in exactly the same way. The SCID guarantees that the log is the authentic history of the DID, wherever it came from.

did:vh provides the same verifiable-history features as did:webvh:

  • A self-certifying identifier (SCID), globally unique and derived from the initial DID log entry, binding the DID to its full history and mitigating the risk of attackers creating a new object with the same identifier.
  • The ability to resolve the full history of the DID using a verifiable chain of updates to the DIDDoc, from creation to deactivation.
  • DIDDoc updates containing a proof signed by a DID Controller-authorized key.
  • An optional mechanism for publishing “pre-rotation” key hashes to prevent the loss of control of a DID in cases where an active private key is compromised.
  • An optional mechanism for having collaborating witnesses approve updates to the DID by a DID Controller before they are distributed.
  • Support for cryptographic agility through versioned specification upgrades, algorithm-identifying formats (e.g., multihash and Data Integrity proofs), and per-entry method parameters in the DID Log that enable DIDs to evolve cryptographically over time.
  • An optional mechanism for listing watchers that archive and re-serve the DID’s history, and that resolvers can use to check that a copy of the log is current and has not been forked.

Separating the identifier from the location of its history gives did:vh properties that a web-located DID cannot have:

  • Permanence. The DID never has to change because the place its history is kept changes. There is no need for a portability mechanism.
  • Location independence. The DID Log can be kept on a web server, with a watcher, in a database, on a distributed ledger, or only in the wallets of the parties to a relationship — and in several such places at once.
  • Peer-to-peer use. A did:vh DID can be used between two parties who exchange their DID Logs directly, in the manner of did:peer [DID-PEER], while still supporting key rotation, pre-rotation and the other did:vh features.

did:vh is comparable to the did:scid:vh format of the proposed did:scid metamethod, and adopts its src parameter.

Overview§

did:webvh added a verifiable history to did:web: a self-certifying identifier (SCID), a hash-chained log of every version of the DIDDoc, signed updates, pre-rotation, witnesses and watchers. It kept the domain name from did:web in the DID, so that a Resolver can turn the DID into an HTTPS URL and fetch the DID Log.

The domain name does two jobs in did:webvh: it tells a Resolver where to find the log, and it makes the DID a web identifier. It is not needed for security — the SCID and the verifiable history provide that on their own. But it does tie the DID to one location. When that location changes, the DID changes, which did:webvh handles with its optional portability mechanism: the SCID stays the same and the DID Log carries the DID’s history across the move, but the DID is no longer the same string.

Many uses of DIDs need an identifier that never changes: as a permanent account identifier, embedded in content-addressed data, or held in long-lived credentials. Others have no web location at all: DIDs exchanged between two parties, DIDs kept in an organisation’s database, or DIDs anchored on a ledger. did:vh serves those uses by removing the location from the DID:

did:webvh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ:example.com:dids:issuer
did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ

Everything else is kept as close to did:webvh as makes sense. The DID Log format, parameters, SCID and entry-hash algorithms, key authorization and pre-rotation, witnesses, watchers, and the version-selection resolution options are those of did:webvh. Implementations of did:webvh can support did:vh by replacing the DID-to-HTTPS transformation with the resolution options defined here and dropping the web-location-specific features.

The following is a tl;dr summary of how did:vh works:

  1. A DID Controller creates the first DID log entry exactly as in did:webvh, using the DID string did:vh:{SCID} with the {SCID} placeholder, calculates the SCID and replaces the placeholders.

  2. The DID Log (did.jsonl) is a JSON Lines file of DID log entries, one per line. Each entry is a JSON object containing:

    1. versionId – a value that combines the version number (starting at 1 and incremented by one per version), a literal dash -, and a hash of the entry. The entry hash calculation links each entry to its predecessor in a ledger-like chain.
    2. versionTime – as asserted by the DID Controller.
    3. parameters – a set of parameters that impact the processing of the current and future log entries, such as the version of the did:vh specification being used, the SCID and the update key(s).
    4. state – the new version of the DIDDoc.
    5. proof – a Data Integrity proof across the entry, signed by a DID Controller-authorized key.

    If the DID Controller uses witnesses, a separate file (did-witness.json) holds the witnesses’ Data Integrity proofs for DID Log entries.

  3. The DID Controller makes the DID Log available wherever it is needed: to the other party in a relationship, to one or more watchers, at one or more web locations, or in any other store. There is no single authoritative location.

  4. A client that needs to resolve did:vh:<SCID> first sources the DID Log: it gets the log itself from context, a watcher or a peer, or a reference to it, such as the web location given in did:vh:<SCID>?src=https://example.com/dids/issuer.

  5. The client calls the Resolver, passing the DID Log (and witness proofs) directly, or by reference in the srcLog (and srcWitness) options. The Resolver verifies every entry and returns the DIDDoc. The SCID check ensures the log is the history of that DID, regardless of where it came from. Optionally, the client asks the Resolver to compare the log with copies held by watchers.

  6. Updates append entries to the log, which the DID Controller re-distributes to the places the log is kept.

Because a did:vh DID Log has no single authoritative location, a Resolver cannot always be sure it holds the latest version of the log, and a DID Controller could give different parties different extensions of the same log. Watchers and witnesses are the tools did:vh uses to manage those risks; see Log Freshness and Duplicity.

Relationship to did:scid§

The proposed did:scid metamethod defines a family of location-independent DIDs, each using the verification data format of an existing SCID-based DID method. Its did:scid:vh format uses the did:webvh format, and so is comparable to did:vh:

did:scid:vh:1:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ
did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ

did:vh shares the design goals of did:scid — a permanent, portable, self-certifying DID whose history can be kept in any number of locations — and adopts its src DID URL query parameter for naming a location that holds the log. The differences are:

  • did:vh is a standalone DID method rather than a format of a metamethod.
  • The version of the specification in use is carried in the method parameter of the DID Log, as in did:webvh, rather than in the DID string.
  • In this version of did:vh, the src parameter carries only a URL: an https URL or a URL with another scheme the Resolver supports (such as ipns). did:scid also allows it to name a DID method that stores the log.
  • src is not a did:vh resolution option. A client passing the log to a Resolver by reference names each file explicitly, in the srcLog and srcWitness options, which a dereferencer derives from a src DID URL parameter. These options can also name loopback http URLs and local file: URLs for a local Resolver.

The did:scid:vh format is currently defined on did:webvh, whose DIDs carry a web location that did:scid does not need. As did:vh is the location-independent form of the same verifiable history, we expect the definition of did:scid:vh to evolve to use did:vh instead of did:webvh. See the note on the initial DIDDoc for how did:vh leaves room for that.

Because the DID string is part of the first DID log entry, and so of the input to the SCID, a did:vh, a did:scid:vh and a did:webvh DID can never share a DID Log or an SCID. A DID Controller can link such DIDs using alsoKnownAs.

did:vh DID Method Specification§

Conformance§

As well as sections marked as non-normative, all examples and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, NOT REQUIRED, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT in this specification are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Relationship to did:webvh§

did:vh is derived from the did:webvh DID method, and is deliberately as close to it as its lack of a location allows. The log format, SCID and entry hash algorithms, key authorization, pre-rotation, witnesses, witness identifiers (did:key), the witness proofs file format, watchers, and the versionId, versionTime and versionNumber resolution options are the same in both methods. The differences are:

did:webvh did:vh
DID did:webvh:<SCID>:<domain>[:<path>] did:vh:<SCID>
Locating the DID Log DID-to-HTTPS transformation Passed to the Resolver in resolution options, after the client sources it
method values did:webvh:1.0 did:vh:1.0
portable parameter Optional Not used — the DID never changes
Parallel did:web Optional Not applicable

Implementations of did:webvh can support did:vh by replacing the DID-to-HTTPS transformation with the resolution options defined here and dropping the features that depend on a web location.

Target System§

did:vh does not have a single target system. A did:vh DID Log can be held by any system that can store and return a file: a web server, a watcher, a database or registry, a distributed ledger, or the wallets of the parties that use the DID. The SCID and the verifiable history make the DID Log verifiable no matter which of those systems it was obtained from.

Method Name§

The namestring that identifies this DID method is: vh. A DID that uses this method MUST begin with the prefix did:vh:. Per the DID specification, the prefix MUST be in lowercase. The remainder of the DID, after the prefix, is the method-specific identifier.

Method-Specific Identifier§

Every did:vh DID MUST conform to the DID Syntax ABNF Rules in [DID-CORE] Section 3.1. The did:vh method-specific identifier is the SCID of the DID, and nothing else. The SCID MUST be generated during the creation of the DID from its initial content.

A did:vh DID MUST conform to the following ABNF [RFC5234]:

vh-did      = "did:vh:" scid
scid        = 46base58-char
base58-char = %x31-39 / %x41-48 / %x4A-4E / %x50-5A / %x61-6B / %x6D-7A
              ; the base58btc alphabet: 1-9, A-Z except I and O,
              ; a-z except l

ABNF string literals are case-insensitive, but [DID-CORE] requires the method name, and so the did:vh: prefix, to be lowercase. The scid production describes the base58btc-encoded multihash generated and verified as specified in SCID Generation and Verification. It is case-sensitive: two did:vh DIDs are the same DID if and only if they are identical character for character. The {SCID} value used temporarily during DID creation is a placeholder and is not a conforming scid; it MUST be replaced before the DID is distributed or resolved.

A did:vh DID URL MUST conform to the DID URL Syntax ABNF Rules in [DID-CORE] Section 3.2, and its contained DID MUST conform to the rule above. did:vh defines the DID URL query parameters described in Reading did:vh DID URLs, including the optional src parameter.

The id of a resolved did:vh DIDDoc identifies the DID subject and therefore MUST be a bare did:vh DID. It MUST NOT contain a DID URL path, query, or fragment component.

A did:vh DID, and DID URLs using the src and versionNumber query parameters, and a fragment:

did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ
did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ?src=https://example.com/dids/issuer
did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ?versionNumber=3
did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ#key-1

Verification of a did:vh DID using this specification ensures cryptographic validity, but that does not imbue “trust” in the identifier itself. Trust in a did:vh DID comes from external sources, such as verifiable credentials issued by trusted parties or via trust registries that maintain authoritative records of trusted DIDs in a given context. Implementers are advised not to conflate technical verification with trustworthiness.

The DID Log File§

The DID Log contains a list of entries, one for each version of the DID. A version of the DID is an update to the contents of the resolved DIDDoc for the DID, and/or a change to the parameters that control the generation and verification of the DID.

Each entry is a JSON object consisting of the following properties.

{ "versionId": "", "versionTime": "", "parameters": {}, "state": {}, "proof" : [] }

  1. The value of versionId MUST be a string consisting of the DID version number (starting at 1 and incrementing by one per DID version), a literal dash -, and the entryHash, a hash calculated across the log entry content. The input to the hash is chosen so as to link each entry to its predecessor in a ledger-like chain. The input to the hash is specified in the Entry Hash Generation and Verification section of this specification.
  2. The value of versionTime MUST be a timestamp in UTC of the entry in ISO8601 format, as asserted by the DID Controller. The timestamp MUST be the time the entry will be retrieved by a witness or Resolver, or before. The timestamp MUST be expressed in whole seconds, with no fractional seconds (for example, 2025-04-01T17:39:50Z). Because each entry’s versionTime is later than the previous entry’s, consecutive entries are at least one second apart.
  3. The JSON object parameters contains the configurations/options set by the DID Controller to be used in the processing of current and future log entries. Permitted parameters are defined in the did:vh DID Method Parameters section of this specification.
  4. The JSON object state contains the DIDDoc for this version of the DID.
  5. The JSON array proof contains a Data Integrity proof created for the entry and signed by a key authorized to update the DIDDoc.

After creation, each entry has (per the JSON Lines specification) all extra whitespace removed, a \n character appended, and the result added to the DID Log.

When the DID Log is stored as a file, the file SHOULD be named did.jsonl, and MUST be named did.jsonl when stored at a location named by a src DID URL parameter. Its media type SHOULD be text/jsonl. When witnesses are used, the witness proofs file SHOULD be named did-witness.json, and MUST be named did-witness.json when stored at a location named by a src DID URL parameter. Whenever the files are transferred over a network, they MUST be published and retrieved as described in Publishing and Retrieving DID Log Resources.

A more comprehensive description of how to create and update a DID log entry is given in steps 4 - 6 of the create DID section.

Examples of log entries that fail verification. Illustrative and non-exhaustive; the normative verification criteria are defined in the Resolution Algorithm.

  1. Duplicate witness IDs. {"threshold": 1, "witnesses": [{"id": "did:key:X"}, {"id": "did:key:X"}]} — the same did:key appears more than once in the witnesses list; each witness has to be unique.

  2. Pre-rotation active but updateKeys omitted. If entry N-1 commits nextKeyHashes: ["H1","H2"], then entry N has to contain an explicit updateKeys whose every member hashes to a value in ["H1","H2"]. An entry N omitting updateKeys (intending to inherit) fails verification.

  3. Wrong cryptosuite on log-entry proof. {"type":"DataIntegrityProof","cryptosuite":"ecdsa-jcs-2019","proofPurpose":"assertionMethod"} — fails verification even if the signature is structurally valid, because parameters.method with value did:vh:1.0 requires eddsa-jcs-2022.

  4. state.id is not the DID. The first entry has parameters.scid: "Qm111...", and an entry has state.id: "did:vh:Qm222...", "did:vh:Qm111...?src=https://example.com" or "did:webvh:Qm111...:example.com". Every entry’s state.id has to be exactly did:vh:Qm111....

  5. portable parameter present. An entry includes "portable": true. portable is not a did:vh parameter.

  6. Malformed method value. The first entry has parameters.method: "did:vh:1.0-rc1", "did:vh:01.0", "did:webvh:1.0" or "didvh:1.0". (A well-formed value for a version the Resolver does not support, such as "did:vh:99.0", is not a verification failure: the Resolver returns featureNotSupported, and never silently downgrades.)

  7. Fractional seconds. An entry has versionTime: "2025-04-01T17:39:50.123Z". versionTime values are in whole seconds.

  8. Entry after updateKeys: []. Entry N sets updateKeys: [] (with pre-rotation not active). Entry N+1 sets nextKeyHashes: ["H1"] and updateKeys: ["K1"], where K1 hashes to H1, and is signed by K1. It fails verification: pre-rotation is not active for entry N+1, so it has to be signed by a key from entry N’s updateKeys, which is empty.

DID Method Operations§

Create (Register)§

Creating a did:vh DID is done by carrying out the following steps.

  1. Define the DID string The DID string MUST be the literal string did:vh:{SCID}, where {SCID} is a placeholder that will be replaced by the calculated SCID later in the process (see step 5). Unlike did:webvh, no domain name or path follows the placeholder: the location where the DID Log will be kept is not part of the DID.

  2. Generate the authorization key pair(s) Authorized keys are authorized to control (create, update, deactivate) the DID. At the same time, generate any other key pairs that will be placed into the initial DIDDoc for the DID.

    1. If the DID is to use pre-rotation, additional key generation will be necessary to generate the required “next” authorization keys and their corresponding pre-rotation hashes.
    2. For each authorization key pair, generate a multikey based on the key pair’s public key. The multikey representations of the public keys are placed in the updateKeys property in parameters.
    3. The public key(s) of the authorization key pair(s) MAY be used in the DIDDoc as well, but that is not required.
  3. Create the initial DIDDoc for the DID The DIDDoc MUST contain the top level id property, which MUST be the DID string from step 1, did:vh:{SCID}. Other DIDDoc verifications SHOULD be performed.

    All other absolute references to the DID in the DIDDoc MUST use the form defined in step 1, with the placeholder for the SCID (e.g., did:vh:{SCID}#key-1).

    The DIDDoc can contain any other content as deemed necessary by the DID Controller.

    1. Note: The placeholder (the string {SCID}) MUST be in every place in the DIDDoc where the SCID is to be placed.

Future use by did:scid:vh. In this version of did:vh, the id of every DIDDoc in the DID Log, starting with the initial one, is the did:vh DID (see step 6 of Read (Resolve)). If did:scid:vh evolves to use the did:vh format (see Relationship to did:scid), the id of each DIDDoc in a did:scid:vh log — and so the DID string in the initial entry that is input to the SCID — would be the did:scid:vh DID, since DID Resolution requires a resolved DIDDoc’s id to be the DID being resolved. The same question has been raised for did:webvh in did:webvh issue #305. Because did:scid is not yet stable, this specification does not define that case. A later version of did:vh is expected to, for example by allowing the DIDDoc id to be a did:scid:vh DID with the same SCID, while the rest of the DID Log is created and verified as defined here.

  1. Generate a preliminary DID Log Entry JSON object containing the same JSON properties that will be in the published DID log entry, but with some values preset, pending calculation of the SCID and entryHash and without the proof.

    1. The value of versionId string MUST be the placeholder literal "{SCID}".
    2. The value of versionTime string MUST be a valid UTC ISO8601 date/time string in whole seconds, and the represented time MUST be before or equal to the current time.
    3. The value of the parameters property MUST be a JSON object defined at the discretion of the DID Controller. The properties in this nested JSON object MUST be as permitted in the did:vh DID Method Parameters section of this specification, and all required values in the first version of the DID MUST be present. In addition, where the SCID of the DID is referenced in the parameters, the placeholder literal string {SCID} MUST be used in place of the to-be-calculated SCID.
    4. The value of the state property MUST be the initial DIDDoc as defined in the previous step 3 of this process.
  2. Update the preliminary DID Log Entry to the initial DID Log Entry Use the preliminary DID log entry to perform the consecutive steps:

    1. Calculate the SCID The preliminary JSON object MUST be used to calculate the SCID for the DID as defined in the SCID Generation and Verification section of this specification.
    2. Replace the placeholder {SCID} Treating the preliminary JSON object entry as a string, perform a literal text replacement of every occurrence of the placeholder {SCID} with the calculated SCID from the previous step.
      • NOTE: As a consequence, the literal string {SCID} cannot appear as a value anywhere in the first DID Log entry — it will always be replaced. If that string is required in the DIDDoc, it can be introduced via an update in a subsequent log entry.
    3. Calculate the Entry Hash The preliminary JSON object updated in the previous step MUST be used to calculate the Entry Hash (entryHash) for the log entry, as defined in the Entry Hash Generation and Verification section of this specification.
    4. Replace the preliminary versionId value The value of the versionId property MUST be updated with the literal string 1 (for version number 1), a literal -, followed by the entryHash value calculated in the previous step.
    5. Generate the Data Integrity proof A Data Integrity proof on the preliminary JSON object as updated in the previous step MUST be generated using an authorized key in the required updateKeys property in the parameters object and the proofPurpose set to assertionMethod.
    6. Add the Data Integrity proof The Data Integrity proof is added to the preliminary JSON object. The resultant JSON object is the initial DID log entry for the DID.
  3. Generate the first JSON Line The DID log entry MUST be updated to be a JSON Lines entry by removing extraneous white space and appending a newline character, and the result stored as the contents of the DID Log (did.jsonl).

    If the DID Controller has opted to use witnesses for the DID, the required proofs from the DID’s witnesses MUST be collected into the witness proofs file (did-witness.json) before the DID Log is distributed. See the DID Witnesses section of this specification.

  4. Distribute the DID Log Instead of publishing the DID Log at a location derived from the DID, the DID Controller makes the DID Log (and witness proofs file) available through the DID Log sources (see Sourcing the DID Log) that the parties who will resolve the DID will use: giving it to a peer, sending it to watchers, publishing it at one or more web locations, or storing it where the ecosystem expects to find it. A DID Controller MUST make the log available through at least one source that those parties can use.

    If there are watchers configured for the DID, the DID Controller notifies them that a new DID is available, as described in Watcher HTTP API Operations.

Read (Resolve)§

A did:vh Resolver implements the resolve function defined in [DID-RESOLUTION]:

resolve(did, resolutionOptions) →
   « didResolutionMetadata, didDocument, didDocumentMetadata »

The did input is the DID itself, did:vh:<SCID>, which says nothing about where the DID Log is. The client of the Resolver therefore passes the DID Log — and, if witnesses are in use, the witness proofs — in resolutionOptions, in one of the two ways defined below: directly, or by reference, in which case the Resolver first retrieves the files. The Resolver then verifies the DID Log and returns the requested version of the DIDDoc.

The Resolver does not discover the DID Log. How a client sources the DID Log — gets the log itself, or a reference to it — before calling resolve is described in the non-normative Sourcing the DID Log section. Once it has the DID Log the client passed, the Resolver retrieves further copies only when the client asks it to, with the checkWatchers and extraWatchers options, to check that the client’s copy is current and has not been forked.

did:vh Resolution Options§

A did:vh Resolver recognises the following options in resolutionOptions. versionId and versionTime are defined in [DID-RESOLUTION]. The others are did:vh-specific, and are to be registered in [DID-EXTENSION-RESOLUTION].

Option Value Purpose
didLog String The complete DID Log, in JSON Lines format.
didWitness JSON array The content of the witness proofs file.
srcLog String A reference to the DID Log file. See The srcLog and srcWitness Options.
srcWitness String A reference to the witness proofs file. See The srcLog and srcWitness Options.
versionId String Select a version by versionId, as defined in Selecting a Version.
versionTime ISO8601 string Select the version active at a time, as defined in Selecting a Version.
versionNumber Positive integer Select a version by version number, as defined in Selecting a Version.
checkWatchers Non-negative integer, or the string all The number of the DID’s listed watchers from which the Resolver MUST retrieve a copy of the DID Log. Defaults to 0. See Comparing Copies of a DID Log.
extraWatchers List of https URLs Watchers, which need not be listed in the DID Log, from each of which the Resolver MUST retrieve a copy of the DID Log. Defaults to an empty list.
minCopies Positive integer The minimum number of retrieved copies of the DID Log that MUST match for resolution to succeed. Defaults to 1.
includeDidLog Boolean If true, the Resolver MUST return the verified DID Log and witness proofs file in the didLog and didWitness properties of the DID Resolution Metadata. Defaults to false.

The didLog, didWitness, srcLog and srcWitness options support two ways of giving the Resolver the DID Log and the witness proofs file:

  • Passing directly. The client passes the content of the DID Log in didLog, and of the witness proofs file (if any) in didWitness.
  • Passing by reference. The client passes, in srcLog, a reference to the file from which the Resolver retrieves the DID Log, and, in srcWitness, a reference to the file from which it retrieves the witness proofs file (if any), as defined in The srcLog and srcWitness Options. In this version of did:vh, a reference is a web location, a location using another URL scheme the Resolver supports, or, for a Resolver local to its client, a local file or loopback web location.

The two files are given independently, so the DID Log can be passed directly and the witness proofs file by reference, or the reverse.

The following rules apply to the options:

  • Exactly one of didLog and srcLog MUST be given.
  • At most one of didWitness and srcWitness MAY be given.
  • At most one of versionId, versionTime and versionNumber MAY be given.
  • A malformed option, a value that does not conform to the rules for srcLog or srcWitness, a violation of any of the rules above, or an extraWatchers value that is not an https URL, MUST cause the invalidOptions error.
  • A Resolver MUST support files passed directly. It MAY decline to retrieve from srcLog and srcWitness references, based on its policy (for example, a Resolver that never retrieves from locations chosen by its callers), and then MUST return the featureNotSupported error, except as defined in Web Locations and Local Files.
  • A Resolver MUST support versionId and versionTime, and SHOULD support versionNumber, checkWatchers, extraWatchers, minCopies and includeDidLog. A Resolver given an option it does not support MUST return the featureNotSupported error rather than ignore the option.

Passing the files directly, resolving version 2:

{
  "did": "did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ",
  "resolutionOptions": {
    "didLog": "{\"versionId\":\"1-Qm...\",...}\n{\"versionId\":\"2-Qm...\",...}\n",
    "didWitness": [ { "versionId": "2-Qm...", "proof": [ ... ] } ],
    "versionNumber": 2
  }
}

Passing the files by reference to a web location, and checking the log against two of the DID’s listed watchers:

{
  "did": "did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ",
  "resolutionOptions": {
    "srcLog": "https://example.com/dids/issuer/did.jsonl",
    "srcWitness": "https://example.com/dids/issuer/did-witness.json",
    "checkWatchers": 2,
    "minCopies": 2
  }
}

Passing the files by reference to local files, using a local Resolver:

{
  "did": "did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ",
  "resolutionOptions": {
    "srcLog": "file:///var/lib/wallet/dids/QmfGEU.../did.jsonl",
    "srcWitness": "file:///var/lib/wallet/dids/QmfGEU.../did-witness.json"
  }
}
The srcLog and srcWitness Options§

The srcLog (“source of the log”) option is a reference to the file holding the DID Log, and the srcWitness (“source of the witness proofs”) option is a reference to the file holding the witness proofs file. Each value names a file, not a directory: the Resolver retrieves exactly the resource named, and does not add to or change the path. The file names did.jsonl and did-witness.json are therefore not required, and the two files need not be in the same place.

Each value MUST be an absolute URL [RFC3986], and its scheme determines the kind of reference:

  • https, or http with a loopback host: a web location, such as https://example.com/dids/issuer/did.jsonl or http://localhost:8000/dids/issuer/did.jsonl.
  • file: a local file [RFC8089], such as file:///var/lib/wallet/dids/QmfGEU.../did.jsonl.
  • Any other scheme: an other scheme reference, such as ipns://k51qzi5uqu5d.../dids/issuer/did.jsonl.

A value that is not an absolute URL, or that is not valid for its kind, MUST cause the invalidOptions error.

The Resolver MUST retrieve the DID Log from the srcLog reference when one is given. If it is not found, the Resolver MUST return the notFound error.

The Resolver MUST retrieve the witness proofs file from the srcWitness reference only if the active parameters of the DID Log require witnesses, and MUST NOT treat a srcWitness reference that it did not need as an error. A client can therefore pass srcWitness whenever a witness proofs file may exist. When witnesses are required but no witness proofs file was passed, or the srcWitness reference was not found, the Resolver MUST proceed as if the witness proofs file contained no proofs, as defined in Verifying Witness Proofs During Resolution.

A srcLog or srcWitness reference is not authoritative: a DID Controller MAY stop publishing at a web location at any time, and the DID Log found through any reference may not be the latest. Because the reference is not part of the DID, the DID does not change when the log is stored elsewhere.

A reference also says nothing about who controls the DID: a DID Controller can publish a log at any location it can write to, and any client can pass any reference. Resolvers and their clients MUST NOT treat a srcLog or srcWitness reference, or a src DID URL parameter, as evidence of an association between the DID and the owner of the location.

The did:scid src parameter can also name a DID method that stores the verification data (for example, a DID-Linked Resource on a ledger). This version of did:vh supports only URL references. Other kinds of reference, such as DID values or references to other ways of storing a DID Log, may be added in a later version.

Web Locations§

A web location reference is the URL of a file published on a web server, such as https://example.com/dids/issuer/did.jsonl.

The following requirements apply to a web location reference:

  • The value MUST be an absolute URL with the https or http scheme and a non-empty path, and MUST NOT include a fragment component.
  • The value MAY include a port, such as https://example.com:3000/dids/did.jsonl, and MAY include a query component, such as a signed URL from a storage service or a watcher operation (https://watcher.example.org/log?scid=<SCID>).
  • For https, the host MUST be a domain name, not an IP address. A host containing non-ASCII characters (an internationalised domain name) MUST be converted to its ASCII form (A-labels) as defined in IDNA2008 [RFC5891] before retrieval; a host that cannot be converted MUST cause the invalidOptions error.
  • For http, the host MUST be a loopback host: localhost, an IPv4 address in 127.0.0.0/8, or [::1]. An http reference with any other host MUST cause the invalidOptions error. An http reference is a loopback reference, intended for development and testing.
  • Each path segment, once percent-decoded, MUST NOT be . or .., and MUST NOT contain /, \ or NUL. The checks apply to the decoded form because percent-encoded variants such as %2E%2E, %2F, %5C and %00 would otherwise pass unnoticed. A segment that fails a check MUST cause the invalidOptions error.
  • A loopback reference is subject to the same restrictions as a local file reference: a Resolver that accepts requests from other systems MUST NOT retrieve from it and MUST return the invalidOptions error. A loopback reference would otherwise let a caller make a Resolver send requests to services on its own host.

To retrieve a file from a web location, the Resolver MUST make an HTTP GET request (HTTPS for an https reference) for the URL as given, following the requirements in Retrieving DID Log Resources. When retrieving from a loopback reference, the requirements in that section to use HTTPS and to reject loopback hosts do not apply.

Local Files§

A local file reference identifies a file on the system where the Resolver runs. It is for a Resolver used by a client on the same system — for example, a Resolver used as a library or command-line tool — such as a wallet that keeps the DID Logs it holds in local storage.

  • A local file reference MUST be a file: URL [RFC8089] with an absolute path, an empty host or the host localhost, and no query or fragment component. Each path segment, once percent-decoded, MUST NOT be . or .., and MUST NOT contain /, \ or NUL; a segment that fails a check MUST cause the invalidOptions error.
  • The Resolver MUST read the file named by the path. A file that does not exist or cannot be read is treated as not found.
  • A Resolver MUST treat the content of the file exactly as if it had been passed directly.
  • A Resolver that accepts requests from other systems — for example, over HTTP — MUST NOT read local files, and MUST return the invalidOptions error for a local file reference.

A local file reference is never derived from a DID URL (see The src DID URL Parameter). A DID URL can come from an untrusted party; allowing it to name local files would let such a party make a Resolver read files on its host.

Local file references and the corresponding files:

file:///var/lib/wallet/dids/QmfGEU.../did.jsonl --> /var/lib/wallet/dids/QmfGEU.../did.jsonl

file://localhost/home/alice/dids/QmfGEU.../did-witness.json --> /home/alice/dids/QmfGEU.../did-witness.json

Other Schemes§

A Resolver MAY support srcLog and srcWitness references using other URL schemes that name a file — for example, an ipns URL naming a file in an IPFS directory, or an ipfs URL naming a file by the hash of its content. For such a reference:

  • The value MUST NOT include a fragment component.
  • The Resolver MUST retrieve the resource the URL names, without changing its path.
  • A Resolver that does not support the scheme MUST return the featureNotSupported error.
  • A Resolver MUST apply to the retrieval protections equivalent to those required in Retrieving DID Log Resources, including to any gateway it uses to reach the scheme’s network.

Other scheme references:

ipns://k51qzi5uqu5d.../dids/issuer/did.jsonl

ipfs://bafybei.../did.jsonl

ipfs://bafkrei... (the DID Log file itself, by content hash)

Some schemes name immutable content. An ipfs URL names a file, or the directory holding it, by the hash of its content, so any change to the DID Log or witness proofs file — including witness proofs added after an entry — gives it a new identifier. An ipfs reference is therefore a snapshot, useful for archiving but never updated; an ipns name, which the DID Controller repoints to each new version, can serve the latest log. See Log Freshness and Duplicity.

Resolution Algorithm§

The following steps MUST be executed to resolve the DIDDoc for a did:vh DID:

  1. The DID. The did input MUST conform to the ABNF in Method-Specific Identifier; if it does not, return the invalidDid error.

  2. The options. Validate the resolutionOptions as defined in did:vh Resolution Options. If they are invalid, return the invalidOptions error.

  3. Getting the log. Get the DID Log according to how it was passed:

    The witness proofs file is needed only if the active parameters require witnesses. When it is, use the didWitness value if one was given, or retrieve the file from the srcWitness reference if one was given, as defined in The srcLog and srcWitness Options.

  4. Processing the log. Process the DID Log as described below.

  5. Other copies. If checkWatchers, extraWatchers or a minCopies greater than 1 was given, or the Resolver has retained a versionId from an earlier resolution of the DID, process the copies as described in Comparing Copies of a DID Log.

  6. Result. Return the requested DIDDoc (unless the DID is deactivated, as defined in Deactivate (Revoke)) with the metadata defined in DID Resolution Metadata, or the error listed there.

To process the DID Log, the Resolver MUST carry out the following steps on each of the log entries in the order they appear, applying the parameters from the current and previous entries. Every step MUST be performed for every entry; in particular, Data Integrity proof verification (step 2) and entryHash verification (step 3) MUST NOT be skipped for intermediate entries on the grounds that the Resolver only needs the latest DIDDoc.

An entry that does not meet a requirement of these steps, or of the sections they reference, fails verification. The Resolver MUST stop processing at the first entry that fails verification, and MUST then produce the result as defined in Results of Processing the Log.

NOTE: A Resolver implementation that caches previously verified state could process only subsequent entries and resume processing after the last verified entry rather than reprocessing the full log, provided the cached state was itself produced by full verification and the cache has not been modified since.

Even without caching state, a Resolver MAY retain the latest versionId it observes for each DID it resolves. Comparing a later copy of the DID Log against that versionId, as described in Comparing Copies of a DID Log, reveals a fork, truncation or rollback that has happened since the previous resolution.

As noted in the DID Log File section, log entries are each a JSON object with the following properties:

  1. versionId
  2. versionTime
  3. parameters
  4. state – the version’s DIDDoc.
  5. proof – a Data Integrity proof for the log entry.

For each entry:

  1. Update the currently active parameters with the parameters from the entry (if any). The parameters MUST adhere to the did:vh DID Method Parameters section of this specification. Continue processing using the now active set of parameters.
    • While all parameters in the first Log Entry take effect immediately, some kinds of parameters defined in later entries only take effect after that entry has been published. For example, updates to the witness parameter take effect only after the entry in which they are defined has been published.
  2. The Data Integrity proof in the entry MUST be valid and signed by an authorized key as defined in the Authorized Keys section of this specification, and with a proofPurpose set to assertionMethod.
    1. If the active updateKeys is empty — for example, after an entry that set updateKeys to [] — no key is authorized and the entry fails verification.
    2. If the DID Controller has opted to use witnesses, Resolvers MUST verify the DID’s witness proofs file. For details, see the DID Witnesses section of this specification.
  3. Verify the versionId for the entry.
    1. The version number MUST be 1 for the first entry and MUST equal the previous entry’s version number + 1 for each subsequent entry. Gaps (e.g., entry 3 after entry 1) MUST cause the entry to fail verification.
    2. Exactly one dash - MUST follow the version number; missing or multiple dashes MUST cause the entry to fail verification.
    3. The entryHash MUST follow the dash, MUST be a valid multihash in the algorithm permitted by the active method, and MUST be verified per Entry Hash Generation and Verification. Verification MUST be performed for every entry.
  4. The versionTime MUST be a valid UTC ISO8601 string with explicit Z (or +00:00); values without a zone designator, or expressing a non-UTC zone, MUST cause the entry to fail verification.
    • The versionTime MUST be in whole seconds. Values with fractional seconds MUST cause the entry to fail verification.
    • The versionTime of every entry MUST be strictly greater than the immediately preceding entry’s. Equal timestamps MUST cause the entry to fail verification.
    • The versionTime of every entry MUST NOT be more than a small, implementation-defined tolerance in the future relative to the Resolver's current time. Resolvers SHOULD use a tolerance of no more than 5 minutes. Entries that exceed this tolerance MUST cause the entry to fail verification.
  5. When processing the first DID log entry, verify the SCID (defined in the parameters) according to the SCID Generation and Verification section of this specification. The SCID MUST equal the SCID of the did input.
  6. Get the value of the log entry property state, which is the DIDDoc for the version. Its top-level id MUST be exactly did:vh: followed by the scid parameter of the first entry. This check MUST apply to every entry’s state.id, not just the first, and to every entry of any further copy retrieved with checkWatchers or extraWatchers. An entry with a mismatch fails verification.
  7. If Key Pre-Rotation is active (the previously active nextKeyHashes is non-empty), the entry being processed MUST include an explicit parameters.updateKeys and MUST NOT rely on inheritance. The hash of every multikey in parameters.updateKeys (computed per Pre-Rotation Key Hash Generation and Verification) MUST appear in the previous entry’s nextKeyHashes. The check applies to the full updateKeys set, not only keys that are new relative to the previous entry. A key not in the previous entry’s nextKeyHashes MUST cause the entry to fail verification, even if it appeared in an earlier entry’s updateKeys.
  8. If a previous entry set deactivated to true, the entry MUST be treated as failing verification, as defined in Deactivate (Revoke).
  9. As each log entry is processed and verified, collect the following information about each version:
    1. The DIDDoc.
    2. The versionId of the DIDDoc.
    3. The UTC versionTime of the DIDDoc.
    4. The latest list of active multikey formatted public keys authorized to update the DID, from the updateKeys lists in the parameters.
    5. If pre-rotation is being used, the hashes of authorized keys that are to be used in the updateKeys list of the next DID log entry. The pre-rotation hashes are in the nextKeyHashes list in the parameters.
    6. All other did:vh processing configuration settings as defined in the parameters object.
  10. If the parameters for any of the versions define that some or all of the DID Log entries require witnessing, the Resolver MUST also verify the witness proofs, as defined in the DID Witnesses section of this specification.
Results of Processing the Log§

Once the log entries have been processed as above, the Resolver MUST produce the result as follows. The valid entries are the entries before the first entry that failed verification, or all of the entries if none failed.

If processing stopped at an unsupported entry — one whose method value names a version of this specification the Resolver does not support — the entries before it are the valid entries, and the rules below apply with featureNotSupported in place of invalidDid. In step 3, the Resolver MUST return the featureNotSupported error rather than the DIDDoc of the last valid entry, because the unsupported entries may change the DIDDoc or its keys.

  1. If the first entry failed verification, the DID is invalid: return the invalidDid error.
  2. If a target version was requested, as defined in Selecting a Version:
    • if it is one of the valid entries, return its DIDDoc with a successful status, even if later entries failed verification;
    • if it is an entry that failed verification, or comes after one, return the invalidDid error;
    • if no entry matches, return the notFound error.
  3. Otherwise, return the DIDDoc of the last valid entry. If any entry failed verification, include the invalid-entries warning defined in DID Resolution Metadata.

The problemDetails of an invalidDid or featureNotSupported error, and the message of an invalid-entries warning, SHOULD identify the entry that failed verification (by version number, and versionId if it can be parsed) and the requirement it did not meet.

While caching policies are an implementation matter and largely outside the scope of this specification, Resolvers SHOULD NOT cache a DID that fails verification. This ensures that the DID Controller has the opportunity to recover a DID that may have been erroneously or maliciously invalidated.

Comparing Copies of a DID Log§

A Resolver retrieves further copies of the DID Log when the client asks it to, using the checkWatchers, extraWatchers and minCopies resolution options. These options let a client check the DID Log it passed against other copies, to detect a copy that is out of date, has been tampered with, or has been forked. They apply as follows:

  1. The copy passed directly or by reference is processed as defined in the Resolution Algorithm.
  2. If checkWatchers is greater than 0, the Resolver reads the watchers parameter active at the last entry of the verified copy. If checkWatchers is all, or is not less than the number of listed watchers, the Resolver MUST retrieve a copy from every listed watcher. Otherwise, it MUST retrieve a copy from that many listed watchers, and SHOULD choose them at random, so that which watchers are checked cannot be predicted.
  3. The Resolver MUST retrieve a copy from each watcher in extraWatchers.
  4. Copies are retrieved from a watcher using the Watcher HTTP API Operations and the SCID of the DID: the DID Log from <WATCHER URL>/log?scid=<SCID> and, if witnesses are active, the witness proofs file from <WATCHER URL>/witness?scid=<SCID>. All retrievals MUST follow Retrieving DID Log Resources.
  5. All copies are compared as described below, and each is reported in copies in the DID Resolution Metadata.
  6. If fewer than minCopies copies have a status of current or behind, the Resolver MUST fail resolution with the insufficientCopies error. The copy passed directly or by reference counts towards minCopies.

A copy that cannot be retrieved, because the watcher is unreachable, does not hold the DID Log, or returns an error, does not by itself fail resolution. It is reported with status unavailable and a copy-unavailable warning, and does not count towards minCopies.

extraWatchers causes the Resolver to retrieve from URLs supplied by its caller. A Resolver offered as a service to other parties MAY refuse, or limit the number of, extraWatchers URLs. A URL that is not retrieved for this reason MUST be reported with status unavailable and a copy-unavailable warning stating that it was refused.

These options apply even when a target version is selected, because a forked log fails resolution for every version, as described below.

A Resolver MAY retain the latest versionId it has verified for each DID it resolves — the versionId of the last valid entry of the reference copy — and use it when it next resolves the DID. A Resolver that does so MUST compare it with the reference copy as defined in step 3 below. Retention is optional: a Resolver that retains no state conforms to this specification, but detects a fork, truncation or rollback only among the copies it is given in a single resolution. A retained versionId records which DIDs the Resolver has resolved; see Surveillance.

A Resolver that has more than one copy of a DID Log, or that has retained a versionId from a previous resolution of the DID, need not verify every copy in full. Instead, it MUST:

  1. Use the copy passed directly or by reference as the reference copy, once it has been fully verified.
  2. Compare each remaining copy to the reference copy by checking a single versionId in each:
    • If the copy has the same number of entries or fewer: compare the versionId of the copy’s last entry with the reference copy’s versionId for the same version number. If they match, the copy is the same log, possibly out of date, and needs no further verification.
    • If the copy has more entries: compare the versionId of the reference copy’s last entry with the copy’s versionId for the same version number. If they match, the copy extends the reference copy. Verify only the copy’s additional entries, starting from the state reached at the reference copy’s last entry. If they pass verification, the copy becomes the reference copy. If they fail, discard the copy.
    • If the versionId values do not match: the copy diverges from the reference copy. Verify it in full. If it fails verification, discard it. If it passes verification, the log has been forked, and the Resolver MUST fail resolution as described below.
  3. If the Resolver has retained a versionId from a previous resolution of the DID, compare it with the reference copy’s versionId for the same version number. The retained versionId was verified when it was first observed, so it needs no further verification.
    • If the reference copy has fewer entries than the retained version number: there is no entry to compare. Every copy is older than the log previously observed, so the log has been truncated or rolled back, or diverges at an entry the Resolver cannot compare. The copy may simply be stale — for example, an older copy held by the client or a peer — so the Resolver MUST NOT fail resolution for this reason, and MUST include the retained-version-not-found warning described in DID Resolution Metadata.
    • If they match: the reference copy is the log previously observed, or an extension of it.
    • If they do not match: the log has been forked, and the Resolver MUST fail resolution as described below. In place of the first differing entry, the report MUST include the retained versionId and the reference copy’s versionId for the same version number.

A copy already found to match the reference copy still matches when a longer copy replaces it, because the longer copy extends the earlier reference copy; earlier comparisons need not be repeated. When every copy and any retained versionId have been compared, the Resolver resolves from the reference copy.

If two or more copies of a DID Log pass verification but diverge, the log has been forked by a party holding authorized keys, and no copy can be relied on. The Resolver MUST fail resolution with the logForked error, including for a requested version that precedes the point of divergence. The problemDetails MUST identify each diverging copy (for example, by the location it was retrieved from) and MUST include the version number of the first log entry at which the copies differ and each copy’s versionId for that entry. The Resolver does not choose between the copies; see Forked Logs.

These checks rely on two properties of the DID Log. Each entry hash covers the previous entry’s versionId, so equal versionId values at entry k mean the two copies commit to the same history up to and including entry k. And because a versionId begins with its version number, entry k is always on line k of the log, so each comparison reads a single known line of each copy rather than searching for the versionId.

Watchers listed in the DID Log are chosen by the DID Controller. Checking them detects a source that is out of date or has been altered, but may not detect a DID Controller that deliberately gives different parties different logs, since such a DID Controller could list watchers it controls. extraWatchers lets a client use watchers it chooses itself, such as its own or those run by its ecosystem, which is a stronger check.

Selecting a Version§

A request to resolve a did:vh DID MAY specify a target version using one of the versionId, versionTime or versionNumber resolution options.

  • By versionId: the log entry whose versionId is exactly equal to the given value.
  • By versionTime: the log entry that was active at the given ISO8601 time — the entry with the latest versionTime that is not later than the given time.
  • By versionNumber: the log entry whose version number — the integer that precedes the - in its versionId — equals the given positive integer.

If no log entry matches, the Resolver MUST return the notFound error.

Selecting by version number is less safe than selecting by versionId. A versionId includes the entry hash, so it identifies the content of exactly one log entry. A version number identifies an entry only within the copy of the log being resolved: if two diverging copies of a DID Log exist, did:vh:<SCID>?versionNumber=3 can resolve to a different DIDDoc for different parties, while did:vh:<SCID>?versionId=3-Qm... resolves to one DIDDoc or fails. Where a reference needs to identify exactly one version — for example, to record which version of the DIDDoc was relied on — versionId is the safer choice.

DID Resolution Metadata§

As defined in [DID-RESOLUTION], a did:vh Resolver SHOULD return the following DID Document Metadata:

{
  "versionId": "1-QmRRaLXwc6BjBuBPosSupJwEQ8w9f3znP7yfbpGfwcnLr6",
  "versionTime": "2025-01-23T04:12:36Z",
  "created": "2025-01-23T04:12:36Z",
  "updated": "2025-01-23T04:12:36Z",
  "scid": "QmPEQVM1JPTyrvEgBcDXwjK4TeyLGSX1PxjgyeAisdWM1p",
  "deactivated": false,
  "ttl": 3600,
  "witness": { ... },
  "watchers": [ ... ]
}

where the items in the metadata are:

“Active” means as set by the last valid DID log entry. That is the last entry in the DID Log unless later entries fail verification, in which case it is the last entry before the first failure.

Metadata values have the same data types as the parameters and log entry properties they come from. updated, and the values marked active, reflect the DID Log passed to the Resolver, which may not be the latest (see Log Freshness and Duplicity).

The following items describe the resolution rather than the DID, so they are returned in the didResolutionMetadata, not the DID Document Metadata:

  • didLog — If includeDidLog was true and resolution succeeded, the DID Log the Resolver resolved from, as a JSON Lines string in the same form as the didLog resolution option. It is the reference copy (see Comparing Copies of a DID Log), which may be longer than the copy the client passed, ending at its last valid entry. It MUST NOT be shortened to a requested target version, and MUST NOT include entries that failed verification.
  • didWitness — If includeDidLog was true, resolution succeeded and the DID Log requires witnesses, the witness proofs file the Resolver used, as a JSON array in the same form as the didWitness resolution option. The Resolver MAY omit items whose versionId is not in the returned didLog, and MAY omit proofs that failed verification.

The returned didLog and didWitness can be passed unchanged to a later resolution of the DID, so a client can keep the verified files — for example, to resolve the DID again without retrieving them, to pass them to another party, or to send them to a watcher — without retrieving them separately. When resolution fails, neither is returned.

  • copies — If the Resolver retrieved, or attempted to retrieve, more than one copy of the DID Log, a list with one item for each copy. A Resolver given checkWatchers, extraWatchers or a minCopies greater than 1 MUST include copies. Each item has:
    • source — Where the copy came from: the srcLog value, didLog for a log passed directly, or the URL of the watcher that served it.
    • versionId — The versionId of the copy’s last log entry. Absent if status is unavailable.
    • status — One of current (the copy’s last log entry is the last entry of the reference copy), behind (the copy matches the reference copy but has fewer entries), invalid (the copy failed verification and was discarded) or unavailable (the copy could not be retrieved, or the Resolver declined to retrieve it).
  • warnings — A list of conditions found during resolution that did not prevent it. A Resolver SHOULD include an item for each of the following conditions, with a code from the list below and a human-readable message, identifying the copy it concerns by its source, where there is one:
    • copy-behind — A copy has status behind. The message includes how many entries the copy is behind the reference copy.
    • copy-invalid — A copy has status invalid. The message includes the version number of the first log entry that failed verification.
    • copy-unavailable — A copy has status unavailable. The message says why, such as the watcher being unreachable, not holding the DID Log, or the Resolver refusing the URL.
    • invalid-entries — Some log entries at the end of the reference copy failed verification, so resolution used the last valid entry.
    • retained-version-not-found — The reference copy has fewer entries than a versionId retained from a previous resolution of the DID, as described in Comparing Copies of a DID Log.
{
  "contentType": "application/did+json",
  "copies": [
    {
      "source": "https://example.com/dids/issuer",
      "versionId": "3-QmRRaLXwc6BjBuBPosSupJwEQ8w9f3znP7yfbpGfwcnLr6",
      "status": "current"
    },
    {
      "source": "https://watcher.example.org",
      "versionId": "2-QmPEQVM1JPTyrvEgBcDXwjK4TeyLGSX1PxjgyeAisdWM1p",
      "status": "behind"
    },
    {
      "source": "https://watcher.example.net",
      "status": "unavailable"
    }
  ],
  "warnings": [
    {
      "code": "copy-behind",
      "source": "https://watcher.example.org",
      "message": "Copy is 1 entry behind the reference copy."
    },
    {
      "code": "copy-unavailable",
      "source": "https://watcher.example.net",
      "message": "Watcher did not respond."
    }
  ]
}

When a DID resolution error occurs, the error field MUST be included in the didResolutionMetadata, as defined in [DID-RESOLUTION], and Resolvers SHOULD include supplemental “Problem Details” metadata following [RFC9457], using the following structure:

"didResolutionMetadata": {
  "error": "invalidDid",
  "problemDetails": {
    "type": "https://w3id.org/security#INVALID_CONTROLLED_IDENTIFIER_DOCUMENT_ID",
    "title": "The resolved DID is invalid.",
    "detail": "The SCID in state.id of entry 3 does not match the SCID of the DID."
  }
}

The following error values MUST be used under the corresponding conditions. The first four are from [DID-EXTENSION-RESOLUTION]; logForked and insufficientCopies are did:vh-specific, and are to be registered there.

  • invalidDid — The DID is malformed, or the DID Log passed to the Resolver (or the requested version) fails verification.
  • invalidOptions — A resolution option is malformed or not permitted, including a local file or loopback reference passed to a Resolver that accepts requests from other systems.
  • notFound — The DID Log was not found through the srcLog reference, the requested version does not exist, or the resource referenced by a DID URL was not found.
  • featureNotSupported — The Resolver declined to retrieve from a srcLog or srcWitness reference, does not support the scheme of such a reference, does not support versionNumber, checkWatchers, extraWatchers, minCopies or includeDidLog, or does not support the version of this specification named in a method parameter of the DID Log.
  • logForked — Two copies of the DID Log both pass verification but diverge, as defined in Comparing Copies of a DID Log. The problemDetails MUST include the fork report that section requires.
  • insufficientCopies — Fewer than minCopies copies of the DID Log were retrieved and matched.

Resolvers SHOULD populate the problemDetails field to aid in diagnosing and understanding resolution failures, without including internal stack traces, file paths, or library versions.

Reading did:vh DID URLs§

The src, versionId, versionTime and versionNumber DID URL query parameters can be used with a did:vh DID, such as did:vh:<SCID>?src=https://example.com/dids/issuer&versionNumber=2. src is a DID URL parameter only: it names the location holding both files, from which the dereferencer derives the srcLog and srcWitness resolution options, as defined in The src DID URL Parameter. didLog, didWitness, srcLog, srcWitness, checkWatchers, extraWatchers, minCopies and includeDidLog are resolution options only, and MUST NOT be used as DID URL query parameters.

When a did:vh DID URL is dereferenced, the DID URL dereferencer (the client of the Resolver) decides which of these parameters to use when calling resolve:

  • It SHOULD pass a versionId, versionTime or versionNumber DID URL parameter as the resolution option of the same name. These select a version as defined in Selecting a Version.
  • It MAY apply its own policy to a valid src value — for example, using it only if it names a location the dereferencer trusts, or ignoring it in favour of a copy of the DID Log it already has. If it uses the src value, it derives the file URLs as defined in The src DID URL Parameter and passes them by reference in srcLog and srcWitness, or retrieves the files itself and passes them directly in didLog and didWitness.

The src parameter never changes which version is returned.

The src DID URL Parameter§

The src (“source”) DID URL parameter names the location where did.jsonl and, if witnesses are active, did-witness.json are published. It is equivalent to the src parameter of did:scid when its value is an https URL.

The following requirements apply to a src DID URL parameter:

  • It MUST be percent-encoded as required for a query parameter value by [RFC3986] (Section 3.4 and, for characters that conflict with delimiters such as & and =, Section 2.2), and a DID URL MUST NOT include more than one. The dereferencer MUST percent-decode it once before validating it.
  • Its value MUST be an absolute URL [RFC3986] with no query or fragment component, using either the https scheme or another scheme with hierarchical paths (such as ipns).
  • An https value MUST meet the requirements for an https web location, except that its path MAY be empty. After any trailing / is removed, each path segment, once percent-decoded, MUST be non-empty and MUST NOT begin or end with whitespace.
  • It MUST NOT be a file: URL or an http URL. A DID URL can come from an untrusted party; allowing it to name local files or loopback hosts would let such a party make a Resolver read files or send requests on its own host.
  • The dereferencer MUST return the invalidDidUrl error for a src value that does not meet these requirements, and MUST NOT pass any reference derived from it to the Resolver.

To derive the srcLog and srcWitness values from a src value, the dereferencer MUST:

  1. Take the src value, removing any trailing /.
  2. Append /did.jsonl. The result is the srcLog value.
  3. Append /did-witness.json to the value from step 1. The result is the srcWitness value.

The same rule applies to every scheme and to a src value with no path; no /.well-known/ location is used.

The dereferencer passes both values; as defined in The srcLog and srcWitness Options, the Resolver retrieves the witness proofs file only if it needs it.

For an https value with a path, a src value names the same location as the domain and path of a did:webvh DID.

src values and the corresponding srcLog values:

https://example.com --> https://example.com/did.jsonl

https://example.com/.well-known --> https://example.com/.well-known/did.jsonl (a /.well-known/ location is used only when it is in the src value)

https://example.com/dids/issuer --> https://example.com/dids/issuer/did.jsonl

https://example.com:3000/dids/issuer --> https://example.com:3000/dids/issuer/did.jsonl

https://example.com/users/{SCID} --> https://example.com/users/{SCID}/did.jsonl

ipns://k51qzi5uqu5d.../dids/issuer --> ipns://k51qzi5uqu5d.../dids/issuer/did.jsonl

ipfs://bafybei.../ --> ipfs://bafybei.../did.jsonl

Because a location can hold only one did.jsonl, a DID Controller publishing several did:vh DID Logs in one place SHOULD give each its own location (a URL path). Using the SCID as the last path segment is a simple way to do so.

Update (Rotate)§

To update a DID, the DID Controller generates a new, verifiable DID Log Entry, has it witnessed (if necessary), appends it to the existing DID Log (did.jsonl), and distributes the result. The process to generate a verifiable DID Log Entry follows a similar process to the Create process, as follows:

  1. Make the desired changes to the DIDDoc. The top-level id in the DIDDoc MUST remain did:vh:<SCID>. See the note on future use by did:scid:vh for how this may change in a later version.
  2. Define the parameters JSON object to include the properties that affect the evolution of the DID. The parameters MUST be from those listed in the did:vh DID Method Parameters section of this specification. Any parameters defined in the JSON object override the previously active value, while any parameters not included imply the existing values remain in effect. If no changes to the parameters are needed, an empty JSON object {} MUST be used.
    • While all parameters in the first Log Entry take effect immediately, some types of parameters defined in later entries only take effect after the entry has been published. For example, rotating the keys authorized to update a DID or changing the witnesses for a DID take effect only after the entry in which they are defined has been published.
  3. Generate a preliminary DID log entry JSON object containing the following properties:
    1. The value of versionId MUST be the value of versionId from the previous DID log entry.
    2. The versionTime value MUST be a string that is an ISO8601 format UTC timestamp in whole seconds. The time MUST be greater than the time of the previous log entry, and MUST be the time the entry will be retrieved by a witness or Resolver, or before.
    3. The parameters passed in as a JSON object.
    4. Set the state JSON object to be the new version of the DIDDoc.
  4. Calculate the new versionId of the new DID Log Entry, including incrementing the version number integer and using the process described in the Entry Hash Generation and Verification section of this specification.
  5. Replace the value of the versionId property in the preliminary DID Log Entry with the value produced in the previous step.
  6. Generate a Data Integrity proof on the DID log entry using an authorized key, as defined in the Authorized Keys section of this specification, and the proofPurpose set to assertionMethod.
  7. If Key Pre-Rotation is being used, the hash of all updateKeys entries in the parameters property MUST match a hash in the array of nextKeyHashes parameter from the previous DID log entry, as defined in the Pre-Rotation Key Hash Generation and Verification section of this specification.
  8. The proof JSON object MUST be added as the value of the proof property in the log entry.
  9. The entry MUST be made a JSON Line by removing extra whitespace, adding a \n to the entry.
  10. If the DID Controller opts to use witnesses for the DID, the DID Controller MUST collect the threshold of proofs from the DID’s witnesses, and update the DID’s witness proofs file. The updated witness proofs file MUST be made available BEFORE the updated DID Log is distributed. See the DID Witnesses section of this specification.
  11. The new log entry MUST be appended to the existing contents of the DID Log.
  12. The DID Controller SHOULD make the updated DID Log available through every DID Log source where it previously made the log available: updating each web location, notifying watchers (see DID Watchers), and sending it to peers.

A DID Controller MUST only distribute a DID Log that extends the log it most recently distributed: every distributed log entry is retained, and the new log entry's predecessor is the last distributed log entry. A DID Controller MUST NOT distribute, or give to any party, two different log entries with the same predecessor.

Applying Peer-to-Peer Updates§

When DID Logs are exchanged peer-to-peer, each party holds the only copies of the other’s log, and an update can carry only the new entries. A party that receives new DID log entries for a DID Log it holds MUST apply them as follows:

  1. Skip any received entry whose versionId is identical to that of an entry it already holds. If a received entry has the same version number as a held entry but a different versionId, the update is duplicitous and MUST be rejected.
  2. Append the remaining entries, in order, to a copy of the held DID Log.
  3. Resolve the DID with that copy as didLog, the received witness proofs file (or, if none was received, the held one) as didWitness, and the versionId of the last appended entry as versionId.
  4. If resolution succeeds, replace the held DID Log and witness proofs file with the ones used in step 3. Otherwise, reject the update and keep the held files unchanged.

A party SHOULD keep a rejected update as evidence of duplicity.

No second copy of the log is needed to detect an update that does not extend the held log. The entry hash of each entry is calculated with the versionId of the previous entry as input, so an appended entry verifies only if it continues from the last held entry. Requesting the versionId of the last appended entry in step 3 ensures that resolution fails, rather than returning an earlier version, if any appended entry is invalid.

Deactivate (Revoke)§

Deactivating a DID allows a DID Controller to signal that the DID is no longer being maintained or updated. There is an explicit approach to deactivation that aligns with the [DID-CORE] specification, and another approach that a did:vh DID Controller can use if the [DID-CORE] approach does not achieve their desired outcome.

To deactivate a did:vh DID per the [DID-CORE] specification, the DID Controller MUST add to the DID log entry parameters the property name and value "deactivated": true. That entry is the last log entry of the DID: a Resolver MUST treat any log entry after it as failing verification. Once a DID is deactivated, a Resolver MUST NOT return the DIDDoc and MUST include "deactivated": true in the DID Document Metadata. Because no entry can follow the deactivating entry, there is no need to also remove the authorized keys when deactivating.

To resolve a prior version of a deactivated did:vh DID, a client can use the versionId, versionTime or versionNumber resolution options. When a prior version is resolved in this way, the DID Document Metadata MUST include "deactivated": true.

A concern with using the [DID-CORE] approach to deactivation is the resolver requirement that the DIDDoc not be returned for a deactivated DID. A DID Controller might want the final DIDDoc to continue to be resolved, while also signaling that the DID is no longer being updated. An alternative is to set the updateKeys array to empty ([]) without setting the deactivated parameter to true. The final DIDDoc then continues to be returned by default, and no further entry can be signed: a Resolver treats any entry after it as failing verification, as defined in Authorized Keys, just as it does any entry after a deactivating entry. If the DID is using pre-rotation, this takes two DID log entries: the first to stop the use of pre-rotation by setting nextKeyHashes to [], and the second to set updateKeys to []. One entry is not enough, because an entry verified with pre-rotation active is signed by a key in its own updateKeys, so an entry with empty updateKeys could not be signed.

Unlike did:webvh, removing a published DID Log does not effectively deactivate a did:vh DID, because copies may be held by watchers, peers, and other sources. A DID Controller that wants to retire a DID SHOULD deactivate it explicitly and distribute the final log, so that all sources report the deactivation. Watchers holding a DID whose published log has been removed SHOULD continue to cache its last known valid state. See Log Freshness and Duplicity for why a Resolver may not see the deactivation immediately.

Sourcing the DID Log§

This section is non-normative.

A did:vh Resolver resolves the DID Log it is given. Before calling resolve, the client therefore needs to source the DID Log: it either obtains the DID Log and witness proofs themselves, which it passes directly in didLog and didWitness, or learns references to where they are stored, which it passes in srcLog and srcWitness. In this specification, “source” covers both outcomes, while “obtain” and “retrieve” mean getting the files themselves. How the client sources the log depends on how it received the DID. Each place it can source the DID Log from is a DID Log source; this section describes the common ones. They can be combined, and a DID Log sourced from any of them is verified by the Resolver in exactly the same way.

Known in Context§

In many uses, a client already has the DID Log, or knows where to get it, because of the context in which it received the DID. For example:

  • A log sent with the DID. A protocol that carries a DID — such as a credential or presentation exchange — also carries the DID Log and witness proofs, or web locations for them. The client passes them directly, or passes the web locations by reference in srcLog and srcWitness.
  • An ecosystem DID host. An ecosystem requires its participants to publish their did:vh DID Logs to a registry or database it operates. The client retrieves the files from the host and passes them directly, or passes the files’ web locations on the host by reference in srcLog and srcWitness.
  • A previously resolved log. The client kept the files from an earlier resolution — for example, as returned with the includeDidLog resolution option — and passes them directly, or by reference to the local files where it keeps them — perhaps after checking another source for newer entries.
  • A DID URL with a src parameter. The client received a DID URL such as did:vh:<SCID>?src=https://example.com/dids/issuer, and uses the location as described in Reading did:vh DID URLs.

From Watchers§

A watcher retrieves, verifies, archives and re-serves DID Logs, indexed by SCID. Because a did:vh DID is its SCID, a client that knows of a watcher holding the DID — for example, one its ecosystem uses — can retrieve:

  • the DID Log with GET <WATCHER URL>/log?scid=<SCID>, and
  • if witnesses are active, the witness proofs file with GET <WATCHER URL>/witness?scid=<SCID>.

These are operations defined in Watcher HTTP API Operations. The client then passes the files directly, or passes these operation URLs by reference in srcLog and srcWitness, for example "srcLog": "https://watcher.example.org/log?scid=<SCID>".

Instead of retrieving from watchers itself, a client can pass the copy it has and ask the Resolver to check it against watchers, using the checkWatchers option for watchers listed in the log and the extraWatchers option for others. See Comparing Copies of a DID Log.

Once a client has resolved the DID, the watchers metadata lists the watchers the DID Controller has chosen. A client can use them to check for newer entries, for example when the copy it holds may be out of date. A client is not limited to those watchers: any party can run its own watcher, or use one its ecosystem operates, and send it the DID Logs it relies on. See Log Freshness and Duplicity.

Peer-to-Peer Exchange§

Two or more parties can use did:vh DIDs with one another by exchanging DID Logs directly, in the manner of did:peer [DID-PEER], without publishing them anywhere. Unlike did:peer, the DIDs keep all the did:vh features, including key rotation and pre-rotation. Each party keeps the other’s DID Log (and witness proofs file, if witnesses are active), and its client passes them directly, or by reference to the local files where it keeps them.

Initial exchange. The DID Controller gives the other parties the complete DID Log from the first entry, and the witness proofs file if witnesses are active.

Updates. When the DID is updated, the DID Controller sends each party either the complete DID Log or just the new DID log entry. Sending just the new entry keeps updates small, and works when each party receives every update in turn; a party that has missed an update cannot apply it, and needs the complete DID Log. If the new entry requires witnessing, the DID Controller also sends the complete current witness proofs file; otherwise that is optional. The protocol used to send updates is outside the scope of this specification.

Applying an update. A party receiving new entries applies them as defined in Applying Peer-to-Peer Updates. Because each entry hash chains to the previous entry, this rejects any entry that does not continue from the log the party holds, without needing a second copy of the log.

A did:vh DID used only peer-to-peer can be created for each relationship, so that no identifier is shared between relationships.

From a Web Location§

A client that learns a web location where the DID Controller publishes the DID Log can pass the files there by reference in the srcLog and srcWitness options, or retrieve them itself and pass them directly. A client can learn such a location from a src DID URL query parameter (deriving the file URLs as defined in The src DID URL Parameter), from an alsoKnownAs entry in a previously resolved DIDDoc (see Advertising DID Log Sources), or from the context in which it received the DID.

Advertising DID Log Sources§

A DID Controller can tell others where current copies of the DID Log are kept:

  • The watchers parameter lists watchers that archive the log.
  • The DIDDoc alsoKnownAs property can include did:vh DID URLs for the same DID with a src parameter, one for each location where the DID Log is published (a web location, or another scheme such as ipns), as in did:scid. Each location listed this way is expected to hold the same DID Log, although some may briefly lag others while an update is distributed.
"alsoKnownAs": [
  "did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ?src=https://example.com/dids/issuer",
  "did:vh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ?src=https://backup.example.org/{SCID}"
]

Both are available only after the DID has been resolved at least once, so they serve to check for newer entries rather than to source the log in the first place.

Log Freshness and Duplicity§

A did:vh DID Log has no single authoritative location, so a client faces two risks that did:webvh handles by trusting the DID’s web location:

  • Staleness. A source may hold an older, shorter copy of the log, and so miss updates such as a key rotation or deactivation. A Resolver verifies the log it is given, but cannot know whether newer entries exist elsewhere.
  • Duplicity. A DID Controller, or an attacker holding its keys, could create two different extensions of the same log and show different ones to different parties.

For two verified copies of a DID Log for the same DID, log B extends log A if B contains every entry of A, in the same positions, with the same versionIds. Since each versionId includes a hash chained to the previous entry, it is enough to check that B contains an entry with the versionId of A’s last entry, at the same position.

A client that needs the current version of a DID can reduce the risk of staleness by sourcing the log from a source expected to be current — such as a watcher listed in the log — rather than relying only on a cached copy or a copy supplied by the party presenting the DID. The ttl metadata indicates how long the DID Controller expects a copy to stay current.

A client that obtains copies from more than one source can compare them. If one extends the other, the longer is the more current. If neither extends the other, the log is duplicitous, and no version of it can be relied on — the copies agree on their earlier entries, but whoever created the fork could have signed those too. The client can keep the conflicting entries as evidence and report them, for example to watchers. A client can also have the Resolver make these comparisons, with the checkWatchers, extraWatchers and minCopies resolution options; the Resolver then fails with logForked for every version if the log has been forked (see Forked Logs).

Witnesses and watchers address duplicity in different ways: witnesses are expected to approve only an entry that extends their own copy of the log, but no one else can confirm that they do, while watchers detect conflicting copies directly, but only the copies they see. For did:vh these matter more than for did:webvh, because there is no web location to act as the reference copy. A relying party that runs its own watcher, or uses one its ecosystem operates, gets a check that is independent of the DID Controller; extraWatchers lets it name such watchers when resolving. DID Controllers of did:vh DIDs that are relied on by many parties are encouraged to use witnesses and watchers, and parties relying on such DIDs are encouraged to use watchers they trust.

DID Method Processes§

The DID Method Operations reference several processes that are executed during DIDDoc generation and DID resolution verification. Each of those processes is specified in the following sections.

did:vh DID Method Parameters§

All did:vh Log entries contain the JSON object parameters. This object defines the DID processing parameters used by the DID Controller when creating the current and subsequent DID log entries. Resolvers MUST use the same parameters to process the DID Log to resolve the DID. The parameters object MUST only include properties defined in the version of the did:vh DID Method specification being used.

General Rules for Parameters:

  • Default Values: When the method parameter (see below) sets the [SEMVER] version of this specification to be used for a DID, any parameter introduced by that version but not explicitly set in the same log entry MUST assume the default value defined in this section. The method parameter appears in the first log entry, and can appear in later entries to upgrade the DID to a newer [SEMVER] version of the did:vh specification, as defined below.

  • Allowed Values: Each parameter is constrained by the data type, structure and allowed values specified in this section. If a value does not conform, the parameter is invalid and MUST cause the log entry to fail verification.

  • Deactivation: Parameters that support deactivation (such as witness or nextKeyHashes) are set to defined values, described below, to indicate they are no longer active.

  • The JSON null value MUST NOT be used to indicate default or deactivated values, as it removes the typing information required for proper interpretation.

An example of the parameters property in the first DID Log entry:

{
  "method": "did:vh:1.0",
  "scid": "{SCID}",
  "updateKeys": [
    "z82LkqR25TU88tztBEiFydNf4fUPn8oWBANckcmuqgonz9TAbK9a7WGQ5dm7jyqyRMpaRAe"
  ],
  "nextKeyHashes": [
    "enkkrohe5ccxyc7zghic6qux5inyzthg2tqka4b57kvtorysc3aa"
  ]
}

The following lists the parameters, their data types, and enumerated values.

  • method: Specifies the did:vh [SEMVER] specification version to be used for processing the DID’s log. Each acceptable value in turn defines what cryptographic algorithms are permitted for the current and subsequent DID log entries. An update to the specification version in the middle of a DID Log could introduce new parameters.
    • MUST appear in the first log entry and MUST be one of the enumerated acceptable values below.
    • A method value MUST be did:vh: followed by a major and minor version number, each a non-negative integer with no leading zeros, separated by . (for example, did:vh:1.0). An entry with a method value not of this form MUST fail verification.
    • A Resolver MUST NOT process an entry whose method value is of this form but is not one of the acceptable values for the version(s) of this specification the Resolver supports, or any later entry. Such an entry is unsupported, and the result is as defined in Results of Processing the Log. Unknown values MUST NOT be silently downgraded, defaulted, or ignored.
    • If not present in later entries, the previous value continues to be active.
    • MAY appear in later entries to upgrade the spec version. A change to a lower version than currently active MUST cause the entry to fail verification.
    • Acceptable values:
      • did:vh:1.0
        • Permitted hash algorithms: SHA-256 [RFC6234] (multihash code 0x12) only. Any other algorithm MUST cause the entry to fail verification.
        • Permitted Data Integrity cryptosuites for both log-entry proofs and witness proofs: exactly eddsa-jcs-2022 [DI-EDDSA-V1.0]. Resolvers MUST verify the proof’s cryptosuite property; an absent, mismatched, or non-conformant cryptosuite MUST cause the entry to fail verification. Verifying only proofPurpose is insufficient.
  • scid: The SCID value for the DID.
  • updateKeys: A JSON array of multikey formatted public keys associated with the private keys that are authorized to sign the log entries that update the DID. See the Authorized Keys section of this specification for additional details.
    • This property MUST appear in the first log entry and MAY appear in subsequent entries.
    • If not present in later DID log entries, the previous value continues to apply.
    • A key from the active updateKeys array MUST be used to authorize each log entry, where active is defined as follows.
    • updateKeys MAY be set to an empty array [] to stop further updates without deactivating the DID. Any log entry after one whose updateKeys is in effect as [] MUST fail verification, as defined in Authorized Keys. See the deactivate section of this specification for more details.
  • nextKeyHashes: A JSON array of strings that are hashes of multikey formatted public keys that MAY be added to the updateKeys list in the next log entry. At least one entry of nextKeyHashes MUST be added to the next updateKeys list.
    • The process for generating the hashes and additional details for using pre-rotation are defined in the Pre-Rotation Key Hash Generation and Verification section of this specification.
    • If not set in the first log entry, its value defaults to an empty array ([]).
    • It can be omitted from a later log entry only while Key Pre-Rotation is not active, and its value then remains []. Its value is never inherited while pre-rotation is active, because it MUST then be present in every entry (see below).
    • Once an entry sets nextKeyHashes to a non-empty array, Key Pre-Rotation is active for every subsequent entry, as defined in Authorized Keys. While active, both nextKeyHashes AND updateKeys MUST be present as explicit properties in every subsequent log entry until pre-rotation is deactivated (by setting nextKeyHashes to []). A subsequent entry that omits either MUST fail verification, even if the omission would otherwise inherit the previous value. Inheritance of updateKeys is never permitted while pre-rotation is active — that bypass would defeat the pre-rotation commitment.
    • While Key Pre-Rotation is active, every multikey in the current entry’s updateKeys (not only those that appear new) MUST have its hash in the previous entry’s nextKeyHashes.
    • A DID Controller MAY include extra hashes in the nextKeyHashes array that are not subsequently used in an updateKeys entry. Any unused hashes in nextKeyHashes arrays are ignored.
    • The value of nextKeyHashes MAY be set to an empty array ([]) to deactivate pre-rotation. For additional details about turning off pre-rotation, see the Pre-Rotation Key Hash Generation and Verification section of this specification.
  • witness: A JSON object declaring the set of witnesses and threshold number of witness proofs required to update the DID. For details of this data and its usage in the DID update approval process, see the DID Witnesses section of this specification.
    • Defaults to {} if not set in the first log entry.
    • If not set in other log entries, its value is retained from the most recent prior value.
    • If the witness property is updated from {}, the change is immediately active, and the corresponding log entry MUST be witnessed.
    • The witness parameter MAY be set to {} to indicate that witnesses are not (or no longer) being used. If witnesses are active when the witness parameter is set to {}, that log entry MUST be witnessed.
  • watchers: An optional entry whose value is a JSON array containing a list of URLs ([RFC9110]) of watchers that have notified the DID Controller that they are willing to watch the DID. See the DID Watchers section of this specification for more details.
    • Defaults to [] if not set in the first log entry.
    • If not set in other log entries, its value is retained from the most recent prior value.
    • MAY be set to an empty array [] to indicate that watchers are not (or no longer) being used.
  • deactivated: A JSON boolean that indicates whether the DID has been deactivated. See the deactivate (revoke) section of this specification for more details.
    • Defaults to false if not set in the first DID log entry.
    • If set to true, the DID is deactivated, and the entry that sets it MUST be the last log entry of the DID.
  • ttl: An unsigned integer that indicates how long, in seconds, the DID Controller expects a Resolver or client to cache the resolved did:vh DID before refreshing. It provides guidance from the DID Controller on cache duration, with a range of 0 to 231 - 1 (2,147,483,647). The parameter is analogous to the TTL parameter used in DNS [RFC2181]. Caching a did:vh can be valuable in places where the business rules require resolving a number of DID URLs for the same DID. For example, a client might want to call the Resolver to get the current DIDDoc, and then make repeated calls to get all of the previous versions of the DIDDoc. By caching the DIDDoc state, the Resolver would not have to retrieve and process the DID Log on each call. For did:vh, ttl is also a hint about how long a copy of the DID Log can be expected to stay current (see Log Freshness and Duplicity).
    • Defaults to 3600 (1 hour) if not set in the first DID log entry.
    • If set to 0, indicates that the DID Controller expects the DID not to be cached.

did:vh does not use the did:webvh portable parameter. An entry that includes it MUST fail verification.

Cryptographic Agility§

The did:vh DID method is designed to support cryptographic agility—the ability to adapt to evolving cryptographic algorithms and suites over time without breaking compatibility or requiring global coordination.

Cryptographic agility in did:vh is achieved through the following mechanisms:

  • Self-describing cryptographic formats: All cryptographically generated data (e.g., hashes and signatures) use formats that encode the algorithm used. Hashes use the Multihash format, and signatures use Data Integrity proofs. These formats allow verifiers to determine the algorithm from the data itself, enabling flexible and extensible support.

  • Specification versioning via the method parameter: The method parameter specifies the version of the did:vh specification used for the entry that sets it and for subsequent log entries. It is set in the first log entry, and a later entry can set it again to adopt a newer (but not older) version of the specification, as defined in did:vh DID Method Parameters. This allows long-lived DIDs to transition to updated algorithm sets over time.

  • Version-specific algorithm policies: Each version of the did:vh specification defines the permitted cryptographic algorithms and suites for that version. This constrains the algorithms DID Controllers can use and limits the verification requirements placed on Resolvers. For example, the did:vh:1.0 version permits only one hash algorithm and one Data Integrity cryptosuite, while future versions can change or expand this set.

  • Response to cryptographic vulnerabilities: If flaws are identified in a cryptographic algorithm permitted by a given version of the specification, a new version of the did:vh specification will be released that removes or replaces the compromised algorithms. DID Controllers can then rotate to the newer version by updating the method parameter in a new log entry.

This design allows did:vh to remain interoperable and verifiable across cryptographic eras while minimizing the burden on Resolvers and preserving backward compatibility where safe to do so.

SCID Generation and Verification§

The self-certifying identifier or SCID is a required parameter in the first DID log entry and is the hash of the DID’s inception event. For did:vh, the SCID is also the whole of the method-specific identifier.

Generate SCID§

To generate the SCID for a did:vh DID, the DID Controller MUST execute the following function:

base58btc(multihash(JCS(preliminary log entry with placeholders), <hash algorithm>))

Where:

  1. The preliminary log entry with placeholders consists of the following pre-publication JSON object of what will become the first log entry. The placeholder is the literal string “{SCID}”.

    • The versionId entry, which MUST be {SCID}.
    • The versionTime entry, which MUST be a string that is the current time in UTC ISO8601 format in whole seconds, e.g., "2024-04-05T07:32:58Z"
    • The complete parameters for the initial log entry as defined by the DID Controller, with the placeholder wherever the SCID will eventually be placed.
    • The state JSON object with the value being the initial DIDDoc with placeholders (the literal string “{SCID}”) wherever the SCID will eventually be placed in the DIDDoc, including in the DID string did:vh:{SCID}.
  2. JCS is an implementation of the JSON Canonicalization Scheme [RFC8785]. It outputs a canonicalized representation of its JSON input.

  3. multihash is an implementation of the multihash specification. Its output is a hash of the input using the associated <hash algorithm>, prefixed with a hash algorithm identifier and the hash size.

  4. <hash algorithm> is the hash algorithm used by the DID Controller. The hash algorithm MUST be one listed in the parameters defined by the version of the did:vh specification being used by the DID Controller.

  5. base58btc is an implementation of the base58btc function. Its output is the plain base58btc encoding of its input, without a multibase prefix.

Verify SCID§

To verify the SCID of a did:vh DID being resolved, the Resolver MUST execute the following process:

  1. Extract the first DID log entry and use it for the rest of the steps in this process.
  2. Extract the scid property value from the parameters in the DID log entry.
  3. Determine the hash algorithm used by the DID Controller from the multihash scid value.
    • The hash algorithm MUST be one listed in the parameters defined by the version of the did:vh specification being used by the DID Controller based on the active method parameters property.
  4. Remove the data integrity proof property from the DID log entry.
  5. Replace the versionId property value with the literal "{SCID}".
  6. Treat the resulting log entry as a string and do a text replacement of the scid value from Step 2 with the literal string {SCID}.
  7. Use the result and the hash algorithm (from Step 3) as input to the function defined in the Generate SCID section (above).
  8. The output string MUST match the scid extracted in Step 2. If not, the first entry fails verification, and resolution fails with the invalidDid error.

Entry Hash Generation and Verification§

The entryHash follows the version number and dash character - in the versionId property in each DID log entry. Each entryHash is calculated across its log entry, excluding the Data Integrity proof. The versionId used in the input to the hash is a predecessor value to the current log entry, ensuring that the entries are cryptographically “chained” together in a microledger. For the first log entry, the predecessor versionId is the SCID (itself a hash), while for all other entries it is the versionId property from the previous log entry.

Generate Entry Hash§

To generate the entry hash and versionId for a did:vh log entry, the DID Controller MUST execute the following process:

  1. Start with the preliminary log entry, without a Data Integrity proof.
  2. Set its versionId to the predecessor value: for the first log entry, the SCID of the DID; for every other entry, the versionId of the previous log entry.
  3. Calculate the entry hash as base58btc(multihash(JCS(entry), <hash algorithm>)), where:
    1. entry is the data from the previous step.
    2. JCS is an implementation of the JSON Canonicalization Scheme ([RFC8785]). Its output is a canonicalized representation of its input.
    3. multihash is an implementation of the multihash specification. Its output is a hash of the input using the associated <hash algorithm>, prefixed with a hash algorithm identifier and the hash size.
    4. <hash algorithm> is the hash algorithm used by the DID Controller. The hash algorithm MUST be one listed in the parameters defined by the version of the did:vh specification being used by the DID Controller.
    5. base58btc is an implementation of the base58btc function. Its output is the plain base58btc encoding of its input, without a multibase prefix.
  4. Set the versionId of the entry to <version number>-<entry hash>, where the version number is 1 for the first log entry and the previous entry’s version number plus one for every other entry.

The Data Integrity proof is then added to the entry, as described in Create (Register) and Update (Rotate).

The following is an example of a preliminary log entry that is processed to produce an entry hash. As this is a first entry in a DID Log, the input versionId is the SCID of the DID.

{"versionId": "QmdmPkUdYzbr9txmx8gM2rsHPgr5L6m3gHjJGAf4vUFoGE", "versionTime": "2025-04-01T17:39:50Z", "parameters": {"witness": {"threshold": 2, "witnesses": [{"id": "did:key:z6Mkkc51mg2vpQzKWAbWQZupeGYhowaBjYkmvcKMTqteqHB4"}, {"id": "did:key:z6MkuDdJdKLCgwZuQuEi9xG6LVgJJ9Tebr74CXPYPSumqgJs"}, {"id": "did:key:z6MkoSWmQyp4fTk4ZQy4KUsss9dFX51XfEUzKKKj1J1JUsrF"}]}, "updateKeys": ["z6MkgzBDcBFV3sk4ypPE5YXMZHmS213A3HpYY2LmcVKV15jr"], "nextKeyHashes": ["QmZreDcjvWEpyRFznQeExWNCsvMLk5i59AcRJJuQC8UodJ"], "method": "did:vh:1.0", "scid": "QmdmPkUdYzbr9txmx8gM2rsHPgr5L6m3gHjJGAf4vUFoGE"}, "state": {"@context": ["https://www.w3.org/ns/did/v1"], "id": "did:vh:QmdmPkUdYzbr9txmx8gM2rsHPgr5L6m3gHjJGAf4vUFoGE"}}

Resulting entryHash: QmNdBb5MGCjawxfCRYKY31deSYWpqp2rxmeRH6acJAsCMe

Verify The Entry Hash§

To verify the entryHash for a given did:vh DID log entry, a Resolver MUST execute the following process:

  1. Extract the versionId in the DID log entry, and remove from it the version number and dash prefix, leaving the log entry entryHash value.
  2. Determine the hash algorithm used by the DID Controller from the multihash entryHash value.
    • The hash algorithm MUST be one listed in the parameters defined by the version of the did:vh specification being used by the DID Controller based on the method parameters property set in the current or most recent prior log entry.
  3. Remove the Data Integrity proof from the log entry.
  4. Set the versionId in the entry object to be the versionId from the previous log entry. If this is the first entry in the log, set the value to <scid>, the value of the SCID of the DID.
  5. Calculate the hash string as base58btc(multihash(JCS(entry), <hash algorithm>)), where:
    1. entry is the data from the previous step.
    2. JCS is an implementation of the JSON Canonicalization Scheme ([RFC8785]). Its output is a canonicalized representation of its input.
    3. multihash is an implementation of the multihash specification. Its output is a hash of the input using the associated <hash algorithm>, prefixed with a hash algorithm identifier and the hash size.
    4. <hash algorithm> is the hash algorithm from Step 2.
    5. base58btc is an implementation of the base58btc function. Its output is the plain base58btc encoding of its input, without a multibase prefix.
  6. Verify that the calculated value matches the extracted entryHash value from Step 1. If not, the entry fails verification.

Authorized Keys§

Each entry in the DID Log MUST include a Data Integrity proof where, at minimum:

  1. type is DataIntegrityProof,
  2. cryptosuite MUST be one listed in the parameters defined by the version of the did:vh specification being used by the DID Controller based on the active method parameters property.
  3. proofPurpose is assertionMethod,
  4. verificationMethod resolves to a multikey that appears verbatim in the active updateKeys.

An entry whose proof fails any check MUST fail verification. A structurally-valid signature over a different cryptosuite than allowed by the active method parameter MUST NOT be accepted.

The authorized verification keys for did:vh are the multikey formatted public keys in the active updateKeys list from the parameters property of the log entries. Any of the authorized verification keys MAY be referenced in the Data Integrity proof.

For the first log entry the active updateKeys list is the one in that first log entry.

A Resolver of the DID MUST verify the signature and the key used for signing each DID Log entry MUST be one from the list of active updateKeys. If not, the entry fails verification.

The active updateKeys for subsequent entries depends on whether Pre-Rotation is active or not. Pre-rotation is active for an entry if, and only if, the nextKeyHashes in effect before that entry — as set by an earlier entry — is non-empty. An entry that first sets a non-empty nextKeyHashes is therefore verified as defined in No Key Pre-Rotation, not as defined in Pre-Rotation Active.

If the active updateKeys for an entry is empty, no key is authorized to sign it, and the entry MUST fail verification. In particular, once an entry sets updateKeys to [] while pre-rotation is not active, every later entry fails verification, including one that sets a non-empty nextKeyHashes or new updateKeys.

A did:vh DID Log has no location whose control an attacker would also need in order to publish an update (see No Authoritative Location), so DID Controllers SHOULD use pre-rotation.

No Key Pre-Rotation§

For all subsequent entries, the active list is the most recent updateKeys before the log entry to be verified. Thus, the general case is that each log entry is signed by the keys from the previous log entry. Once a log entry containing an updateKeys list is published, that updateKeys becomes the active list, and previous updateKeys are ignored.

Pre-Rotation Active§

For all subsequent entries, the active list is the updateKeys from the current log entry to be verified. Thus, the general case is that each log entry is signed by the keys from the current log entry.

Pre-Rotation Key Hash Generation and Verification§

Pre-rotation requires a DID Controller to commit to the authorization keys that will be used (“rotated to”) in the next log entry for updating the DIDDoc. The purpose of committing to future keys is that if the currently authorized keys are compromised by an attacker, the attacker cannot take control of the DID by using the compromised keys to rotate to new keys the attacker controls. Assuming the attacker has not also compromised the committed key pairs, they cannot rotate the authorization keys without detection. See the non-normative section about Using Pre-Rotation Keys in the did:webvh Implementer’s Guide, which applies equally to did:vh, for additional guidance.

As described in the parameters section of this specification, a DID Controller MAY include the parameter nextKeyHashes with a non-empty list in any DID log entry to activate the pre-rotation feature. When pre-rotation is active, all multikey representations of the public keys in the updateKeys parameters property in other than the initial version of the DID log entry MUST have their hash in the nextKeyHashes array from the previous DID log entry. If not, the entry fails verification.

A DID Controller MAY turn off the use of pre-rotation by setting the parameter nextKeyHashes to [] (empty array) in any DID log entry. If there is an active set of nextKeyHashes at the time, the pre-rotation requirements remain in effect for the DID Log entry. The subsequent DID Log entry MUST use the non-pre-rotation rules.

To create a hash to be included in the nextKeyHashes array, the DID Controller MUST execute the following process for each possible future authorization key.

  1. Generate a new key pair. The key type MUST be one that can be used as a did:vh authorization key.
  2. Generate a multikey representation of the public key of the new key pair.
  3. Calculate the hash string as base58btc(multihash(multikey, <hash algorithm>)), where:
    1. multikey is the multikey representation of the public key from Step 2.
    2. multihash is an implementation of the multihash specification. Its output is a hash of the input using the associated <hash algorithm>, prefixed with a hash algorithm identifier and the hash size.
    3. <hash algorithm> is the hash algorithm used by the DID Controller. The hash algorithm MUST be one listed in the parameters defined by the version of the did:vh specification being used by the DID Controller.
    4. base58btc is an implementation of the base58btc function. Its output is the plain base58btc encoding of its input, without a multibase prefix.
  4. Insert the calculated hash into the nextKeyHashes array being built up within the parameters property.
  5. The generated key pair SHOULD be safely stored so that it can be used in the next log entry to become a DID authorization key. At that time, the multikey representation of the public key will be inserted into the updateKeys property in the parameters and the private key can be used to sign the log entry's DID update authorization proofs.

A DID Controller MAY include extra entries (for keys or just random strings) in a nextKeyHashes array.

After rotating from a pre‑rotation public key, the corresponding private key SHOULD be treated as spent and securely destroyed. Reusing a revealed pre‑rotation key is strongly discouraged because it weakens the intended containment and forward‑security properties of pre‑rotation.

When processing other than the first DID log entry where the pre-rotation feature is active, a did:vh Resolver MUST:

  1. For each multikey in the updateKeys property in the parameters of the log entry, calculate the hash and hash algorithm for the multihash multikey.
  2. The hash algorithm MUST be one listed in the parameters defined by the version of the did:vh specification being used by the DID Controller.
  3. The resultant hash MUST be in the nextKeyHashes array from the previous log entry prior to being processed. If not, the entry fails verification.
  4. A new nextKeyHashes list MUST be in the parameters of the log entry currently being processed. If not, the entry fails verification.

DID Witnesses§

The witness process for a did:vh DID provides a way for collaborators to work with the DID Controller to “witness” the creation of new versions of the DID. This specification defines the technical mechanism for using witnesses. Governance and policy questions about when and how to use the technical mechanism are outside the scope of this specification.

Witnesses can prevent a DID Controller from updating or removing versions of a DID without detection by the witnesses. They are also a mitigation against a malicious actor who has compromised a DID Controller's authorization key(s). A did:vh DID Log has no single location whose control the attacker would also need, so with the keys alone the attacker could distribute an update through any DID Log source. With witnesses active, the attacker cannot create a valid update, or rewrite the previous history, without also having compromised a sufficient number of witnesses. DID Controllers SHOULD use witnesses for DIDs relied on by many parties.

This protection depends on witnesses behaving as this specification requires — in particular, approving only an entry that extends their own copy of the DID Log (see Witnessing a DID Version Update). A witness proof shows only that a witness approved an entry; a Resolver cannot confirm how the witness reached that decision. How far witnesses are trusted is therefore a matter for the governance of the ecosystem. Watchers provide a way to detect conflicting logs that does not depend on that trust; see DID Watchers and Log Freshness and Duplicity.

Witness Lists§

The list of DIDs that witness DID updates is defined in the witness parameter, as described in the Parameters section of this specification. After the first witness parameter has been set to other than {} (empty object) in a DID log entry, and while there are active witnesses, the DID Controller MUST obtain valid proofs from a threshold of the active witnesses for each DID log entry before distributing it. If a DID log entry contains a new (replacement) list of witnesses (by including a new witness parameter) that new list becomes active AFTER the new DID log entry has been published. Such a replacement MAY be a {} (empty object). Once the witness attribute set to {} becomes active, updates to the DID are not witnessed.

Witness DIDs and Reputation§

Since did:vh witness DIDs are did:key DIDs, there is not an explicitly published identifier for each witness. If there is a need in an ecosystem to identify who the witnesses are, a mechanism can be defined by the governance of the ecosystem, such as the entry of the DID in a trust registry. Such mechanisms are outside the scope of this specification.

When a did:key DID is used in any did:vh context — as a witness id, as a verificationMethod controller, or as an assertionMethod reference in a Data Integrity proof — the did:key specification MUST be followed. Notably, the multibase value in the method-specific identifier (the body of the DID) MUST equal the multibase value in any fragment identifier (if present) that references the lone verification method within the DID. For did:key:z6MkABC...#z6MkABC..., body and fragment MUST be byte-for-byte equal. Verifiers MUST reject any reference where they differ, because the body authoritatively defines the public key while the fragment is the Verification Method id; permitting divergence would let an attacker claim a proof was made by did:key:A while actually signing with did:key:B.

The witness Parameter§

The witness element in a parameters object of a DID Log entry has the following data structure:

"witness" : {
  "threshold": n,
  "witnesses" : [
      {
         "id": "<did:key DID of witness>"
      }
   ]
}

where:

  • threshold: a positive integer (JSON number, no fractional part, value ≥ 1) that MUST be attained or surpassed by the count of distinct verified witness approvals for a DID log entry to be considered approved. The threshold MUST be between 1 and the number of distinct witnesses[].id values, inclusive. A witness parameter where threshold is missing, non-integer, < 1, or > count(distinct ids) MUST cause the entry that sets it to fail verification; Resolvers MUST NOT silently coerce a malformed witness to “no witnesses”.
  • witnesses: the array of witnesses that MUST be non-empty, with each entry including the field:
    • id: (required) the DID of the witness. The DID MUST be a did:key DID and MUST be unique within the array (compared byte-for-byte after Unicode NFC normalisation). Each id contributes at most one approval to threshold counting, regardless of how many proofs are attributed to it.
    • The did:key used as a witness id MUST decode to a public key compatible with one of the cryptosuites listed in the parameters defined by the version of the did:vh specification being used by the DID Controller based on the active method parameters property. A witness id whose body decodes to a key of any other type MUST cause the entry that sets it to fail verification at parameter-validation time — not at signature-verification time — so an invalid witness configuration cannot ever take effect.
Witness Threshold Algorithm§

The use of the threshold versus needing approvals from all witnesses is to prevent faulty witnesses from blocking the creation of a new version of the DID. To determine if the threshold has been met, participants MUST:

  1. Verify each Data Integrity proof in the witness proofs file for the relevant versionId independently.
  2. Attribute each verified proof to a witness id from the active witnesses list. Proofs that cannot be attributed (the proof’s key does not belong to any listed witness) MUST be discarded.
  3. Form the set of distinct attributed id values. The threshold check applies to the size of this set, not to the raw proof count.
  4. If |set| ≥ threshold, the update is “witnessed”; otherwise the entry is not witnessed and fails verification.

The client of a Resolver can evaluate the witnesses according to the governance of the ecosystem. Such an evaluation is outside the scope of this specification.

The Witness Proofs File§

Proofs from witnesses are placed into a separate file (did-witness.json) from the DID Log. It reaches the Resolver in the same ways as the DID Log: passed directly in didWitness, or by reference in srcWitness. The two files are passed independently, so a client can take the witness proofs file from a different DID Log source than the DID Log — for example, from a watcher's /witness operation. When derived from a src DID URL parameter, the witness proofs file is did-witness.json in the same location as did.jsonl. The media type of the file SHOULD be application/json.

The data model for the did-witness.json file is:

[
  {
    "versionId": "1-Qmba111111...",
    "proof": [{ ... }, { ... }]
  },
  {
    "versionId": "2-Qzmb222222...",
    "proof": [{ ... }, { ... }]
  }
]

Where:

  • versionId is the versionId of the DID log entry to which the witness proofs apply.
  • proof is an array of Data Integrity proofs that use the versionId as input data. The permitted Data Integrity cryptosuite MUST be one listed in the parameters defined by the version of the did:vh specification being used by the DID Controller based on the active method parameters property, and the proofPurpose set to assertionMethod.

Because a witness id is a did:key DID, the verification key is fully determined by decoding the did:key body — no DID resolution is required and no verificationMethod lookup is permitted. Resolvers verifying a witness proof MUST:

  1. Parse the proof’s verificationMethod as did:key:<multibase>#<multibase> and recover the public key by decoding the body multibase per the did:key specification.
  2. Verify the signature using only that key. Resolvers MUST NOT dereference the witness DID for a key, MUST NOT consult any other key store, and MUST NOT accept a proof whose body multibase decodes to a key structurally invalid for the cryptosuites mandated by the active method.

A valid proof from a witness carries the implication that ALL prior DID Log entries are also approved by that witness. To maintain a manageable did-witness.json file size, the DID Controller SHOULD remove all older proofs for distributed DID Log entries, keeping only the latest proof for each witness.

To eliminate the race condition in distributing the DID Log and did-witness.json files, when a new DID Log entry is being added, witness proofs MUST be added to the did-witness.json file and that file made available BEFORE the DID Log containing the new DID Log entry is distributed. As a result, Resolvers may find proofs for undistributed DID log entries in the did-witness.json file. Resolvers MUST ignore proofs with versionIds not in the DID Log. Since Resolvers cannot verify an undistributed DID log entry, the witness proofs on undistributed DID log entries do not carry the implication of approval of prior DID Log entries. Therefore, at times there may be two proofs in the did-witness.json file for a witness:

To avoid unnecessary clutter in the did-witness.json file, array entries without proofs (e.g., containing only the versionId) SHOULD be removed.

A witness proofs file MUST NOT contain proofs for two different versionIds with the same version number. When adding proofs to the witness proofs file, a DID Controller MUST reject any proof for a versionId that conflicts in this way with the DID Log it is distributing.

Witnessing a DID Version Update§

The following process is used to witness a DID version update:

  • The DID Controller prepares the full DID Log Entry (including the proof element) for the new version of the DID, and shares it with the active witnesses.
    • The specification leaves to implementers how the log entry data is provided to the witnesses.
  • Each witness MUST hold its own copy of the DID Log prior to witnessing, and MUST confirm that the controller-supplied candidate entry verifies as the next entry to that DID Log.
    • A witness that does not yet hold the DID Log — for example, one added to the witness parameter after the DID was created — obtains it from a DID Log source, typically the DID Controller along with the candidate entry, and MUST verify it in full before witnessing. That copy then becomes its own copy, which later candidate entries have to extend. A witness can also compare the copy with those held by watchers, to check that the log it was given has not been forked before it joined.
  • Each witness MUST independently verify the candidate entry using every step in the Resolution Algorithm. Any failure MUST cause the witness to refuse approval.
  • A witness MUST NOT approve more than one log entry with the same predecessor.
  • Each witness determines (based on the governance of the ecosystem) if they approve of the DID version update.
    • The meaning of “approve” for any given implementation is outside the scope of this specification.
  • If the verification is successful and approval granted, the witness creates and sends to the DID Controller a Data Integrity proof signed using the witness's did:key DID.
  • The DID Controller MUST add the proof to the record for the applicable versionId for the undistributed DID log entry in the did-witness.json file.
    • The DID Controller MAY make the updated did-witness.json file available as new witness proofs are added to the file.
    • The DID Controller MUST make the updated did-witness.json file available after a threshold of witness proofs have been received and before the witnessed DID Log is distributed.

A Resolver can verify that a threshold of witnesses signed an entry, but not that each witness held its own copy of the log or checked the entry against it. The requirements on witnesses above define correct behaviour; whether a given witness meets them is a matter of trust in that witness.

Verifying Witness Proofs During Resolution§

A did:vh Resolver MUST verify that all DID Log entries that have active witnesses have a threshold of approving witnesses. Resolvers MUST:

  1. Complete all non-witness verifications of the DID Log before processing any witness proof. Witness verification MUST NOT substitute for entry-hash or signature verification.
  2. Get the witness proofs file, passed directly in didWitness or retrieved from the srcWitness reference. If no witness proofs file was passed, or the srcWitness reference was not found, treat the file as containing no proofs.
  3. For each entry in the witness proofs file, confirm its versionId matches a versionId present in this DID Log. Non-matching entries, including those for future entries, MUST be discarded and MUST NOT be treated as evidence of witnessing for any other entry.
  4. Verify enough proofs to meet the threshold for all entries requiring witnessing.
  5. For each entry requiring witnessing, confirm a threshold of verified, distinct-witness proofs whose versionId matches the current or any later entry in the DID Log. Otherwise, that entry fails verification.

For each witness proof, the Resolver MUST extract verificationMethod and confirm that:

  1. It is a valid, did:key specification-compliant DID URL of the form did:key:<multibase>#<multibase> where body and fragment multibases are byte-equal (see did:key body/fragment check).
  2. No previously verified proof was found in the witnesses array for the same versionId and id (one count per witness per entry).

A proof failing either requirement MUST be discarded from threshold counting.

A DID Controller is expected to prune the did-witness.json file to include only the last proof for each witness for a distributed DID log entry. However, if a DID Controller does not prune the file, a Resolver MAY do the pruning as part of the resolution process, verifying only the minimum number of proofs needed to meet the threshold for each DID log entry. While it is expected that a DID Controller will exclude any proofs that fail verification, a Resolver MAY ignore any proofs that fail verification and still resolve the DID if there are enough valid proofs to meet the threshold requirements.

If you want to learn more about the practical application of witnesses, see the Implementer’s Guide section on Witnesses on the did:webvh information site, which applies equally to did:vh.

DID Watchers§

Watchers are components found in some digital trust and DID ecosystems that monitor DIDs on behalf of clients for various purposes, such as:

  • Caching verified DIDs: Storing verified DID Logs to facilitate efficient resolution.
  • Ensuring persistence: Maintaining access to DIDs even after removal by the DID Controller from other sources.
  • Detecting inconsistencies: Identifying malicious behavior by the DID Controller, such as distributing altered DID Logs, or giving different parties conflicting logs (duplicity). A watcher does this by checking that each copy of a DID Log it receives or retrieves extends the copy it holds. This is the most reliable way to detect duplicity, because it does not depend on trusting the DID Controller or the witnesses, but it detects only the copies the watcher sees. A network of watchers can reach consensus independently of witnesses.

For did:vh, watchers are also a primary DID Log source, as described in From Watchers. Any party can set up a watcher for did:vh DIDs, without the involvement of the DID Controller and without being listed in the DID Log — for example, a relying party that wants a check independent of the DID Controller. A did:vh DID Controller can also opt to collaborate with specific watchers by publishing their URIs in the parameters of DID log entries. It is outside the scope of this specification how a DID Controller requests a watcher monitor a DID or how a watcher requests it be included in the DID Log of a DID.

A watcher MUST fully verify each DID Log it receives or retrieves, SHOULD check that it extends the copy it holds (see Log Freshness and Duplicity), and SHOULD report any divergence it detects between copies. A watcher indexes the DID Logs it holds by SCID.

The governance of watchers is out of scope for this specification, which defines only the technical mechanisms for notifying and querying watcher services.

Publishing Watcher URLs§

did:vh provides a mechanism for notifying Resolvers (and their clients via [DID-RESOLUTION] metadata) about configured watchers. The watchers parameter lists URIs that identify the DID’s watchers.

When resolving a did:vh DID, Resolvers MUST provide the active list of watchers in the DID Document Metadata, as noted in DID Resolution Metadata.

Watcher URIs MAY use schemes other than HTTP(S), such as a DID ([DID-CORE]), depending on the specific implementation or network requirements. However, this specification does not define how non-HTTP(S) watcher URIs are resolved or interacted with. If a watcher uses an HTTP(S) URL, it MUST support the HTTP-based interaction model defined in the Watcher Endpoints and Behavior section.

If a watchers entry is included in a DID log entry, it replaces the active set of watchers.

If a new watcher is added after a DID has existed for some time, the DID Controller SHOULD notify the new watcher about previously created DID Resources.

Watchers do not need to be listed in the DID log. DID Controllers MAY send notifications to watchers that the DID Controller is aware of but does not list in the DID Log.

Watcher Endpoints and Behavior§

A watcher is a web server accessible via HTTP that MUST support the following capabilities:

  • Client Requests:
    • Retrieve the DID log for a given SCID.
    • Retrieve the witness proofs file for a given SCID.
    • Retrieve a resource for a given SCID and resource path.
  • Notifications (typically) from the DID Controller:
    • Notify the watcher about a new log entry for a DID.
    • Notify the watcher about a new or updated DID resource.
    • Request removal of a given SCID from the watcher's cache.
    • Request removal of a given DID resource from the watcher's cache.
Watcher HTTP API Operations§

The following HTTP API operations define the interaction between watchers and other components. They are defined in the did:vh Watcher OpenAPI YML Definition, which includes the request and response data models and status codes for each of the endpoints. It is derived from the did:webvh Watcher OpenAPI YML Definition, with the changes noted below for notifying a watcher of a DID that has no web location.

  • GET <WATCHER URL>/log?scid=<SCID>: Returns the latest DID Log for the given SCID.
  • POST <WATCHER URL>/log?did=<DID URL>, where the DID URL includes a src query parameter: notifies the watcher of a log update, prompting retrieval of the latest DID Log (and witness proofs file) from the location src names, as defined in The src DID URL Parameter. As for any DID URL, the src value cannot be a local file or loopback reference.
  • POST <WATCHER URL>/log?did=<DID>, where there is no src parameter: notifies the watcher of a log update, and MUST carry the complete DID Log as the request body, with media type text/jsonl. If witnesses are active, the DID Controller MUST first send the witness proofs file with POST <WATCHER URL>/witness?did=<DID>, with media type application/json.
  • POST <WATCHER URL>/log/delete?scid=<SCID>: Notifies the watcher that the requester asks for the given <SCID> to be deleted from the watcher's cache. If it is removed, the watcher returns a 404 Not Found status to subsequent requests for that <SCID>. The body of the request is a Data Integrity proof from the requester that may be used by the Watcher to decide on the legitimacy of the request. The Watcher will act (or not) on the request according to its governance, which is out of scope of this specification. For example, a watcher might implement a workflow that has to be completed to approve the deletion of a <SCID> from the watcher's cache. The endpoint could be used to carry out a “right to be forgotten” order, such as might be required under Europe’s General Data Protection Regulation (GDPR).
  • GET <WATCHER URL>/witness?scid=<SCID>: Returns the latest did-witness.json file for the given SCID.
  • GET <WATCHER URL>/resource?scid=<SCID>&path=<resourcePath>: Retrieves the requested resource.
  • POST <WATCHER URL>/resource?scid=<SCID>&path=<resourcePath>: Notifies the watcher of a new or updated resource.
  • POST <WATCHER URL>/resource/delete?scid=<SCID>&path=<resourcePath>: Notifies the watcher that the given <resourcePath> associated with the <SCID> is to be deleted from the watcher's cache. If it is removed, the watcher returns a 404 Not Found status to subsequent requests for that <SCID> and <resourcePath>. The body of the request is a Data Integrity proof from the requester that may be used by the Watcher to decide on the legitimacy of the request, as for /log/delete.

In both forms of the /log notification, the watcher MUST fully verify the DID Log, MUST confirm that it extends any copy the watcher already holds, and indexes it by SCID.

Publishing and Retrieving DID Log Resources§

This section applies whenever a DID Log, witness proofs file, or other DID Resource is published to, or retrieved from, a network location over HTTP — a web location named by a srcLog or srcWitness reference or by a src DID URL parameter, or a watcher. It applies equally to a Resolver and to a client that retrieves the files itself before passing them directly.

Publishing DID Log Resources§

  1. DID Log resources MUST be served over HTTPS, with the server authenticated by TLS server authentication. Plain HTTP MUST NOT be used, except for testing or non-production deployments.
  2. Self-signed TLS certificates SHOULD NOT be used in production.
  3. So that a Resolver running in a web browser can retrieve it, the HTTP response for the DID Log MUST include the header Access-Control-Allow-Origin: *.
  4. A DID Controller that serves DID Log resources through intermediaries such as CDN caches or load balancers MUST ensure that those intermediaries do not serve stale or altered resources.

Retrieving DID Log Resources§

A Resolver fetches resources from locations chosen by its caller, or by whoever gave the caller a DID URL, which makes it a potential Server-Side Request Forgery (SSRF) vector. When retrieving DID Log resources, a Resolver MUST, except as defined for loopback references in Web Locations:

  1. HTTPS only. Reject any URL scheme other than https, including after a redirect, and validate the server’s TLS certificate. Certificate validation MUST NOT be disabled by default.
  2. No automatic redirects. Not automatically follow HTTP 3xx responses when fetching the DID Log or the witness proofs file. If following redirects is offered as an opt-in, every check in this list MUST be re-applied to each redirect target.
  3. Case-insensitive percent-decoding. Normalise the case of percent-encoded octets, per [RFC3986] §2.1, before making any allow or deny decision.
  4. Re-validate after decoding. Apply all host and path checks to the decoded values. Percent-encoded IP literals and traversal sequences (such as %2E%2E and %2e%2e) MUST be rejected after decoding.
  5. IP-literal and private-address rejection. Reject IPv4 and IPv6 literal hosts both (a) after percent-decoding the host, and (b) after DNS resolution. By default, deny loopback (127.0.0.0/8, ::1), private (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7) and link-local (169.254.0.0/16, fe80::/10) addresses. Opt-ins for development MAY be provided, but MUST be off by default.
  6. No localhost in production. Not issue requests to localhost, 127.0.0.0/8, ::1, or names resolving to them, except through a testing opt-in that is off by default, or for a loopback reference.
  7. Response size cap. Enforce a maximum body size for both the DID Log and the witness proofs file, terminating the transfer if it is exceeded regardless of any declared Content-Length. The Content-Length header SHOULD be checked before the body is read, and its absence treated as grounds for a stricter cap or for rejection. A cap of 5 MiB is RECOMMENDED as a default.
  8. Operation timeout. Enforce a wall-clock timeout on the complete fetch-and-verify operation for a single resolution. A timeout of 30 seconds is RECOMMENDED as a default.

When performing the DNS resolution for a retrieval, the Resolver SHOULD use [RFC8484] in order to prevent tracking of the identity being resolved.

A Resolver MAY also limit retrievals to locations permitted by its configuration. A Resolver that supports srcLog and srcWitness references using other schemes applies equivalent protections to those retrievals.

Security Considerations§

This section is non-normative.

This section follows the guidelines in [RFC3552] and aligns with the [DID-CORE] requirements in DID Core 7.3. It describes the threats to did:vh and how the requirements in this specification address them. The requirements themselves are defined in the normative sections referenced below.

No Authoritative Location§

A did:webvh Resolver treats the DID’s web location as the authoritative place to find the current DID Log. A did:vh DID has no such location. The integrity of any copy of the log is fully protected by the SCID, the hash chain and the proofs, so a Resolver can safely accept a log from any source. What a Resolver cannot know from the log alone is whether it is complete — whether newer entries exist.

The resulting threats, and their mitigations, are:

  • Withholding and truncation. A source, or the party presenting a DID, supplies an older copy of the log, for example one from before a key rotation or deactivation. A Resolver verifies the log it is given but cannot detect this on its own. Mitigations: clients that need the current version source the log from a source expected to be current, such as a listed watcher, and never treat the absence of newer entries at one source as proof that none exist; a Resolver that retains the latest versionId it has seen detects a copy that is shorter than one seen before; and a client can ask the Resolver to compare the copy with those held by watchers (see Comparing Copies of a DID Log and Log Freshness and Duplicity).
  • Duplicity (split view). A DID Controller, or an attacker with its update keys, creates two different extensions of one log and gives them to different parties. This specification requires DID Controllers to distribute only logs that extend the log they previously distributed (Update (Rotate)), witnesses to approve at most one child of any entry (Witnessing a DID Version Update), and the witness proofs file to contain no conflicting proofs (The Witness Proofs File). Because no other party can verify that a witness has followed these rules, detecting split views ultimately relies on comparing copies of the log from multiple sources: clients that obtain copies from several sources compare them and do not rely on versions past the point of divergence; peers apply updates so that non-extending entries are rejected; Resolvers given more than one copy fail with logForked when the copies diverge; and watchers — including ones run by relying parties — detect and can report conflicting logs. Watchers listed in the log are chosen by the DID Controller, so the extraWatchers resolution option, naming watchers the client chooses, gives the stronger check.
  • Compromised keys and no location to reclaim. In did:webvh, control of the web location is a second factor an attacker who steals the update keys also needs in order to publish. A did:vh log has no such location, so an attacker with the update keys can distribute a valid update through any source. Mitigation: DID Controllers are expected to use pre-rotation (see Authorized Keys), and to use witnesses for DIDs relied on by many parties, so that an update also needs the approval of a threshold of witnesses (see DID Witnesses).

Forked Logs§

Two copies of a DID Log that both pass verification but diverge are proof that a party able to sign as the DID Controller — and as a threshold of the witnesses, if any — created both. That party is the DID Controller acting duplicitously, an attacker holding its keys, or an attacker able to derive private keys from public keys, such as one with a cryptographically relevant quantum computer. Such an attacker can sign as the witnesses too, so the rule that a witness approves at most one child of an entry does not help, and pre-rotation protects only entries not yet published: each published entry reveals the public keys an attacker would need to sign an alternative to it. Pre-rotation does still stop the attacker from extending the genuine branch.

Verification cannot show which branch is genuine, and the copy passed to the Resolver has no special standing — a forked branch can be passed directly, named in a src DID URL, or held by a watcher. A Resolver that chose a branch would let whoever supplied the reference copy take control of the DID. A Resolver that detects a fork therefore fails with logForked (see Comparing Copies of a DID Log). That failure can itself be the attacker’s goal: a forked copy at a watcher can make resolution fail. But it affects only clients that compare against that watcher, whether it was named in extraWatchers or listed in the log. That is a denial of service rather than a takeover.

A watcher keeps the first copy of a DID it receives and accepts only copies that extend it, so a watcher that first receives a forged branch keeps it. DID Controllers are advised to send each new DID to their watchers when it is created, so that their first copy is genuine. Copies that watchers archived before a fork appeared are the best available evidence of which branch came first.

A forked DID cannot be repaired; its DID Controller has to create a new DID. Against an attacker that can derive private keys, the defence is to move to a cryptosuite the attacker cannot break, by upgrading the method version (see Post Quantum Attacks), before such an attack is possible.

Threats and Attacks§

The following classes of attack apply to all DID operations:

  • Eavesdropping — DID Logs, witness proofs files and other DID Resources retrieved over a network are served over HTTPS (see Publishing and Retrieving DID Log Resources). The verifiability of did:vh means that tampering with the contents of individual log entries is detectable; TLS protects against passive observation and other network-based risks.

  • Replay attacks — A Resolver verifies the whole log, including monotonic progression of versions and times and the chain of entry hashes, and rejects any log that does not verify, as defined in the Resolution Algorithm.

  • Message insertion, deletion, and modification — Each DID Log entry and witness proof is integrity-protected by a cryptographic signature. Any change to a log entry causes verification to fail, as defined in the Resolution Algorithm.

  • Truncation, withholding and split views — See No Authoritative Location above.

  • Denial of Service (DoS) and amplification — A malicious or compromised source could attempt to exhaust resolver resources by supplying pathologically large logs, or by holding a connection open and streaming log entries indefinitely. This risk is most acute for resolvers that encounter previously-unseen DIDs on behalf of their clients — for example, a service that performs DID resolution in onboarding new users. In such cases an attacker need only find a service that will pass their DID and log through to a resolver on their behalf. A Resolver that returns the DID Log in the resolution metadata, when asked with the includeDidLog option, returns a response up to the size of the log it accepted, so the size cap also bounds the response.

    • The requirement that each entry’s versionTime be strictly greater than the previous one, in whole seconds, and not in the future, constrains log length — a log with implausibly rapid versionTime progression is likely malformed. However, this does not fully prevent the attack, as a patient attacker can pace log entry generation to match valid versionTime increments.

    • The size cap and timeout required in Retrieving DID Log Resources bound the cost of a single resolution. A declared Content-Length lets a resolver reject an oversized log before processing begins, but cannot itself be relied on; the presence of HTTP range request support (Accept-Ranges: bytes) is a useful signal that a server is serving a static resource rather than generated content. A Resolver that accepts logs passed directly is advised to apply an equivalent size limit to didLog and didWitness values. Resolvers are also advised to apply rate limits to resolution requests, particularly for previously-unseen DIDs, and concurrency limits on simultaneous resolution operations.

    • What counts as “excessively large” or “repeated” is best established through community or ecosystem governance. These mitigations are standard HTTP service hardening practices and are not unique to did:vh.

  • Man-in-the-middle (MitM) — HTTPS and signature verification of log entries and witness proofs protect against undetected modification of individual entries. TLS also authenticates the server and reduces opportunities for active interference.

  • Other attacks — The required did:vh verification process mitigates downgrade attacks on cryptographic algorithms and prevents poisoning of log or witness files, since unauthorized changes fail signature verification. Verification does not, however, address availability. Keeping the DID Log in several places, including with watchers, improves resilience.

References and Other Client-Supplied Values§

The srcLog and srcWitness resolution options, and a src DID URL query parameter, are supplied by the client or by whoever gave it the DID URL, and so are untrusted input. The same is true of a didLog value, which is why it is verified in full, and of extraWatchers URLs:

  • Server-side request forgery. A web location reference or extraWatchers URL can name any host. Resolvers apply to these retrievals the transport requirements in Retrieving DID Log Resources, including rejecting IP literals and private addresses and not following redirects automatically. These are standard SSRF defences; they are stated normatively because common implementations have been found vulnerable to at least one of: following redirects, accepting IP literals, case-sensitive percent-decoding, and checking values before rather than after decoding. A Resolver can also decline to retrieve from srcLog and srcWitness references at all, refuse or limit extraWatchers (see did:vh Resolution Options), or allow only locations permitted by its configuration. The same hardening applies to a client retrieving from a web location or a watcher itself. The one exception is a loopback (http) reference, which is accepted only by a Resolver local to its client and never from a DID URL; see Web Locations. A Resolver supporting other schemes applies equivalent protections to those retrievals and to any gateway it uses.
  • Returning retrieved content. With the includeDidLog option, a Resolver returns the files it retrieved to its caller. It returns only a DID Log that has verified as the history of the DID being resolved, and the witness proofs for it, so the option cannot be used to read arbitrary resources from locations the Resolver can reach.
  • Stale or wrong logs. A web location may serve an old copy of the log, or a log for a different DID. The first is covered under No Authoritative Location; the second is detected by the SCID check that the Resolution Algorithm applies to every entry.
  • Local file and service access. A local file or loopback reference is accepted only by a Resolver local to its client; a Resolver that accepts requests from other systems never reads local files or retrieves from loopback hosts, and a src DID URL parameter is never a file: or loopback URL. A local Resolver reads only the files its client names, and the content of each is verified in full. See Local Files and The src DID URL Parameter.
  • Misleading association. The domain in a reference or src value says nothing about who controls the DID. A DID Controller can publish a log at any location it can write to, and anyone can put any src value in a DID URL. For this reason, Resolvers and their clients do not treat a web location as evidence of an association between the DID and the owner of the domain (see The srcLog and srcWitness Options).

Peer-to-Peer Use§

When DID Logs are exchanged peer-to-peer, each party holds the only copies of the other’s log, and an update can carry only the new entry. With no other copy to compare against, the hash chain is what protects a party: it applies an update as defined in Applying Peer-to-Peer Updates, so that entries that do not continue from the log it holds are rejected, and keeps a rejected update as evidence of duplicity.

Residual Risks§

Residual risks include:

  • Compromise of a system holding a copy of the DID Log, such as a web host or a watcher.
    • While this can impact access to the DID Log and associated files, it does not compromise the integrity of the log entries themselves, nor the verifiability of the DID.
  • Compromise of DID Controller private keys.
    • A DID Controller can mitigate this risk through the use of pre-rotation keys, treating each revealed pre-rotation key as spent and never reusing it. Reuse of a revealed key is not invalid, but it reduces the containment that pre-rotation provides.
    • Other good security practices also help, such as using hardware security modules (HSMs) or secure enclaves for key storage, enforcing strong access controls, maintaining secure backups of critical keys, and performing regular key rotations.
  • Weaknesses in underlying cryptographic algorithms after deployment.
  • Misconfiguration of cache control or TTL values.
  • Implementation errors in Resolvers or DID Controllers.
  • Resolvers operating in contexts where they may encounter large numbers of previously-unseen DIDs — such as open verification services — face elevated resource exhaustion risk. Such resolvers are advised to implement rate limiting and monitoring for abusive resolution patterns, with the ability to block offending sources.

Integrity Protection and Update Authentication§

All DID operations (create, update, deactivate) are integrity-protected by the cryptographic verification of DID Log entries. Update authentication is provided by verifying the DID Controller's proof(s) against the active updateKeys in the DID parameters (see Authorized Keys).

Because a did:vh DID Log and its entries are self-certifying, they can be verified and trusted regardless of how they are obtained — passed with the DID, from a web location, via a cache, through a CDN, from a watcher, from a peer, or via a trusted resolver service. The verification process ensures authenticity and integrity independent of the transport channel.

Authentication Characteristics§

The authentication of DID updates is based on possession of the private keys associated with the update and pre-rotation keys. The security of the DID therefore depends on the strength of these keys, their secure storage, and the cryptographic algorithms used.

Unique Assignment of DIDs§

In did:vh, uniqueness of a DID is based on the self-certifying identifier (SCID) generated at the inception of the DID. The SCID is cryptographically bound to the initial content of the DID, including the DID Controller's keys, and ensures that no two independently created DIDs can have the same identifier. A did:vh DID contains nothing but its SCID, so there is no other component, such as a domain name, whose assignment could be confused or reassigned.

Endpoint Authentication§

Retrievals from web locations and from watchers use HTTPS with TLS server authentication (see Publishing and Retrieving DID Log Resources). The only exception is a retrieval from a loopback (http) reference by a Resolver local to its client. As with all sources, a DID Log is verified by its content, not by the authentication of the server that provided it; TLS provides additional protection against active network attacks.

Network Topology§

did:vh does not require any particular network. A DID Log may be held on web infrastructure, by watchers, in other stores, or exchanged peer-to-peer. CDN caches and load balancers in front of a web location can serve stale data; Publishing DID Log Resources requires DID Controllers that use them to prevent this.

Cryptographic Protection§

The following data is protected:

  • DID Log entries — Signed by the DID Controller's keys.
  • Witness proofs — Signed by witness keys.

These signatures provide integrity and update authentication but not confidentiality; DID Log entries are public. Private keys and other secret material do not belong in the DID Log.

Signature Implementation§

did:vh uses standard Data Integrity proof mechanisms for signing DID Log entries and witness proofs, as defined in the cryptographic suite used. The cryptosuites permitted for each method value are listed in did:vh DID Method Parameters.

Cross-Origin Resource Sharing (CORS)§

To support resolution by client applications running in a web browser, a DID Log published at a web location needs to be accessible from any origin. Publishing DID Log Resources requires the Access-Control-Allow-Origin: * header for this reason.

Post Quantum Attacks§

The did:vh Key Pre-Rotation approach provides enough flexibility for “post-quantum safety.” For guidance on mitigating post-quantum attacks, implementers are advised to consult the corresponding did:webvh Implementation Guide section, which applies equally to did:vh. Pre-rotation is especially valuable for did:vh, for the reason given under No Authoritative Location. Pre-rotation protects entries not yet published, but not entries already published, whose public keys are known; see Forked Logs.

Implementation Hygiene§

The following practices are not unique to did:vh but represent recurring failure points observed across implementations of did:webvh, from which did:vh is derived. Implementers are advised to treat these as baseline hygiene.

  • Dependency currency. Keep cryptographic and HTTP dependencies on supported, patched versions. Run a vulnerability scanner (cargo audit, pip-audit, npm audit, OWASP Dependency-Check) on every build.
  • Filesystem permissions. Create private keys and secret-bearing configuration files with owner-only permissions (e.g., 0600 on POSIX). Do not read secret material from the current working directory or other untrusted locations by default.
  • CLI tools. Do not print private keys, mnemonics, or other long-lived secrets to stdout/stderr or shell history. Where display is necessary, prompt before printing and offer a file-output alternative with restrictive permissions.
  • HTTPS certificate validation. Never disable certificate validation by default (this is required for resolvers in Retrieving DID Log Resources). Certificate pinning is not required (and is incompatible with platform hosting), but ecosystems with appropriate trust models can opt in.
  • Error messages. Avoid including internal stack traces, file paths, or library versions in problemDetails returned to clients.

Privacy Considerations§

This section is non-normative.

This section addresses the privacy considerations in alignment with [RFC6973] Section 5, and aligns with the [DID-CORE] requirements in DID Core 7.4.

Surveillance§

Retrieving a DID Log reveals the Resolver's interest in the DID to the source it retrieves from: the host of a web location, or a watcher. Because did:vh lets a client choose its sources, it can reduce this by using a cached copy, a watcher it trusts, or a copy supplied by the party presenting the DID, and by not retrieving from web locations chosen by others. A Resolver or client can also retrieve through privacy-enhancing network tools, such as Tor or a VPN, or a trusted resolver service, so that the source does not learn the network address of the party interested in the DID. While the contents of a DID Log are generally intended to be public, the timing, frequency, and correlation of updates can be observed and may reveal operational patterns or associations.

A Resolver that retains the latest versionId of each DID it resolves, as permitted in Comparing Copies of a DID Log, keeps a record of which DIDs it has resolved and when. A Resolver offered as a service to other parties is advised to protect that record as it would any request log, to retain it no longer than it is useful, and to say in its documentation whether it retains it; a client concerned about this can use a local Resolver.

Stored Data Compromise§

DID Logs may be stored on web servers, by watchers, and in other stores. A compromise of any of them could allow tampering with the stored copy. Cryptographic signatures protect integrity, so tampering is detected, but confidentiality is not provided.

Correlation and Identification§

A did:vh DID contains no domain name, so it does not by itself link its controller to a domain owner. src values, alsoKnownAs entries and service endpoints can reintroduce such a link, so DID Controllers that want to avoid it are advised not to publish them. The use of a static DID and public DID Log entries can enable correlation of activities over time; DID Controllers are advised to avoid embedding personal identifiers or unnecessary service endpoints in DID documents.

For peer-to-peer use, a DID Controller can create a separate did:vh DID for each relationship, so that the relationships cannot be correlated by identifier.

Unsolicited Traffic§

Distributing a DID Log does not inherently solicit inbound traffic beyond normal DID resolution. However, public exposure of service endpoints in the DID Document may increase unsolicited interactions. DID Controllers are advised to avoid publishing unnecessary endpoints.

Right to Erasure (GDPR Art. 17)§

A did:vh DID Log is likely to be held in several places — by watchers, at web locations, and by peers. A DID Controller cannot remove every copy itself. The watcher deletion operation defined in Watcher HTTP API Operations can be used to request removal from watchers; how such requests are handled is best defined by ecosystem governance.

Secondary Use§

Information published in the DID Log may be repurposed by third parties. DID Controllers are advised to minimise the publication of data that could be used for purposes beyond the intended use.

Disclosure§

All data in the DID Log may become publicly accessible, so sensitive data does not belong in it.

Exclusion§

did:vh does not require a DID Controller to own a domain name or operate any particular infrastructure. A DID Log can be published on a web-hosting platform that serves static files over HTTPS, kept with watchers or in an ecosystem’s registry, or exchanged directly with peers. This reduces barriers to participation, and because the DID does not change when the log is kept elsewhere, a DID Controller who loses access to one host can move the log to another without affecting the DID.

No Phone Home Mitigations§

A privacy concern in decentralized identity ecosystems is the possibility of an issuer of identity information (such as Verifiable Credentials) being notified when and where individuals present those credentials. This “phone home” surveillance problem (such as described by nophonehome.com) can occur if the presentation of a credential requires contacting the issuer’s infrastructure, either directly or indirectly, in a way that can be linked to the credential holder.

Sourcing a did:vh DID Log need not involve the DID Controller at all: the log can be passed with the DID, retrieved from a watcher, or held from an earlier resolution. A src value or service endpoint chosen by an issuer, however, may point at infrastructure the issuer operates, as may related resources retrieved at presentation time — for example, revocation registries or status lists. If these resources are implemented in a way that enables linking access patterns to individual credential holders, the DID Controller could use that information for surveillance.

Privacy-respecting credential issuers, credential holders, and verifiers all have a role in preventing “phone home” surveillance. The following practices can help:

  • Privacy-respecting Issuers (including DID Controllers hosting VC-related resources)
    • Do not design or deploy credential-related resources (such as revocation registries) in a way that enables the identification of individual holders at presentation time.
    • Use privacy-preserving designs — such as compact status lists, batching, and/or large revocation registries that provide “lost in a crowd” anonymity — to prevent correlation of access patterns to specific credential holders.
    • Use HTTP caching headers (e.g., Cache-Control, ETag) to enable CDNs, browsers, and resolvers to cache DID resources efficiently.
  • Holders
    • Pass the issuer’s DID Log along with the credential, or use watchers, trusted intermediaries, or privacy-enhancing network tools to retrieve DID and status data without revealing the holder’s location or identity to the issuer.
    • Separate in time interactions with the issuer from credential presentations to verifiers.
  • Verifiers
    • Be flexible in the timeliness of credential status checks, and consider omitting them entirely when risk is low.
    • Prefer DID Logs passed by the holder, or held from earlier resolutions and checked against watchers, over retrieving from locations operated by the issuer.
    • Use privacy-enhancing network tools or trusted intermediary resolvers to retrieve DID resources in a way that avoids revealing verifier identity or network location to the issuer or hosting provider.

A related risk is that an issuer may deliberately or inadvertently create holder-specific identifiers for data elements that are expected to be common across all holders — for example, by issuing personalized revocation list URLs, unique resource paths, or holder-specific src values. This enables tracking of specific holders even if the underlying credential is otherwise privacy-preserving. Preventing this requires shared responsibility: issuers are expected not to generate such holder-specific identifiers; holders and verifiers can reject credentials or status mechanisms that contain them; and independent third parties, including watchers, can monitor issuer implementations to detect and report violations of this principle.

Definitions§

base58btc
Applies [DRAFT-MSPORNY-BASE58-03] to convert data to a base58 encoding. Used in did:vh for encoding hashes for SCIDs and entry hashes. did:vh uses the plain base58btc encoding, without a multibase prefix, for SCIDs, entry hashes and nextKeyHashes values: for example, a SHA-256 multihash encodes to a string beginning Qm, not zQm.
Data Integrity
W3C Data Integrity is a specification of mechanisms for ensuring the authenticity and integrity of structured digital documents using cryptography, such as digital signatures and other digital mathematical proofs.
Decentralized Identifier
Decentralized Identifiers (DIDs) [DID-CORE] are a type of identifier that enable verifiable, decentralized digital identities. A DID refers to any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) as determined by the controller of the DID.
DID Controller
The entity that controls (creates, updates, deactivates) a given DID, as defined in [DID-CORE].
DIDDoc
A DID Document as defined by [DID-CORE] — the document returned when a DID is resolved.
DID Log
A DID Log is a list of Entries, with an entry added for each update of the DID, including new versions of the DIDDoc or changed information necessary to generate or validate the DID. It is conventionally stored as the file did.jsonl.
DID Log Entry
A DID Log Entry is a JSON object that defines the authorized transformation of a DIDDoc from one version to the next. The initial entry establishes the DID and version 1 of the DIDDoc. All entries are stored in the DID Log.
DID Log source
A place from which a client sources the DID Log of a did:vh DID — that is, gets either the log itself or a reference to it — before passing it to a Resolver: the context in which the DID was received, a watcher, a peer, or a web location. See Sourcing the DID Log.
DID Method
DID methods are the mechanism by which a particular type of DID and its associated DID document are created, resolved, updated, and deactivated. DID methods are defined using separate DID method specifications. This document is the DID Method Specification for did:vh.
DID Resources
A DID Resource is an object (often a file) that is referenced by a DID URL, with a path to the resource. The DID URL allows DID URL dereferencers to locate and retrieve specific content associated with a DID. Examples include configuration files, schemas, credential definitions, logos, images or other data linked to the DID.
did:key
did:key as described in the W3C CCG specification is a DID method that derives a DID document directly from a single, encoded cryptographic public key, requiring no registry, ledger, or network interaction to resolve. did:vh uses did:key DIDs to identify witnesses, where its cryptographic self-sufficiency means a witness proof can be verified without resolving anything.
Entry Hash
A did:vh entry hash is a hash generated using a formally defined process over the input data to a log entry, excluding the Data Integrity proof. The input data includes content from the predecessor to the version of the DID, ensuring that all the versions are “chained” together in a sort of microledger. The generated entry hash is subsequently included in the versionId of the log entry and MUST be verified by a Resolver.
ISO8601
A date/time expressed using the ISO8601 Standard.
JSON Canonicalization Scheme
[RFC8785] defines a method for canonicalizing a JSON structure such that it is suitable for verifiable hashing or signing.
JSON Lines
A file of JSON Lines, as described on the site https://jsonlines.org/. In short, JSONL is lines of JSON with whitespace removed and separated by a newline that is convenient for handling streaming JSON data or log files.
multibase
A specification for encoding binary data as a string using a prefix that indicates the encoding.
multikey
A verification method that encodes key types into a single binary stream that is then encoded as a multibase value.
multihash
Per the [MULTIFORMATS], multihash is a specification for differentiating instances of hashes. Software creating a hash prefixes (according to the specification) data to the hash indicating the algorithm used and the length of the hash, so that software receiving the hash knows how to verify it. Although multihash supports many hash algorithms, for interoperability, DID Controllers MUST only use the hash algorithms defined in this specification as permitted.
parameters
did:vh parameters are a defined set of configurations that control how the DID Controller has generated the DID, and how the Resolver processes the DID Log entries. The use of parameters allows for the controlled evolution of did:vh log handling, such as evolving the set of permitted hash algorithms or cryptosuites. This enables support for very long lasting identifiers – decades.
Pre-Rotation
A technique for a controller of a cryptographic key to commit to the public key it will rotate to next, without exposing that actual public key. It protects from an attacker that gains knowledge of the current private key from being able to rotate to a new key known only to the attacker.
Resolver
A DID resolver, as defined in [DID-RESOLUTION], that implements this specification: given a did:vh DID and a DID Log passed in its resolution options, it verifies the log and returns the current or a historical DIDDoc.
self-certifying identifier
An object identifier derived from initial data such that an attacker could not create a new object with the same identifier. The input for a did:vh SCID is the initial DID log entry with the placeholder {SCID} wherever the SCID is to be placed. A did:vh DID is did:vh: followed by its SCID.
Verifiable Credential
A verifiable credential can represent all of the same information that a physical credential represents, adding technologies such as digital signatures, to make the credentials more tamper-evident and so more trustworthy than their physical counterparts. The Verifiable Credential Data Model is a W3C Standard.
Verifiable Presentation
A verifiable presentation data model is part of W3C’s Verifiable Credential Data Model that contains a set of verifiable credentials about a credentialSubject, and a signature across the verifiable credentials generated by that subject. In this specification, the use case of primary interest is where the DID is the credentialSubject and the DID signs the verifiable presentation.
watcher
Watchers are entities within a decentralized trust ecosystem that retrieve, verify, archive and re-serve DID Logs, indexed by SCID, on behalf of their clients. Watchers maintain a historical cache of DID versions and verify that the DID Controller is consistently following the prescribed evolution process, including detecting conflicting copies of a log. For did:vh, watchers are also a primary DID Log source. Watchers provide endpoints for retrieving DID information and to receive webhooks notifying the watcher about updates to the DID and deletion requests.
webhook
A webhook is a mechanism that enables real-time communication between systems by sending HTTP callbacks (typically POST requests) to a specified URL when an event occurs. Webhooks are commonly used for event-driven integrations and automation. Although webhooks are an implementation pattern rather than a formal standard, best practices are documented in [RFC8030].
witness
Witnesses are participants in the process of creating and verifying a version of a did:vh DIDDoc. Notably, a witness receives from the DID Controller a DID Log entry ready for distribution, verifies it according to this specification, and approves it according to its ecosystem governance (whatever that might be). If the verification and approval process results are positive, the witness returns to the DID Controller a Data Integrity proof attesting to that positive result. did:vh witnesses are identified by did:key DIDs.
threshold
An algorithm that defines when a sufficient number of witnesses have submitted valid Data Integrity proofs for a DID Log entry such that it is approved and can be distributed. The algorithm details are in the Witness Threshold Algorithm section of this specification.

References§

DI-EDDSA-V1.0
Data Integrity EdDSA Cryptosuites v1.0. Dave Longley; Manu Sporny; 2024-12-08. Status: W3C Technical Recommendation.
DID-CORE
Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC.
DID-EXTENSION-RESOLUTION
DID Resolution Extensions Registry. The Decentralized Identifier Working Group (W3C); 2024-11-19. Status: W3C Technical Report.
DID-PEER
Peer DID Method Specification. Daniel Hardman; Stephen Curran; Sam Curren; 2025-05-20. Status: DIF Draft v1.0.
DID-RESOLUTION
Decentralized Identifier Resolution (DID Resolution) v1. Stephen Curran; Joe Andrieu; 2026-09-02. Status: W3C Editor's Draft.
DRAFT-MSPORNY-BASE58-03
The Base58 Encoding Scheme. S. Nakamoto; Manu Sporny; 2021-03-31. Status: Internet Draft.
MULTIFORMATS
Multiformats. Juan Benet; Manu Sporny; 2024-02-21. Status: Internet Draft.
RFC2119
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner; 1997-03. Status: Best Current Practice.
RFC2181
Clarifications to the DNS Specification. R. Elz; R. Bush; 1997-07. Status: Proposed Standard.
RFC3552
Guidelines for Writing RFC Text on Security Considerations. E. Rescorla; B. Korver; 2003-07. Status: Best Current Practice.
RFC3986
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter; 2005-01. Status: Internet Standard.
RFC5234
Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell; 2008-01. Status: Internet Standard.
RFC5891
Internationalized Domain Names in Applications (IDNA): Protocol. J. Klensin; 2010-08. Status: Proposed Standard.
RFC6234
US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF). D. Eastlake 3rd; T. Hansen; 2011-05. Status: Informational.
RFC6973
Privacy Considerations for Internet Protocols. A. Cooper; H. Tschofenig; B. Aboba; J. Peterson; J. Morris; M. Hansen; R. Smith; 2013-07. Status: Informational.
RFC8030
Generic Event Delivery Using HTTP Push. M. Thomson; E. Damaggio; B. Raymor, Ed.; 2016-12. Status: Proposed Standard.
RFC8089
The "file" URI Scheme. M. Kerwin; 2017-02. Status: Proposed Standard.
RFC8174
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba; 2017-05. Status: Best Current Practice.
RFC8484
DNS Queries over HTTPS (DoH). P. Hoffman; P. McManus; 2018-10. Status: Proposed Standard.
RFC8785
JSON Canonicalization Scheme (JCS). A. Rundgren; B. Jordan; S. Erdtman; 2020-06. Status: Informational.
RFC9110
HTTP Semantics. R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.; 2022-06. Status: Internet Standard.
RFC9457
Problem Details for HTTP APIs. M. Nottingham; E. Wilde; S. Dalal; 2023-07. Status: Proposed Standard.
SEMVER
Semantic Versioning 2.0.0. Tom Preston-Werner; 2013-06-18. Status: Internet Draft.

did:vh Version Changelog§

The following lists the substantive changes in each version of the specification.

  • Version 0.1 (Editors Draft)
    • Initial draft, derived from the did:webvh Editors Draft (beyond v1.0) with the domain and path removed from the DID: a did:vh DID is did:vh:<SCID>.
    • Defines resolution as the DID Resolution resolve(did, resolutionOptions) function, with did:vh resolution options for the two ways of passing the log and witness proofs file: directly (didLog, didWitness) or by reference (srcLog, srcWitness, each naming a file at an https web location, a location using another supported URL scheme such as ipns, or, for a local Resolver, a loopback http location or a local file), plus the version options (versionId, versionTime, versionNumber).
    • Defines the src DID URL query parameter, aligned with did:scid, naming the location of did.jsonl and did-witness.json, from which a dereferencer derives srcLog and srcWitness by appending the file names. No /.well-known/ location is used.
    • Defines the result of processing a log in which an entry fails verification, and uses the featureNotSupported error for a method version the Resolver does not support.
    • States that no entry can follow one that sets updateKeys to [], and that pre-rotation is active for an entry only if the nextKeyHashes in effect before it is non-empty.
    • Returns ttl and the witness threshold as integers in the DID Document Metadata, as now permitted by DID Resolution.
    • Makes retaining a versionId from an earlier resolution optional for a Resolver, with a warning (not an error) for a copy shorter than the retained version.
    • Defines the did:vh watcher HTTP API in its own OpenAPI definition, derived from that of did:webvh.
    • Adds the includeDidLog option, returning the verified log and witness proofs file in the resolution metadata (didLog, didWitness).
    • Adds optional comparison of the log with copies held by watchers (checkWatchers, extraWatchers, minCopies), with the logForked and insufficientCopies errors and copies and warnings resolution metadata.
    • Describes, non-normatively, how a client sources the DID Log (the log itself or a reference to it) before resolution — known in context, from watchers, peer-to-peer exchange (with updates sent as the complete log or just the new entries), and from a web location — and how to manage freshness and duplicity.
    • Removes the did:webvh features that depend on a web location: the DID-to-HTTPS transformation and domain-name rules, the portable parameter, and parallel did:web publishing.
    • Requires versionTime values in whole seconds; makes an entry that sets deactivated to true the last entry of the DID; requires DID Controllers to distribute only logs that extend the log they previously distributed, and witnesses to approve at most one entry with the same predecessor.
    • Makes the Security and Privacy Considerations sections non-normative, moving the transport requirements into Publishing and Retrieving DID Log Resources, adds a Forked Logs section, and drops the Resolver Validation Checklist.