@did-btcr2/method 0.65.0 → 0.66.0

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

@@ -1,16 +1,26 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import { canonicalize } from '@did-btcr2/common';
+import { canonicalHashBytes, INVALID_SIGNAL_DATA } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '../btcr2-update.js';
 import type { Signer } from '@did-btcr2/keypair';
-import { base64UrlToHash, blockHash, BTCR2MerkleTree, didToIndex, hashToHex, verifySerializedProof } from '@did-btcr2/smt';
+import { base64UrlToHash, BTCR2MerkleTree, hashToHex, verifyProof } from '@did-btcr2/smt';
 import { randomBytes } from '@noble/hashes/utils';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
+import type { SMTProof } from '../interfaces.js';
 import type { SidecarData } from '../types.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';
 
+/** The hex of the base64url `id` of a proof, or `undefined` if the id does not decode to 32 bytes. */
+function proofIdHex(proof: SMTProof): string | undefined {
+  try {
+    return hashToHex(base64UrlToHash(proof.id));
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#smt-beacon | SMT Beacon}.
  *
@@ -36,15 +46,17 @@ export class SMTBeacon extends SinglePartyBeacon {
   /**
    * Implements {@link https://dcdpr.github.io/did-btcr2/operations/resolve.html#process-smt-beacon | 7.2.e.1 Process SMT Beacon}.
    *
-   * For each signal, the signalBytes contain the hex-encoded SMT root hash.
-   * This method looks up the SMT Proof from the sidecar by root hash,
-   * validates the Merkle inclusion proof, and retrieves the corresponding
-   * signed update using the proof's updateId.
+   * For each signal, the signalBytes contain the hex-encoded SMT root hash
+   * (`smt_root`). This method looks up the SMT Proof from the sidecar by root
+   * hash, checks that the id of the proof is the root, verifies the proof with
+   * the SMT Proof Verification algorithm, and retrieves the signed update by the
+   * proof's updateId. A proof with no updateId announces no update for the DID.
    *
    * @param {Array<BeaconSignal>} signals The array of Beacon Signals to process.
    * @param {SidecarData} sidecar The sidecar data associated with the SMT Beacon.
    * @returns {BeaconProcessResult} Successfully resolved updates and any data needs.
-   * @throws {SMTBeaconError} if proof verification fails or proof is malformed.
+   * @throws {SMTBeaconError} `INVALID_SIGNAL_DATA` if the id of the proof is not the
+   *   signal root, or if the proof does not verify.
    */
   processSignals(
     signals: Array<BeaconSignal>,
@@ -57,7 +69,8 @@ export class SMTBeacon extends SinglePartyBeacon {
     const did = this.did;
 
     for(const signal of signals) {
-      // Signal bytes are the hex-encoded SMT root hash; smtMap is keyed by proof.id (also hex)
+      // "Process SMT Beacon": the signal bytes are smt_root, the hex SMT root hash.
+      // The smtMap is keyed by the hex of proof.id. No entry = a need for the proof.
       const smtProof = sidecar.smtMap.get(signal.signalBytes);
 
       if(!smtProof) {
@@ -70,39 +83,32 @@ export class SMTBeacon extends SinglePartyBeacon {
         continue;
       }
 
-      // Nonce is required for proof verification (inclusion and non-inclusion).
-      if(!smtProof.nonce) {
+      // The id of the proof must equal smt_root. The resolver keys the map by the
+      // hex of the id, so its entries pass. A caller-built map is checked here too.
+      if(proofIdHex(smtProof) !== signal.signalBytes) {
         throw new SMTBeaconError(
-          'SMT proof missing required nonce field.',
-          'INVALID_SMT_PROOF', { smtProof, did }
+          `SMT proof id does not equal the signal root ${signal.signalBytes}.`,
+          INVALID_SIGNAL_DATA, { smtProof, did, smtRootHash: signal.signalBytes }
         );
       }
 
-      // Verify the SMT proof against the on-chain root. Leaf value per spec:
-      // inclusion = hash(hash(nonce) || updateId); non-inclusion = hash(hash(nonce)).
-      // Hash fields are base64url (no padding) per the SMT Proof spec. A
-      // non-inclusion proof (absent updateId) is verified too, not trusted.
-      const index = didToIndex(did);
-      const nonceHash = base64UrlToHash(smtProof.nonce);
-      const candidateHash = smtProof.updateId
-        ? blockHash(blockHash(nonceHash), base64UrlToHash(smtProof.updateId))
-        : blockHash(blockHash(nonceHash));
-      const valid = verifySerializedProof(smtProof, index, candidateHash);
-
-      if(!valid) {
+      // Verify the proof with the SMT Proof Verification algorithm. The nonce and
+      // updateId fields of the proof select the leaf value (four arms). A proof that
+      // does not decode, or that does not walk to the root, is INVALID_SIGNAL_DATA.
+      if(!verifyProof(smtProof, did)) {
         throw new SMTBeaconError(
-          'SMT proof verification failed.',
-          'INVALID_SMT_PROOF', { smtProof, did }
+          `SMT proof verification failed for the signal root ${signal.signalBytes}.`,
+          INVALID_SIGNAL_DATA, { smtProof, did, smtRootHash: signal.signalBytes }
         );
       }
 
-      // Non-inclusion proof verified: no update for this DID this epoch, skip.
-      if(!smtProof.updateId) {
+      // No updateId: the signal announces no update for this DID. No tuple.
+      if(smtProof.updateId === undefined) {
         continue;
       }
 
       // Look up the signed update in sidecar updateMap (keyed by hex canonical
-      // hash). The proof's updateId is base64url, so convert to hex to match.
+      // hash). The proof's updateId is the same hash in base64url.
       const updateHashHex = hashToHex(base64UrlToHash(smtProof.updateId));
       const signedUpdate = sidecar.updateMap.get(updateHashHex);
 
@@ -135,7 +141,7 @@ export class SMTBeacon extends SinglePartyBeacon {
    * @param {BitcoinConnection} bitcoin The Bitcoin network connection.
    * @param {BroadcastOptions} [options] Optional broadcast configuration (e.g. fee estimator).
    * @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
+   *   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.
    */
@@ -148,14 +154,14 @@ export class SMTBeacon extends SinglePartyBeacon {
     // The DID keys this beacon's leaf index in the tree.
     const did = this.did;
 
-    // Build a single-entry SMT from the signed update
-    const canonicalBytes = new TextEncoder().encode(canonicalize(signedUpdate));
+    // Build a single-entry SMT in nonce mode: the leaf value is
+    // hash(hash(nonce) + updateId), with updateId the JSON Document Hash of the update.
     const nonce = randomBytes(32);
     const tree = new BTCR2MerkleTree();
-    tree.addEntries([{ did, nonce, signedUpdate: canonicalBytes }]);
+    tree.addEntries([{ did, nonce, updateId: canonicalHashBytes(signedUpdate) }]);
     tree.finalize();
 
-    // Serialize the inclusion proof (carrying the nonce and updateId) before
+    // Serialize the 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);

package/src/core/identifier.ts

@@ -150,8 +150,10 @@ export class Identifier {
     if (typeof network !== 'string') {
       throw new IdentifierError('Expected "network" to be a known network name', INVALID_DID, { network });
     }
-    const networkValue = BitcoinNetworkNames[network as keyof typeof BitcoinNetworkNames] as number | undefined;
-    if (networkValue === undefined) {
+    // The numeric enum also maps a value string to a name: '5' reads as 'mutinynet', and
+    // the low nibble becomes 0 (bitcoin). Only a name maps to a number.
+    const networkValue: unknown = BitcoinNetworkNames[network as keyof typeof BitcoinNetworkNames];
+    if (typeof networkValue !== 'number') {
       throw new IdentifierError('Invalid "network" name', INVALID_DID, { network });
     }
 

package/src/core/interfaces.ts

@@ -76,22 +76,26 @@ export interface ResolutionOptions extends DidResolutionOptions {
 /**
  * {@link https://dcdpr.github.io/did-btcr2/terminology.html#smt-proof | SMT Proof}
  * a set of SHA-256 hashes for nodes in a Sparse Merkle Tree that together form
- * a path from a leaf in the tree to the Merkle root, proving that the leaf is in the tree.
+ * a path from a leaf in the tree to the Merkle root. The proof shows the value of
+ * the leaf at the index of the DID: an update, no update, or an empty index.
  * See {@link https://dcdpr.github.io/did-btcr2/data-structures.html#smt-proof | SMT Proof (data structure)}.
  *
- * All SHA-256 hash fields (`id`, `nonce`, `updateId`, `hashes`) are "base64url"
- * [RFC4648] encoded without padding (43 chars each). `collapsed` is the 256-bit
- * zero-node bitmap, also base64url no-pad (43 chars).
+ * All fields are "base64url" [RFC4648] encoded without padding. `id`, `updateId`,
+ * `collapsed`, and the entries of `hashes` decode to 32 bytes (43 chars each).
+ * `nonce` has any length. The presence of `nonce` and `updateId` selects the leaf
+ * value that the SMT Proof Verification algorithm walks from:
+ * `hash(hash(nonce) + updateId)`, `hash(hash(nonce))`, `updateId`, or the value of
+ * an empty leaf.
  *
  * @example
  * ```json
  * {
- *   "id": "q1H_iaYG0Oq6gbrycYL-r7FjUsJLnIpHDn49TLeONNA",
- *   "nonce": "99jndCBWHpZfmObXlIvRGHaPMgoQKXIETdD4H-XqryE",
- *   "updateId": "njYNViJq2OmhSw1fLfARPCj12RY3VXKGWdS3-7OQ2BE",
- *   "collapsed": "v_________________________________________8",
+ *   "id": "ZSN-lAyRpXG72aK1xLC9sAuRhFGsILupaQXxpkITJuo",
+ *   "nonce": "WYVxNuwz3RBEhnJKM4LvVh2tOdXI9WRUPYqA_qa0klM",
+ *   "updateId": "_YDKmjcnIkHDY6rnRwrO86id5H1Onycy7Bz62jYq6GA",
+ *   "collapsed": "-_________________________________________8",
  *   "hashes": [
- *     "8JWXL7chPKJXwg-i9O1EFTHan_oOO_RmglDpu_ugax0"
+ *     "s-2LV-dfS-x___DBpNeH4KaBBSJj0xCSpn8ZlusZwLo"
  *   ]
  * }
  * ```
@@ -99,23 +103,32 @@ export interface ResolutionOptions extends DidResolutionOptions {
 export interface SMTProof {
   /**
    * base64url (no padding) SHA-256 hash of the root node of the Sparse Merkle Tree.
+   * The resolver compares it to the Signal Bytes of the SMT beacon signal.
    */
   id: string;
   /**
-   * Optional 256-bit nonce generated for each update. base64url, no padding (43 chars).
+   * Optional nonce, one for each index in each Beacon Signal, of any length.
+   * base64url, no padding. Without the nonce that the DID controller used, the
+   * proof of that signal cannot be verified. Absent in no-nonce mode.
    */
   nonce?: string;
   /**
-   * Optional base64url (no padding) canonical hash of the BTCR2 Signed Update.
+   * Optional base64url (no padding) JSON Document Hash of the BTCR2 Signed Update.
+   * Present when the signal announces an update for the DID. Absent when it does not.
    */
   updateId?: string;
   /**
-   * base64url (no padding) bitmap of zero nodes within the path (see: collapsed
-   * leaves). Bit set = empty/zero sibling; bit clear = a sibling hash is present.
+   * base64url (no padding) 256-bit bitmap of the empty siblings on the path from
+   * the leaf to the root. Bit `i` set = the sibling at level `i` is an empty subtree;
+   * bit `i` clear = the next entry of `hashes` is the sibling. Bit `i` is `bitAt(i)`
+   * of the decoded value, counted from the left: bit `0` is the root level, bit
+   * `255` the leaf level. The number of entries in `hashes` plus the number of set
+   * bits is `256`.
    */
   collapsed: string;
   /**
-   * Array of SHA-256 hashes representing the sibling SMT nodes from the leaf, containing the SHA-256 hash of the BTCR2 Signed Update or the “zero identity”, to the root.
+   * Array of the SHA-256 hashes of the non-empty sibling nodes on the path from the
+   * leaf to the root, in that order.
    */
   hashes: string[];
 }

package/src/core/resolver.ts

@@ -10,9 +10,11 @@ import {
   INVALID_DID,
   INVALID_DID_UPDATE,
   INVALID_OPTIONS,
+  INVALID_SIGNAL_DATA,
   JSONPatch,
   JSONUtils,
   LATE_PUBLISHING_ERROR,
+  MISSING_UPDATE_DATA,
   NOT_FOUND,
   ResolveError
 } from '@did-btcr2/common';
@@ -173,12 +175,15 @@ function isSignedBTCR2Update(value: unknown): value is SignedBTCR2Update {
     && isRecord(value.proof);
 }
 
-/** True if `value` has the shape of an SMT inclusion / non-inclusion proof. */
+/** True if `value` has the shape of an SMT proof: string fields, `hashes` an array of strings. */
 function isSMTProof(value: unknown): value is SMTProof {
   if(!isRecord(value)) return false;
   return typeof value.id === 'string'
     && typeof value.collapsed === 'string'
-    && Array.isArray(value.hashes);
+    && Array.isArray(value.hashes)
+    && value.hashes.every(h => typeof h === 'string')
+    && (value.nonce === undefined || typeof value.nonce === 'string')
+    && (value.updateId === undefined || typeof value.updateId === 'string');
 }
 
 /**
@@ -301,7 +306,12 @@ export class Resolver {
   #currentDocument: DidDocument | null;
   #providedGenesisDocument: object | null = null;
   #beaconServicesSignals: Map<BeaconService, Array<BeaconSignal>> = new Map();
-  #processedServices: Set<string> = new Set();
+  /**
+   * The beacon addresses whose signals became update tuples. Keyed by address, not by
+   * service id: a rotation keeps the id and changes the address, and the specification
+   * has no per-service state (ADR 118).
+   */
+  #processedAddresses: Set<string> = new Set();
   /** The beacon addresses the resolver requested signals for: `scanned_beacons` of the specification. */
   #requestCache: Set<string> = new Set();
   /**
@@ -317,16 +327,25 @@ export class Resolver {
    * The state of the specification loop, carried across every pass: the version counter
    * (`current_version_id`), the update-hash history that backs duplicate confirmation
    * (`update_hash_history`), the confirmations of the block that contains the most
-   * recently applied unique update (`block_confirmations`), and the header time of that
-   * block as `updated`. A pass that finds a new beacon address returns to discovery, so
-   * the state must not restart: a restart would reject a linear history whose later
-   * updates are announced on beacons that earlier updates added.
+   * recently applied unique update (`block_confirmations`), the height of that block
+   * (`current_block_height`), and the header time of that block as `updated`. A pass
+   * that finds a new beacon address returns to discovery, so the state must not
+   * restart: a restart would reject a linear history whose later updates are
+   * announced on beacons that earlier updates added.
    */
   #currentVersionId = 1;
   #updateHashHistory: HashBytes[] = [];
   #blockConfirmations = 0;
   #updated?: string;
 
+  /**
+   * The height of the block that contains the most recently applied update
+   * (`current_block_height`). "Find Beacon Signals" keeps only the signals at or above
+   * it: a beacon address that an update added has no signals for this DID before the
+   * block of that update.
+   */
+  #currentBlockHeight = 0;
+
   /**
    * Opt-in upper bound on multi-round beacon-discovery passes. `Infinity` (the
    * default) leaves discovery unbounded; termination is already guaranteed by
@@ -865,8 +884,9 @@ export class Resolver {
           const allNeeds: Array<DataNeed> = [];
 
           for(const [service, signals] of this.#beaconServicesSignals) {
-            // Skip already-processed services and services with no signals
-            if(this.#processedServices.has(service.id) || !signals.length) continue;
+            // Skip a processed address and a service with no signals
+            const address = BeaconUtils.parseBitcoinAddress(service.serviceEndpoint as string);
+            if(this.#processedAddresses.has(address) || !signals.length) continue;
 
             // Keep only the signals at or above the confirmation threshold. A
             // service whose signals are all below it is treated like a service
@@ -884,13 +904,12 @@ export class Resolver {
               // This service has unmet data needs, collect them
               allNeeds.push(...result.needs);
             } else {
-              // All signals for this service resolved: collect the updates with the
-              // beacon address of the service, mark the service processed.
-              const address = BeaconUtils.parseBitcoinAddress(service.serviceEndpoint as string);
+              // All signals of this address resolved: collect the updates with the
+              // beacon address, mark the address processed.
               this.#unsortedUpdates.push(...result.updates.map(
                 ([update, block]): UpdateTuple => [update, block, address]
               ));
-              this.#processedServices.add(service.id);
+              this.#processedAddresses.add(address);
             }
           }
 
@@ -953,7 +972,7 @@ export class Resolver {
           );
           if(removed) continue;
 
-          // Step 7, "Check targetVersionId", first arm: targetVersionId <= currentVersionId
+          // Step 6, "Check targetVersionId", first arm: targetVersionId <= currentVersionId
           // re-announces an applied version. Confirm that it is a true duplicate, then
           // skip it. A duplicate does not advance the version counter, does not append
           // to the history (the slot already holds the applied update, ADR 067), and
@@ -975,7 +994,7 @@ export class Resolver {
             continue;
           }
 
-          // Step 7, third arm: a version was skipped, so raise LATE_PUBLISHING.
+          // Step 6, third arm: a version was skipped, so raise LATE_PUBLISHING.
           if(update.targetVersionId !== this.#currentVersionId + 1) {
             throw new ResolveError(
               `Version Id Mismatch: targetVersionId cannot be > currentVersionId + 1`,
@@ -986,16 +1005,18 @@ export class Resolver {
             );
           }
 
-          // Step 7, second arm: targetVersionId == currentVersionId + 1. Apply the update,
+          // Step 6, second arm: targetVersionId == currentVersionId + 1. Apply the update,
           // append the unsigned update hash to the history, increment the version.
           this.#currentDocument = Resolver.applyUpdate(document, update, block);
           const unsignedUpdate = JSONUtils.deleteKeys(update, ['proof']) as UnsignedBTCR2Update;
           this.#updateHashHistory.push(canonicalHashBytes(unsignedUpdate));
           this.#currentVersionId++;
 
-          // Step 6: block_confirmations, and the header time as `updated`. On the apply
-          // path only: the stop above and the duplicate branch stamp nothing.
+          // "Apply Update": block_confirmations, current_block_height, and the header time
+          // as `updated`. On the apply path only: the stop above and the duplicate branch
+          // stamp nothing.
           this.#blockConfirmations = block.confirmations;
+          this.#currentBlockHeight = block.height;
           this.#updated = DateUtils.toISOStringNonFractional(DateUtils.blocktimeToTimestamp(block.time));
 
           // The applied update can add a beacon service. "Find Beacon Signals" runs at
@@ -1063,8 +1084,12 @@ export class Resolver {
    * malformed. It fails fast here with a typed error, in the style of the
    * {@link provide} guards, and not later with an invalid date or a false
    * `versionTime` comparison in the ProcessUpdate phase.
+   *
+   * "Find Beacon Signals" finds only the transactions at or above
+   * `current_block_height`, the height of the block of the most recently applied
+   * update. A signal below it is excluded: it emits no data need and applies no update.
    * @param {Array<BeaconSignal>} signals The signals the caller provided for one service.
-   * @returns {Array<BeaconSignal>} The signals at or above the threshold, in the given order.
+   * @returns {Array<BeaconSignal>} The signals at or above the threshold and the height, in the given order.
    * @throws {ResolveError} `INVALID_DID_UPDATE` for an eligible signal with no valid block metadata.
    */
   #eligibleSignals(signals: Array<BeaconSignal>): Array<BeaconSignal> {
@@ -1089,6 +1114,10 @@ export class Resolver {
           }
         );
       }
+      // "Find Beacon Signals" finds only the transactions at or above current_block_height.
+      // A signal before the block of the update that added the address is not a signal
+      // of this DID.
+      if((block!.height as number) < this.#currentBlockHeight) continue;
       eligible.push(signal);
     }
     return eligible;
@@ -1142,12 +1171,14 @@ export class Resolver {
           );
         }
         // Fail fast if the provided announcement is not the one the on-chain
-        // signal requested: its canonical hash must equal the need's hash.
+        // signal requested: its canonical hash must equal the need's hash. The
+        // specification ("Process CAS Beacon") treats an announcement whose hash is
+        // not map_update_hash as not available from CAS: MISSING_UPDATE_DATA.
         const announcementHash = canonicalHash(data, { encoding: 'hex' });
         if(announcementHash !== need.announcementHash) {
           throw new ResolveError(
             `CAS announcement hash mismatch: expected ${need.announcementHash}, got ${announcementHash}.`,
-            INVALID_DID_UPDATE, { expected: need.announcementHash, actual: announcementHash }
+            MISSING_UPDATE_DATA, { expected: need.announcementHash, actual: announcementHash }
           );
         }
         this.#sidecarData.casMap.set(announcementHash, data);
@@ -1162,12 +1193,13 @@ export class Resolver {
           );
         }
         // Fail fast if the provided update is not the one the on-chain signal
-        // requested: its canonical hash must equal the need's hash.
+        // requested: the specification compares the JSON Document Hash of a
+        // retrieved update to update_hash, and a mismatch is INVALID_SIGNAL_DATA.
         const updateHash = canonicalHash(data, { encoding: 'hex' });
         if(updateHash !== need.updateHash) {
           throw new ResolveError(
             `Signed update hash mismatch: expected ${need.updateHash}, got ${updateHash}.`,
-            INVALID_DID_UPDATE, { expected: need.updateHash, actual: updateHash }
+            INVALID_SIGNAL_DATA, { expected: need.updateHash, actual: updateHash }
           );
         }
         this.#sidecarData.updateMap.set(updateHash, data);
@@ -1175,18 +1207,27 @@ export class Resolver {
       }
 
       case 'NeedSMTProof': {
+        // A proof of another shape is data for the signal that does not agree with
+        // its Signal Bytes: INVALID_SIGNAL_DATA, as for the id and the walk below.
         if(!isSMTProof(data)) {
           throw new ResolveError(
             'Provided data for NeedSMTProof is not an SMT proof.',
-            INVALID_DID_UPDATE, { kind: need.kind }
+            INVALID_SIGNAL_DATA, { kind: need.kind }
           );
         }
-        // proof.id is base64url per spec; smtRootHash is the hex on-chain signal.
-        const proofIdHex = encodeHash(decodeHash(data.id, 'base64urlnopad'), 'hex');
+        // proof.id is base64url per spec; smtRootHash is the hex on-chain signal. The
+        // specification ("Process SMT Beacon") compares the id of smt_proof to
+        // smt_root: a mismatch, or an id that does not decode, is INVALID_SIGNAL_DATA.
+        let proofIdHex: string | undefined;
+        try {
+          proofIdHex = encodeHash(decodeHash(data.id, 'base64urlnopad'), 'hex');
+        } catch {
+          proofIdHex = undefined;
+        }
         if(proofIdHex !== need.smtRootHash) {
           throw new ResolveError(
-            `SMT proof root hash mismatch: expected ${need.smtRootHash}, got ${proofIdHex}`,
-            INVALID_DID_UPDATE, { expected: need.smtRootHash, actual: proofIdHex }
+            `SMT proof root hash mismatch: expected ${need.smtRootHash}, got ${proofIdHex ?? 'an id that does not decode'}.`,
+            INVALID_SIGNAL_DATA, { expected: need.smtRootHash, actual: proofIdHex }
           );
         }
         this.#sidecarData.smtMap.set(need.smtRootHash, data);

package/src/core/types.ts

@@ -49,8 +49,10 @@ export type Sidecar = {
   casUpdates?: Array<CASAnnouncement>;
 
   /**
-   * Optional array of SMT Proofs. Required if the DID being resolved has used
-   * an SMT Beacon to publish a BTCR2 Update.
+   * Optional array of SMT Proofs: one proof for each SMT beacon signal that the
+   * resolver finds for the DID, with an update announced or not. The DID
+   * controller keeps every proof for the life of the DID. Sidecar is the only
+   * channel for a proof.
    */
   smtProofs?: Array<SMTProof>;
 };