coracle-rust/book/01-introduction.md

Introduction

Nostr is a simple, open protocol for decentralized social networking. Unlike traditional platforms, nostr has no central server. Instead, users publish signed messages called events to a network of relays — simple WebSocket servers that store and forward events.

The protocol's power comes from its simplicity. At its core, nostr defines just one data structure (the event) and a handful of message types for communicating with relays. Everything else — social graphs, encrypted messaging, long-form content, marketplace listings — is built on top of this foundation through a system of NIPs (Nostr Implementation Possibilities), which are community-authored specifications.

What this book covers

This book is both a tutorial and the source code for the coracle family of Rust crates:

• coracle-lib — Core types and stateless utilities: events, keys, tags, filters, and serialization. Everything you need to understand and manipulate nostr data.
• coracle-net — Networking: connecting to relays, managing subscriptions, publishing events, and relay discovery.
• coracle-signer — Signing abstractions: local key signing, NIP-46 remote signing, and browser extension integration.
• coracle-content — Content handling: parsing note text, rendering mentions, handling media links, and working with NIP-27 references.
• coracle-storage — Persistence: storing and querying events locally across different platforms and backends.

The chapters are ordered so that each concept builds on what came before. Code blocks marked with a file path are tangled — extracted and assembled into Rust source files that form the actual library. What you're reading is the source code.

How literate programming works here

Throughout this book, you'll see code blocks annotated with an output file path like this:

 ```rust {file=coracle-lib/src/lib.rs}
 pub mod event;

These blocks are the real source code. The `coracle-tangle` tool extracts them in document
order and writes them to the indicated file paths. Multiple blocks targeting the same file are
concatenated, so a struct can be introduced in one section and have methods added later in the
narrative.

Code blocks *without* a file annotation are illustrative — they show examples, intermediate
states, or protocol concepts without contributing to the compiled output.