@did-btcr2/method 0.13.1

package/src/btcr2/beacon/smt-aggregate.ts

@@ -0,0 +1,136 @@
+import { Btcr2Error, DidUpdatePayload } from '@did-btcr2/common';
+import { DidServiceEndpoint } from '@web5/dids';
+import { Beacon } from '../../interfaces/beacon.js';
+import { BeaconService, BeaconSignal } from '../../interfaces/ibeacon.js';
+import { RawTransactionV2 } from '../../types/bitcoin.js';
+import { BeaconSidecarData, SignalsMetadata, SMTAggregateSidecar } from '../../types/crud.js';
+
+/**
+ * TODO: Finish implementation
+ *
+ * Implements {@link https://dcdpr.github.io/did-btcr2/#smtaggregate-beacon | 5.3 SMTAggregate Beacon}.
+ *
+ * A SMTAggregate Beacon is a Beacon whose Beacon Signals are Bitcoin transactions containing the root of a Sparse
+ * Merkle Tree (SMT). The SMT root attests to a set of DID Update Payloads, however, the updates themselves MUST be
+ * provided along with a proof of inclusion against the SMT root through a Sidecar mechanism during resolution. Using
+ * the SMT root a resolver can then verify the inclusion proof for the given DID Update Payload. If a DID document
+ * includes a SMTAggregator Beacon in their set of Beacon services, then they MUST provide proofs for each signal that
+ * the Beacon broadcasts. If they did not submit an update to their DID in a signal, then they MUST provide a proof of
+ * non-inclusion for that signal.
+ *
+ * @class SMTAggregateBeacon
+ * @type {SMTAggregateBeacon}
+ * @extends {Beacon}
+ */
+export class SMTAggregateBeacon extends Beacon {
+  /**
+   * Creates an instance of SMTAggregateBeacon.
+   * @param {BeaconService} service The Beacon service.
+   * @param {?BeaconSidecarData} [sidecar] Optional sidecar data.
+   */
+  constructor(service: BeaconService, sidecar?: BeaconSidecarData<SMTAggregateSidecar>) {
+    super({ ...service, type: 'SMTAggregateBeacon' }, sidecar);
+  }
+
+  /**
+   * Get the Beacon service.
+   * @readonly
+   * @type {BeaconService} The Beacon service.
+   */
+  get service(): BeaconService {
+    const service = {
+      type            : this.type,
+      id              : this.id,
+      serviceEndpoint : this.serviceEndpoint
+    };
+    return service;
+  }
+
+  /**
+   * TODO: Figure out if this is necessary or not.
+   * @param {string} didUpdatePayload The DID Update Payload to generate the signal for.
+   * @returns {BeaconSignal} The generated signal.
+   * @throws {Btcr2Error} if the signal is invalid.
+   */
+  public generateSignal(didUpdatePayload: string): BeaconSignal {
+    throw new Btcr2Error('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {didUpdatePayload});
+  }
+
+  /**
+   * Implements {@link https://dcdpr.github.io/did-btcr2/#establish-beacon | 5.3.1 Establish Beacon}.
+   *
+   * The Establish Beacon algorithm is essentially the same as for the CIDAggregate Beacon in Establish CIDAggregate
+   * Beacon. A cohort of DID controllers need to coordinate to produce a Bitcoin address that will act as the Beacon.
+   * It is RECOMMENDED this is an n-of-n P2TR address, with n being the set of DID controllers in the cohort. Once the
+   * address has been created, and all parties in the cohort acknowledge their intention to participate in that Beacon,
+   * each DID controller SHOULD add the Beacon as a service to their DID document.
+   *
+   * Additionally, the SMTAggregate Beacon cohort participants MUST register the did:btcr2 identifiers they intend use
+   * this Beacon with. This is so the Beacon coordinator can generate the necessary proofs of both inclusion and
+   * non-inclusion for each DID.
+   *
+   * Static, convenience method for establishing a Beacon object.
+   *
+   * @param {string} id The Beacon ID.
+   * @param {string} type The Beacon type.
+   * @param {DidServiceEndpoint} serviceEndpoint The service endpoint.
+   * @returns {Beacon} The Beacon.
+   */
+  public static establish(id: string, type: string, serviceEndpoint: DidServiceEndpoint): SMTAggregateBeacon {
+    return new SMTAggregateBeacon({ id, type, serviceEndpoint });
+  }
+
+  /**
+   *
+   * Implements {@link https://dcdpr.github.io/did-btcr2/#broadcast-smtaggregate-beacon-signal | 5.3.2 Broadcast SMTAggregate Beacon Signal}.
+   *
+   * See {@link Beacon.broadcastSignal | Beacon Interface Method broadcastSignal} for more information.
+   *
+   * To publish a DID Update Payload, the DID controller MUST get a hash of the DID Update Payload included at the leaf
+   * of the Sparse Merkle Tree (SMT) identified by their did:btcr2 identifier and receive an inclusion proof for this
+   * data. If a member of the Beacon cohort does not wish to announce an update in a Beacon Signal, they MUST receive
+   * and verify a proof of non-inclusion for their DID. Upon verifying the non-inclusion proof against the SMT root
+   * contained in the Beacon Signal, they SHOULD accept and authorize the signal following the MuSig2 protocol. Once all
+   * members of the cohort have authorized the signal, it can be broadcast as a transaction to the Bitcoin network. DID
+   * controllers are responsible for persisting their DID updates and proofs, these will need to be provided through a
+   * Sidecar mechanism during a resolution process.
+   *
+   * @param {DidUpdatePayload} didUpdatePayload The DID Update Payload to broadcast.
+   * @returns {Promise<SignalMetadata>} The signal metadata.
+   * @throws {Btcr2Error} if the signal is invalid.
+   */
+  public broadcastSignal(didUpdatePayload: DidUpdatePayload): Promise<SignalsMetadata> {
+    throw new Btcr2Error('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, didUpdatePayload);
+  }
+
+
+  /**
+   * Implements {@link https://dcdpr.github.io/did-btcr2/#process-smtaggregate-beacon-signal | 5.3.3 Process SMTAggregate Beacon Signal}.
+   *
+   * See {@link Beacon.processSignal | Beacon Interface Method processSignal} for more information.
+   *
+   * A Beacon Signal from a SMTAggregate Beacon is a Bitcoin transaction with the first transaction output of the format
+   * [OP_RETURN, OP_PUSH32, <32bytes>]. The 32 bytes of data contained within this transaction output represent the root
+   * of a Sparse Merkle Tree (SMT). This SMT aggregates a set of hashes of DID Update payloads. In order to process
+   * these Beacon Signals, the resolver MUST have been passed Sidecar data for this signal containing either the DID
+   * Update payload object and a SMT proof that the hash of this object is in the SMT at the leaf indexed by the
+   * did:btc1identifier being resolved. Or theSidecar data:: MUST contain a proof that the leaf indexed by the
+   * did:btc1identifier is empty, thereby proving that theSMT:: does not contain an update for their identifier.
+   *
+   * The Process SMTAggregate Beacon Signal is called by the Process Beacon Signals algorithm as part of the Read
+   * operation. It takes as inputs a did:btcr2 identifier, btc1Identifier, a Beacon Signal, tx, and a optional object,
+   * signalSidecarData, containing any sidecar data provided to the resolver for the Beacon Signal identified by the
+   * Bitcoin transaction identifier.
+   *
+   * It returns the DID Update payload announced by the Beacon Signal for the did:btcr2 identifier being resolved or
+   * throws an error.
+   *
+   * @param {RawTransactionV2} signal The raw transaction signal.
+   * @param {SignalsMetadata} signalsMetadata The signals metadata.
+   * @returns {Promise<DidUpdatePayload | undefined>} The updated DID document.
+   * @throws {Btcr2Error} if the signal is invalid.
+   */
+  public processSignal(signal: RawTransactionV2, signalsMetadata: SignalsMetadata): Promise<DidUpdatePayload | undefined> {
+    throw new Btcr2Error('Method not implemented.', `METHOD_NOT_IMPLEMENTED`, {signal, signalsMetadata});
+  }
+}

package/src/btcr2/crud/create.ts

@@ -0,0 +1,160 @@
+import { Btcr2IdentifierTypes, KeyBytes, PatchOperation } from '@did-btcr2/common';
+import { PublicKey } from '@did-btcr2/keypair';
+import { DidCreateOptions as IDidCreateOptions } from '@web5/dids';
+import { getNetwork } from '../../bitcoin/network.js';
+import { BeaconUtils } from '../../utils/beacons.js';
+import { Btc1DidDocument, IntermediateDidDocument } from '../../utils/did-document.js';
+import { Btc1Identifier } from '../../utils/identifier.js';
+import { Btc1KeyManager } from '../key-manager/index.js';
+
+export type Btc1CreateParams = Btc1CreateKeyParams | Btc1CreateExternalParams;
+export interface CreateIdentifierParams {
+  genesisBytes: Uint8Array;
+  newtork?: string;
+  version?: string;
+}
+export type Btc1CreateResponse = {
+  did: string;
+  initialDocument: Btc1DidDocument;
+};
+export interface Btc1UpdateConstructParams {
+    identifier: string;
+    sourceDocument: Btc1DidDocument;
+    sourceVersionId: number;
+    patch: PatchOperation[];
+}
+export interface Btc1UpdateParams extends Btc1UpdateConstructParams {
+    verificationMethodId: string;
+    beaconIds: string[];
+}
+export interface DidCreateOptions extends IDidCreateOptions<Btc1KeyManager> {
+  /** DID BTCR2 Version Number */
+  version?: number;
+  /** Bitcoin Network */
+  network?: string;
+}
+export type Btc1CreateKeyParams = {
+  idType: 'KEY';
+  pubKeyBytes: KeyBytes;
+  options?: DidCreateOptions;
+};
+export type Btc1CreateExternalParams = {
+  idType: 'EXTERNAL';
+  intermediateDocument: IntermediateDidDocument;
+  options?: DidCreateOptions;
+};
+
+/**
+ * Implements section {@link https://dcdpr.github.io/did-btcr2/#create | 4.1 Create}.
+ *
+ * A did:btcr2 identifier and associated DID document can either be created deterministically from a cryptographic seed,
+ * or it can be created from an arbitrary genesis intermediate DID document representation. In both cases, DID creation
+ * can be undertaken in an offline manner, i.e., the DID controller does not need to interact with the Bitcoin network
+ * to create their DID.
+ *
+ * @class Btc1Create
+ * @type {Btc1Create}
+ */
+export class Btc1Create {
+  /**
+   * Implements {@link https://dcdpr.github.io/did-btcr2/#deterministic-key-based-creation | 4.1.1 Deterministic Key-Based Creation}.
+   *
+   * For deterministic key-based creation, the did:btcr2 identifier encodes a secp256k1 public key. The key is then used
+   * to deterministically generate the initial DID document.
+   *
+   * @param {Btc1CreateKeyParams} params See {@link Btc1CreateKeyParams} for details.
+   * @param {number} params.version did-btcr2 identifier version.
+   * @param {string} params.network did-btcr2 bitcoin network.
+   * @param {KeyBytes} params.pubKeyBytes public key bytes for id creation.
+   * @returns {Btc1CreateResponse} A response object of type {@link Btc1CreateResponse}.
+   * @throws {DidError} if the public key is missing or invalid.
+   */
+  public static deterministic({ pubKeyBytes, options }: {
+    pubKeyBytes: KeyBytes;
+    options: DidCreateOptions;
+  }): Btc1CreateResponse {
+    // Deconstruct options and set the default values
+    const { version = 1, network = 'bitcoin' } = options;
+
+    // Set idType to "KEY"
+    const idType = Btcr2IdentifierTypes.KEY;
+
+    // Call the the did:btcr2 Identifier Encoding algorithm
+    const identifier = Btc1Identifier.encode({ version, network, idType, genesisBytes: pubKeyBytes });
+
+    // Instantiate PublicKey object and get the multibase formatted publicKey
+    const { compressed: publicKey, multibase: publicKeyMultibase } = new PublicKey(pubKeyBytes);
+
+    // Generate the service field for the DID Document
+    const service = BeaconUtils.generateBeaconServices({
+      identifier,
+      publicKey,
+      network : getNetwork(network),
+      type    : 'SingletonBeacon',
+    });
+
+    // Create initialDocument ensuring conformant to spec as Btc1DidDocument
+    const initialDocument = new Btc1DidDocument({
+      id                 : identifier,
+      controller         : [identifier],
+      verificationMethod : [{
+        id                 : `${identifier}#initialKey`,
+        type               : 'Multikey',
+        controller         : identifier,
+        publicKeyMultibase : publicKeyMultibase.address,
+      }],
+      service,
+    });
+
+    // Return did & initialDocument
+    return { did: identifier, initialDocument };
+  }
+
+  /**
+   * Implements {@link https://dcdpr.github.io/did-btcr2/#external-initial-document-creation | 4.1.2 External Initial Document Creation}.
+   *
+   * Creates a did:btcr2 identifier from some initiating arbitrary DID document. This allows for more complex
+   * initial DID documents, including the ability to include Service Endpoints and Beacons that support aggregation.
+   * Inputs include `intermediateDocument`, optional version and network returning initialDidDocument. The
+   * intermediateDocument should be a valid DID document except all places where the DID document requires the use of
+   * the identifier (e.g. the id field). These fields should use placeholder value
+   * `did:btcr2:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`. The intermediateDocument should include at
+   * least one verificationMethod and service of the type SingletonBeacon.
+   *
+   * @param {Btc1CreateExternalParams} params See {@link Btc1CreateExternalParams} for details.
+   * @param {number} params.version Identifier version.
+   * @param {string} params.network Identifier network name.
+   * @param {string} params.documentBytes Intermediate DID Document bytes.
+   * @returns {Btc1CreateResponse} A Promise resolving to {@link Btc1CreateResponses}.
+   * @throws {DidError} if the verificationMethod or service objects are missing required properties
+   */
+  public static async external({ intermediateDocument, options }: {
+    intermediateDocument: IntermediateDidDocument;
+    options: DidCreateOptions;
+  }): Promise<Btc1CreateResponse> {
+    // 1. Set idType to "EXTERNAL"
+    const idType = Btcr2IdentifierTypes.EXTERNAL;
+
+    // 2. Set version to 1
+    // 3. Set network to the desired network.
+    const { version = 1, network = 'bitcoin' } = options;
+
+    // Validate intermediateDocument
+    intermediateDocument.validateIntermediate();
+
+    // 4. Set genesisBytes to the result of passing intermediateDocument into the JSON Canonicalization and Hash
+    //    algorithm.
+    const genesisBytes = await JSON.canonicalization.canonicalhash(intermediateDocument);
+
+    // 5. Pass idType, version, network, and genesisBytes to the did:btcr2 Identifier Encoding algorithm, retrieving id.
+    // 6. Set did to id
+    const did = Btc1Identifier.encode({ idType, genesisBytes, version, network });
+
+    // 7. Set initialDocument to a copy of the intermediateDocument.
+    // 8. Replace all did:btcr2:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx values in the initialDocument with the did.
+    const initialDocument = intermediateDocument.toBtc1DidDocument(did);
+
+    // Return DID & DID Document.
+    return { did, initialDocument };
+  }
+}

package/src/btcr2/crud/deactivate.ts

@@ -0,0 +1,13 @@
+import { DidBtc1 } from '../../did-btcr2.js';
+
+/**
+ * Implements {@link https://dcdpr.github.io/did-btcr2/#deactivate | 4.4 Deactivate}
+ * To deactivate a did:btcr2, the DID controller MUST add the property deactivated with the value true on the DID
+ * document. To do this, the DID controller constructs a valid DID Update Payload with a JSON patch that adds this
+ * property and announces the payload through a Beacon in their current DID document following the algorithm in Update.
+ * Once a did:btcr2 has been deactivated this state is considered permanent and resolution MUST terminate.
+ * @class Btc1Deactivate
+ * @type {Btc1Deactivate}
+ * @extends {DidBtc1}
+ */
+export class Btc1Deactivate extends DidBtc1 {}