@did-btcr2/method 0.29.0 → 0.32.0

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

@@ -1,12 +1,14 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { KeyBytes, PatchOperation } from '@did-btcr2/common';
+import type { PatchOperation } from '@did-btcr2/common';
 import { type SignedBTCR2Update, type UnsignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import { type Btcr2DidDocument, type DidVerificationMethod } from '../utils/did-document.js';
 import type { BeaconService } from './beacon/interfaces.js';
 /**
- * The updater needs the caller to supply a signing key (or a KMS-backed signature)
- * for the given verification method. The unsigned update is attached so the caller
- * can inspect it before producing a signature.
+ * The updater needs the caller to supply a {@link Signer} for the given
+ * verification method. The unsigned update is attached so the caller can
+ * inspect it before producing a signature. The signer can wrap a local secret
+ * key (`LocalSigner`), a KMS-managed key (`KeyManagerSigner`), or any custom backend.
  */
 export interface NeedSigningKey {
     readonly kind: 'NeedSigningKey';
@@ -29,6 +31,18 @@ export interface NeedFunding {
     /** The beacon service this address belongs to. */
     readonly beaconService: BeaconService;
 }
+/**
+ * Optional proof the caller passes when fulfilling {@link NeedFunding}. The
+ * state machine asserts the proof before transitioning to Broadcast. Sans-I/O
+ * is preserved: the caller still performs the UTXO lookup; this is just a
+ * contract-level handshake.
+ */
+export interface FundingProof {
+    /** Number of spendable UTXOs the caller observed at the beacon address. Must be >= 1. */
+    utxoCount: number;
+    /** Optional txid the caller funded with, for diagnostics. */
+    txid?: string;
+}
 /**
  * The updater needs the caller to broadcast the signed update via the beacon.
  *
@@ -86,20 +100,21 @@ export interface UpdaterParams {
  *
  * ```typescript
  * const updater = DidBtcr2.update({ sourceDocument, patches, ... });
+ * const signer = new LocalSigner(secretKeyBytes); // or KeyManagerSigner / custom
  * let state = updater.advance();
  *
  * while(state.status === 'action-required') {
  *   for(const need of state.needs) {
  *     switch(need.kind) {
  *       case 'NeedSigningKey':
- *         updater.provide(need, secretKeyBytes);
+ *         updater.provide(need, signer);
  *         break;
  *       case 'NeedFunding':
  *         // Check UTXOs at need.beaconAddress, fund if needed
  *         updater.provide(need);
  *         break;
  *       case 'NeedBroadcast':
- *         await Updater.announce(need.beaconService, need.signedUpdate, secretKey, bitcoin);
+ *         await Updater.announce(need.beaconService, need.signedUpdate, signer, bitcoin);
  *         updater.provide(need);
  *         break;
  *     }
@@ -143,21 +158,21 @@ export declare class Updater {
      * @param {string} did The did-btcr2 identifier to derive the root capability from.
      * @param {UnsignedBTCR2Update} unsignedUpdate The unsigned update to sign.
      * @param {DidVerificationMethod} verificationMethod The verification method for signing.
-     * @param {KeyBytes} secretKey The secret key bytes.
+     * @param {Signer} signer Signer that produces the BIP-340 Schnorr signature.
      * @returns {SignedBTCR2Update} The signed update with a Data Integrity proof.
      */
-    static sign(did: string, unsignedUpdate: UnsignedBTCR2Update, verificationMethod: DidVerificationMethod, secretKey: KeyBytes): SignedBTCR2Update;
+    static sign(did: string, unsignedUpdate: UnsignedBTCR2Update, verificationMethod: DidVerificationMethod, signer: Signer): SignedBTCR2Update;
     /**
      * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#announce-did-update | 7.3.d Announce DID Update}.
      * Announces a signed update to the Bitcoin blockchain via the specified beacon.
      *
      * @param {BeaconService} beaconService The beacon service to broadcast through.
      * @param {SignedBTCR2Update} update The signed update to announce.
-     * @param {KeyBytes} secretKey The secret key for signing the Bitcoin transaction.
+     * @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.
      */
-    static announce(beaconService: BeaconService, update: SignedBTCR2Update, secretKey: KeyBytes, bitcoin: BitcoinConnection): Promise<SignedBTCR2Update>;
+    static announce(beaconService: BeaconService, update: SignedBTCR2Update, signer: Signer, bitcoin: BitcoinConnection): Promise<SignedBTCR2Update>;
     /**
      * Advance the state machine. Returns either:
      * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
@@ -171,8 +186,8 @@ export declare class Updater {
      * @param need The DataNeed being fulfilled (from the `needs` array).
      * @param data The data payload corresponding to the need kind (omit for NeedFunding/NeedBroadcast).
      */
-    provide(need: NeedSigningKey, data: KeyBytes): void;
-    provide(need: NeedFunding): void;
+    provide(need: NeedSigningKey, data: Signer): void;
+    provide(need: NeedFunding, proof?: FundingProof): void;
     provide(need: NeedBroadcast): void;
 }
 //# sourceMappingURL=updater.d.ts.map

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.29.0",
+  "version": "0.32.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",
@@ -80,11 +80,11 @@
     "helia": "^5.5.1",
     "multiformats": "^13.4.2",
     "nostr-tools": "^2.23.3",
-    "@did-btcr2/smt": "^0.2.4",
-    "@did-btcr2/cryptosuite": "^6.0.6",
     "@did-btcr2/bitcoin": "^0.6.0",
-    "@did-btcr2/common": "^9.0.0",
-    "@did-btcr2/keypair": "^0.11.4"
+    "@did-btcr2/common": "^9.1.0",
+    "@did-btcr2/cryptosuite": "^8.0.0",
+    "@did-btcr2/smt": "^0.2.4",
+    "@did-btcr2/keypair": "^0.13.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

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

@@ -1,28 +1,64 @@
 import { NotImplementedError } from '@did-btcr2/common';
-import { NostrTransport } from './nostr.js';
+import type { Logger } from '../logger.js';
 import { TransportError } from './error.js';
-import type { Transport, TransportType } from './transport.js';
+import type { HttpClientTransportConfig } from './http/client.js';
+import { HttpClientTransport } from './http/client.js';
+import type { HttpServerTransportConfig } from './http/server.js';
+import { HttpServerTransport } from './http/server.js';
+import { NostrTransport } from './nostr.js';
+import type { Transport } from './transport.js';
+
+/** Discriminated-union config for {@link TransportFactory.establish}. */
+export type TransportConfig =
+  | NostrTransportConfigOption
+  | DidCommTransportConfigOption
+  | HttpClientTransportConfigOption
+  | HttpServerTransportConfigOption;
 
-export interface TransportConfig {
-  type: TransportType;
+export interface NostrTransportConfigOption {
+  type: 'nostr';
   relays?: string[];
+  logger?: Logger;
+  broadcastLookbackMs?: number;
+}
+
+export interface DidCommTransportConfigOption {
+  type: 'didcomm';
 }
 
-/**
- * Factory for creating Transport instances.
- * @class TransportFactory
- */
+export interface HttpClientTransportConfigOption extends HttpClientTransportConfig {
+  type: 'http';
+  role: 'client';
+}
+
+export interface HttpServerTransportConfigOption extends HttpServerTransportConfig {
+  type: 'http';
+  role: 'server';
+}
+
+/** Factory for creating Transport instances. */
 export class TransportFactory {
   static establish(config: TransportConfig): Transport {
-    switch (config.type) {
+    switch(config.type) {
       case 'nostr':
-        return new NostrTransport({ relays: config.relays });
+        return new NostrTransport({
+          relays              : config.relays,
+          logger              : config.logger,
+          broadcastLookbackMs : config.broadcastLookbackMs,
+        });
       case 'didcomm':
         throw new NotImplementedError('DIDComm transport not implemented yet.');
+      case 'http':
+        if(config.role === 'client') return new HttpClientTransport(config);
+        if(config.role === 'server') return new HttpServerTransport(config);
+        throw new NotImplementedError(
+          `HTTP transport role not implemented: ${(config as { role: string }).role}`,
+        );
       default:
         throw new TransportError(
-          `Invalid transport type: ${config.type}`,
-          'INVALID_TRANSPORT_TYPE', { config }
+          `Invalid transport type: ${(config as { type: string }).type}`,
+          'INVALID_TRANSPORT_TYPE',
+          { config },
         );
     }
   }

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

@@ -0,0 +1,409 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
+
+import { Identifier } from '../../../identifier.js';
+import type { Logger } from '../../logger.js';
+import { CONSOLE_LOGGER } from '../../logger.js';
+import type { BaseMessage } from '../../messages/base.js';
+import type { MessageHandler, Transport } from '../transport.js';
+import { reviveFromWire, signEnvelope, verifyEnvelope } from './envelope.js';
+import { HttpTransportError } from './errors.js';
+import {
+  DEFAULT_CLOCK_SKEW_SEC,
+  HTTP_ROUTE,
+  SSE_EVENT,
+  type SignedEnvelope,
+} from './protocol.js';
+import { buildRequestAuth } from './request-auth.js';
+import { parseSseStream } from './sse-stream.js';
+
+export interface HttpClientTransportConfig {
+  /** Base URL of the aggregation service (e.g. `https://aggregator.example.com/`). */
+  baseUrl: string | URL;
+  /** Custom `fetch` implementation (tests, Workers, React Native). Defaults to `globalThis.fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Diagnostic logger. Defaults to {@link CONSOLE_LOGGER}. */
+  logger?: Logger;
+  /** Reconnect backoff (ms) given attempt count (0-based). */
+  reconnectBackoff?: (attempt: number) => number;
+  /** Envelope / request-auth clock-skew tolerance in seconds. */
+  clockSkewSec?: number;
+}
+
+/** Default exponential backoff: 1s, 2s, 4s, ..., capped at 30s, 20% jitter. */
+export function defaultReconnectBackoff(attempt: number): number {
+  const base   = Math.min(1000 * 2 ** attempt, 30_000);
+  const jitter = base * 0.2 * Math.random();
+  return Math.floor(base + jitter);
+}
+
+interface ActorEntry {
+  keys: SchnorrKeyPair;
+  handlers: Map<string, MessageHandler>;
+  inboxAbort?: AbortController;
+}
+
+/**
+ * HTTP transport client. Implements the transport-agnostic {@link Transport}
+ * interface; the wire is fetch-based SSE for incoming events and fetch-based
+ * POST for outgoing messages. All runtime I/O goes through `fetchImpl` so
+ * tests can substitute a mock without touching the network.
+ */
+export class HttpClientTransport implements Transport {
+  readonly name = 'http';
+
+  readonly #baseUrl:      URL;
+  readonly #fetch:        typeof fetch;
+  readonly #logger:       Logger;
+  readonly #backoff:      (attempt: number) => number;
+  readonly #clockSkewSec: number;
+
+  readonly #actors: Map<string, ActorEntry>   = new Map();
+  readonly #peers:  Map<string, Uint8Array>   = new Map();
+
+  #started = false;
+  #broadcastAbort?: AbortController;
+
+  constructor(config: HttpClientTransportConfig) {
+    const base = typeof config.baseUrl === 'string' ? new URL(config.baseUrl) : new URL(config.baseUrl.href);
+    if(!base.pathname.endsWith('/')) base.pathname += '/';
+    this.#baseUrl      = base;
+    this.#logger       = config.logger ?? CONSOLE_LOGGER;
+    this.#backoff      = config.reconnectBackoff ?? defaultReconnectBackoff;
+    this.#clockSkewSec = config.clockSkewSec ?? DEFAULT_CLOCK_SKEW_SEC;
+
+    const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+    if(typeof fetchImpl !== 'function') {
+      throw new HttpTransportError(
+        'No fetch implementation available. Pass config.fetchImpl explicitly.',
+        'NO_FETCH_IMPL',
+      );
+    }
+    this.#fetch = fetchImpl;
+  }
+
+  start(): void {
+    if(this.#started) return;
+    this.#started = true;
+
+    this.#broadcastAbort = new AbortController();
+    this.#runBroadcastLoop(this.#broadcastAbort.signal);
+
+    for(const [did, entry] of this.#actors) {
+      this.#openInbox(did, entry);
+    }
+  }
+
+  /**
+   * Tear down all SSE subscriptions and stop reconnect loops. Not part of the
+   * {@link Transport} interface, but needed in tests and whenever a client
+   * wants to cleanly disconnect without unregistering every actor.
+   *
+   * Idempotent. Actors remain registered (re-call {@link start} to resume).
+   */
+  stop(): void {
+    this.#broadcastAbort?.abort();
+    this.#broadcastAbort = undefined;
+    for(const entry of this.#actors.values()) {
+      entry.inboxAbort?.abort();
+      entry.inboxAbort = undefined;
+    }
+    this.#started = false;
+  }
+
+  registerActor(did: string, keys: SchnorrKeyPair): void {
+    const existing = this.#actors.get(did);
+    if(existing?.inboxAbort) existing.inboxAbort.abort();
+
+    const entry: ActorEntry = { keys, handlers: new Map() };
+    this.#actors.set(did, entry);
+    if(this.#started) this.#openInbox(did, entry);
+  }
+
+  unregisterActor(did: string): void {
+    const entry = this.#actors.get(did);
+    if(!entry) return;
+    entry.inboxAbort?.abort();
+    this.#actors.delete(did);
+    this.#peers.delete(did);
+  }
+
+  getActorPk(did: string): Uint8Array | undefined {
+    return this.#actors.get(did)?.keys.publicKey.compressed;
+  }
+
+  registerPeer(did: string, communicationPk: Uint8Array): void {
+    try {
+      new CompressedSecp256k1PublicKey(communicationPk);
+    } catch {
+      throw new HttpTransportError(
+        `Invalid communication public key for peer ${did}: expected a 33-byte compressed secp256k1 key.`,
+        'INVALID_PEER_KEY',
+        { did, keyLength: communicationPk.length },
+      );
+    }
+    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) {
+      throw new HttpTransportError(
+        `Cannot register handler: actor ${actorDid} not registered. Call registerActor() first.`,
+        'UNKNOWN_ACTOR',
+        { did: actorDid },
+      );
+    }
+    actor.handlers.set(messageType, handler);
+  }
+
+  unregisterMessageHandler(actorDid: string, messageType: string): void {
+    this.#actors.get(actorDid)?.handlers.delete(messageType);
+  }
+
+  async sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void> {
+    const actor = this.#actors.get(sender);
+    if(!actor) {
+      throw new HttpTransportError(
+        `Unknown sender: ${sender}. Call registerActor() before sending messages.`,
+        'UNKNOWN_SENDER',
+        { did: sender },
+      );
+    }
+
+    const envelope = signEnvelope(
+      message,
+      { did: sender, keys: actor.keys },
+      { to: recipient },
+    );
+
+    const url = this.#route(HTTP_ROUTE.MESSAGES);
+    const res = await this.#fetch(url, {
+      method  : 'POST',
+      headers : { 'content-type': 'application/json' },
+      body    : JSON.stringify(envelope),
+    });
+
+    if(!res.ok) {
+      const body = await safeText(res);
+      throw new HttpTransportError(
+        `sendMessage failed: HTTP ${res.status}`,
+        'SEND_MESSAGE_HTTP',
+        { status: res.status, body: body.slice(0, 256), messageType: message.type },
+      );
+    }
+  }
+
+  publishRepeating(
+    message:   BaseMessage,
+    sender:    string,
+    intervalMs: number,
+    recipient?: string,
+  ): () => void {
+    let stopped = false;
+    const attempt = (): void => {
+      if(stopped) return;
+      this.sendMessage(message, sender, recipient).catch((err) => {
+        this.#logger.debug('publishRepeating send failed:', err);
+      });
+    };
+    attempt();
+    const timer = setInterval(attempt, intervalMs);
+    return (): void => {
+      if(stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    };
+  }
+
+  #route(template: string): URL {
+    // Strip the leading slash so `new URL(rel, base)` is resolved against the
+    // base's pathname instead of replacing it.
+    return new URL(template.replace(/^\//, ''), this.#baseUrl);
+  }
+
+  #openInbox(did: string, entry: ActorEntry): void {
+    const abort = new AbortController();
+    entry.inboxAbort = abort;
+    this.#runInboxLoop(did, entry, abort.signal);
+  }
+
+  async #runBroadcastLoop(signal: AbortSignal): Promise<void> {
+    const url = this.#route(HTTP_ROUTE.ADVERTS);
+    let attempt = 0;
+    while(!signal.aborted) {
+      try {
+        const res = await this.#fetch(url, {
+          method  : 'GET',
+          headers : { accept: 'text/event-stream' },
+          signal,
+        });
+        if(!res.ok || !res.body) {
+          this.#logger.warn(`Broadcast subscribe failed: HTTP ${res.status}`);
+          await sleep(this.#backoff(attempt++), signal);
+          continue;
+        }
+        attempt = 0;
+        for await (const ev of parseSseStream(res.body)) {
+          if(signal.aborted) return;
+          if(ev.event !== SSE_EVENT.ADVERT) continue;
+          this.#dispatchBroadcast(ev.data);
+        }
+      } catch(err) {
+        if(signal.aborted) return;
+        this.#logger.debug('Broadcast loop error:', err);
+        try {
+          await sleep(this.#backoff(attempt++), signal);
+        } catch {
+          return; // sleep was aborted
+        }
+      }
+    }
+  }
+
+  async #runInboxLoop(did: string, entry: ActorEntry, signal: AbortSignal): Promise<void> {
+    const url = this.#route(HTTP_ROUTE.ACTOR_INBOX.replace('{did}', encodeURIComponent(did)));
+    let attempt = 0;
+    while(!signal.aborted) {
+      try {
+        const auth = buildRequestAuth(did, entry.keys, url.pathname);
+        const res = await this.#fetch(url, {
+          method  : 'GET',
+          headers : { accept: 'text/event-stream', authorization: auth },
+          signal,
+        });
+        if(!res.ok || !res.body) {
+          this.#logger.warn(`Inbox subscribe failed for ${did}: HTTP ${res.status}`);
+          await sleep(this.#backoff(attempt++), signal);
+          continue;
+        }
+        attempt = 0;
+        for await (const ev of parseSseStream(res.body)) {
+          if(signal.aborted) return;
+          if(ev.event !== SSE_EVENT.MESSAGE) continue;
+          await this.#dispatchInbox(ev.data, did, entry);
+        }
+      } catch(err) {
+        if(signal.aborted) return;
+        this.#logger.debug(`Inbox loop error for ${did}:`, err);
+        try {
+          await sleep(this.#backoff(attempt++), signal);
+        } catch {
+          return;
+        }
+      }
+    }
+  }
+
+  #dispatchBroadcast(dataJson: string): void {
+    const envelope = parseEnvelope(dataJson, this.#logger);
+    if(!envelope) return;
+
+    const senderPk = this.#resolveSenderPk(envelope.from);
+    if(!senderPk) {
+      this.#logger.debug(`Broadcast from unresolvable DID: ${envelope.from}`);
+      return;
+    }
+    try {
+      verifyEnvelope(envelope, senderPk, { clockSkewSec: this.#clockSkewSec });
+    } catch(err) {
+      this.#logger.debug('Broadcast envelope verification failed:', err);
+      return;
+    }
+
+    const revived = reviveFromWire(envelope.message) as Record<string, unknown>;
+    const flat = flattenMessage(revived);
+    const messageType = typeof flat.type === 'string' ? flat.type : undefined;
+    if(!messageType) return;
+
+    for(const actor of this.#actors.values()) {
+      const handler = actor.handlers.get(messageType);
+      if(handler) void Promise.resolve(handler(flat));
+    }
+  }
+
+  async #dispatchInbox(dataJson: string, actorDid: string, entry: ActorEntry): Promise<void> {
+    const envelope = parseEnvelope(dataJson, this.#logger);
+    if(!envelope) return;
+
+    const senderPk = this.#resolveSenderPk(envelope.from);
+    if(!senderPk) {
+      this.#logger.debug(`Inbox message from unresolvable DID: ${envelope.from}`);
+      return;
+    }
+    try {
+      verifyEnvelope(envelope, senderPk, {
+        clockSkewSec : this.#clockSkewSec,
+        expectedTo   : actorDid,
+      });
+    } catch(err) {
+      this.#logger.debug(`Inbox envelope verification failed for ${actorDid}:`, err);
+      return;
+    }
+
+    const revived = reviveFromWire(envelope.message) as Record<string, unknown>;
+    const flat = flattenMessage(revived);
+    const messageType = typeof flat.type === 'string' ? flat.type : undefined;
+    if(!messageType) return;
+
+    const handler = entry.handlers.get(messageType);
+    if(handler) await handler(flat);
+  }
+
+  #resolveSenderPk(did: string): CompressedSecp256k1PublicKey | undefined {
+    const peerBytes = this.#peers.get(did);
+    if(peerBytes) {
+      try { return new CompressedSecp256k1PublicKey(peerBytes); }
+      catch { /* fall through to DID decode */ }
+    }
+    try {
+      const components = Identifier.decode(did);
+      if(components.idType === 'KEY') {
+        return new CompressedSecp256k1PublicKey(components.genesisBytes);
+      }
+    } catch {
+      // Not a decodable did:btcr2 KEY identifier.
+    }
+    return undefined;
+  }
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if(ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(new Error('aborted'));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    if(signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+async function safeText(res: Response): Promise<string> {
+  try { return await res.text(); }
+  catch { return ''; }
+}
+
+function parseEnvelope(dataJson: string, logger: Logger): SignedEnvelope | undefined {
+  try { return JSON.parse(dataJson) as SignedEnvelope; }
+  catch(err) {
+    logger.debug('SSE event: failed to parse envelope JSON:', err);
+    return undefined;
+  }
+}
+
+function flattenMessage(msg: Record<string, unknown>): Record<string, unknown> {
+  if(msg.body && typeof msg.body === 'object') {
+    return { ...msg, ...(msg.body as Record<string, unknown>) };
+  }
+  return msg;
+}