diff --git a/src/algorithms.md b/src/algorithms.md index 5fb8d600..3b3772bf 100644 --- a/src/algorithms.md +++ b/src/algorithms.md @@ -10,7 +10,7 @@ These algorithms are referenced throughout this specification. ## DID-BTCR2 Identifier Encoding -Any errors encountered during this algorithm MUST raise an [`INVALID_DID`](./errors.html) error. +Any errors encountered during this algorithm MUST raise an [`INVALID_DID`] error. A **did:btcr2** identifier is created from three arguments: `version_number`, `network_name` and `key_or_hash` ([Genesis Bytes]). @@ -79,7 +79,7 @@ Example output: ## DID-BTCR2 Identifier Decoding -Any errors encountered during this algorithm MUST raise an [`INVALID_DID`](./errors.html) error. +Any errors encountered during this algorithm MUST raise an [`INVALID_DID`] error. Parsing a **did:btcr2** identifier produces three values: `version_number`, `network_name`, and `key_or_hash` ([Genesis Bytes]). diff --git a/src/conformance.md b/src/conformance.md index 2b15af18..c9782f97 100644 --- a/src/conformance.md +++ b/src/conformance.md @@ -11,4 +11,4 @@ The key words MAY, MUST, MUST NOT, RECOMMENDED, SHOULD, and SHOULD NOT in this d Interoperability of implementations of the **did:btcr2** DID method is tested by evaluating an implementation's ability to create, resolve, update, and deactivate, **did:btcr2** identifiers and DID documents that conform to this specification. Interoperability for producers and consumers of **did:btcr2** identifiers and DID documents is provided by ensuring the DIDs and DID documents conform. -Implementations MUST be conformant to all normative statements in Decentralized Identifiers v1.1 {{#cite DID-CORE}} and DID Resolution v0.3 {{#cite DID-RESOLUTION}}. +Implementations MUST be conformant to all normative statements in Decentralized Identifiers v1.1 {{#cite DID-CORE}} and the latest version of DID Resolution {{#cite DID-RESOLUTION}}. diff --git a/src/data-structures.md b/src/data-structures.md index 7ecb8a5b..758c30ea 100644 --- a/src/data-structures.md +++ b/src/data-structures.md @@ -165,7 +165,7 @@ The following properties MUST be included in the Data Integrity Config: - `cryptosuite`: The string `"bip340-jcs-2025"`. - `verificationMethod`: A valid `verificationMethod` reference that exists in the most recent DID document. - `proofPurpose`: The string `"capabilityInvocation"`. -- `capability`: A URN of the following format: `urn:zcap:root:${encodeURIComponent(did)}`. +- `capability`: A URN of the following format: `urn:zcap:root:${encodeURIComponent(did)}`. The `encodeURIComponent()` function is defined by ECMA-262 {{#cite ECMA-262}}. - `capabilityAction`: A string declaring the action required for the capability invocation. The string MUST be set to `"Write"`. @@ -277,7 +277,7 @@ SHA-256 hashes {{#cite SHA256}} (`id`, `updateId`, `hashes`) MUST be `"base64url ## Resolution Options { #resolution-options } -This data structure is defined by DID Resolution v0.3 {{#cite DID-RESOLUTION}}. +This data structure is defined by the latest version of DID Resolution {{#cite DID-RESOLUTION}}. Resolution options MAY contain the following properties: @@ -306,13 +306,15 @@ Resolution options MAY contain the following properties: ## DID Resolution Metadata { #did-resolution-metadata } -This data structure is defined by DID Resolution v0.3 {{#cite DID-RESOLUTION}}. +This data structure is defined by the latest version of DID Resolution {{#cite DID-RESOLUTION}}. Resolution metadata MAY contain the following properties: -- `contentType`: OPTIONAL media type of the returned DID document. E.g., `"application/ld+json"`. +- `contentType`: OPTIONAL media type of the returned DID document. E.g., `"application/did"`. - `error`: REQUIRED if an error occurs during DID resolution. +A **did:btcr2** resolver returning a bare DID document MUST use the media type `"application/did"` {{#cite DID-CORE}}. A resolver returning a full DID resolution result MUST use the media type `"application/did-resolution"` {{#cite DID-RESOLUTION}}. In both cases the `contentType` property records the media type of the DID document itself. + {% set hide_text = `` %} {% set ex_did_resolution_metadata = ` @@ -333,13 +335,14 @@ Resolution metadata MAY contain the following properties: ## DID Document Metadata { #did-document-metadata } -This data structure is defined by DID Resolution v0.3 {{#cite DID-RESOLUTION}}. +This data structure is defined by the latest version of DID Resolution {{#cite DID-RESOLUTION}}. -Document metadata MAY contain the following properties: +Document metadata contains the following properties: +- `confirmations`: REQUIRED integer number of confirmations for the Bitcoin block that contains the most recently applied unique update for the resolved DID document. `0` when no [BTCR2 Update] has been applied. - `deactivated`: REQUIRED boolean that represents whether the resolved DID document has been deactivated. - `updated`: OPTIONAL XML Datetime normalized to UTC without sub-second decimal precision of the last Update operation for the resolved DID document. -- `versionId`: OPTIONAL ASCII string representation of the version of the last Update operation for the resolved DID document. +- `versionId`: REQUIRED ASCII string representation of the version of the last Update operation for the resolved DID document. `"1"` when no [BTCR2 Update] has been applied. {% set hide_text = `` %} {% set ex_did_document_metadata = @@ -388,7 +391,7 @@ A Root Capability is an Object Capability used to authorize updates to a DID doc The Root Capability MUST be a map containing only the following properties: - `@context`: MUST be the context string `"https://w3id.org/zcap/v1"` -- `id`: MUST be a URN of the following format: `urn:zcap:root:${encodeURIComponent(did)}` +- `id`: MUST be a URN of the following format: `urn:zcap:root:${encodeURIComponent(did)}`. The `encodeURIComponent()` function is defined by ECMA-262 {{#cite ECMA-262}}. - `invocationTarget`: MUST be the `did`. - `controller`: MUST be the `did`. diff --git a/src/errors.md b/src/errors.md index 37f732fd..29aa46e8 100644 --- a/src/errors.md +++ b/src/errors.md @@ -5,7 +5,7 @@ # Errors -The algorithms described in this specification can raise the specific errors listed below. Additional error types defined in Section 10 of DID Resolution v0.3 {{#cite DID-RESOLUTION}} may also be raised. +The algorithms described in this specification can raise the specific errors listed below. Additional error types defined in the Errors section of the latest version of DID Resolution {{#cite DID-RESOLUTION}} may also be raised. These errors are assumed to be fatal and all **did:btcr2** operations must abort when one of these errors are raised. diff --git a/src/example-data/did-document-metadata.json b/src/example-data/did-document-metadata.json index b398c5ea..93169ba6 100644 --- a/src/example-data/did-document-metadata.json +++ b/src/example-data/did-document-metadata.json @@ -1,4 +1,5 @@ { + "confirmations": 2016, "deactivated": false, "updated": "2025-01-06T16:23:10Z", "versionId": "5" diff --git a/src/example-data/did-resolution-metadata.json b/src/example-data/did-resolution-metadata.json index b36f70a8..515e301d 100644 --- a/src/example-data/did-resolution-metadata.json +++ b/src/example-data/did-resolution-metadata.json @@ -1,3 +1,3 @@ { - "contentType": "application/did+ld+json" + "contentType": "application/did" } diff --git a/src/includes/errors-links.tera b/src/includes/errors-links.tera index 692f12d5..116d9020 100644 --- a/src/includes/errors-links.tera +++ b/src/includes/errors-links.tera @@ -1,3 +1,4 @@ +[`INVALID_DID`]: https://www.w3.org/TR/did-resolution/#errors [`INVALID_DID_UPDATE`]: {{ root }}errors.md#invalid_did_update [`LATE_PUBLISHING`]: {{ root }}errors.md#late_publishing [`MISSING_UPDATE_DATA`]: {{ root }}errors.md#missing_update_data diff --git a/src/operations/resolve.md b/src/operations/resolve.md index e32a1b19..f7510fc1 100644 --- a/src/operations/resolve.md +++ b/src/operations/resolve.md @@ -8,7 +8,7 @@ Resolving a **did:btcr2** identifier iteratively builds a DID document by applying [BTCR2 Updates][BTCR2 Update] committed to the Bitcoin blockchain by [Authorized Beacon Signals][Authorized Beacon Signal] to an [Initial DID Document]. The [Initial DID Document] is either deterministically created from the DID or provided by [Sidecar Data]. -DID resolution is defined by DID Resolution v0.3 {{#cite DID-RESOLUTION}}. +DID resolution is defined by the latest version of DID Resolution {{#cite DID-RESOLUTION}}. The resolve operation has the following function signature: @@ -28,7 +28,7 @@ Resolution maintains the following state while building the DID document: * `current_document`: the DID document being assembled. * `current_version_id`: the version number being processed (starts at `1`). * `update_hash_history`: a list of [BTCR2 Unsigned Update] hashes used to detect duplicates. -* `block_confirmations`: confirmations for the Bitcoin block that contains the most recently applied unique update. +* `block_confirmations`: confirmations for the Bitcoin block that contains the most recently applied unique update (starts at `0`). The resolver: diff --git a/src/operations/update.md b/src/operations/update.md index 4722efb3..db4cddcf 100644 --- a/src/operations/update.md +++ b/src/operations/update.md @@ -91,7 +91,7 @@ Create `cryptosuite` as a BIP340 Cryptosuite {{#cite BIP340-Cryptosuite}} instan Fill the Data Integrity {{#cite VC-DATA-INTEGRITY}} template below with the required template variables. * `verification-method`: The value of `verificationMethodId`. -* `capability`: A URN of the following format: `urn:zcap:root:${encodeURIComponent(didSourceDocument.id)}`. +* `capability`: A URN of the following format: `urn:zcap:root:${encodeURIComponent(didSourceDocument.id)}`. The `encodeURIComponent()` function is defined by ECMA-262 {{#cite ECMA-262}}. {% set hide_text = `` %} {% set data_integrity_config_template = diff --git a/src/references.bib b/src/references.bib index d6bff9f8..49822ffb 100644 --- a/src/references.bib +++ b/src/references.bib @@ -100,18 +100,28 @@ @misc{DID-CORE } @misc{DID-RESOLUTION, - title = {Decentralized Identifier Resolution (DID Resolution) v0.3}, + title = {Decentralized Identifier Resolution (DID Resolution)}, author = {Markus Sabadello, Dmitri Zagidulin}, - howpublished = {Online}, - year = {2025}, - month = {September}, - url = {https://www.w3.org/TR/did-resolution}, + howpublished = {Online, latest version}, + year = {2026}, + url = {https://www.w3.org/TR/did-resolution/}, note = {DID-RESOLUTION}, abstract = {Decentralized identifiers (DIDs) are a new type of identifier for verifiable, "self-sovereign" digital identity. DIDs are fully under the control of the DID controller, independent from any centralized registry, identity provider, or certificate authority. DIDs resolve to DID Documents — simple documents that describe how to use that specific DID. This document specifies the algorithms and guidelines for resolving DIDs and dereferencing DID URLs. Additionally, this document describes the input and output metadata related to the DID resolution processes and further describes the data structures that may be returned from a DID resolution request. This document relies on the core DID specification, Decentralized Identifiers (DIDs) v1.1, which describes the underlying DID architecture in full detail.} } +@misc{ECMA-262, + title = {ECMAScript 2025 Language Specification}, + author = {Ecma International}, + howpublished = {Standard ECMA-262, 16th Edition}, + year = {2025}, + month = {June}, + url = {https://262.ecma-international.org/16.0/index.html}, + note = {ECMA-262}, + abstract = {ECMA-262, 16th Edition (ECMAScript 2025) defines the ECMAScript general-purpose programming language, including the URI handling functions encodeURIComponent() and decodeURIComponent() that escape and unescape components of Uniform Resource Identifiers.} +} + @misc{JSON-LD, title = {JSON-LD 1.1}, author = {Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Pierre-Antoine Champin, Niklas Lindström}, diff --git a/src/update-data-distribution.md b/src/update-data-distribution.md index 698621f3..8be8f6ab 100644 --- a/src/update-data-distribution.md +++ b/src/update-data-distribution.md @@ -1,3 +1,4 @@ +{% import "includes/ui.tera" as ui %} {% import "includes/links.tera" as links %} {{ links::include() }} @@ -77,13 +78,37 @@ the [CID]. The IPFS CIDv1 is a binary identifier constructed from the file hash as: * `0x01`, the code for CIDv1; -* `0x00`, the [multicodec](https://github.com/multiformats/multicodec) code for raw binary; -* `0x12`, the [multihash](https://github.com/multiformats/multihash) code for SHA-256; and +* `0x55`, the [multicodec](https://github.com/multiformats/multicodec) code for raw binary; +* `0x12`, the [multihash](https://github.com/multiformats/multihash) code for SHA-256; +* `0x20`, the length of the SHA-256 digest (32 bytes); and * the SHA-256 of the file. The stringified version of the CIDv1 is accomplished using [multibase](https://github.com/multiformats/multibase) encoding. The final URL is `"ipfs://"`. +{% set hide_text = `` %} +{% set ex_cidv1_construction = +' +Example input: + +* file content: the 3-byte ASCII string `"abc"` (`0x61 0x62 0x63`) + +Example output: + +* SHA-256 of the file: `ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad` +* CIDv1 bytes: `01551220ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad` +* stringified CIDv1 (multibase `base32`, prefix `b`): `"bafkreif2pall7dybz7vecqka3zo24irdwabwdi4wc55jznaq75q7eaavvu"` +* final URL: `"ipfs://bafkreif2pall7dybz7vecqka3zo24irdwabwdi4wc55jznaq75q7eaavvu"`' %} + +{{ ui::show_example_tabs( + group_id="cidv1-construction-example", + example=ex_cidv1_construction, + hide=hide_text, + default="hide", + show_label="Show Example", + hide_label="Hide" +) }} + A resolver retrieves a file associated with a SHA-256 hash by constructing the IPFS CIDv1 and requesting the file from an IPFS node.