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

# Build all crates
cargo build

# Build release binaries
cargo build --release

# Run all tests (300 total)
cargo test --workspace

Usage

Generate a keypair

cargo run -p keypair-generator

Sign a text note

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

Use as a library dependency

Add to your Cargo.toml:

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

Relay pool

RelayPool keeps a set of relay connections alive in the background: it reconnects with exponential backoff (1 s → 60 s, ×2, ±20% jitter), replays open REQ subscriptions after every reconnect, and publishes a status snapshot through a tokio::sync::watch channel.

use nostr_relay::pool::{RelayPool, ReconnectConfig};
use std::sync::Arc;

// Persistent pool: unlimited reconnect attempts, 1 s → 60 s backoff,
// 10 s per-attempt connect timeout.
let pool = Arc::new(RelayPool::new(Some(ReconnectConfig::persistent())));
for url in ["wss://relay.damus.io", "wss://nos.lol"] {
    pool.add_relay(url).await?;
}

// Drive the pool in the background (non-blocking; pass a small tick).
tokio::spawn(Arc::clone(&pool).run(50));

// Watch connection status changes (RelayStatusInfo: status, attempt,
// next_retry_in, last_error, connected_for, enabled).
let mut rx = pool.status_watch();
while rx.changed().await.is_ok() {
    for s in rx.borrow().iter() {
        println!("{}: {:?}", s.url, s.status);
    }
}

// Per-relay manual control: a disabled relay is never connected by the
// pool (run(), subscribe, publish_async, connect_all*) until re-enabled.
pool.disable_relay("wss://relay.damus.io").await?;   // disconnect + stay down
pool.enable_relay("wss://relay.damus.io").await?;    // reconnect right away
pool.reconnect_relay("wss://relay.damus.io").await?; // force drop + retry now
pool.add_relay_disabled("wss://backup.lol").await?;  // add parked (disabled)

Fetch a user's NIP-65 relay list through the bootstrap relays:

let relay_list = nostr_relay::nip65::fetch_relay_list(
    &pubkey_hex,
    &nostr_relay::nip65::default_bootstrap_relays(),
    8_000,
).await?;

Test Summary

Crate	Tests	Description
`nostr-core`	62	Types, errors, crypto, utilities
`nostr-nips`	97	All 18 NIP implementations
`nostr-relay`	46	WebSocket, HTTP, relay pool (35 unit + 11 pool_live integration)
`nostr-signer`	29	Signer trait, local + signer
`nostr-services`	31	Validator, Blossom, Cashu
`integration-tests`	35	Ported from C test suite
Total	300

Versioning

This project uses Semantic Versioning with a single source of truth in the VERSION file. The workspace version in Cargo.toml and the badge in README.md are kept in sync by the increment_and_push.sh script.

Releasing a new version

# 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:

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

Changelog

See CHANGELOG.md for a record of notable changes per release. Follow the Keep a Changelog format when adding entries under [Unreleased].

License

MIT

README.md Unescape Escape

NOSTR Core Library — Rust

📋 NIP Implementation Status

Core Protocol NIPs

Workspace Structure