cesride — Rust CESR Primitives

Overview

cesride is the Rust implementation of CESR (Composable Event Streaming Representation) primitives for the KERI ecosystem. It provides typed wrappers around cryptographic material (keys, signatures, digests) with qualified CESR encoding (qb64/qb2), plus SAD serialization (Serder/Creder), counter-based stream framing, and threshold logic.

Key design: every primitive implements the Matter trait (or Indexer for indexed signatures), giving uniform qb64()/qb2()/raw()/code() access. Construction follows a consistent pattern across all types.

Companion skills: For CESR encoding theory and code tables, see cesr. For KERI event semantics, see spec. For ACDC credential structure, see acdc.

Quick Reference

Type	Purpose	Trait	Reference
Verfer	Public verification key	Matter	cesr-primitives.md
Signer	Private signing key (auto-zeroized)	Matter	cesr-primitives.md
Diger	Cryptographic digest	Matter	cesr-primitives.md
Cigar	Unindexed signature	Matter	cesr-primitives.md
Siger	Indexed signature (multisig)	Indexer	cesr-primitives.md
Salter	Key derivation salt (auto-zeroized)	Matter	cesr-primitives.md
Saider	Self-Addressing Identifier (SAID)	Matter	cesr-primitives.md
Prefixer	KERI identifier prefix	Matter	cesr-primitives.md
Seqner	Sequence number (16-byte)	Matter	cesr-primitives.md
Number	Auto-sized unsigned integer	Matter	cesr-primitives.md
Dater	ISO 8601 timestamp	Matter	cesr-primitives.md
Bexter	Base64 text (Bext trait)	Matter	cesr-primitives.md
Pather	SAD path resolver (Bext trait)	Matter	cesr-primitives.md
Serder	KERI event serializer	Sadder	sad-serialization.md
Creder	ACDC credential serializer	Sadder	sad-serialization.md
Counter	Group framing construct	—	sad-serialization.md
Tholder	Signing threshold logic	—	threshold-utils.md

Import Guide

// Core traits
use cesride::core::matter::Matter;
use cesride::core::indexer::Indexer;
use cesride::core::sadder::Sadder;
use cesride::core::bexter::Bext;

// Primitives
use cesride::core::{Verfer, Diger, Signer, Salter, Cigar, Siger};
use cesride::core::{Saider, Prefixer, Seqner, Number, Dater, Bexter, Pather};

// Serialization
use cesride::core::{Serder, Creder, Counter};
use cesride::core::common::{versify, deversify, sniff};

// Code tables
use cesride::core::matter::tables as MatterCodex;
use cesride::core::indexer::tables as IndexerCodex;
use cesride::core::counter::tables as CounterCodex;

// Data model
use cesride::data::{Value, dat};
use cesride::error::{Error, Result};

// Crypto (raw bytes, no CESR)
use cesride::crypto::{sign, hash, salt, csprng};

Reference Files

File	Contents	Size
references/cesr-primitives.md	All 13 typed Matter/Indexer primitives — constructors, methods, valid codes	11KB
references/sad-serialization.md	Sadder/Serder/Creder traits, Counter API, Ids/Ilkage constants	4KB
references/crypto.md	Raw cryptographic operations — sign/verify, hash, stretch, CSPRNG	5KB
references/data-errors.md	Value enum, data::Number, Error (28 variants), dat! macro	7KB
references/threshold-utils.md	Tholder (weighted/unweighted), B64 conversion utilities	6KB

Common Constructor Pattern

All Matter primitives share the same constructor family:

Type::new(/* type-specific params */, code, raw, qb64b, qb64, qb2) -> Result<Self>
Type::new_with_raw(raw, code) -> Result<Self>
Type::new_with_qb64(qb64) -> Result<Self>
Type::new_with_qb64b(qb64b) -> Result<Self>
Type::new_with_qb2(qb2) -> Result<Self>

Construction dispatches: first non-None wins in order: raw → qb64b → qb64 → qb2.

Usage Patterns

1. Generate Key Pair and Sign

let signer = Signer::new_with_defaults(Some(true), None)?; // Ed25519, transferable
let verfer = signer.verfer();
let cigar = signer.sign_unindexed(message)?;
assert!(verfer.verify(&cigar.raw(), message)?);

2. Derive Keys from Salt

let salter = Salter::new_with_defaults(Some("low"))?;
let signers = salter.signers(Some(3), None, Some("icp"), None, None, None, None)?;

3. Create and Verify SAID

let (saider, saidified_sad) = Saider::saidify(&sad, None, None, None, None)?;
assert!(saider.verify(&saidified_sad, None, None, None, None, None)?);

4. Build KERI Event

let serder = Serder::new_with_ked(&ked, None, None)?;
let said = serder.said()?;
let pre = serder.pre()?;
let raw = serder.raw();

5. Check Threshold Satisfaction

let tholder = Tholder::new_with_sith(&dat!([["1/2", "1/2"], ["1"]]))?;
assert!(tholder.satisfy(&[0, 1, 2])?);

Anti-Patterns

DON'T: Store Signer or Salter raw bytes — they auto-zeroize on drop. DO: Use Salter::signers() with hierarchical paths for deterministic key derivation.

DON'T: Use Cigar for multisig — it has no index information. DO: Use Siger with sign_indexed() for multisig coordination.

DON'T: Construct version strings manually. DO: Use versify()/deversify() for version string handling.

DON'T: Confuse data::Number (JSON numeric wrapper) with core::Number (CESR primitive). DO: Use core::Number for CESR-encoded integers, data::Number for JSON values.

DON'T: Use Counter as a Matter primitive — it has its own encoding scheme. DO: Use Counter::new_with_code_and_count() for stream framing.