Repository files navigation

nostr-java is a Java SDK for theNostr protocol. It provides utilities for creating, signing and publishing Nostr events to relays.

• Maven
• Java 21+

Seedocs/GETTING_STARTED.md for installation and usage instructions.

• Full test suite (requires Docker for Testcontainers ITs):

  mvn -q verify

• Without Docker (skips Testcontainers-based integration tests via profile):

  mvn -q -Pno-docker verify

Theno-docker profile excludes tests under**/nostr/api/integration/** and setsnoDocker=true for conditional test disabling.

For diagnosing relay send issues and capturing failure details, see the how‑to guide:docs/howto/diagnostics.md.

• Docs index:docs/README.md — quick entry point to all guides and references.
• Operations:docs/operations/README.md — logging, metrics, configuration, diagnostics.
• Getting started:docs/GETTING_STARTED.md — install via Maven/Gradle and build from source.
• API how‑to:docs/howto/use-nostr-java-api.md — create, sign, and publish basic events.
• Streaming subscriptions:docs/howto/streaming-subscriptions.md — open and manage long‑lived, non‑blocking subscriptions.
• Custom events how‑to:docs/howto/custom-events.md — define, sign, and send custom event types.
• API reference:docs/reference/nostr-java-api.md — classes, key methods, and short examples.
• Extending events:docs/explanation/extending-events.md — guidance for extending the event model.
• Codebase overview and contributing:docs/CODEBASE_OVERVIEW.md — layout, testing, and contribution workflow.

Examples are located in thenostr-java-examples module. See theAPI Examples Guide for detailed walkthroughs.

• NostrApiExamples – Comprehensive examples covering 13+ use cases including text notes, encrypted DMs, reactions, channels, and more. See theguide for details.

• SpringSubscriptionExample – Shows how to open a non-blockingNostrSpringWebSocketClient subscription and close it after a fixed duration.

• ✅Clean Architecture - Modular design following SOLID principles
• ✅Comprehensive NIP Support - 25 NIPs implemented covering core protocol, encryption, payments, and more
• ✅Type-Safe API - Strongly-typed events, tags, and messages with builder patterns
• ✅Non-Blocking Subscriptions - Spring WebSocket client with reactive streaming support
• ✅Well-Documented - Extensive JavaDoc, architecture guides, and code examples
• ✅Production-Ready - High test coverage, CI/CD pipeline, code quality checks

🎯API Cleanup & Removals (breaking)

• Deprecated APIs removed:Constants.Kind,Encoder.ENCODER_MAPPER_BLACKBIRD, and NIP01 Identity-based overloads
• NIP01 now exclusively uses the instance-configured sender; builder simplified accordingly

🚀Performance & Serialization

• Centralized JSON mapper vianostr.event.json.EventJsonMapper (Blackbird module); unified across event encoders

📚Documentation & Structure

• Migration guide updated for 1.0.0 removals and replacements
• Troubleshooting moved to dedicated how‑to:docs/howto/diagnostics.md
• README streamlined to focus on users; maintainer topics moved under docs

🛠️Build & Release Tooling

• CI workflow split for Docker vs no‑Docker runs
• Release automation (scripts/release.sh) with bump/tag/verify/publish steps

Seedocs/explanation/architecture.md for detailed architecture overview.

25 NIPs implemented - comprehensive coverage of core protocol, security, and advanced features.

Coverage: 25/100+ NIPs (core protocol + most commonly used extensions)

Contributions are welcome! SeeCONTRIBUTING.md for:

• Coding standards and conventions
• How to add new NIPs
• Pull request guidelines
• Testing requirements

For architectural guidance, seedocs/explanation/architecture.md.

This project is licensed under the MIT License - see theLICENSE file for details.