Skip to main content

Crate nk_core

Crate nk_core 

Source
Expand description

§nk-core

The owned Rust implementation of the nostr wire protocol — the protocol crate of the nk-* workspace, platform-neutral (no_std + alloc, sans-IO) and byte-compatible with @qntx/nostr: both run the shared vectors in vectors/ and the differential stream suite with zero divergence (Rust’s only intentional difference is rejecting non-canonical JSON that JSON.parse accepts).

§Core

The crate root carries the model: per-module error enums (key::Error, event::Error, tag::Error, url::Error, filter::Error, message::Error), Timestamp, RelayUrl (WHATWG relay-URL normalization), Kind/KindClass, PublicKey, Tag/Tags/Coordinate, the UnsignedEvent/Event model with canonical NIP-01 serialization and SHA-256 event ids, SecretKey/Keys (BIP-340 Schnorr signing over secp256k1), Signature::verify/Event::verify, SingleLetterTag/Filter/fingerprint (NIP-01 filter matching, limits, canonical serialization), EventBuilder with Metadata/DeletionTarget (NIP-09 deletion, NIP-18 reposts, NIP-25 reactions), and SubscriptionId/CountResult/ClientMessage/RelayMessage (NIP-01/NIP-42/NIP-45/NIP-77 wire messages with from_json/to_json).

use nk_core::{EventBuilder, Keys, Timestamp};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let keys = Keys::generate()?; // os-rng feature
    let unsigned = EventBuilder::text_note("hello nostr")
        .build_at(keys.public_key(), Timestamp::from_secs(1_700_000_000));
    let event = keys.sign_event(unsigned, &mut nk_core::SysRng)?;
    event.verify()?;
    Ok(())
}

§NIPs

nips hosts the NIP implementations — every module is always compiled except nip04, nip44, and nip49, which carry extra dependencies. Each module owns its own Error enum: nip19 — the bech32 entity codec (npub/nsec/note/nprofile/nevent/naddr); nip21 — the nostr: URI scheme; nip04 — the legacy AES-256-CBC encrypted-DM payload; nip44 — NIP-44 v2 authenticated payload encryption with constant-time MAC verification; nip49 — ncryptsec secret-key encryption; plus the always-on NIP modules listed in the feature table below.

use nk_core::nips::nip19::Entity;
use nk_core::SecretKey;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let nsec = SecretKey::from_bytes([7; 32])?.to_bech32();
    let entity = Entity::from_bech32(&nsec)?;
    assert!(matches!(entity, Entity::Secret(_)));
    Ok(())
}

§Features

featuredefaulteffect
stdyesOS facilities; global secp256k1 context; base for clock/os-rng
clockyesTimestamp::now and wall-clock helpers where a NIP needs them
os-rngyesSecretKey::generate, Keys::generate, SubscriptionId::generate, SysRng
nip04nolegacy encrypted DMs (aes, cbc)
nip44nov2 payload encryption (chacha20, hkdf, hmac); also enables nips::nip17, nips::nip59, nip51 privates
nip49noncryptsec secret-key encryption (scrypt, chacha20poly1305)

Re-exports§

pub use event::Coordinate;
pub use event::DeletionTarget;
pub use event::Event;
pub use event::EventBuilder;
pub use event::EventId;
pub use event::Kind;
pub use event::KindClass;
pub use event::Metadata;
pub use event::Tag;
pub use event::Tags;
pub use event::UnsignedEvent;
pub use filter::Filter;
pub use filter::SingleLetterTag;
pub use filter::fingerprint;
pub use key::Keys;
pub use key::PublicKey;
pub use key::SecretKey;
pub use key::Signature;
pub use message::ClientMessage;
pub use message::CountResult;
pub use message::Hll;
pub use message::RelayMessage;
pub use message::SubscriptionId;
pub use signer::BoxFuture;
pub use signer::NostrSigner;
pub use signer::SignerBackendError;
pub use signer::SignerError;
pub use time::Timestamp;
pub use url::RelayUrl;
pub use rand_core;

Modules§

event
NIP-01 — the event model: event ids, signatures, unsigned and signed events, kinds, tags, builders, and the canonical serialization used for hashing.
filter
NIP-01 subscription filters: matching, intrinsic limit bounds, and the canonical serialization used by REQ coalescing.
key
Keys: x-only public keys, secret scalars, BIP-340 signatures and signing (NIP-01, BIP-340).
limits
Protocol byte/character limits shared by the wire types.
message
Client and relay wire messages — NIP-01, NIP-42, NIP-45, NIP-77.
nips
The NIP implementations of nk-core: nip04/nip44/nip49 sit behind their extra dependencies; every other NIP is always compiled.
signer
Signer abstraction (NIP-42/NIP-44-ready): any entity that can yield a public key and sign events, without the key material living in this crate.
time
Unix-timestamp newtype (seconds since the epoch) — NIP-01.
url
RelayUrl: a WHATWG-normalized relay URL (NIP-01, NIP-65).

Structs§

JsonError
A serde_json parse/validation failure, wrapped so no serde_json type leaks into the public API.
SysRngos-rng
A TryRng interface over the system’s preferred random number source