Nexnet

Open-source peer-to-peer social chat network with blockchain-backed identity, scarce usernames, local-first history, and privacy-routed discovery.

Status: TypeScript monorepo with 77 passing tests. Crypto, protocol, storage, client, workers, and TUI scaffolded and working. Chain .in app not yet implemented.

Nexnet should feel like a modern mix of Usenet, IRC, peer-to-peer messaging, and social discovery — without a central message store.

What users get

• Globally unique usernames rooted in wallet identity
• Public ownerless chatrooms
• Private end-to-end encrypted DMs and group chats
• Sender-held offline messages (no relay mailbox for private content)
• Multi-device accounts with peer-to-peer history transfer
• Interest / language / random discovery, with private routing for strangers
• Free standard use — no payment required for messaging or usernames

Core principles

Principle	Meaning
Local-first	Private history lives on user devices
P2P by default	Direct peer transfer when possible
E2EE	Relays never see private plaintext or long-term keys
Cryptographic identity	Wallet root; device-signed messages
Immutable communication	No edit / unsend protocol
Minimal social state	Exact online presence, delivered receipts only
Open protocol	Independent implementations welcome
Free user access	Infrastructure funded outside the chat UX

Architecture (overview)

flowchart TB
  subgraph Clients
    CLI[nexnet-cli]
    Core[nexnet-node / core]
  end

  subgraph Transport
    P2P[Direct P2P sessions]
    Route[Optional multi-hop routing]
  end

  subgraph Infra
    Relay[Relays: signalling · presence · room fanout]
    Disc[Discovery services]
    Chain[Blockchain: usernames · identity roots · relays]
  end

  CLI --> Core
  Core --> P2P
  Core --> Route
  Core --> Relay
  Core --> Disc
  Core --> Chain
  P2P <-->|encrypted messages · attachments| P2P
  Route --> Relay

Loading

Five layers:

1. Client — wallet, keys, local store, encrypt/sign, queue, UI/CLI
2. P2P transport — DM sessions, attachments, room gossip, device sync
3. Discovery / presence — username resolve, online leases, matching
4. Relays — signalling, NAT assist, optional onion path, public rooms
5. Blockchain — own chain (inauguration .in state machine); scarce authoritative state only (not private chat)

Full system map: docs/architecture.md

One-sentence definition

Nexnet is an open-source, wallet-identified, peer-to-peer social chat network with blockchain usernames, local-only history, sender-held offline messages, public ownerless chatrooms, private encrypted conversations, and privacy-routed stranger discovery.

Repository layout

nexnet/
  package.json            # Bun workspace
  tsconfig.json
  packages/               # TypeScript packages
    types/                # @nexnet/types — protocol types
    crypto/               # @nexnet/crypto — noble crypto wrappers
    protocol/             # @nexnet/protocol — CBOR CDE, event signing
    storage/              # @nexnet/storage — encrypted local DB
    client/               # @nexnet/client — messaging, rooms, groups
    tui/                  # @nexnet/tui — OpenTUI + SolidJS terminal client
    client/chain-stub.ts  # development chain adapter
  workers/                # Cloudflare Workers
    relay/                # signalling, room gossip
    presence/             # presence leases
    discovery/            # interests, language, random match
  chain/                  # inauguration .in state machine (AD-3)
  docs/
  test-vectors/
  schemas/

Documentation

Doc	Topic
docs/README.md	Doc index
docs/architecture.md	Layers, topology, data flow
docs/principles.md	Product principles
docs/identity.md	Wallet, username, passkeys, devices
docs/profiles.md	Bio profile fields (AD-24)
docs/chain.md	On-chain scope, token, treasury
docs/consensus.md	HotStuff consensus (AD-9)
docs/messaging.md	DMs, offline queue, receipts, ordering
docs/cryptography.md	Primitives and session design
docs/transport.md	Direct / routed / fallback modes
docs/presence.md	Exact online leases
docs/discovery.md	Interests, language, random match
docs/groups.md	Private creator-owned groups
docs/rooms.md	Public ownerless chatrooms
docs/attachments.md	Encrypted blob transfer
docs/multi-device.md	Fanout and history sync
docs/storage.md	Local encrypted DB
docs/protocol.md	Event model and encoding
docs/apis.md	Service surface
docs/reputation.md	Random-match reputation
docs/moderation.md	Abuse boundaries
docs/privacy.md	Content vs metadata privacy
docs/threat-model.md	Adversaries and guarantees
docs/mvp.md	First shippable slice
docs/phases.md	Implementation phases
docs/defaults.md	Product defaults
docs/open-decisions.md	Unresolved design issues
docs/stack.md	Recommended technology stack
docs/agent-notes.md	Coding-agent constraints

MVP snapshot

In: local identity, dev chain usernames, presence, direct E2EE DMs with sender-side offline queue, public rooms, basic discovery + random match, attachments, open-source relay, CLI client.

Out: production tokenomics, automated relay mining, full onion routing, nearby discovery, polished GUI, calls/video.

Details: docs/mvp.md · phases: docs/phases.md

Status

The TypeScript/Bun foundation is implemented: protocol types, reviewed crypto wrappers, CDE event signing, local encrypted storage, client flows, Workers, and a TUI all have tests. The chain application currently contains pure .in transition rules; its stateful executor and the end-to-end MVP remain to ship.

License

ISC — open protocol, independent implementations encouraged.

Contributing

Protocol and reference code are developed in the open. Design changes belong in issues against the docs in docs/.