Update

did:btcr2 DID documents can be updated by anchoring BTCR2 Updates to Bitcoin transactions. These transactions MAY be published to the Bitcoin network.

Any property in the DID document may be updated except the id. Doing so would invalidate the DID document.

The update operation has the following function signature:

fn update(
  didSourceDocument,
  jsonPatches,
  targetVersionId,
  verificationMethodId,
  privateKey,
) ->
  signedUpdate

Input arguments:

didSourceDocument: The source DID document.
jsonPatches: An array of JSON patch documents [RFC6902] with the changes to be made to the source DID document.
targetVersionId: The versionId of the target DID document that the new BTCR2 Signed Update will yield.
verificationMethodId: The verificationMethod ID used for signing the BTCR2 Update.
privateKey: Private key associated with the verificationMethodId.
- An implementation MAY use the verificationMethodId ID to retrieve the private key from a key material manager.

Outputs:

signedUpdate: A copy of the BTCR2 Signed Update anchored to the Bitcoin blockchain by a BTCR2 Update Announcement.

Process

Updating a did:btcr2 DID document is a matter of constructing a BTCR2 Signed Update then announcing that update via one or more BTCR2 Beacons listed in the DID document. The update announcement process varies depending on the Beacon Type.

Constructing a BTCR2 Signed Update is a two-step process. First, a BTCR2 Unsigned Update is constructed. Then the update is signed with a private key to construct the BTCR2 Signed Update.

Construct BTCR2 Unsigned Update

This process constructs a BTCR2 Unsigned Update (data structure).

Apply all JSON patches in jsonPatches to didSourceDocument to create didTargetDocument. didTargetDocument MUST be conformant to DID Core v1.1 [DID-CORE]. An INVALID_DID_UPDATE error MUST be raised if didTargetDocument.id is not equal to didSourceDocument.id.

Fill the BTCR2 Unsigned Update (data structure) template below with the required template variables.

array-of-patches: jsonPatches serialized to a JSON string.
source-hash: didSourceDocument hashed with the JSON Document Hashing algorithm.
target-hash: didTargetDocument hashed with the JSON Document Hashing algorithm.
target-version-id: The value of targetVersionId.

Hide

Show Template

{
  "@context": [
    "https://w3id.org/security/v2",
    "https://w3id.org/zcap/v1",
    "https://w3id.org/json-ld-patch/v1",
    "https://btcr2.dev/context/v1"
  ],
  "patch": {{array-of-patches}},
  "sourceHash": "{{source-hash}}",
  "targetHash": "{{target-hash}}",
  "targetVersionId": {{target-version-id}}
}

Let update be the result of parsing the rendered template as JSON. The resulting BTCR2 Unsigned Update (data structure) MUST be conformant to this specification.

Construct BTCR2 Signed Update

This process constructs a BTCR2 Signed Update (data structure) from update, a BTCR2 Unsigned Update (data structure).

An INVALID_DID_UPDATE error MUST be raised if the didSourceDocument.verificationMethod Set does not contain an id matching verificationMethodId.

An INVALID_DID_UPDATE error MUST be raised if the didSourceDocument.capabilityInvocation Set does not contain verificationMethodId.

Create cryptosuite as a BIP340 Cryptosuite [BIP340-Cryptosuite] instance with privateKey and "bip340-jcs-2025" cryptosuite.

Fill the Data Integrity [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)}.

Hide

Show Template

{
  "@context": [
    "https://w3id.org/security/v2",
    "https://w3id.org/zcap/v1",
    "https://w3id.org/json-ld-patch/v1",
    "https://btcr2.dev/context/v1"
  ],
  "type": "DataIntegrityProof",
  "cryptosuite": "bip340-jcs-2025",
  "verificationMethod": "{{ verification-method }}",
  "proofPurpose": "capabilityInvocation",
  "capability": "{{ capability }}",
  "capabilityAction": "Write"
}

Let proofConfig be the result of parsing the rendered template as JSON. The resulting Data Integrity Config (data structure) MUST be conformant to Verifiable Credentials Data Integrity 1.0 [VC-DATA-INTEGRITY].

Pass update and proofConfig to the cryptosuite.createProof method and set update.proof to the resulting Data Integrity Proof (data structure).

Announce DID Update

BTCR2 Signed Updates are announced to the Bitcoin blockchain depending on the Beacon Type.

Announcing to a Singleton Beacon

A BTCR2 Update Announcement for a Singleton Beacon is the BTCR2 Signed Update hashed with the JSON Document Hashing algorithm. This 32-byte SHA-256 hash is used as the Signal Bytes when constructing a Beacon Signal Bitcoin transaction. The Beacon Signal is signed by the private key that controls the Beacon Address and broadcast to the Bitcoin network. To broadcast signed Bitcoin transactions, see the [Bitcoin-Core] source code.

Announcing to an Aggregate Beacon

Aggregating and announcing updates for multiple did:btcr2 identifiers is the responsibility of the Aggregation Service. The main responsibilities include establishing a protocol for one or more rounds of secure group communications amongst Aggregation Participants, advertising available Aggregation Cohorts to Aggregation Participants including the creation, management, timing and scheduling of those Aggregation Cohorts, and broadcasting a Bitcoin transaction to the Bitcoin network that includes signatures from all Aggregation Participants in a given Aggregation Cohort.

Keyboard shortcuts