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

• Maven
• Java 21+

See docs/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

The no-docker profile excludes tests under **/nostr/api/integration/** and sets noDocker=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 the nostr-java-examples module. See the API Examples Guide for detailed walkthroughs.

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

• SpringSubscriptionExample – Shows how to open a non-blocking NostrSpringWebSocketClient 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 via nostr.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

See docs/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! See CONTRIBUTING.md for:

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

For architectural guidance, see docs/explanation/architecture.md.

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