# Installing `@decentnetwork/peer`

A pure TypeScript / Node.js implementation of the Elastos Carrier
(toxcore-derived) peer-to-peer protocol. Use it as a library in
your own Node app, or run the bundled `decent-peer` CLI for ad-hoc
identity / friend / messaging operations.

## Requirements

- **Node.js 20 or newer** (uses modern WebStreams + AbortController).
- Any OS Node runs on. No native compilation; all crypto is pure JS.
- Outbound network — TCP and/or UDP to public Carrier bootstrap
  nodes (port 33445 + 443). No inbound port needed.

## Install (as a library)

```bash
npm install @decentnetwork/peer
# or
pnpm add @decentnetwork/peer
# or
yarn add @decentnetwork/peer
```

Then in your code:

```ts
import { Peer } from "@decentnetwork/peer";

const peer = await Peer.create({
  keyFile: "./my-peer.save",
  compatibilityMode: "legacy",
  bootstrapNodes: [
    { host: "47.100.103.201", port: 33445,
      pk: "CX1XH419p4xJ5SV4KvDxBeKYSRdMJW9QpdWJY8owUxHd" },
    // ... more, see USAGE_GUIDE.md
  ],
});
await peer.start();
await peer.joinNetwork();
console.log("my address:", peer.address());
```

See [`USAGE_GUIDE.md`](USAGE_GUIDE.md) for the full programmatic
API with copy-paste-ready examples for every common task
(friending, text messages, binary packets, offline relay).

## Install (CLI, globally)

```bash
npm install -g @decentnetwork/peer
```

That puts `decent-peer` on your `$PATH`:

```bash
decent-peer --help
decent-peer identity   # print address + userid
decent-peer join       # sit in the network until killed (useful for testing)
```

The CLI is mostly for diagnostics; production usage almost always
embeds the library directly.

## Configuration

The library is configured per-call (no global config file).
Persistent state lives in the **key file** you pass to
`Peer.create`. That file holds:

- The keypair (Ed25519 + X25519-derived)
- A separate "friends" file alongside it (`<keyFile>.friends.json`)
  with the friend store

Treat both like SSH private keys — back them up; deleting them
gives this peer a brand-new identity.

Knobs:

| option / env | what |
|---|---|
| `Peer.create({ keyFile })` | path to the identity file (created if missing) |
| `Peer.create({ bootstrapNodes })` | DHT entry points |
| `Peer.create({ expressNodes })` | optional HTTPS offline-message relays |
| `Peer.create({ compatibilityMode: "legacy" })` | required for interop with iOS Beagle and the Carrier C SDK |
| `DECENT_DEBUG=1` env var | verbose protocol logs |
| `DECENT_EXPRESS_PULL_INTERVAL_MS` | offline-relay poll cadence (default 4000) |
| `DECENT_FRIEND_CONNECTION_LOOP_MS` | friend-connection tick (default 250) |

## Upgrading

`npm install @decentnetwork/peer@latest` (or `-g` for the CLI).
The keypair file format is stable; upgrades preserve identity and
friends.

## See also

- [`USAGE_GUIDE.md`](USAGE_GUIDE.md) — programmatic API guide,
  copy-paste examples for every common task
- Protocol-level reference (DHT / onion / TCP relay / FlatBuffers
  message kinds): not shipped in this tarball — see
  `docs/PROTOCOL_OVERVIEW.md` in the GitHub repo.
- Project page: https://github.com/0xli/peer