@did-btcr2/method 0.27.0 → 0.28.0

package/dist/browser.mjs

@@ -138549,9 +138549,8 @@ init_shim();
 // src/did-btcr2.ts
 init_shim();
 var ecc = __toESM(require_dist2(), 1);
-init_utils();
 
-// src/core/update.ts
+// src/core/updater.ts
 init_shim();
 
 // src/utils/did-document.ts
@@ -138917,17 +138916,37 @@ var GenesisDocument = class _GenesisDocument extends DidDocument {
   }
 };
 
-// src/core/update.ts
-var Update = class {
+// src/core/updater.ts
+var Updater = class _Updater {
+  #phase = "Construct" /* Construct */;
+  #sourceDocument;
+  #patches;
+  #sourceVersionId;
+  #verificationMethod;
+  #beaconService;
+  #unsignedUpdate = null;
+  #signedUpdate = null;
+  /**
+   * @internal — Use {@link DidBtcr2.update} to create instances.
+   */
+  constructor(params) {
+    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}.
-   * This process constructs a BTCR2 Unsigned Update conformant to the spec template.
    *
    * @param {Btcr2DidDocument} sourceDocument The source DID document to be updated.
-   * @param {PatchOperation[]} patches The array of JSON Patch operations to apply to the sourceDocument.
+   * @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} InvalidDid if sourceDocument.id does not match identifier.
+   * @throws {UpdateError} If the target document fails DID Core validation.
    */
   static construct(sourceDocument, patches, sourceVersionId) {
     const unsignedUpdate = {
@@ -138957,13 +138976,12 @@ var Update = class {
   }
   /**
    * Implements subsection {@link http://dcdpr.github.io/did-btcr2/operations/update.html#construct-btcr2-signed-update | 7.3.c Construct BTCR2 Signed Update }.
-   * This process constructs a BTCR2 Signed Update from a BTCR2 Unsigned Update.
    *
-   * @param {string} did The did-btcr2 identifier to derive the root capability from
-   * @param {UnsignedBTCR2Update} unsignedUpdate The updatePayload object to be signed
-   * @param {DidVerificationMethod} verificationMethod The verificationMethod object to be used for signing
-   * @returns {SignedBTCR2Update} Did update payload secured with a proof => SignedBTCR2Update
-   * @throws {UpdateError} if the privateKeyBytes are invalid
+   * @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, unsignedUpdate, verificationMethod, secretKey) {
     const controller = verificationMethod.controller;
@@ -138988,17 +139006,141 @@ var Update = class {
   }
   /**
    * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#announce-did-update | 7.3.d Announce DID Update}.
-   * BTCR2 Signed Updates are announced to the Bitcoin blockchain depending on the Beacon Type.
-   * @param {BeaconService} beaconService The BeaconService object representing the funded beacon to announce the update to.
-   * @param {SignedBTCR2Update} update The signed update object to be announced.
-   * @param {KeyBytes} secretKey The private key used to sign the update for announcement.
-   * @returns {SignedBTCR2Update} The SignedBTCR2Update object containing data to validate the Beacon Signal
-   * @throws {UpdateError} if the beaconService type is invalid
+   * 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, update, secretKey, bitcoin3) {
     const beacon = BeaconFactory.establish(beaconService);
-    const result = await beacon.broadcastSignal(update, secretKey, bitcoin3);
-    return result;
+    return beacon.broadcastSignal(update, secretKey, bitcoin3);
+  }
+  // ─── Private instance wrappers ─────────────────────────────────────────────
+  // Delegate to the public statics with bound instance fields for cleaner
+  // advance/provide code.
+  #construct() {
+    return _Updater.construct(this.#sourceDocument, this.#patches, this.#sourceVersionId);
+  }
+  #sign(secretKey) {
+    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() {
+    while (true) {
+      switch (this.#phase) {
+        // Phase: Construct
+        // Build the unsigned update from source doc + patches. Pure, synchronous.
+        case "Construct" /* Construct */: {
+          this.#unsignedUpdate = this.#construct();
+          this.#phase = "Sign" /* Sign */;
+          continue;
+        }
+        // Phase: Sign
+        // Emit NeedSigningKey — the caller supplies the secret key (or a KMS signature).
+        case "Sign" /* 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 "Fund" /* 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 "Broadcast" /* Broadcast */: {
+          return {
+            status: "action-required",
+            needs: [{
+              kind: "NeedBroadcast",
+              beaconService: this.#beaconService,
+              signedUpdate: this.#signedUpdate
+            }]
+          };
+        }
+        // Phase: Complete
+        case "Complete" /* Complete */: {
+          return {
+            status: "complete",
+            result: { signedUpdate: this.#signedUpdate }
+          };
+        }
+      }
+    }
+  }
+  provide(need, data) {
+    switch (need.kind) {
+      case "NeedSigningKey": {
+        if (this.#phase !== "Sign" /* 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 = "Fund" /* Fund */;
+        break;
+      }
+      case "NeedFunding": {
+        if (this.#phase !== "Fund" /* Fund */) {
+          throw new UpdateError(
+            `Cannot provide NeedFunding: updater phase is ${this.#phase}, expected Fund.`,
+            INVALID_DID_UPDATE,
+            { phase: this.#phase }
+          );
+        }
+        this.#phase = "Broadcast" /* Broadcast */;
+        break;
+      }
+      case "NeedBroadcast": {
+        if (this.#phase !== "Broadcast" /* Broadcast */) {
+          throw new UpdateError(
+            `Cannot provide NeedBroadcast: updater phase is ${this.#phase}, expected Broadcast.`,
+            INVALID_DID_UPDATE,
+            { phase: this.#phase }
+          );
+        }
+        this.#phase = "Complete" /* Complete */;
+        break;
+      }
+    }
   }
 };
 
@@ -139068,42 +139210,35 @@ var DidBtcr2 = class {
     });
   }
   /**
-   * 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.
-   *
-   * 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.
+   * Entry point for section {@link https://dcdpr.github.io/did-btcr2/#update | 7.3 Update}.
+   *
+   * 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 async update({
+  static update({
     sourceDocument,
     patches,
     sourceVersionId,
     verificationMethodId,
-    beaconId,
-    signingMaterial,
-    bitcoin: bitcoin3
+    beaconId
   }) {
-    if (!signingMaterial) {
-      throw new UpdateError(
-        "Missing signing material for update",
-        INVALID_DID_UPDATE,
-        { signingMaterial }
-      );
-    }
-    const secretKey = typeof signingMaterial === "string" ? hexToBytes(signingMaterial) : signingMaterial;
     if (!sourceDocument.capabilityInvocation?.some((vr) => vr === verificationMethodId)) {
       throw new UpdateError(
         "Invalid verificationMethodId: not authorized for capabilityInvocation",
@@ -139133,8 +139268,6 @@ var DidBtcr2 = class {
         verificationMethod
       );
     }
-    const update = Update.construct(sourceDocument, patches, sourceVersionId);
-    const signed = Update.sign(sourceDocument.id, update, verificationMethod, secretKey);
     const beaconService = sourceDocument.service.filter((service) => service.id === beaconId).filter((service) => !!service).shift();
     if (!beaconService) {
       throw new UpdateError(
@@ -139143,15 +139276,13 @@ var DidBtcr2 = class {
         { sourceDocument, beaconId }
       );
     }
-    if (!bitcoin3) {
-      throw new UpdateError(
-        "Bitcoin connection required for update. Pass a configured `bitcoin` parameter or use DidBtcr2Api which injects it automatically.",
-        INVALID_DID_UPDATE,
-        { beaconId }
-      );
-    }
-    await Update.announce(beaconService, signed, secretKey, bitcoin3);
-    return signed;
+    return new Updater({
+      sourceDocument,
+      patches,
+      sourceVersionId,
+      verificationMethod,
+      beaconService
+    });
   }
   /**
    * Given the W3C DID Document of a `did:btcr2` identifier, return the signing verification method that will be used
@@ -139698,11 +139829,12 @@ export {
   SigningSessionPhase,
   SingletonBeacon,
   SingletonBeaconError,
+  StaticFeeEstimator,
   TransportAdapterError,
   TransportError,
   TransportFactory,
   TypedEventEmitter,
-  Update,
+  Updater,
   VALIDATION_ACK,
   createAggregatedNonceMessage,
   createAuthorizationRequestMessage,