@did-btcr2/method 0.18.1 → 0.20.0

package/src/core/crud/update.ts

@@ -1,292 +0,0 @@
-import {
-  BTCR2_DID_UPDATE_PAYLOAD_CONTEXT,
-  DidUpdateInvocation,
-  DidUpdatePayload,
-  INVALID_DID_DOCUMENT,
-  INVALID_DID_UPDATE,
-  INVALID_PUBLIC_KEY_TYPE,
-  Logger,
-  MethodError,
-  NOT_FOUND,
-  PatchOperation,
-  ProofOptions
-} from '@did-btcr2/common';
-import { 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 { BeaconService } from '../../interfaces/beacon.js';
-import { Appendix } from '../../utils/appendix.js';
-import { DidDocument, DidVerificationMethod } from '../../utils/did-document.js';
-import { SignalsMetadata } from '../../utils/types.js';
-import { BeaconFactory } from '../beacon/factory.js';
-import { Identifier } from '../identifier.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;
-  didUpdatePayload: DidUpdatePayload;
-  verificationMethod: DidVerificationMethod;
-}
-
-/**
- * Implements {@link https://dcdpr.github.io/did-btcr2/#update | 4.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
- * the update as specified in the previous DID document. Capability invocations
- * for updates MUST be authorized using Data Integrity following the
- * bip340-jcs-2025 cryptosuite with a proofPurpose of capabilityInvocation.
- *
- * @class Update
- * @type {Update}
- */
-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.
-   *
-   * @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<DidUpdatePayload>} The constructed DidUpdatePayload object.
-   * @throws {MethodError} 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<DidUpdatePayload> {
-
-    // 1. Check that sourceDocument.id equals identifier else MUST raise invalidDIDUpdate error.
-    if (sourceDocument.id !== identifier) {
-      throw new MethodError(
-        INVALID_DID_UPDATE,
-        'Source document id does not match identifier',
-        { sourceDocument, identifier}
-      );
-    }
-
-    // 2. Initialize didUpdatePayload to an empty object.
-    const didUpdatePayload: DidUpdatePayload = {
-    // 3. Set didUpdatePayload.@context to the following list
-      '@context'      : BTCR2_DID_UPDATE_PAYLOAD_CONTEXT,
-      // 4. Set didUpdatePayload.patch to documentPatch.
-      patch,
-      targetHash      : '',
-      targetVersionId : 0,
-      sourceHash      : '',
-    };
-    // TODO: Need to add btcr2 context. ["https://w3id.org/zcap/v1", "https://w3id.org/security/data-integrity/v2", "https://w3id.org/json-ld-patch/v1"]
-
-    // 5. Set targetDocument to the result of applying the documentPatch to the sourceDocument, following the JSON Patch
-    //    specification.
-    const targetDocument = JSON.patch.apply(sourceDocument, patch) as DidDocument;
-
-    // 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 didUpdatePayload.sourceHash to the base58-btc Multibase encoding of sourceHashBytes.
-    didUpdatePayload.sourceHash = (await JSON.canonicalization.process(sourceDocument, '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 didUpdatePayload.targetHash to the base58-btc Multibase encoding of targetHashBytes.
-    didUpdatePayload.targetHash = (await JSON.canonicalization.process(targetDocument, 'base58')).slice(1);
-
-    // 11. Set didUpdatePayload.targetVersionId to sourceVersionId + 1.
-    didUpdatePayload.targetVersionId = sourceVersionId + 1;
-
-    // 12. Return updatePayload.
-    return didUpdatePayload;
-  }
-
-  /**
-   * {@link https://dcdpr.github.io/did-btcr2/#invoke-did-update-payload | 4.3.2 Invoke DID Update Payload}.
-   *
-   * The Invoke DID Update Payload algorithm takes in a Identifier, an unsigned didUpdatePayload, 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 {DidUpdatePayload} params.didUpdatePayload The updatePayload object to be signed
-   * @param {DidVerificationMethod} params.verificationMethod The verificationMethod object to be used for signing
-   * @returns {DidUpdateInvocation} Did update payload secured with a proof => DidUpdateInvocation
-   * @throws {MethodError} if the privateKeyBytes are invalid
-   */
-  public static async invoke({
-    identifier,
-    didUpdatePayload,
-    verificationMethod
-  }: {
-    identifier: string;
-    didUpdatePayload: DidUpdatePayload;
-    verificationMethod: DidVerificationMethod;
-  }): Promise<DidUpdateInvocation> {
-    // 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) })
-      : await 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.
-    const options: ProofOptions = {
-      cryptosuite,
-      type               : 'DataIntegrityProof',
-      verificationMethod : fullId,
-      proofPurpose       : 'capabilityInvocation',
-      capability         : rootCapability.id,
-      capabilityAction   : 'Write',
-    };
-
-    // 10. Set cryptosuite to the result of executing the Cryptosuite Instantiation algorithm from the BIP340 Data
-    //     Integrity specification passing in proofOptions.
-    const diproof = multikey.toCryptosuite(cryptosuite).toDataIntegrityProof();
-
-    // 12. Set didUpdateInvocation to the result of executing the Add Proof algorithm from VC Data Integrity passing
-    //     didUpdatePayload as the input document, cryptosuite, and the set of proofOptions.
-    // 13. Return didUpdateInvocation.
-    return await diproof.addProof({ document: didUpdatePayload, options });
-  }
-
-  /**
-   * 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 didUpdateInvocation. It returns an array of signalsMetadata, containing the necessary
-   * data to validate the Beacon Signal against the didUpdateInvocation.
-   *
-   * @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 didUpdatePayload object to be signed
-   * @param {DidUpdateInvocation} params.didUpdatePayload The verificationMethod object to be used for signing
-   * @returns {SignalsMetadata} The signalsMetadata object containing data to validate the Beacon Signal
-   * @throws {MethodError} if the beaconService type is invalid
-   */
-  public static async announce({
-    sourceDocument,
-    beaconIds,
-    didUpdateInvocation
-  }: {
-    sourceDocument: DidDocument;
-    beaconIds: string[];
-    didUpdateInvocation: DidUpdateInvocation;
-  }): Promise<SignalsMetadata> {
-    // 1. Set beaconServices to an empty array.
-    const beaconServices: BeaconService[] = [];
-
-    // 2. signalMetadata to an empty array.
-    let signalsMetadata;
-
-    // 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 didUpdateInvocation to the Broadcast
-      //          Singleton Beacon Signal algorithm.
-      // 4.3 Else If beaconService.type == CIDAggregateBeacon:
-      //    4.3.1 Set signalMetadata to the result of passing Identifier, beaconService and didUpdateInvocation to
-      //          the Broadcast CIDAggregate Beacon Signal algorithm.
-      // 4.4 Else If beaconService.type == SMTAggregateBeacon:
-      //    4.4.1 Set signalMetadata to the result of passing Identifier, beaconService and didUpdateInvocation to
-      //          the Broadcast SMTAggregate Beacon Signal algorithm.
-      // 4.5 Else:
-      //    4.5.1 MUST throw invalidBeacon error.
-      const beacon = BeaconFactory.establish(beaconService);
-      signalsMetadata = await beacon.broadcastSignal(didUpdateInvocation);
-    }
-    if(!signalsMetadata) {
-      throw new MethodError(
-        'Invalid beacon: no signalsMetadata found',
-        INVALID_DID_DOCUMENT, { beaconServices }
-      );
-    }
-    Logger.debug('signalsMetadata', signalsMetadata);
-    // Return the signalsMetadata
-    return signalsMetadata;
-  }
-}

package/src/interfaces/beacon.ts

@@ -1,137 +0,0 @@
-import { RawTransactionRest, RawTransactionV2 } from '@did-btcr2/bitcoin';
-import { DidUpdatePayload, UnixTimestamp } from '@did-btcr2/common';
-import { DidServiceEndpoint, DidService as IDidService } from '@web5/dids';
-import { SidecarData, SignalsMetadata } from '../utils/types.js';
-
-/**
- * Beacon interface
- * @interface IBeacon
- * @type {IBeacon}
- */
-export interface IBeacon {
-    /**
-     * A unique identifier for the Beacon
-     * @type {string}
-     */
-    id: string;
-
-    /**
-     * The type of the Beacon
-     * @type {string}
-     */
-    type: string;
-
-    /**
-     * The service endpoint of the Beacon
-     * @type {string}
-     */
-    serviceEndpoint: DidServiceEndpoint;
-
-    /**
-     * Returns the Beacon Service object
-     * @type {BeaconService}
-     */
-    service: BeaconService;
-
-    /**
-     * Generates a Beacon Signal Transaction
-     * @param {string} didUpdatePayload The DID update payload
-     * @returns {BeaconSignal} The Beacon Signal
-     */
-    generateSignal(didUpdatePayload: string): BeaconSignal;
-
-    /**
-     * Processes a Beacon Signal.
-     * @param {RawTransactionV2} signal The raw transaction
-     * @param {SidecarData} signalsMetadata The signals metadata from the sidecar data
-     * @returns {Promise<DidUpdatePayload | undefined>} The DID update payload
-     */
-    processSignal(signal: RawTransactionV2, signalsMetadata: SignalsMetadata): Promise<DidUpdatePayload | undefined>;
-
-
-    /**
-     * Broadcasts a signal.
-     * @param {DidUpdatePayload} didUpdatePayload The DID update payload.
-     * @returns {Promise<SignalMetadata>} The signal metadata.
-     */
-    broadcastSignal(didUpdatePayload: DidUpdatePayload): Promise<SignalsMetadata>;
-}
-
-export interface BeaconService extends IDidService {
-    serviceEndpoint: DidServiceEndpoint;
-    casType?: string;
-}
-
-export interface BeaconServiceAddress extends BeaconService {
-    address: string;
-}
-export interface BeaconSignal {
-  beaconId: string;
-  beaconType: string;
-  beaconAddress: string;
-  tx: RawTransactionRest | RawTransactionV2;
-  blockheight: number;
-  blocktime: UnixTimestamp;
-}
-
-/**
- * Implements {@link https://dcdpr.github.io/did-btcr2/#update-beacons | 5. Beacons}.
- * Beacons are the mechanism by which a DID controller announces an update to their DID document by broadcasting an
- * attestation to this update onto the public Bitcoin network. Beacons are identified by a Bitcoin address and emit
- * Beacon Signals by broadcasting a valid Bitcoin transaction that spends from this Beacon address. These transactions
- * include attestations to a set of didUpdatePayloads, either in the form of Content Identifiers (CIDs) or Sparse Merkle
- * Tree (SMT) roots. Beacons are included as a service in DID documents, with the Service Endpoint identifying a Bitcoin
- * address to watch for Beacon Signals. All Beacon Signals broadcast from this Beacon MUST be processed as part of
- * resolution (see Read). The type of the Beacon service in the DID document defines how Beacon Signals SHOULD be
- * processed.
- * did:btcr2 supports different Beacon Types, with each type defining a set of algorithms for:
- *  1. How a Beacon can be established and added as a service to a DID document.
- *  2. How attestations to DID updates are broadcast within Beacon Signals.
- *  3. How a resolver processes a Beacon Signal, identifying, verifying, and applying the authorized mutations to a
- *     DID document for a specific DID.
- * This is an extendable mechanism, such that in the future new Beacon Types could be added. It would be up to the
- * resolver to determine if the Beacon Type is a mechanism they support and are willing to trust. If they are unable to
- * support a Beacon Type and a DID they are resolving uses that type then the DID MUST be treated as invalid.
- * The current, active Beacons of a DID document are specified in the document’s service property. By updating the DID
- * document, a DID controller can change the set of Beacons they can use to broadcast updates to their DID document over
- * time. Resolution of a DID MUST process signals from all Beacons identified in the latest DID document and apply them
- * in order determined by the version specified by the didUpdatePayload.
- * All resolvers of did:btcr2 DIDs MUST support the core Beacon Types defined in this specification.
- *
- * @abstract
- * @class Beacon
- * @type {Beacon}
- */
-export abstract class Beacon implements IBeacon {
-  public id: string;
-  public type: string;
-  public serviceEndpoint: DidServiceEndpoint;
-  public sidecar?: SidecarData;
-
-  constructor({ id, type, serviceEndpoint }: BeaconService, sidecar?: SidecarData) {
-    this.id = id;
-    this.type = type;
-    this.serviceEndpoint = serviceEndpoint;
-    this.sidecar = sidecar;
-  }
-
-  /**
-   * Returns the Beacon Service object.
-   */
-  abstract get service(): BeaconService;
-
-  /**
-   * Generates a Beacon Signal (implemented by subclasses).
-   */
-  abstract generateSignal(didUpdatePayload: string): BeaconSignal;
-
-  /**
-   * Processes a Beacon Signal (implemented by subclasses).
-   */
-  abstract processSignal(signal: RawTransactionRest | RawTransactionV2, signalsMetadata: SignalsMetadata): Promise<DidUpdatePayload | undefined>
-
-  /**
-   * Broadcasts a Beacon Signal (implemented by subclasses).
-   */
-  abstract broadcastSignal(didUpdatePayload: DidUpdatePayload): Promise<SignalsMetadata>;
-}

package/src/interfaces/crud.ts

@@ -1,33 +0,0 @@
-import { UnixTimestamp } from '@did-btcr2/common';
-import { DidResolutionOptions as IDidResolutionOptions } from '@web5/dids';
-import { DidDocument } from '../utils/did-document.js';
-import { SidecarData } from '../utils/types.js';
-
-/**
- * Options for resolving a DID Document
- * @param {?number} versionId The versionId for resolving the DID Document
- * @param {?UnixTimestamp} versionTime The versionTime for resolving the DID Document
- * @param {?SidecarData} sidecarData The sidecar data for resolving the DID Document
- */
-export interface DidResolutionOptions extends IDidResolutionOptions {
-  versionId?: number
-  versionTime?: UnixTimestamp;
-  sidecarData?: SidecarData;
-  network?: string;
-}
-export interface RootCapability {
-    '@context': string;
-    id: string;
-    controller: string;
-    invocationTarget: string;
-}
-export interface ReadBlockchainParams {
-  contemporaryDidDocument: DidDocument;
-  contemporaryBlockHeight: number | 1;
-  currentVersionId: number | 1;
-  targetVersionId?: number;
-  targetBlockHeight: number;
-  updateHashHistory: string[];
-  sidecarData?: SidecarData;
-  options?: DidResolutionOptions;
-}

package/src/utils/types.ts

@@ -1,41 +0,0 @@
-import { DidUpdatePayload, ProofBytes } from '@did-btcr2/common';
-import { BeaconService } from '../interfaces/beacon.js';
-import { DidDocument } from './did-document.js';
-import { BlockV3 } from '@did-btcr2/bitcoin';
-
-export type FindNextSignals = {
-  block: BlockV3;
-  beacons: BeaconService[]
-};
-export type Metadata = {
-  didUpdate: DidUpdatePayload;
-  proofs?: string;
-};
-export type SignalSidecarData = Metadata;
-export interface Sidecar {
-  did: string;
-}
-export type SignalsMetadata = { [signalId: string]: Metadata; };
-export interface SingletonSidecar extends Sidecar {
-  signalsMetadata: SignalsMetadata;
-}
-export interface CIDAggregateSidecar extends Sidecar {
-  initialDocument: DidDocument;
-  signalsMetadata: SignalsMetadata;
-  cidUpdates: Array<string>;
-}
-export interface SMTAggregateSidecar extends Sidecar {
-  initialDocument: DidDocument;
-  signalsMetadata: SignalsMetadata;
-  smtProof: ProofBytes;
-}
-export type BeaconSidecarData<T> =
-  T extends 'SingletonBeacon' ? SingletonSidecar :
-  T extends 'CIDAggregateBeacon' ? CIDAggregateSidecar :
-  T extends 'SMTAggregateBeacon' ? SMTAggregateSidecar :
-  T;
-export type SidecarData = BeaconSidecarData<SingletonSidecar | CIDAggregateSidecar | SMTAggregateSidecar>;
-export type GetSigningMethodParams = {
-  didDocument: DidDocument;
-  methodId?: string;
-};