@did-btcr2/method 0.32.0 → 0.34.0

package/src/core/aggregation/transport/in-memory.ts

@@ -0,0 +1,174 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import type { BaseMessage } from '../messages/base.js';
+import type { MessageHandler, Transport } from './transport.js';
+
+/** Internal registration for a single actor sharing an {@link InMemoryTransport}. */
+interface ActorEntry {
+  keys: SchnorrKeyPair;
+  handlers: Map<string, MessageHandler>;
+}
+
+/**
+ * In-process message bus connecting one or more {@link InMemoryTransport}
+ * instances. Routes broadcasts to every registered actor and directed messages
+ * to the actor that owns the recipient DID — with no relay, server, or network.
+ *
+ * Each delivery does a JSON round-trip (Uint8Array preserved as `__bytes` hex)
+ * so handlers receive an isolated, serialization-faithful copy, exactly as a
+ * real transport would. The message `body` is merged to the top level to match
+ * the shape the {@link NostrTransport} dispatch produces.
+ *
+ * @class InMemoryBus
+ */
+export class InMemoryBus {
+  #transports: Set<InMemoryTransport> = new Set();
+
+  /** Attach a transport to this bus. Called by the transport's constructor. */
+  register(transport: InMemoryTransport): void {
+    this.#transports.add(transport);
+  }
+
+  /** Detach a transport from this bus. */
+  unregister(transport: InMemoryTransport): void {
+    this.#transports.delete(transport);
+  }
+
+  /**
+   * Deliver a message. With no `recipient` the message is broadcast to every
+   * actor on the bus; otherwise it is routed to the single transport that owns
+   * the recipient DID.
+   */
+  async deliver(message: BaseMessage, _sender: string, recipient?: string): Promise<void> {
+    const type = (message as { type?: string }).type;
+    if(!type) return;
+
+    // JSON round-trip to mimic transport serialization, preserving Uint8Array.
+    const replacer = (_k: string, v: unknown): unknown => v instanceof Uint8Array ? { __bytes: bytesToHex(v) } : v;
+    const reviver = (_k: string, v: unknown): unknown =>
+      v && typeof v === 'object' && '__bytes' in (v as Record<string, unknown>)
+        ? hexToBytes((v as { __bytes: string }).__bytes)
+        : v;
+    const raw = JSON.parse(JSON.stringify(message, replacer), reviver) as Record<string, unknown>;
+    const serialized = { ...raw, ...((raw.body as Record<string, unknown> | undefined) ?? {}) };
+
+    if(!recipient) {
+      for(const t of this.#transports) {
+        await t.dispatchBroadcast(type, serialized);
+      }
+      return;
+    }
+    for(const t of this.#transports) {
+      if(t.hasActor(recipient)) {
+        await t.dispatchDirected(recipient, type, serialized);
+        return;
+      }
+    }
+  }
+}
+
+/**
+ * In-process {@link Transport} that routes aggregation messages through an
+ * {@link InMemoryBus} instead of a relay or HTTP server. Supports multiple
+ * actors per instance, so a single transport can host both a service and its
+ * participants (e.g. a cohort-of-one via {@link AggregationRunner.solo}).
+ *
+ * Encryption is a no-op (in-process, same trust domain); `registerPeer` /
+ * `getPeerPk` keep a registry so the contract matches the wire transports.
+ *
+ * @class InMemoryTransport
+ * @implements {Transport}
+ */
+export class InMemoryTransport implements Transport {
+  name: string = 'in-memory';
+  readonly bus: InMemoryBus;
+
+  #actors: Map<string, ActorEntry> = new Map();
+  #peers: Map<string, Uint8Array> = new Map();
+
+  /** @param bus Shared bus. Pass the same bus to connect multiple transports. */
+  constructor(bus: InMemoryBus = new InMemoryBus()) {
+    this.bus = bus;
+    this.bus.register(this);
+  }
+
+  start(): void {
+    // No-op: there is no underlying connection to open.
+  }
+
+  registerActor(did: string, keys: SchnorrKeyPair): void {
+    this.#actors.set(did, { keys, handlers: new Map() });
+  }
+
+  getActorPk(did: string): Uint8Array | undefined {
+    return this.#actors.get(did)?.keys.publicKey.compressed;
+  }
+
+  /** True if `did` is registered on this transport. Used by the bus for routing. */
+  hasActor(did: string): boolean {
+    return this.#actors.has(did);
+  }
+
+  registerPeer(did: string, communicationPk: Uint8Array): void {
+    this.#peers.set(did, communicationPk);
+  }
+
+  getPeerPk(did: string): Uint8Array | undefined {
+    return this.#peers.get(did);
+  }
+
+  registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void {
+    const actor = this.#actors.get(actorDid);
+    if(actor) actor.handlers.set(messageType, handler);
+  }
+
+  unregisterMessageHandler(actorDid: string, messageType: string): void {
+    const actor = this.#actors.get(actorDid);
+    if(actor) actor.handlers.delete(messageType);
+  }
+
+  unregisterActor(did: string): void {
+    const actor = this.#actors.get(did);
+    if(!actor) return;
+    actor.handlers.clear();
+    this.#actors.delete(did);
+    this.#peers.delete(did);
+  }
+
+  async sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void> {
+    await this.bus.deliver(message, sender, recipient);
+  }
+
+  publishRepeating(
+    message: BaseMessage,
+    sender: string,
+    intervalMs: number,
+    recipient?: string,
+  ): () => void {
+    let stopped = false;
+    void this.sendMessage(message, sender, recipient).catch(() => { /* in-process: no relay to reject */ });
+    const timer = setInterval(() => {
+      if(stopped) return;
+      void this.sendMessage(message, sender, recipient).catch(() => { /* ignore */ });
+    }, intervalMs);
+    return () => {
+      if(stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    };
+  }
+
+  /** Deliver a broadcast message to every actor on this transport that handles `type`. */
+  async dispatchBroadcast(type: string, message: unknown): Promise<void> {
+    for(const actor of this.#actors.values()) {
+      const handler = actor.handlers.get(type);
+      if(handler) await handler(message);
+    }
+  }
+
+  /** Deliver a directed message to the recipient actor's handler for `type`. */
+  async dispatchDirected(recipientDid: string, type: string, message: unknown): Promise<void> {
+    const handler = this.#actors.get(recipientDid)?.handlers.get(type);
+    if(handler) await handler(message);
+  }
+}

package/src/core/aggregation/transport/index.ts

@@ -1,6 +1,7 @@
 export * from './transport.js';
 export * from './error.js';
 export * from './factory.js';
+export * from './in-memory.js';
 export * from './nostr.js';
 export * from './didcomm.js';
 export * from './http/index.js';

package/src/core/beacon/beacon.ts

@@ -89,7 +89,7 @@ export function deriveSingletonAddress(
 }
 
 /**
- * Options accepted by {@link Beacon.buildSignAndBroadcast} and related helpers.
+ * Options accepted by {@link SinglePartyBeacon.buildSignAndBroadcast} and related helpers.
  */
 export interface BroadcastOptions {
   /** Fee estimator for computing the transaction fee. Defaults to {@link DEFAULT_FEE_ESTIMATOR}. */
@@ -115,14 +115,14 @@ export interface BeaconTxPlan {
   feeSats: bigint;
   /**
    * Singleton beacon script kind, when applicable. Drives the signing dispatch
-   * in {@link Beacon.signSinglePartyTx}. Aggregation plans set this to `'p2tr'`.
+   * in {@link SinglePartyBeacon.signSinglePartyTx}. Aggregation plans set this to `'p2tr'`.
    */
   scriptKind: SingletonScriptKind;
 }
 
 /**
  * Build an OP_RETURN script carrying a 32-byte beacon signal.
- * Exported as a utility so callers building txs outside Beacon (e.g., the aggregation
+ * Exported as a utility so callers building txs outside SinglePartyBeacon (e.g., the aggregation
  * `onProvideTxData` callback) can produce identical output.
  *
  * Uses the opcode *string* `'RETURN'` rather than the numeric `OP.RETURN`
@@ -168,7 +168,7 @@ async function fetchSpendableUtxo(
  * Returns the unsigned Transaction + prev-output metadata that an aggregation service's
  * signing session consumes (via {@link SigningTxData}).
  *
- * This is the reusable counterpart to {@link Beacon.buildSignAndBroadcast}'s internal
+ * This is the reusable counterpart to {@link SinglePartyBeacon.buildSignAndBroadcast}'s internal
  * construction step — the aggregation path must produce an unsigned tx because the
  * signature comes from a MuSig2 round, not a local secret key.
  *
@@ -311,9 +311,11 @@ async function signSingletonInput(
 }
 
 /**
- * Abstract base class for all BTCR2 Beacon types.
- * A Beacon is a service listed in a BTCR2 DID document that informs resolvers
- * how to find authentic updates to the DID.
+ * Abstract base class providing the single-party broadcast machinery shared by
+ * all BTCR2 beacon types: one party holds one key and broadcasts one 32-byte
+ * signal (P2PKH / P2WPKH / P2TR key-path). The aggregation (cohort of N >= 1)
+ * broadcast mode is the orthogonal axis, handled by the AggregationService and
+ * {@link buildAggregationBeaconTx}, not by this class hierarchy. See ADR 037.
  *
  * Beacons are lightweight typed wrappers around a {@link BeaconService} configuration.
  * Dependencies (signals, sidecar data, bitcoin connection) are passed as method
@@ -322,10 +324,10 @@ async function signSingletonInput(
  * Use {@link BeaconFactory.establish} to create typed instances from service config.
  *
  * @abstract
- * @class Beacon
- * @type {Beacon}
+ * @class SinglePartyBeacon
+ * @type {SinglePartyBeacon}
  */
-export abstract class Beacon {
+export abstract class SinglePartyBeacon {
   /**
    * The Beacon service configuration parsed from the DID Document.
    */

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

@@ -5,7 +5,7 @@ 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 { Beacon } from './beacon.js';
+import { SinglePartyBeacon } from './beacon.js';
 import type { BeaconService, BeaconSignal, BlockMetadata, CasPublishFn } from './interfaces.js';
 
 /**
@@ -28,9 +28,9 @@ export interface CASBroadcastOptions extends BroadcastOptions {
  *
  * @class CASBeacon
  * @type {CASBeacon}
- * @extends {Beacon}
+ * @extends {SinglePartyBeacon}
  */
-export class CASBeacon extends Beacon {
+export class CASBeacon extends SinglePartyBeacon {
   /**
    * Creates an instance of CASBeacon.
    * @param {BeaconService} service The service of the Beacon.
@@ -115,7 +115,7 @@ export class CASBeacon extends Beacon {
    * 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,
-   * and broadcast are delegated to {@link Beacon.buildSignAndBroadcast}.
+   * and broadcast are delegated to {@link SinglePartyBeacon.buildSignAndBroadcast}.
    *
    * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.

package/src/core/beacon/factory.ts

@@ -1,5 +1,5 @@
 import { MethodError } from '@did-btcr2/common';
-import type { Beacon } from './beacon.js';
+import type { SinglePartyBeacon } from './beacon.js';
 import { CASBeacon } from './cas-beacon.js';
 import type { BeaconService } from './interfaces.js';
 import { SingletonBeacon } from './singleton-beacon.js';
@@ -14,9 +14,9 @@ export class BeaconFactory {
   /**
    * Establish a Beacon instance based on the provided service and optional sidecar data.
    * @param {BeaconService} service The beacon service configuration.
-   * @returns {Beacon} The established Beacon instance.
+   * @returns {SinglePartyBeacon} The established Beacon instance.
    */
-  static establish(service: BeaconService): Beacon {
+  static establish(service: BeaconService): SinglePartyBeacon {
     switch (service.type) {
       case 'SingletonBeacon':
         return new SingletonBeacon(service);

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

@@ -5,16 +5,16 @@ 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 { Beacon } from './beacon.js';
+import { SinglePartyBeacon } from './beacon.js';
 import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
 
 /**
  * Implements {@link https://dcdpr.github.io/did-btcr2/terminology.html#singleton-beacon | Singleton Beacon}.
  * @class SingletonBeacon
  * @type {SingletonBeacon}
- * @extends {Beacon}
+ * @extends {SinglePartyBeacon}
  */
-export class SingletonBeacon extends Beacon {
+export class SingletonBeacon extends SinglePartyBeacon {
 
   /**
    * Creates an instance of SingletonBeacon.
@@ -64,7 +64,7 @@ export class SingletonBeacon extends Beacon {
    *
    * The signal bytes embedded in OP_RETURN are the SHA-256 canonical hash of the signed update.
    * UTXO selection, PSBT construction, fee estimation, signing, and broadcast are delegated to
-   * {@link Beacon.buildSignAndBroadcast}.
+   * {@link SinglePartyBeacon.buildSignAndBroadcast}.
    *
    * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.

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

@@ -2,12 +2,12 @@ import type { BitcoinConnection } from '@did-btcr2/bitcoin';
 import { canonicalize } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
 import type { Signer } from '@did-btcr2/keypair';
-import { blockHash, BTCR2MerkleTree, didToIndex, hexToHash, verifySerializedProof } from '@did-btcr2/smt';
+import { base64UrlToHash, blockHash, BTCR2MerkleTree, didToIndex, hashToHex, verifySerializedProof } from '@did-btcr2/smt';
 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 { Beacon } from './beacon.js';
+import { SinglePartyBeacon } from './beacon.js';
 import { SMTBeaconError } from './error.js';
 import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js';
 
@@ -21,9 +21,9 @@ import type { BeaconService, BeaconSignal, BlockMetadata } from './interfaces.js
  *
  * @class SMTBeacon
  * @type {SMTBeacon}
- * @extends {Beacon}
+ * @extends {SinglePartyBeacon}
  */
-export class SMTBeacon extends Beacon {
+export class SMTBeacon extends SinglePartyBeacon {
   /**
    * Creates an instance of SMTBeacon.
    * @param {BeaconService} service The Beacon service.
@@ -69,12 +69,7 @@ export class SMTBeacon extends Beacon {
         continue;
       }
 
-      // Non-inclusion proof — no update for this DID in this epoch, skip
-      if(!smtProof.updateId) {
-        continue;
-      }
-
-      // Nonce is required for proof verification
+      // Nonce is required for proof verification (inclusion and non-inclusion).
       if(!smtProof.nonce) {
         throw new SMTBeaconError(
           'SMT proof missing required nonce field.',
@@ -82,9 +77,15 @@ export class SMTBeacon extends Beacon {
         );
       }
 
-      // Verify Merkle inclusion: leaf = hash(hash(nonce) || updateId)
+      // 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 candidateHash = blockHash(blockHash(hexToHash(smtProof.nonce)), hexToHash(smtProof.updateId));
+      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) {
@@ -94,14 +95,21 @@ export class SMTBeacon extends Beacon {
         );
       }
 
-      // Look up the signed update in sidecar updateMap (keyed by hex canonical hash)
-      const signedUpdate = sidecar.updateMap.get(smtProof.updateId);
+      // Non-inclusion proof verified — no update for this DID this epoch, skip.
+      if(!smtProof.updateId) {
+        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.
+      const updateHashHex = hashToHex(base64UrlToHash(smtProof.updateId));
+      const signedUpdate = sidecar.updateMap.get(updateHashHex);
 
       if(!signedUpdate) {
         // Signed update not available — emit a need
         needs.push({
           kind             : 'NeedSignedUpdate',
-          updateHash       : smtProof.updateId,
+          updateHash       : updateHashHex,
           beaconServiceId  : this.service.id
         });
         continue;
@@ -119,7 +127,7 @@ export class SMTBeacon extends Beacon {
    * Builds a single-entry Sparse Merkle Tree from the signed update, then broadcasts the tree's
    * root hash via OP_RETURN. For multi-party aggregation, use the {@link AggregationService}
    * subsystem directly instead of this method. UTXO selection, PSBT construction, fee estimation,
-   * signing, and broadcast are delegated to {@link Beacon.buildSignAndBroadcast}.
+   * signing, and broadcast are delegated to {@link SinglePartyBeacon.buildSignAndBroadcast}.
    *
    * @param {SignedBTCR2Update} signedUpdate The signed BTCR2 update to broadcast.
    * @param {Signer} signer Signer that produces the ECDSA signature for the Bitcoin transaction.

package/src/core/interfaces.ts

@@ -43,36 +43,39 @@ export interface ResolutionOptions extends DidResolutionOptions {
  * a path from a leaf in the tree to the Merkle root, proving that the leaf is in the tree.
  * 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).
+ *
  * @example
  * ```json
  * {
- *   "id": "<< Hexadecimal of Root Hash >>",
- *   "nonce": "<< Hexadecimal of Nonce 1101 >>",
- *   "updateId": "<< Hexadecimal of hash(Data Block 1101) >>",
- *   "collapsed": "<< Hexadecimal of 0001 >>",
+ *   "id": "q1H_iaYG0Oq6gbrycYL-r7FjUsJLnIpHDn49TLeONNA",
+ *   "nonce": "99jndCBWHpZfmObXlIvRGHaPMgoQKXIETdD4H-XqryE",
+ *   "updateId": "njYNViJq2OmhSw1fLfARPCj12RY3VXKGWdS3-7OQ2BE",
+ *   "collapsed": "v_________________________________________8",
  *   "hashes": [
- *     "<< Hexadecimal of Hash 1110 >>",
- *     "<< Hexadecimal of Hash 1001 >>",
- *     "<< Hexadecimal of Hash 0 >>"
+ *     "8JWXL7chPKJXwg-i9O1EFTHan_oOO_RmglDpu_ugax0"
  *   ]
  * }
  * ```
  */
 export interface SMTProof {
   /**
-   * The SHA-256 hash of the root node of the Sparse Merkle Tree.
+   * base64url (no padding) SHA-256 hash of the root node of the Sparse Merkle Tree.
    */
   id: string;
   /**
-   * Optional 256-bit nonce generated for each update. Hex-encoded (64 chars).
+   * Optional 256-bit nonce generated for each update. base64url, no padding (43 chars).
    */
   nonce?: string;
   /**
-   * Optional hex-encoded canonical hash of the BTCR2 Signed Update.
+   * Optional base64url (no padding) canonical hash of the BTCR2 Signed Update.
    */
   updateId?: string;
   /**
-   * Bitmap of zero nodes within the path (see: collapsed leaves).
+   * 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.
    */
   collapsed: string;
   /**

package/src/core/resolver.ts

@@ -102,7 +102,7 @@ export type ResolverState =
   | { status: 'resolved'; result: DidResolutionResponse };
 
 /**
- * Return type from {@link Beacon.processSignals}.
+ * Return type from {@link SinglePartyBeacon.processSignals}.
  * Contains successfully resolved updates and any data needs that must be
  * satisfied before the remaining signals can be processed.
  */
@@ -281,11 +281,12 @@ export class Resolver {
         casMap.set(canonicalHash(update, { encoding: 'hex' }), update);
       }
 
-    // SMT Proofs map
+    // SMT Proofs map. proof.id is base64url per the SMT Proof spec; key by the
+    // hex root hash so lookups match the hex signalBytes from the OP_RETURN.
     const smtMap = new Map<string, SMTProof>();
     if(sidecar.smtProofs?.length)
       for(const proof of sidecar.smtProofs) {
-        smtMap.set(proof.id, proof);
+        smtMap.set(encodeHash(decodeHash(proof.id, 'base64urlnopad'), 'hex'), proof);
       }
 
     return { updateMap, casMap, smtMap };
@@ -723,10 +724,12 @@ export class Resolver {
       case 'NeedSMTProof': {
         const smtNeed = need as NeedSMTProof;
         const proof = data as SMTProof;
-        if(proof.id !== smtNeed.smtRootHash) {
+        // proof.id is base64url per spec; smtRootHash is the hex on-chain signal.
+        const proofIdHex = encodeHash(decodeHash(proof.id, 'base64urlnopad'), 'hex');
+        if(proofIdHex !== smtNeed.smtRootHash) {
           throw new ResolveError(
-            `SMT proof root hash mismatch: expected ${smtNeed.smtRootHash}, got ${proof.id}`,
-            INVALID_DID_UPDATE, { expected: smtNeed.smtRootHash, actual: proof.id }
+            `SMT proof root hash mismatch: expected ${smtNeed.smtRootHash}, got ${proofIdHex}`,
+            INVALID_DID_UPDATE, { expected: smtNeed.smtRootHash, actual: proofIdHex }
           );
         }
         this.#sidecarData.smtMap.set(smtNeed.smtRootHash, proof);