@did-btcr2/method 0.53.0 → 0.54.0

package/dist/types/core/updater.d.ts

@@ -3,6 +3,8 @@ import type { PatchOperation } from '@did-btcr2/common';
 import type { Signer } from '@did-btcr2/keypair';
 import type { SignedBTCR2Update, UnsignedBTCR2Update } from './btcr2-update.js';
 import { type Btcr2DidDocument, type DidVerificationMethod } from '../utils/did-document.js';
+import type { BroadcastResult } from './beacon/beacon.js';
+import type { CASBroadcastOptions } from './beacon/cas-beacon.js';
 import type { BeaconService } from './beacon/interfaces.js';
 /**
  * The updater needs the caller to supply a {@link Signer} for the given
@@ -47,10 +49,15 @@ 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, secretKey, bitcoin)` or
+ * `Updater.announce(beaconService, signedUpdate, signer, bitcoin, options?)` or
  * `BeaconFactory.establish(beaconService).broadcastSignal(...)`. For multi-party
  * aggregate beacons, hand off to the aggregation protocol.
  *
+ * Both single-party paths return a `BroadcastResult`; capture it. Beyond the txid,
+ * it carries the per-beacon-type sidecar artifacts: the CAS Announcement (CAS
+ * beacons) and the SMT inclusion proof (SMT beacons), whose embedded nonce exists
+ * nowhere else, so a discarded proof makes the signal permanently unresolvable.
+ *
  * After the broadcast succeeds, the caller calls `updater.provide(need)` (with no
  * data) to transition the updater to Complete.
  */
@@ -113,10 +120,14 @@ export interface UpdaterParams {
  *         // Check UTXOs at need.beaconAddress, fund if needed
  *         updater.provide(need);
  *         break;
- *       case 'NeedBroadcast':
- *         await Updater.announce(need.beaconService, need.signedUpdate, signer, bitcoin);
+ *       case 'NeedBroadcast': {
+ *         // 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);
  *         updater.provide(need);
  *         break;
+ *       }
  *     }
  *   }
  *   state = updater.advance();
@@ -170,9 +181,13 @@ export declare class Updater {
      * @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.
-     * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+     * @param {CASBroadcastOptions} [options] Optional broadcast configuration (fee estimator,
+     *   change address, and, for CAS beacons, a `casPublish` callback invoked before the
+     *   transaction broadcast; other beacon types ignore `casPublish`).
+     * @returns {Promise<BroadcastResult>} The broadcast artifacts: the signed update, the signal
+     *   txid, and any per-beacon-type sidecar data (CAS announcement / SMT proof).
      */
-    static announce(beaconService: BeaconService, update: SignedBTCR2Update, signer: Signer, bitcoin: BitcoinConnection): Promise<SignedBTCR2Update>;
+    static announce(beaconService: BeaconService, update: SignedBTCR2Update, signer: Signer, bitcoin: BitcoinConnection, options?: CASBroadcastOptions): Promise<BroadcastResult>;
     /**
      * Advance the state machine. Returns either:
      * - `{ status: 'action-required', needs }` caller must provide data via {@link provide}

package/dist/types/core/updater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"updater.d.ts","sourceRoot":"","sources":["../../../src/core/updater.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"updater.d.ts","sourceRoot":"","sources":["../../../src/core/updater.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.53.0",
+  "version": "0.54.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",
@@ -69,11 +69,11 @@
     "@scure/base": "^1.2.6",
     "@scure/btc-signer": "^1.8.1",
     "@web5/dids": "^1.2.0",
-    "@did-btcr2/bitcoin": "^0.8.0",
     "@did-btcr2/common": "^9.1.0",
-    "@did-btcr2/keypair": "^0.13.1",
     "@did-btcr2/smt": "^0.3.0",
-    "@did-btcr2/cryptosuite": "^9.0.0"
+    "@did-btcr2/cryptosuite": "^9.0.0",
+    "@did-btcr2/keypair": "^0.13.1",
+    "@did-btcr2/bitcoin": "^0.8.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/src/core/beacon/beacon.ts

@@ -4,8 +4,9 @@ import type { SignedBTCR2Update } from '../btcr2-update.js';
 import type { Signer } from '@did-btcr2/keypair';
 import { concatBytes, hexToBytes } from '@noble/hashes/utils.js';
 import { Address, OutScript, p2pkh, p2tr, p2wpkh, Script, SigHash, Transaction } from '@scure/btc-signer';
+import type { SMTProof } from '../interfaces.js';
 import type { BeaconProcessResult } from '../resolver.js';
-import type { SidecarData } from '../types.js';
+import type { CASAnnouncement, SidecarData } from '../types.js';
 import { BeaconError } from './error.js';
 import { DEFAULT_FEE_ESTIMATOR } from './fee-estimator.js';
 import type { FeeEstimator } from './fee-estimator.js';
@@ -185,6 +186,33 @@ export interface BroadcastOptions {
   changeAddress?: string;
 }
 
+/**
+ * Result of a single-party beacon broadcast. Beyond the signed update itself,
+ * it carries every artifact the broadcast produced that a resolver will later
+ * need: without them, some signals are unresolvable (the SMT proof) or the
+ * controller cannot distribute the sidecar data the spec requires them to
+ * retain (the CAS announcement).
+ */
+export interface BroadcastResult {
+  /** The signed update that was broadcast. */
+  signedUpdate: SignedBTCR2Update;
+  /** Transaction id of the on-chain beacon signal. */
+  txid: string;
+  /**
+   * The CAS Announcement whose hash rode in the OP_RETURN output. CAS beacons
+   * only. Capture it for sidecar distribution (or publish it to a CAS): a
+   * resolver cannot process the signal without it.
+   */
+  announcement?: CASAnnouncement;
+  /**
+   * SMT inclusion proof for the broadcast update, including the nonce the leaf
+   * was blinded with. SMT beacons only. Capture it for sidecar distribution:
+   * the nonce is generated at broadcast time and appears nowhere else, so a
+   * signal whose proof is dropped is permanently unresolvable.
+   */
+  proof?: SMTProof;
+}
+
 /**
  * Unsigned beacon transaction + the prev-output metadata needed for downstream
  * signing (single-party ECDSA or multi-party MuSig2 Taproot).
@@ -544,14 +572,15 @@ export abstract class SinglePartyBeacon {
    *   ECDSA for P2PKH / P2WPKH singletons, Schnorr (BIP-340) for P2TR key-path.
    * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
    * @param {BroadcastOptions} [options] Optional broadcast configuration (e.g. fee estimator).
-   * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+   * @returns {Promise<BroadcastResult>} The broadcast artifacts: the signed update, the
+   *   signal txid, and the per-beacon-type sidecar data (CAS announcement / SMT proof).
    */
   abstract broadcastSignal(
     signedUpdate: SignedBTCR2Update,
     signer: Signer,
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
-  ): Promise<SignedBTCR2Update>;
+  ): Promise<BroadcastResult>;
 
   /**
    * Build + sign + broadcast a singleton beacon signal transaction. The beacon

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

@@ -4,14 +4,15 @@ import type { SignedBTCR2Update } from '../btcr2-update.js';
 import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
-import type { BroadcastOptions } from './beacon.js';
+import type { BroadcastOptions, BroadcastResult } from './beacon.js';
 import { SinglePartyBeacon } from './beacon.js';
 import type { BeaconService, BeaconSignal, BlockMetadata, CasPublishFn } from './interfaces.js';
 
 /**
  * CAS-specific broadcast options: extends {@link BroadcastOptions} with an optional
- * `casPublish` callback used to publish the CAS Announcement off-chain after the
- * OP_RETURN signal is broadcast.
+ * `casPublish` callback used to publish the CAS Announcement off-chain before the
+ * OP_RETURN signal transaction is broadcast. A publish failure aborts the broadcast
+ * while the beacon UTXO is still unspent.
  */
 export interface CASBroadcastOptions extends BroadcastOptions {
   casPublish?: CasPublishFn;
@@ -134,17 +135,23 @@ export class CASBeacon extends SinglePartyBeacon {
   /**
    * Broadcasts a CAS Beacon signal to the Bitcoin network.
    *
-   * Creates a CAS Announcement mapping the DID to the update hash, broadcasts the hash of the
-   * announcement via OP_RETURN, and optionally publishes the announcement off-chain via the
-   * supplied `casPublish` callback. UTXO selection, PSBT construction, fee estimation, signing,
+   * Creates a CAS Announcement mapping the DID to the update hash, optionally publishes the
+   * announcement off-chain via the supplied `casPublish` callback, then broadcasts the hash of
+   * the announcement via OP_RETURN. UTXO selection, PSBT construction, fee estimation, signing,
    * and broadcast are delegated to {@link SinglePartyBeacon.buildSignAndBroadcast}.
    *
+   * The CAS publish happens **before** the transaction broadcast: a publish failure aborts the
+   * operation while the beacon UTXO is still unspent, so no on-chain signal ever points at an
+   * announcement that failed to publish. The announcement is content-addressed, so a retry
+   * after a failed broadcast re-publishes the same bytes to the same address (idempotent).
+   *
    * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.
    * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
    * @param {CASBroadcastOptions} [options] Optional broadcast configuration, including a
    *   `casPublish` callback to publish the announcement off-chain and a `feeEstimator`.
-   * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+   * @returns {Promise<BroadcastResult>} The signed update, the signal txid, and the CAS
+   *   Announcement (capture it for sidecar distribution when no `casPublish` is supplied).
    * @throws {BeaconError} if the bitcoin address is invalid, unfunded, or UTXO cannot cover the fee.
    */
   async broadcastSignal(
@@ -152,7 +159,7 @@ export class CASBeacon extends SinglePartyBeacon {
     signer: Signer,
     bitcoin: BitcoinConnection,
     options?: CASBroadcastOptions
-  ): Promise<SignedBTCR2Update> {
+  ): Promise<BroadcastResult> {
     // Extract the DID from the beacon service id (strip the #fragment)
     const did = this.service.id.split('#')[0];
 
@@ -165,14 +172,15 @@ export class CASBeacon extends SinglePartyBeacon {
     // Canonicalize and hash the CAS Announcement for the OP_RETURN output
     const announcementHash = hash(canonicalize(casAnnouncement));
 
-    // Delegate UTXO selection, PSBT construction, fee estimation, signing, and broadcast
-    await this.buildSignAndBroadcast(announcementHash, signer, bitcoin, options);
-
-    // Publish CAS Announcement to content-addressed store if callback provided
+    // Publish the announcement to the content-addressed store before spending the
+    // beacon UTXO, so a publish failure aborts pre-spend.
     if(options?.casPublish) {
       await options.casPublish(casAnnouncement);
     }
 
-    return signedUpdate;
+    // Delegate UTXO selection, PSBT construction, fee estimation, signing, and broadcast
+    const txid = await this.buildSignAndBroadcast(announcementHash, signer, bitcoin, options);
+
+    return { signedUpdate, txid, announcement: casAnnouncement };
   }
 }

package/src/core/beacon/interfaces.ts

@@ -68,8 +68,11 @@ export interface BeaconSignal {
 
 /**
  * Callback for publishing a CAS Announcement to a content-addressed store.
- * The method package defines this type; the api layer provides the implementation
- * (e.g., via CasApi.publish backed by IPFS/Helia).
+ * The method package defines this type; the caller provides the implementation
+ * (e.g., the api layer's CasApi.publish backed by any CAS executor).
+ *
+ * Invoked before the beacon signal transaction is broadcast, so a thrown error
+ * aborts the operation while the beacon UTXO is still unspent.
  *
  * @param announcement The CAS Announcement object (DID to update hash mapping).
  */

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

@@ -4,7 +4,7 @@ import type { SignedBTCR2Update } from '../btcr2-update.js';
 import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
-import type { BroadcastOptions } from './beacon.js';
+import type { BroadcastOptions, BroadcastResult } from './beacon.js';
 import { SinglePartyBeacon } from './beacon.js';
 import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
 
@@ -70,7 +70,7 @@ export class SingletonBeacon extends SinglePartyBeacon {
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.
    * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
    * @param {BroadcastOptions} [options] Optional broadcast configuration (e.g. fee estimator).
-   * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+   * @returns {Promise<BroadcastResult>} The signed update and the signal txid.
    * @throws {BeaconError} if the bitcoin address is invalid, unfunded, or UTXO cannot cover the fee.
    */
   async broadcastSignal(
@@ -78,9 +78,9 @@ export class SingletonBeacon extends SinglePartyBeacon {
     signer: Signer,
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
-  ): Promise<SignedBTCR2Update> {
+  ): Promise<BroadcastResult> {
     const signalBytes = hash(canonicalize(signedUpdate));
-    await this.buildSignAndBroadcast(signalBytes, signer, bitcoin, options);
-    return signedUpdate;
+    const txid = await this.buildSignAndBroadcast(signalBytes, signer, bitcoin, options);
+    return { signedUpdate, txid };
   }
 }

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

@@ -6,7 +6,7 @@ import { base64UrlToHash, blockHash, BTCR2MerkleTree, didToIndex, hashToHex, ver
 import { randomBytes } from '@noble/hashes/utils';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';
-import type { BroadcastOptions } from './beacon.js';
+import type { BroadcastOptions, BroadcastResult } from './beacon.js';
 import { SinglePartyBeacon } from './beacon.js';
 import { SMTBeaconError } from './error.js';
 import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
@@ -133,7 +133,9 @@ export class SMTBeacon extends SinglePartyBeacon {
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.
    * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
    * @param {BroadcastOptions} [options] Optional broadcast configuration (e.g. fee estimator).
-   * @return {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+   * @return {Promise<BroadcastResult>} The signed update, the signal txid, and the SMT
+   *   inclusion proof (with the leaf nonce embedded). The proof MUST be captured for sidecar
+   *   distribution: the nonce exists only here, so the on-chain signal is unresolvable without it.
    * @throws {BeaconError} if the bitcoin address is invalid, unfunded, or UTXO cannot cover the fee.
    */
   async broadcastSignal(
@@ -141,7 +143,7 @@ export class SMTBeacon extends SinglePartyBeacon {
     signer: Signer,
     bitcoin: BitcoinConnection,
     options?: BroadcastOptions
-  ): Promise<SignedBTCR2Update> {
+  ): Promise<BroadcastResult> {
     // Extract the DID from the beacon service id (strip the #fragment)
     const did = this.service.id.split('#')[0];
 
@@ -152,9 +154,14 @@ export class SMTBeacon extends SinglePartyBeacon {
     tree.addEntries([{ did, nonce, signedUpdate: canonicalBytes }]);
     tree.finalize();
 
+    // Serialize the inclusion proof (carrying the nonce and updateId) before
+    // broadcasting: it is the only artifact that can link the on-chain root back
+    // to the update, and the nonce it embeds is irrecoverable once dropped.
+    const proof = tree.proof(did);
+
     // Root hash is the signal bytes for the OP_RETURN output
-    await this.buildSignAndBroadcast(tree.rootHash, signer, bitcoin, options);
+    const txid = await this.buildSignAndBroadcast(tree.rootHash, signer, bitcoin, options);
 
-    return signedUpdate;
+    return { signedUpdate, txid, proof };
   }
 }

package/src/core/updater.ts

@@ -5,6 +5,8 @@ import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import type { Signer } from '@did-btcr2/keypair';
 import type { Btcr2DataIntegrityConfig, SignedBTCR2Update, UnsignedBTCR2Update } from './btcr2-update.js';
 import { DidDocument, type Btcr2DidDocument, type DidVerificationMethod } from '../utils/did-document.js';
+import type { BroadcastResult } from './beacon/beacon.js';
+import type { CASBroadcastOptions } from './beacon/cas-beacon.js';
 import { BeaconFactory } from './beacon/factory.js';
 import type { BeaconService } from './beacon/interfaces.js';
 
@@ -56,10 +58,15 @@ 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, secretKey, bitcoin)` or
+ * `Updater.announce(beaconService, signedUpdate, signer, bitcoin, options?)` or
  * `BeaconFactory.establish(beaconService).broadcastSignal(...)`. For multi-party
  * aggregate beacons, hand off to the aggregation protocol.
  *
+ * Both single-party paths return a `BroadcastResult`; capture it. Beyond the txid,
+ * it carries the per-beacon-type sidecar artifacts: the CAS Announcement (CAS
+ * beacons) and the SMT inclusion proof (SMT beacons), whose embedded nonce exists
+ * nowhere else, so a discarded proof makes the signal permanently unresolvable.
+ *
  * After the broadcast succeeds, the caller calls `updater.provide(need)` (with no
  * data) to transition the updater to Complete.
  */
@@ -137,10 +144,14 @@ export interface UpdaterParams {
  *         // Check UTXOs at need.beaconAddress, fund if needed
  *         updater.provide(need);
  *         break;
- *       case 'NeedBroadcast':
- *         await Updater.announce(need.beaconService, need.signedUpdate, signer, bitcoin);
+ *       case 'NeedBroadcast': {
+ *         // 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);
  *         updater.provide(need);
  *         break;
+ *       }
  *     }
  *   }
  *   state = updater.advance();
@@ -315,16 +326,21 @@ export class Updater {
    * @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.
-   * @returns {Promise<SignedBTCR2Update>} The signed update that was broadcast.
+   * @param {CASBroadcastOptions} [options] Optional broadcast configuration (fee estimator,
+   *   change address, and, for CAS beacons, a `casPublish` callback invoked before the
+   *   transaction broadcast; other beacon types ignore `casPublish`).
+   * @returns {Promise<BroadcastResult>} The broadcast artifacts: the signed update, the signal
+   *   txid, and any per-beacon-type sidecar data (CAS announcement / SMT proof).
    */
   static async announce(
     beaconService: BeaconService,
     update: SignedBTCR2Update,
     signer: Signer,
-    bitcoin: BitcoinConnection
-  ): Promise<SignedBTCR2Update> {
+    bitcoin: BitcoinConnection,
+    options?: CASBroadcastOptions
+  ): Promise<BroadcastResult> {
     const beacon = BeaconFactory.establish(beaconService);
-    return beacon.broadcastSignal(update, signer, bitcoin);
+    return beacon.broadcastSignal(update, signer, bitcoin, options);
   }
 
   // Private instance wrappers