# 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:

```text
 ```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.