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:vhis 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:vhDID can be used between two parties who exchange their DID Logs directly, in the manner ofdid:peer[DID-PEER], while still supporting key rotation, pre-rotation and the otherdid:vhfeatures.
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:
-
A DID Controller creates the first DID log entry exactly as in
did:webvh, using the DID stringdid:vh:{SCID}with the{SCID}placeholder, calculates the SCID and replaces the placeholders. -
The DID Log (
did.jsonl) is a JSON Lines file of DID log entries, one per line. Each entry is a JSON object containing:versionId– a value that combines the version number (starting at1and 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.versionTime– as asserted by the DID Controller.parameters– a set of parameters that impact the processing of the current and future log entries, such as the version of thedid:vhspecification being used, the SCID and the update key(s).state– the new version of the DIDDoc.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. -
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.
-
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 indid:vh:<SCID>?src=https://example.com/dids/issuer. -
The client calls the Resolver, passing the DID Log (and witness proofs) directly, or by reference in the
srcLog(andsrcWitness) 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. -
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:vhis a standalone DID method rather than a format of a metamethod.- The version of the specification in use is carried in the
methodparameter of the DID Log, as indid:webvh, rather than in the DID string. - In this version of
did:vh, thesrcparameter carries only a URL: anhttpsURL or a URL with another scheme the Resolver supports (such asipns).did:scidalso allows it to name a DID method that stores the log. srcis not adid:vhresolution option. A client passing the log to a Resolver by reference names each file explicitly, in thesrcLogandsrcWitnessoptions, which a dereferencer derives from asrcDID URL parameter. These options can also name loopbackhttpURLs and localfile: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" : [] }
- The value of
versionIdMUST be a string consisting of the DID version number (starting at1and incrementing by one per DID version), a literal dash-, and theentryHash, 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. - The value of
versionTimeMUST 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’sversionTimeis later than the previous entry’s, consecutive entries are at least one second apart. - The JSON object
parameterscontains the configurations/options set by the DID Controller to be used in the processing of current and future log entries. Permittedparametersare defined in thedid:vhDID Method Parameters section of this specification. - The JSON object
statecontains the DIDDoc for this version of the DID. - The JSON array
proofcontains 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.
-
Duplicate witness IDs.
{"threshold": 1, "witnesses": [{"id": "did:key:X"}, {"id": "did:key:X"}]}— the samedid:keyappears more than once in the witnesses list; each witness has to be unique. -
Pre-rotation active but
updateKeysomitted. If entry N-1 commitsnextKeyHashes: ["H1","H2"], then entry N has to contain an explicitupdateKeyswhose every member hashes to a value in["H1","H2"]. An entry N omittingupdateKeys(intending to inherit) fails verification. -
Wrong cryptosuite on log-entry proof.
{"type":"DataIntegrityProof","cryptosuite":"ecdsa-jcs-2019","proofPurpose":"assertionMethod"}— fails verification even if the signature is structurally valid, becauseparameters.methodwith valuedid:vh:1.0requireseddsa-jcs-2022. -
state.idis not the DID. The first entry hasparameters.scid: "Qm111...", and an entry hasstate.id: "did:vh:Qm222...","did:vh:Qm111...?src=https://example.com"or"did:webvh:Qm111...:example.com". Every entry’sstate.idhas to be exactlydid:vh:Qm111.... -
portableparameter present. An entry includes"portable": true.portableis not adid:vhparameter. -
Malformed
methodvalue. The first entry hasparameters.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 returnsfeatureNotSupported, and never silently downgrades.) -
Fractional seconds. An entry has
versionTime: "2025-04-01T17:39:50.123Z".versionTimevalues are in whole seconds. -
Entry after
updateKeys: []. Entry N setsupdateKeys: [](with pre-rotation not active). Entry N+1 setsnextKeyHashes: ["H1"]andupdateKeys: ["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’supdateKeys, which is empty.
DID Method Operations§
Create (Register)§
Creating a did:vh DID is done by carrying out the following steps.
-
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). Unlikedid:webvh, no domain name or path follows the placeholder: the location where the DID Log will be kept is not part of the DID. -
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.
- 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.
- 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
updateKeysproperty in parameters. - The public key(s) of the authorization key pair(s) MAY be used in the DIDDoc as well, but that is not required.
-
Create the initial DIDDoc for the DID The DIDDoc MUST contain the top level
idproperty, 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.
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.
-
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.- The value of
versionIdstring MUST be the placeholder literal"{SCID}". - The value of
versionTimestring 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. - The value of the
parametersproperty 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 thedid:vhDID 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. - The value of the
stateproperty MUST be the initial DIDDoc as defined in the previous step 3 of this process.
- The value of
-
Update the preliminary DID Log Entry to the initial DID Log Entry Use the preliminary DID log entry to perform the consecutive steps:
- 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.
- 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. - 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. - Replace the preliminary
versionIdvalue The value of theversionIdproperty MUST be updated with the literal string1(for version number 1), a literal-, followed by theentryHashvalue calculated in the previous step. - 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
updateKeysproperty in the parameters object and theproofPurposeset toassertionMethod. - 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.
-
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. -
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) indidWitness. - Passing by reference. The client passes, in
srcLog, a reference to the file from which the Resolver retrieves the DID Log, and, insrcWitness, a reference to the file from which it retrieves the witness proofs file (if any), as defined in ThesrcLogandsrcWitnessOptions. In this version ofdid: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
didLogandsrcLogMUST be given. - At most one of
didWitnessandsrcWitnessMAY be given. - At most one of
versionId,versionTimeandversionNumberMAY be given. - A malformed option, a value that does not conform to the rules for
srcLogorsrcWitness, a violation of any of the rules above, or anextraWatchersvalue that is not anhttpsURL, MUST cause theinvalidOptionserror. - A Resolver MUST support files passed directly. It MAY
decline to retrieve from
srcLogandsrcWitnessreferences, based on its policy (for example, a Resolver that never retrieves from locations chosen by its callers), and then MUST return thefeatureNotSupportederror, except as defined in Web Locations and Local Files. - A Resolver MUST support
versionIdandversionTime, and SHOULD supportversionNumber,checkWatchers,extraWatchers,minCopiesandincludeDidLog. A Resolver given an option it does not support MUST return thefeatureNotSupportederror 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, orhttpwith a loopback host: a web location, such ashttps://example.com/dids/issuer/did.jsonlorhttp://localhost:8000/dids/issuer/did.jsonl.file: a local file [RFC8089], such asfile:///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
httpsorhttpscheme 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 theinvalidOptionserror. - For
http, the host MUST be a loopback host:localhost, an IPv4 address in127.0.0.0/8, or[::1]. Anhttpreference with any other host MUST cause theinvalidOptionserror. Anhttpreference 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,%5Cand%00would otherwise pass unnoticed. A segment that fails a check MUST cause theinvalidOptionserror. - 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
invalidOptionserror. 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 hostlocalhost, 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 theinvalidOptionserror. - 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
invalidOptionserror 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
featureNotSupportederror. - 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:
-
The DID. The
didinput MUST conform to the ABNF in Method-Specific Identifier; if it does not, return theinvalidDiderror. -
The options. Validate the
resolutionOptionsas defined indid:vhResolution Options. If they are invalid, return theinvalidOptionserror. -
Getting the log. Get the DID Log according to how it was passed:
- Directly: the
didLogvalue. - By reference: retrieve it from the
srcLogreference as defined in ThesrcLogandsrcWitnessOptions. If the DID Log is not found, return thenotFounderror.
The witness proofs file is needed only if the active parameters require witnesses. When it is, use the
didWitnessvalue if one was given, or retrieve the file from thesrcWitnessreference if one was given, as defined in ThesrcLogandsrcWitnessOptions. - Directly: the
-
Processing the log. Process the DID Log as described below.
-
Other copies. If
checkWatchers,extraWatchersor aminCopiesgreater than1was given, or the Resolver has retained aversionIdfrom an earlier resolution of the DID, process the copies as described in Comparing Copies of a DID Log. -
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
errorlisted 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:
versionIdversionTimeparametersstate– the version’s DIDDoc.proof– a Data Integrity proof for the log entry.
For each entry:
- Update the currently active parameters with the
parameters from the entry (if any). The
parametersMUST adhere to thedid:vhDID 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
witnessparameter take effect only after the entry in which they are defined has been published.
- 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
- 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
proofPurposeset toassertionMethod.- If the active
updateKeysis empty — for example, after an entry that setupdateKeysto[]— no key is authorized and the entry fails verification. - 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.
- If the active
- Verify the
versionIdfor the entry.- The version number MUST be
1for 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. - Exactly one dash
-MUST follow the version number; missing or multiple dashes MUST cause the entry to fail verification. - The
entryHashMUST follow the dash, MUST be a valid multihash in the algorithm permitted by the activemethod, and MUST be verified per Entry Hash Generation and Verification. Verification MUST be performed for every entry.
- The version number MUST be
- The
versionTimeMUST be a valid UTC ISO8601 string with explicitZ(or+00:00); values without a zone designator, or expressing a non-UTC zone, MUST cause the entry to fail verification.- The
versionTimeMUST be in whole seconds. Values with fractional seconds MUST cause the entry to fail verification. - The
versionTimeof every entry MUST be strictly greater than the immediately preceding entry’s. Equal timestamps MUST cause the entry to fail verification. - The
versionTimeof 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.
- The
- 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
didinput. - Get the value of the log entry property
state, which is the DIDDoc for the version. Its top-levelidMUST be exactlydid:vh:followed by thescidparameter of the first entry. This check MUST apply to every entry’sstate.id, not just the first, and to every entry of any further copy retrieved withcheckWatchersorextraWatchers. An entry with a mismatch fails verification. - If Key Pre-Rotation is active (the previously active
nextKeyHashesis non-empty), the entry being processed MUST include an explicitparameters.updateKeysand MUST NOT rely on inheritance. The hash of every multikey inparameters.updateKeys(computed per Pre-Rotation Key Hash Generation and Verification) MUST appear in the previous entry’snextKeyHashes. The check applies to the fullupdateKeysset, not only keys that are new relative to the previous entry. A key not in the previous entry’snextKeyHashesMUST cause the entry to fail verification, even if it appeared in an earlier entry’supdateKeys. - If a previous entry set
deactivatedtotrue, the entry MUST be treated as failing verification, as defined in Deactivate (Revoke). - As each log entry is processed and verified, collect the
following information about each version:
- The DIDDoc.
- The
versionIdof the DIDDoc. - The UTC
versionTimeof the DIDDoc. - The latest list of active multikey formatted public keys
authorized to update the DID, from the
updateKeyslists in the parameters. - If pre-rotation is being used, the hashes of authorized keys
that are to be used in the
updateKeyslist of the next DID log entry. The pre-rotation hashes are in thenextKeyHasheslist in the parameters. - All other
did:vhprocessing configuration settings as defined in theparametersobject.
- If the
parametersfor 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.
- If the first entry failed verification, the DID is invalid: return the
invalidDiderror. - 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
invalidDiderror; - if no entry matches, return the
notFounderror.
- Otherwise, return the DIDDoc of the last valid entry. If any
entry failed verification, include the
invalid-entrieswarning 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:
- The copy passed directly or by reference is processed as defined in the Resolution Algorithm.
- If
checkWatchersis greater than0, the Resolver reads thewatchersparameter active at the last entry of the verified copy. IfcheckWatchersisall, 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. - The Resolver MUST retrieve a copy from each watcher
in
extraWatchers. - 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. - All copies are compared as described below, and each is reported in
copiesin the DID Resolution Metadata. - If fewer than
minCopiescopies have astatusofcurrentorbehind, the Resolver MUST fail resolution with theinsufficientCopieserror. The copy passed directly or by reference counts towardsminCopies.
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:
- Use the copy passed directly or by reference as the reference copy, once it has been fully verified.
- Compare each remaining copy to the reference copy by checking a single
versionIdin each:- If the copy has the same number of entries or fewer: compare the
versionIdof the copy’s last entry with the reference copy’sversionIdfor 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
versionIdof the reference copy’s last entry with the copy’sversionIdfor 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
versionIdvalues 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.
- If the copy has the same number of entries or fewer: compare the
- If the Resolver has retained a
versionIdfrom a previous resolution of the DID, compare it with the reference copy’sversionIdfor the same version number. The retainedversionIdwas 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-foundwarning 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
versionIdand the reference copy’sversionIdfor the same version number.
- 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
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 whoseversionIdis exactly equal to the given value. - By
versionTime: the log entry that was active at the given ISO8601 time — the entry with the latestversionTimethat is not later than the given time. - By
versionNumber: the log entry whose version number — the integer that precedes the-in itsversionId— 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:
versionId— TheversionIdof the DID log entry of the resolved DIDDoc version.versionTime— TheversionTimeof the DID log entry of the resolved DIDDoc version, as an ISO8601 timestamp.created— TheversionTimeof the first DID log entry, as an ISO8601 timestamp: when, according to the DID Controller, the DID was created.updated— TheversionTimeof the last valid DID log entry, as an ISO8601 timestamp.scid— The SCID of the DID.deactivated— A boolean that istrueif the DID has been deactivated, as defined in Deactivate (Revoke), even when an earlier version was resolved; otherwisefalse.ttl— The activettlparameter, an unsigned integer number of seconds: guidance from the DID Controller on how long to cache the resolution result.witness— The activewitnessparameter object, as defined in ThewitnessParameter, if witnesses are active, with itsthresholdas a positive integer.watchers— The active list of watcher URLs from thewatchersparameter.
“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— IfincludeDidLogwastrueand resolution succeeded, the DID Log the Resolver resolved from, as a JSON Lines string in the same form as thedidLogresolution 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— IfincludeDidLogwastrue, resolution succeeded and the DID Log requires witnesses, the witness proofs file the Resolver used, as a JSON array in the same form as thedidWitnessresolution option. The Resolver MAY omit items whoseversionIdis not in the returneddidLog, 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 givencheckWatchers,extraWatchersor aminCopiesgreater than1MUST includecopies. Each item has:source— Where the copy came from: thesrcLogvalue,didLogfor a log passed directly, or the URL of the watcher that served it.versionId— TheversionIdof the copy’s last log entry. Absent ifstatusisunavailable.status— One ofcurrent(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) orunavailable(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 acodefrom the list below and a human-readablemessage, identifying the copy it concerns by itssource, where there is one:copy-behind— A copy hasstatusbehind. The message includes how many entries the copy is behind the reference copy.copy-invalid— A copy hasstatusinvalid. The message includes the version number of the first log entry that failed verification.copy-unavailable— A copy hasstatusunavailable. 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 aversionIdretained 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 thesrcLogreference, the requested version does not exist, or the resource referenced by a DID URL was not found.featureNotSupported— The Resolver declined to retrieve from asrcLogorsrcWitnessreference, does not support the scheme of such a reference, does not supportversionNumber,checkWatchers,extraWatchers,minCopiesorincludeDidLog, or does not support the version of this specification named in amethodparameter 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. TheproblemDetailsMUST include the fork report that section requires.insufficientCopies— Fewer thanminCopiescopies 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,versionTimeorversionNumberDID 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
srcvalue — 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 thesrcvalue, it derives the file URLs as defined in ThesrcDID URL Parameter and passes them by reference insrcLogandsrcWitness, or retrieves the files itself and passes them directly indidLoganddidWitness.
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
httpsscheme or another scheme with hierarchical paths (such asipns). - An
httpsvalue MUST meet the requirements for anhttpsweb 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 anhttpURL. 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
invalidDidUrlerror for asrcvalue 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:
- Take the
srcvalue, removing any trailing/. - Append
/did.jsonl. The result is thesrcLogvalue. - Append
/did-witness.jsonto the value from step 1. The result is thesrcWitnessvalue.
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:
- Make the desired changes to the DIDDoc. The top-level
idin the DIDDoc MUST remaindid:vh:<SCID>. See the note on future use bydid:scid:vhfor how this may change in a later version. - Define the parameters JSON object to include the properties that
affect the evolution of the DID. The
parametersMUST be from those listed in thedid:vhDID 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.
- Generate a preliminary DID log entry JSON object containing the
following properties:
- The value of
versionIdMUST be the value ofversionIdfrom the previous DID log entry. - The
versionTimevalue 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. - The parameters passed in as a JSON object.
- Set the
stateJSON object to be the new version of the DIDDoc.
- The value of
- Calculate the new
versionIdof 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. - Replace the value of the
versionIdproperty in the preliminary DID Log Entry with the value produced in the previous step. - 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
proofPurposeset toassertionMethod. - If Key Pre-Rotation is being used, the hash of all
updateKeysentries in theparametersproperty MUST match a hash in the array ofnextKeyHashesparameter from the previous DID log entry, as defined in the Pre-Rotation Key Hash Generation and Verification section of this specification. - The proof JSON object MUST be added as the value of the
proofproperty in the log entry. - The entry MUST be made a JSON Line by removing extra
whitespace, adding a
\nto the entry. - 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.
- The new log entry MUST be appended to the existing contents of the DID Log.
- 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:
- Skip any received entry whose
versionIdis identical to that of an entry it already holds. If a received entry has the same version number as a held entry but a differentversionId, the update is duplicitous and MUST be rejected. - Append the remaining entries, in order, to a copy of the held DID Log.
- Resolve the DID with that copy as
didLog, the received witness proofs file (or, if none was received, the held one) asdidWitness, and theversionIdof the last appended entry asversionId. - 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
srcLogandsrcWitness. - An ecosystem DID host. An ecosystem requires its participants to publish
their
did:vhDID 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 insrcLogandsrcWitness. - A previously resolved log. The client kept the files from an earlier
resolution — for example, as returned with the
includeDidLogresolution 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
srcparameter. The client received a DID URL such asdid:vh:<SCID>?src=https://example.com/dids/issuer, and uses the location as described in Readingdid:vhDID 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
watchersparameter lists watchers that archive the log. - The DIDDoc
alsoKnownAsproperty can includedid:vhDID URLs for the same DID with asrcparameter, one for each location where the DID Log is published (a web location, or another scheme such asipns), as indid: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
methodparameter (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. Themethodparameter appears in the first log entry, and can appear in later entries to upgrade the DID to a newer [SEMVER] version of thedid:vhspecification, 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
witnessornextKeyHashes) are set to defined values, described below, to indicate they are no longer active. -
The JSON
nullvalue 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 thedid: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
methodvalue MUST bedid: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 amethodvalue not of this form MUST fail verification. - A Resolver MUST NOT process an entry whose
methodvalue 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 code0x12) 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’scryptosuiteproperty; an absent, mismatched, or non-conformantcryptosuiteMUST cause the entry to fail verification. Verifying onlyproofPurposeis insufficient.- witness did:key identifiers MUST use a key
compliant with the
eddsa-jcs-2022cryptosuite defined in [DI-EDDSA-V1.0].
- witness did:key identifiers MUST use a key
compliant with the
- Permitted hash algorithms:
scid: The SCID value for the DID.- MUST appear in the first log entry.
- MUST NOT appear in later log entries.
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
updateKeysarray MUST be used to authorize each log entry, where active is defined as follows.- In the first log entry, the active
updateKeysis the one defined in that entry. - In all other log entries without Key Pre-Rotation
active, the active
updateKeysis that of the most recent prior log entry. - In all other log entries with Key Pre-Rotation
active, the active
updateKeysis that of the most current log entry. - Whether Key Pre-Rotation is active for an entry is defined in Authorized Keys.
- In the first log entry, the active
updateKeysMAY be set to an empty array[]to stop further updates without deactivating the DID. Any log entry after one whoseupdateKeysis 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 theupdateKeyslist in the next log entry. At least one entry ofnextKeyHashesMUST be added to the nextupdateKeyslist.- 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
nextKeyHashesto a non-empty array, Key Pre-Rotation is active for every subsequent entry, as defined in Authorized Keys. While active, bothnextKeyHashesANDupdateKeysMUST be present as explicit properties in every subsequent log entry until pre-rotation is deactivated (by settingnextKeyHashesto[]). A subsequent entry that omits either MUST fail verification, even if the omission would otherwise inherit the previous value. Inheritance ofupdateKeysis 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’snextKeyHashes. - A DID Controller MAY include extra hashes in the
nextKeyHashesarray that are not subsequently used in anupdateKeysentry. Any unused hashes innextKeyHashesarrays are ignored. - The value of
nextKeyHashesMAY 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
witnessproperty is updated from{}, the change is immediately active, and the corresponding log entry MUST be witnessed. - The
witnessparameter MAY be set to{}to indicate that witnesses are not (or no longer) being used. If witnesses are active when thewitnessparameter is set to{}, that log entry MUST be witnessed.
- Defaults to
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.
- Defaults to
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
falseif 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.
- Defaults to
ttl: An unsigned integer that indicates how long, in seconds, the DID Controller expects a Resolver or client to cache the resolveddid:vhDID 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 theTTLparameter used in DNS [RFC2181]. Caching adid:vhcan 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. Fordid:vh,ttlis 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.
- Defaults to
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
methodparameter: Themethodparameter specifies the version of thedid:vhspecification 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 indid:vhDID Method Parameters. This allows long-lived DIDs to transition to updated algorithm sets over time. -
Version-specific algorithm policies: Each version of the
did:vhspecification 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, thedid:vh:1.0version 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:vhspecification will be released that removes or replaces the compromised algorithms. DID Controllers can then rotate to the newer version by updating themethodparameter 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:
-
The
preliminary log entry with placeholdersconsists of the following pre-publication JSON object of what will become the first log entry. The placeholder is the literal string “{SCID}”.- The
versionIdentry, which MUST be{SCID}. - The
versionTimeentry, 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
parametersfor the initial log entry as defined by the DID Controller, with the placeholder wherever the SCID will eventually be placed. - The
stateJSON 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 stringdid:vh:{SCID}.
- The
-
JCSis an implementation of the JSON Canonicalization Scheme [RFC8785]. It outputs a canonicalized representation of its JSON input. -
multihashis 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. -
<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 thedid:vhspecification being used by the DID Controller. -
base58btcis 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:
- Extract the first DID log entry and use it for the rest of the steps in this process.
- Extract the
scidproperty value from the parameters in the DID log entry. - Determine the hash algorithm used by the DID Controller from the
multihash
scidvalue.- The hash algorithm MUST be one listed in the
parameters defined by the version of the
did:vhspecification being used by the DID Controller based on the activemethodparameters property.
- The hash algorithm MUST be one listed in the
parameters defined by the version of the
- Remove the data integrity proof property from the DID log entry.
- Replace the
versionIdproperty value with the literal"{SCID}". - Treat the resulting log entry as a string and do a text
replacement of the
scidvalue from Step 2 with the literal string{SCID}. - Use the result and the hash algorithm (from Step 3) as input to the function defined in the Generate SCID section (above).
- The output string MUST match the
scidextracted in Step 2. If not, the first entry fails verification, and resolution fails with theinvalidDiderror.
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:
- Start with the preliminary log entry, without a
Data Integrity
proof. - Set its
versionIdto the predecessor value: for the first log entry, the SCID of the DID; for every other entry, theversionIdof the previous log entry. - Calculate the entry hash as
base58btc(multihash(JCS(entry), <hash algorithm>)), where:entryis the data from the previous step.JCSis an implementation of the JSON Canonicalization Scheme ([RFC8785]). Its output is a canonicalized representation of its input.multihashis 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.<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 thedid:vhspecification being used by the DID Controller.base58btcis an implementation of the base58btc function. Its output is the plain base58btc encoding of its input, without a multibase prefix.
- Set the
versionIdof the entry to<version number>-<entry hash>, where the version number is1for 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:
- Extract the
versionIdin the DID log entry, and remove from it the version number and dash prefix, leaving the log entryentryHashvalue. - Determine the hash algorithm used by the DID Controller from the
multihash
entryHashvalue.- The hash algorithm MUST be one listed in the
parameters defined by the version of the
did:vhspecification being used by the DID Controller based on themethodparameters property set in the current or most recent prior log entry.
- The hash algorithm MUST be one listed in the
parameters defined by the version of the
- Remove the Data Integrity
prooffrom the log entry. - Set the
versionIdin the entry object to be theversionIdfrom 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. - Calculate the hash string as
base58btc(multihash(JCS(entry), <hash algorithm>)), where:entryis the data from the previous step.JCSis an implementation of the JSON Canonicalization Scheme ([RFC8785]). Its output is a canonicalized representation of its input.multihashis 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.<hash algorithm>is the hash algorithm from Step 2.base58btcis an implementation of the base58btc function. Its output is the plain base58btc encoding of its input, without a multibase prefix.
- Verify that the calculated value matches the extracted
entryHashvalue 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:
typeisDataIntegrityProof,cryptosuiteMUST be one listed in the parameters defined by the version of thedid:vhspecification being used by the DID Controller based on the activemethodparameters property.proofPurposeisassertionMethod,verificationMethodresolves to a multikey that appears verbatim in the activeupdateKeys.
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.
- Generate a new key pair. The key type MUST be one that can be used as a
did:vhauthorization key. - Generate a multikey representation of the public key of the new key pair.
- Calculate the hash string as
base58btc(multihash(multikey, <hash algorithm>)), where:multikeyis the multikey representation of the public key from Step 2.multihashis 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.<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 thedid:vhspecification being used by the DID Controller.base58btcis an implementation of the base58btc function. Its output is the plain base58btc encoding of its input, without a multibase prefix.
- Insert the calculated hash into the
nextKeyHashesarray being built up within the parameters property. - 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
updateKeysproperty 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:
- For each multikey in the
updateKeysproperty in theparametersof the log entry, calculate the hash and hash algorithm for the multihash multikey. - The hash algorithm MUST be one listed in the
parameters defined by the version of the
did:vhspecification being used by the DID Controller. - The resultant hash MUST be in the
nextKeyHashesarray from the previous log entry prior to being processed. If not, the entry fails verification. - A new
nextKeyHasheslist MUST be in theparametersof 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. ThethresholdMUST be between 1 and the number of distinctwitnesses[].idvalues, inclusive. Awitnessparameter wherethresholdis missing, non-integer, < 1, or > count(distinct ids) MUST cause the entry that sets it to fail verification; Resolvers MUST NOT silently coerce a malformedwitnessto “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 adid:keyDID and MUST be unique within the array (compared byte-for-byte after Unicode NFC normalisation). Eachidcontributes at most one approval to threshold counting, regardless of how many proofs are attributed to it.- The
did:keyused as a witnessidMUST decode to a public key compatible with one of the cryptosuites listed in the parameters defined by the version of thedid:vhspecification being used by the DID Controller based on the activemethodparameters property. A witnessidwhose 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:
- Verify each Data Integrity proof in the witness proofs file for
the relevant
versionIdindependently. - Attribute each verified proof to a witness
idfrom the activewitnesseslist. Proofs that cannot be attributed (the proof’s key does not belong to any listed witness) MUST be discarded. - Form the set of distinct attributed
idvalues. The threshold check applies to the size of this set, not to the raw proof count. - 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:
versionIdis theversionIdof the DID log entry to which the witness proofs apply.proofis an array of Data Integrity proofs that use theversionIdas input data. The permitted Data Integrity cryptosuite MUST be one listed in the parameters defined by the version of thedid:vhspecification being used by the DID Controller based on the activemethodparameters property, and theproofPurposeset toassertionMethod.
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:
- Parse the proof’s
verificationMethodasdid:key:<multibase>#<multibase>and recover the public key by decoding the body multibase per the did:key specification. - 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:
- The most recent proof for a distributed DID Log entry.
- An additional proof that applies to an undistributed DID Log entry.
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
proofelement) for the new version of the DID, and shares it with the active 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
witnessparameter 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.
- A witness that does not yet hold the DID Log — for
example, one added to the
- 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:keyDID.- The specification leaves to implementers how witness proofs are sent to the DID Controller.
- The DID Controller MUST add the proof to the record for the
applicable
versionIdfor the undistributed DID log entry in thedid-witness.jsonfile.- The DID Controller MAY make the updated
did-witness.jsonfile available as new witness proofs are added to the file. - The DID Controller MUST make the updated
did-witness.jsonfile available after a threshold of witness proofs have been received and before the witnessed DID Log is distributed.
- The DID Controller MAY make the updated
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:
- 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.
- Get the witness proofs file, passed directly in
didWitnessor retrieved from thesrcWitnessreference. If no witness proofs file was passed, or thesrcWitnessreference was not found, treat the file as containing no proofs. - For each entry in the witness proofs file, confirm its
versionIdmatches aversionIdpresent 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. - Verify enough proofs to meet the threshold for all entries requiring witnessing.
- For each entry requiring witnessing, confirm a threshold of verified,
distinct-witness proofs whose
versionIdmatches 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:
- 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 (seedid:keybody/fragment check). - No previously verified proof was found in the witnesses array for the same
versionIdandid(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:
- Notifications (typically) from the DID Controller:
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 asrcquery parameter: notifies the watcher of a log update, prompting retrieval of the latest DID Log (and witness proofs file) from the locationsrcnames, as defined in ThesrcDID URL Parameter. As for any DID URL, thesrcvalue cannot be a local file or loopback reference. - POST
<WATCHER URL>/log?did=<DID>, where there is nosrcparameter: notifies the watcher of a log update, and MUST carry the complete DID Log as the request body, with media typetext/jsonl. If witnesses are active, the DID Controller MUST first send the witness proofs file with POST<WATCHER URL>/witness?did=<DID>, with media typeapplication/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 a404 Not Foundstatus 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 latestdid-witness.jsonfile 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 a404 Not Foundstatus 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§
- 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.
- Self-signed TLS certificates SHOULD NOT be used in production.
- 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: *. - 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:
- 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. - 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.
- Case-insensitive percent-decoding. Normalise the case of percent-encoded octets, per [RFC3986] §2.1, before making any allow or deny decision.
- Re-validate after decoding. Apply all host and path checks to the
decoded values. Percent-encoded IP literals and traversal sequences (such
as
%2E%2Eand%2e%2e) MUST be rejected after decoding. - 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. - 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. - 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. TheContent-Lengthheader 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. - 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
versionIdit 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
logForkedwhen 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 theextraWatchersresolution 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. Adid:vhlog 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:vhmeans 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
includeDidLogoption, 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
versionTimebe strictly greater than the previous one, in whole seconds, and not in the future, constrains log length — a log with implausibly rapidversionTimeprogression is likely malformed. However, this does not fully prevent the attack, as a patient attacker can pace log entry generation to match validversionTimeincrements. -
The size cap and timeout required in Retrieving DID Log Resources bound the cost of a single resolution. A declared
Content-Lengthlets 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 todidLoganddidWitnessvalues. 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:vhverification 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
extraWatchersURL 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 fromsrcLogandsrcWitnessreferences at all, refuse or limitextraWatchers(seedid:vhResolution 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
includeDidLogoption, 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
srcDID URL parameter is never afile: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 ThesrcDID URL Parameter. - Misleading association. The domain in a reference or
srcvalue 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 anysrcvalue 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 ThesrcLogandsrcWitnessOptions).
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.,
0600on 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
problemDetailsreturned 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
base58encoding. Used indid:vhfor encoding hashes for SCIDs and entry hashes.did:vhuses the plain base58btc encoding, without a multibase prefix, for SCIDs, entry hashes andnextKeyHashesvalues: for example, a SHA-256 multihash encodes to a string beginningQm, notzQm. - 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:vhDID — 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:keyas 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:vhusesdid:keyDIDs to identify witnesses, where its cryptographic self-sufficiency means a witness proof can be verified without resolving anything.- Entry Hash
- A
did:vhentry 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 theversionIdof 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,
JSONLis 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:vhparameters 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 ofdid:vhlog 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:vhDID 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:vhSCID is the initial DID log entry with the placeholder{SCID}wherever the SCID is to be placed. Adid:vhDID isdid: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 thecredentialSubjectand 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:vhDIDDoc. 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:vhwitnesses 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:webvhEditors Draft (beyond v1.0) with the domain and path removed from the DID: adid:vhDID isdid:vh:<SCID>. - Defines resolution as the DID Resolution
resolve(did, resolutionOptions)function, withdid:vhresolution 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 anhttpsweb location, a location using another supported URL scheme such asipns, or, for a local Resolver, a loopbackhttplocation or a local file), plus the version options (versionId,versionTime,versionNumber). - Defines the
srcDID URL query parameter, aligned withdid:scid, naming the location ofdid.jsonlanddid-witness.json, from which a dereferencer derivessrcLogandsrcWitnessby 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
featureNotSupportederror for amethodversion the Resolver does not support. - States that no entry can follow one that sets
updateKeysto[], and that pre-rotation is active for an entry only if thenextKeyHashesin effect before it is non-empty. - Returns
ttland thewitnessthresholdas integers in the DID Document Metadata, as now permitted by DID Resolution. - Makes retaining a
versionIdfrom an earlier resolution optional for a Resolver, with a warning (not an error) for a copy shorter than the retained version. - Defines the
did:vhwatcher HTTP API in its own OpenAPI definition, derived from that ofdid:webvh. - Adds the
includeDidLogoption, 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 thelogForkedandinsufficientCopieserrors andcopiesandwarningsresolution 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:webvhfeatures that depend on a web location: the DID-to-HTTPS transformation and domain-name rules, theportableparameter, and paralleldid:webpublishing. - Requires
versionTimevalues in whole seconds; makes an entry that setsdeactivatedtotruethe 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.
- Initial draft, derived from the