libp2p-mesh 2026.5.13 → 2026.5.15

package/dist/src/types.d.ts

@@ -1,3 +1,21 @@
+export interface InstanceIdentity {
+    /** Full InstanceID string, e.g. "alice-mac@AQIDBAUGBweI.7a3f9e2b" */
+    id: string;
+    /** Human-readable instance name */
+    name: string;
+    /** Base64url-encoded Ed25519 public key */
+    pubkey: string;
+    /** Hex SHA-256 binding hash of environment dimensions */
+    binding: string;
+    /** Components that contributed to the binding hash */
+    bindingComponents: {
+        username: string;
+        hostname: string;
+        platform: string;
+    };
+    /** Timestamp when the identity was created */
+    createdAt: number;
+}
 export interface P2PMessage {
     id: string;
     type: "direct" | "broadcast" | "agent-sync";
@@ -6,6 +24,12 @@ export interface P2PMessage {
     topic?: string;
     payload: string;
     timestamp: number;
+    /** Instance identity of the sender (for cross-instance authentication) */
+    instanceId?: string;
+    /** Base64url-encoded Ed25519 public key of the sender (allows direct verification without DHT lookup) */
+    pubkey?: string;
+    /** Ed25519 signature of the message payload, verifiable with instance pubkey */
+    signature?: string;
 }
 export interface MeshConfig {
     listenAddrs?: string[];
@@ -15,6 +39,63 @@ export interface MeshConfig {
     enableAgentSync?: boolean;
     enableWebSocket?: boolean;
     peerIdPath?: string;
+    instanceName?: string;
+    /** Enable DHT for WAN peer discovery and pubkey registry (default: true when discovery=dht, false otherwise) */
+    enableDHT?: boolean;
+    /**
+     * Master switch for the NAT traversal stack. When `false` none of the
+     * NAT-related services are wired in, restoring the pre-2026.5.16
+     * behaviour. Default `true`.
+     */
+    enableNATTraversal?: boolean;
+    /** Run the libp2p identify protocol (required by AutoNAT/DCUtR). Default `true` when NAT traversal is on. */
+    enableIdentify?: boolean;
+    /** AutoNAT detects whether we are reachable from the public internet. Default `true` when NAT traversal is on. */
+    enableAutoNAT?: boolean;
+    /** Attempt UPnP/PMP port mapping on the local gateway. Default `true` when NAT traversal is on. */
+    enableUPnP?: boolean;
+    /** Circuit Relay v2 transport — required to dial peers via a relay. Default `true` when NAT traversal is on. */
+    enableCircuitRelay?: boolean;
+    /**
+     * Act as a Circuit Relay v2 server for other peers. Default `false` —
+     * only enable on a node with a public, routable address (e.g. a cloud VM)
+     * because relayed traffic is forwarded through this process.
+     */
+    enableCircuitRelayServer?: boolean;
+    /** Direct Connection Upgrade through Relay (hole punching). Default `true` when NAT traversal is on. */
+    enableDCUtR?: boolean;
+    /**
+     * Explicit relay multiaddrs to reserve a slot on. Each entry should be a
+     * full multiaddr ending in `/p2p/<peer-id>`. The node will keep a
+     * reservation open with each one so other peers can dial us through them.
+     */
+    relayList?: string[];
+    /**
+     * Number of relays to auto-discover via content routing. Requires DHT.
+     * Default `0` (disabled). Set to e.g. `2` to look up public relays.
+     */
+    discoverRelays?: number;
+    /**
+     * Multiaddrs to announce to the network on top of the auto-detected
+     * listen/observed addresses. Useful when running behind a known port
+     * forward where AutoNAT cannot probe (e.g. behind a cloud LB).
+     */
+    announceAddrs?: string[];
+}
+export interface NATTraversalStatus {
+    /** Which NAT-traversal services were wired in at start() */
+    enabled: {
+        identify: boolean;
+        autoNAT: boolean;
+        upnp: boolean;
+        circuitRelay: boolean;
+        circuitRelayServer: boolean;
+        dcutr: boolean;
+    };
+    /** Relay multiaddrs we have an active reservation on */
+    reservedRelays: string[];
+    /** Whether at least one circuit-relay address has been advertised as a listen address */
+    hasRelayedListenAddr: boolean;
 }
 export interface MeshNetwork {
     start(): Promise<void>;
@@ -25,6 +106,12 @@ export interface MeshNetwork {
     subscribeToTopic(topic: string, handler: (msg: string) => void): Promise<void>;
     getLocalPeerId(): string;
     getConnectedPeers(): string[];
+    getMultiaddrs(): string[];
+    dial(multiaddr: string): Promise<void>;
+    /** Get the OpenClaw instance identity (lightweight BAID-inspired ID) */
+    getInstanceIdentity(): InstanceIdentity | undefined;
+    /** Inspect which NAT-traversal services are running and whether any relay reservations are active */
+    getNATStatus(): NATTraversalStatus;
 }
 export type MeshAccount = {
     accountId: string;

package/index.ts

@@ -2,7 +2,7 @@ import { definePluginEntry } from "openclaw/plugin-sdk/core";
 import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk/core";
 import { registerLibp2pMesh } from "./src/plugin.js";
 
-export function createLibp2pMeshConfigSchema(): OpenClawPluginConfigSchema {
+function createLibp2pMeshConfigSchema(): OpenClawPluginConfigSchema {
   return {
     safeParse(value: unknown) {
       if (value === undefined) {
@@ -38,6 +38,7 @@ export function createLibp2pMeshConfigSchema(): OpenClawPluginConfigSchema {
         bootstrapList: {
           type: "array",
           items: { type: "string" },
+          description: "List of bootstrap multiaddrs for WAN discovery (required when discovery=dht or bootstrap)",
         },
         meshTopic: {
           type: "string",
@@ -51,29 +52,64 @@ export function createLibp2pMeshConfigSchema(): OpenClawPluginConfigSchema {
           type: "boolean",
           default: true,
         },
-        feishu: {
-          type: "object",
-          description: "Feishu integration configuration",
-          properties: {
-            appId: {
-              type: "string",
-              description: "Feishu app App ID",
-            },
-            appSecret: {
-              type: "string",
-              description: "Feishu app App Secret",
-            },
-            webhookPort: {
-              type: "number",
-              default: 9222,
-              description: "Port for Feishu webhook callback (default: 9222)",
-            },
-            webhookPath: {
-              type: "string",
-              default: "/webhook/feishu",
-              description: "Path for Feishu webhook callback",
-            },
-          },
+        enableDHT: {
+          type: "boolean",
+          default: true,
+          description: "Enable DHT for WAN peer discovery and pubkey registry. Default true when discovery=dht, can be explicitly disabled.",
+        },
+        instanceName: {
+          type: "string",
+          description: "Custom name for this OpenClaw instance (used in InstanceID). Defaults to \"<username>-<hostname>\".",
+        },
+        enableNATTraversal: {
+          type: "boolean",
+          default: true,
+          description: "Master switch for the NAT traversal stack (identify + AutoNAT + UPnP + Circuit Relay v2 + DCUtR). Set to false to restore pre-NAT behaviour.",
+        },
+        enableIdentify: {
+          type: "boolean",
+          default: true,
+          description: "Run the libp2p identify protocol; required by AutoNAT and DCUtR.",
+        },
+        enableAutoNAT: {
+          type: "boolean",
+          default: true,
+          description: "Use AutoNAT to learn whether this node is publicly reachable.",
+        },
+        enableUPnP: {
+          type: "boolean",
+          default: true,
+          description: "Attempt UPnP/PMP port mapping against the local gateway so other peers can dial us directly when behind a home router.",
+        },
+        enableCircuitRelay: {
+          type: "boolean",
+          default: true,
+          description: "Allow this node to dial peers via /p2p-circuit relay addresses and to reserve a slot on the relays in relayList.",
+        },
+        enableCircuitRelayServer: {
+          type: "boolean",
+          default: false,
+          description: "Act as a Circuit Relay v2 SERVER for other peers. Only enable on a publicly reachable node (e.g. a cloud VM).",
+        },
+        enableDCUtR: {
+          type: "boolean",
+          default: true,
+          description: "Direct Connection Upgrade through Relay (hole punching). Upgrades a relayed connection to a direct one when possible.",
+        },
+        relayList: {
+          type: "array",
+          items: { type: "string" },
+          description: "Multiaddrs of relay nodes to reserve a slot on (each entry must end in /p2p/<peer-id>).",
+        },
+        discoverRelays: {
+          type: "number",
+          default: 0,
+          description: "How many relays to auto-discover via content routing. Requires DHT. 0 disables discovery.",
+        },
+        announceAddrs: {
+          type: "array",
+          items: { type: "string" },
+          description: "Extra multiaddrs to announce to the network (useful when running behind a known port forward where AutoNAT cannot probe).",
         },
       },
     },

package/openclaw.plugin.json

@@ -1,5 +1,10 @@
 {
   "id": "libp2p-mesh",
+  "activation": {
+    "onStartup": true
+  },
+  "channels": ["libp2p-mesh"],
+  "enabledByDefault": true,
   "name": "libp2p Mesh Network",
   "description": "P2P network for cross-instance agent communication via libp2p.",
   "configSchema": {
@@ -36,42 +41,76 @@
       "enableAgentSync": {
         "type": "boolean",
         "default": true
+      },
+      "enableDHT": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable DHT for WAN peer discovery and pubkey registry."
+      },
+      "instanceName": {
+        "type": "string",
+        "description": "Custom name for this OpenClaw instance (used in InstanceID). Defaults to \"<username>-<hostname>\"."
+      },
+      "enableNATTraversal": {
+        "type": "boolean",
+        "default": true,
+        "description": "Master switch for the NAT traversal stack (identify + AutoNAT + UPnP + Circuit Relay v2 + DCUtR)."
+      },
+      "enableIdentify": {
+        "type": "boolean",
+        "default": true,
+        "description": "Run the libp2p identify protocol; required by AutoNAT and DCUtR."
+      },
+      "enableAutoNAT": {
+        "type": "boolean",
+        "default": true,
+        "description": "Use AutoNAT to learn whether this node is publicly reachable."
+      },
+      "enableUPnP": {
+        "type": "boolean",
+        "default": true,
+        "description": "Attempt UPnP/PMP port mapping on the local gateway."
+      },
+      "enableCircuitRelay": {
+        "type": "boolean",
+        "default": true,
+        "description": "Dial peers via /p2p-circuit relay addresses; reserve a slot on each entry in relayList."
+      },
+      "enableCircuitRelayServer": {
+        "type": "boolean",
+        "default": false,
+        "description": "Act as a Circuit Relay v2 server. Only enable on a publicly reachable node."
+      },
+      "enableDCUtR": {
+        "type": "boolean",
+        "default": true,
+        "description": "Direct Connection Upgrade through Relay (hole punching)."
+      },
+      "relayList": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Multiaddrs of relays to reserve a slot on (each entry must end in /p2p/<peer-id>)."
+      },
+      "discoverRelays": {
+        "type": "number",
+        "default": 0,
+        "description": "Auto-discover this many relays via content routing. Requires DHT."
+      },
+      "announceAddrs": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Extra multiaddrs to announce to the network on top of auto-detected ones."
       }
     }
   },
-  "channels": ["libp2p-mesh", "feishu"],
-  "channelConfigs": {
-    "libp2p-mesh": {
-      "schema": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "listenAddrs": {
-            "type": "array",
-            "items": { "type": "string" },
-            "default": ["/ip4/0.0.0.0/tcp/0"]
-          },
-          "enableWebSocket": {
-            "type": "boolean",
-            "default": false,
-            "description": "Enable WebSocket transport"
-          },
-          "discovery": {
-            "type": "string",
-            "enum": ["mdns", "bootstrap", "dht"],
-            "default": "mdns"
-          },
-          "bootstrapList": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "meshTopic": {
-            "type": "string",
-            "default": "openclaw-mesh"
-          }
-        }
-      }
-    }
+  "contracts": {
+    "tools": [
+      "p2p_send_message",
+      "p2p_broadcast",
+      "p2p_list_peers",
+      "p2p_get_instance_identity",
+      "p2p_get_network_info"
+    ]
   },
   "uiHints": {
     "listenAddrs": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2p-mesh",
-  "version": "2026.5.13",
+  "version": "2026.5.15",
   "description": "OpenClaw libp2p P2P mesh network plugin for cross-instance agent communication",
   "type": "module",
   "main": "dist/index.js",
@@ -19,24 +19,26 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@libp2p/bootstrap": "^10.1.5",
+    "@libp2p/bootstrap": "^9.0.12",
+    "@libp2p/kad-dht": "^10.0.0",
     "@libp2p/mdns": "^9.0.14",
     "@libp2p/mplex": "^9.0.12",
     "@libp2p/noise": "^12.0.1",
+    "@libp2p/peer-id": "^3.0.6",
     "@libp2p/peer-id-factory": "^3.0.11",
     "@libp2p/tcp": "^8.0.13",
-    "@libp2p/websockets": "^8.2.0",
+    "@libp2p/websockets": "^7.0.13",
     "@multiformats/multiaddr": "^12.5.1",
-    "it-length-prefixed": "^10.0.1",
+    "it-length-prefixed": "^9.0.1",
     "it-pipe": "^3.0.1",
     "libp2p": "^0.46.16",
     "uint8arraylist": "^2.4.8"
   },
   "devDependencies": {
+    "@types/node": "^25.7.0",
     "openclaw": "^2026.5.7",
     "tsx": "^4.0.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.8"
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
     "openclaw": ">=2026.3.24"
@@ -61,7 +63,7 @@
       "systemImage": "network"
     },
     "install": {
-      "npmSpec": "openclaw-libp2p-mesh",
+      "npmSpec": "libp2p-mesh",
       "defaultChoice": "npm",
       "minHostVersion": ">=2026.3.24"
     },
@@ -99,5 +101,15 @@
   "bugs": {
     "url": "https://github.com/lilingfy/openclaw-libp2p-mesh/issues"
   },
-  "homepage": "https://github.com/lilingfy/openclaw-libp2p-mesh#readme"
+  "homepage": "https://github.com/lilingfy/openclaw-libp2p-mesh#readme",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@google/genai",
+      "esbuild",
+      "koffi",
+      "openclaw",
+      "protobufjs",
+      "tree-sitter-bash"
+    ]
+  }
 }

package/src/agent-tools.ts

@@ -1,5 +1,4 @@
 import type { MeshNetwork } from "./types.js";
-import type { FeishuApiClient } from "./feishu-client.js";
 
 export function buildP2PTools(mesh: MeshNetwork) {
   return [
@@ -113,48 +112,83 @@ export function buildP2PTools(mesh: MeshNetwork) {
         }
       },
     },
-  ];
-}
-
-export function buildFeishuTools(feishuClient: FeishuApiClient | null) {
-  if (!feishuClient) return [];
-  return [
     {
-      name: "feishu_send_message",
-      label: "Feishu Send Message",
-      description: "Send a text message to a Feishu user by their openId. Use this to notify users through Feishu.",
+      name: "p2p_get_instance_identity",
+      label: "P2P Get Instance Identity",
+      description: "Get the OpenClaw instance identity (lightweight BAID-inspired ID) of this node.",
       parameters: {
         type: "object" as const,
-        properties: {
-          openId: {
-            type: "string" as const,
-            description: "Feishu openId of the recipient",
-          },
-          message: {
-            type: "string" as const,
-            description: "Text message content to send",
-          },
-        },
-        required: ["openId", "message"],
+        properties: {},
       },
-      async execute(_toolCallId: string, params: { openId: string; message: string }) {
-        const result = await feishuClient.sendMessage(params.openId, params.message);
-        if (result.success) {
+      async execute(_toolCallId: string) {
+        try {
+          const identity = mesh.getInstanceIdentity();
+          if (!identity) {
+            return {
+              content: [{ type: "text" as const, text: "Instance identity not yet initialized." }],
+              details: { initialized: false },
+            };
+          }
+          const lines = [
+            `Instance ID: ${identity.id}`,
+            `Name:        ${identity.name}`,
+            `Pubkey:      ${identity.pubkey.slice(0, 32)}...`,
+            `Binding:     ${identity.binding.slice(0, 16)}...`,
+            `Bound to:    ${identity.bindingComponents.username}@${identity.bindingComponents.hostname} (${identity.bindingComponents.platform})`,
+            `Created:     ${new Date(identity.createdAt).toLocaleString()}`,
+          ];
+          return {
+            content: [{ type: "text" as const, text: lines.join("\n") }],
+            details: { identity },
+          };
+        } catch (err) {
           return {
-            content: [{ type: "text" as const, text: `Message sent to Feishu user ${params.openId}` }],
-            details: { sent: true, openId: params.openId, messageId: result.messageId },
+            content: [{ type: "text" as const, text: `Error: ${String(err)}` }],
+            details: { error: String(err) },
+            isError: true,
           };
         }
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: `Failed to send Feishu message to ${params.openId}: ${result.error}`,
+      },
+    },
+    {
+      name: "p2p_get_network_info",
+      label: "P2P Get Network Info",
+      description: "Get combined network and identity info: Peer ID, Instance ID, listen addresses, and connected peers.",
+      parameters: {
+        type: "object" as const,
+        properties: {},
+      },
+      async execute(_toolCallId: string) {
+        try {
+          const identity = mesh.getInstanceIdentity();
+          const peerId = mesh.getLocalPeerId();
+          const addrs = mesh.getMultiaddrs();
+          const peers = mesh.getConnectedPeers();
+
+          const lines = [
+            `Peer ID:      ${peerId || "(not started)"}`,
+            `Instance ID:  ${identity?.id || "(not initialized)"}`,
+            `Instance:     ${identity?.bindingComponents.username}@${identity?.bindingComponents.hostname}` || "",
+            `Listen Addrs: ${addrs.length > 0 ? addrs.join(", ") : "(none)"}`,
+            `Connected:    ${peers.length} peer(s)${peers.length > 0 ? ": " + peers.join(", ") : ""}`,
+          ];
+
+          return {
+            content: [{ type: "text" as const, text: lines.join("\n") }],
+            details: {
+              peerId,
+              instanceId: identity?.id,
+              listenAddrs: addrs,
+              connectedPeers: peers,
             },
-          ],
-          details: { sent: false, openId: params.openId, error: result.error },
-          isError: true,
-        };
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text" as const, text: `Error: ${String(err)}` }],
+            details: { error: String(err) },
+            isError: true,
+          };
+        }
       },
     },
   ];

package/src/channel.ts

@@ -2,8 +2,12 @@ import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
 import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
 import type { MeshNetwork, MeshAccount } from "./types.js";
 import { sendViaMesh } from "./send.js";
+import {
+  getLibp2pMeshRuntime,
+  hasLibp2pMeshRuntime,
+} from "../runtime-setter-api.js";
 
-export function createLibp2pMeshChannel(mesh: MeshNetwork): ChannelPlugin {
+function buildChannel(getMesh: () => MeshNetwork): ChannelPlugin {
   return createChatChannelPlugin<MeshAccount>({
     base: {
       id: "libp2p-mesh",
@@ -42,7 +46,9 @@ export function createLibp2pMeshChannel(mesh: MeshNetwork): ChannelPlugin {
           name: "default",
           configured: true,
           enabled: true,
-          connected: mesh.getConnectedPeers().length > 0,
+          connected: hasLibp2pMeshRuntime()
+            ? getMesh().getConnectedPeers().length > 0
+            : false,
         }),
       },
       messaging: {
@@ -57,12 +63,27 @@ export function createLibp2pMeshChannel(mesh: MeshNetwork): ChannelPlugin {
       deliveryMode: "gateway",
       sendText: async ({ to, text }) => {
         try {
-          await sendViaMesh(mesh, to, text);
+          await sendViaMesh(getMesh(), to, text);
           return { channel: "libp2p-mesh", messageId: `p2p-${Date.now()}` };
         } catch (err) {
-          return { channel: "libp2p-mesh", messageId: `p2p-${Date.now()}`, meta: { error: String(err) } };
+          return {
+            channel: "libp2p-mesh",
+            messageId: `p2p-${Date.now()}`,
+            meta: { error: String(err) },
+          };
         }
       },
     },
   }) as ChannelPlugin;
 }
+
+// Static channel plugin export for the bundled-channel-entry contract.
+// The mesh instance is resolved lazily through runtime-setter-api.ts, which
+// plugin.ts populates after starting the mesh service.
+export const libp2pMeshPlugin: ChannelPlugin = buildChannel(getLibp2pMeshRuntime);
+
+// Backwards-compatible factory: kept so any caller that still passes the mesh
+// instance directly (e.g. the standalone plugin entry) continues to work.
+export function createLibp2pMeshChannel(mesh: MeshNetwork): ChannelPlugin {
+  return buildChannel(() => mesh);
+}