@did-btcr2/method 0.62.0 → 0.64.0

package/dist/esm/core/resolver.js

@@ -1,11 +1,11 @@
 import { getNetwork } from '@did-btcr2/bitcoin';
-import { canonicalHash, canonicalHashBytes, canonicalize, DateUtils, encode as encodeHash, decode as decodeHash, INTERNAL_ERROR, INVALID_DID, INVALID_DID_UPDATE, INVALID_OPTIONS, JSONPatch, JSONUtils, LATE_PUBLISHING_ERROR, ResolveError } from '@did-btcr2/common';
+import { canonicalHash, canonicalHashBytes, canonicalize, DateUtils, encode as encodeHash, decode as decodeHash, INTERNAL_ERROR, INVALID_DID, INVALID_DID_UPDATE, INVALID_OPTIONS, JSONPatch, JSONUtils, LATE_PUBLISHING_ERROR, NOT_FOUND, ResolveError } from '@did-btcr2/common';
 import { BTCR2_UPDATE_CONTEXT, isBtcr2UpdateContext } from './btcr2-update.js';
 import { BIP340Cryptosuite, BIP340DataIntegrityProof, SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
-import { DidBtcr2 } from '../did-btcr2.js';
 import { Appendix } from '../utils/appendix.js';
 import { DidDocument, ID_PLACEHOLDER_VALUE } from '../utils/did-document.js';
+import { errorCause } from '../utils/error-cause.js';
 import { BeaconFactory } from './beacon/factory.js';
 import { BeaconUtils } from './beacon/utils.js';
 import { Identifier } from './identifier.js';
@@ -63,18 +63,64 @@ function validateMinConf(value) {
         return DEFAULT_MIN_CONF;
     if (typeof value === 'number' && Number.isInteger(value) && value >= 1)
         return value;
-    const shown = typeof value === 'string' ? JSON.stringify(value) : String(value);
-    throw new ResolveError(`Invalid resolution option minConf: expected a positive integer (minimum 1), got ${shown}.`, INVALID_OPTIONS, { minConf: value });
+    throw new ResolveError(`Invalid resolution option minConf: expected a positive integer (minimum 1), got ${shown(value)}.`, INVALID_OPTIONS, { minConf: value });
 }
+/** Render an option value for an error message: a string in quotes, any other value as is. */
+function shown(value) {
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+/** An ASCII string of an integer: an optional minus sign, then digits. */
+const ASCII_INTEGER = /^-?[0-9]+$/;
 /**
- * Different possible Resolver states representing phases in the resolution process.
+ * Parse `ResolutionOptions.versionId`. The specification says that the value MUST
+ * parse as an integer, and DID Resolution v1 types the option as a string. The
+ * accepted form is an ASCII string of an integer inside the safe integer range.
+ * @returns {number | undefined} The integer, or `undefined` when the option is absent.
+ * @throws {ResolveError} `INVALID_OPTIONS` for every other value.
+ */
+function validateVersionId(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string' && ASCII_INTEGER.test(value) && Number.isSafeInteger(Number(value))) {
+        return Number(value);
+    }
+    throw new ResolveError(`Invalid resolution option versionId: expected an ASCII string of an integer, got ${shown(value)}.`, INVALID_OPTIONS, { versionId: value });
+}
+/** An XML Datetime in UTC with the `Z` designator and no fraction, for example `2026-07-01T00:00:00Z`. */
+const UTC_XSD_DATETIME = /^-?\d{4,}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+/** The timezone part that an XML Schema `dateTimeStamp` requires: `Z` or an offset. */
+const XSD_TIMEZONE = /(Z|[+-]\d{2}:\d{2})$/;
+/**
+ * Parse `ResolutionOptions.versionTime`. DID Resolution v1 requires an XML Datetime
+ * normalized to UTC without sub-second precision. The specification raises
+ * `INVALID_OPTIONS` for a value that does not parse.
+ * @returns {number | undefined} The instant in milliseconds since the Unix epoch, or `undefined` when the option is absent.
+ * @throws {ResolveError} `INVALID_OPTIONS` for every other value.
+ */
+function validateVersionTime(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string' && UTC_XSD_DATETIME.test(value) && DateUtils.isValidXsdDateTime(value)) {
+        const ms = Date.parse(value);
+        if (Number.isFinite(ms))
+            return ms;
+    }
+    throw new ResolveError('Invalid resolution option versionTime: expected an XML Datetime in UTC without a fraction '
+        + `(for example "2026-07-01T00:00:00Z"), got ${shown(value)}.`, INVALID_OPTIONS, { versionTime: value });
+}
+/**
+ * The phases of the resolution process. Each pass of the specification loop is
+ * BeaconDiscovery (the scan of the beacon addresses the resolver did not scan yet),
+ * BeaconProcess (the tuples of the signals the caller provided), and ProcessUpdate
+ * (one tuple). GenesisDocument runs once, for an EXTERNAL identifier whose genesis
+ * document is not in the sidecar.
  */
 var ResolverPhase;
 (function (ResolverPhase) {
     ResolverPhase["GenesisDocument"] = "GenesisDocument";
     ResolverPhase["BeaconDiscovery"] = "BeaconDiscovery";
     ResolverPhase["BeaconProcess"] = "BeaconProcess";
-    ResolverPhase["ApplyUpdates"] = "ApplyUpdates";
+    ResolverPhase["ProcessUpdate"] = "ProcessUpdate";
     ResolverPhase["Complete"] = "Complete";
 })(ResolverPhase || (ResolverPhase = {}));
 /**
@@ -102,7 +148,9 @@ var ResolverPhase;
 export class Resolver {
     // --- Immutable inputs ---
     #didComponents;
+    /** The parsed `ResolutionOptions.versionId`, or `undefined` when the option is absent. */
     #versionId;
+    /** The parsed `ResolutionOptions.versionTime` in milliseconds since the Unix epoch, or `undefined`. */
     #versionTime;
     /**
      * The specific phase the Resolver is current in.
@@ -113,22 +161,28 @@ export class Resolver {
     #providedGenesisDocument = null;
     #beaconServicesSignals = new Map();
     #processedServices = new Set();
+    /** The beacon addresses the resolver requested signals for: `scanned_beacons` of the specification. */
     #requestCache = new Set();
+    /**
+     * The tuples of the specification's `updates` list: a signed update and the metadata of
+     * the block that announced it. BeaconProcess appends; ProcessUpdate sorts the list and
+     * removes one tuple per step. A tuple that one pass does not reach waits for the next.
+     */
     #unsortedUpdates = [];
     #resolvedResponse = null;
     /**
-     * Monotonic DID-document version counter and the update-hash history that backs
-     * duplicate confirmation, both carried across the entire resolution. The spec's
-     * read algorithm keeps a single version counter and a single update-hash history
-     * for the whole signal-processing loop, re-deriving beacons from the contemporary
-     * document on each pass. This sans-I/O resolver splits that one loop into discovery
-     * rounds, so the two must persist across rounds rather than restart each pass.
-     * Restarting them would reject a legitimate linear history whose later updates are
-     * announced on beacons that earlier updates added: round two would forget it had
-     * already reached version two, see version three, and raise a late-publishing error.
+     * The state of the specification loop, carried across every pass: the version counter
+     * (`current_version_id`), the update-hash history that backs duplicate confirmation
+     * (`update_hash_history`), the confirmations of the block that contains the most
+     * recently applied unique update (`block_confirmations`), and the header time of that
+     * block as `updated`. A pass that finds a new beacon address returns to discovery, so
+     * the state must not restart: a restart would reject a linear history whose later
+     * updates are announced on beacons that earlier updates added.
      */
     #currentVersionId = 1;
     #updateHashHistory = [];
+    #blockConfirmations = 0;
+    #updated;
     /**
      * Opt-in upper bound on multi-round beacon-discovery passes. `Infinity` (the
      * default) leaves discovery unbounded; termination is already guaranteed by
@@ -153,14 +207,20 @@ export class Resolver {
         this.#didComponents = didComponents;
         this.#sidecarData = sidecarData;
         this.#currentDocument = currentDocument;
-        this.#versionId = options?.versionId;
-        this.#versionTime = options?.versionTime;
+        // The resolution options fail here, before any data need is emitted, so the
+        // caller does no I/O for a request it cannot serve. DID Resolution v1 defines
+        // versionId and versionTime as mutually exclusive; the specification raises
+        // INVALID_OPTIONS for a request with both, and for a value that does not parse.
+        if (options?.versionId !== undefined && options?.versionTime !== undefined) {
+            throw new ResolveError('Invalid resolution options: versionId and versionTime are mutually exclusive. Pass one of them.', INVALID_OPTIONS, { versionId: options.versionId, versionTime: options.versionTime });
+        }
+        this.#versionId = validateVersionId(options?.versionId);
+        this.#versionTime = validateVersionTime(options?.versionTime);
         // Discovery is unbounded by default; a positive maxDiscoveryRounds opts into a
         // finite resource guard. A non-positive or omitted value means no limit.
         const rounds = options?.maxDiscoveryRounds;
         this.#maxDiscoveryRounds = typeof rounds === 'number' && rounds > 0 ? rounds : Infinity;
-        // The signal confirmation threshold. An invalid value fails here, before any
-        // data need is emitted, so the caller does no I/O for a request it cannot serve.
+        // The signal confirmation threshold.
         this.#minConf = validateMinConf(options?.minConf);
         // If a genesis document was provided (from sidecar), pre-seed it for validation
         if (options?.genesisDocument) {
@@ -254,124 +314,7 @@ export class Resolver {
         return { updateMap, casMap, smtMap };
     }
     /**
-     * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#process-updates | 7.2.f Process updates Array}.
-     * @param {DidDocument} currentDocument The current DID Document to apply the updates to.
-     * @param {Array<[SignedBTCR2Update, BlockMetadata]>} unsortedUpdates The unsorted array of BTCR2 Signed Updates and their associated Block Metadata.
-     * @param {string} [versionTime] The optional version time to limit updates to.
-     * @param {string} [versionId] The optional version id to limit updates to.
-     * @param {{ currentVersionId: number; updateHashHistory: HashBytes[] }} [resolutionState]
-     *   Version counter and update-hash history carried from earlier discovery rounds.
-     *   Standalone callers omit it and start fresh at version 1 with an empty history.
-     * @returns {DidResolutionResponse} The updated DID Document, number of confirmations, and version id.
-     *
-     * Confirmation depth is not checked here. The BeaconProcess phase excludes a
-     * signal below `ResolutionOptions.minConf` before its update reaches this method,
-     * so every tuple here comes from a block at or above the threshold.
-     */
-    static updates(currentDocument, unsortedUpdates, versionTime, versionId, resolutionState = { currentVersionId: 1, updateHashHistory: [] }) {
-        // Continue the version counter and update-hash history from earlier discovery
-        // rounds so the whole resolution is one monotonic sequence, matching the spec's
-        // single signal-processing loop. updateHashHistory is shared by reference, so the
-        // appends made below are visible to the next round.
-        let currentVersionId = resolutionState.currentVersionId;
-        const updateHashHistory = resolutionState.updateHashHistory;
-        // 1. Sort updates by targetVersionId (ascending), using blockheight as tie-breaker
-        const updates = unsortedUpdates.sort(([upd0, blk0], [upd1, blk1]) => upd0.targetVersionId - upd1.targetVersionId || blk0.height - blk1.height);
-        // Create a default response object. `updated` is absent until an update applies.
-        const response = {
-            didDocument: currentDocument,
-            metadata: {
-                versionId: `${currentVersionId}`,
-                confirmations: 0,
-                deactivated: currentDocument.deactivated || false
-            }
-        };
-        // Iterate over each (update block) pair
-        for (const [update, block] of updates) {
-            // Get the hash of the current document as raw bytes
-            const currentDocumentHash = canonicalHashBytes(response.didDocument);
-            // Safely convert block.time to timestamp
-            const blocktime = DateUtils.blocktimeToTimestamp(block.time);
-            // Set the updated field to the blocktime of the current update
-            response.metadata.updated = DateUtils.toISOStringNonFractional(blocktime);
-            // Set confirmations to the block confirmations
-            response.metadata.confirmations = block.confirmations;
-            // Check update.targetVersionId against currentVersionId.
-            // If update.targetVersionId <= currentVersionId, this update re-announces a version
-            // that has already been applied. Confirm it is a true duplicate, then skip it: a
-            // duplicate does not advance the version counter (the increment and the
-            // metadata.versionId it sets run only on the apply path below), and confirmation
-            // compares against the update-hash history without appending to it, because the
-            // history already holds the applied update at updateHashHistory[targetVersionId - 2].
-            // Holding the increment off the duplicate path is the deliberate did:btcr2 deviation
-            // recorded in ADR 067: the read algorithm's "Increment current_version_id" belongs
-            // to the apply branch, not to every tuple. Duplicates are confirmed whatever their
-            // blocktime, before the versionTime check below, so a re-announcement mined after
-            // versionTime can neither truncate the in-window history nor dodge late-publishing
-            // detection (ADR 068).
-            if (update.targetVersionId <= currentVersionId) {
-                this.confirmDuplicate(update, updateHashHistory);
-                continue;
-            }
-            // if resolutionOptions.versionTime is defined and the blocktime is more recent, return
-            // currentDocument. Evaluated only for tuples that would change state (apply or late
-            // publishing). The spec places this check before the duplicate branch, where the sort
-            // by targetVersionId lets a duplicate of an early version mined after versionTime end
-            // resolution before genuine in-window updates are processed; checking it here is the
-            // deliberate deviation recorded in ADR 068.
-            if (versionTime) {
-                // Safely convert versionTime to timestamp
-                if (blocktime > DateUtils.dateStringToTimestamp(versionTime)) {
-                    return response;
-                }
-            }
-            // If update.targetVersionId == currentVersionId + 1, apply the update
-            if (update.targetVersionId === currentVersionId + 1) {
-                // Check if update.sourceHash !== currentDocumentHash (byte comparison)
-                const sourceHashBytes = decodeHash(update.sourceHash, 'base64urlnopad');
-                if (!equalBytes(sourceHashBytes, currentDocumentHash)) {
-                    throw new ResolveError(`Hash mismatch: update.sourceHash !== currentDocumentHash`, INVALID_DID_UPDATE, {
-                        sourceHash: update.sourceHash,
-                        currentDocumentHash: encodeHash(currentDocumentHash, 'hex')
-                    });
-                }
-                // Apply the update to the currentDocument and set it in the response
-                response.didDocument = this.applyUpdate(response.didDocument, update);
-                // Create unsigned_update by removing the proof property from update.
-                const unsignedUpdate = JSONUtils.deleteKeys(update, ['proof']);
-                // Push the canonicalized unsigned update hash bytes to the updateHashHistory
-                updateHashHistory.push(canonicalHashBytes(unsignedUpdate));
-            }
-            // Otherwise update.targetVersionId > currentVersionId + 1: a version was skipped,
-            // so throw LATE_PUBLISHING error. The duplicate case already continued above.
-            else {
-                throw new ResolveError(`Version Id Mismatch: targetVersionId cannot be > currentVersionId + 1`, LATE_PUBLISHING_ERROR, {
-                    targetVersionId: update.targetVersionId,
-                    currentVersionId: currentVersionId + 1
-                });
-            }
-            // Increment currentVersionId
-            currentVersionId++;
-            // Set response.versionId to be the new currentVersionId
-            response.metadata.versionId = `${currentVersionId}`;
-            // If resolutionOptions.versionId is defined and <= currentVersionId, return currentDocument
-            const versionIdNumber = Number(versionId);
-            if (!isNaN(versionIdNumber) && versionIdNumber <= currentVersionId) {
-                return response;
-            }
-            // Check if the current document is deactivated before further processing
-            if (response.didDocument.deactivated) {
-                // Set the response deactivated flag to true
-                response.metadata.deactivated = response.didDocument.deactivated;
-                // If deactivated, stop processing further updates and return the response
-                return response;
-            }
-        }
-        // Return response data
-        return response;
-    }
-    /**
-     * Implements subsection {@link https://dcdpr.github.io/did-btcr2/#confirm-duplicate-update | 7.2.f.1 Confirm Duplicate Update}.
+     * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#confirm-duplicate-update | Confirm Duplicate Update}.
      * This step confirms that an update with a lower-than-expected targetVersionId is a true duplicate.
      * @param {SignedBTCR2Update} update The BTCR2 Signed Update to confirm as a duplicate.
      * @param {HashBytes[]} updateHashHistory The accumulated hash history for comparison.
@@ -410,14 +353,90 @@ export class Resolver {
         }
     }
     /**
-     * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#apply-update | 7.2.f.3 Apply Update}
+     * Decode a hash of a BTCR2 Update (`sourceHash` or `targetHash`). The specification encodes
+     * both with base64url without padding.
+     * @param {unknown} value The encoded hash.
+     * @param {'sourceHash' | 'targetHash'} field The name of the field, for the error.
+     * @returns {HashBytes} The decoded bytes.
+     * @throws {ResolveError} `INVALID_DID_UPDATE` if the value is not a string or does not decode.
+     */
+    static decodeUpdateHash(value, field) {
+        if (typeof value === 'string') {
+            try {
+                return decodeHash(value, 'base64urlnopad');
+            }
+            catch (error) {
+                throw new ResolveError(`Invalid update: ${field} does not decode as base64url: ${errorCause(error).message}`, INVALID_DID_UPDATE, { [field]: value, cause: errorCause(error) });
+            }
+        }
+        throw new ResolveError(`Invalid update: ${field} is not a string`, INVALID_DID_UPDATE, { [field]: value });
+    }
+    /**
+     * Parse a `created` or `expires` value of an update proof. Data Integrity types both as an
+     * XML Schema `dateTimeStamp`: an XML Datetime with a timezone. A value without a timezone
+     * names no fixed instant, so two resolvers would read two instants; it is rejected.
+     * @param {Btcr2DataIntegrityProof} proof The update proof.
+     * @param {'created' | 'expires'} field The field to parse.
+     * @returns {number | undefined} The instant in milliseconds since the Unix epoch, or `undefined` when the field is absent.
+     * @throws {ResolveError} `INVALID_DID_UPDATE` for a value that is not an XML Datetime with a timezone.
+     */
+    static proofInstant(proof, field) {
+        const value = proof[field];
+        if (value === undefined)
+            return undefined;
+        if (typeof value === 'string' && XSD_TIMEZONE.test(value) && DateUtils.isValidXsdDateTime(value)) {
+            const ms = Date.parse(value);
+            if (Number.isFinite(ms))
+                return ms;
+        }
+        throw new ResolveError(`Invalid update: proof.${field} is not an XML Datetime with a timezone`, INVALID_DID_UPDATE, { [field]: value });
+    }
+    /**
+     * Spec "Check `update.proof`": the proof time window against the block that contains the
+     * Beacon Signal. `created` must not be after the header time of the block: a controller
+     * signs a short time before the block, and on mainnet the header time is about one hour
+     * after the `mediantime`. `expires` must not be before the block `mediantime`: it limits a
+     * replay, and a single miner cannot change `mediantime`. `expires` must not be before
+     * `created`. Each comparison has no tolerance.
+     * @param {Btcr2DataIntegrityProof} proof The update proof.
+     * @param {BlockMetadata} block The block of the Beacon Signal.
+     * @throws {ResolveError} `INVALID_DID_UPDATE` if a value is outside the window.
+     */
+    static checkProofWindow(proof, block) {
+        const created = Resolver.proofInstant(proof, 'created');
+        const expires = Resolver.proofInstant(proof, 'expires');
+        if (created !== undefined && created > block.time * 1000) {
+            throw new ResolveError('Invalid update: proof.created is after the header time of the block that contains the Beacon Signal', INVALID_DID_UPDATE, { created: proof.created, blockTime: block.time });
+        }
+        if (expires !== undefined && expires < block.mediantime * 1000) {
+            throw new ResolveError('Invalid update: proof.expires is before the mediantime of the block that contains the Beacon Signal', INVALID_DID_UPDATE, { expires: proof.expires, mediantime: block.mediantime });
+        }
+        if (created !== undefined && expires !== undefined && expires < created) {
+            throw new ResolveError('Invalid update: proof.expires is before proof.created', INVALID_DID_UPDATE, { created: proof.created, expires: proof.expires });
+        }
+    }
+    /**
+     * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#apply-update | Apply update}
      * and its step {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#check-update-proof | Check update.proof}.
+     * Every failure that the specification names raises `INVALID_DID_UPDATE`. An error of the
+     * cryptosuite, the multikey, the hash decoder, or the patch rides along as `data.cause`.
      * @param {DidDocument} currentDocument The current DID Document to apply the update to.
      * @param {SignedBTCR2Update} update The BTCR2 Signed Update to apply.
+     * @param {BlockMetadata} block The block that contains the Beacon Signal that announced the update.
      * @returns {DidDocument} The updated DID Document after applying the update.
-     * @throws {ResolveError} If the update is invalid or cannot be applied.
+     * @throws {ResolveError} `INVALID_DID_UPDATE` if the update is invalid or cannot be applied.
      */
-    static applyUpdate(currentDocument, update) {
+    static applyUpdate(currentDocument, update, block) {
+        // Spec "Apply update": the hash of the current document must be the decoded
+        // update.sourceHash (byte comparison).
+        const currentDocumentHash = canonicalHashBytes(currentDocument);
+        const sourceHashBytes = Resolver.decodeUpdateHash(update.sourceHash, 'sourceHash');
+        if (!equalBytes(sourceHashBytes, currentDocumentHash)) {
+            throw new ResolveError(`Hash mismatch: update.sourceHash !== currentDocumentHash`, INVALID_DID_UPDATE, {
+                sourceHash: update.sourceHash,
+                currentDocumentHash: encodeHash(currentDocumentHash, 'hex')
+            });
+        }
         // Spec "Check update.proof": the update @context must be the array that the BTCR2
         // Unsigned Update data structure pins, and the proof @context must equal it, member
         // for member and in order. The array is inside the hashed and signed bytes, so an
@@ -429,74 +448,89 @@ export class Resolver {
         if (!isBtcr2UpdateContext(update.proof?.['@context'], update['@context'])) {
             throw new ResolveError('Invalid update: proof @context does not equal the update @context', INVALID_DID_UPDATE, { proofContext: update.proof?.['@context'], context: update['@context'] });
         }
-        // Get the capability id from the to update proof.
-        const capabilityId = update.proof?.capability;
-        // Since this field is optional, check that it exists
-        if (!capabilityId) {
-            // If it does not exist, throw INVALID_DID_UPDATE error
-            throw new ResolveError('No root capability found in update', INVALID_DID_UPDATE, update);
-        }
-        // Get the root capability object by dereferencing the capabilityId
-        const rootCapability = Appendix.dereferenceZcapId(capabilityId);
-        // Deconstruct the invocationTarget and controller from the root capability
-        const { invocationTarget, controller: rootController } = rootCapability;
-        // Check that both invocationTarget and rootController equal currentDocument.id
-        if (![invocationTarget, rootController].every((id) => id === currentDocument.id)) {
-            // If they do not all match, throw INVALID_DID_UPDATE error
-            throw new ResolveError('Invalid root capability', INVALID_DID_UPDATE, { rootCapability, currentDocument });
-        }
-        // Get the verificationMethod field from the update proof as verificationMethodId.
-        const verificationMethodId = update.proof?.verificationMethod;
-        // Since this field is optional, check that it exists
-        if (!verificationMethodId) {
-            // If it does not exist, throw INVALID_DID_UPDATE error
-            throw new ResolveError('No verificationMethod found in update', INVALID_DID_UPDATE, update);
+        // Spec "Check update.proof": each proof field by string equality, before the method
+        // lookup and before signature verification, so that a failure names the field. The
+        // capability is the URN that the Data Integrity Config specifies for this DID; the root
+        // capability is not derived, the specification makes that optional.
+        const proof = update.proof;
+        const expectedFields = [
+            ['type', 'DataIntegrityProof'],
+            ['cryptosuite', 'bip340-jcs-2025'],
+            ['proofPurpose', 'capabilityInvocation'],
+            ['capabilityAction', 'Write'],
+            ['capability', `urn:zcap:root:${encodeURIComponent(currentDocument.id)}`],
+        ];
+        for (const [field, expected] of expectedFields) {
+            const actual = proof[field];
+            if (actual !== expected) {
+                throw new ResolveError(`Invalid update: proof.${field} must equal "${expected}"`, INVALID_DID_UPDATE, { field, expected, actual });
+            }
         }
-        // Spec "Check update.proof": raise INVALID_DID_UPDATE if
-        // currentDocument.capabilityInvocation does not contain
-        // update.proof.verificationMethod. Locating the method in verificationMethod[] and
-        // verifying its signature is not sufficient on its own: a key the controller
-        // published only for authentication (or for no relationship at all) must not be
-        // able to authorize a DID update. The write path enforces this in DidBtcr2.update();
-        // without it here the read path applies an update signed by any key in the document.
-        // Checked before the method is located so an unauthorized method always fails with
-        // this typed error, whether or not it also appears in verificationMethod[].
-        const authorizedMethodId = Appendix.relationshipMethodId(verificationMethodId, currentDocument.id);
-        const authorized = authorizedMethodId !== undefined && currentDocument.capabilityInvocation?.some(entry => Appendix.relationshipMethodId(entry, currentDocument.id) === authorizedMethodId);
-        if (!authorized) {
+        // Spec "Check update.proof": the entry of currentDocument.capabilityInvocation that
+        // identifies update.proof.verificationMethod, in the reference form or the embedded
+        // form. A key the controller published for authentication only, or for no relationship
+        // at all, must not authorize an update; the membership test runs before the method
+        // lookup so that such a key always fails with this typed error. The method is the
+        // entry itself when embedded, else the member of verificationMethod[] with that id.
+        const verificationMethodId = proof.verificationMethod;
+        const entry = Appendix.capabilityInvocationEntry(currentDocument, verificationMethodId);
+        if (entry === undefined) {
             throw new ResolveError('Invalid update: verificationMethod is not authorized for capabilityInvocation', INVALID_DID_UPDATE, {
                 verificationMethodId,
                 capabilityInvocation: currentDocument.capabilityInvocation
             });
         }
-        // Get the verificationMethod from the DID Document using the verificationMethodId.
-        const vm = DidBtcr2.getSigningMethod(currentDocument, verificationMethodId);
-        // Construct a new SchnorrMultikey.
-        const multikey = SchnorrMultikey.fromVerificationMethod(vm);
-        // Construct a new BIP340Cryptosuite with the SchnorrMultikey.
-        const cryptosuite = new BIP340Cryptosuite(multikey);
-        // Canonicalize the update
-        const canonicalUpdate = canonicalize(update);
-        // Construct a DataIntegrityProof with the cryptosuite
-        const diProof = new BIP340DataIntegrityProof(cryptosuite);
-        // Call the verifyProof method
-        const verificationResult = diProof.verifyProof(canonicalUpdate, 'capabilityInvocation');
-        // If the result is not verified, throw INVALID_DID_UPDATE error
-        if (!verificationResult.verified) {
-            throw new ResolveError('Invalid update: proof not verified', INVALID_DID_UPDATE, verificationResult);
+        const vm = Appendix.verificationMethodOfEntry(currentDocument, entry);
+        if (vm === undefined) {
+            throw new ResolveError('Invalid update: verificationMethod is not found in the verificationMethod of the current document', INVALID_DID_UPDATE, { verificationMethodId });
+        }
+        // Spec "Check update.proof": the proof time window against the block of the signal.
+        Resolver.checkProofWindow(proof, block);
+        // Verify the proof with the public key that the verification method publishes. The
+        // multikey names the method by its absolute DID URL, as the proof does. An error of the
+        // multikey or the cryptosuite (a key that does not decode, a proof value that does not
+        // decode, a created value the suite rejects) is an invalid update.
+        let verified;
+        try {
+            const multikey = SchnorrMultikey.fromVerificationMethod({
+                ...vm, id: Appendix.absoluteDidUrl(vm.id, currentDocument.id) ?? vm.id
+            });
+            const diProof = new BIP340DataIntegrityProof(new BIP340Cryptosuite(multikey));
+            verified = diProof.verifyProof(canonicalize(update), 'capabilityInvocation').verified;
+        }
+        catch (error) {
+            throw new ResolveError(`Invalid update: proof verification failed: ${errorCause(error).message}`, INVALID_DID_UPDATE, { verificationMethodId, cause: errorCause(error) });
+        }
+        if (!verified) {
+            throw new ResolveError('Invalid update: proof not verified', INVALID_DID_UPDATE, { verificationMethodId });
+        }
+        // Spec "Apply update": apply update.patch strictly. The first operation that fails,
+        // including a failed test, fails the whole patch.
+        let updatedDocument;
+        try {
+            updatedDocument = JSONPatch.apply(currentDocument, update.patch, { strict: true });
+        }
+        catch (error) {
+            throw new ResolveError(`Invalid update: ${errorCause(error).message}`, INVALID_DID_UPDATE, { cause: errorCause(error) });
+        }
+        // Spec "Apply update": the patched document keeps the DID as its id and conforms to
+        // DID Core v1.1.
+        if (updatedDocument?.id !== currentDocument.id) {
+            throw new ResolveError(`Invalid update: the patch changes the document id (from "${currentDocument.id}" to "${String(updatedDocument?.id)}")`, INVALID_DID_UPDATE, { sourceId: currentDocument.id, targetId: updatedDocument?.id });
         }
-        // Apply the update.patch to the currentDocument to get the updatedDocument.
-        const updatedDocument = JSONPatch.apply(currentDocument, update.patch);
-        // Verify that updatedDocument is conformant to DID Core v1.1.
-        DidDocument.validate(updatedDocument);
-        // Canonicalize and hash the updatedDocument to get the currentDocumentHash (raw bytes).
-        const currentDocumentHash = canonicalHashBytes(updatedDocument);
-        // Prepare the update targetHash for comparison with currentDocumentHash.
-        const updateTargetHash = decodeHash(update.targetHash);
-        // Make sure the update.targetHash equals currentDocumentHash.
-        if (!equalBytes(updateTargetHash, currentDocumentHash)) {
-            // If they do not match, throw INVALID_DID_UPDATE error.
-            throw new ResolveError(`Invalid update: update.targetHash !== currentDocumentHash`, INVALID_DID_UPDATE, { updateTargetHash, currentDocumentHash });
+        try {
+            DidDocument.validate(updatedDocument);
+        }
+        catch (error) {
+            throw new ResolveError(`Invalid update: the patched document does not conform to DID Core: ${errorCause(error).message}`, INVALID_DID_UPDATE, { cause: errorCause(error) });
+        }
+        // Canonicalize and hash the updatedDocument (raw bytes).
+        const updatedDocumentHash = canonicalHashBytes(updatedDocument);
+        // Prepare the update targetHash for comparison with updatedDocumentHash.
+        const updateTargetHash = Resolver.decodeUpdateHash(update.targetHash, 'targetHash');
+        // Make sure the update.targetHash equals updatedDocumentHash.
+        if (!equalBytes(updateTargetHash, updatedDocumentHash)) {
+            throw new ResolveError(`Invalid update: update.targetHash !== updatedDocumentHash`, INVALID_DID_UPDATE, { updateTargetHash, updatedDocumentHash });
         }
         //  Return final updatedDocument.
         return updatedDocument;
@@ -585,66 +619,118 @@ export class Resolver {
                     if (allNeeds.length > 0) {
                         return { status: 'action-required', needs: allNeeds };
                     }
-                    this.#phase = ResolverPhase.ApplyUpdates;
+                    this.#phase = ResolverPhase.ProcessUpdate;
                     continue;
                 }
-                // Phase: ApplyUpdates
-                // Apply collected updates, then check for new beacon services (multi-round).
-                case ResolverPhase.ApplyUpdates: {
-                    if (this.#unsortedUpdates.length > 0) {
-                        // Apply this round's updates, continuing the resolution-wide version
-                        // counter and update-hash history rather than restarting them. Without
-                        // this carry, a linear history split across discovery rounds would be
-                        // rejected at round two as late publishing.
-                        this.#resolvedResponse = Resolver.updates(this.#currentDocument, this.#unsortedUpdates, this.#versionTime, this.#versionId, { currentVersionId: this.#currentVersionId, updateHashHistory: this.#updateHashHistory });
-                        // updates() reports the version it reached via metadata.versionId; carry
-                        // it forward so the next round continues the monotonic sequence.
-                        this.#currentVersionId = Number(this.#resolvedResponse.metadata.versionId);
-                        this.#currentDocument = this.#resolvedResponse.didDocument;
-                        this.#unsortedUpdates = [];
-                        // Check for new beacon services added by updates (multi-round discovery)
-                        const beaconServices = BeaconUtils.getBeaconServices(this.#currentDocument);
-                        const hasNewServices = beaconServices.some(service => {
-                            const address = BeaconUtils.parseBitcoinAddress(service.serviceEndpoint);
-                            return !this.#requestCache.has(address);
+                // Phase: ProcessUpdate
+                // Spec "Process Next Update": one tuple per step. The phase repeats until
+                // the document resolves, or until an applied update adds a beacon address
+                // that the resolver did not scan (then the pass returns to BeaconDiscovery).
+                case ResolverPhase.ProcessUpdate: {
+                    const document = this.#currentDocument;
+                    // Step 1: the requested version is reached. The test runs before Apply,
+                    // so version 1 is reachable.
+                    if (this.#versionId !== undefined && this.#currentVersionId === this.#versionId) {
+                        this.#phase = ResolverPhase.Complete;
+                        continue;
+                    }
+                    // Step 2: no tuple is left, or the document is deactivated. A requested
+                    // version that the history does not reach is NOT_FOUND.
+                    if (this.#unsortedUpdates.length === 0 || document.deactivated) {
+                        if (this.#versionId !== undefined) {
+                            throw new ResolveError(`Version ${this.#versionId} of the DID does not exist: the history `
+                                + (document.deactivated
+                                    ? `ends with the deactivation at version ${this.#currentVersionId}.`
+                                    : `ends at version ${this.#currentVersionId}.`), NOT_FOUND, { versionId: this.#versionId, currentVersionId: this.#currentVersionId });
+                        }
+                        this.#phase = ResolverPhase.Complete;
+                        continue;
+                    }
+                    // Step 3: sort the tuples by targetVersionId (ascending), then by block
+                    // height, and remove the first one. The sort runs on every step because
+                    // a scan between two steps can add a tuple with a lower version.
+                    this.#unsortedUpdates.sort(([upd0, blk0], [upd1, blk1]) => upd0.targetVersionId - upd1.targetVersionId || blk0.height - blk1.height);
+                    const [update, block] = this.#unsortedUpdates.shift();
+                    // Check targetVersionId, first arm: update.targetVersionId <= currentVersionId
+                    // re-announces an applied version. Confirm that it is a true duplicate, then
+                    // skip it. A duplicate does not advance the version counter, does not append
+                    // to the history (the slot already holds the applied update, ADR 067), and
+                    // does not stamp the metadata: confirmations refers to the block of the most
+                    // recently applied unique update. The branch runs before the versionTime
+                    // test (ADR 068): a re-announcement mined after versionTime can neither end
+                    // the resolution early nor dodge late-publishing detection.
+                    if (update.targetVersionId <= this.#currentVersionId) {
+                        Resolver.confirmDuplicate(update, this.#updateHashHistory);
+                        continue;
+                    }
+                    // Step 4: the versionTime stop. The block mediantime of the tuple is after
+                    // versionTime: resolve the current document. The boundary is inclusive, so a
+                    // tuple whose mediantime equals versionTime applies. The stopped tuple stamps
+                    // nothing: the metadata reports the last applied update.
+                    if (this.#versionTime !== undefined && block.mediantime * 1000 > this.#versionTime) {
+                        this.#phase = ResolverPhase.Complete;
+                        continue;
+                    }
+                    // Check targetVersionId, third arm: a version was skipped, so raise LATE_PUBLISHING.
+                    if (update.targetVersionId !== this.#currentVersionId + 1) {
+                        throw new ResolveError(`Version Id Mismatch: targetVersionId cannot be > currentVersionId + 1`, LATE_PUBLISHING_ERROR, {
+                            targetVersionId: update.targetVersionId,
+                            currentVersionId: this.#currentVersionId + 1
                         });
-                        if (hasNewServices) {
-                            // Discovery is unbounded by default: termination is guaranteed by
-                            // address de-duplication (#requestCache), so a well-formed DID
-                            // resolves in however many rounds its history requires. An opt-in
-                            // maxDiscoveryRounds lets a caller bound the work as a resource
-                            // guard. Exceeding it is a limit the caller imposed, not a malformed
-                            // document, so it surfaces as INTERNAL_ERROR, not INVALID_DID_DOCUMENT.
-                            if (++this.#discoveryRounds > this.#maxDiscoveryRounds) {
-                                throw new ResolveError(`Exceeded the configured maximum of ${this.#maxDiscoveryRounds} beacon-discovery `
-                                    + 'rounds. Raise or remove ResolutionOptions.maxDiscoveryRounds to resolve this DID.', INTERNAL_ERROR, { maxDiscoveryRounds: this.#maxDiscoveryRounds, discoveryRounds: this.#discoveryRounds });
-                            }
-                            // Loop back to discover signals for new beacon services
-                            this.#phase = ResolverPhase.BeaconDiscovery;
-                            continue;
+                    }
+                    // Second arm: update.targetVersionId == currentVersionId + 1. Apply the update,
+                    // append the unsigned update hash to the history, increment the version.
+                    this.#currentDocument = Resolver.applyUpdate(document, update, block);
+                    const unsignedUpdate = JSONUtils.deleteKeys(update, ['proof']);
+                    this.#updateHashHistory.push(canonicalHashBytes(unsignedUpdate));
+                    this.#currentVersionId++;
+                    // Step 5: block_confirmations, and the header time as `updated`. On the apply
+                    // path only: the stop above and the duplicate branch stamp nothing.
+                    this.#blockConfirmations = block.confirmations;
+                    this.#updated = DateUtils.toISOStringNonFractional(DateUtils.blocktimeToTimestamp(block.time));
+                    // The applied update can add a beacon service. "Find Beacon Signals" runs at
+                    // the top of every pass for the addresses that are not scanned yet, so the
+                    // pass returns to BeaconDiscovery before the next tuple. Discovery is
+                    // unbounded by default: termination is guaranteed by address
+                    // de-duplication (#requestCache). An opt-in maxDiscoveryRounds lets a caller
+                    // bound the work as a resource guard. Exceeding it is a limit the caller
+                    // imposed, not a malformed document, so it surfaces as INTERNAL_ERROR.
+                    if (this.#hasUnscannedBeacons()) {
+                        if (++this.#discoveryRounds > this.#maxDiscoveryRounds) {
+                            throw new ResolveError(`Exceeded the configured maximum of ${this.#maxDiscoveryRounds} beacon-discovery `
+                                + 'rounds. Raise or remove ResolutionOptions.maxDiscoveryRounds to resolve this DID.', INTERNAL_ERROR, { maxDiscoveryRounds: this.#maxDiscoveryRounds, discoveryRounds: this.#discoveryRounds });
                         }
+                        this.#phase = ResolverPhase.BeaconDiscovery;
                     }
-                    this.#phase = ResolverPhase.Complete;
                     continue;
                 }
                 // Phase: Complete
+                // The document metadata of the specification: versionId is current_version_id,
+                // confirmations is block_confirmations (0 when no update applied), deactivated
+                // is the flag of the document. `updated` is present after the first apply.
                 case ResolverPhase.Complete: {
-                    return {
-                        status: 'resolved',
-                        // No update applied: confirmations is 0 per the specification.
-                        result: this.#resolvedResponse ?? {
-                            didDocument: this.#currentDocument,
-                            metadata: {
-                                versionId: this.#versionId ?? '1',
-                                confirmations: 0,
-                                deactivated: this.#currentDocument.deactivated || false
-                            }
+                    this.#resolvedResponse ??= {
+                        didDocument: this.#currentDocument,
+                        metadata: {
+                            versionId: `${this.#currentVersionId}`,
+                            confirmations: this.#blockConfirmations,
+                            ...(this.#updated !== undefined ? { updated: this.#updated } : {}),
+                            deactivated: this.#currentDocument.deactivated || false
                         }
                     };
+                    return { status: 'resolved', result: this.#resolvedResponse };
                 }
             }
         }
     }
+    /**
+     * True if the current document carries a beacon service whose address the resolver
+     * did not request signals for. "Find Beacon Signals" scans such an address on the
+     * next pass.
+     */
+    #hasUnscannedBeacons() {
+        return BeaconUtils.getBeaconServices(this.#currentDocument).some(service => !this.#requestCache.has(BeaconUtils.parseBitcoinAddress(service.serviceEndpoint)));
+    }
     /**
      * Return the signals of one beacon service that resolution may process: the
      * signals with at least `#minConf` confirmations. The specification removes a
@@ -653,10 +739,11 @@ export class Resolver {
      * integer confirmation count is excluded too: that is a mempool transaction
      * from a driver that did not skip it.
      *
-     * An eligible signal must carry a finite block height and block time. A
-     * signal that passes the count but lacks them is malformed. It fails fast
-     * here with a typed error, in the style of the {@link provide} guards, and
-     * not later with an invalid date inside {@link updates}.
+     * An eligible signal must carry a finite block height, block time, and block
+     * median time past. A signal that passes the count but lacks them is
+     * malformed. It fails fast here with a typed error, in the style of the
+     * {@link provide} guards, and not later with an invalid date or a false
+     * `versionTime` comparison in the ProcessUpdate phase.
      * @param {Array<BeaconSignal>} signals The signals the caller provided for one service.
      * @returns {Array<BeaconSignal>} The signals at or above the threshold, in the given order.
      * @throws {ResolveError} `INVALID_DID_UPDATE` for an eligible signal with no valid block metadata.
@@ -669,9 +756,15 @@ export class Resolver {
             if (!Number.isInteger(confirmations) || confirmations < this.#minConf) {
                 continue;
             }
-            if (!Number.isFinite(block?.height) || !Number.isFinite(block?.time)) {
+            if (!Number.isFinite(block?.height) || !Number.isFinite(block?.time) || !Number.isFinite(block?.mediantime)) {
                 throw new ResolveError(`Beacon signal ${signal.signalBytes} has ${confirmations} confirmations `
-                    + 'but no valid block height or block time.', INVALID_DID_UPDATE, { signalBytes: signal.signalBytes, confirmations, height: block?.height, time: block?.time });
+                    + 'but no valid block height, block time, or block mediantime.', INVALID_DID_UPDATE, {
+                    signalBytes: signal.signalBytes,
+                    confirmations,
+                    height: block?.height,
+                    time: block?.time,
+                    mediantime: block?.mediantime
+                });
             }
             eligible.push(signal);
         }