@decentnetwork/peer

@decentnetwork/peer is a pure TypeScript implementation of the Carrier protocol (the toxcore-derived protocol the Beagle apps and the native Carrier SDKs speak). A Peer owns a self-generated keypair, joins the public DHT through bootstrap nodes, becomes friends with other peers, and exchanges end-to-end encrypted text, files and custom packets with them — directly over UDP when a hole can be punched, through a TCP relay when it cannot, and through an HTTPS Express relay when the friend is offline. It is wire-compatible with the iOS and Android Beagle apps and the C SDK. There are no native dependencies; it runs on Node.js 20+.

When to use it

Use @decentnetwork/peer when your program needs its own identity on the Decent Network: a bot, a backend service, a CLI, a desktop daemon, or a test harness that talks to Beagle users or to other peers.

• It is the transport. Every other npm package on this site that talks to the network sits on top of it.
• For audio and video calls, add @decentnetwork/peer-webrtc. It uses this package's friend-invite channel for call signaling.
• For forms inside chat messages, add @decentnetwork/chat-components. It only formats message text; it never touches the transport.
• For a VPN-style virtual LAN between peers, use @decentnetwork/lan instead of building one on custom packets.
• For a ready-made desktop chat client, see @decentnetwork/beagle.
• On Android, iOS or in C, use the native SDKs (Android, Swift, C/C++). They interoperate with this package on the wire.

Install

npm install @decentnetwork/peer

The package is ESM only ("type": "module", no require export). Use import, an .mjs file, or "type": "module" in your package.json. TypeScript declarations ship in the package.

Quickstart

This single file creates two identities, Alice and Bob, in separate directories. Alice sends Bob a friend request, Bob accepts it, and Alice sends Bob a text message over the live network. It exits on its own, or after 3 minutes if the network cannot complete the exchange.

// quickstart.mjs — two peers, one friendship, one message, over the live network.
// Run: node quickstart.mjs
import { Peer, carrierIdFromAddress } from "@decentnetwork/peer";

// Public Carrier bootstrap nodes (the same list the Beagle apps ship with).
const bootstrapNodes = [
  { host: "47.100.103.201", port: 33445, pk: "CX1XH419p4xJ5SV4KvDxBeKYSRdMJW9QpdWJY8owUxHd" },
  { host: "154.64.235.176", port: 33445, pk: "GdNtV2N74fZnLjhH7NhQ18nGdxb1k8jRM9dQaK7WnxmL" },
  { host: "45.207.220.155", port: 33445, pk: "37PXijTXkyX9rUcRFjGo7PYpwf732KXQJgMtcKuMu3ym" },
  { host: "13.58.208.50", port: 33445, pk: "89vny8MrKdDKs7Uta9RdVmspPjnRMdwMmaiEW27pZ7gh" },
];
// Optional HTTPS store-and-forward relay: carries the friend request (and
// messages) when the other side cannot be reached directly yet.
const expressNodes = [
  { host: "lens.beagle.chat", port: 443, pk: "ECbs4GxwGzxGerNkmqDJFibEmevu8jAXqAZtikccvD95" },
];

// Never hang: give up after 3 minutes.
const watchdog = setTimeout(() => { console.error("timed out"); process.exit(1); }, 180_000);

// Each identity is a key file, created on first run; keep it to keep the identity.
// Give every peer its own directory (created if missing): start() also writes
// announce-data-key.json and <keyFile>.friends.json next to the key file.
const alice = await Peer.create({ keyFile: "./alice/peer.save", bootstrapNodes, expressNodes, nickname: "alice" });
const bob = await Peer.create({ keyFile: "./bob/peer.save", bootstrapNodes, expressNodes, nickname: "bob" });

// Bob accepts every friend request and resolves when a text arrives.
bob.onFriendRequest((req) => {
  console.log(`bob   <- friend request from ${req.userid}: "${req.hello}"`);
  void bob.acceptFriendRequest(req.pubkey);
});
const received = new Promise((resolve) => bob.onText((msg) => resolve(msg)));

await alice.start();
await bob.start();
await Promise.all([alice.joinNetwork(), bob.joinNetwork()]);

console.log(`alice address ${alice.address()}`);
console.log(`alice userid  ${alice.userid()}`);
console.log(`bob   address ${bob.address()}`);
console.log(`bob   userid  ${bob.userid()}`);

// Alice adds Bob by his address, then waits for the encrypted session.
await alice.sendFriendRequest(bob.address(), "hi bob, it's alice");
const bobId = carrierIdFromAddress(bob.address()); // === bob.userid()
const online = await alice.waitForFriendConnected(bobId, 120_000);
console.log(`alice -> session with bob: ${online ? "connected" : "not connected (yet)"}`);

const result = await alice.sendText(bobId, "hello from alice");
console.log(`alice -> sendText delivery: ${result.delivery}`);

const msg = await received;
console.log(`bob   <- "${msg.text}" from ${msg.pubkey} via ${msg.via}`);

await alice.stop();
await bob.stop();
clearTimeout(watchdog);
process.exit(0);

npm install @decentnetwork/peer@0.1.172
node quickstart.mjs

Verified output (npm @decentnetwork/peer@0.1.172, 2026-11-06):

alice address dp4jcRUUoAjKHkfkCUr7TpbvAhtyemXe42kCQhVNVXEeU6Mr3Ff2
alice userid  HkPpHmCJ7R31A2BHyaNWexHJvMdJP5w8UzySdQKEUrid
bob   address S8ZYCF6aBufgA6nDuGJUFjM1imrNb32ZPmstSbDLZSkXwqUZT9yQ
bob   userid  CS9d5xdUuSz4XGKnL9cJWdHkQar862hkTvPpXG8pTmDG
bob   <- friend request from HkPpHmCJ7R31A2BHyaNWexHJvMdJP5w8UzySdQKEUrid: "hi bob, it's alice"
alice -> session with bob: connected
alice -> sendText delivery: offline
bob   <- "hello from alice" from HkPpHmCJ7R31A2BHyaNWexHJvMdJP5w8UzySdQKEUrid via offline

The whole exchange took about 45 seconds on a home network (macOS, Node.js 24.3.0). Repeated runs end the same way, but the delivery path varies: in some runs sendText returned acked and Bob saw via online. Right after a session comes up, sendText may still choose the Express relay because no keepalive has arrived from the friend yet. See Messages and delivery results.

What the output shows:

• An address (alice address …) is what you share so others can add you. It is the public key plus a 4-byte nospam and a checksum, in base58.
• A userid (alice userid …) is the public key alone. Every per-friend method (sendText, waitForFriendConnected, removeFriend, …) takes the userid. carrierIdFromAddress(address) converts one to the other.

API reference

Everything below is exported from the package root (import { … } from "@decentnetwork/peer"), as declared in dist/index.d.ts of 0.1.172.

Class Peer

Lifecycle

Identity and profile

Friends

Messages and delivery results

TextDeliveryResult.delivery means:

• "acked": the far side confirmed it. You can mark the message sent.
• "accepted": it went into a live session but was not confirmed in time. Do not resend on this alone, or the recipient may see a duplicate.
• "offline": it was stored on an Express relay. The friend collects it the next time it polls.

Files

Calls, invites and custom packets

Events

Register these before start(). Each takes one callback.

Methods whose names start with _test or __test are test hooks, not public API.

Functions and constants

Exported types: PeerOptions, NetworkNode, CompatibilityMode, FriendRequest, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, TextMessage, TextDeliveryResult, SendTextUntilAckOptions, InlineFileEvent, InlineSendResult, InviteEvent, InviteResponseEvent, CustomPacketEvent, LookupResult, CarrierAddressParts, CarrierTurnCreds, CarrierTurnServerInfo, RtcIceServer, BuildIceServersOptions, CarrierPacket, FriendMessagePacket, FriendRequestPacket, InviteReqPacket, InviteRspPacket, ToxDhtCryptoRequest.

Configuration

PeerOptions

Environment variables

The 0.1.172 build reads these at startup:

To save CPU when many friends are offline, raise the interval or the backoff cap. Do not lower DECENT_FRIEND_ROUTE_MAX_ATTEMPTS: phones are only online in short windows, and a narrower sweep misses them.

CLI: decent-peer

The package ships a small CLI for diagnostics. Run it with npx; there is no need for a global install.

npx decent-peer init                       # write ~/.decent-peer/config.json
npx decent-peer address                    # print this peer's address
npx decent-peer userid                     # print this peer's userid
npx decent-peer listen                     # join and print incoming text until Ctrl-C
npx decent-peer add-friend <address> [hello]
npx decent-peer accept <userid>
npx decent-peer send <userid> <text>
npx decent-peer list-friends               # JSON

The config file is ~/.decent-peer/config.json; set DECENT_PEER_CONFIG to use another path. It accepts keyFile, bootstrapNodes and compatibilityMode. The CLI's default bootstrap list has one node, and the CLI never configures an Express relay. init, address, userid and list-friends were verified with 0.1.172.

Platforms

• Node.js 20 or newer (engines.node >= 20.0.0). Verified on Node.js 24.3.0, macOS (Apple Silicon).
• Pure JavaScript. The dependencies are tweetnacl, curve25519-js and flatbuffers; nothing is compiled.
• Network: outbound UDP and TCP to the bootstrap nodes (port 33445; some use 443), and outbound HTTPS to the Express relay if you configure one. No inbound port is needed.
• One Peer per identity. Several peers can share a process if each has its own keyFile directory, as in the quickstart.
• Browsers: the API has hooks for hosts without UDP or a filesystem (tcpOnlyBootstrap, keyPair, debug), but the package root imports Node built-ins and is not published as a browser bundle. The browser build was not verified for this page.

Version, source and changelog

• Verified version: 0.1.172 (npm latest on 2026-11-06).
• npm: https://www.npmjs.com/package/@decentnetwork/peer
• Source: the source repository is not public yet. The published code (compiled JavaScript plus .d.ts) is in the npm package: https://www.npmjs.com/package/@decentnetwork/peer?activeTab=code
• Changelog: none is published for this package.
• License: GPL-3.0-or-later.
• Protocol reference: the native Carrier SDK this package is wire-compatible with is public at https://github.com/decentnetworks/Elastos.NET.Carrier.Native.SDK