@did-btcr2/method 0.56.0 → 0.59.0

package/src/core/beacon/cas-beacon.ts

@@ -57,9 +57,10 @@ export class CASBeacon extends SinglePartyBeacon {
   /**
    * Creates an instance of CASBeacon.
    * @param {BeaconService} service The service of the Beacon.
+   * @param {string} did The absolute did:btcr2 identifier this beacon serves.
    */
-  constructor(service: BeaconService) {
-    super({ ...service, type: 'CASBeacon' });
+  constructor(service: BeaconService, did: string) {
+    super({ ...service, type: 'CASBeacon' }, did);
   }
 
   /**
@@ -82,8 +83,8 @@ export class CASBeacon extends SinglePartyBeacon {
     const updates = new Array<[SignedBTCR2Update, BlockMetadata]>();
     const needs = new Array<DataNeed>();
 
-    // Extract the DID from the beacon service id (strip the #fragment)
-    const did = this.service.id.split('#')[0];
+    // The DID under resolution keys this beacon's announcement entry.
+    const did = this.did;
 
     for(const signal of signals) {
       // Signal bytes are hex, matches hex-keyed sidecar maps directly
@@ -160,8 +161,8 @@ export class CASBeacon extends SinglePartyBeacon {
     bitcoin: BitcoinConnection,
     options?: CASBroadcastOptions
   ): Promise<BroadcastResult> {
-    // Extract the DID from the beacon service id (strip the #fragment)
-    const did = this.service.id.split('#')[0];
+    // The DID this beacon serves keys its announcement entry.
+    const did = this.did;
 
     // Hash the signed update (base64urlnopad for the CAS Announcement entry per spec)
     const updateHash = canonicalHash(signedUpdate);

package/src/core/beacon/factory.ts

@@ -14,16 +14,18 @@ export class BeaconFactory {
   /**
    * Establish a Beacon instance based on the provided service and optional sidecar data.
    * @param {BeaconService} service The beacon service configuration.
+   * @param {string} did The absolute did:btcr2 identifier the beacon serves. Supplied
+   *   by the caller because a beacon service `id` may be a relative DID URL.
    * @returns {SinglePartyBeacon} The established Beacon instance.
    */
-  static establish(service: BeaconService): SinglePartyBeacon {
+  static establish(service: BeaconService, did: string): SinglePartyBeacon {
     switch (service.type) {
       case 'SingletonBeacon':
-        return new SingletonBeacon(service);
+        return new SingletonBeacon(service, did);
       case 'CASBeacon':
-        return new CASBeacon(service);
+        return new CASBeacon(service, did);
       case 'SMTBeacon':
-        return new SMTBeacon(service);
+        return new SMTBeacon(service, did);
       default:
         throw new MethodError('Invalid Beacon Type', 'INVALID_BEACON_ERROR', service);
     }

package/src/core/beacon/interfaces.ts

@@ -76,4 +76,4 @@ export interface BeaconSignal {
  *
  * @param announcement The CAS Announcement object (DID to update hash mapping).
  */
-export type CasPublishFn = (announcement: Record<string, string>) => Promise<void>;
+export type CasPublishFn = (announcement: Record<string, string>) => Promise<void>;

package/src/core/beacon/signal-discovery.ts

@@ -109,6 +109,20 @@ export class BeaconSignalDiscovery {
   /**
    * Retrieves the beacon signals for the given array of BeaconService objects
    * using an esplora/electrs REST API connection via a bitcoin I/O driver.
+   *
+   * The address listing includes mempool transactions. The method skips a
+   * transaction whose `status.confirmed` is not `true`. A mempool transaction
+   * has no block height and no block time, so it cannot carry block metadata.
+   * The specification also says that a resolver must not process an
+   * unconfirmed transaction. An absent flag counts as unconfirmed, as it does
+   * for UTXO selection. The check runs before the OP_RETURN parse, so a
+   * mempool transaction costs no prevout fetch. The {@link fullnode} path
+   * needs no such check: it walks mined blocks only.
+   *
+   * The `confirmations` count uses the block count fetched before the listing.
+   * A block that arrives between the two calls yields a count of `0` for its
+   * transactions. The resolver then excludes them, because its minimum is at
+   * least `1`. An under-count is the safe direction, so keep that order.
    * @param {Array<BeaconService>} beaconServices Array of BeaconService objects to retrieve signals for
    * @param {BitcoinConnection} bitcoin Bitcoin network connection to use for REST calls
    * @returns {Promise<Map<BeaconService, Array<BeaconSignal>>>} Map of beacon service to its discovered signals
@@ -136,6 +150,14 @@ export class BeaconSignalDiscovery {
 
       // Iterate over each signal
       for (const beaconSignal of beaconSignals) {
+        // Skip a mempool transaction before any parse or fetch. Esplora reports it
+        // as `{ confirmed: false }` with no block fields, so it has no block
+        // metadata, and the specification forbids a resolver to process it.
+        const status = beaconSignal.status;
+        if(status.confirmed !== true) {
+          continue;
+        }
+
         // Get the last vout in the transaction
         const lastSignalVout = beaconSignal.vout.slice(-1)[0];
 
@@ -169,7 +191,7 @@ export class BeaconSignalDiscovery {
         }
 
         // Use the pre-fetched block count instead of calling per-signal
-        const confirmations = currentBlockCount - beaconSignal.status.block_height + 1;
+        const confirmations = currentBlockCount - status.block_height + 1;
 
         // Push the beacon signal object to the signals array for the beacon service
         beaconServiceSignals.get(beaconService)?.push({
@@ -177,8 +199,8 @@ export class BeaconSignalDiscovery {
           signalBytes   : updateHash,
           blockMetadata : {
             confirmations,
-            height : beaconSignal.status.block_height,
-            time   : beaconSignal.status.block_time,
+            height : status.block_height,
+            time   : status.block_time,
           }
         });
       }

package/src/core/beacon/singleton-beacon.ts

@@ -20,8 +20,8 @@ export class SingletonBeacon extends SinglePartyBeacon {
    * Creates an instance of SingletonBeacon.
    * @param {BeaconService} service The BeaconService object representing the funded beacon to announce the update to.
    */
-  constructor(service: BeaconService) {
-    super({ ...service, type: 'SingletonBeacon' });
+  constructor(service: BeaconService, did: string) {
+    super({ ...service, type: 'SingletonBeacon' }, did);
   }
 
   /**

package/src/core/beacon/smt-beacon.ts

@@ -27,9 +27,10 @@ export class SMTBeacon extends SinglePartyBeacon {
   /**
    * Creates an instance of SMTBeacon.
    * @param {BeaconService} service The Beacon service.
+   * @param {string} did The absolute did:btcr2 identifier this beacon serves.
    */
-  constructor(service: BeaconService) {
-    super({ ...service, type: 'SMTBeacon' });
+  constructor(service: BeaconService, did: string) {
+    super({ ...service, type: 'SMTBeacon' }, did);
   }
 
   /**
@@ -52,8 +53,8 @@ export class SMTBeacon extends SinglePartyBeacon {
     const updates = new Array<[SignedBTCR2Update, BlockMetadata]>();
     const needs = new Array<DataNeed>();
 
-    // Extract the DID from the beacon service id (strip the #fragment)
-    const did = this.service.id.split('#')[0];
+    // The DID under resolution keys this beacon's leaf index.
+    const did = this.did;
 
     for(const signal of signals) {
       // Signal bytes are the hex-encoded SMT root hash; smtMap is keyed by proof.id (also hex)
@@ -144,8 +145,8 @@ export class SMTBeacon extends SinglePartyBeacon {
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
   ): Promise<BroadcastResult> {
-    // Extract the DID from the beacon service id (strip the #fragment)
-    const did = this.service.id.split('#')[0];
+    // The DID keys this beacon's leaf index in the tree.
+    const did = this.did;
 
     // Build a single-entry SMT from the signed update
     const canonicalBytes = new TextEncoder().encode(canonicalize(signedUpdate));

package/src/core/did-sender-resolver.ts

@@ -1,6 +1,7 @@
 import { DidDocumentError, INVALID_DID_DOCUMENT } from '@did-btcr2/common';
 import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
+import { Appendix } from '../utils/appendix.js';
 import type { DidDocument, DidVerificationMethod } from '../utils/did-document.js';
 import { Identifier } from './identifier.js';
 import { Resolver } from './resolver.js';
@@ -40,9 +41,16 @@ export function getAggregationCommunicationKey(
   // Resolve capabilityInvocation[0] to a verification method: a string reference is
   // dereferenced by id against verificationMethod; an embedded method is used directly.
   // A local id lookup is used rather than getSigningMethod, which defaults to #initialKey
-  // and does not resolve embedded methods.
+  // and does not resolve embedded methods. Reference and method id are each resolved to an
+  // absolute DID URL first, because either may be spelled as a relative DID URL; an
+  // unusable reference resolves to nothing rather than to the first unusable method id.
+  const invocationId = Appendix.absoluteDidUrl(invocation, document.id);
   const vm: DidVerificationMethod | undefined = typeof invocation === 'string'
-    ? document.verificationMethod?.find(method => method.id === invocation)
+    ? (invocationId === undefined
+      ? undefined
+      : document.verificationMethod?.find(
+        method => Appendix.absoluteDidUrl(method.id, document.id) === invocationId
+      ))
     : invocation;
 
   if(!vm) {

package/src/core/interfaces.ts

@@ -46,6 +46,20 @@ export interface ResolutionOptions extends DidResolutionOptions {
    * document is well-formed, the resolver simply stopped at the caller's limit.
    */
   maxDiscoveryRounds?: number;
+
+  /**
+   * Minimum number of Bitcoin block confirmations a Beacon Signal transaction
+   * must have before resolution processes it. A positive integer, minimum `1`.
+   * Defaults to `6` ({@link DEFAULT_MIN_CONF}), the value the specification
+   * mandates. A signal below the threshold is excluded from the resolution
+   * as if it did not exist yet; the rest of the signals are processed. A lower
+   * value shows a fresh update sooner and raises the exposure to a block
+   * reorganization. The `confirmations` field of the resolution metadata
+   * reports the depth of the last applied signal, so a consumer can judge it.
+   * Any other value (`0`, a negative number, a fraction, `NaN`, a string)
+   * fails with a `ResolveError` of type `INVALID_OPTIONS`.
+   */
+  minConf?: number;
 }
 
 /**

package/src/core/resolver.ts

@@ -9,6 +9,7 @@ import {
   INTERNAL_ERROR,
   INVALID_DID_DOCUMENT,
   INVALID_DID_UPDATE,
+  INVALID_OPTIONS,
   JSONPatch,
   JSONUtils,
   LATE_PUBLISHING_ERROR,
@@ -37,6 +38,15 @@ import type { SMTProof } from './interfaces.js';
 import type { CASAnnouncement, Sidecar, SidecarData } from './types.js';
 import { equalBytes } from '@noble/curves/utils.js';
 
+/**
+ * Default minimum number of Bitcoin block confirmations a Beacon Signal
+ * transaction must have before resolution processes it. The specification
+ * mandates `6` when `ResolutionOptions.minConf` is not set: six confirmations
+ * is the accepted standard for a settled Bitcoin transaction. A resolution
+ * request can raise or lower it through `minConf`.
+ */
+export const DEFAULT_MIN_CONF = 6;
+
 /**
  * The response object for DID Resolution.
  */
@@ -149,30 +159,20 @@ function isSMTProof(value: unknown): value is SMTProof {
     && Array.isArray(value.hashes);
 }
 
-// ─── verification relationship membership ────────────────────────────────────
-
 /**
- * Resolves a verification relationship entry to the absolute DID URL of the
- * method it names, or `undefined` when the entry names no method.
- *
- * An entry is either a reference (a bare fragment such as `#key-0`, or an
- * absolute DID URL) or an embedded verification method object. A bare fragment
- * is relative to the document that carries it, so it is resolved against
- * `documentId` before comparison; every other string is returned unchanged, so
- * a reference naming a different DID can never collapse onto this document's.
- *
- * Malformed entries yield `undefined` rather than a placeholder string, so two
- * unusable values never compare equal to each other.
- *
- * @param {string} documentId The `id` of the DID document carrying the entry.
- * @param {unknown} entry The relationship entry: a reference or an embedded method.
- * @returns {string | undefined} The absolute DID URL, or undefined if unusable.
+ * Validate `ResolutionOptions.minConf`. `undefined` selects the specification
+ * default, {@link DEFAULT_MIN_CONF}. Any other value must be an integer of at
+ * least 1, as the specification defines the option.
+ * @throws {ResolveError} `INVALID_OPTIONS` for every other value.
  */
-function relationshipMethodId(documentId: string, entry: unknown): string | undefined {
-  // An embedded method names itself with its `id`; a reference is the id itself.
-  const id = isRecord(entry) ? entry.id : entry;
-  if(typeof id !== 'string' || id.length === 0) return undefined;
-  return id.startsWith('#') ? `${documentId}${id}` : id;
+function validateMinConf(value: unknown): number {
+  if(value === undefined) 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 }
+  );
 }
 
 /**
@@ -251,6 +251,16 @@ export class Resolver {
   /** Count of beacon-discovery passes driven by updates adding new beacon services. */
   #discoveryRounds = 0;
 
+  /**
+   * Minimum block confirmations a Beacon Signal must have before this resolver
+   * processes it: `ResolutionOptions.minConf`, default {@link DEFAULT_MIN_CONF}.
+   * Applied at signal intake in the BeaconProcess phase. A signal below the
+   * threshold is excluded from the resolution; the rest of the signals are
+   * processed.
+   */
+  readonly #minConf: number;
+
+
   /**
    * @internal Use {@link DidBtcr2.resolve} to create instances.
    */
@@ -258,7 +268,13 @@ export class Resolver {
     didComponents: DidComponents,
     sidecarData: SidecarData,
     currentDocument: DidDocument | null,
-    options?: { versionId?: string; versionTime?: string; genesisDocument?: object; maxDiscoveryRounds?: number }
+    options?: {
+      versionId?: string;
+      versionTime?: string;
+      genesisDocument?: object;
+      maxDiscoveryRounds?: number;
+      minConf?: number;
+    }
   ) {
     this.#didComponents = didComponents;
     this.#sidecarData = sidecarData;
@@ -269,6 +285,9 @@ export class Resolver {
     // 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.
+    this.#minConf = validateMinConf(options?.minConf);
 
     // If a genesis document was provided (from sidecar), pre-seed it for validation
     if(options?.genesisDocument) {
@@ -394,6 +413,10 @@ export class Resolver {
    *   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: DidDocument,
@@ -434,8 +457,6 @@ export class Resolver {
       // Safely convert block.time to timestamp
       const blocktime = DateUtils.blocktimeToTimestamp(block.time);
 
-      // TODO: How to detect if block is unconfirmed and exit gracefully or return without it
-
       // Set the updated field to the blocktime of the current update
       response.metadata.updated = DateUtils.toISOStringNonFractional(blocktime);
 
@@ -636,9 +657,9 @@ export class Resolver {
     // 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 = relationshipMethodId(currentDocument.id, verificationMethodId);
+    const authorizedMethodId = Appendix.relationshipMethodId(verificationMethodId, currentDocument.id);
     const authorized = authorizedMethodId !== undefined && currentDocument.capabilityInvocation?.some(
-      entry => relationshipMethodId(currentDocument.id, entry) === authorizedMethodId
+      entry => Appendix.relationshipMethodId(entry, currentDocument.id) === authorizedMethodId
     );
     if(!authorized) {
       throw new ResolveError(
@@ -772,9 +793,17 @@ export class Resolver {
             // Skip already-processed services and services with no signals
             if(this.#processedServices.has(service.id) || !signals.length) continue;
 
+            // Keep only the signals at or above the confirmation threshold. A
+            // service whose signals are all below it is treated like a service
+            // with no signals: it is not processed and not marked processed.
+            const eligible = this.#eligibleSignals(signals);
+            if(!eligible.length) continue;
+
             // Establish a typed beacon and process its signals
-            const beacon = BeaconFactory.establish(service);
-            const result = beacon.processSignals(signals, this.#sidecarData);
+            // The beacon is bound to the DID under resolution: a beacon service
+            // `id` may be a relative DID URL, so it cannot supply the subject.
+            const beacon = BeaconFactory.establish(service, this.#currentDocument!.id);
+            const result = beacon.processSignals(eligible, this.#sidecarData);
 
             if(result.needs.length > 0) {
               // This service has unmet data needs, collect them
@@ -864,6 +893,43 @@ export class Resolver {
     }
   }
 
+  /**
+   * Return the signals of one beacon service that resolution may process: the
+   * signals with at least `#minConf` confirmations. The specification removes a
+   * transaction below the threshold from the set of Beacon Signals, so an
+   * excluded signal emits no data need and applies no update. A signal with no
+   * 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}.
+   * @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.
+   */
+  #eligibleSignals(signals: Array<BeaconSignal>): Array<BeaconSignal> {
+    const eligible: Array<BeaconSignal> = [];
+    for(const signal of signals) {
+      const block = signal.blockMetadata as Partial<BlockMetadata> | undefined;
+      const confirmations = block?.confirmations;
+      if(!Number.isInteger(confirmations) || (confirmations as number) < this.#minConf) {
+        continue;
+      }
+      if(!Number.isFinite(block?.height) || !Number.isFinite(block?.time)) {
+        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 }
+        );
+      }
+      eligible.push(signal);
+    }
+    return eligible;
+  }
+
   /**
    * Provide data the resolver requested in a previous {@link resolve} call.
    * Call once per need, then call {@link resolve} again to continue.

package/src/core/updater.ts

@@ -58,8 +58,8 @@ 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, signer, bitcoin, options?)` or
- * `BeaconFactory.establish(beaconService).broadcastSignal(...)`. For multi-party
+ * `Updater.announce(beaconService, did, signedUpdate, signer, bitcoin, options?)` or
+ * `BeaconFactory.establish(beaconService, did).broadcastSignal(...)`. For multi-party
  * aggregate beacons, hand off to the aggregation protocol.
  *
  * Both single-party paths return a `BroadcastResult`; capture it. Beyond the txid,
@@ -76,6 +76,11 @@ export interface NeedBroadcast {
   readonly beaconService: BeaconService;
   /** The signed update ready for broadcast. */
   readonly signedUpdate: SignedBTCR2Update;
+  /**
+   * The DID being updated. Supplied because a beacon service `id` may be a
+   * relative DID URL and so cannot be used to recover the subject.
+   */
+  readonly did: string;
 }
 
 /** Discriminated union of all data needs the updater may request from the caller. */
@@ -148,7 +153,7 @@ export interface UpdaterParams {
  *         // 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);
+ *         const broadcast = await Updater.announce(need.beaconService, need.did, need.signedUpdate, signer, bitcoin);
  *         updater.provide(need);
  *         break;
  *       }
@@ -278,6 +283,12 @@ export class Updater {
     const id = verificationMethod.id.slice(hashIdx);
     const multikey = SchnorrMultikey.fromSigner(id, controller, signer);
 
+    // The absolute spelling of the method id, for the proof to name it by. `hashIdx === 0`
+    // means the document writes this method's own id as a relative DID URL, which per DID
+    // Core denotes that fragment of the document's `id`: the same rule as
+    // Appendix.absoluteDidUrl, whose `undefined` case the fragment check above excludes.
+    const absoluteMethodId = hashIdx === 0 ? `${did}${id}` : verificationMethod.id;
+
     // Fail fast if the signer's public key is not the key published in the named
     // verification method. Signing with the wrong key yields a Data Integrity
     // proof that cannot verify against the method, so the resulting on-chain
@@ -308,7 +319,12 @@ export class Updater {
       ],
       cryptosuite        : 'bip340-jcs-2025',
       type               : 'DataIntegrityProof',
-      verificationMethod : verificationMethod.id,
+      // The proof names the signing method by absolute DID URL, even when the document
+      // spells that method's own id relatively: a proof travels apart from the document
+      // that defines the method, so a bare `#initialKey` in it resolves against nothing.
+      // For a document that already spells its ids absolutely this is the id unchanged,
+      // so proofs over such documents are byte-identical to before.
+      verificationMethod : absoluteMethodId,
       proofPurpose       : 'capabilityInvocation',
       capability         : `urn:zcap:root:${encodeURIComponent(did)}`,
       capabilityAction   : 'Write',
@@ -323,6 +339,8 @@ export class Updater {
    * Announces a signed update to the Bitcoin blockchain via the specified beacon.
    *
    * @param {BeaconService} beaconService The beacon service to broadcast through.
+   * @param {string} did The DID being updated. Required because a beacon service
+   *   `id` may be a relative DID URL and so cannot supply the subject.
    * @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.
@@ -334,12 +352,13 @@ export class Updater {
    */
   static async announce(
     beaconService: BeaconService,
+    did: string,
     update: SignedBTCR2Update,
     signer: Signer,
     bitcoin: BitcoinConnection,
     options?: CASBroadcastOptions
   ): Promise<BroadcastResult> {
-    const beacon = BeaconFactory.establish(beaconService);
+    const beacon = BeaconFactory.establish(beaconService, did);
     return beacon.broadcastSignal(update, signer, bitcoin, options);
   }
 
@@ -406,6 +425,7 @@ export class Updater {
               kind          : 'NeedBroadcast',
               beaconService : this.#beaconService,
               signedUpdate  : this.#state.signedUpdate,
+              did           : this.#sourceDocument.id,
             }],
           };
         }

package/src/did-btcr2.ts

@@ -131,7 +131,8 @@ export class DidBtcr2 implements DidMethod {
       versionId          : resolutionOptions.versionId,
       versionTime        : resolutionOptions.versionTime,
       genesisDocument    : resolutionOptions.sidecar?.genesisDocument,
-      maxDiscoveryRounds : resolutionOptions.maxDiscoveryRounds
+      maxDiscoveryRounds : resolutionOptions.maxDiscoveryRounds,
+      minConf            : resolutionOptions.minConf
     });
   }
 
@@ -171,8 +172,16 @@ export class DidBtcr2 implements DidMethod {
     verificationMethodId: string;
     beaconId: string;
   }): Updater {
-    // Validate that the verificationMethodId is authorized for capabilityInvocation
-    if(!sourceDocument.capabilityInvocation?.some(vr => vr === verificationMethodId)) {
+    // Validate that the verificationMethodId is authorized for capabilityInvocation.
+    // Both sides are resolved to absolute DID URLs first, so the caller's spelling of the
+    // reference and the document's spelling of the entry may differ: either is legal per
+    // DID Core. This is the same rule the read path applies to an update's proof, so an
+    // update this factory authorizes is one the resolver will also accept.
+    const authorizedMethodId = Appendix.relationshipMethodId(verificationMethodId, sourceDocument.id);
+    const authorized = authorizedMethodId !== undefined && sourceDocument.capabilityInvocation?.some(
+      entry => Appendix.relationshipMethodId(entry, sourceDocument.id) === authorizedMethodId
+    );
+    if(!authorized) {
       throw new UpdateError(
         'Invalid verificationMethodId: not authorized for capabilityInvocation',
         INVALID_DID_DOCUMENT, sourceDocument
@@ -206,9 +215,14 @@ export class DidBtcr2 implements DidMethod {
       );
     }
 
-    // Find the beacon service matching the given beaconId
+    // Find the beacon service matching the given beaconId. A service `id` may be a relative
+    // DID URL, so both sides are resolved against the document before comparison; an
+    // unusable beaconId matches nothing rather than matching an unusable service id.
+    const targetBeaconId = Appendix.absoluteDidUrl(beaconId, sourceDocument.id);
     const beaconService = sourceDocument.service
-      .filter((service: BeaconService) => service.id === beaconId)
+      .filter((service: BeaconService) =>
+        targetBeaconId !== undefined
+        && Appendix.absoluteDidUrl(service.id, sourceDocument.id) === targetBeaconId)
       .filter((service: BeaconService): service is BeaconService => !!service)
       .shift();
 
@@ -250,10 +264,17 @@ export class DidBtcr2 implements DidMethod {
     }
 
     // Attempt to find a verification method that matches the given method ID, or if not given,
-    // find the first verification method intended for signing claims.
-    const verificationMethod = didDocument.verificationMethod?.find(
-      (vm: DidVerificationMethod) => Appendix.extractDidFragment(vm.id) === (Appendix.extractDidFragment(methodId)
-        ?? Appendix.extractDidFragment(didDocument.assertionMethod?.[0]))
+    // find the first verification method intended for signing claims. Both sides are resolved
+    // to absolute DID URLs first: a document may spell either the verification method `id` or
+    // the reference to it as a relative DID URL (`#initialKey`), and the two must still match.
+    const targetId = Appendix.absoluteDidUrl(methodId, didDocument.id)
+      ?? Appendix.relationshipMethodId(didDocument.assertionMethod?.[0], didDocument.id);
+
+    // An unusable target matches nothing: without this guard it compares equal to every
+    // method whose own id is unusable, and the document's first malformed method is
+    // returned as the signing method.
+    const verificationMethod = targetId === undefined ? undefined : didDocument.verificationMethod?.find(
+      (vm: DidVerificationMethod) => Appendix.absoluteDidUrl(vm.id, didDocument.id) === targetId
     );
 
     // If no verification method is found, throw an error

package/src/utils/appendix.ts

@@ -18,14 +18,46 @@ import type { RootCapability } from '../core/interfaces.js';
  */
 export class Appendix {
   /**
-   * Extracts a DID fragment from a given input
-   * @param {unknown} input The input to extract the DID fragment from
-   * @returns {string | undefined} The extracted DID fragment or undefined if not found
+   * Resolves a DID URL that may be written as a relative reference against the
+   * DID it appears under. DID Core permits the `id` of a verification method or
+   * service, and the entries of a verification relationship, to be a relative
+   * DID URL such as `#initialKey`; it denotes that fragment of `did`. Absolute
+   * DID URLs are returned unchanged, so both spellings of the same reference
+   * compare equal without discarding the DID being compared.
+   *
+   * @param {unknown} input The DID URL to resolve. Non-strings yield `undefined`.
+   * @param {string} did The DID the relative reference is resolved against.
+   * @returns {string | undefined} The absolute DID URL, or `undefined` if `input` is not a usable string.
    */
-  public static extractDidFragment(input: unknown): string | undefined {
+  public static absoluteDidUrl(input: unknown, did: string): string | undefined {
     if (typeof input !== 'string') return undefined;
     if (input.length === 0) return undefined;
-    return input;
+    return input.startsWith('#') ? `${did}${input}` : input;
+  }
+
+  /**
+   * Resolves a verification relationship entry to the absolute DID URL of the method it
+   * names. A relationship entry is either a reference to a method defined elsewhere in the
+   * document, or a method embedded inline, which names itself with its own `id`; either
+   * spelling may be a relative DID URL.
+   *
+   * Every comparison of a relationship entry against a method id goes through this helper,
+   * on both the read path and the write path, so the two admit exactly the same spellings.
+   *
+   * Malformed entries yield `undefined` rather than a placeholder string, so two unusable
+   * values never compare equal to each other. Callers comparing a resolved entry must still
+   * reject an `undefined` target before comparing, or an unusable target matches an
+   * unusable entry.
+   *
+   * @param {unknown} entry The relationship entry: a reference, or an embedded method.
+   * @param {string} did The DID the relative reference is resolved against.
+   * @returns {string | undefined} The absolute DID URL, or `undefined` if unusable.
+   */
+  public static relationshipMethodId(entry: unknown, did: string): string | undefined {
+    const id = (typeof entry === 'object' && entry !== null && !Array.isArray(entry))
+      ? (entry as { id?: unknown }).id
+      : entry;
+    return Appendix.absoluteDidUrl(id, did);
   }
 
   /**