A Java implementation of the Nostr protocol: events, signing, relays, encrypted messaging, and an MCP server that puts all of it in reach of an LLM agent.
| If you want to | Read |
|---|---|
| Add the library to a build and send your first note | Getting started |
| See worked examples of the common tasks | API examples |
| Understand how the modules fit together | Architecture |
| Look up a class or method | API reference |
| Work out why something is failing | Troubleshooting |
The pages below are grouped by what they are for, following Diátaxis: tutorials teach, how-to guides solve a problem, reference describes the machinery, and explanation gives the reasoning.
Learning-oriented, for a first encounter with the library.
- Getting started — install via Maven or Gradle, generate an identity, publish a note.
Task-oriented, for someone who knows what they want to achieve.
Using the library
- Create, sign and send events — the shortest path from a keypair to a published event.
- API examples — worked examples of the common tasks, in one place.
- Publish and subscribe across many relays —
NostrClient, partial failure, and reading results back. - Send private direct messages — NIP-17 gift wrapping and delivery to each recipient's own relays.
- Stream long-lived subscriptions — staying connected and handling events as they arrive.
- Work with custom event kinds — events and tags the library does not model directly.
- Run the MCP server — let an LLM agent use Nostr, with the safety model explained.
Operating and diagnosing
- Diagnose relay failures — finding out which relay refused what, and why.
- Configure the library — timeouts, retries, and connection settings.
- Configure logging — what is logged, at which level, and how to change it.
- Collect metrics — the Micrometer metrics exposed and what they mean.
Releasing and contributing
- Cut a release — tagging, publishing, and BOM alignment.
- Configure release secrets — Maven Central and GPG credentials.
- Keep CI green — stabilising the Docker-backed integration tests.
- Maintain the roadmap project — the GitHub project board.
Information-oriented, for looking things up.
- API reference — classes, methods and signatures across the modules.
- Migration guide — what changed between major versions and how to move.
- Troubleshooting — symptoms, causes and fixes.
- Operations index — configuration, logging and metrics at a glance.
- Codebase overview — module layout, build and test commands.
- Shared vocabulary — what this project means by pool, publish result, and delivery plan.
Understanding-oriented, for the reasoning behind the design.
- Architecture — the modules, their dependencies, and how data flows between them.
- Working with events and tags —
GenericEvent,GenericTagand the kind ranges. - Dependency alignment — why versions are managed through a BOM.
- Secure coding guidelines — the rules this codebase follows around keys and encryption.
Specifications
- MCP server specification — the design of
nostr-java-mcp, including its safety model. - NIP-17 direct messages — private messages and NIP-59 gift wrapping.
Proposals and history
These describe work that is proposed, in progress, or finished. They are kept because the reasoning outlives the change.
- Simplification proposal — a proposed reduction of the 2.0 design. Describes code that does not all exist yet.
- 1.0 roadmap — historical, kept for context.
- Generic tag fragility — analysis of a
GenericTag.getCode()failure and its downstream effects. - Integration test bug analysis — why the relay container sometimes starts inert, and how the tests handle it.
Architecture decision records: what was decided, and what was given up.
- 0001 — Introduce
nostr-java-api— why the module exists and what it deliberately is not. - 0002 — Multi-relay failure semantics — partial failure, pool construction, de-duplication.
- 0003 — API v1 service scope — which services ship, and where NIP-17 orchestration lives.
- 0004 — Pool concurrency and subscription lifecycle — per-relay serialisation, parsed payloads, auto-resubscribe.
- 0005 — Pool membership, EOSE and ownership — mutable membership, synthetic EOSE, resource ownership.
DocumentationAccuracyTest in nostr-java-api runs with the ordinary build and fails when the
documentation drifts from the code: a guide naming a type or method that does not exist, a link
pointing at nothing, an install snippet quoting a version that is not the one being built, or a
page nobody links to from this index.
It found real problems when it was written, including a reference page teaching
BaseMessage.read(json), a method that has never existed. Documentation rots quietly because
nothing fails when it does, which is exactly why it is worth a test.