@did-btcr2/method 0.13.1

package/src/btcr2/key-manager/interface.ts

@@ -0,0 +1,129 @@
+import { HashBytes, Hex, SignatureBytes } from '@did-btcr2/common';
+import { Multikey, SchnorrMultikey } from '@did-btcr2/cryptosuite';
+import { SchnorrKeyPair, PublicKey } from '@did-btcr2/keypair';
+import { KeyValueStore } from '@web5/common';
+
+export type Btc1KeyManagerOptions = {
+  importKey?: boolean;
+  active?: boolean
+};
+
+/** Alias type for Btc1KeyManager keyUri */
+export type KeyIdentifier = string;
+
+/** Params for initializing a Btc1KeyManager class instance. */
+export type KeyManagerParams = {
+  /**
+   * An optional property to specify a custom `KeyValueStore` instance for key management. If not
+   * provided, {@link Btc1KeyManager | `Btc1KeyManager`} uses a default `MemoryStore` instance.
+   * This store is responsible for managing cryptographic keys, allowing them to be retrieved,
+   * stored, and managed during cryptographic operations.
+   * @type {KeyValueStore<KeyIdentifier, KeyPair>}
+   */
+  store?: KeyValueStore<KeyIdentifier, SchnorrMultikey>;
+
+  /**
+   * An optional property to specify a key URI for the key manager. If not provided, the key manager
+   * will generate a key URI based on the public key of the key pair.
+   * @type {KeyIdentifier}
+   */
+  keyUri?: KeyIdentifier;
+
+  /**
+   * An optional property to specify the DID contoller id.
+   * @type {string}
+   */
+  id?: string;
+
+  /**
+   * An optional property to specify the DID controller.\
+   * @type {string}
+   */
+  controller?: string;
+
+  /**
+   * An optional property to pass in an initial key pair
+   * @type {SchnorrKeyPair}
+   */
+  keys?: SchnorrKeyPair;
+};
+
+export type GenerateKeyParams = {
+  id: string;
+  controller: string;
+  options: Btc1KeyManagerOptions
+};
+
+/**
+ * The interface for the Btc1KeyManager class.
+ * @interface KeyManager
+ * @type {KeyManager}
+ */
+export interface KeyManager {
+    /**
+     * The URI of the active key.
+     * @type {KeyIdentifier}
+     */
+    activeKeyUri?: KeyIdentifier;
+
+    /**
+     * Exports the full key pair from the key store.
+     * @param {KeyIdentifier} keyUri The URI of the key to export.
+     * @returns {Promise<Multikey | undefined>} The key pair associated with the key URI.
+     * @throws {Btc1KeyManagerError} If the key is not found in the key store.
+     */
+    exportKey(keyUri?: KeyIdentifier): Promise<Multikey | undefined>;
+
+    /**
+     * Gets the public key of a key pair.
+     * @param {KeyIdentifier} keyUri The URI of the key to get the public key for.
+     * @returns {Promise<PublicKey>} The public key of the key pair.
+     */
+    getPublicKey(keyUri: KeyIdentifier): Promise<PublicKey>;
+
+    /**
+     * Imports a key pair into the key store.
+     * @param {SchnorrKeyPair} keyPair The key pair to import.
+     * @param {string} keyUri The full DID controller + fragment identifier (e.g. 'did:btcr2:xyz#key-1').
+     * @param {Btc1KeyManagerOptions} options The options for importing the key pair.
+     * @param {boolean} options.active Whether to set the imported key as active.
+     * @returns {Promise<KeyIdentifier>} A promise that resolves to the key identifier of the imported key.
+     */
+    importKey(keyPair: SchnorrKeyPair, keyUri: string, options: Btc1KeyManagerOptions): Promise<KeyIdentifier>;
+}
+
+export interface CryptoSigner {
+  /**
+   * Signs a message with a key pair.
+   * @param {Hex} data The data to sign.
+   * @param {?KeyIdentifier} keyUri The URI of the key to sign the data with.
+   * @returns {Promise<SignatureBytes>} The signature of the input data.
+   */
+  sign(data: Hex, keyUri?: KeyIdentifier): Promise<SignatureBytes>;
+
+  /**
+   * Verifies if a signature was produced by a key pair.
+   * @param {SignatureBytes} signature The signature to verify.
+   * @param {Hex} data The data that was signed.
+   * @param {?KeyIdentifier} keyUri The URI of the key to use for verification.
+   * @returns {Promise<boolean>} A promise that resolves if the signature is valid, and rejects otherwise.
+   */
+  verify(signature: SignatureBytes, data: Hex, keyUri?: KeyIdentifier): Promise<boolean>;
+
+  /**
+   * Returns the sha256 hash of the input data.
+   * @param {Uint8Array} data The data to hash.
+   * @returns {HashBytes} The sha256 hash of the input data.
+   */
+  digest(data: Uint8Array): HashBytes;
+}
+
+export interface BitcoinSigner {
+  /**
+   * Signs a Bitcoin transaction with a key pair.
+   * @param txHex The hex-encoded transaction to sign.
+   * @param keyUri The URI of the key to sign the transaction with.
+   * @returns {Promise<Hex>} A promise that resolves to the hex-encoded signed transaction.
+   */
+  signTransaction(txHex: Hex, keyUri?: KeyIdentifier): Promise<Hex>;
+}

package/src/canonicalize.d.ts

@@ -0,0 +1,6 @@
+// canonicalize.d.ts
+declare module 'canonicalize' {
+    const canonicalize: any;
+    export default canonicalize;
+  }
+  

package/src/did-btcr2.ts

@@ -0,0 +1,288 @@
+import {
+  Btcr2Error,
+  Btcr2IdentifierTypes,
+  INVALID_DID,
+  INVALID_DID_DOCUMENT,
+  METHOD_NOT_SUPPORTED,
+  PatchOperation,
+  W3C_DID_RESOLUTION_V1
+} from '@did-btcr2/common';
+import type {
+  DidResolutionResult,
+  DidVerificationMethod
+} from '@web5/dids';
+import {
+  Did,
+  DidError,
+  DidErrorCode,
+  DidMethod,
+  EMPTY_DID_RESOLUTION_RESULT
+} from '@web5/dids';
+import { initEccLib } from 'bitcoinjs-lib';
+import * as tinysecp from 'tiny-secp256k1';
+import { Btc1Create, Btc1CreateParams, Btc1CreateResponse } from './btcr2/crud/create.js';
+import { Btc1Read } from './btcr2/crud/read.js';
+import { Btc1Update } from './btcr2/crud/update.js';
+import { DidResolutionOptions } from './interfaces/crud.js';
+import { Btc1Appendix } from './utils/appendix.js';
+import { Btc1DidDocument, Btc1VerificationMethod } from './utils/did-document.js';
+import { Btc1Identifier } from './utils/identifier.js';
+
+/** Initialize tiny secp256k1 */
+initEccLib(tinysecp);
+
+/**
+ * Implements {@link https://dcdpr.github.io/did-btcr2 | did:btcr2 DID Method Specification}.
+ * did:btcr2 is a censorship resistant DID Method using the Bitcoin blockchain as a Verifiable Data Registry to announce
+ * changes to the DID document. It improves on prior work by allowing: zero-cost off-chain DID creation; aggregated
+ * updates for scalable on-chain update costs; long-term identifiers that can support frequent updates; private
+ * communication of the DID document; private DID resolution; and non-repudiation appropriate for serious contracts.
+ *
+ * @class DidBtc1
+ * @type {DidBtc1}
+ *
+ */
+export class DidBtc1 implements DidMethod {
+  /** @type {string} Name of the DID method, as defined in the DID BTCR2 specification */
+  public static methodName: string = 'btcr2';
+
+  /**
+   * Entry point for section {@link https://dcdpr.github.io/did-btcr2/#create | 4.1 Create}.
+   * See {@link Btc1Create} for implementation details.
+   *
+   * 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.
+   * @param {Btc1CreateParams} params See {@link Btc1CreateParams} for details.
+   * @param {IdType} params.idType Type of identifier to create (key or external).
+   * @param {KeyBytes} params.pubKeyBytes Public key byte array used to create a btcr2 "key" identifier.
+   * @param {IntermediateDocument} params.intermediateDocument DID Document used to create a btcr2 "external" identifier.
+   * @param {DidCreateOptions} params.options See {@link DidCreateOptions} for create options.
+   * @param {number} params.options.version Version number of the btcr2 method.
+   * @param {string} params.options.network Bitcoin network name (mainnet, testnet, signet, regtest).
+   * @returns {Promise<CreateResponse>} Promise resolving to a CreateResponse object.
+   * @throws {DidBtc1Error} if any of the checks fail
+   */
+  public static async create(params: Btc1CreateParams): Promise<Btc1CreateResponse> {
+    // Deconstruct the idType and options from the params
+    const { idType, options = {} } = params;
+
+    // If idType is key, call Btc1Create.deterministic
+    if(idType === Btcr2IdentifierTypes.KEY) {
+      // Deconstruct the pubKeyBytes from the params
+      const { pubKeyBytes } = params;
+
+      // Return call to Btc1Create.deterministic
+      return Btc1Create.deterministic({ pubKeyBytes, options });
+    }
+
+    // If idType is external, call Btc1Create.external
+    if(idType === Btcr2IdentifierTypes.EXTERNAL) {
+      // Deconstruct the intermediateDocument from the params
+      const { intermediateDocument } = params;
+
+      // Return call to Btc1Create.external
+      return await Btc1Create.external({ intermediateDocument, options });
+    }
+
+    // Throw error if idType is not key or external
+    throw new Btcr2Error('Invalid idType: expected "KEY" or "EXTERNAL"', INVALID_DID, params);
+  }
+
+  /**
+   * Entry point for section {@link https://dcdpr.github.io/did-btcr2/#read | 7.2 Read}.
+   * See {@link Btc1Read} for implementation details.
+   *
+   * The Read operation is an algorithm consisting of a series of subroutine algorithms executed by a resolver after a
+   * resolution request identifying a specific did:btcr2 identifier is received from a client at Resolution Time. The
+   * request MUST always contain the resolutionOptions object containing additional information to be used in resolution.
+   * This object MAY be empty. See the DID Resolution specification for further details about the DID Resolution Options
+   * object. The resolver then attempts to resolve the DID document of the identifier at a specific Target Time. The
+   * Target Time is either provided in resolutionOptions or is set to the Resolution Time of the request.
+   *
+   * @param {string} identifier a valid did:btcr2 identifier to be resolved
+   * @param {DidResolutionOptions} [resolutionsOptions] see {@link https://www.w3.org/TR/did-1.0/#did-resolution-options | DidResolutionOptions}
+   * @param {number} options.versionId the version of the identifier and/or DID document
+   * @param {number} options.versionTime a timestamp used during resolution as a bound for when to stop resolving
+   * @param {Btc1DidDocument} options.sidecarData data necessary for resolving a DID
+   * @param {string} options.network Bitcoin network name (mainnet, testnet, signet, regtest).
+   * @returns {DidResolutionResult} Promise resolving to a DID Resolution Result containing the `targetDocument`
+   * @throws {Error} if the resolution fails for any reason
+   * @throws {DidError} InvalidDid if the identifier is invalid
+   * @example
+   * ```ts
+   * const resolution = await DidBtc1.resolve('did:btcr2:k1q0dygyp3gz969tp46dychzy4q78c2k3js68kvyr0shanzg67jnuez2cfplh')
+   * ```
+   */
+  public static async resolve(identifier: string, resolutionsOptions: DidResolutionOptions = {}): Promise<DidResolutionResult> {
+    try {
+      // 1. Pass identifier to the did:btcr2 Identifier Decoding algorithm, retrieving idType, version, network, and genesisBytes.
+      // 2. Set identifierComponents to a map of idType, version, network, and genesisBytes.
+      const identifierComponents = Btc1Identifier.decode(identifier);
+
+      // 3. Set initialDocument to the result of running the algorithm in Resolve Initial Document passing in the
+      //    identifier, identifierComponents and resolutionOptions.
+      const initialDocument = await Btc1Read.initialDocument({ identifier, identifierComponents, resolutionsOptions });
+
+      // 4. Set targetDocument to the result of running the algorithm in Resolve Target Document passing in
+      //    initialDocument and resolutionOptions.
+      const targetDocument = await Btc1Read.targetDocument({ initialDocument, resolutionsOptions });
+
+      // 5. Return targetDocument.
+      const didResolutionResult: DidResolutionResult = {
+        '@context'            : W3C_DID_RESOLUTION_V1,
+        didResolutionMetadata : { contentType: 'application/ld+json' },
+        didDocumentMetadata   : { created: new Date().getUTCDateTime() },
+        didDocument           : targetDocument,
+      };
+
+      // Return didResolutionResult;
+      return didResolutionResult;
+    } catch (error: any) {
+      console.error(error);
+      // Rethrow any unexpected errors that are not a `DidError`.
+      if (!(error instanceof DidError)) throw new Error(error);
+
+      // Return a DID Resolution Result with the appropriate error code.
+      return {
+        ...EMPTY_DID_RESOLUTION_RESULT,
+        didResolutionMetadata : {
+          error : error.code,
+          ...error.message && { errorMessage: error.message }
+        }
+      };
+    }
+  }
+
+  /**
+   * Entry point for section {@link https://dcdpr.github.io/did-btcr2/#update | 4.3 Update}.
+   * See {@link Btc1Update} for implementation details.
+   *
+   * 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.
+   *
+   * The Update algorithm takes as inputs a btc1Identifier, sourceDocument, sourceVersionId, documentPatch, a
+   * verificationMethodId and an array of beaconIds. The sourceDocument is the DID document being updated. The
+   * documentPatch is a JSON Patch object containing a set of transformations to be applied to the sourceDocument.
+   * The result of these transformations MUST produce a DID document conformant to the DID Core specification. The
+   * verificationMethodId is an identifier for a verificationMethod within the sourceDocument. The verificationMethod
+   * identified MUST be a BIP340 Multikey. The beaconIds MUST identify service endpoints with one of the three Beacon
+   * Types SingletonBeacon, CIDAggregateBeacon, and SMTAggregateBeacon.
+   *
+   * @param {Btc1UpdateParams} params Required parameters for the update operation.
+   * @param {string} params.identifier The btcr2 identifier to be updated.
+   * @param {Btc1DidDocument} params.sourceDocument The DID document being updated.
+   * @param {string} params.sourceVersionId The versionId of the source document.
+   * @param {Btc1DocumentPatch} params.documentPatch The JSON patch to be applied to the source document.
+   * @param {string} params.verificationMethodId The verificationMethod ID to sign the update
+   * @param {string[]} params.beaconIds The beacon IDs to announce the update
+   * @returns {Promise<void>} Promise resolving to void
+   * @throws {Btcr2Error} if the verificationMethod type is not `Multikey` or the publicKeyMultibase header is not `zQ3s`
+   */
+  public static async update(params: {
+    identifier: string;
+    sourceDocument: Btc1DidDocument;
+    sourceVersionId: number;
+    patch: PatchOperation[];
+    verificationMethodId: string;
+    beaconIds: string[];
+  }): Promise<any> {
+    // Deconstruct the params
+    const {
+      identifier,
+      sourceDocument,
+      sourceVersionId,
+      patch,
+      verificationMethodId: methodId,
+      beaconIds,
+    } = params;
+
+    // 1. Set unsignedUpdate to the result of passing btc1Identifier, sourceDocument,
+    //    sourceVersionId, and documentPatch into the Construct DID Update
+    //    Payload algorithm.
+    const didUpdatePayload = await Btc1Update.construct({
+      identifier,
+      sourceDocument,
+      sourceVersionId,
+      patch,
+    });
+
+    // 2. Set verificationMethod to the result of retrieving the verificationMethod
+    //    from sourceDocument using the verificationMethodId.
+    const verificationMethod = this.getSigningMethod({ didDocument: sourceDocument, methodId, });
+
+    // Validate the verificationMethod exists in the sourceDocument
+    if (!verificationMethod) {
+      throw new Btcr2Error('Verification method not found in did document', INVALID_DID_DOCUMENT, sourceDocument);
+    }
+
+    // 3. Validate the verificationMethod is a BIP340 Multikey:
+    //    3.1 verificationMethod.type == Multikey
+    if (verificationMethod.type !== 'Multikey') {
+      throw new Btcr2Error('Invalid type: must be type "Multikey"', INVALID_DID_DOCUMENT, verificationMethod);
+    }
+
+    //    3.2 verificationMethod.publicKeyMultibase[4] == zQ3s
+    const mbasePrefix = verificationMethod.publicKeyMultibase?.slice(0, 4);
+    if (mbasePrefix !== 'zQ3s') {
+      throw new Btcr2Error(`Invalid publicKeyMultibase prefix ${mbasePrefix}`, INVALID_DID_DOCUMENT, verificationMethod);
+    }
+
+    // 4. Set didUpdateInvocation to the result of passing btc1Identifier, unsignedUpdate as didUpdatePayload, and
+    //    verificationMethod to the Invoke DID Update Payload algorithm.
+    const didUpdateInvocation = await Btc1Update.invoke({ identifier, verificationMethod, didUpdatePayload, });
+
+    // 5. Set signalsMetadata to the result of passing btc1Identifier, sourceDocument, beaconIds and didUpdateInvocation
+    //    to the Announce DID Update algorithm.
+    const signalsMetadata = await Btc1Update.announce({ sourceDocument, beaconIds, didUpdateInvocation, });
+
+    // 6. Return signalsMetadata. It is up to implementations to ensure that the signalsMetadata is persisted.
+    return signalsMetadata;
+    // TODO: Should we be applying the patch, producing a target did document and returning it?
+  }
+
+  /**
+   * Given the W3C DID Document of a `did:btcr2` identifier, return the signing verification method that will be used
+   * for signing messages and credentials. If given, the `methodId` parameter is used to select the
+   * verification method. If not given, the Identity Key's verification method with an ID fragment
+   * of '#initialKey' is used.
+   *
+   * @param {{ didDocument: Btc1DidDocument; methodId?: string; }} params Parameters for the `getSigningMethod` method.
+   * @param {DidDocument} params.didDocument DID Document to get the verification method from.
+   * @param {string} params.methodId Optional ID of the verification method to use for signing.
+   * @returns {Btc1VerificationMethod} Promise resolving to the {@link Btc1VerificationMethod} object used for signing.
+   * @throws {DidError} if the parsed did method does not match `btcr2` or signing method could not be determined.
+   */
+  public static getSigningMethod({ didDocument, methodId }: {
+    didDocument: Btc1DidDocument;
+    methodId?: string;
+  }): Btc1VerificationMethod {
+    // Set the default methodId to the first assertionMethod if not given
+    methodId ??= '#initialKey';
+
+    // Verify the DID method is supported.
+    const parsedDid = Did.parse(didDocument.id);
+    if (parsedDid && parsedDid.method !== this.methodName) {
+      throw new Btcr2Error(`Method not supported: ${parsedDid.method}`, METHOD_NOT_SUPPORTED, { identifier: didDocument.id });
+    }
+
+    // Attempt to find a verification method that matches the given method ID, or if not given,
+    // find the first verification method intended for signing claims.
+    const verificationMethod = didDocument.verificationMethod?.find(
+      (vm: DidVerificationMethod) => Btc1Appendix.extractDidFragment(vm.id) === (Btc1Appendix.extractDidFragment(methodId)
+        ?? Btc1Appendix.extractDidFragment(didDocument.assertionMethod?.[0]))
+    );
+
+    // If no verification method is found, throw an error
+    if (!(verificationMethod && verificationMethod.publicKeyMultibase)) {
+      throw new DidError(
+        DidErrorCode.InternalError,
+        'A verification method intended for signing could not be determined from the DID Document'
+      );
+    }
+    return verificationMethod as Btc1VerificationMethod;
+  }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+
+export * from './bitcoin/constants.js';
+export * from './bitcoin/interface.js';
+export * from './bitcoin/network.js';
+export * from './bitcoin/rpc-client.js';
+
+export * from './btcr2/beacon/cid-aggregate.js';
+export * from './btcr2/beacon/factory.js';
+export * from './btcr2/beacon/singleton.js';
+export * from './btcr2/beacon/smt-aggregate.js';
+
+export * from './btcr2/crud/create.js';
+export * from './btcr2/crud/deactivate.js';
+export * from './btcr2/crud/read.js';
+export * from './btcr2/crud/update.js';
+
+export * from './btcr2/key-manager/index.js';
+export * from './btcr2/key-manager/interface.js';
+
+export * from './interfaces/beacon.js';
+export * from './interfaces/crud.js';
+export * from './interfaces/ibeacon.js';
+
+export * from './types/bitcoin.js';
+export * from './types/crud.js';
+
+export * from './utils/appendix.js';
+export * from './utils/beacons.js';
+export * from './utils/did-document-builder.js';
+export * from './utils/did-document.js';
+export * from './utils/general.js';
+export * from './utils/identifier.js';
+
+export * from './did-btcr2.js';

package/src/interfaces/beacon.ts

@@ -0,0 +1,68 @@
+import { DidUpdatePayload } from '@did-btcr2/common';
+import { DidServiceEndpoint } from '@web5/dids';
+import { RawTransactionRest } from '../bitcoin/rest-client.js';
+import { RawTransactionV2 } from '../types/bitcoin.js';
+import { SidecarData, SignalsMetadata } from '../types/crud.js';
+import { BeaconService, BeaconSignal, IBeacon } from './ibeacon.js';
+
+/**
+ * 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

@@ -0,0 +1,36 @@
+import { BitcoinNetworkNames, UnixTimestamp } from '@did-btcr2/common';
+import { DidResolutionOptions as IDidResolutionOptions } from '@web5/dids';
+import BitcoinRpc from '../bitcoin/rpc-client.js';
+import { SidecarData } from '../types/crud.js';
+import { Btc1DidDocument } from '../utils/did-document.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 {?BitcoinRpc} rpc BitcoinRpc client connection
+ * @param {?SidecarData} sidecarData The sidecar data for resolving the DID Document
+ */
+export interface DidResolutionOptions extends IDidResolutionOptions {
+  versionId?: number
+  versionTime?: UnixTimestamp;
+  sidecarData?: SidecarData;
+  network?: BitcoinNetworkNames;
+  rpc?: BitcoinRpc;
+}
+export interface Btc1RootCapability {
+    '@context': string;
+    id: string;
+    controller: string;
+    invocationTarget: string;
+}
+export interface ReadBlockchainParams {
+  contemporaryDidDocument: Btc1DidDocument;
+  contemporaryBlockHeight: number | 1;
+  currentVersionId: number | 1;
+  targetVersionId?: number;
+  targetBlockHeight: number;
+  updateHashHistory: string[];
+  sidecarData?: SidecarData;
+  options?: DidResolutionOptions;
+}

package/src/interfaces/ibeacon.ts

@@ -0,0 +1,76 @@
+import { DidUpdatePayload, UnixTimestamp } from '@did-btcr2/common';
+import { DidServiceEndpoint, DidService as IDidService } from '@web5/dids';
+import { RawTransactionV2 } from '../types/bitcoin.js';
+import { SignalsMetadata } from '../types/crud.js';
+import { RawTransactionRest } from '../bitcoin/rest-client.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;
+}