Crate notepack 

notepack

A Rust library for packing and parsing nostr notes into a compact binary format called notepack.

This crate provides two core capabilities:

• Encoding: Turn a Note (a structured Nostr event) into a notepack binary, or a Base64 string prefixed with notepack_.
• Decoding / Streaming Parsing: Efficiently stream through a binary notepack payload using NoteParser, yielding fields as they are parsed (without needing to fully deserialize).

Features

• Compact binary format using varint encoding for integers.
• Streaming parser: no allocation-heavy parsing; fields are yielded one by one as they’re read.

Example: Encoding a Note

use notepack::{NoteBuf, pack_note_to_string};

let note = NoteBuf {
    id: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa".into(),
    pubkey: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb".into(),
    created_at: 1753898766,
    kind: 1,
    tags: vec![vec!["tag".into(), "value".into()]],
    content: "Hello, world!".into(),
    sig: "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc".into(),
};

let packed = pack_note_to_string(&note).unwrap();
println!("{packed}");
// prints something like `notepack_AAECA...`

Example: Streaming Parse

use notepack::{NoteParser, ParsedField};

let b64 = "notepack_737yskaxtaKQSL3IPPhOOR8T1R4G/f4ARPHGeNPfOpF4417q9YtU+4JZGOD3+Y0S3uVU6/edo64oTqJQ0pOF29Ms7GmX6fzM4Wjc6sohGPlbdRGLjhuqIRccETX5DliwUFy9qGg2lDD9oMl8ijoNFq4wwJ5Ikmr4Vh7NYWBwOkuo/anEBgECaGkA";
let bytes = NoteParser::decode(b64).unwrap();
let parser = NoteParser::new(&bytes);

for field in parser {
    match field.unwrap() {
        ParsedField::Id(id) => println!("id: {}", hex::encode(id)),
        ParsedField::Content(c) => println!("content: {}", c),
        _ => {}
    }
}

Binary Tool

This crate also ships with a small CLI called notepack (see main.rs):

• Pipe in a JSON Nostr event → outputs a notepack_... string.
• Pipe in a notepack_... string → outputs the JSON representation.

echo '{"id":"...","pubkey":"...","created_at":123,"kind":1,"tags":[],"content":"Hi","sig":"..."}' \
  | notepack

Modules

• Note — main event struct used for encoding.
• NoteParser — streaming parser for notepack binaries.
• ParsedField — enum of parsed fields yielded by the parser.
• Error — unified error type.
• StringType — distinguishes between raw byte tags and UTF-8 tags.

Spec

The notepack format is loosely inspired by MessagePack but optimized for Nostr notes. Strings that look like 32-byte hex are stored more compactly; integers are encoded as LEB128-style varints; and the format starts with a version field for forward compatibility.

Structs

Note

a Nostr note in notepack format

NoteBuf

NoteParser

Stateful streaming parser for notepack binary payloads.

TagElems

A lazy iterator over the elements of a single tag.

Tags

A lazy view over tags in a packed Note.

Enums

Error

ParsedField

Represents a parsed field from a notepack‐encoded Nostr note.

ParserState

Internal parser state machine.

StringType

Functions

pack_note

Packs a Note into its compact binary notepack representation.

pack_note_to_string

Encodes a Note directly to a notepack_... Base64 string.