@decentnetwork/peer

Pure TypeScript / Node.js port of the Elastos Carrier Native SDK (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.

pnpm add @decentnetwork/peer
# or
npm install @decentnetwork/peer

30-second example

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):

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
• Protocol overview: actors, identities, lifecycle — docs/PROTOCOL_OVERVIEW.md
• Carrier vs Tox/Onion: where Carrier diverges from upstream toxcore — docs/CARRIER_VS_TOX.md
• Discovery flow: the four discovery stages with timing budgets — docs/DISCOVERY_FLOW.md
• iOS interop playbook: real-world bug catalog and debug markers — docs/IOS_INTEROP_PLAYBOOK.md

License

GPL-3.0-or-later. Same as upstream toxcore.