@did-btcr2/method 0.26.0 → 0.27.0

package/src/core/aggregation/signing-session.ts

@@ -0,0 +1,209 @@
+import * as musig2 from '@scure/btc-signer/musig2';
+import { Transaction } from 'bitcoinjs-lib';
+import type { AggregationCohort } from './cohort.js';
+import { SigningSessionError } from './errors.js';
+import type { SigningSessionPhaseType } from './phases.js';
+import { SigningSessionPhase } from './phases.js';
+
+type PublicKeyHex = string;
+type Nonce = Uint8Array;
+
+export interface SigningSessionParams {
+  id?: string;
+  cohort: AggregationCohort;
+  pendingTx: Transaction;
+  prevOutScripts?: Uint8Array[];
+  prevOutValues?: bigint[];
+}
+
+/**
+ * MuSig2 signing session for a beacon transaction.
+ *
+ * Implements the BIP-327 signing protocol over a Taproot key-path-only
+ * transaction. The session is used by both AggregationService (collecting
+ * nonces and partial signatures, computing the final signature) and
+ * AggregationParticipant (generating their nonce and partial signature).
+ *
+ * @class BeaconSigningSession
+ */
+export class BeaconSigningSession {
+  /** Unique identifier for this signing session. */
+  public id: string;
+
+  /** The cohort this session signs for. */
+  public cohort: AggregationCohort;
+
+  /** The Bitcoin transaction being signed. */
+  public pendingTx: Transaction;
+
+  /** Previous output scripts for Taproot sighash computation (BIP-341). */
+  public prevOutScripts: Uint8Array[];
+
+  /** Previous output values for Taproot sighash computation. */
+  public prevOutValues: bigint[];
+
+  /** Map of participant publicKey-hex → public nonce contribution. */
+  public nonceContributions: Map<PublicKeyHex, Nonce> = new Map();
+
+  /** Aggregated MuSig2 nonce (66 bytes). */
+  public aggregatedNonce?: Uint8Array;
+
+  /** Map of participant DID → partial signature. */
+  public partialSignatures: Map<string, Uint8Array> = new Map();
+
+  /** Final 64-byte Schnorr signature. */
+  public signature?: Uint8Array;
+
+  /** Current signing session phase. */
+  public phase: SigningSessionPhaseType;
+
+  /** Participant's secret nonce (held only by the participant during signing). */
+  public secretNonce?: Uint8Array;
+
+  constructor({ id, cohort, pendingTx, prevOutScripts, prevOutValues }: SigningSessionParams) {
+    this.id = id || crypto.randomUUID();
+    this.cohort = cohort;
+    this.pendingTx = pendingTx;
+    this.prevOutScripts = prevOutScripts || [];
+    this.prevOutValues = prevOutValues || [];
+    this.phase = SigningSessionPhase.AwaitingNonceContributions;
+  }
+
+  /**
+   * Computes the Taproot sighash (BIP-341) for the first input.
+   */
+  get sigHash(): Uint8Array {
+    if(!this.prevOutScripts.length || !this.prevOutValues.length) {
+      throw new SigningSessionError(
+        'Cannot compute sighash: missing prevOutScripts or prevOutValues.',
+        'SIGHASH_ERROR'
+      );
+    }
+    return this.pendingTx.hashForWitnessV1(
+      0,
+      this.prevOutScripts,
+      this.prevOutValues,
+      Transaction.SIGHASH_DEFAULT
+    );
+  }
+
+  public addNonceContribution(participantDid: string, nonceContribution: Uint8Array): void {
+    if(this.phase !== SigningSessionPhase.AwaitingNonceContributions) {
+      throw new SigningSessionError(
+        `Nonce contributions not expected. Current phase: ${this.phase}`,
+        'INVALID_PHASE', { phase: this.phase }
+      );
+    }
+    if(nonceContribution.length !== 66) {
+      throw new SigningSessionError(
+        `Invalid nonce contribution: expected 66 bytes, got ${nonceContribution.length}.`,
+        'INVALID_NONCE_LENGTH'
+      );
+    }
+    if(this.nonceContributions.has(participantDid)) {
+      throw new SigningSessionError(
+        `Duplicate nonce contribution from ${participantDid}.`,
+        'DUPLICATE_NONCE'
+      );
+    }
+    this.nonceContributions.set(participantDid, nonceContribution);
+
+    if(this.nonceContributions.size === this.cohort.participants.length) {
+      this.phase = SigningSessionPhase.NonceContributionsReceived;
+    }
+  }
+
+  public generateAggregatedNonce(): Uint8Array {
+    if(this.phase !== SigningSessionPhase.NonceContributionsReceived) {
+      throw new SigningSessionError(
+        `Cannot aggregate nonces: phase is ${this.phase}, expected NonceContributionsReceived.`,
+        'INVALID_PHASE'
+      );
+    }
+    this.aggregatedNonce = musig2.nonceAggregate([...this.nonceContributions.values()]);
+    this.phase = SigningSessionPhase.AwaitingPartialSignatures;
+    return this.aggregatedNonce;
+  }
+
+  public addPartialSignature(participantDid: string, partialSig: Uint8Array): void {
+    if(this.phase !== SigningSessionPhase.AwaitingPartialSignatures) {
+      throw new SigningSessionError(
+        `Partial signatures not expected. Current phase: ${this.phase}`,
+        'INVALID_PHASE'
+      );
+    }
+    if(this.partialSignatures.has(participantDid)) {
+      throw new SigningSessionError(
+        `Duplicate partial signature from ${participantDid}.`,
+        'DUPLICATE_PARTIAL_SIG'
+      );
+    }
+    this.partialSignatures.set(participantDid, partialSig);
+
+    if(this.partialSignatures.size === this.cohort.participants.length) {
+      this.phase = SigningSessionPhase.PartialSignaturesReceived;
+    }
+  }
+
+  public generateFinalSignature(): Uint8Array {
+    if(this.phase !== SigningSessionPhase.PartialSignaturesReceived) {
+      throw new SigningSessionError(
+        `Cannot generate final signature: phase is ${this.phase}.`,
+        'INVALID_PHASE'
+      );
+    }
+    if(!this.aggregatedNonce) {
+      throw new SigningSessionError('Aggregated nonce missing.', 'MISSING_AGGREGATED_NONCE');
+    }
+    const session = new musig2.Session(
+      this.aggregatedNonce,
+      this.cohort.cohortKeys,
+      this.sigHash,
+      [this.cohort.trMerkleRoot],
+      [true]
+    );
+    this.signature = session.partialSigAgg([...this.partialSignatures.values()]);
+    this.phase = SigningSessionPhase.Complete;
+    return this.signature;
+  }
+
+  /**
+   * Generates a fresh MuSig2 nonce contribution for the participant.
+   * Stores the secret nonce internally for use in `generatePartialSignature()`.
+   */
+  public generateNonceContribution(participantPublicKey: Uint8Array, participantSecretKey: Uint8Array): Uint8Array {
+    const aggPublicKey = musig2.keyAggExport(musig2.keyAggregate(this.cohort.cohortKeys));
+    const nonces = musig2.nonceGen(participantPublicKey, participantSecretKey, aggPublicKey);
+    this.secretNonce = nonces.secret;
+    return nonces.public;
+  }
+
+  /**
+   * Generates a partial signature using the participant's secret key + secret nonce.
+   * Requires the aggregated nonce to have been set first (via the service).
+   */
+  public generatePartialSignature(participantSecretKey: Uint8Array): Uint8Array {
+    if(!this.aggregatedNonce) {
+      throw new SigningSessionError('Aggregated nonce not available.', 'MISSING_AGGREGATED_NONCE');
+    }
+    if(!this.secretNonce) {
+      throw new SigningSessionError('Secret nonce not available — generateNonceContribution() must be called first.', 'MISSING_SECRET_NONCE');
+    }
+    const session = new musig2.Session(
+      this.aggregatedNonce,
+      this.cohort.cohortKeys,
+      this.sigHash,
+      [this.cohort.trMerkleRoot],
+      [true]
+    );
+    return session.sign(this.secretNonce, participantSecretKey);
+  }
+
+  public isComplete(): boolean {
+    return this.phase === SigningSessionPhase.Complete;
+  }
+
+  public isFailed(): boolean {
+    return this.phase === SigningSessionPhase.Failed;
+  }
+}

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

@@ -0,0 +1,42 @@
+import { NotImplementedError } from '@did-btcr2/common';
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import type { BaseMessage } from '../messages/base.js';
+import type { MessageHandler, Transport } from './transport.js';
+
+/**
+ * DIDComm Transport (stub).
+ *
+ * @class DidCommTransport
+ * @implements {Transport}
+ */
+export class DidCommTransport implements Transport {
+  public name: string = 'didcomm';
+
+  public start(): void {
+    throw new NotImplementedError('DidCommTransport not implemented. Use NostrTransport instead.');
+  }
+
+  public registerActor(_did: string, _keys: SchnorrKeyPair): void {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public getActorPk(_did: string): Uint8Array | undefined {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public registerPeer(_did: string, _communicationPk: Uint8Array): void {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public getPeerPk(_did: string): Uint8Array | undefined {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public registerMessageHandler(_actorDid: string, _messageType: string, _handler: MessageHandler): void {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public async sendMessage(_message: BaseMessage, _sender: string, _recipient?: string): Promise<void> {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+}

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

@@ -0,0 +1,13 @@
+import { MethodError } from '@did-btcr2/common';
+
+export class TransportError extends MethodError {
+  constructor(message: string, type: string = 'TransportError', data?: Record<string, any>) {
+    super(message, type, data);
+  }
+}
+
+export class TransportAdapterError extends MethodError {
+  constructor(message: string, type: string = 'TransportAdapterError', data?: Record<string, any>) {
+    super(message, type, data);
+  }
+}

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

@@ -0,0 +1,29 @@
+import { NotImplementedError } from '@did-btcr2/common';
+import { NostrTransport } from './nostr.js';
+import { TransportError } from './error.js';
+import type { Transport, TransportType } from './transport.js';
+
+export interface TransportConfig {
+  type: TransportType;
+  relays?: string[];
+}
+
+/**
+ * Factory for creating Transport instances.
+ * @class TransportFactory
+ */
+export class TransportFactory {
+  static establish(config: TransportConfig): Transport {
+    switch (config.type) {
+      case 'nostr':
+        return new NostrTransport({ relays: config.relays });
+      case 'didcomm':
+        throw new NotImplementedError('DIDComm transport not implemented yet.');
+      default:
+        throw new TransportError(
+          `Invalid transport type: ${config.type}`,
+          'INVALID_TRANSPORT_TYPE', { config }
+        );
+    }
+  }
+}

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

@@ -0,0 +1,5 @@
+export * from './transport.js';
+export * from './error.js';
+export * from './factory.js';
+export * from './nostr.js';
+export * from './didcomm.js';

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

@@ -0,0 +1,333 @@
+import type { Did } from '@did-btcr2/common';
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import type { Event, EventTemplate} from 'nostr-tools';
+import { finalizeEvent, nip44 } from 'nostr-tools';
+import { SimplePool } from 'nostr-tools/pool';
+import type { BaseMessage } from '../messages/base.js';
+import { COHORT_ADVERT } from '../messages/constants.js';
+import { isAggregationMessageType, isKeygenMessageType, isSignMessageType, isUpdateMessageType } from '../messages/guards.js';
+import { TransportAdapterError } from './error.js';
+import type { MessageHandler, Transport } from './transport.js';
+
+/**
+ * Default Nostr relay URLs.
+ * @constant {Array<string>} DEFAULT_NOSTR_RELAYS
+ */
+export const DEFAULT_NOSTR_RELAYS = [
+  'wss://relay.damus.io',
+  'wss://nos.lol',
+  'wss://relay.snort.social',
+  'wss://nostr-pub.wellorder.net',
+];
+
+export interface NostrTransportConfig {
+  relays?: string[];
+}
+
+/** Internal registration for a single actor sharing this transport. */
+interface ActorEntry {
+  keys: SchnorrKeyPair;
+  handlers: Map<string, MessageHandler>;
+}
+
+/**
+ * Nostr Transport for did:btcr2 aggregation messages.
+ *
+ * A single NostrTransport manages one relay pool and supports multiple
+ * registered actors. Each actor registers its own DID and keys via
+ * {@link registerActor}; the transport resolves the correct identity when
+ * sending or receiving.
+ *
+ * Message routing:
+ * - Keygen messages (COHORT_ADVERT, COHORT_OPT_IN, COHORT_OPT_IN_ACCEPT, COHORT_READY) → kind 1 (plaintext)
+ * - Update messages (SUBMIT_UPDATE, DISTRIBUTE_AGGREGATED_DATA, VALIDATION_ACK) → kind 1059 (NIP-44 encrypted)
+ * - Sign messages → kind 1059 (NIP-44 encrypted)
+ *
+ * @class NostrTransport
+ * @implements {Transport}
+ */
+export class NostrTransport implements Transport {
+  name: string = 'nostr';
+
+  pool?: SimplePool;
+  #relays: string[];
+  #actors: Map<string, ActorEntry> = new Map();
+  #peerRegistry: Map<string, Uint8Array> = new Map();
+  #started = false;
+
+  constructor(config?: NostrTransportConfig) {
+    this.#relays = config?.relays ?? DEFAULT_NOSTR_RELAYS;
+  }
+
+  /**
+   * Registers an actor (DID + keys) to send/receive messages with.
+   * Must be called before start() to ensure subscriptions are created for the actor.
+   * @param {string} did - The DID of the actor.
+   * @param {SchnorrKeyPair} keys - The Schnorr key pair for the actor.
+   * @throws {TransportAdapterError} If the actor is already registered or if the transport has already started.
+   * @example
+   * const transport = new NostrTransport();
+   * const keys = SchnorrKeyPair.generate();
+   * transport.registerActor('did:btcr2:...', keys);
+   * transport.start();
+   */
+  public registerActor(did: string, keys: SchnorrKeyPair): void {
+    const entry: ActorEntry = { keys, handlers: new Map() };
+    this.#actors.set(did, entry);
+
+    // If already started, create a directed subscription for this actor
+    if(this.#started && this.pool) {
+      this.#subscribeDirected(did, entry);
+    }
+  }
+
+  public getActorPk(did: string): Uint8Array | undefined {
+    return this.#actors.get(did)?.keys.publicKey.compressed;
+  }
+
+  public registerPeer(did: string, communicationPk: Uint8Array): void {
+    try {
+      new CompressedSecp256k1PublicKey(communicationPk);
+    } catch {
+      throw new TransportAdapterError(
+        `Invalid communication public key for peer ${did}: expected a 33-byte compressed secp256k1 key.`,
+        'INVALID_PEER_KEY', { adapter: this.name, did, keyLength: communicationPk.length }
+      );
+    }
+    this.#peerRegistry.set(did, communicationPk);
+  }
+
+  public getPeerPk(did: string): Uint8Array | undefined {
+    return this.#peerRegistry.get(did);
+  }
+
+  public registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void {
+    const actor = this.#actors.get(actorDid);
+    if(!actor) {
+      throw new TransportAdapterError(
+        `Cannot register handler: actor ${actorDid} not registered. Call registerActor() first.`,
+        'UNKNOWN_ACTOR_ERROR', { adapter: this.name, did: actorDid }
+      );
+    }
+    actor.handlers.set(messageType, handler);
+  }
+
+  public start(): NostrTransport {
+    if(this.#started) return this;
+    this.#started = true;
+
+    this.pool = new SimplePool();
+    const since = Math.floor(Date.now() / 1000);
+
+    // Broadcast subscription: kind 1 COHORT_ADVERT events (all actors receive these)
+    this.pool.subscribeMany(this.#relays, { kinds: [1], '#t': [COHORT_ADVERT], since }, {
+      onclose : (reasons: string[]) => console.debug('Nostr broadcast subscription closed', reasons),
+      onevent : this.#handleBroadcastEvent.bind(this),
+    });
+
+    // Directed subscriptions for any actors already registered
+    for(const [did, entry] of this.#actors) {
+      this.#subscribeDirected(did, entry);
+    }
+
+    console.info(`NostrTransport started, listening on ${this.#relays.length} relay(s)`);
+    return this;
+  }
+
+  public async sendMessage(message: BaseMessage, sender: Did, to?: Did): Promise<void> {
+    const type = message.type;
+
+    if(!type) {
+      throw new TransportAdapterError(
+        'Message type is undefined',
+        'SEND_MESSAGE_ERROR', { adapter: this.name, type }
+      );
+    }
+
+    const actor = this.#actors.get(sender);
+    if(!actor) {
+      throw new TransportAdapterError(
+        `Unknown sender: ${sender}. Call registerActor() before sending messages.`,
+        'UNKNOWN_ACTOR_ERROR', { adapter: this.name, did: sender }
+      );
+    }
+
+    const senderKeys = actor.keys;
+
+    // Sender p-tag matches the event signing key
+    const tags: string[][] = [
+      ['p', bytesToHex(senderKeys.publicKey.x)],
+      ['t', type],
+    ];
+
+    if(to) {
+      const recipientPkBytes = this.#peerRegistry.get(to);
+      if(recipientPkBytes) {
+        const recipientPk = new CompressedSecp256k1PublicKey(recipientPkBytes);
+        tags.push(['p', bytesToHex(recipientPk.x)]);
+      }
+    }
+
+    // Keygen messages: plaintext, kind 1
+    if(isKeygenMessageType(type)) {
+      const event = finalizeEvent({
+        kind       : 1,
+        created_at : Math.floor(Date.now() / 1000),
+        tags,
+        content    : JSON.stringify(message, NostrTransport.#jsonReplacer),
+      } as EventTemplate, senderKeys.secretKey.bytes);
+      console.debug(`Publishing kind 1 [${type}]`);
+      await this.#publishToRelays(event);
+      return;
+    }
+
+    // Update and sign messages: NIP-44 encrypted, kind 1059
+    if(isUpdateMessageType(type) || isSignMessageType(type)) {
+      if(!to) {
+        throw new TransportAdapterError(
+          `Encrypted messages require a recipient DID, got undefined for type: ${type}`,
+          'SEND_MESSAGE_ERROR', { adapter: this.name }
+        );
+      }
+      const recipientPkBytes = this.#peerRegistry.get(to);
+      if(!recipientPkBytes) {
+        throw new TransportAdapterError(
+          `Unknown peer DID: ${to}. Register peer via registerPeer() before sending encrypted messages.`,
+          'UNKNOWN_PEER_ERROR', { adapter: this.name, did: to }
+        );
+      }
+      const recipientPk = new CompressedSecp256k1PublicKey(recipientPkBytes);
+      const conversationKey = nip44.v2.utils.getConversationKey(
+        senderKeys.secretKey.bytes,
+        bytesToHex(recipientPk.x)
+      );
+      const content = nip44.v2.encrypt(JSON.stringify(message, NostrTransport.#jsonReplacer), conversationKey);
+
+      const event = finalizeEvent({
+        kind       : 1059,
+        created_at : Math.floor(Date.now() / 1000),
+        tags,
+        content,
+      } as EventTemplate, senderKeys.secretKey.bytes);
+      console.debug(`Publishing kind 1059 [${type}]`);
+      await this.#publishToRelays(event);
+      return;
+    }
+
+    console.warn(`Unsupported message type: ${type}`);
+  }
+
+  #subscribeDirected(did: string, entry: ActorEntry): void {
+    if(!this.pool) return;
+
+    const pkHex = bytesToHex(entry.keys.publicKey.x);
+    const since = Math.floor(Date.now() / 1000);
+
+    this.pool.subscribeMany(this.#relays, { kinds: [1, 1059], '#p': [pkHex], since }, {
+      onclose : (reasons: string[]) => console.debug(`Nostr directed subscription closed for ${did}`, reasons),
+      onevent : this.#makeActorEventHandler(did),
+    });
+  }
+
+  #makeActorEventHandler(actorDid: string): (event: Event) => Promise<void> {
+    return async (event: Event) => {
+      const actor = this.#actors.get(actorDid);
+      if(!actor) return;
+
+      let message: Record<string, unknown>;
+
+      try {
+        if(event.kind === 1) {
+          message = JSON.parse(event.content, NostrTransport.#jsonReviver);
+        } else if(event.kind === 1059) {
+          const conversationKey = nip44.v2.utils.getConversationKey(
+            actor.keys.secretKey.bytes,
+            event.pubkey
+          );
+          const plaintext = nip44.v2.decrypt(event.content, conversationKey);
+          message = JSON.parse(plaintext, NostrTransport.#jsonReviver);
+        } else {
+          return;
+        }
+      } catch(err) {
+        console.debug(`Failed to parse event ${event.id} for ${actorDid}:`, err);
+        return;
+      }
+
+      this.#dispatchMessage(message, actor);
+    };
+  }
+
+  async #handleBroadcastEvent(event: Event): Promise<void> {
+    if(event.kind !== 1) return;
+
+    let message: Record<string, unknown>;
+    try {
+      message = JSON.parse(event.content, NostrTransport.#jsonReviver);
+    } catch(err) {
+      console.debug(`Failed to parse broadcast event ${event.id}:`, err);
+      return;
+    }
+
+    if(message.body && typeof message.body === 'object') {
+      message = { ...message, ...(message.body as Record<string, unknown>) };
+    }
+
+    const messageType = message.type as string;
+    if(!messageType || !isAggregationMessageType(messageType)) return;
+
+    // Dispatch to ALL actors that have a handler for this message type
+    for(const actor of this.#actors.values()) {
+      const handler = actor.handlers.get(messageType);
+      if(handler) await handler(message);
+    }
+  }
+
+  #dispatchMessage(message: Record<string, unknown>, actor: ActorEntry): void {
+    if(message.body && typeof message.body === 'object') {
+      message = { ...message, ...(message.body as Record<string, unknown>) };
+    }
+
+    const messageType = message.type as string;
+    if(!messageType || !isAggregationMessageType(messageType)) return;
+
+    const handler = actor.handlers.get(messageType);
+    if(handler) handler(message);
+  }
+
+  async #publishToRelays(event: Event): Promise<void> {
+    const relayPromises = this.pool?.publish(this.#relays, event);
+    if(!relayPromises?.length) return;
+
+    const results = await Promise.allSettled(relayPromises);
+    const accepted = results.filter(r => r.status === 'fulfilled').length;
+    const rejected = results.filter(r => r.status === 'rejected');
+
+    for(const r of rejected) {
+      console.debug(`Relay rejected event ${event.id}: ${(r as PromiseRejectedResult).reason}`);
+    }
+
+    if(accepted === 0) {
+      throw new TransportAdapterError(
+        `All ${results.length} relay(s) rejected event ${event.id}`,
+        'PUBLISH_ERROR', { adapter: this.name, reasons: rejected.map(r => String((r as PromiseRejectedResult).reason)) }
+      );
+    }
+  }
+
+  static #jsonReplacer(_key: string, value: unknown): unknown {
+    if(value instanceof Uint8Array) {
+      return { __bytes: bytesToHex(value) };
+    }
+    return value;
+  }
+
+  static #jsonReviver(_key: string, value: unknown): unknown {
+    if(value && typeof value === 'object' && '__bytes' in (value as Record<string, unknown>)) {
+      return hexToBytes((value as { __bytes: string }).__bytes);
+    }
+    return value;
+  }
+}

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

@@ -0,0 +1,46 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import type { BaseMessage } from '../messages/base.js';
+
+export type SyncMessageHandler = (msg: any) => void;
+export type AsyncMessageHandler = (msg: any) => Promise<void>;
+export type MessageHandler = SyncMessageHandler | AsyncMessageHandler;
+
+export type TransportType = 'nostr' | 'didcomm';
+
+/**
+ * Multi-actor message transport.
+ *
+ * A single transport instance manages one connection (relay pool, channel, etc.)
+ * shared by all registered actors. Each actor registers its own DID and keys;
+ * the transport resolves the correct identity when sending or receiving messages.
+ *
+ * The transport is a pure passthrough — it knows nothing about the aggregation
+ * protocol. It only signs/encrypts outgoing messages with the sender's keys and
+ * dispatches incoming messages to the correct actor's registered handler.
+ *
+ * @interface Transport
+ */
+export interface Transport {
+  name: string;
+
+  /** Start the underlying transport (idempotent — only starts once). */
+  start(): void;
+
+  /** Register an actor (service or participant) with this transport. */
+  registerActor(did: string, keys: SchnorrKeyPair): void;
+
+  /** Return a registered actor's compressed communication public key. */
+  getActorPk(did: string): Uint8Array | undefined;
+
+  /** Store a remote peer's communication public key for encrypted routing. */
+  registerPeer(did: string, communicationPk: Uint8Array): void;
+
+  /** Retrieve a remote peer's communication public key. */
+  getPeerPk(did: string): Uint8Array | undefined;
+
+  /** Register a message handler scoped to a specific actor. */
+  registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void;
+
+  /** Send a message. The transport looks up sender to resolve signing keys. */
+  sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void>;
+}