# `@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.