@did-btcr2/method 0.49.0 → 0.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.49.0",
+  "version": "0.51.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",
@@ -66,49 +66,35 @@
   "dependencies": {
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
-    "@noble/secp256k1": "^2.3.0",
     "@scure/base": "^1.2.6",
-    "@scure/bip32": "^1.7.0",
-    "@scure/bip39": "^1.6.0",
     "@scure/btc-signer": "^1.8.1",
-    "@web5/common": "^1.1.0",
-    "@web5/crypto": "^1.0.6",
     "@web5/dids": "^1.2.0",
-    "canonicalize": "^2.1.0",
-    "dotenv": "^16.6.1",
-    "nostr-tools": "^2.23.3",
     "@did-btcr2/bitcoin": "^0.8.0",
-    "@did-btcr2/common": "^9.1.0",
-    "@did-btcr2/cryptosuite": "^9.0.0",
+    "@did-btcr2/smt": "^0.3.0",
     "@did-btcr2/keypair": "^0.13.1",
-    "@did-btcr2/smt": "^0.3.0"
+    "@did-btcr2/common": "^9.1.0",
+    "@did-btcr2/cryptosuite": "^9.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "@types/chai": "^5.2.3",
-    "@types/chai-as-promised": "^8.0.2",
-    "@types/eslint": "^9.6.1",
     "@types/mocha": "^10.0.10",
     "@types/node": "^25.5.0",
     "@typescript-eslint/eslint-plugin": "^8.58.0",
     "@typescript-eslint/parser": "^8.58.0",
     "c8": "^10.1.3",
     "chai": "^5.3.3",
-    "chai-as-promised": "^8.0.2",
     "commander": "^13.1.0",
     "esbuild": "^0.24.2",
     "eslint": "^9.39.4",
     "eslint-plugin-mocha": "^10.5.0",
     "globals": "^15.15.0",
     "mocha": "^10.8.2",
-    "mocha-junit-reporter": "^2.2.1",
     "multiformats": "^13.4.2",
     "node-stdlib-browser": "^1.3.1",
     "rimraf": "^6.1.3",
     "tsup": "^8.5.1",
-    "typedoc-plugin-markdown": "^4.11.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.58.0"
+    "typescript": "^5.9.3"
   },
   "scripts": {
     "clean": "rimraf dist coverage tests/compiled",

package/src/core/beacon/beacon.ts

@@ -229,27 +229,97 @@ export function opReturnScript(signalBytes: Uint8Array): Uint8Array {
 }
 
 /**
- * Fetch the most recent confirmed UTXO at `bitcoinAddress` + the raw bytes of its
- * parent transaction (needed by PSBT inputs). Throws if unfunded.
+ * Minimum value (sats) a beacon UTXO must exceed for {@link selectSpendableUtxo} to
+ * treat it as spendable. This is a fixed, conservative, script-kind-agnostic floor:
+ * an output at or below it is too small to be worth spending, so selection discards
+ * it in favor of a larger confirmed UTXO. Keeping the floor a constant (rather than
+ * deriving it from a fee estimate) keeps selection pure and fee-estimator-independent.
+ *
+ * The floor is a coarse pre-filter, not the fee-coverage boundary: whether a selected
+ * UTXO actually covers the transaction fee is a separate check, enforced against the
+ * live {@link FeeEstimator} by the builders' `value <= feeSats` guard
+ * ({@link SinglePartyBeacon.buildSinglePartyTx} and {@link buildAggregationBeaconTx}).
+ * At the default 5 sat/vB rate that fee (roughly 775 to 1200 sats across the three
+ * script kinds) sits above this floor, so a UTXO can clear the dust filter and still
+ * be rejected as insufficient; conversely, at a very low fee rate an output near the
+ * floor could cover the fee. The floor's job is only to skip trivially small inputs.
+ *
+ * The value is the standard Bitcoin Core P2PKH dust threshold, the largest of the
+ * three singleton beacon script kinds (P2PKH 546, P2TR 330, P2WPKH 294 per
+ * {@link DUST_LIMIT_SATS}): a UTXO above it is non-dust under any beacon address kind.
+ * Distinct from {@link DUST_LIMIT_SATS}, which sizes the outgoing change output by
+ * kind; this bounds the incoming UTXO chosen to fund the transaction.
  */
-async function fetchSpendableUtxo(
-  bitcoinAddress: string,
-  bitcoin: BitcoinConnection,
-): Promise<{ utxo: AddressUtxo; prevTxBytes: Uint8Array }> {
-  const utxos = await bitcoin.rest.address.getUtxos(bitcoinAddress);
+export const SPENDABLE_DUST_LIMIT_SATS = 546;
+
+/**
+ * Deterministic ordering for spendable UTXO selection: deepest first (ascending
+ * block height, so the most-confirmed UTXO sorts first), tie-broken by `txid` then
+ * `vout`. The tie-break makes the winner independent of the order the REST API
+ * returns UTXOs in, so retries and independent resolvers converge on the same input.
+ */
+function byDepthThenId(a: AddressUtxo, b: AddressUtxo): number {
+  if(a.status.block_height !== b.status.block_height) {
+    return a.status.block_height - b.status.block_height;
+  }
+  const txidOrder = a.txid.localeCompare(b.txid);
+  return txidOrder !== 0 ? txidOrder : a.vout - b.vout;
+}
+
+/**
+ * Select the beacon UTXO to fund a signal transaction from the set of UTXOs at a
+ * beacon address. Pure and deterministic: the same address state always yields the
+ * same input, across broadcast retries and across independent resolvers.
+ *
+ * Filters to confirmed UTXOs (an unconfirmed input is reorg- and RBF-unsafe: a
+ * signal built on it can be orphaned or double-spent before it confirms), then drops
+ * dust at or below {@link SPENDABLE_DUST_LIMIT_SATS}, then picks the deepest via
+ * {@link byDepthThenId}. The did:btcr2 spec does not mandate a selection rule or a
+ * confirmation depth (only the security considerations favor deeper confirmations),
+ * so this is an implementation policy: prefer safety and reproducibility over
+ * spending the newest or largest output.
+ *
+ * @param utxos UTXOs reported at the beacon address.
+ * @param address Beacon address, used only to annotate thrown errors.
+ * @returns The confirmed, non-dust, deepest UTXO.
+ * @throws {BeaconError} `UNFUNDED_BEACON_ADDRESS` when no UTXOs exist at all;
+ *   `NO_SPENDABLE_BEACON_UTXO` when UTXOs exist but none are both confirmed and above
+ *   the dust limit (the message distinguishes all-unconfirmed from all-dust).
+ */
+export function selectSpendableUtxo(utxos: Array<AddressUtxo>, address?: string): AddressUtxo {
   if(!utxos.length) {
     throw new BeaconError(
       'No UTXOs found, please fund address!',
-      'UNFUNDED_BEACON_ADDRESS', { address: bitcoinAddress }
+      'UNFUNDED_BEACON_ADDRESS', { address }
     );
   }
-  const utxo = utxos.sort((a, b) => b.status.block_height - a.status.block_height).shift();
-  if(!utxo) {
+  const confirmed = utxos.filter(utxo => utxo.status.confirmed === true);
+  const spendable = confirmed.filter(utxo => utxo.value > SPENDABLE_DUST_LIMIT_SATS);
+  if(!spendable.length) {
+    const reason = confirmed.length === 0
+      ? `all ${utxos.length} UTXO(s) are unconfirmed`
+      : `all ${confirmed.length} confirmed UTXO(s) are at or below the ${SPENDABLE_DUST_LIMIT_SATS}-sat dust limit`;
     throw new BeaconError(
-      'Beacon bitcoin address unfunded or utxos unconfirmed.',
-      'UNFUNDED_BEACON_ADDRESS', { address: bitcoinAddress }
+      `No spendable UTXO at beacon address: ${reason}.`,
+      'NO_SPENDABLE_BEACON_UTXO',
+      { address, total: utxos.length, confirmed: confirmed.length, dustLimit: SPENDABLE_DUST_LIMIT_SATS }
     );
   }
+  return [ ...spendable ].sort(byDepthThenId)[0]!;
+}
+
+/**
+ * Fetch the deepest confirmed, non-dust spendable UTXO at `bitcoinAddress` plus the
+ * raw bytes of its parent transaction (needed by PSBT inputs). Selection is delegated
+ * to {@link selectSpendableUtxo}; throws {@link BeaconError} when the address is
+ * unfunded or has no confirmed, non-dust UTXO.
+ */
+async function fetchSpendableUtxo(
+  bitcoinAddress: string,
+  bitcoin: BitcoinConnection,
+): Promise<{ utxo: AddressUtxo; prevTxBytes: Uint8Array }> {
+  const utxos = await bitcoin.rest.address.getUtxos(bitcoinAddress);
+  const utxo = selectSpendableUtxo(utxos, bitcoinAddress);
   const prevTxHex = await bitcoin.rest.transaction.getHex(utxo.txid);
   return { utxo, prevTxBytes: hexToBytes(prevTxHex) };
 }

package/src/core/did-sender-resolver.ts

@@ -1,25 +1,106 @@
+import { DidDocumentError, INVALID_DID_DOCUMENT } from '@did-btcr2/common';
+import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
+import type { DidDocument, DidVerificationMethod } from '../utils/did-document.js';
 import { Identifier } from './identifier.js';
+import { Resolver } from './resolver.js';
+
+/**
+ * Derive the aggregation communication public key from a resolved did:btcr2 DID Document.
+ *
+ * The communication key is the verification method referenced by
+ * `capabilityInvocation[0]`, resolved to its public key. This is the exact relationship
+ * the method already enforces for DID updates (construct and sign require the signing
+ * method to be in `capabilityInvocation`, the update proof is built and verified with
+ * `proofPurpose: 'capabilityInvocation'`), so binding the transport communication key to
+ * it yields the invariant "transport-authenticated as D implies authorized to update D."
+ * For a KEY (`k1`) document the single deterministic key is already the sole
+ * `capabilityInvocation` entry, so this is a no-op for KEY DIDs.
+ *
+ * There is deliberately no `verificationMethod[0]` fallback: a document without
+ * `capabilityInvocation` cannot be updated at all, so it is useless for aggregation and is
+ * rejected here rather than bound to an unrelated key.
+ *
+ * @param {DidDocument} document The resolved DID Document (placeholder id already replaced).
+ * @returns {CompressedSecp256k1PublicKey} The compressed public key of the communication method.
+ * @throws {DidDocumentError} If `capabilityInvocation` is absent or its first entry does not
+ *   resolve to a verification method in the document.
+ */
+export function getAggregationCommunicationKey(
+  document: DidDocument,
+): CompressedSecp256k1PublicKey {
+  const invocation = document.capabilityInvocation?.[0];
+  if(invocation === undefined) {
+    throw new DidDocumentError(
+      'Cannot derive aggregation communication key: capabilityInvocation is absent',
+      INVALID_DID_DOCUMENT, { id: document.id }
+    );
+  }
+
+  // Resolve capabilityInvocation[0] to a verification method: a string reference is
+  // dereferenced by id against verificationMethod; an embedded method is used directly.
+  // A local id lookup is used rather than getSigningMethod, which defaults to #initialKey
+  // and does not resolve embedded methods.
+  const vm: DidVerificationMethod | undefined = typeof invocation === 'string'
+    ? document.verificationMethod?.find(method => method.id === invocation)
+    : invocation;
+
+  if(!vm) {
+    throw new DidDocumentError(
+      `Cannot derive aggregation communication key: capabilityInvocation[0] "${invocation}" `
+        + 'does not resolve to a verification method',
+      INVALID_DID_DOCUMENT, { id: document.id, invocation }
+    );
+  }
+
+  return SchnorrMultikey.fromVerificationMethod(vm).publicKey;
+}
 
 /**
  * Resolve a did:btcr2 sender's communication public key from its DID, for the
- * aggregation HTTP transport's `resolveSenderPk` option: a KEY identifier decodes to
- * its genesis public key. The aggregation transport is DID-method-agnostic and does
- * not name `Identifier`; method supplies this resolver when it wires the transport so
- * a sender that is not a pre-registered peer can still be authenticated from its DID.
+ * aggregation HTTP transport's `resolveSenderPk` option.
  *
- * @param did The sender's DID.
- * @returns The sender's compressed public key, or `undefined` when the DID is not a
- *   decodable did:btcr2 KEY identifier (resolution then falls back to registered peers).
+ * A KEY (`k1`) identifier decodes directly to its genesis public key: the DID string is
+ * the key. An EXTERNAL (`x1`) identifier is a commitment to the hash of a genesis
+ * document, so there is no key in the DID string. When the genesis document is supplied
+ * in-band (via `opts.genesisDocument`), it is self-verifying against the DID: `Resolver`'s
+ * external path recomputes its canonical hash, compares it to the identifier's genesis
+ * bytes (throwing on mismatch), and resolves it, after which the communication key is
+ * derived from `capabilityInvocation[0]` ({@link getAggregationCommunicationKey}). Without
+ * a genesis document, an `x1` DID still resolves to `undefined`, so callers that pass no
+ * second argument behave exactly as before.
+ *
+ * The aggregation transport is DID-method-agnostic and does not name `Identifier`; method
+ * supplies this resolver when it wires the transport so a sender that is not a
+ * pre-registered peer can still be authenticated from its DID.
+ *
+ * @param {string} did The sender's DID.
+ * @param {object} [opts] Optional resolution inputs.
+ * @param {object} [opts.genesisDocument] The `x1` sender's genesis document, carried in-band
+ *   on the bootstrap opt-in. Ignored for KEY identifiers.
+ * @returns {CompressedSecp256k1PublicKey | undefined} The sender's compressed public key, or
+ *   `undefined` when the DID is not a decodable did:btcr2 identifier, is an `x1` identifier
+ *   with no (or a non-matching) genesis document, or has no usable communication key.
  */
-export function resolveBtcr2SenderPk(did: string): CompressedSecp256k1PublicKey | undefined {
+export function resolveBtcr2SenderPk(
+  did: string,
+  opts?: { genesisDocument?: object },
+): CompressedSecp256k1PublicKey | undefined {
   try {
     const components = Identifier.decode(did);
     if(components.idType === 'KEY') {
       return new CompressedSecp256k1PublicKey(components.genesisBytes);
     }
+    // EXTERNAL (x1): the DID commits to the hash of a genesis document. With the genesis
+    // supplied in-band, verify it hashes to the DID and derive the communication key from
+    // it; without it, there is no key to return.
+    if(opts?.genesisDocument) {
+      const document = Resolver.external(components, opts.genesisDocument);
+      return getAggregationCommunicationKey(document);
+    }
   } catch {
-    // Not a decodable did:btcr2 KEY identifier.
+    // Not a decodable did:btcr2 identifier, the genesis does not hash to the DID, or the
+    // document has no usable capabilityInvocation communication key.
   }
   return undefined;
 }