@did-btcr2/method 0.19.0 → 0.22.0

package/src/core/types.ts

@@ -1,5 +1,5 @@
 import { HexString } from '@did-btcr2/common';
-import { BTCR2SignedUpdate } from '@did-btcr2/cryptosuite';
+import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
 import { SMTProof } from './interfaces.js';
 
 /**
@@ -41,7 +41,7 @@ export type Sidecar = {
    * Optional array of BTCR2 Signed Updates. Required if the DID being resolved
    * has ever had a published BTCR2 Update.
    */
-  updates?: Array<BTCR2SignedUpdate>
+  updates?: Array<SignedBTCR2Update>
 
   /**
    * Optional array of CAS Announcements. Required if the DID being reslved has
@@ -56,23 +56,40 @@ export type Sidecar = {
   smtProofs?: Array<SMTProof>;
 };
 
+/**
+ * The Sidecar data structure used for Singleton Beacons.
+ */
+export type SingletonBeaconSidecarData = Map<HexString, SignedBTCR2Update>;
+/**
+ * The Sidecar data structure used for CAS Beacons.
+ */
+export type CASBeaconSidecarData = Map<HexString, CASAnnouncement>;
+/**
+ * The Sidecar data structure used for SMT Beacons.
+ */
+export type SMTBeaconSidecarData = Map<string, SMTProof>;
+
 /**
  * The Sidecar data structure post-processing used for resolution.
  */
 export type SidecarData = {
   /**
    * Map of BTCR2 Signed Updates by their hash bytes.
-   * @type {Map<HexString, BTCR2SignedUpdate>}
    */
-  updateMap: Map<HexString, BTCR2SignedUpdate>;
+  updateMap: SingletonBeaconSidecarData;
+
   /**
    * Map of CAS Announcements by their hash bytes.
-   * @type {Map<HexString, CASAnnouncement>}
    */
-  casMap: Map<HexString, CASAnnouncement>;
+  casMap: CASBeaconSidecarData;
+
   /**
    * Map of SMT Proofs by their ID.
-   * @type {Map<string, SMTProof>}
    */
-  smtMap: Map<string, SMTProof>;
+  smtMap: SMTBeaconSidecarData;
 }
+
+/**
+ * Union type for all Beacon Sidecar data structures.
+ */
+export type BeaconSidecarData = SingletonBeaconSidecarData | CASBeaconSidecarData | SMTBeaconSidecarData;

package/src/core/update.ts

@@ -1,44 +1,24 @@
 import {
-  INVALID_DID_DOCUMENT,
+  Canonicalization,
   INVALID_DID_UPDATE,
-  INVALID_PUBLIC_KEY_TYPE,
   JSONPatch,
-  MethodError,
-  NOT_FOUND,
+  KeyBytes,
   PatchOperation,
   UpdateError
 } from '@did-btcr2/common';
-import { BTCR2SignedUpdate, BTCR2UnsignedUpdate, DataIntegrityConfig, SchnorrMultikey } from '@did-btcr2/cryptosuite';
-import { CompressedSecp256k1PublicKey, SchnorrKeyPair, Secp256k1SecretKey } from '@did-btcr2/keypair';
-import { Kms } from '@did-btcr2/kms';
-import type { DidService } from '@web5/dids';
-import { canonicalization } from '../did-btcr2.js';
-import { Appendix } from '../utils/appendix.js';
-import { DidDocument, DidVerificationMethod } from '../utils/did-document.js';
+import {
+  DataIntegrityConfig,
+  SchnorrMultikey,
+  SignedBTCR2Update,
+  UnsignedBTCR2Update
+} from '@did-btcr2/cryptosuite';
+import { Btcr2DidDocument, DidDocument, DidVerificationMethod } from '../utils/did-document.js';
+import { BeaconFactory } from './beacon/factory.js';
 import { BeaconService } from './beacon/interfaces.js';
-import { Identifier } from './identifier.js';
-import { SidecarData } from './types.js';
-
-export interface ConstructUpdateParams {
-    identifier: string;
-    sourceDocument: DidDocument;
-    sourceVersionId: number;
-    patch: PatchOperation[];
-}
-
-export interface UpdateParams extends ConstructUpdateParams {
-    verificationMethodId: string;
-    beaconIds: string[];
-}
-
-export type InvokePayloadParams = {
-  identifier: string;
-  BTCR2SignedUpdate: BTCR2SignedUpdate;
-  verificationMethod: DidVerificationMethod;
-}
+import { BitcoinNetworkConnection } from '@did-btcr2/bitcoin';
 
 /**
- * Implements {@link https://dcdpr.github.io/did-btcr2/#update | 4.3 Update}.
+ * Implements {@link https://dcdpr.github.io/did-btcr2/operations/update.html | 7.3 Update}.
  *
  * An update to a did:btcr2 document is an invoked capability using the ZCAP-LD
  * data format, signed by a verificationMethod that has the authority to make
@@ -51,154 +31,80 @@ export type InvokePayloadParams = {
  */
 export class Update {
   /**
-   * Implements {@link https://dcdpr.github.io/did-btcr2/#construct-did-update-payload | 4.3.1 Construct DID Update Payload}.
-   *
-   * The Construct DID Update Payload algorithm applies the documentPatch to the sourceDocument and verifies the
-   * resulting targetDocument is a conformant DID document. It takes in a Identifier, sourceDocument,
-   * sourceVersionId, and documentPatch objects. It returns an unsigned DID Update Payload.
+   * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#construct-btcr2-unsigned-update | 7.3.b Construct BTCR2 Unsigned Update}.
+   * This process constructs a BTCR2 Unsigned Update conformant to the spec template.
    *
-   * @param {ConstructPayloadParams} params See  {@link ConstructPayloadParams} for more details.
-   * @param {string} params.identifier The did-btcr2 identifier to use for verification.
-   * @param {DidDocument} params.sourceDocument The source document to be updated.
-   * @param {string} params.sourceVersionId The versionId of the source document.
-   * @param {DidDocumentPatch} params.patch The JSON patch to be applied to the source document.
-   * @returns {Promise<BTCR2SignedUpdate>} The constructed BTCR2SignedUpdate object.
-   * @throws {MethodError} InvalidDid if sourceDocument.id does not match identifier.
+   * @param {Btcr2DidDocument} sourceDocument The source DID document to be updated.
+   * @param {PatchOperation[]} patches The array of JSON Patch operations to apply to the sourceDocument.
+   * @param {number} sourceVersionId The version ID of the source document.
+   * @returns {Promise<SignedBTCR2Update>} The constructed SignedBTCR2Update object.
+   * @throws {UpdateError} InvalidDid if sourceDocument.id does not match identifier.
    */
-  public static async construct({
-    identifier,
-    sourceDocument,
-    sourceVersionId,
-    patch,
-  }: {
-    identifier: string;
-    sourceDocument: DidDocument;
-    sourceVersionId: number;
-    patch: PatchOperation[];
-  }): Promise<BTCR2UnsignedUpdate> {
-
-    // 1. Check that sourceDocument.id equals identifier else MUST raise invalidDIDUpdate error.
-    if (sourceDocument.id !== identifier) {
-      throw new UpdateError(
-        'Identifier mismatch: sourceDocument.id !== identifier',
-        INVALID_DID_UPDATE, { sourceDocument, identifier }
-      );
-    }
-
-    // 2. Initialize an unsigned update.
-    const unsignedUpdate: BTCR2UnsignedUpdate = {
-    // 3. Set BTCR2SignedUpdate.@context to the following list
+  static async construct(
+    sourceDocument: Btcr2DidDocument,
+    patches: PatchOperation[],
+    sourceVersionId: number,
+  ): Promise<UnsignedBTCR2Update> {
+    // Initialize an unsigned update conformant to btcr2 spec.
+    const unsignedUpdate: UnsignedBTCR2Update = {
       '@context'      : [
         'https://w3id.org/security/v2',
         'https://w3id.org/zcap/v1',
         'https://w3id.org/json-ld-patch/v1',
         'https://btcr2.dev/context/v1'
       ],
-      // 4. Set BTCR2SignedUpdate.patch to documentPatch.
-      patch,
+      patch           : patches,
       targetHash      : '',
-      targetVersionId : 0,
-      sourceHash      : '',
+      targetVersionId : sourceVersionId + 1,
+      sourceHash      : Canonicalization.process(sourceDocument, { encoding: 'base58' }),
     };
 
-    // 5. Set targetDocument to the result of applying the documentPatch to the sourceDocument, following the JSON Patch
-    //    specification.
-    const targetDocument = JSONPatch.apply(sourceDocument, patch) as DidDocument;
+    // Apply all JSON patches to sourceDocument.
+    const targetDocument = JSONPatch.apply(sourceDocument, patches);
 
-    // 6. Validate targetDocument is a conformant DID document, else MUST raise invalidDIDUpdate error.
-    DidDocument.validate(targetDocument);
-
-    // 7. Set sourceHashBytes to the result of passing sourceDocument into the JSON Canonicalization and Hash algorithm.
-    // 8. Set BTCR2SignedUpdate.sourceHash to the base58-btc Multibase encoding of sourceHashBytes.
-    unsignedUpdate.sourceHash = (canonicalization.process(sourceDocument, { encoding: 'base58' })).slice(1);
-    // TODO: Question - is base58btc the correct encoding scheme?
-
-    // 9. Set targetHashBytes to the result of passing targetDocument into the JSON Canonicalization and Hash algorithm.
-    // 10. Set BTCR2SignedUpdate.targetHash to the base58-btc Multibase encoding of targetHashBytes.
-    unsignedUpdate.targetHash = (canonicalization.process(targetDocument, { encoding: 'base58' })).slice(1);
+    try {
+      // Ensure the targetDocument is conformant to DID Core v1.1.
+      DidDocument.isValid(targetDocument);
+    } catch (error) {
+      // If validation fails, throw an UpdateError with INVALID_DID_UPDATE.
+      throw new UpdateError(
+        'Error validating targetDocument: ' + (error instanceof Error ? error.message : String(error)),
+        INVALID_DID_UPDATE, targetDocument
+      );
+    }
 
-    // 11. Set BTCR2SignedUpdate.targetVersionId to sourceVersionId + 1.
-    unsignedUpdate.targetVersionId = sourceVersionId + 1;
+    // Set the targetHash by canonicalizing the targetDocument and encoding it in base58.
+    unsignedUpdate.targetHash = Canonicalization.process(targetDocument, { encoding: 'base58' });
 
-    // 12. Return updatePayload.
+    // Return unsignedUpdate.
     return unsignedUpdate;
   }
 
   /**
-   * {@link https://dcdpr.github.io/did-btcr2/#invoke-did-update-payload | 4.3.2 Invoke DID Update Payload}.
+   * Implements subsection {@link http://dcdpr.github.io/did-btcr2/operations/update.html#construct-btcr2-signed-update | 7.3.c Construct BTCR2 Signed Update }.
+   * This process constructs a BTCR2 Signed Update from a BTCR2 Unsigned Update.
    *
-   * The Invoke DID Update Payload algorithm takes in a Identifier, an unsigned BTCR2SignedUpdate, and a
-   * verificationMethod. It retrieves the privateKeyBytes for the verificationMethod and adds a capability invocation in
-   * the form of a Data Integrity proof following the Authorization Capabilities (ZCAP-LD) and VC Data Integrity
-   * specifications. It returns the invoked DID Update Payload.
-   *
-   * @param {InvokePayloadParams} params Required params for calling the invokePayload method
-   * @param {string} params.identifier The did-btcr2 identifier to derive the root capability from
-   * @param {BTCR2SignedUpdate} params.BTCR2SignedUpdate The updatePayload object to be signed
-   * @param {DidVerificationMethod} params.verificationMethod The verificationMethod object to be used for signing
-   * @returns {BTCR2SignedUpdate} Did update payload secured with a proof => BTCR2SignedUpdate
-   * @throws {MethodError} if the privateKeyBytes are invalid
+   * @param {string} did The did-btcr2 identifier to derive the root capability from
+   * @param {UnsignedBTCR2Update} unsignedUpdate The updatePayload object to be signed
+   * @param {DidVerificationMethod} verificationMethod The verificationMethod object to be used for signing
+   * @returns {SignedBTCR2Update} Did update payload secured with a proof => SignedBTCR2Update
+   * @throws {UpdateError} if the privateKeyBytes are invalid
    */
-  public static async invoke({
-    identifier,
-    unsignedUpdate,
-    verificationMethod
-  }: {
-    identifier: string;
-    unsignedUpdate: BTCR2UnsignedUpdate;
-    verificationMethod: DidVerificationMethod;
-  }): Promise<BTCR2SignedUpdate> {
-    // Deconstruct the verificationMethod
-    const { id: fullId, controller, publicKeyMultibase, secretKeyMultibase } = verificationMethod;
-
-    // Validate the verificationMethod
-    if(!publicKeyMultibase) {
-      throw new MethodError(
-        'Invalid publicKeyMultibase: cannot be undefined',
-        INVALID_PUBLIC_KEY_TYPE, verificationMethod
-      );
-    }
-
-    // 1. Set privateKeyBytes to the result of retrieving the private key bytes
-    // associated with the verificationMethod value.
-    // 1.1 Let id be the fragment portion of verificationMethod.id.
-    const id = fullId.slice(fullId.indexOf('#'));
-
-    // 1.2 Retrieve the key pair from the KMS or from the secretKeyMultibase
-    const components = Identifier.decode(id);
-    const keyUri = new CompressedSecp256k1PublicKey(components.genesisBytes).hex;
-    const keys = secretKeyMultibase
-      ? new SchnorrKeyPair({ secretKey: Secp256k1SecretKey.decode(secretKeyMultibase) })
-      : Kms.getKey(keyUri as string);
-    if (!keys) {
-      throw new MethodError(
-        'No privateKey found in kms or vm',
-        NOT_FOUND, verificationMethod
-      );
-    }
-
-    // 1.3 Set multikey to the result of passing verificationMethod and privateKeyBytes into the Multikey Creation algorithm.
-    const multikey = SchnorrMultikey.create({ id, controller, keys });
-
-    // 1.4 If the privateKey is not found, throw an error
-    if (!multikey) {
-      throw new MethodError(
-        'Failed to create multikey from verification method',
-        'MULTKEY_CREATE_FAILED', verificationMethod
-      );
-    }
-
-    // 2. Set rootCapability to the result of passing Identifier into the Derive Root Capability from did:btcr2
-    //    Identifier algorithm.
-    const rootCapability = Appendix.deriveRootCapability(identifier);
-    const cryptosuite = 'bip340-jcs-2025';
-    // 3. Initialize proofOptions to an empty object.
-    // 4. Set proofOptions.type to DataIntegrityProof.
-    // 5. Set proofOptions.cryptosuite to schnorr-secp256k1-jcs-2025.
-    // 6. Set proofOptions.verificationMethod to verificationMethod.id.
-    // 7. Set proofOptions.proofPurpose to capabilityInvocation.
-    // 8. Set proofOptions.capability to rootCapability.id.
-    // 9. Set proofOptions.capabilityAction to Write.
+  static async sign(
+    did: string,
+    unsignedUpdate: UnsignedBTCR2Update,
+    verificationMethod: DidVerificationMethod,
+    secretKey: KeyBytes,
+  ): Promise<SignedBTCR2Update> {
+    // Parse the controller from the verificationMethod
+    const controller = verificationMethod.controller;
+    // Parse the fragment from the vmId
+    const id = verificationMethod.id.slice(verificationMethod.id.indexOf('#'));
+
+    // Construct a Schnorr Multikey
+    const multikey = SchnorrMultikey.fromSecretKey(id, controller, secretKey);
+
+    // Define the Data Integrity proof config
     const config: DataIntegrityConfig = {
       '@context' : [
         'https://w3id.org/security/v2',
@@ -206,94 +112,43 @@ export class Update {
         'https://w3id.org/json-ld-patch/v1',
         'https://btcr2.dev/context/v1'
       ],
-      cryptosuite,
+      cryptosuite        : 'bip340-jcs-2025',
       type               : 'DataIntegrityProof',
-      verificationMethod : fullId,
+      verificationMethod : verificationMethod.id,
       proofPurpose       : 'capabilityInvocation',
-      capability         : rootCapability.id,
+      capability         : `urn:zcap:root:${encodeURIComponent(did)}`,
       capabilityAction   : 'Write',
     };
 
-    // 10. Set cryptosuite to the result of executing the Cryptosuite Instantiation algorithm from the BIP340 Data
-    //     Integrity specification passing in proofOptions.
+    // Go from multikey => cryptosuite => diproof
     const diproof = multikey.toCryptosuite().toDataIntegrityProof();
 
-    // 12. Set BTCR2SignedUpdate to the result of executing the Add Proof algorithm from VC Data Integrity passing
-    //     BTCR2SignedUpdate as the input document, cryptosuite, and the set of proofOptions.
-    // 13. Return BTCR2SignedUpdate.
-    return await diproof.addProof(unsignedUpdate, config);
+    // Use the config to add a proof to the unsigned update
+    return diproof.addProof(unsignedUpdate, config);
   }
 
   /**
-   * Implements {@link https://dcdpr.github.io/did-btcr2/#announce-did-update | 4.3.3 Announce DID Update}.
-   *
-   * The Announce DID Update algorithm retrieves beaconServices from the sourceDocument and calls the Broadcast DID
-   * Update algorithm corresponding to the type of the Beacon. It takes in a Identifier, sourceDocument, an array of
-   * beaconIds, and a BTCR2SignedUpdate. It returns an array of signalsMetadata, containing the necessary
-   * data to validate the Beacon Signal against the BTCR2SignedUpdate.
-   *
-   * @param {AnnounceUpdatePayloadParams} params Required params for calling the announcePayload method
-   * @param {DidDocument} params.sourceDocument The did-btcr2 did document to derive the root capability from
-   * @param {string[]} params.beaconIds The BTCR2SignedUpdate object to be signed
-   * @param {BTCR2SignedUpdate} params.BTCR2SignedUpdate The verificationMethod object to be used for signing
-   * @returns {BTCR2SignedUpdate} The BTCR2SignedUpdate object containing data to validate the Beacon Signal
-   * @throws {MethodError} if the beaconService type is invalid
+   * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#announce-did-update | 7.3.d Announce DID Update}.
+   * BTCR2 Signed Updates are announced to the Bitcoin blockchain depending on the Beacon Type.
+   * @param {BeaconService} beaconService The BeaconService object representing the funded beacon to announce the update to.
+   * @param {SignedBTCR2Update} update The signed update object to be announced.
+   * @param {KeyBytes} secretKey The private key used to sign the update for announcement.
+   * @returns {SignedBTCR2Update} The SignedBTCR2Update object containing data to validate the Beacon Signal
+   * @throws {UpdateError} if the beaconService type is invalid
    */
-  public static async announce({
-    sourceDocument,
-    beaconIds,
-    signedUpdate
-  }: {
-    sourceDocument: DidDocument;
-    beaconIds: string[];
-    signedUpdate: BTCR2SignedUpdate;
-  }): Promise<SidecarData> {
-    // 1. Set beaconServices to an empty array.
-    const beaconServices: BeaconService[] = [];
-
-    // 2. sidecarData to an empty array.
-    let sidecarData: SidecarData | undefined;
-
-    // 3. For beaconId in beaconIds:
-    for (const beaconId of beaconIds) {
-      //    3.1 Find the beacon services in the sourceDocument
-      const beaconService = sourceDocument.service.find((s: DidService) => s.id === beaconId);
-
-      //    3.2 If no beaconService MUST throw beaconNotFound error.
-      if (!beaconService) {
-        throw new MethodError('Not found: sourceDocument does not contain beaconId', INVALID_DID_DOCUMENT, { beaconId });
-      }
-
-      //    3.3 Push beaconService to beaconServices.
-      beaconServices.push(beaconService);
-    }
-
-    // 4. For beaconService in beaconServices:
-    for (const beaconService of beaconServices) {
-      // 4.1 Set signalMetadata to null.
-      // 4.2 If beaconService.type == SingletonBeacon:
-      //    4.2.1 Set signalMetadata to the result of passing beaconService and BTCR2SignedUpdate to the Broadcast
-      //          Singleton Beacon Signal algorithm.
-      // 4.3 Else If beaconService.type == CASBeacon:
-      //    4.3.1 Set signalMetadata to the result of passing Identifier, beaconService and BTCR2SignedUpdate to
-      //          the Broadcast CIDAggregate Beacon Signal algorithm.
-      // 4.4 Else If beaconService.type == SMTBeacon:
-      //    4.4.1 Set signalMetadata to the result of passing Identifier, beaconService and BTCR2SignedUpdate to
-      //          the Broadcast SMTAggregate Beacon Signal algorithm.
-      // 4.5 Else:
-      //    4.5.1 MUST throw invalidBeacon error.
-      // const beacon = BeaconFactory.establish(beaconService);
-      // sidecarData = await beacon.broadcastSignal(signedUpdate);
-      console.log('TODO: refactor this code', signedUpdate, beaconService);
-    }
-    if(!sidecarData) {
-      throw new MethodError(
-        'Invalid beacon: no sidecarData found',
-        INVALID_DID_DOCUMENT, { beaconServices }
-      );
-    }
+  static async announce(
+    beaconService: BeaconService,
+    update: SignedBTCR2Update,
+    secretKey: KeyBytes,
+    bitcoin: BitcoinNetworkConnection
+  ): Promise<SignedBTCR2Update> {
+    // Establish a beacon object
+    const beacon = BeaconFactory.establish(beaconService);
+
+    // Broadcast the update
+    const result = await beacon.broadcastSignal(update, secretKey, bitcoin);
 
     // Return the sidecarData
-    return sidecarData;
+    return result;
   }
 }