# NOSTR Core Library — Rust

A Rust implementation of the NOSTR protocol library, ported from the C `nostr_core_lib` project.

[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](#)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](#)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](#building)

## 📋 NIP Implementation Status

### Core Protocol NIPs
- [x] [NIP-01](nips/01.md) — Basic protocol flow — event creation, signing, and validation
- [ ] NIP-02 — Contact List and Petnames
- [x] [NIP-03](nips/03.md) — OpenTimestamps Attestations for Events
- [x] [NIP-04](nips/04.md) — Encrypted Direct Messages (legacy)
- [x] [NIP-05](nips/05.md) — Mapping Nostr keys to DNS-based internet identifiers
- [x] [NIP-06](nips/06.md) — Basic key derivation from mnemonic seed phrase
- [ ] NIP-07 — `window.nostr` capability for web browsers
- [ ] NIP-08 — Handling Mentions
- [ ] NIP-09 — Event Deletion
- [ ] NIP-10 — Conventions for clients' use of `e` and `p` tags in text events
- [x] [NIP-11](nips/11.md) — Relay Information Document
- [ ] NIP-12 — Generic Tag Queries
- [x] [NIP-13](nips/13.md) — Proof of Work
- [ ] NIP-14 — Subject tag in text events
- [ ] NIP-15 — Nostr Marketplace
- [ ] NIP-16 — Event Treatment
- [x] [NIP-17](nips/17.md) — Private Direct Messages
- [ ] NIP-18 — Reposts
- [x] [NIP-19](nips/19.md) — bech32-encoded entities
- [ ] NIP-20 — Command Results
- [x] [NIP-21](nips/21.md) — `nostr:` URI scheme
- [ ] NIP-22 — Event `created_at` Limits
- [ ] NIP-23 — Long-form Content
- [ ] NIP-24 — Extra metadata fields and tags
- [ ] NIP-25 — Reactions
- [ ] NIP-26 — Delegated Event Signing
- [ ] NIP-27 — Text Note References
- [ ] NIP-28 — Public Chat
- [ ] NIP-29 — Relay-based Groups
- [ ] NIP-30 — Custom Emoji
- [ ] NIP-31 — Dealing with Unknown Events
- [ ] NIP-32 — Labeling
- [ ] NIP-33 — Parameterized Replaceable Events
- [x] [NIP-34](nips/34.md) — `git` stuff
- [ ] NIP-35 — Torrents
- [ ] NIP-36 — Sensitive Content
- [ ] NIP-37 — Draft Events
- [ ] NIP-38 — User Statuses
- [ ] NIP-39 — External Identities in Profiles
- [ ] NIP-40 — Expiration Timestamp
- [x] [NIP-42](nips/42.md) — Authentication of clients to relays
- [x] [NIP-44](nips/44.md) — Versioned Encryption
- [ ] NIP-45 — Counting results
- [x] [NIP-46](nips/46.md) — Nostr Remote Signing
- [ ] NIP-47 — Wallet Connect
- [ ] NIP-48 — Proxy Tags
- [ ] NIP-49 — Private Key Encryption
- [ ] NIP-50 — Search Capability
- [ ] NIP-51 — Lists
- [ ] NIP-52 — Calendar Events
- [ ] NIP-53 — Live Activities
- [ ] NIP-54 — Wiki
- [ ] NIP-55 — Android Signer Application
- [ ] NIP-56 — Reporting
- [ ] NIP-57 — Lightning Zaps
- [ ] NIP-58 — Badges
- [x] [NIP-59](nips/59.md) — Gift Wrap
- [x] [NIP-60](nips/60.md) — Cashu Wallet
- [x] [NIP-61](nips/61.md) — Nutzaps
- [ ] NIP-62 — Log events
- [ ] NIP-64 — Chess (PGN)
- [ ] NIP-65 — Relay List Metadata
- [ ] NIP-66 — Relay Monitor
- [ ] NIP-68 — Web badges
- [ ] NIP-69 — Peer-to-peer Order events
- [ ] NIP-70 — Protected Events
- [ ] NIP-71 — Video Events
- [ ] NIP-72 — Moderated Communities
- [ ] NIP-73 — External Content IDs
- [ ] NIP-75 — Zap Goals
- [ ] NIP-77 — Arbitrary custom app data
- [ ] NIP-78 — Application-specific data
- [ ] NIP-84 — Highlights
- [ ] NIP-86 — Relay Management API
- [ ] NIP-87 — Relay List Recommendations
- [ ] NIP-88 — Stella: A Stellar Relay
- [ ] NIP-89 — Recommended Application Handlers
- [ ] NIP-90 — Data Vending Machines
- [ ] NIP-92 — Media Attachments
- [ ] NIP-94 — File Metadata
- [ ] NIP-96 — HTTP File Storage Integration
- [ ] NIP-98 — HTTP Auth
- [ ] NIP-99 — Classified Listings

**Legend:** ✅ Implemented | ❌ Not Implemented

**Implementation Summary:** 14 of 96+ NIPs fully implemented (14.6%)

## Workspace Structure

```
nostr_core_lib_rust/
├── core/              # Core types, errors, crypto, utilities
├── relay/             # WebSocket, HTTP, relay pool
├── nips/              # All NIP implementations
├── signer/            # Signer trait, local + signer remote
├── services/          # Request validator, Blossom, Cashu
├── nostr-core/        # Umbrella re-export crate
├── examples/          # Example programs
│   ├── keypair_generator/  # Generate Nostr keypairs
│   └── event_signer/       # Create and sign events
└── tests/             # Integration tests (ported from C)
```

## Building

```bash
# Build all crates
cargo build

# Build release binaries
cargo build --release

# Run all tests (202 total)
cargo test --workspace
```

## Usage

### Generate a keypair

```bash
cargo run -p keypair-generator
```

### Sign a text note

```bash
cargo run -p event-signer -- nsec1... "Hello, Nostr!"
```

### Use as a library dependency

Add to your `Cargo.toml`:

```toml
[dependencies]
nostr-core = { git = "ssh://git@laantungir.net:2222/laantungir/nostr_core_lib_rust.git" }
```

## Test Summary

| Crate | Tests | Description |
|-------|-------|-------------|
| `nostr-core` | 34 | Types, errors, crypto, utilities |
| `nostr-nips` | 68 | All 14 NIP implementations |
| `nostr-relay` | 8 | WebSocket, HTTP, relay pool |
| `nostr-signer` | 23 | Signer trait, local + signer |
| `nostr-services` | 31 | Validator, Blossom, Cashu |
| `integration-tests` | 38 | Ported from C test suite |
| **Total** | **202** | |

## Versioning

This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
with a single source of truth in the [`VERSION`](VERSION) file. The workspace
version in [`Cargo.toml`](Cargo.toml) and the badge in
[`README.md`](README.md) are kept in sync by the
[`increment_and_push.sh`](increment_and_push.sh) script.

### Releasing a new version

```bash
# Patch bump (bug fixes): 0.2.0 → 0.2.1
./increment_and_push.sh patch

# Minor bump (new features): 0.2.0 → 0.3.0
./increment_and_push.sh minor

# Major bump (breaking changes): 0.2.0 → 1.0.0
./increment_and_push.sh major

# Prerelease bump: 0.2.0 → 0.2.0-pre.1
./increment_and_push.sh prerelease

# Set an explicit version
./increment_and_push.sh 1.2.3

# Preview without modifying files or git
./increment_and_push.sh minor --dry-run

# Bump without pushing to origin
./increment_and_push.sh patch no-push
```

The script:
1. Reads the current version from [`VERSION`](VERSION).
2. Computes the next version per the requested bump type.
3. Updates [`VERSION`](VERSION), the workspace version in
   [`Cargo.toml`](Cargo.toml), and the badge in [`README.md`](README.md).
4. Moves the `[Unreleased]` section in [`CHANGELOG.md`](CHANGELOG.md) to the
   new version with today's date.
5. Verifies the workspace still builds with `cargo build --workspace`.
6. Creates a `[release] vX.Y.Z` commit and an annotated `vX.Y.Z` git tag.
7. Pushes the branch and tag to `origin` (unless `no-push`).

### Changelog

See [`CHANGELOG.md`](CHANGELOG.md) for a record of notable changes per
release. Follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
format when adding entries under `[Unreleased]`.

## License

MIT