libp2p-mesh 2026.5.12 → 2026.5.14

package/README.md

@@ -9,6 +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
+- **NAT Traversal** — Built-in AutoNAT + UPnP + Circuit Relay v2 + DCUtR for peers behind home routers / firewalls
 
 ## Requirements
 
@@ -145,6 +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 |
+
+## NAT Traversal
+
+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).
+
+### Behind a NAT — minimal config
+
+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
+      }
+    }
+  }
+}
+```
+
+> 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.js

@@ -36,6 +36,7 @@ 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,6 +50,65 @@ function createLibp2pMeshConfigSchema() {
                     type: "boolean",
                     default: true,
                 },
+                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-feishu.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/agent-tools-feishu.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { buildFeishuTools } from "./agent-tools.js";
+describe("buildFeishuTools", () => {
+    it("should return empty array when feishuClient is null", () => {
+        const tools = buildFeishuTools(null);
+        expect(tools).toEqual([]);
+    });
+    it("should return array with one tool when feishuClient is provided", () => {
+        const mockClient = {
+            sendMessage: vi.fn(),
+        };
+        const tools = buildFeishuTools(mockClient);
+        expect(tools).toHaveLength(1);
+        expect(tools[0].name).toBe("feishu_send_message");
+    });
+    describe("feishu_send_message tool", () => {
+        let tools;
+        let mockClient;
+        beforeEach(() => {
+            mockClient = {
+                sendMessage: vi.fn(),
+            };
+            tools = buildFeishuTools(mockClient);
+        });
+        it("should require openId and message parameters", () => {
+            const tool = tools[0];
+            expect(tool.parameters.required).toEqual(["openId", "message"]);
+        });
+        it("should return success result on successful send", async () => {
+            mockClient.sendMessage.mockResolvedValue({
+                success: true,
+                messageId: "msg-789",
+            });
+            const result = await tools[0].execute("call-1", {
+                openId: "ou-test",
+                message: "hello",
+            });
+            expect(result.isError).toBeUndefined();
+            expect(result.details.sent).toBe(true);
+            expect(result.details.openId).toBe("ou-test");
+            expect(mockClient.sendMessage).toHaveBeenCalledWith("ou-test", "hello");
+        });
+        it("should return error result on failed send", async () => {
+            mockClient.sendMessage.mockResolvedValue({
+                success: false,
+                error: "rate limited",
+            });
+            const result = await tools[0].execute("call-1", {
+                openId: "ou-test",
+                message: "hello",
+            });
+            expect(result.isError).toBe(true);
+            expect(result.details.sent).toBe(false);
+            expect(result.details.error).toBe("rate limited");
+        });
+    });
+});

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

@@ -127,4 +127,91 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         };
         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: {
+            initialized: boolean;
+            identity?: undefined;
+            error?: undefined;
+        };
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            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,5 +112,84 @@ export function buildP2PTools(mesh) {
                 }
             },
         },
+        {
+            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: {},
+            },
+            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: `Error: ${String(err)}` }],
+                        details: { error: String(err) },
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            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,
+                        },
+                    };
+                }
+                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/config-schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/config-schema.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { createLibp2pMeshConfigSchema } from "./index.js";
+describe("createLibp2pMeshConfigSchema - Feishu config", () => {
+    const schema = createLibp2pMeshConfigSchema();
+    it("should include feishu in jsonSchema properties", () => {
+        const props = schema.jsonSchema.properties;
+        expect(props).toHaveProperty("feishu");
+    });
+    it("feishu should be an object type with correct properties", () => {
+        const props = schema.jsonSchema.properties;
+        const feishu = props.feishu;
+        expect(feishu.type).toBe("object");
+        expect(feishu.properties).toHaveProperty("appId");
+        expect(feishu.properties).toHaveProperty("appSecret");
+        expect(feishu.properties).toHaveProperty("webhookPort");
+        expect(feishu.properties).toHaveProperty("webhookPath");
+    });
+    it("feishu.webhookPort should default to 9222", () => {
+        const props = schema.jsonSchema.properties;
+        expect(props.feishu.properties.webhookPort.default).toBe(9222);
+    });
+    it("feishu.webhookPath should default to /webhook/feishu", () => {
+        const props = schema.jsonSchema.properties;
+        expect(props.feishu.properties.webhookPath.default).toBe("/webhook/feishu");
+    });
+    it("feishu.appId and appSecret should be string type without default", () => {
+        const props = schema.jsonSchema.properties;
+        expect(props.feishu.properties.appId.type).toBe("string");
+        expect(props.feishu.properties.appSecret.type).toBe("string");
+        expect(props.feishu.properties.appId.default).toBeUndefined();
+        expect(props.feishu.properties.appSecret.default).toBeUndefined();
+    });
+    it("should parse config with feishu fields", () => {
+        const result = schema.safeParse({
+            listenAddrs: ["/ip4/0.0.0.0/tcp/0"],
+            feishu: {
+                appId: "cli-123",
+                appSecret: "secret-456",
+                webhookPort: 9999,
+                webhookPath: "/custom/path",
+            },
+        });
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.data.feishu.appId).toBe("cli-123");
+            expect(result.data.feishu.webhookPort).toBe(9999);
+        }
+    });
+    it("should parse config without feishu (feishu is optional)", () => {
+        const result = schema.safeParse({
+            listenAddrs: ["/ip4/0.0.0.0/tcp/0"],
+        });
+        expect(result.success).toBe(true);
+    });
+});

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[];
+};

package/dist/src/dht-registry.js

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+const DHT_KEY_PREFIX = "openclaw:pubkey:";
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const pubkeyCache = new Map();
+function encodeKey(instanceId) {
+    return new TextEncoder().encode(`${DHT_KEY_PREFIX}${instanceId}`);
+}
+/**
+ * Register this instance's pubkey in the DHT.
+ * Other nodes can later look it up to verify signatures from this instance.
+ */
+export async function registerPubkey(dht, instanceId, pubkey, logger) {
+    const key = encodeKey(instanceId);
+    const value = new TextEncoder().encode(pubkey);
+    try {
+        for await (const event of dht.put(key, value)) {
+            // Drain the async iterable; put completes when the iterable ends
+            logger?.info?.(`[dht-registry] put event: ${event.name}`);
+        }
+        logger?.info?.(`[dht-registry] Registered pubkey for ${instanceId}`);
+    }
+    catch (err) {
+        logger?.warn?.(`[dht-registry] Failed to register pubkey: ${String(err)}`);
+        // Non-fatal: identity verification may degrade but mesh continues
+    }
+}
+/**
+ * Look up a pubkey from the DHT for the given instanceId.
+ * Results are cached locally to avoid repeated DHT queries.
+ */
+export async function lookupPubkey(dht, instanceId, logger) {
+    // 1. Check local cache
+    const cached = pubkeyCache.get(instanceId);
+    if (cached && cached.expiry > Date.now()) {
+        logger?.debug?.(`[dht-registry] Cache hit for ${instanceId}`);
+        return cached.pubkey;
+    }
+    // 2. Query DHT
+    const key = encodeKey(instanceId);
+    try {
+        for await (const event of dht.get(key)) {
+            if (event.name === "VALUE") {
+                const pubkey = new TextDecoder().decode(event.value);
+                pubkeyCache.set(instanceId, {
+                    pubkey,
+                    expiry: Date.now() + CACHE_TTL_MS,
+                });
+                logger?.info?.(`[dht-registry] DHT lookup success for ${instanceId}`);
+                return pubkey;
+            }
+        }
+    }
+    catch (err) {
+        logger?.warn?.(`[dht-registry] DHT lookup failed for ${instanceId}: ${String(err)}`);
+    }
+    logger?.info?.(`[dht-registry] No pubkey found for ${instanceId}`);
+    return undefined;
+}
+/**
+ * Clear the local pubkey cache.
+ */
+export function clearPubkeyCache() {
+    pubkeyCache.clear();
+}
+/**
+ * Get cache stats for observability.
+ */
+export function getCacheStats() {
+    return {
+        size: pubkeyCache.size,
+        keys: Array.from(pubkeyCache.keys()),
+    };
+}