Crate nostr_sdk

source ·
Expand description

High level Nostr client library.

§Nostr SDK

crates.io crates.io - Downloads Documentation Rustc Version 1.64.0+ CI MIT

§Description

A high-level, Nostr client library written in Rust.

If you’re writing a typical Nostr client or bot, this is likely the crate you need.

However, the crate is designed in a modular way and depends on several other lower-level crates. If you’re attempting something more custom, you might be interested in these:

§Getting started

[dependencies]
nostr-sdk = "0.28"
tokio = { version = "1", features = ["full"] }
use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4};
use std::str::FromStr;

use nostr_sdk::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Generate new random keys
    let my_keys = Keys::generate();

    // Or use your already existing (from hex or bech32)
    let my_keys = Keys::parse("hex-or-bech32-secret-key")?;

    // Show bech32 public key
    let bech32_pubkey: String = my_keys.public_key().to_bech32()?;
    println!("Bech32 PubKey: {}", bech32_pubkey);

    // Create new client
    let client = Client::new(&my_keys);

    let proxy = Some(SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, 9050)));

    // Add relays
    client.add_relay("wss://relay.damus.io").await?;
    client.add_relay_with_opts(
        "wss://relay.nostr.info", 
        RelayOptions::new().proxy(proxy).write(false)
    ).await?;
    client.add_relay_with_opts(
        "ws://jgqaglhautb4k6e6i2g34jakxiemqp6z4wynlirltuukgkft2xuglmqd.onion",
        RelayOptions::new().proxy(proxy),
    ).await?;

    // Connect to relays
    client.connect().await;

    let metadata = Metadata::new()
        .name("username")
        .display_name("My Username")
        .about("Description")
        .picture(Url::parse("https://example.com/avatar.png")?)
        .banner(Url::parse("https://example.com/banner.png")?)
        .nip05("username@example.com")
        .lud16("yuki@getalby.com")
        .custom_field("custom_field", "my value");

    // Update metadata
    client.set_metadata(&metadata).await?;

    // Publish a text note
    client.publish_text_note("My first text note from Nostr SDK!", []).await?;

    // Create a POW text note
    let event: Event = EventBuilder::text_note("POW text note from nostr-sdk", []).to_pow_event(&my_keys, 20)?;
    client.send_event(event).await?; // Send to all relays
    // client.send_event_to(["wss://relay.damus.io"], event).await?; // Send to specific relay

    // --------- Zap! -------------

    // Configure zapper
    let uri = NostrWalletConnectURI::from_str("nostr+walletconnect://...")?;
    let zapper = NWC::new(uri).await?; // Use `WebLNZapper::new().await` for WebLN
    client.set_zapper(zapper).await;

    // Send SAT without zap event
    let public_key = PublicKey::from_bech32(
        "npub1drvpzev3syqt0kjrls50050uzf25gehpz9vgdw08hvex7e0vgfeq0eseet",
    )?;
    client.zap(public_key, 1000, None).await?;

    // Zap profile
    let details = ZapDetails::new(ZapType::Public).message("Test");
    client.zap(public_key, 1000, Some(details)).await?;

    // Zap event
    let event = Nip19Event::from_bech32("nevent1qqsr0q447ylm3y3tvw07vt69w3kzk026vl6yn3dwm9fweay0dw0jttgpz3mhxue69uhhyetvv9ujumn0wd68ytnzvupzq6xcz9jerqgqkldy8lpg7lglcyj4g3nwzy2cs6u70wejdaj7csnjqvzqqqqqqygequ53")?;
    let details = ZapDetails::new(ZapType::Anonymous).message("Anonymous Zap!");
    client.zap(event, 1000, Some(details)).await?;

    Ok(())
}

More examples can be found in the examples/ directory.

§WASM

This crate supports the wasm32 targets.

An example can be found at nostr-sdk-wasm-example repo.

On macOS you need to install llvm:

brew install llvm
LLVM_PATH=$(brew --prefix llvm)
AR="${LLVM_PATH}/bin/llvm-ar" CC="${LLVM_PATH}/bin/clang" cargo build --target wasm32-unknown-unknown

NOTE: Currently nip03 feature not support WASM.

§Crate Feature Flags

The following crate feature flags are available:

FeatureDefaultDescription
sqliteNoEnable SQLite Storage backend
rocksdbNoEnable RocksDB Storage backend
indexeddbNoEnable Web’s IndexedDb Storage backend
weblnNoEnable WebLN zapper
all-nipsYesEnable all NIPs
nip03NoEnable NIP-03: OpenTimestamps Attestations for Events
nip04YesEnable NIP-04: Encrypted Direct Message
nip05YesEnable NIP-05: Mapping Nostr keys to DNS-based internet identifiers
nip06YesEnable NIP-06: Basic key derivation from mnemonic seed phrase
nip07YesEnable NIP-07: window.nostr capability for web browsers (available only for wasm32!)
nip11YesEnable NIP-11: Relay Information Document
nip44YesEnable NIP-44: Encrypted Payloads (Versioned)
nip46YesEnable NIP-46: Nostr Connect
nip47YesEnable NIP-47: Nostr Wallet Connect
nip49YesEnable NIP-49: Private Key Encryption
nip57YesEnable NIP-57: Zaps
nip59YesEnable NIP-59: Gift Wrap

§Supported NIPs

Look at https://github.com/rust-nostr/nostr/tree/master/crates/nostr#supported-nips

§State

This library is in an ALPHA state, things that are implemented generally work but the API will change in breaking ways.

§Donations

rust-nostr is free and open-source. This means we do not earn any revenue by selling it. Instead, we rely on your financial support. If you actively use any of the rust-nostr libs/software/services, then please donate.

§License

This project is distributed under the MIT software license - see the LICENSE file for details

Re-exports§

Modules§

  • Correct, fast, and configurable base64 decoding and encoding. Base64 transports binary data efficiently in contexts where only plain text is allowed.
  • Encoding and decoding of the Bech32 format
  • BIP39 Mnemonic Codes
  • Rust Bitcoin Library
  • Client
  • Event
  • Rust hashes library.
  • Keys
  • Messages
  • Rust implementation of the negentropy set-reconciliation protocol.
  • NIPs
  • Rust bindings for Pieter Wuille’s secp256k1 library, which is used for fast and accurate manipulation of ECDSA signatures on the secp256k1 curve. Such signatures are used extensively by the Bitcoin network and its derivatives.
  • Serde JSON
  • Types
  • Util

Structs§

Enums§

Statics§

Traits§

Type Aliases§