libp2p-mesh 2026.5.13 → 2026.5.15

package/README.md

@@ -9,7 +9,7 @@ P2P mesh network plugin for OpenClaw. Enables direct peer-to-peer communication
 - **Broadcast** — Publish messages to a shared topic, flood-fill forwarded across the mesh
 - **Bootstrap Mode** — Optional static bootstrap peer list for non-LAN scenarios
 - **WebSocket Transport** — Optional WebSocket support for NAT/firewall-friendly connections
-- **Feishu Integration (Beta)** — Receive and send messages via Feishu (Lark) IM, with automatic P2P forwarding
+- **NAT Traversal** — Built-in AutoNAT + UPnP + Circuit Relay v2 + DCUtR for peers behind home routers / firewalls
 
 ## Requirements
 
@@ -22,7 +22,7 @@ P2P mesh network plugin for OpenClaw. Enables direct peer-to-peer communication
 ### Method 1: Via OpenClaw CLI (Recommended)
 
 ```bash
-openclaw plugins install libp2p-mesh-v1
+openclaw install openclaw-libp2p-mesh
 ```
 
 ### Method 2: Manual (npm)
@@ -31,7 +31,7 @@ openclaw plugins install libp2p-mesh-v1
 
 ```bash
 cd ~/.openclaw/npm
-npm install libp2p-mesh-v1
+npm install openclaw-libp2p-mesh
 ```
 
 然后刷新插件注册表：
@@ -146,34 +146,72 @@ If peers are on different networks, use a bootstrap node:
 | `enableWebSocket` | `boolean` | `false` | Enable WebSocket transport for browser/NAT compatibility |
 | `meshTopic` | `string` | `"openclaw-mesh"` | Default broadcast topic |
 | `enableAgentSync` | `boolean` | `true` | Enable agent state synchronization over the mesh |
+| `enableNATTraversal` | `boolean` | `true` | Master switch for identify + AutoNAT + UPnP + Circuit Relay v2 + DCUtR |
+| `enableIdentify` | `boolean` | `true` | libp2p identify protocol (required by AutoNAT and DCUtR) |
+| `enableAutoNAT` | `boolean` | `true` | AutoNAT — detect whether this node is publicly reachable |
+| `enableUPnP` | `boolean` | `true` | Attempt UPnP/PMP port mapping on the local gateway |
+| `enableCircuitRelay` | `boolean` | `true` | Dial peers via /p2p-circuit relay addresses |
+| `enableCircuitRelayServer` | `boolean` | `false` | Act as a Circuit Relay v2 server (only enable on a public node) |
+| `enableDCUtR` | `boolean` | `true` | Hole-punching: upgrade a relayed connection to a direct one |
+| `relayList` | `string[]` | `[]` | Multiaddrs of relays to reserve a slot on |
+| `discoverRelays` | `number` | `0` | Auto-discover this many relays via content routing |
+| `announceAddrs` | `string[]` | `[]` | Extra multiaddrs to announce on top of auto-detected ones |
 
-## Feishu 集成（Beta）
+## NAT Traversal
 
-OpenClaw 可以通过飞书与用户交互。配置后，你的 OpenClaw 实例会：
-- 接收你在飞书中的消息
-- 通过 P2P mesh 与其他 OpenClaw 实例通信
-- 将 P2P 消息自动转发到你的飞书
+When both peers have a routable address (same LAN, public IPs, or working port-forwarding) no extra setup is needed. The defaults above kick in automatically:
 
-### 配置步骤
+- **UPnP** asks your home router to open a port for libp2p TCP.
+- **AutoNAT** asks peers to verify whether you're reachable from the outside.
+- If you're not directly reachable, **Circuit Relay v2** lets another peer (the "relay") forward traffic on your behalf. The relay only sees encrypted bytes — Noise still terminates end-to-end at the original peers.
+- Once a relayed connection is established, **DCUtR** tries to upgrade it to a direct connection via simultaneous TCP open (hole punching). This works for most home NATs (full-cone, restricted-cone, port-restricted) but not symmetric NATs (CGNAT, some carrier networks).
 
-1. 在[飞书开放平台](https://open.feishu.cn/)创建企业自建应用
-2. 开启"机器人"能力，获取 App ID 和 App Secret
-3. 配置事件订阅：请求地址填 `http://<your-host>:9222/webhook/feishu`
-4. 订阅事件类型：`im.message.receive_v1`
-5. 在 OpenClaw 配置中添加：
+### Behind a NAT — minimal config
 
-```yaml
-feishu:
-  appId: "cli-xxxxxxxxxx"
-  appSecret: "xxxxxxxxxxxxxxxx"
-  webhookPort: 9222
-  webhookPath: "/webhook/feishu"
+You need at least one relay node with a public IP. Set it in `relayList`:
+
+```json
+{
+  "plugins": {
+    "libp2p-mesh": {
+      "enabled": true,
+      "config": {
+        "discovery": "bootstrap",
+        "bootstrapList": [
+          "/ip4/<RELAY-IP>/tcp/4001/p2p/<RELAY-PEER-ID>"
+        ],
+        "relayList": [
+          "/ip4/<RELAY-IP>/tcp/4001/p2p/<RELAY-PEER-ID>"
+        ]
+      }
+    }
+  }
+}
 ```
 
-### 部署要求
+After start-up you should see your node listening on a `/p2p-circuit` address — that's how remote peers will reach you.
+
+### Running your own relay on a public VM
+
+Add `enableCircuitRelayServer: true` to your config and announce the public address so other peers can dial you:
+
+```json
+{
+  "plugins": {
+    "libp2p-mesh": {
+      "enabled": true,
+      "config": {
+        "discovery": "bootstrap",
+        "listenAddrs": ["/ip4/0.0.0.0/tcp/4001"],
+        "announceAddrs": ["/ip4/<PUBLIC-IP>/tcp/4001"],
+        "enableCircuitRelayServer": true
+      }
+    }
+  }
+}
+```
 
-- webhook 端口必须对飞书服务器可达（公网 IP 或端口映射）
-- 本地开发可以使用 ngrok: `ngrok http 9222`
+> Detailed walkthrough including how to rent a cloud VM is in `../TESTING_NAT.md`.
 
 ## Usage: Two Computers on the Same LAN
 

package/api.ts

@@ -1,2 +1,2 @@
 export { createMeshNetwork } from "./src/mesh.js";
-export type { MeshNetwork, P2PMessage, MeshConfig } from "./src/types.js";
+export type { MeshNetwork, P2PMessage, MeshConfig, InstanceIdentity } from "./src/types.js";

package/dist/api.d.ts

@@ -1,2 +1,2 @@
 export { createMeshNetwork } from "./src/mesh.js";
-export type { MeshNetwork, P2PMessage, MeshConfig } from "./src/types.js";
+export type { MeshNetwork, P2PMessage, MeshConfig, InstanceIdentity } from "./src/types.js";

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk/core";
-export declare function createLibp2pMeshConfigSchema(): OpenClawPluginConfigSchema;
 declare const _default: {
     id: string;
     name: string;

package/dist/index.js

@@ -1,6 +1,6 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/core";
 import { registerLibp2pMesh } from "./src/plugin.js";
-export function createLibp2pMeshConfigSchema() {
+function createLibp2pMeshConfigSchema() {
     return {
         safeParse(value) {
             if (value === undefined) {
@@ -36,6 +36,7 @@ export function createLibp2pMeshConfigSchema() {
                 bootstrapList: {
                     type: "array",
                     items: { type: "string" },
+                    description: "List of bootstrap multiaddrs for WAN discovery (required when discovery=dht or bootstrap)",
                 },
                 meshTopic: {
                     type: "string",
@@ -49,29 +50,64 @@ export function createLibp2pMeshConfigSchema() {
                     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/dist/runtime-setter-api.d.ts

@@ -0,0 +1,4 @@
+import type { MeshNetwork } from "./src/types.js";
+export declare function setLibp2pMeshRuntime(mesh: MeshNetwork): void;
+export declare function getLibp2pMeshRuntime(): MeshNetwork;
+export declare function hasLibp2pMeshRuntime(): boolean;

package/dist/runtime-setter-api.js

@@ -0,0 +1,19 @@
+// Narrow setter for the libp2p-mesh runtime. The bundled channel entry needs
+// a static `libp2pMeshPlugin` export to satisfy openclaw's bundled-channel
+// contract; the channel itself however needs the mesh runtime, which is
+// constructed inside registerFull(). We bridge the two via this module-level
+// holder: registerFull() calls setLibp2pMeshRuntime(mesh) after starting the
+// service, and channel.ts reads from getLibp2pMeshRuntime() when sending.
+let _runtime = null;
+export function setLibp2pMeshRuntime(mesh) {
+    _runtime = mesh;
+}
+export function getLibp2pMeshRuntime() {
+    if (!_runtime) {
+        throw new Error("libp2p-mesh: runtime not initialized — registerFull() must call setLibp2pMeshRuntime() before any channel call");
+    }
+    return _runtime;
+}
+export function hasLibp2pMeshRuntime() {
+    return _runtime !== null;
+}

package/dist/src/agent-tools.d.ts

@@ -1,5 +1,4 @@
 import type { MeshNetwork } from "./types.js";
-import type { FeishuApiClient } from "./feishu-client.js";
 export declare function buildP2PTools(mesh: MeshNetwork): ({
     name: string;
     label: string;
@@ -128,37 +127,27 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         };
         isError: boolean;
     }>;
-})[];
-export declare function buildFeishuTools(feishuClient: FeishuApiClient | null): {
+} | {
     name: string;
     label: string;
     description: string;
     parameters: {
         type: "object";
         properties: {
-            openId: {
-                type: "string";
-                description: string;
-            };
-            message: {
-                type: "string";
-                description: string;
-            };
+            peerId?: undefined;
+            message?: undefined;
+            topic?: undefined;
         };
-        required: string[];
+        required?: undefined;
     };
-    execute(_toolCallId: string, params: {
-        openId: string;
-        message: string;
-    }): Promise<{
+    execute(_toolCallId: string): Promise<{
         content: {
             type: "text";
             text: string;
         }[];
         details: {
-            sent: boolean;
-            openId: string;
-            messageId: string | undefined;
+            initialized: boolean;
+            identity?: undefined;
             error?: undefined;
         };
         isError?: undefined;
@@ -168,11 +157,61 @@ export declare function buildFeishuTools(feishuClient: FeishuApiClient | null):
             text: string;
         }[];
         details: {
-            sent: boolean;
-            openId: string;
-            error: string | undefined;
-            messageId?: undefined;
+            identity: import("./types.js").InstanceIdentity;
+            initialized?: undefined;
+            error?: undefined;
+        };
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            error: string;
+            initialized?: undefined;
+            identity?: undefined;
         };
         isError: boolean;
     }>;
-}[];
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            peerId?: undefined;
+            message?: undefined;
+            topic?: undefined;
+        };
+        required?: undefined;
+    };
+    execute(_toolCallId: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            peerId: string;
+            instanceId: string | undefined;
+            listenAddrs: string[];
+            connectedPeers: string[];
+            error?: undefined;
+        };
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            error: string;
+            peerId?: undefined;
+            instanceId?: undefined;
+            listenAddrs?: undefined;
+            connectedPeers?: undefined;
+        };
+        isError: boolean;
+    }>;
+})[];

package/dist/src/agent-tools.js

@@ -112,48 +112,83 @@ export function buildP2PTools(mesh) {
                 }
             },
         },
-    ];
-}
-export function buildFeishuTools(feishuClient) {
-    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",
-                properties: {
-                    openId: {
-                        type: "string",
-                        description: "Feishu openId of the recipient",
-                    },
-                    message: {
-                        type: "string",
-                        description: "Text message content to send",
-                    },
-                },
-                required: ["openId", "message"],
+                properties: {},
             },
-            async execute(_toolCallId, params) {
-                const result = await feishuClient.sendMessage(params.openId, params.message);
-                if (result.success) {
+            async execute(_toolCallId) {
+                try {
+                    const identity = mesh.getInstanceIdentity();
+                    if (!identity) {
+                        return {
+                            content: [{ type: "text", 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", text: lines.join("\n") }],
+                        details: { identity },
+                    };
+                }
+                catch (err) {
                     return {
-                        content: [{ type: "text", text: `Message sent to Feishu user ${params.openId}` }],
-                        details: { sent: true, openId: params.openId, messageId: result.messageId },
+                        content: [{ type: "text", text: `Error: ${String(err)}` }],
+                        details: { error: String(err) },
+                        isError: true,
                     };
                 }
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            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",
+                properties: {},
+            },
+            async execute(_toolCallId) {
+                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", 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", text: `Error: ${String(err)}` }],
+                        details: { error: String(err) },
+                        isError: true,
+                    };
+                }
             },
         },
     ];

package/dist/src/channel.d.ts

@@ -1,3 +1,4 @@
 import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
 import type { MeshNetwork } from "./types.js";
+export declare const libp2pMeshPlugin: ChannelPlugin;
 export declare function createLibp2pMeshChannel(mesh: MeshNetwork): ChannelPlugin;

package/dist/src/channel.js

@@ -1,6 +1,7 @@
 import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
 import { sendViaMesh } from "./send.js";
-export function createLibp2pMeshChannel(mesh) {
+import { getLibp2pMeshRuntime, hasLibp2pMeshRuntime, } from "../runtime-setter-api.js";
+function buildChannel(getMesh) {
     return createChatChannelPlugin({
         base: {
             id: "libp2p-mesh",
@@ -39,7 +40,9 @@ export function createLibp2pMeshChannel(mesh) {
                     name: "default",
                     configured: true,
                     enabled: true,
-                    connected: mesh.getConnectedPeers().length > 0,
+                    connected: hasLibp2pMeshRuntime()
+                        ? getMesh().getConnectedPeers().length > 0
+                        : false,
                 }),
             },
             messaging: {
@@ -54,13 +57,26 @@ export function createLibp2pMeshChannel(mesh) {
             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) },
+                    };
                 }
             },
         },
     });
 }
+// 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 = 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) {
+    return buildChannel(() => mesh);
+}

package/dist/src/dht-registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * DHT-based public key registry for cross-instance identity verification.
+ *
+ * Each OpenClaw instance publishes its Ed25519 pubkey to the DHT under the key:
+ *   openclaw:pubkey:<instanceId>
+ *
+ * Other instances can look up this pubkey to verify message signatures.
+ */
+import type { KadDHT } from "@libp2p/kad-dht";
+/**
+ * Register this instance's pubkey in the DHT.
+ * Other nodes can later look it up to verify signatures from this instance.
+ */
+export declare function registerPubkey(dht: KadDHT, instanceId: string, pubkey: string, logger?: {
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+    warn?: (msg: string) => void;
+}): Promise<void>;
+/**
+ * Look up a pubkey from the DHT for the given instanceId.
+ * Results are cached locally to avoid repeated DHT queries.
+ */
+export declare function lookupPubkey(dht: KadDHT, instanceId: string, logger?: {
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+    warn?: (msg: string) => void;
+}): Promise<string | undefined>;
+/**
+ * Clear the local pubkey cache.
+ */
+export declare function clearPubkeyCache(): void;
+/**
+ * Get cache stats for observability.
+ */
+export declare function getCacheStats(): {
+    size: number;
+    keys: string[];
+};