Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Data Structures

For the purposes of interoperability, this specification defines data structures using the data model defined by the DID core v1.1 specification [DID-CORE].

Concrete representations of these data structures MUST conform to the JSON-LD 1.1 specification [JSON-LD].

All SHA-256 hashes [SHA256] that appear in concrete representations of these data structures MUST be encoded as a string using the "base64url" [RFC4648] encoding.

DID Document

A DID document is a map data structure defined by the DID core v1.1 specification [DID-CORE].

The following properties MUST be included:

  • @context: A context array containing the following context URLs:
    • "https://www.w3.org/TR/did-1.1"
    • "https://btcr2.dev/context/v1"
  • id: The did.

It can optionally include one or more of the following properties:

  • verificationMethod: A set of verification method objects.
  • assertionMethod: A set of references to verification methods or embedded verification method objects to be used for assertions.
  • capabilityInvocation: A set of references to verification methods or embedded verification method objects to be used for capability invocations.
  • service: An array of service objects.

In order for this DID document to be updatable, controllers must include at least one verification method with a capability invocation verification relationship and at least one BTCR2 Beacon service.

Genesis Document

A Genesis Document is a DID document (data structure) with the identifier set to the placeholder value (did:btcr2:_).

Initial DID Document

An Initial DID Document is a conformant DID document (data structure).

BTCR2 Unsigned Update

A BTCR2 Unsigned Update is a Map data structure with the following properties:

  • @context: A context array containing the following context URLs:
    • "https://w3id.org/zcap/v1"
    • "https://w3id.org/security/data-integrity/v2"
    • "https://w3id.org/json-ld-patch/v1"
    • "https://btcr2.dev/context/v1"
  • patch: A JSON Patch [RFC6902] object that defines a set of transformations to be applied to a DID document. The result of applying the patch MUST be a conformant DID document according to the DID core v1.1 specification [DID-CORE].
  • targetVersionId: The versionId of the DID document after the patch has been applied. The targetVersionId MUST be one more than the versionId of the DID document being updated.
  • sourceHash: A SHA-256 hash of the DID document that the patch MUST be applied to. The hash MUST be produced by the JSON Document Hashing algorithm.
  • targetHash: A SHA-256 hash of the DID document that results from applying the patch to the source document. The hash MUST be produced by the JSON Document Hashing algorithm.

BTCR2 Signed Update

A BTCR2 Signed Update is a Map data structure with the same properties as BTCR2 Unsigned Update (data structure) and one additional property:

Data Integrity Config

A Data Integrity [VC-DATA-INTEGRITY] proof with the proofPurpose set to "capabilityInvocation" and proofValue omitted.

The following properties MUST be included in the Data Integrity Config:

  • @context: A context array containing the follow context URLs:
    • "https://w3id.org/security/v2"
    • "https://w3id.org/zcap/v1"
    • "https://w3id.org/json-ld-patch/v1"
    • "https://btcr2.dev/context/v1"
  • type: The string "DataIntegrityProof".
  • 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)}.
  • capabilityAction: A string declaring the action required for the capability invocation. The string MUST be set to "Write".

Data Integrity Proof

A Data Integrity Proof with the proofPurpose set to "capabilityInvocation". This proof MUST be a valid invocation of the capability to update a did:btcr2 DID document.

This data structure is a Map data structure with the same properties as Data Integrity Config (data structure) and one additional property:

  • proofValue: MUST be a detached Schnorr signature produced according to Schnorr Signatures for secp256k1 [BIP340], as a Multibase "base-58-btc" [CID] encoded string.

Sidecar Data

The Sidecar Data contains optional properties:

SMT Proof

A SMT Proof data structure contains the following properties:

  • id: SHA-256 hash of the root node.
  • nonce: OPTIONAL 256-bit nonce generated for each update. MUST be encoded as a string using the "base64url" [RFC4648] encoding.
  • updateId: The OPTIONAL BTCR2 Signed Update (data structure) hashed with the JSON Document Hashing algorithm.
  • collapsed: Bitmap of zero nodes within the path (see: collapsed leaves).
  • hashes: Array of SHA-256 hashes representing the sibling SMT nodes from the leaf, containing the SHA-256 hash of the BTCR2 Signed Update or the “zero identity”, to the root.

Resolution Options

This data structure is defined by DID Resolution v0.3 [DID-RESOLUTION].

Resolution options MAY contain the following properties:

  • versionId: OPTIONAL ASCII string representation of the specific version of a DID document to be resolved.
  • versionTime: OPTIONAL XML Datetime normalized to UTC without sub-second decimal precision. The DID document to be resolved is the most recent version of the DID document that was valid for the DID before the specified versionTime.
  • sidecar: Sidecar Data (data structure).

DID Resolution Metadata

This data structure is defined by DID Resolution v0.3 [DID-RESOLUTION].

Resolution metadata MAY contain the following properties:

  • contentType: OPTIONAL media type of the returned DID document. E.g., "application/ld+json".
  • error: REQUIRED if an error occurs during DID resolution.

DID Document Metadata

This data structure is defined by DID Resolution v0.3 [DID-RESOLUTION].

Document metadata MAY contain the following properties:

  • 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.

CAS Announcement

A data structure that maps DIDs to BTCR2 Signed Update hashes. All BTCR2 Signed Updates (data structure) MUST be hashed with the JSON Document Hashing algorithm. The concrete representation of this data structure will be published to a CAS.

Root Capability

A Root Capability is an Object Capability used to authorize updates to a DID document. Implementation MAY use ZCAP-LD for capability invocations [ZCAP-LD].

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)}
  • invocationTarget: MUST be the did.
  • controller: MUST be the did.