Jon Staab
50 lines
2.4 KiB
Markdown
50 lines
2.4 KiB
Markdown
# 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.
|