How to Create Your Own Decentralized Messenger Protocol

Developer Karboosx released an architecture specification for lnchat, a decentralized messaging protocol designed for end-to-end encrypted communication across independent servers without central orchestration. According to karboosx.net's report, the system establishes direct server-to-server exchanges using domain discovery, standardized JSON payloads, and cryptographic signature verification to prevent spoofed domain requests.

This technical guide details protocol constraints, address formatting, well-known metadata discovery manifests, public key resolution schemas, and browser-side cryptographic key storage for backend engineers and protocol designers. The design prioritizes single-device text messaging to demonstrate core federation mechanics, deliberately omitting attachments, group channels, multi-device syncing, and delivery receipts.

01Server federation and domain discovery

Federation allows autonomous servers to join a shared network and exchange data directly without passing through a centralized coordinator. The system functions much like SMTP email, where anyone can deploy an independent mail server without central approval. Participating hosts rely on well-defined protocol contracts and shared payload schemas to communicate directly.

Direct communication requires an initial discovery routine to determine which destination server manages a given identity. In email environments, an outbound host extracts the destination domain and performs a DNS lookup for MX records. Federated messaging applies this exact concept by establishing discovery steps before servers initiate direct HTTP connections.

Security requirements dictate that federated nodes must not blindly trust unauthenticated HTTP requests asserting domain ownership. When an external machine sends an inbound request, the receiving server must verify that the message carries a valid cryptographic signature. This validation proves that the request genuinely originated from the host controlling the source domain.

02Protocol constraints and user identity formats

The lnchat specification eliminates unnecessary complexities to establish a lean baseline for private messaging. Advanced features such as media attachments, multi-device management, group chat channels, and read receipts are excluded from the initial release. Confining the design to single-device text messaging reduces attack vectors while keeping implementation requirements realistic.

User identities follow the standard email syntax pattern of nickname followed by domain name separated by an at-symbol. While alternate formats such as hash symbols or arrow notation are possible, email-shaped addresses provide an intuitive convention. The domain component informs foreign servers where to query federation metadata when resolving user accounts.

Individual home servers manage local user authentication, registrations, and account storage independently. End-to-end encryption ensures that host servers only route encrypted ciphertext payloads without accessing underlying message plaintext. Client devices handle all encryption and decryption operations locally, preventing intermediate servers from snooping on user communication.

03Well-known metadata manifests and versioning

Instead of relying on custom DNS records, lnchat implements discovery through an HTTP manifest in the standard well-known directory. Every compliant server must serve a static JSON configuration file at GET /.well-known/lnchat.json. This manifest allows connecting hosts to verify whether a target domain supports the protocol before initiating federation calls.

The manifest enforces explicit protocol versioning to ensure backward compatibility as system requirements change. The initial release specifies the version value lnchat.federation.v1 to validate contractual expectations between servers. Including version strings directly in the root discovery file prevents communication breakdowns when node operators upgrade their backend software.

In addition to version strings, the discovery JSON defines an endpoints map that advertises custom federation routes. Rather than hardcoding fixed URL paths site-wide, servers expose a resolve_users endpoint pointing to their preferred route, such as https://example.com/federation/v1/users/resolve. This design prevents path conflicts with existing web applications running on the same domain.

04Batch user resolution and key schemas

Before dispatching encrypted payloads, a sending server queries the destination host's resolve_users endpoint to collect recipient public keys. The request payload accepts an array of user handles, such as adam@x.com and eve@x.com, alongside the protocol version. Querying multiple users in a single HTTP request significantly reduces latency and server load on high-volume networks.

The response payload delivers an array containing individual status evaluations for each queried account. Valid accounts return an ok status with a key object holding a unique key_id and a raw public_key string. Accounts that exist on the server but have not generated cryptographic keys receive a not_deliverable status to indicate delivery is currently impossible.

Assigning unique identifiers like adam-enc-2026-07-a to keys allows clients to manage local key caches and identify rotation events. If a recipient public key changes unexpectedly, clients can warn users of potential tampering or compromised credentials. Because servers publish these keys, complete security models require additional safeguards like key fingerprints, trust-on-first-use rules, or key transparency verification.

05Browser key generation and IndexedDB storage

To maintain end-to-end encryption integrity, client devices must generate cryptographic keys locally rather than delegating creation to servers. Web clients call window.crypto.subtle.generateKey using the X25519 algorithm with deriveBits usage flags. Setting the extractable parameter to false ensures private keys remain non-extractable, preventing malicious scripts or debugging logs from exposing sensitive key data.

Browsers persist these non-extractable CryptoKey objects inside client-side IndexedDB storage to survive page reloads safely. Clients then export their corresponding public key in raw format using window.crypto.subtle.exportKey and upload it to their home server database. The home server stores this thirty-two-byte public key and exposes it externally through the resolve_users federation interface.

The exported public key is not used to encrypt message payloads directly during transmission. Instead, client cryptographic routines utilize the sender private key and receiver public key to compute a shared secret. This derived secret encrypts the message payload, ensuring that federated home servers transport only ciphertext across the network.