cairn-p2p 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -1319,6 +1319,67 @@ var MessageQueue = class {
   }
 };
 
+// src/transport/libp2p-node.ts
+function defaultTransportConfig() {
+  return {
+    quicEnabled: true,
+    tcpEnabled: true,
+    websocketEnabled: true,
+    webtransportEnabled: true,
+    webrtcEnabled: true,
+    circuitRelayEnabled: true,
+    perTransportTimeoutMs: 1e4,
+    stunServers: [
+      "stun:stun.l.google.com:19302",
+      "stun:stun1.l.google.com:19302"
+    ],
+    turnServers: []
+  };
+}
+function isNodeEnvironment() {
+  return typeof globalThis.process !== "undefined" && typeof globalThis.process.versions !== "undefined" && typeof globalThis.process.versions.node !== "undefined";
+}
+async function createCairnNode(options) {
+  const config = { ...defaultTransportConfig(), ...options?.config };
+  const { createLibp2p } = await import("libp2p");
+  const { yamux } = await import("@libp2p/yamux");
+  const { noise } = await import("@chainsafe/libp2p-noise");
+  const transports = [];
+  if (isNodeEnvironment()) {
+    if (config.tcpEnabled) {
+      const { tcp } = await import("@libp2p/tcp");
+      transports.push(tcp());
+    }
+    if (config.websocketEnabled) {
+      const { webSockets } = await import("@libp2p/websockets");
+      transports.push(webSockets());
+    }
+  } else {
+    if (config.webrtcEnabled) {
+      const { webRTC } = await import("@libp2p/webrtc");
+      transports.push(webRTC());
+    }
+    if (config.websocketEnabled) {
+      const { webSockets } = await import("@libp2p/websockets");
+      transports.push(webSockets());
+    }
+    if (config.webtransportEnabled) {
+      const { webTransport } = await import("@libp2p/webtransport");
+      transports.push(webTransport());
+    }
+  }
+  if (config.circuitRelayEnabled) {
+    const { circuitRelayTransport } = await import("@libp2p/circuit-relay-v2");
+    transports.push(circuitRelayTransport());
+  }
+  const node = await createLibp2p({
+    transports,
+    streamMuxers: [yamux()],
+    connectionEncrypters: [noise()]
+  });
+  return node;
+}
+
 // src/node.ts
 var APP_MSG_TYPE_MIN = 61440;
 var APP_MSG_TYPE_MAX = 65535;
@@ -1526,6 +1587,10 @@ var Node = class _Node {
   _closed = false;
   _identity = null;
   _pairedPeers = /* @__PURE__ */ new Set();
+  /** The libp2p node instance (null until startTransport is called). */
+  _libp2pNode = null;
+  /** Listen addresses reported by the libp2p node. */
+  _listenAddresses = [];
   constructor(config) {
     this._config = config;
   }
@@ -1565,6 +1630,40 @@ var Node = class _Node {
     node._identity = await IdentityKeypair.generate();
     return node;
   }
+  /**
+   * Create a node AND start the transport layer.
+   * This is the recommended entry point for applications that need real
+   * network connectivity.
+   */
+  static async createAndStart(config) {
+    const node = await _Node.create(config);
+    await node.startTransport();
+    return node;
+  }
+  /**
+   * Start the libp2p transport layer.
+   *
+   * Creates a libp2p node with environment-appropriate transports
+   * (WebRTC + WebSocket in browser, TCP + WebSocket in Node.js),
+   * starts listening, and populates listen addresses.
+   *
+   * Safe to skip in unit tests — the node works without transport.
+   */
+  async startTransport() {
+    const libp2pNode = await createCairnNode();
+    await libp2pNode.start();
+    this._libp2pNode = libp2pNode;
+    const addrs = libp2pNode.getMultiaddrs();
+    this._listenAddresses = addrs.map((a) => a.toString());
+  }
+  /** Get the libp2p node (null if transport not started). */
+  get libp2pNode() {
+    return this._libp2pNode;
+  }
+  /** Get the node's listen addresses (available after startTransport). */
+  get listenAddresses() {
+    return [...this._listenAddresses];
+  }
   /** Get the node configuration. */
   get config() {
     return this._config;
@@ -1614,11 +1713,12 @@ var Node = class _Node {
     const nonce = generateNonce();
     const now = Math.floor(Date.now() / 1e3);
     const ttlSec = Math.floor(this._config.reconnectionPolicy.pairingPayloadExpiry / 1e3);
+    const hints = this._listenAddresses.length > 0 ? this._listenAddresses.map((addr) => ({ hintType: "multiaddr", value: addr })) : void 0;
     return {
       peerId: this._identity.peerId(),
       nonce,
       pakeCredential: nonce,
-      // use nonce as PAKE credential (same as Rust)
+      hints,
       createdAt: now,
       expiresAt: now + ttlSec
     };

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { Libp2p } from 'libp2p';
+
 /**
  * Storage adapter interface for persisting identity, per-peer state, and
  * per-session state. All values are opaque Uint8Array blobs.
@@ -460,6 +462,10 @@ declare class Node {
     private _closed;
     private _identity;
     private readonly _pairedPeers;
+    /** The libp2p node instance (null until startTransport is called). */
+    private _libp2pNode;
+    /** Listen addresses reported by the libp2p node. */
+    private _listenAddresses;
     private constructor();
     /** Create a new cairn peer node with zero-config defaults (Tier 0). */
     static create(config?: Partial<CairnConfig>): Promise<Node>;
@@ -470,6 +476,26 @@ declare class Node {
      * meshEnabled: true, relayWilling: true, relayCapacity: 100, etc.
      */
     static createServer(config?: Partial<CairnConfig>): Promise<Node>;
+    /**
+     * Create a node AND start the transport layer.
+     * This is the recommended entry point for applications that need real
+     * network connectivity.
+     */
+    static createAndStart(config?: Partial<CairnConfig>): Promise<Node>;
+    /**
+     * Start the libp2p transport layer.
+     *
+     * Creates a libp2p node with environment-appropriate transports
+     * (WebRTC + WebSocket in browser, TCP + WebSocket in Node.js),
+     * starts listening, and populates listen addresses.
+     *
+     * Safe to skip in unit tests — the node works without transport.
+     */
+    startTransport(): Promise<void>;
+    /** Get the libp2p node (null if transport not started). */
+    get libp2pNode(): Libp2p | null;
+    /** Get the node's listen addresses (available after startTransport). */
+    get listenAddresses(): string[];
     /** Get the node configuration. */
     get config(): ResolvedConfig;
     /** Whether this node has been closed. */

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { Libp2p } from 'libp2p';
+
 /**
  * Storage adapter interface for persisting identity, per-peer state, and
  * per-session state. All values are opaque Uint8Array blobs.
@@ -460,6 +462,10 @@ declare class Node {
     private _closed;
     private _identity;
     private readonly _pairedPeers;
+    /** The libp2p node instance (null until startTransport is called). */
+    private _libp2pNode;
+    /** Listen addresses reported by the libp2p node. */
+    private _listenAddresses;
     private constructor();
     /** Create a new cairn peer node with zero-config defaults (Tier 0). */
     static create(config?: Partial<CairnConfig>): Promise<Node>;
@@ -470,6 +476,26 @@ declare class Node {
      * meshEnabled: true, relayWilling: true, relayCapacity: 100, etc.
      */
     static createServer(config?: Partial<CairnConfig>): Promise<Node>;
+    /**
+     * Create a node AND start the transport layer.
+     * This is the recommended entry point for applications that need real
+     * network connectivity.
+     */
+    static createAndStart(config?: Partial<CairnConfig>): Promise<Node>;
+    /**
+     * Start the libp2p transport layer.
+     *
+     * Creates a libp2p node with environment-appropriate transports
+     * (WebRTC + WebSocket in browser, TCP + WebSocket in Node.js),
+     * starts listening, and populates listen addresses.
+     *
+     * Safe to skip in unit tests — the node works without transport.
+     */
+    startTransport(): Promise<void>;
+    /** Get the libp2p node (null if transport not started). */
+    get libp2pNode(): Libp2p | null;
+    /** Get the node's listen addresses (available after startTransport). */
+    get listenAddresses(): string[];
     /** Get the node configuration. */
     get config(): ResolvedConfig;
     /** Whether this node has been closed. */

package/dist/index.js

@@ -1264,6 +1264,67 @@ var MessageQueue = class {
   }
 };
 
+// src/transport/libp2p-node.ts
+function defaultTransportConfig() {
+  return {
+    quicEnabled: true,
+    tcpEnabled: true,
+    websocketEnabled: true,
+    webtransportEnabled: true,
+    webrtcEnabled: true,
+    circuitRelayEnabled: true,
+    perTransportTimeoutMs: 1e4,
+    stunServers: [
+      "stun:stun.l.google.com:19302",
+      "stun:stun1.l.google.com:19302"
+    ],
+    turnServers: []
+  };
+}
+function isNodeEnvironment() {
+  return typeof globalThis.process !== "undefined" && typeof globalThis.process.versions !== "undefined" && typeof globalThis.process.versions.node !== "undefined";
+}
+async function createCairnNode(options) {
+  const config = { ...defaultTransportConfig(), ...options?.config };
+  const { createLibp2p } = await import("libp2p");
+  const { yamux } = await import("@libp2p/yamux");
+  const { noise } = await import("@chainsafe/libp2p-noise");
+  const transports = [];
+  if (isNodeEnvironment()) {
+    if (config.tcpEnabled) {
+      const { tcp } = await import("@libp2p/tcp");
+      transports.push(tcp());
+    }
+    if (config.websocketEnabled) {
+      const { webSockets } = await import("@libp2p/websockets");
+      transports.push(webSockets());
+    }
+  } else {
+    if (config.webrtcEnabled) {
+      const { webRTC } = await import("@libp2p/webrtc");
+      transports.push(webRTC());
+    }
+    if (config.websocketEnabled) {
+      const { webSockets } = await import("@libp2p/websockets");
+      transports.push(webSockets());
+    }
+    if (config.webtransportEnabled) {
+      const { webTransport } = await import("@libp2p/webtransport");
+      transports.push(webTransport());
+    }
+  }
+  if (config.circuitRelayEnabled) {
+    const { circuitRelayTransport } = await import("@libp2p/circuit-relay-v2");
+    transports.push(circuitRelayTransport());
+  }
+  const node = await createLibp2p({
+    transports,
+    streamMuxers: [yamux()],
+    connectionEncrypters: [noise()]
+  });
+  return node;
+}
+
 // src/node.ts
 var APP_MSG_TYPE_MIN = 61440;
 var APP_MSG_TYPE_MAX = 65535;
@@ -1471,6 +1532,10 @@ var Node = class _Node {
   _closed = false;
   _identity = null;
   _pairedPeers = /* @__PURE__ */ new Set();
+  /** The libp2p node instance (null until startTransport is called). */
+  _libp2pNode = null;
+  /** Listen addresses reported by the libp2p node. */
+  _listenAddresses = [];
   constructor(config) {
     this._config = config;
   }
@@ -1510,6 +1575,40 @@ var Node = class _Node {
     node._identity = await IdentityKeypair.generate();
     return node;
   }
+  /**
+   * Create a node AND start the transport layer.
+   * This is the recommended entry point for applications that need real
+   * network connectivity.
+   */
+  static async createAndStart(config) {
+    const node = await _Node.create(config);
+    await node.startTransport();
+    return node;
+  }
+  /**
+   * Start the libp2p transport layer.
+   *
+   * Creates a libp2p node with environment-appropriate transports
+   * (WebRTC + WebSocket in browser, TCP + WebSocket in Node.js),
+   * starts listening, and populates listen addresses.
+   *
+   * Safe to skip in unit tests — the node works without transport.
+   */
+  async startTransport() {
+    const libp2pNode = await createCairnNode();
+    await libp2pNode.start();
+    this._libp2pNode = libp2pNode;
+    const addrs = libp2pNode.getMultiaddrs();
+    this._listenAddresses = addrs.map((a) => a.toString());
+  }
+  /** Get the libp2p node (null if transport not started). */
+  get libp2pNode() {
+    return this._libp2pNode;
+  }
+  /** Get the node's listen addresses (available after startTransport). */
+  get listenAddresses() {
+    return [...this._listenAddresses];
+  }
   /** Get the node configuration. */
   get config() {
     return this._config;
@@ -1559,11 +1658,12 @@ var Node = class _Node {
     const nonce = generateNonce();
     const now = Math.floor(Date.now() / 1e3);
     const ttlSec = Math.floor(this._config.reconnectionPolicy.pairingPayloadExpiry / 1e3);
+    const hints = this._listenAddresses.length > 0 ? this._listenAddresses.map((addr) => ({ hintType: "multiaddr", value: addr })) : void 0;
     return {
       peerId: this._identity.peerId(),
       nonce,
       pakeCredential: nonce,
-      // use nonce as PAKE credential (same as Rust)
+      hints,
       createdAt: now,
       expiresAt: now + ttlSec
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-p2p",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/node.ts

@@ -33,6 +33,9 @@ import type { MessageEnvelope } from './protocol/envelope.js';
 import { DATA_MESSAGE } from './protocol/message-types.js';
 import { MessageQueue } from './session/message-queue.js';
 import type { EnqueueResult } from './session/message-queue.js';
+import type { ConnectionHint } from './pairing/payload.js';
+import type { Libp2p } from 'libp2p';
+import { createCairnNode } from './transport/libp2p-node.js';
 
 /** Fully resolved configuration with no optional fields. */
 export interface ResolvedConfig {
@@ -333,6 +336,10 @@ export class Node {
   private _closed = false;
   private _identity: IdentityKeypair | null = null;
   private readonly _pairedPeers = new Set<string>();
+  /** The libp2p node instance (null until startTransport is called). */
+  private _libp2pNode: Libp2p | null = null;
+  /** Listen addresses reported by the libp2p node. */
+  private _listenAddresses: string[] = [];
 
   private constructor(config: ResolvedConfig) {
     this._config = config;
@@ -377,6 +384,46 @@ export class Node {
     return node;
   }
 
+  /**
+   * Create a node AND start the transport layer.
+   * This is the recommended entry point for applications that need real
+   * network connectivity.
+   */
+  static async createAndStart(config?: Partial<CairnConfig>): Promise<Node> {
+    const node = await Node.create(config);
+    await node.startTransport();
+    return node;
+  }
+
+  /**
+   * Start the libp2p transport layer.
+   *
+   * Creates a libp2p node with environment-appropriate transports
+   * (WebRTC + WebSocket in browser, TCP + WebSocket in Node.js),
+   * starts listening, and populates listen addresses.
+   *
+   * Safe to skip in unit tests — the node works without transport.
+   */
+  async startTransport(): Promise<void> {
+    const libp2pNode = await createCairnNode();
+    await libp2pNode.start();
+    this._libp2pNode = libp2pNode;
+
+    // Collect listen addresses
+    const addrs = libp2pNode.getMultiaddrs();
+    this._listenAddresses = addrs.map(a => a.toString());
+  }
+
+  /** Get the libp2p node (null if transport not started). */
+  get libp2pNode(): Libp2p | null {
+    return this._libp2pNode;
+  }
+
+  /** Get the node's listen addresses (available after startTransport). */
+  get listenAddresses(): string[] {
+    return [...this._listenAddresses];
+  }
+
   /** Get the node configuration. */
   get config(): ResolvedConfig {
     return this._config;
@@ -436,10 +483,17 @@ export class Node {
     const nonce = generateNonce();
     const now = Math.floor(Date.now() / 1000);
     const ttlSec = Math.floor(this._config.reconnectionPolicy.pairingPayloadExpiry / 1000);
+
+    // Include listen addresses as connection hints if transport is running
+    const hints: ConnectionHint[] | undefined = this._listenAddresses.length > 0
+      ? this._listenAddresses.map(addr => ({ hintType: 'multiaddr', value: addr }))
+      : undefined;
+
     return {
       peerId: this._identity.peerId(),
       nonce,
-      pakeCredential: nonce, // use nonce as PAKE credential (same as Rust)
+      pakeCredential: nonce,
+      hints,
       createdAt: now,
       expiresAt: now + ttlSec,
     };