@did-btcr2/method 0.61.0 → 0.63.0

package/dist/cjs/index.js

@@ -1370,7 +1370,18 @@ var Identifier = class _Identifier {
     if (encoded !== encoded.toLowerCase()) {
       throw new import_common8.IdentifierError(`Invalid method-specific id (must be lowercase): ${identifier}`, import_common8.INVALID_DID, { identifier });
     }
-    const { prefix: hrp, bytes: dataBytes } = import_base.bech32m.decodeToBytes(encoded);
+    let hrp;
+    let dataBytes;
+    try {
+      ({ prefix: hrp, bytes: dataBytes } = import_base.bech32m.decodeToBytes(encoded));
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new import_common8.IdentifierError(
+        `Invalid method-specific id (Bech32m decoding failed: ${reason}): ${identifier}`,
+        import_common8.INVALID_DID,
+        { identifier, reason }
+      );
+    }
     if (!["x", "k"].includes(hrp)) {
       throw new import_common8.IdentifierError(`Invalid hrp: ${hrp}`, import_common8.INVALID_DID, { identifier });
     }
@@ -1803,6 +1814,7 @@ var BeaconSignalDiscovery = class _BeaconSignalDiscovery {
   static async indexer(beaconServices, bitcoin) {
     const beaconServiceSignals = /* @__PURE__ */ new Map();
     const currentBlockCount = await bitcoin.rest.block.count();
+    const mediantimes = /* @__PURE__ */ new Map();
     for (const beaconService of beaconServices) {
       beaconServiceSignals.set(beaconService, []);
       const beaconAddress = BeaconUtils.parseBitcoinAddress(beaconService.serviceEndpoint);
@@ -1827,19 +1839,49 @@ var BeaconSignalDiscovery = class _BeaconSignalDiscovery {
           continue;
         }
         const confirmations = currentBlockCount - status.block_height + 1;
+        const mediantime = await _BeaconSignalDiscovery.mediantime(status.block_hash, bitcoin, mediantimes);
         beaconServiceSignals.get(beaconService)?.push({
           tx: beaconSignal,
           signalBytes: updateHash,
           blockMetadata: {
             confirmations,
             height: status.block_height,
-            time: status.block_time
+            time: status.block_time,
+            mediantime
           }
         });
       }
     }
     return beaconServiceSignals;
   }
+  /**
+   * Return the median time past of a block, from the per-run cache or from the
+   * Esplora block record (`GET /block/:hash`). The specification compares
+   * `versionTime` with the block `mediantime`, and the address listing does not
+   * carry it. One block record serves every signal in that block.
+   * @param {string} blockhash The hash of the block that contains a signal.
+   * @param {BitcoinConnection} bitcoin Bitcoin network connection to use for REST calls.
+   * @param {Map<string, number>} cache The median time past values fetched so far, keyed by block hash.
+   * @returns {Promise<number>} The median time past of the block, in Unix seconds.
+   * @throws {ResolveError} `INTERNAL_ERROR` if the backend returns no block record or no `mediantime` for the hash.
+   */
+  static async mediantime(blockhash, bitcoin, cache) {
+    const cached = cache.get(blockhash);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const block = await bitcoin.rest.block.get({ blockhash });
+    const mediantime = block?.mediantime;
+    if (typeof mediantime !== "number" || !Number.isFinite(mediantime)) {
+      throw new import_common10.ResolveError(
+        `Block ${blockhash} has no mediantime in the block record of the Bitcoin REST backend.`,
+        import_common10.INTERNAL_ERROR,
+        { blockhash, block }
+      );
+    }
+    cache.set(blockhash, mediantime);
+    return mediantime;
+  }
   /**
    * Traverse the full blockchain from genesis to chain top looking for beacon signals.
    * @param {Array<BeaconService>} beaconServices Array of BeaconService objects to search for signals.
@@ -1909,6 +1951,7 @@ var BeaconSignalDiscovery = class _BeaconSignalDiscovery {
             blockMetadata: {
               height: block.height,
               time: block.time,
+              mediantime: block.mediantime,
               confirmations: block.confirmations
             }
           });
@@ -2428,17 +2471,46 @@ function isSMTProof(value) {
 function validateMinConf(value) {
   if (value === void 0) 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 import_common13.ResolveError(
-    `Invalid resolution option minConf: expected a positive integer (minimum 1), got ${shown}.`,
+    `Invalid resolution option minConf: expected a positive integer (minimum 1), got ${shown(value)}.`,
     import_common13.INVALID_OPTIONS,
     { minConf: value }
   );
 }
+function shown(value) {
+  return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+var ASCII_INTEGER = /^-?[0-9]+$/;
+function validateVersionId(value) {
+  if (value === void 0) return void 0;
+  if (typeof value === "string" && ASCII_INTEGER.test(value) && Number.isSafeInteger(Number(value))) {
+    return Number(value);
+  }
+  throw new import_common13.ResolveError(
+    `Invalid resolution option versionId: expected an ASCII string of an integer, got ${shown(value)}.`,
+    import_common13.INVALID_OPTIONS,
+    { versionId: value }
+  );
+}
+var UTC_XSD_DATETIME = /^-?\d{4,}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+function validateVersionTime(value) {
+  if (value === void 0) return void 0;
+  if (typeof value === "string" && UTC_XSD_DATETIME.test(value) && import_common13.DateUtils.isValidXsdDateTime(value)) {
+    const ms = Date.parse(value);
+    if (Number.isFinite(ms)) return ms;
+  }
+  throw new import_common13.ResolveError(
+    `Invalid resolution option versionTime: expected an XML Datetime in UTC without a fraction (for example "2026-07-01T00:00:00Z"), got ${shown(value)}.`,
+    import_common13.INVALID_OPTIONS,
+    { versionTime: value }
+  );
+}
 var Resolver = 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.
@@ -2449,22 +2521,28 @@ var Resolver = class _Resolver {
   #providedGenesisDocument = null;
   #beaconServicesSignals = /* @__PURE__ */ new Map();
   #processedServices = /* @__PURE__ */ new Set();
+  /** The beacon addresses the resolver requested signals for: `scanned_beacons` of the specification. */
   #requestCache = /* @__PURE__ */ 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
@@ -2489,8 +2567,15 @@ var Resolver = class _Resolver {
     this.#didComponents = didComponents;
     this.#sidecarData = sidecarData;
     this.#currentDocument = currentDocument;
-    this.#versionId = options?.versionId;
-    this.#versionTime = options?.versionTime;
+    if (options?.versionId !== void 0 && options?.versionTime !== void 0) {
+      throw new import_common13.ResolveError(
+        "Invalid resolution options: versionId and versionTime are mutually exclusive. Pass one of them.",
+        import_common13.INVALID_OPTIONS,
+        { versionId: options.versionId, versionTime: options.versionTime }
+      );
+    }
+    this.#versionId = validateVersionId(options?.versionId);
+    this.#versionTime = validateVersionTime(options?.versionTime);
     const rounds = options?.maxDiscoveryRounds;
     this.#maxDiscoveryRounds = typeof rounds === "number" && rounds > 0 ? rounds : Infinity;
     this.#minConf = validateMinConf(options?.minConf);
@@ -2530,14 +2615,14 @@ var Resolver = class _Resolver {
    * @param {DidComponents} didComponents BTCR2 DID components used to resolve the DID Document
    * @param {object} genesisDocument The genesis document for resolving the DID Document.
    * @returns {DidDocument} The resolved DID Document object
-   * @throws {ResolveError} InvalidDidDocument if not conformant to DID Core v1.1
+   * @throws {ResolveError} `INVALID_DID` if the hash of the genesis document is not the genesis bytes of the identifier
    */
   static external(didComponents, genesisDocument) {
     const genesisDocumentHash = (0, import_common13.canonicalHashBytes)(genesisDocument);
     if (!(0, import_utils7.equalBytes)(didComponents.genesisBytes, genesisDocumentHash)) {
       throw new import_common13.ResolveError(
         `Initial document mismatch: genesisBytes !== genesisDocumentHash`,
-        import_common13.INVALID_DID_DOCUMENT,
+        import_common13.INVALID_DID,
         {
           genesisBytes: (0, import_common13.encode)(didComponents.genesisBytes, "hex"),
           genesisDocumentHash: (0, import_common13.encode)(genesisDocumentHash, "hex")
@@ -2574,89 +2659,7 @@ var Resolver = 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: [] }) {
-    let currentVersionId = resolutionState.currentVersionId;
-    const updateHashHistory = resolutionState.updateHashHistory;
-    const updates = unsortedUpdates.sort(
-      ([upd0, blk0], [upd1, blk1]) => upd0.targetVersionId - upd1.targetVersionId || blk0.height - blk1.height
-    );
-    const response = {
-      didDocument: currentDocument,
-      metadata: {
-        versionId: `${currentVersionId}`,
-        confirmations: 0,
-        updated: "",
-        deactivated: currentDocument.deactivated || false
-      }
-    };
-    for (const [update, block] of updates) {
-      const currentDocumentHash = (0, import_common13.canonicalHashBytes)(response.didDocument);
-      const blocktime = import_common13.DateUtils.blocktimeToTimestamp(block.time);
-      response.metadata.updated = import_common13.DateUtils.toISOStringNonFractional(blocktime);
-      response.metadata.confirmations = block.confirmations;
-      if (update.targetVersionId <= currentVersionId) {
-        this.confirmDuplicate(update, updateHashHistory);
-        continue;
-      }
-      if (versionTime) {
-        if (blocktime > import_common13.DateUtils.dateStringToTimestamp(versionTime)) {
-          return response;
-        }
-      }
-      if (update.targetVersionId === currentVersionId + 1) {
-        const sourceHashBytes = (0, import_common13.decode)(update.sourceHash, "base64urlnopad");
-        if (!(0, import_utils7.equalBytes)(sourceHashBytes, currentDocumentHash)) {
-          throw new import_common13.ResolveError(
-            `Hash mismatch: update.sourceHash !== currentDocumentHash`,
-            import_common13.INVALID_DID_UPDATE,
-            {
-              sourceHash: update.sourceHash,
-              currentDocumentHash: (0, import_common13.encode)(currentDocumentHash, "hex")
-            }
-          );
-        }
-        response.didDocument = this.applyUpdate(response.didDocument, update);
-        const unsignedUpdate = import_common13.JSONUtils.deleteKeys(update, ["proof"]);
-        updateHashHistory.push((0, import_common13.canonicalHashBytes)(unsignedUpdate));
-      } else {
-        throw new import_common13.ResolveError(
-          `Version Id Mismatch: targetVersionId cannot be > currentVersionId + 1`,
-          import_common13.LATE_PUBLISHING_ERROR,
-          {
-            targetVersionId: update.targetVersionId,
-            currentVersionId: currentVersionId + 1
-          }
-        );
-      }
-      currentVersionId++;
-      response.metadata.versionId = `${currentVersionId}`;
-      const versionIdNumber = Number(versionId);
-      if (!isNaN(versionIdNumber) && versionIdNumber <= currentVersionId) {
-        return response;
-      }
-      if (response.didDocument.deactivated) {
-        response.metadata.deactivated = response.didDocument.deactivated;
-        return response;
-      }
-    }
-    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.
@@ -2695,14 +2698,26 @@ var Resolver = class _Resolver {
     }
   }
   /**
-   * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#apply-update | 7.2.f.3 Apply Update}
+   * 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}.
    * @param {DidDocument} currentDocument The current DID Document to apply the update to.
    * @param {SignedBTCR2Update} update The BTCR2 Signed Update to apply.
    * @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) {
+    const currentDocumentHash = (0, import_common13.canonicalHashBytes)(currentDocument);
+    const sourceHashBytes = (0, import_common13.decode)(update.sourceHash, "base64urlnopad");
+    if (!(0, import_utils7.equalBytes)(sourceHashBytes, currentDocumentHash)) {
+      throw new import_common13.ResolveError(
+        `Hash mismatch: update.sourceHash !== currentDocumentHash`,
+        import_common13.INVALID_DID_UPDATE,
+        {
+          sourceHash: update.sourceHash,
+          currentDocumentHash: (0, import_common13.encode)(currentDocumentHash, "hex")
+        }
+      );
+    }
     if (!isBtcr2UpdateContext(update["@context"])) {
       throw new import_common13.ResolveError(
         "Invalid update: @context is not the array the specification pins for a BTCR2 Update",
@@ -2763,13 +2778,13 @@ var Resolver = class _Resolver {
     }
     const updatedDocument = import_common13.JSONPatch.apply(currentDocument, update.patch);
     DidDocument.validate(updatedDocument);
-    const currentDocumentHash = (0, import_common13.canonicalHashBytes)(updatedDocument);
+    const updatedDocumentHash = (0, import_common13.canonicalHashBytes)(updatedDocument);
     const updateTargetHash = (0, import_common13.decode)(update.targetHash);
-    if (!(0, import_utils7.equalBytes)(updateTargetHash, currentDocumentHash)) {
+    if (!(0, import_utils7.equalBytes)(updateTargetHash, updatedDocumentHash)) {
       throw new import_common13.ResolveError(
-        `Invalid update: update.targetHash !== currentDocumentHash`,
+        `Invalid update: update.targetHash !== updatedDocumentHash`,
         import_common13.INVALID_DID_UPDATE,
-        { updateTargetHash, currentDocumentHash }
+        { updateTargetHash, updatedDocumentHash }
       );
     }
     return updatedDocument;
@@ -2843,59 +2858,99 @@ var Resolver = class _Resolver {
           if (allNeeds.length > 0) {
             return { status: "action-required", needs: allNeeds };
           }
-          this.#phase = "ApplyUpdates" /* ApplyUpdates */;
+          this.#phase = "ProcessUpdate" /* ProcessUpdate */;
           continue;
         }
-        // Phase: ApplyUpdates
-        // Apply collected updates, then check for new beacon services (multi-round).
-        case "ApplyUpdates" /* ApplyUpdates */: {
-          if (this.#unsortedUpdates.length > 0) {
-            this.#resolvedResponse = _Resolver.updates(
-              this.#currentDocument,
-              this.#unsortedUpdates,
-              this.#versionTime,
-              this.#versionId,
-              { currentVersionId: this.#currentVersionId, updateHashHistory: this.#updateHashHistory }
-            );
-            this.#currentVersionId = Number(this.#resolvedResponse.metadata.versionId);
-            this.#currentDocument = this.#resolvedResponse.didDocument;
-            this.#unsortedUpdates = [];
-            const beaconServices = BeaconUtils.getBeaconServices(this.#currentDocument);
-            const hasNewServices = beaconServices.some((service) => {
-              const address = BeaconUtils.parseBitcoinAddress(service.serviceEndpoint);
-              return !this.#requestCache.has(address);
-            });
-            if (hasNewServices) {
-              if (++this.#discoveryRounds > this.#maxDiscoveryRounds) {
-                throw new import_common13.ResolveError(
-                  `Exceeded the configured maximum of ${this.#maxDiscoveryRounds} beacon-discovery rounds. Raise or remove ResolutionOptions.maxDiscoveryRounds to resolve this DID.`,
-                  import_common13.INTERNAL_ERROR,
-                  { maxDiscoveryRounds: this.#maxDiscoveryRounds, discoveryRounds: this.#discoveryRounds }
-                );
+        // 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 "ProcessUpdate" /* ProcessUpdate */: {
+          const document = this.#currentDocument;
+          if (this.#versionId !== void 0 && this.#currentVersionId === this.#versionId) {
+            this.#phase = "Complete" /* Complete */;
+            continue;
+          }
+          if (this.#unsortedUpdates.length === 0 || document.deactivated) {
+            if (this.#versionId !== void 0) {
+              throw new import_common13.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}.`),
+                import_common13.NOT_FOUND,
+                { versionId: this.#versionId, currentVersionId: this.#currentVersionId }
+              );
+            }
+            this.#phase = "Complete" /* Complete */;
+            continue;
+          }
+          this.#unsortedUpdates.sort(
+            ([upd0, blk0], [upd1, blk1]) => upd0.targetVersionId - upd1.targetVersionId || blk0.height - blk1.height
+          );
+          const [update, block] = this.#unsortedUpdates.shift();
+          if (update.targetVersionId <= this.#currentVersionId) {
+            _Resolver.confirmDuplicate(update, this.#updateHashHistory);
+            continue;
+          }
+          if (this.#versionTime !== void 0 && block.mediantime * 1e3 > this.#versionTime) {
+            this.#phase = "Complete" /* Complete */;
+            continue;
+          }
+          if (update.targetVersionId !== this.#currentVersionId + 1) {
+            throw new import_common13.ResolveError(
+              `Version Id Mismatch: targetVersionId cannot be > currentVersionId + 1`,
+              import_common13.LATE_PUBLISHING_ERROR,
+              {
+                targetVersionId: update.targetVersionId,
+                currentVersionId: this.#currentVersionId + 1
               }
-              this.#phase = "BeaconDiscovery" /* BeaconDiscovery */;
-              continue;
+            );
+          }
+          this.#currentDocument = _Resolver.applyUpdate(document, update);
+          const unsignedUpdate = import_common13.JSONUtils.deleteKeys(update, ["proof"]);
+          this.#updateHashHistory.push((0, import_common13.canonicalHashBytes)(unsignedUpdate));
+          this.#currentVersionId++;
+          this.#blockConfirmations = block.confirmations;
+          this.#updated = import_common13.DateUtils.toISOStringNonFractional(import_common13.DateUtils.blocktimeToTimestamp(block.time));
+          if (this.#hasUnscannedBeacons()) {
+            if (++this.#discoveryRounds > this.#maxDiscoveryRounds) {
+              throw new import_common13.ResolveError(
+                `Exceeded the configured maximum of ${this.#maxDiscoveryRounds} beacon-discovery rounds. Raise or remove ResolutionOptions.maxDiscoveryRounds to resolve this DID.`,
+                import_common13.INTERNAL_ERROR,
+                { maxDiscoveryRounds: this.#maxDiscoveryRounds, discoveryRounds: this.#discoveryRounds }
+              );
             }
+            this.#phase = "BeaconDiscovery" /* BeaconDiscovery */;
           }
-          this.#phase = "Complete" /* 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 "Complete" /* Complete */: {
-          return {
-            status: "resolved",
-            result: this.#resolvedResponse ?? {
-              didDocument: this.#currentDocument,
-              metadata: {
-                versionId: this.#versionId ?? "1",
-                deactivated: this.#currentDocument.deactivated || false
-              }
+          this.#resolvedResponse ??= {
+            didDocument: this.#currentDocument,
+            metadata: {
+              versionId: `${this.#currentVersionId}`,
+              confirmations: this.#blockConfirmations,
+              ...this.#updated !== void 0 ? { 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
@@ -2904,10 +2959,11 @@ var Resolver = 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.
@@ -2920,11 +2976,17 @@ var Resolver = 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 import_common13.ResolveError(
-          `Beacon signal ${signal.signalBytes} has ${confirmations} confirmations but no valid block height or block time.`,
+          `Beacon signal ${signal.signalBytes} has ${confirmations} confirmations but no valid block height, block time, or block mediantime.`,
           import_common13.INVALID_DID_UPDATE,
-          { signalBytes: signal.signalBytes, confirmations, height: block?.height, time: block?.time }
+          {
+            signalBytes: signal.signalBytes,
+            confirmations,
+            height: block?.height,
+            time: block?.time,
+            mediantime: block?.mediantime
+          }
         );
       }
       eligible.push(signal);

package/dist/esm/core/beacon/signal-discovery.js

@@ -1,5 +1,5 @@
 import { GENESIS_TX_ID, TXIN_WITNESS_COINBASE } from '@did-btcr2/bitcoin';
-import { ResolveError } from '@did-btcr2/common';
+import { INTERNAL_ERROR, ResolveError } from '@did-btcr2/common';
 import { BeaconUtils } from './utils.js';
 /**
  * The serialized form of a Beacon Signal output: `OP_RETURN` (`0x6a`), the 32-byte push
@@ -107,6 +107,9 @@ export class BeaconSignalDiscovery {
         const beaconServiceSignals = new Map();
         // Fetch the current block count once before the loop
         const currentBlockCount = await bitcoin.rest.block.count();
+        // The median time past of each block that holds a signal, keyed by block hash.
+        // One fetch per distinct block for the whole run.
+        const mediantimes = new Map();
         // Iterate over each beacon
         for (const beaconService of beaconServices) {
             beaconServiceSignals.set(beaconService, []);
@@ -156,6 +159,10 @@ export class BeaconSignalDiscovery {
                 }
                 // Use the pre-fetched block count instead of calling per-signal
                 const confirmations = currentBlockCount - status.block_height + 1;
+                // The address listing carries the header time of the block, not its median
+                // time past. The resolver compares `versionTime` with the median time past,
+                // so read it from the block record.
+                const mediantime = await BeaconSignalDiscovery.mediantime(status.block_hash, bitcoin, mediantimes);
                 // Push the beacon signal object to the signals array for the beacon service
                 beaconServiceSignals.get(beaconService)?.push({
                     tx: beaconSignal,
@@ -164,12 +171,37 @@ export class BeaconSignalDiscovery {
                         confirmations,
                         height: status.block_height,
                         time: status.block_time,
+                        mediantime,
                     }
                 });
             }
         }
         return beaconServiceSignals;
     }
+    /**
+     * Return the median time past of a block, from the per-run cache or from the
+     * Esplora block record (`GET /block/:hash`). The specification compares
+     * `versionTime` with the block `mediantime`, and the address listing does not
+     * carry it. One block record serves every signal in that block.
+     * @param {string} blockhash The hash of the block that contains a signal.
+     * @param {BitcoinConnection} bitcoin Bitcoin network connection to use for REST calls.
+     * @param {Map<string, number>} cache The median time past values fetched so far, keyed by block hash.
+     * @returns {Promise<number>} The median time past of the block, in Unix seconds.
+     * @throws {ResolveError} `INTERNAL_ERROR` if the backend returns no block record or no `mediantime` for the hash.
+     */
+    static async mediantime(blockhash, bitcoin, cache) {
+        const cached = cache.get(blockhash);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const block = await bitcoin.rest.block.get({ blockhash });
+        const mediantime = block?.mediantime;
+        if (typeof mediantime !== 'number' || !Number.isFinite(mediantime)) {
+            throw new ResolveError(`Block ${blockhash} has no mediantime in the block record of the Bitcoin REST backend.`, INTERNAL_ERROR, { blockhash, block });
+        }
+        cache.set(blockhash, mediantime);
+        return mediantime;
+    }
     /**
      * Traverse the full blockchain from genesis to chain top looking for beacon signals.
      * @param {Array<BeaconService>} beaconServices Array of BeaconService objects to search for signals.
@@ -290,6 +322,7 @@ export class BeaconSignalDiscovery {
                         blockMetadata: {
                             height: block.height,
                             time: block.time,
+                            mediantime: block.mediantime,
                             confirmations: block.confirmations
                         }
                     });

package/dist/esm/core/beacon/signal-discovery.js.map

@@ -1 +1 @@
-{"version":3,"file":"signal-discovery.js","sourceRoot":"","sources":["../../../../src/core/beacon/signal-discovery.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"signal-discovery.js","sourceRoot":"","sources":["../../../../src/core/beacon/signal-discovery.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/identifier.js

@@ -111,8 +111,18 @@ export class Identifier {
         if (encoded !== encoded.toLowerCase()) {
             throw new IdentifierError(`Invalid method-specific id (must be lowercase): ${identifier}`, INVALID_DID, { identifier });
         }
-        // 7. Bech32m-decode the id into its hrp and dataBytes.
-        const { prefix: hrp, bytes: dataBytes } = bech32m.decodeToBytes(encoded);
+        // 7. Bech32m-decode the id into its hrp and dataBytes. The decoder throws its own Error
+        //    for a bad character, a bad length, a bad checksum, or bad padding. The specification
+        //    maps every decoding failure to INVALID_DID.
+        let hrp;
+        let dataBytes;
+        try {
+            ({ prefix: hrp, bytes: dataBytes } = bech32m.decodeToBytes(encoded));
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new IdentifierError(`Invalid method-specific id (Bech32m decoding failed: ${reason}): ${identifier}`, INVALID_DID, { identifier, reason });
+        }
         // 8. The hrp MUST be "k" (KEY) or "x" (EXTERNAL).
         if (!['x', 'k'].includes(hrp)) {
             throw new IdentifierError(`Invalid hrp: ${hrp}`, INVALID_DID, { identifier });