@did-btcr2/method 0.27.0 → 0.28.0

package/dist/browser.js

@@ -97563,11 +97563,12 @@ a=end-of-candidates
     SigningSessionPhase: () => SigningSessionPhase,
     SingletonBeacon: () => SingletonBeacon,
     SingletonBeaconError: () => SingletonBeaconError,
+    StaticFeeEstimator: () => StaticFeeEstimator,
     TransportAdapterError: () => TransportAdapterError,
     TransportError: () => TransportError,
     TransportFactory: () => TransportFactory,
     TypedEventEmitter: () => TypedEventEmitter,
-    Update: () => Update,
+    Updater: () => Updater,
     VALIDATION_ACK: () => VALIDATION_ACK,
     createAggregatedNonceMessage: () => createAggregatedNonceMessage,
     createAuthorizationRequestMessage: () => createAuthorizationRequestMessage,
@@ -138629,9 +138630,8 @@ a=end-of-candidates
   // 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
@@ -138997,17 +138997,37 @@ a=end-of-candidates
     }
   };
 
-  // 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 = {
@@ -139037,13 +139057,12 @@ a=end-of-candidates
     }
     /**
      * 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;
@@ -139068,17 +139087,141 @@ a=end-of-candidates
     }
     /**
      * 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;
+        }
+      }
     }
   };
 
@@ -139148,42 +139291,35 @@ a=end-of-candidates
       });
     }
     /**
-     * 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",
@@ -139213,8 +139349,6 @@ a=end-of-candidates
           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(
@@ -139223,15 +139357,13 @@ a=end-of-candidates
           { 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