@decentnetwork/peer 0.1.0

package/LICENSE

@@ -0,0 +1,31 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+This package is licensed under the GNU General Public License v3.0 or any
+later version. You may redistribute and/or modify it under the terms of
+the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+Public License for more details.
+
+The full text of the GPL-3.0-or-later license is available at
+<https://www.gnu.org/licenses/gpl-3.0.html>.
+
+This package derives in part from the Elastos.NET.Carrier.Native.SDK,
+which itself derives from the toxcore project — both also licensed under
+GPL-3.0-or-later. The protocol-level parity with those upstreams is
+intentional; the wire format implementations in `compat/` reference the
+toxcore C source by file:line in their top comments.
+
+  - Elastos.NET.Carrier.Native.SDK:
+    https://github.com/elastos/Elastos.NET.Carrier.Native.SDK
+  - c-toxcore:
+    https://github.com/TokTok/c-toxcore

package/README.md

@@ -0,0 +1,97 @@
+# `@decentnetwork/peer`
+
+Pure TypeScript / Node.js port of the [Elastos Carrier Native SDK][carrier-c]
+(Carrier-flavored toxcore). Wire-compatible with the C SDK and iOS Beagle —
+the same DHT, onion routing, FlatBuffers app payloads, TCP relay protocol,
+and Express HTTP store-and-forward relay. End-to-end interop with iOS Beagle
+on iPad is verified working.
+
+[carrier-c]: https://github.com/elastos/Elastos.NET.Carrier.Native.SDK
+
+```bash
+pnpm add @decentnetwork/peer
+# or
+npm install @decentnetwork/peer
+```
+
+## 30-second example
+
+```ts
+import { Peer } from "@decentnetwork/peer";
+
+const peer = await Peer.create({
+  keyFile: "./peer.save",
+  bootstrapNodes: [
+    {
+      host: "47.100.103.201",
+      port: 33445,
+      pk: "CX1XH419p4xJ5SV4KvDxBeKYSRdMJW9QpdWJY8owUxHd"
+    }
+    // (more bootstraps recommended — see docs/USAGE_GUIDE.md)
+  ],
+  compatibilityMode: "legacy"
+});
+
+await peer.start();
+await peer.joinNetwork();
+
+console.log("my address:", peer.address());
+
+peer.onText((msg) => {
+  console.log(`from ${msg.pubkey}: ${msg.text}`);
+});
+
+// Send a friend request to a peer (their address comes from their UI):
+await peer.sendFriendRequest(
+  "ZJxuWL9SDqdvunnCSMLUd5jyGCaBV44G6THYaQS7ZaZAz1wmt4nz",
+  "hello!"
+);
+
+// Once they accept and the session establishes, send a message:
+await peer.sendText(
+  "FhbohSLrj5UjdyFKCEYNeEWAPq3QD9hRg6hsso5ipag2",
+  "first message via @decentnetwork/peer"
+);
+
+await peer.stop();
+```
+
+## Optional CLI
+
+For users who just want to run a peer without writing JS, the package
+also ships an optional `decent-peer` binary (the library export is
+unchanged — the CLI is additive):
+
+```bash
+npm install -g @decentnetwork/peer
+decent-peer init                              # creates ~/.decent-peer/
+decent-peer address                           # print your address
+decent-peer listen                            # daemon mode (Ctrl-C to stop)
+decent-peer send <addr> "hello"               # one-shot send
+decent-peer add-friend <addr> "hi from me"    # one-shot friend request
+decent-peer accept <pubkey>                   # accept a pending request
+
+# zero-install:
+npx @decentnetwork/peer listen
+```
+
+Config lives at `~/.decent-peer/config.json` (override with the
+`DECENT_PEER_CONFIG` env var). The keyfile at `~/.decent-peer/peer.save`
+is your identity — back it up.
+
+## Documentation
+
+- **Usage guide**: full developer-facing tutorial with sample apps —
+  see [`docs/USAGE_GUIDE.md`](https://github.com/0xli/peer/blob/main/docs/USAGE_GUIDE.md)
+- **Protocol overview**: actors, identities, lifecycle —
+  [`docs/PROTOCOL_OVERVIEW.md`](https://github.com/0xli/peer/blob/main/docs/PROTOCOL_OVERVIEW.md)
+- **Carrier vs Tox/Onion**: where Carrier diverges from upstream toxcore —
+  [`docs/CARRIER_VS_TOX.md`](https://github.com/0xli/peer/blob/main/docs/CARRIER_VS_TOX.md)
+- **Discovery flow**: the four discovery stages with timing budgets —
+  [`docs/DISCOVERY_FLOW.md`](https://github.com/0xli/peer/blob/main/docs/DISCOVERY_FLOW.md)
+- **iOS interop playbook**: real-world bug catalog and debug markers —
+  [`docs/IOS_INTEROP_PLAYBOOK.md`](https://github.com/0xli/peer/blob/main/docs/IOS_INTEROP_PLAYBOOK.md)
+
+## License
+
+GPL-3.0-or-later. Same as upstream toxcore.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// Optional command-line interface for @decentnetwork/peer.
+//
+// Library users do NOT need this — `import { Peer } from "@decentnetwork/peer"`
+// stays the canonical way to embed a peer in a Node.js app. This CLI is for
+// people who want to run a peer (one-shot or as a daemon) without writing JS.
+//
+// Install:   npm install -g @decentnetwork/peer
+// One-shot:  npx @decentnetwork/peer <command>
+// Subcommands:
+//   init                       create ~/.decent-peer/ with a default config
+//   address                    print this peer's address and exit
+//   userid                     print this peer's userid (short address form)
+//   listen                     run as daemon — print incoming text until Ctrl-C
+//   send <addr> <text>         send one text message and exit
+//   add-friend <addr> [hello]  send a friend request and exit
+//   accept <pubkey>            accept a pending friend request and exit
+//   list-friends               print known friends as JSON and exit
+//   help                       print this help
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { Peer } from "./peer.js";
+const DEFAULT_CONFIG_DIR = join(homedir(), ".decent-peer");
+const DEFAULT_CONFIG_PATH = join(DEFAULT_CONFIG_DIR, "config.json");
+// Conservative default set — same list as packages/peer/README.md.
+// Users should drop more bootstraps into ~/.decent-peer/config.json for
+// robustness.
+const DEFAULT_BOOTSTRAPS = [
+    {
+        host: "47.100.103.201",
+        port: 33445,
+        pk: "CX1XH419p4xJ5SV4KvDxBeKYSRdMJW9QpdWJY8owUxHd"
+    }
+];
+function expandHome(p) {
+    if (p.startsWith("~/") || p === "~") {
+        return join(homedir(), p.slice(2));
+    }
+    return p;
+}
+function configPath() {
+    return process.env.DECENT_PEER_CONFIG
+        ? resolve(expandHome(process.env.DECENT_PEER_CONFIG))
+        : DEFAULT_CONFIG_PATH;
+}
+function loadConfig() {
+    const path = configPath();
+    if (!existsSync(path)) {
+        // Fall back to in-memory defaults so `address`, `listen`, etc. just work
+        // even if the user never ran `init`. The keyfile is auto-created on first
+        // start by Peer.create() when it doesn't exist.
+        return {
+            keyFile: join(DEFAULT_CONFIG_DIR, "peer.save"),
+            compatibilityMode: "legacy",
+            bootstrapNodes: DEFAULT_BOOTSTRAPS
+        };
+    }
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    return {
+        keyFile: expandHome(raw.keyFile ?? join(DEFAULT_CONFIG_DIR, "peer.save")),
+        compatibilityMode: raw.compatibilityMode ?? "legacy",
+        bootstrapNodes: raw.bootstrapNodes ?? DEFAULT_BOOTSTRAPS
+    };
+}
+function ensureDirFor(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+async function withPeer(cfg, fn, opts = {}) {
+    ensureDirFor(cfg.keyFile);
+    const peer = await Peer.create({
+        keyFile: cfg.keyFile,
+        bootstrapNodes: cfg.bootstrapNodes,
+        compatibilityMode: cfg.compatibilityMode
+    });
+    await peer.start();
+    if (opts.join !== false) {
+        await peer.joinNetwork();
+    }
+    try {
+        return await fn(peer);
+    }
+    finally {
+        await peer.stop().catch(() => { });
+    }
+}
+// ──────────────────────────── subcommands ────────────────────────────
+async function cmdInit() {
+    const path = configPath();
+    if (existsSync(path)) {
+        console.log(`config already exists at ${path}`);
+        return;
+    }
+    ensureDirFor(path);
+    const cfg = {
+        keyFile: join(DEFAULT_CONFIG_DIR, "peer.save"),
+        compatibilityMode: "legacy",
+        bootstrapNodes: DEFAULT_BOOTSTRAPS
+    };
+    writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n");
+    console.log(`wrote ${path}`);
+    console.log(`keyfile will be created at ${cfg.keyFile} on first run.`);
+}
+async function cmdAddress(cfg) {
+    await withPeer(cfg, async (peer) => {
+        console.log(peer.address());
+    }, { join: false });
+}
+async function cmdUserid(cfg) {
+    await withPeer(cfg, async (peer) => {
+        console.log(peer.userid());
+    }, { join: false });
+}
+async function cmdListen(cfg) {
+    // Long-running. Resolves only on SIGINT.
+    const peer = await Peer.create({
+        keyFile: cfg.keyFile,
+        bootstrapNodes: cfg.bootstrapNodes,
+        compatibilityMode: cfg.compatibilityMode
+    });
+    await peer.start();
+    console.log(`my address: ${peer.address()}`);
+    console.log(`joining network…`);
+    await peer.joinNetwork();
+    console.log(`joined. listening for messages (Ctrl-C to quit).`);
+    peer.onFriendConnection((event) => {
+        console.log(`[${new Date().toISOString()}] friend ${event.pubkey} ${event.status}`);
+    });
+    peer.onText((message) => {
+        console.log(`[${new Date().toISOString()}] ${message.pubkey}: ${message.text}`);
+    });
+    await new Promise((res) => {
+        const shutdown = async () => {
+            console.log("\nshutting down…");
+            await peer.stop().catch(() => { });
+            res();
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+}
+async function cmdSend(cfg, addr, text) {
+    await withPeer(cfg, async (peer) => {
+        await peer.sendText(addr, text);
+        console.log(`sent ${text.length} chars to ${addr}`);
+    });
+}
+async function cmdAddFriend(cfg, addr, hello) {
+    await withPeer(cfg, async (peer) => {
+        await peer.sendFriendRequest(addr, hello);
+        console.log(`friend request sent to ${addr}`);
+    });
+}
+async function cmdAccept(cfg, pubkey) {
+    await withPeer(cfg, async (peer) => {
+        await peer.acceptFriendRequest(pubkey);
+        console.log(`accepted ${pubkey}`);
+    });
+}
+async function cmdListFriends(cfg) {
+    await withPeer(cfg, async (peer) => {
+        console.log(JSON.stringify(peer.friends(), null, 2));
+    }, { join: false });
+}
+function printHelp() {
+    process.stdout.write(`decent-peer — CLI for @decentnetwork/peer\n\n` +
+        `usage: decent-peer <command> [args]\n\n` +
+        `commands:\n` +
+        `  init                       create ~/.decent-peer/config.json\n` +
+        `  address                    print this peer's address\n` +
+        `  userid                     print this peer's userid (short address)\n` +
+        `  listen                     run as daemon, print incoming text\n` +
+        `  send <addr> <text>         send one message and exit\n` +
+        `  add-friend <addr> [hello]  send a friend request and exit\n` +
+        `  accept <pubkey>            accept a pending friend request\n` +
+        `  list-friends               print known friends as JSON\n` +
+        `  help                       this help\n\n` +
+        `config: ~/.decent-peer/config.json (override with DECENT_PEER_CONFIG)\n` +
+        `keyfile: defaults to ~/.decent-peer/peer.save — KEEP THIS, it's your identity.\n\n` +
+        `for SDK usage instead, see docs/USAGE_GUIDE.md and import { Peer } from\n` +
+        `"@decentnetwork/peer".\n`);
+}
+// ──────────────────────────── entry ────────────────────────────
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+        printHelp();
+        return;
+    }
+    if (cmd === "init") {
+        await cmdInit();
+        return;
+    }
+    const cfg = loadConfig();
+    switch (cmd) {
+        case "address":
+            await cmdAddress(cfg);
+            return;
+        case "userid":
+            await cmdUserid(cfg);
+            return;
+        case "listen":
+            await cmdListen(cfg);
+            return;
+        case "send": {
+            const [addr, ...textParts] = rest;
+            if (!addr || textParts.length === 0) {
+                console.error("usage: decent-peer send <addr> <text>");
+                process.exit(2);
+            }
+            await cmdSend(cfg, addr, textParts.join(" "));
+            return;
+        }
+        case "add-friend": {
+            const [addr, ...helloParts] = rest;
+            if (!addr) {
+                console.error("usage: decent-peer add-friend <addr> [hello]");
+                process.exit(2);
+            }
+            const hello = helloParts.join(" ") || "hello";
+            await cmdAddFriend(cfg, addr, hello);
+            return;
+        }
+        case "accept": {
+            const [pubkey] = rest;
+            if (!pubkey) {
+                console.error("usage: decent-peer accept <pubkey>");
+                process.exit(2);
+            }
+            await cmdAccept(cfg, pubkey);
+            return;
+        }
+        case "list-friends":
+            await cmdListFriends(cfg);
+            return;
+        default:
+            console.error(`unknown command: ${cmd}`);
+            printHelp();
+            process.exit(2);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.stack ?? err.message : err);
+    process.exit(1);
+});

package/dist/compat/address.d.ts

@@ -0,0 +1,13 @@
+export declare const CARRIER_PUBLIC_KEY_SIZE = 32;
+export declare const CARRIER_NOSPAM_SIZE = 4;
+export declare const CARRIER_ADDRESS_CHECKSUM_SIZE = 2;
+export declare const CARRIER_ADDRESS_SIZE: number;
+export type CarrierAddressParts = {
+    publicKey: Uint8Array;
+    nospam: number;
+    checksum: number;
+};
+export declare function carrierAddressFromPublicKey(publicKey: Uint8Array, nospam?: number): string;
+export declare function parseCarrierAddress(address: string): CarrierAddressParts;
+export declare function carrierIdFromAddress(address: string): string;
+export declare function carrierIdFromPublicKey(publicKey: Uint8Array): string;

package/dist/compat/address.js

@@ -0,0 +1,69 @@
+import { base58ToBytes, bytesToBase58 } from "../utils/base58.js";
+export const CARRIER_PUBLIC_KEY_SIZE = 32;
+export const CARRIER_NOSPAM_SIZE = 4;
+export const CARRIER_ADDRESS_CHECKSUM_SIZE = 2;
+export const CARRIER_ADDRESS_SIZE = CARRIER_PUBLIC_KEY_SIZE + CARRIER_NOSPAM_SIZE + CARRIER_ADDRESS_CHECKSUM_SIZE;
+export function carrierAddressFromPublicKey(publicKey, nospam = 0) {
+    if (publicKey.length !== CARRIER_PUBLIC_KEY_SIZE) {
+        throw new Error(`Carrier public key must be ${CARRIER_PUBLIC_KEY_SIZE} bytes`);
+    }
+    const address = new Uint8Array(CARRIER_ADDRESS_SIZE);
+    address.set(publicKey, 0);
+    writeUint32LE(address, CARRIER_PUBLIC_KEY_SIZE, nospam);
+    writeUint16LE(address, CARRIER_PUBLIC_KEY_SIZE + CARRIER_NOSPAM_SIZE, addressChecksum(address.subarray(0, -2)));
+    return bytesToBase58(address);
+}
+export function parseCarrierAddress(address) {
+    const bytes = base58ToBytes(address);
+    if (bytes.length !== CARRIER_ADDRESS_SIZE) {
+        throw new Error(`Carrier address must decode to ${CARRIER_ADDRESS_SIZE} bytes`);
+    }
+    const actual = readUint16LE(bytes, CARRIER_PUBLIC_KEY_SIZE + CARRIER_NOSPAM_SIZE);
+    const expected = addressChecksum(bytes.subarray(0, -2));
+    if (actual !== expected) {
+        throw new Error("Carrier address checksum mismatch");
+    }
+    return {
+        publicKey: bytes.slice(0, CARRIER_PUBLIC_KEY_SIZE),
+        nospam: readUint32LE(bytes, CARRIER_PUBLIC_KEY_SIZE),
+        checksum: actual
+    };
+}
+export function carrierIdFromAddress(address) {
+    return bytesToBase58(parseCarrierAddress(address).publicKey);
+}
+export function carrierIdFromPublicKey(publicKey) {
+    if (publicKey.length !== CARRIER_PUBLIC_KEY_SIZE) {
+        throw new Error(`Carrier public key must be ${CARRIER_PUBLIC_KEY_SIZE} bytes`);
+    }
+    return bytesToBase58(publicKey);
+}
+function addressChecksum(bytes) {
+    const checksum = [0, 0];
+    for (let i = 0; i < bytes.length; i++) {
+        checksum[i % 2] ^= bytes[i];
+    }
+    return checksum[0] | (checksum[1] << 8);
+}
+function writeUint16LE(bytes, offset, value) {
+    bytes[offset] = value & 0xff;
+    bytes[offset + 1] = (value >>> 8) & 0xff;
+}
+function readUint16LE(bytes, offset) {
+    return bytes[offset] | (bytes[offset + 1] << 8);
+}
+function writeUint32LE(bytes, offset, value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+        throw new Error("Carrier nospam must be a uint32");
+    }
+    bytes[offset] = value & 0xff;
+    bytes[offset + 1] = (value >>> 8) & 0xff;
+    bytes[offset + 2] = (value >>> 16) & 0xff;
+    bytes[offset + 3] = (value >>> 24) & 0xff;
+}
+function readUint32LE(bytes, offset) {
+    return (bytes[offset] |
+        (bytes[offset + 1] << 8) |
+        (bytes[offset + 2] << 16) |
+        (bytes[offset + 3] << 24)) >>> 0;
+}

package/dist/compat/bootstrap.d.ts

@@ -0,0 +1,29 @@
+import type { NetworkNode } from "../types/peer.js";
+import type { KeyPair } from "../crypto/keypair.js";
+import { UdpTransport } from "../transport/udp.js";
+type DhtNode = {
+    host: string;
+    port: number;
+    publicKey: Uint8Array;
+    transport: "udp4" | "udp6" | "tcp4" | "tcp6";
+};
+export type BootstrapClientOptions = {
+    nodes: NetworkNode[];
+    keyPair: KeyPair;
+    transport: UdpTransport;
+};
+export type BootstrapAttempt = {
+    node: NetworkNode;
+    status: "queued" | "sent" | "responded";
+};
+export type BootstrapResult = {
+    respondingNode: NetworkNode;
+    discoveredNodes: DhtNode[];
+};
+export declare class LegacyBootstrapClient {
+    #private;
+    constructor(opts: BootstrapClientOptions);
+    attempts(): BootstrapAttempt[];
+    join(timeoutMs?: number): Promise<BootstrapResult>;
+}
+export {};

package/dist/compat/bootstrap.js

@@ -0,0 +1,178 @@
+import { base58ToBytes } from "../utils/base58.js";
+import { concatBytes, randomBytes } from "../utils/bytes.js";
+import nacl from "tweetnacl";
+const NET_PACKET_GET_NODES = 0x02;
+const NET_PACKET_SEND_NODES_IPV6 = 0x04;
+const CARRIER_MAGIC = Uint8Array.of(0x69, 0x76, 0x65, 0x67);
+const PUBLIC_KEY_SIZE = 32;
+const NONCE_SIZE = 24;
+const MAC_SIZE = 16;
+const SENDBACK_SIZE = 8;
+const MAX_SENT_NODES = 4;
+export class LegacyBootstrapClient {
+    #nodes;
+    #keyPair;
+    #transport;
+    constructor(opts) {
+        this.#nodes = opts.nodes;
+        this.#keyPair = opts.keyPair;
+        this.#transport = opts.transport;
+    }
+    attempts() {
+        return this.#nodes.map((node) => ({ node, status: "queued" }));
+    }
+    async join(timeoutMs = 30000) {
+        if (!this.#transport.bound) {
+            throw new Error("UDP transport must be started before bootstrap join");
+        }
+        return new Promise((resolve, reject) => {
+            const sendbacks = new Map();
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error(`legacy bootstrap timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const cleanup = () => {
+                clearTimeout(timer);
+                this.#transport.off("datagram", onDatagram);
+            };
+            const onDatagram = (datagram) => {
+                const parsed = this.#parseSendNodes(datagram.data, sendbacks);
+                if (!parsed) {
+                    return;
+                }
+                cleanup();
+                resolve(parsed);
+            };
+            this.#transport.on("datagram", onDatagram);
+            void this.#sendGetNodes(sendbacks).catch((error) => {
+                cleanup();
+                reject(error);
+            });
+        });
+    }
+    async #sendGetNodes(sendbacks) {
+        // Stagger getnodes probes so the bootstrap list priority actually matters:
+        // the first listed node gets a head start, and if it responds within the
+        // stagger window the join() promise resolves before later probes are even
+        // sent. The first stagger is intentionally larger (covers transpacific
+        // RTT to Alibaba/China bootstraps); subsequent stagger is short so a
+        // dead first node falls through quickly. Total worst-case fan-out for a
+        // 14-node list: 800 + 13*150 = ~2.7s, still well under the 30s join
+        // timeout. Operators can tune via DECENT_BOOTSTRAP_STAGGER_FIRST_MS and
+        // DECENT_BOOTSTRAP_STAGGER_MS.
+        const FIRST_STAGGER_MS = Number.parseInt(process.env.DECENT_BOOTSTRAP_STAGGER_FIRST_MS ?? "800", 10);
+        const STAGGER_MS = Number.parseInt(process.env.DECENT_BOOTSTRAP_STAGGER_MS ?? "150", 10);
+        for (let i = 0; i < this.#nodes.length; i++) {
+            const node = this.#nodes[i];
+            if (!node.pk) {
+                throw new Error(`bootstrap node ${node.host}:${node.port} is missing pk`);
+            }
+            const publicKey = base58ToBytes(node.pk);
+            if (publicKey.length !== PUBLIC_KEY_SIZE) {
+                throw new Error(`bootstrap node ${node.host}:${node.port} public key decoded to ${publicKey.length} bytes`);
+            }
+            const sendback = randomBytes(SENDBACK_SIZE);
+            sendbacks.set(Buffer.from(sendback).toString("hex"), node);
+            const packet = this.#createCarrierPacket(this.#createGetNodesPacket(publicKey, this.#keyPair.publicKey, sendback));
+            await this.#transport.send(Buffer.from(packet), node.host, node.port);
+            if (i + 1 < this.#nodes.length) {
+                const delay = i === 0 ? FIRST_STAGGER_MS : STAGGER_MS;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+    }
+    #createCarrierPacket(dhtPacket) {
+        return concatBytes([CARRIER_MAGIC, dhtPacket]);
+    }
+    #createGetNodesPacket(nodePublicKey, requestedNodeId, sendback) {
+        const nonce = randomBytes(NONCE_SIZE);
+        const plain = concatBytes([requestedNodeId, sendback]);
+        const sharedKey = nacl.box.before(nodePublicKey, this.#keyPair.secretKey);
+        const encrypted = nacl.box.after(plain, nonce, sharedKey);
+        return concatBytes([
+            Uint8Array.of(NET_PACKET_GET_NODES),
+            this.#keyPair.publicKey,
+            nonce,
+            encrypted
+        ]);
+    }
+    #parseSendNodes(data, sendbacks) {
+        data = this.#stripCarrierMagic(data);
+        const minimumLength = 1 + PUBLIC_KEY_SIZE + NONCE_SIZE + 1 + SENDBACK_SIZE + MAC_SIZE;
+        if (data.length < minimumLength || data[0] !== NET_PACKET_SEND_NODES_IPV6) {
+            return undefined;
+        }
+        const remotePublicKey = data.slice(1, 1 + PUBLIC_KEY_SIZE);
+        const nonce = data.slice(1 + PUBLIC_KEY_SIZE, 1 + PUBLIC_KEY_SIZE + NONCE_SIZE);
+        const encrypted = data.slice(1 + PUBLIC_KEY_SIZE + NONCE_SIZE);
+        const sharedKey = nacl.box.before(remotePublicKey, this.#keyPair.secretKey);
+        const plain = nacl.box.open.after(encrypted, nonce, sharedKey);
+        if (!plain || plain.length < 1 + SENDBACK_SIZE) {
+            return undefined;
+        }
+        const numNodes = plain[0];
+        if (numNodes > MAX_SENT_NODES) {
+            return undefined;
+        }
+        const sendback = plain.slice(plain.length - SENDBACK_SIZE);
+        const respondingNode = sendbacks.get(Buffer.from(sendback).toString("hex"));
+        if (!respondingNode) {
+            return undefined;
+        }
+        const nodeData = plain.slice(1, plain.length - SENDBACK_SIZE);
+        const discoveredNodes = this.#parseNodes(nodeData, numNodes);
+        if (discoveredNodes.length !== numNodes) {
+            return undefined;
+        }
+        return { respondingNode, discoveredNodes };
+    }
+    #stripCarrierMagic(data) {
+        if (data.length >= CARRIER_MAGIC.length + 1 &&
+            data[0] === CARRIER_MAGIC[0] &&
+            data[1] === CARRIER_MAGIC[1] &&
+            data[2] === CARRIER_MAGIC[2] &&
+            data[3] === CARRIER_MAGIC[3]) {
+            return data.slice(CARRIER_MAGIC.length);
+        }
+        return data;
+    }
+    #parseNodes(data, count) {
+        const nodes = [];
+        let offset = 0;
+        for (let i = 0; i < count; i++) {
+            const family = data[offset];
+            offset += 1;
+            let host;
+            let transport;
+            if (family === 2 || family === 130) {
+                if (offset + 4 + 2 + PUBLIC_KEY_SIZE > data.length) {
+                    return nodes;
+                }
+                host = [...data.slice(offset, offset + 4)].join(".");
+                offset += 4;
+                transport = family === 2 ? "udp4" : "tcp4";
+            }
+            else if (family === 10 || family === 138) {
+                if (offset + 16 + 2 + PUBLIC_KEY_SIZE > data.length) {
+                    return nodes;
+                }
+                const parts = [];
+                for (let part = 0; part < 8; part++) {
+                    parts.push(((data[offset + part * 2] << 8) | data[offset + part * 2 + 1]).toString(16));
+                }
+                host = parts.join(":");
+                offset += 16;
+                transport = family === 10 ? "udp6" : "tcp6";
+            }
+            else {
+                return nodes;
+            }
+            const port = (data[offset] << 8) | data[offset + 1];
+            offset += 2;
+            const publicKey = data.slice(offset, offset + PUBLIC_KEY_SIZE);
+            offset += PUBLIC_KEY_SIZE;
+            nodes.push({ host, port, publicKey, transport });
+        }
+        return nodes;
+    }
+}

package/dist/compat/dht.d.ts

@@ -0,0 +1,3 @@
+export declare class LegacyDhtClient {
+    lookup(pubkey: string): Promise<never>;
+}

package/dist/compat/dht.js

@@ -0,0 +1,9 @@
+import { LegacyProtocolNotImplementedError } from "../runtime/errors.js";
+export class LegacyDhtClient {
+    async lookup(pubkey) {
+        if (!pubkey) {
+            throw new Error("pubkey is required");
+        }
+        throw new LegacyProtocolNotImplementedError("Legacy DHT lookup");
+    }
+}