Nostr library

A comprehensive low-level Elixir library implementing the Nostr protocol. Provides structures, parsing, serialization, and cryptographic functions for building Nostr applications.

Features

• Full event lifecycle: creation, signing, validation, serialization
• Schnorr signature support (secp256k1)
• NIP-44 encryption (versioned encrypted payloads)
• NIP-19 bech32 encoding (npub, nsec, note, nprofile, nevent, naddr)
• NIP-59 gift wrap protocol for private messaging
• WebSocket message protocol handling
• NIP-13 proof-of-work difficulty validation and mining helpers
• NIP-29 relay-based groups helpers
• NIP-77 negentropy wire message handling (NEG-OPEN, NEG-MSG, NEG-CLOSE, NEG-ERR)
• NIP-98 HTTP auth event creation and validation
• Subscription filter building

Installation

Add nostr_lib to your dependencies in mix.exs:

def deps do
  [
    {:nostr_lib, "~> 0.2.1"}
  ]
end

Quick Start

Create and Sign an Event

# Generate or use existing private key (32 bytes hex)
private_key = "your_private_key_hex"

# Create a text note (kind 1)
{:ok, event} = Nostr.Event.Note.create("Hello Nostr!", private_key)

# Serialize for sending to relay
json = Nostr.Event.serialize(event)

Parse Incoming Events

# Parse JSON from relay
{:ok, event} = Nostr.Event.parse(json_string)

# Validate event signature
case Nostr.Event.Validator.validate(event) do
  {:ok, event} -> # Valid event
  {:error, reason, event} -> # Invalid
end

Build Subscription Filters

# Create a filter for text notes from specific authors
filter = %Nostr.Filter{
  kinds: [1],
  authors: ["pubkey1", "pubkey2"],
  limit: 100
}

Bech32 Encoding

# Encode public key as npub
{:ok, npub} = Nostr.Bech32.encode(:npub, pubkey_hex)
# => "npub1..."

# Decode back
{:ok, {:npub, pubkey}} = Nostr.Bech32.decode(npub)

Implemented NIPs

Core Modules

Event Types

Each event kind has a dedicated module in Nostr.Event.*:

Related Packages

This library is part of a larger Nostr ecosystem for Elixir:

• nostr_lib (this package) - Low-level protocol implementation
• nostr_client - WebSocket client for connecting to relays
• nostr_server - WebSocket server for building relays
• nostr_relay - Full relay implementation

Documentation

Full documentation is available on HexDocs.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.