@did-btcr2/method 0.13.1

package/dist/esm/btcr2/crud/read.js

@@ -0,0 +1,686 @@
+import { BitcoinNetworkNames, Btcr2Error, Btcr2IdentifierHrp, Btcr2ReadError, ID_PLACEHOLDER_VALUE, INVALID_DID, INVALID_DID_DOCUMENT, INVALID_DID_UPDATE, LATE_PUBLISHING_ERROR, Logger } from '@did-btcr2/common';
+import { Cryptosuite, DataIntegrityProof, SchnorrMultikey } from '@did-btcr2/cryptosuite';
+import { PublicKey } from '@did-btcr2/keypair';
+import { bytesToHex } from '@noble/hashes/utils';
+import { GENESIS_TX_ID, TXIN_WITNESS_COINBASE } from '../../bitcoin/constants.js';
+import bitcoinNetwork, { Bitcoin } from '../../bitcoin/index.js';
+import { getNetwork } from '../../bitcoin/network.js';
+import { DidBtc1 } from '../../did-btcr2.js';
+import { Btc1Appendix } from '../../utils/appendix.js';
+import { BeaconUtils } from '../../utils/beacons.js';
+import { Btc1DidDocument } from '../../utils/did-document.js';
+import { BeaconFactory } from '../beacon/factory.js';
+;
+;
+;
+/**
+ * Implements {@link https://dcdpr.github.io/did-btcr2/#read | 4.2 Read}.
+ * The read operation is executed by a resolver after a resolution request identifying a specific did:btcr2 identifier is
+ * received from a client at Resolution Time. The request MAY contain a resolutionOptions object containing additional
+ * information to be used in resolution. 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.
+ * To do so it executes the following algorithm:
+ *  1. Let identifierComponents be the result of running the algorithm
+ *     in Parse did:btcr2 identifier, passing in the identifier.
+ *  2. Set initialDocument to the result of running Resolve Initial Document
+ *     passing identifier, identifierComponents and resolutionOptions.
+ *  3. Set targetDocument to the result of running the algorithm in Resolve
+ *     Target Document passing in initialDocument and resolutionOptions.
+ *  4. Return targetDocument.
+ *
+ * @class Btc1Read
+ * @type {Btc1Read}
+ */
+export class Btc1Read {
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#deterministically-generate-initial-did-document | 4.2.2.1 Deterministically Generate Initial DID Document}.
+     *
+     * The Deterministically Generate Initial DID Document algorithm deterministically generates an initial DID
+     * Document from a secp256k1 public key. It takes in a did:btcr2 identifier and a identifierComponents object and
+     * returns an initialDocument.
+     *
+     * @param {Btc1ReadDeterministic} params See {@link Btc1ReadDeterministic} for details.
+     * @param {string} params.identifier The did-btcr2 version.
+     * @param {DidComponents} params.identifierComponents The decoded components of the identifier.
+     * @returns {Btc1DidDocument} The resolved DID Document object.
+     */
+    static deterministic({ identifier, identifierComponents }) {
+        // Deconstruct the components
+        const { network, genesisBytes } = identifierComponents;
+        // Construct a new PublicKey and deconstruct the publicKey and publicKeyMultibase
+        const { compressed: publicKey, multibase: publicKeyMultibase } = new PublicKey(genesisBytes);
+        // Generate the service field for the DID Document
+        const service = BeaconUtils.generateBeaconServices({
+            identifier,
+            publicKey,
+            network: getNetwork(network),
+            type: 'SingletonBeacon',
+        });
+        return new Btc1DidDocument({
+            id: identifier,
+            controller: [identifier],
+            verificationMethod: [{
+                    id: `${identifier}#initialKey`,
+                    type: 'Multikey',
+                    controller: identifier,
+                    publicKeyMultibase: publicKeyMultibase.address
+                }],
+            service
+        });
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#external-resolution | 4.2.2.2 External Resolution}.
+     *
+     * The External Resolution algorithm externally retrieves an intermediateDocumentRepresentation, either by retrieving
+     * it from {@link https://dcdpr.github.io/did-btcr2/#def-content-addressable-storage | Content Addressable Storage (CAS)}
+     * or from the {@link https://dcdpr.github.io/did-btcr2/#def-sidecar-data | Sidecar Data} provided as part of the
+     * resolution request. It takes in a did:btcr2 identifier, a identifierComponents object and a resolutionOptions object.
+     * It returns an initialDocument, which is a conformant DID document validated against the identifier.
+     *
+     * @param {Btc1ReadExternal} params Required params for calling the external method.
+     * @param {string} params.identifier The DID to be resolved.
+     * @param {DidComponents} params.identifierComponents The decoded components of the identifier.
+     * @param {DidResolutionOptions} params.resolutionsOptions The options for resolving the DID Document.
+     * @param {Btc1DidDocument} params.resolutionsOptions.sidecarData The sidecar data for resolving the DID Document.
+     * @param {Btc1DidDocument} params.resolutionsOptions.sidecarData.initialDocument The offline user-provided DID Document
+     * @returns {Btc1DidDocument} The resolved DID Document object
+     */
+    static async external({ identifier, identifierComponents, resolutionsOptions }) {
+        // Deconstruct the options
+        const { initialDocument: document } = resolutionsOptions.sidecarData;
+        // 1. If resolutionOptions.sidecarData.initialDocument is not null, set initialDocument to the result of passing
+        //    identifier, identifierComponents and resolutionOptions.sidecarData.initialDocument into algorithm Sidecar
+        //    Initial Document Validation.
+        // 2. Else set initialDocument to the result of passing identifier and identifierComponents to the CAS Retrieval algorithm.
+        const initialDocument = document
+            ? await this.sidecar({ identifierComponents, initialDocument: document })
+            : await this.cas({ identifier, identifierComponents });
+        // 3. Validate initialDocument is a conformant DID document according to the DID Core 1.1 specification. Else MUST
+        //    raise invalidDidDocument error.
+        Btc1DidDocument.validate(initialDocument);
+        // 4. Return initialDocument.
+        return initialDocument;
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#sidecar-initial-document-validation | 4.2.2.2.1 Sidecar Initial Document Validation}.
+     *
+     * The Sidecar Initial Document Validation algorithm validates an initialDocument against its identifier, by first
+     * constructing the intermediateDocumentRepresentation and verifying the hash of this document matches the bytes
+     * encoded within the identifier. It takes in a did:btcr2 identifier, identifierComponents and a
+     * initialDocument. It returns the initialDocument if validated, otherwise it throws an error.
+     *
+     * @param {Btc1ReadSidecar} params Required params for calling the sidecar method
+     * @param {string} params.identifier The DID to be resolved
+     * @param {DidComponents} params.identifierComponents The components of the DID identifier
+     * @param {Btc1DidDocument} params.initialDocument The initial DID Document provided by the user
+     * @returns {Btc1DidDocument} The resolved DID Document object
+     * @throws {DidError} InvalidDidDocument if genesisBytes !== initialDocument hashBytes
+     */
+    static async sidecar({ identifierComponents, initialDocument }) {
+        // Replace the placeholder did with the identifier throughout the initialDocument.
+        const intermediateDocument = JSON.parse(JSON.stringify(initialDocument).replaceAll(initialDocument.id, ID_PLACEHOLDER_VALUE));
+        // Canonicalize and sha256 hash the intermediateDocument
+        const hashBytes = await JSON.canonicalization.process(intermediateDocument, 'hex');
+        // Compare the genesisBytes to the hashBytes
+        const genesisBytes = bytesToHex(identifierComponents.genesisBytes);
+        // If the genesisBytes do not match the hashBytes, throw an error
+        if (genesisBytes !== hashBytes) {
+            throw new Btcr2Error(`Initial document mismatch: genesisBytes ${genesisBytes} !== hashBytes ${hashBytes}`, INVALID_DID_DOCUMENT, { genesisBytes, hashBytes });
+        }
+        // Return a W3C conformant DID Document
+        return new Btc1DidDocument(initialDocument);
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#cas-retrieval | 4.2.2.2.2 CAS Retrieval}.
+     *
+     * The CAS Retrieval algorithm attempts to retrieve an initialDocument from a Content Addressable Storage (CAS) system
+     * by converting the bytes in the identifier into a Content Identifier (CID). It takes in an identifier and
+     * an identifierComponents object. It returns an initialDocument.
+     *
+     * @param {DidReadCas} params Required params for calling the cas method
+     * @param {string} params.identifier BTCR2 DID used to resolve the DID Document
+     * @param {DidComponents} params.identifierComponents BTCR2 DID components used to resolve the DID Document
+     * @returns {Btc1DidDocument} The resolved DID Document object
+     * @throws {Btcr2Error} if the DID Document content is invalid
+     */
+    static async cas({ identifier, identifierComponents }) {
+        // 1. Set hashBytes to identifierComponents.genesisBytes.
+        const hashBytes = identifierComponents.genesisBytes;
+        // 3. Set intermediateDocumentRepresentation to the result of fetching the cid against a Content Addressable Storage
+        //    (CAS) system such as IPFS.
+        const intermediateDocument = await Btc1Appendix.fetchFromCas(hashBytes);
+        // Validate the intermediateDocument is not null and is parsable JSON
+        if (!intermediateDocument || !JSON.parsable(intermediateDocument)) {
+            throw new Btcr2Error(INVALID_DID_DOCUMENT, 'Invalid DID Document content', { intermediateDocument });
+        }
+        // 5. Replace the placeholder did with the identifier throughout the initialDocument.
+        const initialDocument = JSON.parse(intermediateDocument.replaceAll(ID_PLACEHOLDER_VALUE, identifier));
+        // 6. Return initialDocument.
+        return new Btc1DidDocument(initialDocument);
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#resolve-initial-document | 4.2.2 Resolve Initial Document}.
+     *
+     * This algorithm resolves an initial DID document and validates it against the identifier for a specific did:btcr2.
+     * The algorithm takes in a did:btcr2 identifier, identifier components object, resolutionsOptions object and returns
+     * a valid initialDocument for that identifier.
+     *
+     * @public
+     * @param {ResolveInitialDocument} params See {@link ResolveInitialDocument} for parameter details.
+     * @param {string} params.identifier The DID to be resolved.
+     * @param {DidComponents} params.identifierComponents The decoded components of the identifier.
+     * @param {DidResolutionOptions} params.resolutionsOptions Options for resolving the DID Document. See {@link DidResolutionOptions}.
+     * @returns {Promise<Btc1DidDocument>} The resolved DID Document object.
+     * @throws {DidError} if the DID hrp is invalid, no sidecarData passed and hrp = "x".
+     */
+    static async initialDocument({ identifier, identifierComponents, resolutionsOptions }) {
+        // Deconstruct the hrp from the components
+        const hrp = identifierComponents.hrp;
+        // Validate the hrp is either 'k' or 'x'
+        if (!(hrp in Btcr2IdentifierHrp)) {
+            throw new Btcr2Error(`Invalid DID hrp ${hrp}`, INVALID_DID, { hrp });
+        }
+        //  Make sure options.sidecarData is not null if hrp === x
+        if (hrp === Btcr2IdentifierHrp.x && !resolutionsOptions.sidecarData) {
+            throw new Btcr2Error('External resolution requires sidecar data', INVALID_DID, resolutionsOptions);
+        }
+        return hrp === Btcr2IdentifierHrp.k
+            ? this.deterministic({ identifier, identifierComponents })
+            : await this.external({ identifier, identifierComponents, resolutionsOptions });
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#resolve-target-document | 4.2.3 Resolve Target Document}.
+     *
+     * The Resolve Target Document algorithm resolves a DID document from an initial document by walking the Bitcoin
+     * blockchain to identify Beacon Signals that announce DID Update Payloads applicable to the did:btcr2 identifier being
+     * resolved. It takes as inputs initialDocument, resolutionOptions and network. It returns a valid DID document.
+     *
+     * @public
+     * @param {TargetDocumentParams} params See {@link TargetDocumentParams} for details.
+     * @param {Btc1DidDocument} params.initialDocument The initial DID Document to resolve
+     * @param {ResolutionOptions} params.options See {@link DidResolutionOptions} for details.
+     * @returns {Btc1DidDocument} The resolved DID Document object with a validated single, canonical history
+     */
+    static async targetDocument({ initialDocument, resolutionsOptions }) {
+        // Set the network from the options or default to mainnet
+        const network = resolutionsOptions.network ?? BitcoinNetworkNames.bitcoin;
+        // 1. If resolutionOptions.versionId is not null, set targetVersionId to resolutionOptions.versionId.
+        const targetVersionId = resolutionsOptions.versionId;
+        // 2. Else if resolutionOptions.versionTime is not null, set targetTime to resolutionOptions.versionTime.
+        // 3. Else set targetTime to the UNIX timestamp for now at the moment of execution.
+        const targetTime = resolutionsOptions.versionTime ?? new Date().toUnix();
+        // 4. Set signalsMetadata to resolutionOptions.sidecarData.signalsMetadata.
+        const signalsMetadata = resolutionsOptions.sidecarData.signalsMetadata;
+        // 5. Set currentVersionId to 1
+        const currentVersionId = 1;
+        // 6. If currentVersionId equals targetVersionId return initialDocument.
+        if (currentVersionId === targetVersionId) {
+            return new Btc1DidDocument(initialDocument);
+        }
+        // 10. Set targetDocument to the result of calling the Traverse Bitcoin Blockchain History algorithm
+        // passing in contemporaryDIDDocument, contemporaryBlockheight, currentVersionId, targetVersionId,
+        // targetTime, didDocumentHistory, btc1UpdateHashHistory, signalsMetadata, and network.
+        const targetDocument = this.traverseBlockchainHistory({
+            contemporaryDidDocument: initialDocument,
+            contemporaryBlockHeight: 0,
+            currentVersionId,
+            targetVersionId,
+            targetTime,
+            didDocumentHistory: new Array(),
+            btc1UpdateHashHistory: new Array(),
+            signalsMetadata,
+            network
+        });
+        // 11. Return targetDocument.
+        return targetDocument;
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#traverse-blockchain-history | 4.2.3.2 Traverse Blockchain History}.
+     *
+     * The Traverse Blockchain History algorithm traverses Bitcoin blocks, starting from the block with the
+     * contemporaryBlockheight, to find beaconSignals emitted by Beacons within the contemporaryDidDocument. Each
+     * beaconSignal is processed to retrieve a didUpdatePayload to the DID document. Each update is applied to the
+     * document and duplicates are ignored. If the algorithm reaches the block with the blockheight specified by a
+     * targetBlockheight, the contemporaryDidDocument at that blockheight is returned assuming a single canonical history
+     * of the DID document has been constructed up to that point. It takes in contemporaryDidDocument,
+     * contemporaryBlockHeight, currentVersionId, targetVersionId, targetBlockheight, updateHashHistory, signalsMetadata
+     * and network. It returns the contemporaryDidDocument once either the targetBlockheight or targetVersionId have been
+     * reached.
+     *
+     * @protected
+     * @param {ReadBlockchainParams} params The parameters for the traverseBlockchainHistory operation.
+     * @param {Btc1DidDocument} params.contemporaryDidDocument The DID document for the did:btcr2 identifier being resolved.
+     *    It should be "current" (contemporary) at the blockheight of the contemporaryBlockheight.
+     *    It should be a DID Core conformant DID document.
+     * @param {number} params.contemporaryBlockHeight The Bitcoin blockheight signaling the "contemporary time" of the
+     *    contemporary DID Document that is being resolved and updated using the Traverse Blockchain History algorithm.
+     * @param {number} params.currentVersionId The version of the contemporary DID document starting from 1 and
+     *    incrementing by 1 with each BTCR2 Update applied to the DID document.
+     * @param {number} params.targetVersionId The version of the DID document where resolution will complete.
+     * @param {UnixTimestamp} params.targetTime The timestamp used to target specific historical states of a DID document.
+     *    Only Beacon Signals included in the Bitcoin blockchain before the targetTime are processed.
+     * @param {boolean} params.didDocumentHistory An array of DID documents ordered ascensing by version (1...N).
+     * @param {boolean} params.btc1UpdateHashHistory An array of SHA256 hashes of BTCR2 Updates ordered by version that are
+     *    applied to the DID document in order to construct the contemporaryDIDDocument.
+     * @param {SignalsMetadata} params.signalsMetadata See {@link SignalsMetadata} for details.
+     * @param {BitcoinNetworkNames} params.network The bitcoin network to connect to (mainnet, signet, testnet, regtest).
+     * @returns {Promise<Btc1DidDocument>} The resolved DID Document object with a validated single, canonical history.
+     */
+    static async traverseBlockchainHistory({ contemporaryDidDocument, contemporaryBlockHeight, currentVersionId, targetVersionId, targetTime, didDocumentHistory, btc1UpdateHashHistory, signalsMetadata, network }) {
+        // 1. Set contemporaryHash to the SHA256 hash of the contemporaryDidDocument
+        let contemporaryHash = await JSON.canonicalization.process(contemporaryDidDocument, 'base58');
+        // 2. Find all BTCR2 Beacons in contemporaryDIDDocument.service where service.type equals one of
+        //    SingletonBeacon, CIDAggregateBeacon and SMTAggregateBeacon.
+        // 3. For each beacon in beacons convert the beacon.serviceEndpoint to a Bitcoin address
+        //    following BIP21. Set beacon.address to the Bitcoin address.
+        const beacons = BeaconUtils.toBeaconServiceAddress(BeaconUtils.getBeaconServices(contemporaryDidDocument));
+        // 4. Set nextSignals to the result of calling algorithm Find Next Signals passing in contemporaryBlockheight,
+        //    beacons and network.
+        const nextSignals = await this.findNextSignals({ contemporaryBlockHeight, beacons, network, targetTime });
+        if (!nextSignals || nextSignals.length === 0) {
+            // 5. If nextSignals is null or empty, return contemporaryDidDocument.
+            return new Btc1DidDocument(contemporaryDidDocument);
+        }
+        // 6. If nextSignals[0].blocktime is greater than targetTime, return contemporaryDIDDocument.
+        if (nextSignals[0].blocktime > targetTime) {
+            return new Btc1DidDocument(contemporaryDidDocument);
+        }
+        // 8. Set updates to the result of calling algorithm Process Beacon Signals passing in signals and sidecarData.
+        // 9. Set orderedUpdates to the list of updates ordered by the targetVersionId property.
+        const orderedUpdates = (await Promise.all(nextSignals.map(async (signal) => await this.processBeaconSignal(signal, signalsMetadata)))).sort((a, b) => a.targetVersionId - b.targetVersionId);
+        // 10. For update in orderedUpdates:
+        for (let update of orderedUpdates) {
+            const updateTargetVersionId = update.targetVersionId;
+            // 10.1. If update.targetVersionId is less than or equal to currentVersionId, run Algorithm Confirm Duplicate
+            //      Update passing in update, documentHistory, and contemporaryHash.
+            if (updateTargetVersionId <= currentVersionId) {
+                btc1UpdateHashHistory.push(contemporaryHash);
+                await this.confirmDuplicateUpdate({ update, updateHashHistory: btc1UpdateHashHistory });
+                //  10.2. If update.targetVersionId equals currentVersionId + 1:
+            }
+            else if (updateTargetVersionId === currentVersionId + 1) {
+                // Prepend `z` to the sourceHash if it does not start with it
+                const sourceHash = update.sourceHash.startsWith('z') ? update.sourceHash : `z${update.sourceHash}`;
+                //  10.2.1. Check that update.sourceHash equals contemporaryHash, else MUST raise latePublishing error.
+                if (sourceHash !== contemporaryHash) {
+                    throw new Btcr2ReadError(`Hash mismatch: sourceHash ${sourceHash} !== contemporaryHash ${contemporaryHash}`, LATE_PUBLISHING_ERROR, { sourceHash: sourceHash, contemporaryHash });
+                }
+                // 10.2.2. Set contemporaryDidDocument to the result of calling Apply DID Update algorithm passing in
+                //        contemporaryDidDocument, update.
+                contemporaryDidDocument = await this.applyDidUpdate({ contemporaryDidDocument, update });
+                // 10.2.4 Push contemporaryDIDDocument onto didDocumentHistory.
+                didDocumentHistory.push(contemporaryDidDocument);
+                // 10.2.4. Increment currentVersionId.
+                currentVersionId++;
+                // 10.2.5. Set unsecuredUpdate to a copy of the update object.
+                const unsecuredUpdate = update;
+                // 10.2.6 Remove the proof property from the unsecuredUpdate object.
+                delete unsecuredUpdate.proof;
+                // 10.2.7 Set updateHash to the result of passing unsecuredUpdate into the JSON Canonicalization and Hash algorithm.
+                const updateHash = await JSON.canonicalization.process(update, 'base58');
+                // 10.2.8. Push updateHash onto btc1UpdateHashHistory.
+                btc1UpdateHashHistory.push(updateHash);
+                // 10.2.9. Set contemporaryHash to result of passing contemporaryDIDDocument into the JSON Canonicalization and Hash algorithm.
+                contemporaryHash = await JSON.canonicalization.process(contemporaryDidDocument, 'base58');
+                //  10.3. If update.targetVersionId is greater than currentVersionId + 1, MUST throw a LatePublishing error.
+            }
+            else if (update.targetVersionId > currentVersionId + 1) {
+                throw new Btcr2ReadError(`Version Id Mismatch: target ${update.targetVersionId} cannot be > current+1 ${currentVersionId + 1}`, 'LATE_PUBLISHING_ERROR');
+            }
+        }
+        // 13. If targetVersionId in not null, set targetDocument to the index at the targetVersionId of the didDocumentHistory array.
+        if (targetVersionId) {
+            return new Btc1DidDocument(didDocumentHistory[targetVersionId]);
+        }
+        // 14. Return contemporaryDidDocument.
+        return new Btc1DidDocument(contemporaryDidDocument);
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#find-next-signals | 4.2.3.3 Find Next Signals}.
+     *
+     * The Find Next Signals algorithm finds the next Bitcoin block containing Beacon Signals from one or more of the
+     * beacons and retuns all Beacon Signals within that block.
+     *
+     * It takes the following inputs:
+     *  - `contemporaryBlockhieght`: The height of the block this function is looking for Beacon Signals in.
+     *                               An integer greater or equal to 0.
+     *  - `targetBlockheight`: The height of the Bitcoin block that the resolution algorithm searches for Beacon Signals
+     *                         up to. An integer greater or equal to 0.
+     *  - `beacons`: An array of Beacon services in the contemporary DID document. Each Beacon contains properties:
+     *      - `id`: The id of the Beacon service in the DID document. A string.
+     *      - `type`: The type of the Beacon service in the DID document. A string whose values MUST be
+     *                          either SingletonBeacon, CIDAggregateBeacon or SMTAggregateBeacon.
+     *      - `serviceEndpoint`: A BIP21 URI representing a Bitcoin address.
+     *      - `address`: The Bitcoin address decoded from the `serviceEndpoint value.
+     *  - `network`: A string identifying the Bitcoin network of the did:btcr2 identifier. This algorithm MUST query the
+     *               Bitcoin blockchain identified by the network.
+     *
+     * It returns a nextSignals struct, containing the following properties:
+     *  - blockheight: The Bitcoin blockheight for the block containing the Beacon Signals.
+     *  - signals: An array of signals. Each signal is a struct containing the following:
+     *      - beaconId: The id for the Beacon that the signal was announced by.
+     *      - beaconType: The type of the Beacon that announced the signal.
+     *      - tx: The Bitcoin transaction that is the Beacon Signal.
+     *
+     * @public
+     * @param {FindNextSignals} params The parameters for the findNextSignals operation.
+     * @param {number} params.blockheight The blockheight to start looking for beacon signals.
+     * @param {Array<BeaconService>} params.target The target blockheight at which to stop finding signals.
+     * @param {Array<BeaconService>} params.beacons The beacons to look for in the block.
+     * @returns {Promise<Array<BeaconSignal>>} An array of BeaconSignal objects with blockHeight and signals.
+     */
+    static async findNextSignals({ contemporaryBlockHeight, targetTime, beacons }) {
+        let height = contemporaryBlockHeight;
+        // Toggle RPC or REST connection based on the connection type
+        const bitcoin = bitcoinNetwork ?? new Bitcoin();
+        // Create an default beaconSignal and beaconSignals array
+        let beaconSignals = [];
+        if (bitcoin.network.rest) {
+            return await this.findSignalsRest({ beacons });
+        }
+        // Use connection to get the block data at the blockhash
+        let block = await bitcoin.network.rpc.getBlock({ height });
+        Logger.info(`Searching for signals, please wait ...`);
+        while (block.time <= targetTime) {
+            // Iterate over each transaction in the block
+            for (const tx of block.tx) {
+                // If the txid is a coinbase, continue ...
+                if (tx.txid === GENESIS_TX_ID) {
+                    continue;
+                }
+                // Iterate over each input in the transaction
+                for (const vin of tx.vin) {
+                    // If the vin is a coinbase transaction, continue ...
+                    if (vin.coinbase) {
+                        continue;
+                    }
+                    // If the vin txinwitness contains a coinbase identifier, continue ...
+                    if (vin.txinwitness && vin.txinwitness.length === 1 && vin.txinwitness[0] === TXIN_WITNESS_COINBASE) {
+                        continue;
+                    }
+                    // If the txid from the vin is undefined, continue ...
+                    if (!vin.txid) {
+                        continue;
+                    }
+                    // If the vout from the vin is undefined, continue ...
+                    if (vin.vout === undefined) {
+                        continue;
+                    }
+                    // Get the previous output transaction data
+                    const prevout = await bitcoin.network.rpc.getRawTransaction(vin.txid, 2);
+                    // If the previous output vout at the vin.vout index is undefined, continue ...
+                    if (!prevout.vout[vin.vout]) {
+                        continue;
+                    }
+                    // Get the address from the scriptPubKey from the prevvout (previous output's input at the vout index)
+                    const scriptPubKey = prevout.vout[vin.vout].scriptPubKey;
+                    // If the scriptPubKey.address is undefined, continue ...
+                    if (!scriptPubKey.address) {
+                        continue;
+                    }
+                    // If the beaconAddress from prevvout scriptPubKey is not a beacon service endpoint address, continue ...
+                    const beaconAddresses = BeaconUtils.getBeaconServiceAddressMap(beacons);
+                    const beacon = (beaconAddresses.get(scriptPubKey.address) ?? {});
+                    if (!beacon || !(beacon.id && beacon.type)) {
+                        continue;
+                    }
+                    // If the prevout.vout[vin.vout].scriptPubKey.asm does not include 'OP_RETURN', continue ...
+                    if (!prevout.vout[vin.vout].scriptPubKey.asm.includes('OP_RETURN')) {
+                        continue;
+                    }
+                    // Log the found txid and beacon
+                    Logger.info(`Tx ${tx.txid} contains beacon address ${scriptPubKey.address} and OP_RETURN!`, tx);
+                    // Push the signal object to to signals array
+                    beaconSignals.push({
+                        beaconId: beacon.id,
+                        beaconType: beacon.type,
+                        beaconAddress: beacon.address,
+                        tx,
+                        blockheight: block.height,
+                        blocktime: block.time
+                    });
+                }
+                ;
+            }
+            height += 1;
+            const tip = await bitcoin.network.rpc.getBlockCount();
+            if (height > tip) {
+                Logger.info(`Chain tip reached ${height}, breaking ...`);
+                break;
+            }
+            // Reset the block to the next block
+            block = await bitcoin.network.rpc.getBlock({ height });
+        }
+        return beaconSignals;
+    }
+    /**
+     * Helper method for the {@link findNextSignals | Find Next Signals} algorithm.
+     *
+     * @param params See {@link FindNextSignalsRestParams} for details.
+     * @param {BitcoinClient} params.connection The bitcoin connection to use.
+     * @param {Array<BeaconSignal>} params.beaconSignals The beacon signals to process.
+     * @param {BlockV3} params.block The block to process.
+     * @param {Array<BeaconService>} params.beacons The beacons to process.
+     * @returns {Promise<Array<BeaconSignal>>} The beacon signals found in the block.
+     */
+    static async findSignalsRest({ beacons }) {
+        const bitcoin = bitcoinNetwork ?? new Bitcoin();
+        // Empty array of beaconSignals
+        const beaconSignals = new Array();
+        // Iterate over each beacon
+        for (const beacon of BeaconUtils.toBeaconServiceAddress(beacons)) {
+            // Get the transactions for the beacon address via REST
+            const transactions = await bitcoin.rest.address.getTxs(beacon.address);
+            // If no transactions are found, continue
+            if (!transactions || transactions.length === 0) {
+                continue;
+            }
+            // Iterate over each transaction and push a beaconSignal
+            for (const tx of transactions) {
+                for (const vout of tx.vout) {
+                    if (vout.scriptpubkey_asm.includes('OP_RETURN')) {
+                        beaconSignals.push({
+                            beaconId: beacon.id,
+                            beaconType: beacon.type,
+                            beaconAddress: beacon.address,
+                            tx,
+                            blockheight: tx.status.block_height,
+                            blocktime: tx.status.block_time,
+                        });
+                    }
+                }
+            }
+        }
+        // Return the beaconSignals
+        return beaconSignals;
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#process-beacon-signals | 4.2.3.4 Process Beacon Signals}.
+     *
+     * The Process Beacon Signals algorithm processes each Beacon Signal by attempting to retrieve and validate an
+     * announce DID Update Payload for that signal according to the type of the Beacon.
+     *
+     * It takes as inputs
+     *  - `beaconSignals`: An array of Beacon Signals retrieved from the Find Next Signals algorithm. Each signal contains:
+     *    - `beaconId`: The id for the Beacon that the signal was announced by.
+     *    - `beaconType`: The type of the Beacon that announced the signal.
+     *    - `tx`: The Bitcoin transaction that is the Beacon Signal.
+     *  - `signalsMetadata`: Maps Beacon Signal Bitcoin transaction ids to a SignalMetadata object containing:
+     *    - `updatePayload`: A DID Update Payload which should match the update announced by the Beacon Signal.
+     *                       In the case of a SMT proof of non-inclusion, no DID Update Payload may be provided.
+     *    - `proofs`: Sparse Merkle Tree proof used to verify that the `updatePayload` exists as the leaf indexed by the
+     *                did:btcr2 identifier being resolved.
+     *
+     * It returns an array of {@link https://dcdpr.github.io/did-btcr2/#def-did-update-payload | DID Update Payloads}.
+     *
+     * @public
+     * @param {BeaconSignal} signal The beacon signals to process.
+     * @param {SignalsMetadata} signalsMetadata The sidecar data for the DID Document.
+     * @returns {DidUpdatePayload[]} The updated DID Document object.
+     */
+    static async processBeaconSignal(signal, signalsMetadata) {
+        // 1. Set updates to an empty array.
+        const updates = new Array();
+        // 2. For beaconSignal in beaconSignals:
+        // 2.1 Set type to beaconSignal.beaconType.
+        // 2.2 Set signalTx to beaconSignal.tx.
+        // 2.3 Set signalId to signalTx.id.
+        const { beaconId: id, beaconType: type, beaconAddress: address, tx } = signal;
+        const signalTx = tx;
+        // 2.4 Set signalSidecarData to signalsMetadata[signalId]. TODO: formalize structure of sidecarData
+        // const signalSidecarData = new Map(Object.entries(signalsMetadata)).get(id)!;
+        // TODO: processBeaconSignal - formalize structure of sidecarData, signalSidecarData
+        // 2.6 If type == SingletonBeacon:
+        //     2.6.1 Set didUpdatePayload to the result of passing signalTx and signalSidecarData to Process Singleton Beacon Signal algorithm.
+        // 2.7 If type == CIDAggregateBeacon:
+        //     2.7.1 Set didUpdatePayload to the result of passing signalTx and signalSidecarData to the Process CIDAggregate Beacon Signal algorithm.
+        // 2.8 If type == SMTAggregateBeacon:
+        //     2.8.1 Set didUpdatePayload to the result of passing signalTx and signalSidecarData to the Process SMTAggregate Beacon Signal algorithm.
+        // TODO: processBeaconSignal - where/how to convert signalsMetadata to diff sidecars
+        const sidecar = { signalsMetadata };
+        // switch (type) {
+        //   case 'SingletonBeacon': {
+        //     sidecar = { signalsMetadata } as SingletonSidecar;
+        //     break;
+        //   }
+        //   case 'CIDAggregateBeacon': {
+        //     sidecar = {} as CIDAggregateSidecar;
+        //     break;
+        //   }
+        //   case 'SMTAggregateBeacon': {
+        //     sidecar = {} as SMTAggregateSidecar;
+        //     break;
+        //   }
+        //   default: {
+        //     throw new Btcr2Error('Invalid beacon type', 'INVALID_BEACON_TYPE', { type });
+        //   }
+        // }
+        // Construct a service object from the beaconId and type
+        // and set the serviceEndpoint to the BIP21 URI for the Bitcoin address.
+        const service = { id, type, serviceEndpoint: `bitcoin:${address}` };
+        // Establish a Beacon instance using the service and sidecar
+        const beacon = BeaconFactory.establish(service, sidecar);
+        // 2.5 Set btc1Update to null.
+        const btc1Update = await beacon.processSignal(signalTx, signalsMetadata) ?? null;
+        // If the updates is null, throw an error
+        if (!btc1Update) {
+            throw new Btcr2Error('No btc1Update for beacon', 'PROCESS_BEACON_SIGNALS_ERROR', { tx, signalsMetadata });
+        }
+        // 2.9 If btc1Update is not null, push btc1Update to updates.
+        updates.push(btc1Update);
+        // 3. Return updates.
+        return btc1Update;
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#confirm-duplicate-update | 7.2.2.4 Confirm Duplicate Update}.
+     *
+     * The Confirm Duplicate Update algorithm takes in a {@link DidUpdatePayload | DID Update Payload} and verifies that
+     * the update is a duplicate against the hash history of previously applied updates. The algorithm takes in an update
+     * and an array of hashes, updateHashHistory. It throws an error if the update is not a duplicate, otherwise it
+     * returns.
+     *
+     * @public
+     * @param {{ update: DidUpdatePayload; updateHashHistory: string[]; }} params Parameters for confirmDuplicateUpdate.
+     * @param {DidUpdatePayload} params.update The DID Update Payload to confirm.
+     * @param {Array<string>} params.updateHashHistory The history of hashes for previously applied updates.
+     * @returns {Promise<void>} A promise that resolves if the update is a duplicate, otherwise throws an error.
+     * @throws {DidBtc1Error} if the update hash does not match the historical hash.
+     */
+    static async confirmDuplicateUpdate({ update, updateHashHistory }) {
+        // 1. Let unsecuredUpdate be a copy of the update object.
+        const unsecuredUpdate = update;
+        // 2. Remove the proof property from the unsecuredUpdate object.
+        delete unsecuredUpdate.proof;
+        // 3. Let updateHash equal the result of passing unsecuredUpdate into the JSON Canonicalization and Hash algorithm.
+        const updateHash = await JSON.canonicalization.process(unsecuredUpdate);
+        // 4. Let updateHashIndex equal update.targetVersionId - 2.
+        // const updateHashIndex = update.targetVersionId - 2;
+        // 5. Let historicalUpdateHash equal updateHashHistory[updateHashIndex].
+        const historicalUpdateHash = updateHashHistory[update.targetVersionId - 2];
+        // Check if the updateHash matches the historical hash
+        if (historicalUpdateHash !== updateHash) {
+            throw new Btcr2ReadError(`Invalid duplicate: ${updateHash} does not match ${historicalUpdateHash}`, 'LATE_PUBLISHING_ERROR', { updateHash, updateHashHistory });
+        }
+    }
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#apply-did-update | 4.2.3.6 Apply DID Update}.
+     *
+     * This algorithm attempts to apply a DID Update to a DID document, it first verifies the proof on the update is a
+     * valid capabilityInvocation of the root authority over the DID being resolved. Then it applies the JSON patch
+     * transformation to the DID document, checks the transformed DID document matches the targetHash specified by the
+     * update and validates it is a conformant DID document before returning it. This algorithm takes inputs
+     * contemporaryDidDocument and an update.
+     *
+     * @public
+     * @param {ApplyDidUpdateParams} params Parameters for applyDidUpdate.
+     * @param {Btc1DidDocument} params.contemporaryDidDocument The current DID Document to update.
+     * @param {DidUpdatePayload} params.update The DID Update Payload to apply.
+     * @param {Bytes} params.genesisBytes The genesis bytes for the DID Document.
+     * @returns {Promise<Btc1DidDocument>}
+     */
+    static async applyDidUpdate({ contemporaryDidDocument, update }) {
+        // 1. Set capabilityId to update.proof.capability.
+        const capabilityId = update.proof?.capability;
+        if (!capabilityId) {
+            throw new Btcr2ReadError('No capabilityId found in update', INVALID_DID_UPDATE);
+        }
+        // 2. Set rootCapability to the result of passing capabilityId to the Dereference Root Capability Identifier algorithm.
+        const rootCapability = Btc1Appendix.derefernceRootCapabilityIdentifier(capabilityId);
+        // 3. If rootCapability.invocationTarget does not equal contemporaryDidDocument.id
+        //    and rootCapability.controller does not equal contemporaryDidDocument.id, MUST throw an invalidDidUpdate error.
+        const { invocationTarget, controller: rootController } = rootCapability;
+        if (![invocationTarget, rootController].every((id) => id === contemporaryDidDocument.id)) {
+            throw new Btcr2ReadError(`Invalid root capability: ${rootCapability}`, INVALID_DID_UPDATE);
+        }
+        // 4. Instantiate a bip340-jcs-2025 cryptosuite instance using the key referenced by the verificationMethod field in the update.
+        // Get the verificationMethod field from the update.
+        const methodId = update.proof?.verificationMethod;
+        if (!methodId) {
+            throw new Btcr2ReadError('No verificationMethod found in update', INVALID_DID_UPDATE, update);
+        }
+        // Get the verificationMethod from the DID Document using the methodId.
+        const { id: vmId, publicKeyMultibase } = DidBtc1.getSigningMethod({ didDocument: contemporaryDidDocument, methodId });
+        // Split the vmId by the `#` to get the id and controller.
+        const [controller, id] = vmId.split('#');
+        // Construct a new Multikey.
+        const multikey = SchnorrMultikey.fromPublicKeyMultibase({ id: `#${id}`, controller, publicKeyMultibase });
+        // Logger.warn('// TODO: applyDidUpdate - Refactor Multikey to accept pub/priv bytes => Pub/PrivKey => KeyPair.');
+        const cryptosuite = new Cryptosuite({ cryptosuite: 'bip340-jcs-2025', multikey });
+        // Logger.warn('// TODO: applyDidUpdate - Refactor Cryptosuite to default to RDFC.');
+        // 5. Set expectedProofPurpose to capabilityInvocation.
+        const expectedPurpose = 'capabilityInvocation';
+        // 6. Set mediaType to ????
+        // const mediaType = 'application/json';
+        // Logger.warn('// TODO: applyDidUpdate - is this just application/json?');
+        // 7. Set documentBytes to the bytes representation of update.
+        const documentBytes = await JSON.canonicalization.canonicalize(update);
+        // 8. Set verificationResult to the result of passing mediaType, documentBytes, cryptosuite, and
+        //    expectedProofPurpose into the Verify Proof algorithm defined in the VC Data Integrity specification.
+        const diProof = new DataIntegrityProof(cryptosuite);
+        const verificationResult = await diProof.verifyProof({ document: documentBytes, expectedPurpose });
+        // 9. If verificationResult.verified equals False, MUST raise a invalidUpdateProof exception.
+        if (!verificationResult.verified) {
+            throw new Btcr2Error('Invalid update: proof not verified', INVALID_DID_UPDATE, verificationResult);
+        }
+        // 10. Set targetDIDDocument to a copy of contemporaryDidDocument.
+        let targetDIDDocument = contemporaryDidDocument;
+        // 11. Use JSON Patch to apply the update.patch to the targetDIDDOcument.
+        targetDIDDocument = JSON.patch.apply(targetDIDDocument, update.patch);
+        // 12. Verify that targetDIDDocument is conformant with the data model specified by the DID Core specification.
+        Btc1DidDocument.validate(targetDIDDocument);
+        // 13. Set targetHash to the SHA256 hash of targetDIDDocument.
+        const targetHash = await JSON.canonicalization.process(targetDIDDocument, 'base58');
+        // Prepend the sourceHash if it does not start with `z`
+        const updateTargetHash = update.targetHash.startsWith('z')
+            ? update.targetHash
+            : `z${update.targetHash}`;
+        // 14. Check that targetHash equals update.targetHash, else raise InvalidDIDUpdate error.
+        if (updateTargetHash !== targetHash) {
+            throw new Btcr2Error(`Invalid update: updateTargetHash ${updateTargetHash} does not match targetHash ${targetHash}`, INVALID_DID_UPDATE);
+        }
+        // 15. Return targetDIDDocument.
+        return targetDIDDocument;
+    }
+}
+//# sourceMappingURL=read.js.map