@did-btcr2/method 0.27.0 → 0.28.0

package/dist/types/did-btcr2.d.ts

@@ -1,9 +1,8 @@
-import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { DocumentBytes, HexString, KeyBytes, PatchOperation } from '@did-btcr2/common';
-import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { DocumentBytes, KeyBytes, PatchOperation } from '@did-btcr2/common';
 import type { DidMethod } from '@web5/dids';
 import type { ResolutionOptions } from './core/interfaces.js';
 import { Resolver } from './core/resolver.js';
+import { Updater } from './core/updater.js';
 import type { Btcr2DidDocument, DidVerificationMethod } from './utils/did-document.js';
 export interface DidCreateOptions {
     /** Type of identifier to create (key or external) */
@@ -71,34 +70,35 @@ export declare class DidBtcr2 implements DidMethod {
      */
     static resolve(did: string, resolutionOptions?: ResolutionOptions): Resolver;
     /**
-     * Entry point for section {@link https://dcdpr.github.io/did-btcr2/#read | 7.3 Update}.
-     * See specification for the {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#process | Resolve Process}.
-     * See {@link Update | Update (class)} for class implementation.
+     * Entry point for section {@link https://dcdpr.github.io/did-btcr2/#update | 7.3 Update}.
      *
-     * BTCR2 DID documents can be updated by anchoring BTCR2 Updates to Bitcoin transactions. These transactions MAY be
-     * published to the Bitcoin network. Any property in the DID document may be updated except the id. Doing so would
-     * invalidate the DID document.
-     * @param params An object containing the parameters for the update operation.
+     * Factory method that validates the update parameters and returns a sans-I/O
+     * {@link Updater} state machine. The caller drives the updater through its
+     * phases (Construct → Sign → Broadcast → Complete) by calling `advance()` and
+     * `provide()`. The method package performs **zero I/O** — signing key retrieval
+     * (or KMS delegation) and the on-chain broadcast are the caller's responsibility.
+     *
+     * For a fully-wired version with Bitcoin broadcast and key handling, see
+     * `DidMethodApi.update()` in `@did-btcr2/api`.
+     *
+     * @param params Update construction parameters.
      * @param {Btcr2DidDocument} params.sourceDocument The DID document being updated.
-     * @param {PatchOperation[]} params.patches The array of JSON Patch operations to apply to the sourceDocument.
-     * @param {string} params.sourceVersionId The version ID before applying the update.
-     * @param {string} params.verificationMethodId The verificationMethod ID to sign the update with.
-     * @param {string} params.beaconId The beacon ID associated with the update.
-     * @param {KeyBytes | HexString} [params.signingMaterial] Optional signing material (key bytes or hex string).
-     * @param {BitcoinConnection} [params.bitcoin] Optional Bitcoin network connection for announcing the update. If not provided, a default connection will be initialized.
-     * @return {Promise<SignedBTCR2Update>} Promise resolving to the signed BTCR2 update.
-     * @throws {UpdateError} if no verificationMethod, verificationMethod type is not `Multikey` or the publicKeyMultibase
-     * header is not `zQ3s`
+     * @param {PatchOperation[]} params.patches The JSON Patch operations to apply.
+     * @param {number} params.sourceVersionId The version ID before applying the update.
+     * @param {string} params.verificationMethodId The verification method ID to sign with.
+     * @param {string} params.beaconId The beacon service ID to broadcast through.
+     * @returns {Updater} A sans-I/O state machine for driving the update.
+     * @throws {UpdateError} If the verification method is not authorized, not found,
+     *   not of type `Multikey`, or does not have a `zQ3s` publicKeyMultibase prefix.
+     *   Also throws if the beacon service is not found.
      */
-    static update({ sourceDocument, patches, sourceVersionId, verificationMethodId, beaconId, signingMaterial, bitcoin, }: {
+    static update({ sourceDocument, patches, sourceVersionId, verificationMethodId, beaconId, }: {
         sourceDocument: Btcr2DidDocument;
         patches: PatchOperation[];
         sourceVersionId: number;
         verificationMethodId: string;
         beaconId: string;
-        signingMaterial?: KeyBytes | HexString;
-        bitcoin?: BitcoinConnection;
-    }): Promise<SignedBTCR2Update>;
+    }): Updater;
     /**
      * Given the W3C DID Document of a `did:btcr2` identifier, return the signing verification method that will be used
      * for signing messages and credentials. If given, the `methodId` parameter is used to select the

package/dist/types/did-btcr2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"did-btcr2.d.ts","sourceRoot":"","sources":["../../src/did-btcr2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,QAAQ,EACR,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAS3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EACV,SAAS,EAAC,MAAM,YAAY,CAAC;AAW/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEvF,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,YAAW,SAAS;IACxC;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,CAAW;IAEpC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,GAAG,aAAa,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM;IAezF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CACZ,GAAG,EAAE,MAAM,EACX,iBAAiB,GAAE,iBAAsB,GACxC,QAAQ;IAsBX;;;;;;;;;;;;;;;;;;;OAmBG;WACU,MAAM,CAAC,EAClB,cAAc,EACd,OAAO,EACP,eAAe,EACf,oBAAoB,EACpB,QAAQ,EACR,eAAe,EACf,OAAO,GACR,EAAE;QACD,cAAc,EAAE,gBAAgB,CAAC;QACjC,OAAO,EAAE,cAAc,EAAE,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;QACxB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;QACvC,OAAO,CAAC,EAAE,iBAAiB,CAAC;KAC7B,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoF9B;;;;;;;;;OASG;IACH,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,gBAAgB,EAAG,QAAQ,CAAC,EAAE,MAAM,GAAG,qBAAqB;CA0BlG"}
+{"version":3,"file":"did-btcr2.d.ts","sourceRoot":"","sources":["../../src/did-btcr2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAS3C,OAAO,KAAK,EACV,SAAS,EAAC,MAAM,YAAY,CAAC;AAU/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEvF,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,YAAW,SAAS;IACxC;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,CAAW;IAEpC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,GAAG,aAAa,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM;IAezF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CACZ,GAAG,EAAE,MAAM,EACX,iBAAiB,GAAE,iBAAsB,GACxC,QAAQ;IAsBX;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,MAAM,CAAC,EACZ,cAAc,EACd,OAAO,EACP,eAAe,EACf,oBAAoB,EACpB,QAAQ,GACT,EAAE;QACD,cAAc,EAAE,gBAAgB,CAAC;QACjC,OAAO,EAAE,cAAc,EAAE,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;QACxB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO;IA2DX;;;;;;;;;OASG;IACH,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,gBAAgB,EAAG,QAAQ,CAAC,EAAE,MAAM,GAAG,qBAAqB;CA0BlG"}

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@ export * from './core/beacon/beacon.js';
 export * from './core/beacon/cas-beacon.js';
 export * from './core/beacon/error.js';
 export * from './core/beacon/factory.js';
+export * from './core/beacon/fee-estimator.js';
 export * from './core/beacon/interfaces.js';
 export * from './core/beacon/signal-discovery.js';
 export * from './core/beacon/singleton-beacon.js';
@@ -20,7 +21,7 @@ export * from './core/identifier.js';
 export * from './core/interfaces.js';
 export * from './core/resolver.js';
 export * from './core/types.js';
-export * from './core/update.js';
+export * from './core/updater.js';
 export * from './utils/appendix.js';
 export * from './utils/did-document-builder.js';
 export * from './utils/did-document.js';

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AAGnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AAGxC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AAGnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AAGxC,cAAc,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "type": "module",
   "description": "Reference implementation for the did:btcr2 DID method written in TypeScript and JavaScript. did:btcr2 is a censorship resistant DID Method using the Bitcoin blockchain as a Verifiable Data Registry to announce changes to the DID document. This is the core method implementation for the did-btcr2-js monorepo.",
   "main": "./dist/cjs/index.js",
@@ -83,10 +83,10 @@
     "multiformats": "^13.4.2",
     "nostr-tools": "^2.23.3",
     "@did-btcr2/bitcoin": "^0.5.3",
-    "@did-btcr2/common": "^9.0.0",
     "@did-btcr2/cryptosuite": "^6.0.6",
     "@did-btcr2/smt": "^0.2.4",
-    "@did-btcr2/keypair": "^0.11.4"
+    "@did-btcr2/keypair": "^0.11.4",
+    "@did-btcr2/common": "^9.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/src/core/aggregation/runner/participant-runner.ts

@@ -87,7 +87,11 @@ export interface AggregationParticipantRunnerOptions {
  *   keys: myKeys,
  *   shouldJoin: async (advert) => advert.beaconType === 'CASBeacon',
  *   onProvideUpdate: async ({ beaconAddress }) => {
+<<<<<<< Updated upstream
  *     return Update.sign(myDid, unsigned, vm, secretKey);
+=======
+ *     return Updater.sign(myDid, unsigned, vm, secretKey);
+>>>>>>> Stashed changes
  *   },
  * });
  *

package/src/core/updater.ts

@@ -0,0 +1,415 @@
+import type { BitcoinConnection } from '@did-btcr2/bitcoin';
+import type { KeyBytes, PatchOperation } from '@did-btcr2/common';
+import { canonicalHash, INVALID_DID_UPDATE, JSONPatch, UpdateError } from '@did-btcr2/common';
+import { SchnorrMultikey, type DataIntegrityConfig, type SignedBTCR2Update, type UnsignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import { DidDocument, type Btcr2DidDocument, type DidVerificationMethod } from '../utils/did-document.js';
+import { BeaconFactory } from './beacon/factory.js';
+import type { BeaconService } from './beacon/interfaces.js';
+
+// ─── DataNeed types ──────────────────────────────────────────────────────────
+
+/**
+ * The updater needs the caller to supply a signing key (or a KMS-backed signature)
+ * for the given verification method. The unsigned update is attached so the caller
+ * can inspect it before producing a signature.
+ */
+export interface NeedSigningKey {
+  readonly kind: 'NeedSigningKey';
+  /** The verification method ID that requires a signing key. */
+  readonly verificationMethodId: string;
+  /** The unsigned update that will be signed. */
+  readonly unsignedUpdate: UnsignedBTCR2Update;
+}
+
+/**
+ * The updater needs the caller to ensure the beacon address is funded before
+ * broadcasting. The caller checks the beacon address for UTXOs, funds it if
+ * needed, and then calls `updater.provide(need)` to continue.
+ *
+ * If the beacon is already funded, the caller can provide immediately (no-op).
+ */
+export interface NeedFunding {
+  readonly kind: 'NeedFunding';
+  /** The Bitcoin address that must have a spendable UTXO for broadcast. */
+  readonly beaconAddress: string;
+  /** The beacon service this address belongs to. */
+  readonly beaconService: BeaconService;
+}
+
+/**
+ * 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
+ * `BeaconFactory.establish(beaconService).broadcastSignal(...)`. For multi-party
+ * aggregate beacons, hand off to the aggregation protocol.
+ *
+ * After the broadcast succeeds, the caller calls `updater.provide(need)` (with no
+ * data) to transition the updater to Complete.
+ */
+export interface NeedBroadcast {
+  readonly kind: 'NeedBroadcast';
+  /** The beacon service to broadcast through. Inspect `beaconService.type` to decide the path. */
+  readonly beaconService: BeaconService;
+  /** The signed update ready for broadcast. */
+  readonly signedUpdate: SignedBTCR2Update;
+}
+
+/** Discriminated union of all data needs the updater may request from the caller. */
+export type UpdaterDataNeed = NeedSigningKey | NeedFunding | NeedBroadcast;
+
+/**
+ * The result returned by the updater when it reaches the Complete phase.
+ */
+export interface UpdaterResult {
+  /** The signed update that was constructed, signed, and broadcast. */
+  signedUpdate: SignedBTCR2Update;
+}
+
+/**
+ * Output of {@link Updater.advance}. Either the updater needs data from the
+ * caller, or the update is complete.
+ */
+export type UpdaterState =
+  | { status: 'action-required'; needs: ReadonlyArray<UpdaterDataNeed> }
+  | { status: 'complete'; result: UpdaterResult };
+
+/**
+ * Internal phases of the Updater state machine.
+ * @internal
+ */
+enum UpdaterPhase {
+  Construct = 'Construct',
+  Sign      = 'Sign',
+  Fund      = 'Fund',
+  Broadcast = 'Broadcast',
+  Complete  = 'Complete',
+}
+
+/**
+ * Parameters for constructing an {@link Updater}. Built by
+ * {@link https://dcdpr.github.io/did-btcr2/operations/update.html | DidBtcr2.update}.
+ */
+export interface UpdaterParams {
+  sourceDocument: Btcr2DidDocument;
+  patches: PatchOperation[];
+  sourceVersionId: number;
+  verificationMethod: DidVerificationMethod;
+  beaconService: BeaconService;
+}
+
+/**
+ * Sans-I/O state machine for did:btcr2 updates — the counterpart to {@link Resolver}.
+ *
+ * Created by {@link DidBtcr2.update} (the factory). The caller drives the update by
+ * repeatedly calling {@link advance} and {@link provide}:
+ *
+ * ```typescript
+ * const updater = DidBtcr2.update({ sourceDocument, patches, ... });
+ * let state = updater.advance();
+ *
+ * while(state.status === 'action-required') {
+ *   for(const need of state.needs) {
+ *     switch(need.kind) {
+ *       case 'NeedSigningKey':
+ *         updater.provide(need, secretKeyBytes);
+ *         break;
+ *       case 'NeedFunding':
+ *         // Check UTXOs at need.beaconAddress, fund if needed
+ *         updater.provide(need);
+ *         break;
+ *       case 'NeedBroadcast':
+ *         await Updater.announce(need.beaconService, need.signedUpdate, secretKey, bitcoin);
+ *         updater.provide(need);
+ *         break;
+ *     }
+ *   }
+ *   state = updater.advance();
+ * }
+ *
+ * const { signedUpdate } = state.result;
+ * ```
+ *
+ * The Updater performs **zero I/O**. All external work (signing with a KMS or raw
+ * key, funding checks, Bitcoin transaction construction, broadcast) flows through
+ * the advance/provide protocol. This mirrors the {@link Resolver} pattern and makes
+ * the update path transport-agnostic and KMS-ready.
+ *
+ * The class also exposes static utility methods ({@link construct}, {@link sign},
+ * {@link announce}) for callers that need direct access to individual update steps
+ * outside the state machine (e.g., test vector generation scripts).
+ *
+ * @class Updater
+ */
+export class Updater {
+  #phase: UpdaterPhase = UpdaterPhase.Construct;
+  readonly #sourceDocument: Btcr2DidDocument;
+  readonly #patches: PatchOperation[];
+  readonly #sourceVersionId: number;
+  readonly #verificationMethod: DidVerificationMethod;
+  readonly #beaconService: BeaconService;
+
+  #unsignedUpdate: UnsignedBTCR2Update | null = null;
+  #signedUpdate: SignedBTCR2Update | null = null;
+
+  /**
+   * @internal — Use {@link DidBtcr2.update} to create instances.
+   */
+  constructor(params: UpdaterParams) {
+    this.#sourceDocument = params.sourceDocument;
+    this.#patches = params.patches;
+    this.#sourceVersionId = params.sourceVersionId;
+    this.#verificationMethod = params.verificationMethod;
+    this.#beaconService = params.beaconService;
+  }
+
+  // ─── Public static utility methods ─────────────────────────────────────────
+  // Used by generate-vector.ts and other scripts that need direct access to
+  // individual update steps outside the state machine flow.
+
+  /**
+   * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#construct-btcr2-unsigned-update | 7.3.b Construct BTCR2 Unsigned Update}.
+   *
+   * @param {Btcr2DidDocument} sourceDocument The source DID document to be updated.
+   * @param {PatchOperation[]} patches The JSON Patch operations to apply.
+   * @param {number} sourceVersionId The version ID of the source document.
+   * @returns {UnsignedBTCR2Update} The constructed UnsignedBTCR2Update object.
+   * @throws {UpdateError} If the target document fails DID Core validation.
+   */
+  static construct(
+    sourceDocument: Btcr2DidDocument,
+    patches: PatchOperation[],
+    sourceVersionId: number,
+  ): UnsignedBTCR2Update {
+    const unsignedUpdate: UnsignedBTCR2Update = {
+      '@context'      : [
+        'https://w3id.org/security/v2',
+        'https://w3id.org/zcap/v1',
+        'https://w3id.org/json-ld-patch/v1',
+        'https://btcr2.dev/context/v1'
+      ],
+      patch           : patches,
+      targetHash      : '',
+      targetVersionId : sourceVersionId + 1,
+      sourceHash      : canonicalHash(sourceDocument),
+    };
+
+    const targetDocument = JSONPatch.apply(sourceDocument, patches);
+
+    try {
+      DidDocument.isValid(targetDocument);
+    } catch (error) {
+      throw new UpdateError(
+        'Error validating targetDocument: ' + (error instanceof Error ? error.message : String(error)),
+        INVALID_DID_UPDATE, targetDocument
+      );
+    }
+
+    unsignedUpdate.targetHash = canonicalHash(targetDocument);
+    return unsignedUpdate;
+  }
+
+  /**
+   * Implements subsection {@link http://dcdpr.github.io/did-btcr2/operations/update.html#construct-btcr2-signed-update | 7.3.c Construct BTCR2 Signed Update }.
+   *
+   * @param {string} did The did-btcr2 identifier to derive the root capability from.
+   * @param {UnsignedBTCR2Update} unsignedUpdate The unsigned update to sign.
+   * @param {DidVerificationMethod} verificationMethod The verification method for signing.
+   * @param {KeyBytes} secretKey The secret key bytes.
+   * @returns {SignedBTCR2Update} The signed update with a Data Integrity proof.
+   */
+  static sign(
+    did: string,
+    unsignedUpdate: UnsignedBTCR2Update,
+    verificationMethod: DidVerificationMethod,
+    secretKey: KeyBytes,
+  ): SignedBTCR2Update {
+    const controller = verificationMethod.controller;
+    const id = verificationMethod.id.slice(verificationMethod.id.indexOf('#'));
+    const multikey = SchnorrMultikey.fromSecretKey(id, controller, secretKey);
+
+    const config: DataIntegrityConfig = {
+      '@context' : [
+        'https://w3id.org/security/v2',
+        'https://w3id.org/zcap/v1',
+        'https://w3id.org/json-ld-patch/v1',
+        'https://btcr2.dev/context/v1'
+      ],
+      cryptosuite        : 'bip340-jcs-2025',
+      type               : 'DataIntegrityProof',
+      verificationMethod : verificationMethod.id,
+      proofPurpose       : 'capabilityInvocation',
+      capability         : `urn:zcap:root:${encodeURIComponent(did)}`,
+      capabilityAction   : 'Write',
+    };
+
+    const diproof = multikey.toCryptosuite().toDataIntegrityProof();
+    return diproof.addProof(unsignedUpdate, config);
+  }
+
+  /**
+   * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#announce-did-update | 7.3.d Announce DID Update}.
+   * Announces a signed update to the Bitcoin blockchain via the specified beacon.
+   *
+   * @param {BeaconService} beaconService The beacon service to broadcast through.
+   * @param {SignedBTCR2Update} update The signed update to announce.
+   * @param {KeyBytes} secretKey The secret key for signing the Bitcoin transaction.
+   * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
+   * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+   */
+  static async announce(
+    beaconService: BeaconService,
+    update: SignedBTCR2Update,
+    secretKey: KeyBytes,
+    bitcoin: BitcoinConnection
+  ): Promise<SignedBTCR2Update> {
+    const beacon = BeaconFactory.establish(beaconService);
+    return beacon.broadcastSignal(update, secretKey, bitcoin);
+  }
+
+  // ─── Private instance wrappers ─────────────────────────────────────────────
+  // Delegate to the public statics with bound instance fields for cleaner
+  // advance/provide code.
+
+  #construct(): UnsignedBTCR2Update {
+    return Updater.construct(this.#sourceDocument, this.#patches, this.#sourceVersionId);
+  }
+
+  #sign(secretKey: KeyBytes): SignedBTCR2Update {
+    return Updater.sign(this.#sourceDocument.id, this.#unsignedUpdate!, this.#verificationMethod, secretKey);
+  }
+
+  // ─── State machine ─────────────────────────────────────────────────────────
+
+  /**
+   * Advance the state machine. Returns either:
+   * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
+   * - `{ status: 'complete', result }` — update is signed and broadcast
+   */
+  advance(): UpdaterState {
+    while(true) {
+      switch(this.#phase) {
+
+        // Phase: Construct
+        // Build the unsigned update from source doc + patches. Pure, synchronous.
+        case UpdaterPhase.Construct: {
+          this.#unsignedUpdate = this.#construct();
+          this.#phase = UpdaterPhase.Sign;
+          continue;
+        }
+
+        // Phase: Sign
+        // Emit NeedSigningKey — the caller supplies the secret key (or a KMS signature).
+        case UpdaterPhase.Sign: {
+          return {
+            status : 'action-required',
+            needs  : [{
+              kind                 : 'NeedSigningKey',
+              verificationMethodId : this.#verificationMethod.id,
+              unsignedUpdate       : this.#unsignedUpdate!,
+            }],
+          };
+        }
+
+        // Phase: Fund
+        // Emit NeedFunding with the beacon address. The caller checks UTXOs,
+        // funds the address if needed, and provides to continue.
+        case UpdaterPhase.Fund: {
+          const beaconAddress = this.#beaconService.serviceEndpoint.replace('bitcoin:', '');
+          return {
+            status : 'action-required',
+            needs  : [{
+              kind           : 'NeedFunding',
+              beaconAddress,
+              beaconService  : this.#beaconService,
+            }],
+          };
+        }
+
+        // Phase: Broadcast
+        // Emit NeedBroadcast with the signed update + beacon service. The caller performs
+        // the actual on-chain announcement (or hands off to the aggregation protocol).
+        case UpdaterPhase.Broadcast: {
+          return {
+            status : 'action-required',
+            needs  : [{
+              kind          : 'NeedBroadcast',
+              beaconService : this.#beaconService,
+              signedUpdate  : this.#signedUpdate!,
+            }],
+          };
+        }
+
+        // Phase: Complete
+        case UpdaterPhase.Complete: {
+          return {
+            status : 'complete',
+            result : { signedUpdate: this.#signedUpdate! },
+          };
+        }
+      }
+    }
+  }
+
+  /**
+   * Provide data the updater requested in a previous {@link advance} call.
+   * Call once per need, then call {@link advance} again to continue.
+   *
+   * @param need The DataNeed being fulfilled (from the `needs` array).
+   * @param data The data payload corresponding to the need kind (omit for NeedFunding/NeedBroadcast).
+   */
+  provide(need: NeedSigningKey, data: KeyBytes): void;
+  provide(need: NeedFunding): void;
+  provide(need: NeedBroadcast): void;
+  provide(need: UpdaterDataNeed, data?: KeyBytes): void {
+    switch(need.kind) {
+      case 'NeedSigningKey': {
+        if(this.#phase !== UpdaterPhase.Sign) {
+          throw new UpdateError(
+            `Cannot provide NeedSigningKey: updater phase is ${this.#phase}, expected Sign.`,
+            INVALID_DID_UPDATE, { phase: this.#phase }
+          );
+        }
+        if(!data) {
+          throw new UpdateError(
+            'NeedSigningKey requires secret key bytes.',
+            INVALID_DID_UPDATE
+          );
+        }
+        if(!this.#unsignedUpdate) {
+          throw new UpdateError(
+            'Internal error: unsigned update missing in Sign phase.',
+            INVALID_DID_UPDATE
+          );
+        }
+        this.#signedUpdate = this.#sign(data);
+        this.#phase = UpdaterPhase.Fund;
+        break;
+      }
+
+      case 'NeedFunding': {
+        if(this.#phase !== UpdaterPhase.Fund) {
+          throw new UpdateError(
+            `Cannot provide NeedFunding: updater phase is ${this.#phase}, expected Fund.`,
+            INVALID_DID_UPDATE, { phase: this.#phase }
+          );
+        }
+        // Caller has confirmed funding (or it was already funded). Continue.
+        this.#phase = UpdaterPhase.Broadcast;
+        break;
+      }
+
+      case 'NeedBroadcast': {
+        if(this.#phase !== UpdaterPhase.Broadcast) {
+          throw new UpdateError(
+            `Cannot provide NeedBroadcast: updater phase is ${this.#phase}, expected Broadcast.`,
+            INVALID_DID_UPDATE, { phase: this.#phase }
+          );
+        }
+        // Caller has broadcast externally. Transition to Complete.
+        this.#phase = UpdaterPhase.Complete;
+        break;
+      }
+    }
+  }
+}