@did-btcr2/method 0.52.0 → 0.54.0

package/src/core/resolver.ts

@@ -126,13 +126,18 @@ function isCASAnnouncement(value: unknown): value is CASAnnouncement {
   return isRecord(value) && Object.values(value).every(v => typeof v === 'string');
 }
 
-/** True if `value` has the shape of a signed BTCR2 update. */
+/**
+ * True if `value` has the shape of a signed BTCR2 update. targetVersionId must be an
+ * integer of at least 2: an update targets the version after the one it patches, and
+ * genesis is version 1, so no conformant update can target a lower version (ADR 068).
+ */
 function isSignedBTCR2Update(value: unknown): value is SignedBTCR2Update {
   if(!isRecord(value)) return false;
   return Array.isArray(value.patch)
     && typeof value.sourceHash === 'string'
     && typeof value.targetHash === 'string'
-    && typeof value.targetVersionId === 'number'
+    && Number.isInteger(value.targetVersionId)
+    && (value.targetVersionId as number) >= 2
     && isRecord(value.proof);
 }
 
@@ -411,14 +416,6 @@ export class Resolver {
       // Set confirmations to the block confirmations
       response.metadata.confirmations = block.confirmations;
 
-      // if resolutionOptions.versionTime is defined and the blocktime is more recent, return currentDocument
-      if(versionTime) {
-        // Safely convert versionTime to timestamp
-        if(blocktime > DateUtils.dateStringToTimestamp(versionTime)) {
-          return response;
-        }
-      }
-
       // 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
@@ -428,12 +425,28 @@ export class Resolver {
       // 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.
+      // 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)
@@ -501,6 +514,17 @@ export class Resolver {
    * @returns {void} Does not return a value, but throws an error if the update is not a valid duplicate.
    */
   private static confirmDuplicate(update: SignedBTCR2Update, updateHashHistory: HashBytes[]): void {
+    // A conformant update targets the version after the one it patches, so targetVersionId
+    // is an integer of at least 2 (genesis is version 1). Anything else cannot name an
+    // applied update: it is a malformed update, not a duplicate, and without this guard it
+    // would read a nonexistent history slot below and crash on the byte comparison (ADR 068).
+    if (!Number.isInteger(update.targetVersionId) || update.targetVersionId < 2) {
+      throw new ResolveError(
+        `Invalid duplicate: targetVersionId must be an integer >= 2`,
+        INVALID_DID_UPDATE, { targetVersionId: update.targetVersionId }
+      );
+    }
+
     // Create unsigned_update by removing the proof property from update.
     const { proof: _, ...unsignedUpdate } = update;
 
@@ -510,6 +534,20 @@ export class Resolver {
     // Let historicalUpdateHash equal updateHashHistory[updateHashIndex].
     const historicalUpdateHash = updateHashHistory[update.targetVersionId - 2];
 
+    // The resolver's own loop records one history entry per applied version, so this slot
+    // always exists on that path; a standalone caller, however, can pass a resolutionState
+    // whose version counter outruns its history. A duplicate that cannot be checked against
+    // an applied update is unconfirmable, which is late-publishing evidence, not a pass.
+    if (historicalUpdateHash === undefined) {
+      throw new ResolveError(
+        `Invalid duplicate: no applied update in history for targetVersionId`,
+        LATE_PUBLISHING_ERROR, {
+          targetVersionId : update.targetVersionId,
+          historyLength   : updateHashHistory.length
+        }
+      );
+    }
+
     // Check if the updateHash matches the historical hash (byte comparison)
     if (!equalBytes(historicalUpdateHash, unsignedUpdateHash)) {
       throw new ResolveError(

package/src/core/updater.ts

@@ -5,6 +5,8 @@ import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import type { Signer } from '@did-btcr2/keypair';
 import type { Btcr2DataIntegrityConfig, SignedBTCR2Update, UnsignedBTCR2Update } from './btcr2-update.js';
 import { DidDocument, type Btcr2DidDocument, type DidVerificationMethod } from '../utils/did-document.js';
+import type { BroadcastResult } from './beacon/beacon.js';
+import type { CASBroadcastOptions } from './beacon/cas-beacon.js';
 import { BeaconFactory } from './beacon/factory.js';
 import type { BeaconService } from './beacon/interfaces.js';
 
@@ -56,10 +58,15 @@ export interface FundingProof {
  * The updater needs the caller to broadcast the signed update via the beacon.
  *
  * The caller decides how: for single-party beacons, call
- * `Updater.announce(beaconService, signedUpdate, secretKey, bitcoin)` or
+ * `Updater.announce(beaconService, signedUpdate, signer, bitcoin, options?)` or
  * `BeaconFactory.establish(beaconService).broadcastSignal(...)`. For multi-party
  * aggregate beacons, hand off to the aggregation protocol.
  *
+ * Both single-party paths return a `BroadcastResult`; capture it. Beyond the txid,
+ * it carries the per-beacon-type sidecar artifacts: the CAS Announcement (CAS
+ * beacons) and the SMT inclusion proof (SMT beacons), whose embedded nonce exists
+ * nowhere else, so a discarded proof makes the signal permanently unresolvable.
+ *
  * After the broadcast succeeds, the caller calls `updater.provide(need)` (with no
  * data) to transition the updater to Complete.
  */
@@ -137,10 +144,14 @@ export interface UpdaterParams {
  *         // Check UTXOs at need.beaconAddress, fund if needed
  *         updater.provide(need);
  *         break;
- *       case 'NeedBroadcast':
- *         await Updater.announce(need.beaconService, need.signedUpdate, signer, bitcoin);
+ *       case 'NeedBroadcast': {
+ *         // Capture the BroadcastResult: broadcast.txid, plus broadcast.announcement
+ *         // (CAS beacons) and broadcast.proof (SMT beacons; must be retained, the
+ *         // proof's nonce exists nowhere else).
+ *         const broadcast = await Updater.announce(need.beaconService, need.signedUpdate, signer, bitcoin);
  *         updater.provide(need);
  *         break;
+ *       }
  *     }
  *   }
  *   state = updater.advance();
@@ -315,16 +326,21 @@ export class Updater {
    * @param {SignedBTCR2Update} update The signed update to announce.
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.
    * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
-   * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+   * @param {CASBroadcastOptions} [options] Optional broadcast configuration (fee estimator,
+   *   change address, and, for CAS beacons, a `casPublish` callback invoked before the
+   *   transaction broadcast; other beacon types ignore `casPublish`).
+   * @returns {Promise<BroadcastResult>} The broadcast artifacts: the signed update, the signal
+   *   txid, and any per-beacon-type sidecar data (CAS announcement / SMT proof).
    */
   static async announce(
     beaconService: BeaconService,
     update: SignedBTCR2Update,
     signer: Signer,
-    bitcoin: BitcoinConnection
-  ): Promise<SignedBTCR2Update> {
+    bitcoin: BitcoinConnection,
+    options?: CASBroadcastOptions
+  ): Promise<BroadcastResult> {
     const beacon = BeaconFactory.establish(beaconService);
-    return beacon.broadcastSignal(update, signer, bitcoin);
+    return beacon.broadcastSignal(update, signer, bitcoin, options);
   }
 
   // Private instance wrappers