@did-btcr2/api 0.5.0 → 0.8.0

package/src/method.ts

@@ -1,9 +1,10 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { DocumentBytes, HexString, KeyBytes, PatchOperation } from '@did-btcr2/common';
-import { decode as decodeHash, IdentifierTypes, NotImplementedError } from '@did-btcr2/common';
+import type { DocumentBytes, KeyBytes, PatchOperation } from '@did-btcr2/common';
+import { decode as decodeHash, IdentifierTypes, INVALID_DID_UPDATE, NotImplementedError, UpdateError } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import type { Btcr2DidDocument, CASAnnouncement, DidCreateOptions, NeedCASAnnouncement, NeedGenesisDocument, NeedSignedUpdate, ResolutionOptions } from '@did-btcr2/method';
-import { BeaconSignalDiscovery, DidBtcr2 } from '@did-btcr2/method';
+import { BeaconFactory, BeaconSignalDiscovery, DidBtcr2 } from '@did-btcr2/method';
 import type { DidResolutionResult, DidVerificationMethod } from '@web5/dids';
 import type { BitcoinApi } from './bitcoin.js';
 import type { CasApi } from './cas.js';
@@ -162,8 +163,16 @@ export class DidMethodApi {
   }
 
   /**
-   * Update an existing DID document. If a Bitcoin connection is configured on
-   * the API, it is injected automatically.
+   * Update an existing DID document by driving the sans-I/O {@link Updater} state
+   * machine (from @did-btcr2/method). This method handles the I/O side:
+   * - Signing: supplies the {@link Signer} to `NeedSigningKey`.
+   * - Broadcast: establishes a beacon via {@link BeaconFactory} and calls
+   *   `broadcastSignal()` with the bitcoin connection configured on the API.
+   *
+   * For multi-party aggregation of SMT/CAS beacons, the caller should drive the
+   * Updater directly and delegate `NeedBroadcast` to the aggregation runner
+   * rather than using this high-level method.
+   *
    * @param params The update parameters.
    * @returns The signed update.
    */
@@ -173,7 +182,7 @@ export class DidMethodApi {
     sourceVersionId,
     verificationMethodId,
     beaconId,
-    signingMaterial,
+    signer,
     bitcoin,
   }: {
     sourceDocument: Btcr2DidDocument;
@@ -181,19 +190,73 @@ export class DidMethodApi {
     sourceVersionId: number;
     verificationMethodId: string;
     beaconId: string;
-    signingMaterial?: KeyBytes | HexString;
+    signer: Signer;
     bitcoin?: BitcoinConnection;
   }): Promise<SignedBTCR2Update> {
-    const btcConnection = bitcoin ?? this.#btc?.connection ?? undefined;
-    return await DidBtcr2.update({
+    // Bitcoin connection resolution order: per-call `bitcoin` param wins over the
+    // BitcoinApi injected at DidBtcr2Api construction time. One of the two must
+    // be present; this can't be encoded in the type system, so it's a runtime check.
+    const btcConnection = bitcoin ?? this.#btc?.connection;
+    if(!btcConnection) {
+      throw new UpdateError(
+        'Bitcoin connection required for update. Pass a configured `bitcoin` parameter '
+        + 'or configure a BitcoinApi on the DidBtcr2Api instance.',
+        INVALID_DID_UPDATE, { beaconId }
+      );
+    }
+
+    this.#log.debug('Updating DID', sourceDocument.id, { beaconId, verificationMethodId });
+
+    // Factory validates and returns a sans-I/O state machine
+    const updater = DidBtcr2.update({
       sourceDocument,
       patches,
       sourceVersionId,
       verificationMethodId,
       beaconId,
-      signingMaterial,
-      bitcoin : btcConnection,
     });
+
+    // Drive the state machine. All I/O (signing delegation, Bitcoin broadcast)
+    // happens inside the need-handlers below — the Updater itself is pure.
+    let state = updater.advance();
+    while(state.status === 'action-required') {
+      for(const need of state.needs) {
+        switch(need.kind) {
+          case 'NeedSigningKey': {
+            this.#log.debug('Providing signer for', need.verificationMethodId);
+            updater.provide(need, signer);
+            break;
+          }
+          case 'NeedFunding': {
+            this.#log.debug('Checking funding for beacon address %s', need.beaconAddress);
+            const utxos = await btcConnection.rest.address.getUtxos(need.beaconAddress);
+            if(!utxos.length) {
+              throw new UpdateError(
+                `Beacon address ${need.beaconAddress} is unfunded. `
+                + 'Send BTC to this address before broadcasting the update.',
+                INVALID_DID_UPDATE, { beaconAddress: need.beaconAddress }
+              );
+            }
+            this.#log.debug('Beacon address funded (%d UTXOs)', utxos.length);
+            updater.provide(need);
+            break;
+          }
+          case 'NeedBroadcast': {
+            this.#log.debug(
+              'Broadcasting signed update via %s beacon', need.beaconService.type
+            );
+            const beacon = BeaconFactory.establish(need.beaconService);
+            await beacon.broadcastSignal(need.signedUpdate, signer, btcConnection);
+            updater.provide(need);
+            break;
+          }
+        }
+      }
+      state = updater.advance();
+    }
+
+    this.#log.debug('DID update complete', sourceDocument.id);
+    return state.result.signedUpdate;
   }
 
   /**
@@ -217,8 +280,9 @@ export class DidMethodApi {
    *   .buildUpdate(currentDoc)
    *   .patch({ op: 'add', path: '/service/1', value: newService })
    *   .version(2)
-   *   .signer('#initialKey')
+   *   .verificationMethodId('#initialKey')
    *   .beacon('#beacon-0')
+   *   .signer(new LocalSigner(secretKey))
    *   .execute();
    * ```
    */
@@ -252,7 +316,7 @@ export class UpdateBuilder {
   #sourceVersionId?: number;
   #verificationMethodId?: string;
   #beaconId?: string;
-  #signingMaterial?: KeyBytes | HexString;
+  #signer?: Signer;
   #bitcoin?: BitcoinConnection;
 
   /** @internal */
@@ -279,8 +343,8 @@ export class UpdateBuilder {
     return this;
   }
 
-  /** Set the verification method ID used for signing. */
-  signer(methodId: string): this {
+  /** Set the verification method ID used for signing the update. */
+  verificationMethodId(methodId: string): this {
     this.#verificationMethodId = methodId;
     return this;
   }
@@ -291,32 +355,44 @@ export class UpdateBuilder {
     return this;
   }
 
-  /** Set the signing material (secret key bytes or hex). */
-  signingMaterial(material: KeyBytes | HexString): this {
-    this.#signingMaterial = material;
+  /**
+   * Set the {@link Signer} that produces the update's BIP-340 Schnorr proof
+   * and the beacon transaction's ECDSA input signature. Use `LocalSigner`
+   * for in-process secret keys, `KeyManagerSigner` for KMS-managed keys
+   * (AWS, Vault, HSM, etc.), or any custom adapter implementing the `Signer`
+   * interface.
+   */
+  signer(s: Signer): this {
+    this.#signer = s;
     return this;
   }
 
   /** Override the Bitcoin connection for this update. */
-  withBitcoin(connection: BitcoinConnection): this {
+  bitcoin(connection: BitcoinConnection): this {
     this.#bitcoin = connection;
     return this;
   }
 
   /**
    * Execute the update.
-   * @throws {Error} If required fields (version, signer, beacon) are missing.
+   * @throws {Error} If required fields (version, verificationMethodId, beacon, signer) are missing.
    */
   async execute(): Promise<SignedBTCR2Update> {
     if (this.#sourceVersionId === undefined) {
       throw new Error('UpdateBuilder: sourceVersionId is required. Call .version(id) before .execute().');
     }
     if (!this.#verificationMethodId) {
-      throw new Error('UpdateBuilder: verificationMethodId is required. Call .signer(id) before .execute().');
+      throw new Error(
+        'UpdateBuilder: verificationMethodId is required. '
+        + 'Call .verificationMethodId(id) before .execute().'
+      );
     }
     if (!this.#beaconId) {
       throw new Error('UpdateBuilder: beaconId is required. Call .beacon(id) before .execute().');
     }
+    if (!this.#signer) {
+      throw new Error('UpdateBuilder: signer is required. Call .signer(s) before .execute().');
+    }
 
     return this.#methodApi.update({
       sourceDocument       : this.#sourceDocument,
@@ -324,7 +400,7 @@ export class UpdateBuilder {
       sourceVersionId      : this.#sourceVersionId,
       verificationMethodId : this.#verificationMethodId,
       beaconId             : this.#beaconId,
-      signingMaterial      : this.#signingMaterial,
+      signer               : this.#signer,
       bitcoin              : this.#bitcoin,
     });
   }

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { HttpExecutor, NetworkName, RestConfig, RpcConfig } from '@did-btcr2/bitcoin';
-import type { KeyManager } from '@did-btcr2/kms';
+import type { KeyManager } from '@did-btcr2/key-manager';
 import type { Btcr2DidDocument } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
 import type { CasConfig } from './cas.js';

package/dist/esm/kms.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"kms.js","sourceRoot":"","sources":["../../src/kms.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,GAAG,GAEJ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,OAAO,aAAa;IACxB,uCAAuC;IAC9B,GAAG,CAAa;IAEzB,4EAA4E;IAC5E,YAAY,GAAgB;QAC1B,IAAI,CAAC,GAAG,GAAG,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC;IAC9B,CAAC;IAED,8CAA8C;IAC9C,WAAW,CAAC,OAA4B;QACtC,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,4CAA4C;IAC5C,SAAS,CAAC,EAAiB;QACzB,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,qDAAqD;IACrD,YAAY,CAAC,EAAkB;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,6CAA6C;IAC7C,MAAM,CAAC,EAAkB,EAAE,OAA0B;QACnD,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,EAAiB;QACtB,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CACb,wEAAwE;kBACtE,uDAAuD,CAC1D,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,wCAAwC;IACxC,QAAQ;QACN,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC7B,CAAC;IAED,iCAAiC;IACjC,SAAS,CAAC,EAAiB,EAAE,UAA+B,EAAE;QAC5D,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAW,EAAE,EAAkB,EAAE,OAAqB;QACzD,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,sCAAsC;IACtC,MAAM,CAAC,SAAyB,EAAE,IAAW,EAAE,EAAkB,EAAE,OAAqB;QACtF,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IAED,gCAAgC;IAChC,MAAM,CAAC,IAAgB;QACrB,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"kms.d.ts","sourceRoot":"","sources":["../../src/kms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EAAC,MAAM,gBAAgB,CAAC;AACpC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EAErB,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAGxB;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB,4EAA4E;gBAChE,GAAG,CAAC,EAAE,UAAU;IAI5B,8CAA8C;IAC9C,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,aAAa;IAIxD,4CAA4C;IAC5C,SAAS,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI;IAIlC,qDAAqD;IACrD,YAAY,CAAC,EAAE,CAAC,EAAE,aAAa,GAAG,KAAK;IAIvC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,aAAa;IAIrE;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,aAAa,GAAG,cAAc;IAUzC,wCAAwC;IACxC,QAAQ,IAAI,aAAa,EAAE;IAI3B,iCAAiC;IACjC,SAAS,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI;IAIrE;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,cAAc;IAK5E,sCAAsC;IACtC,MAAM,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO;IAIlG,gCAAgC;IAChC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS;CAGpC"}