cesride

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cesride — Rust CESR Primitives

cesride — Rust CESR 原语

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.

cesride是KERI生态系统中CESR（可组合事件流表示）原语的Rust实现。它为加密材料（密钥、签名、摘要）提供了类型化包装器，支持合格的CESR编码（qb64/qb2），以及SAD序列化（Serder/Creder）、基于计数器的流帧和阈值逻辑。

核心设计：所有原语均实现

Matter

trait（带索引的签名则实现

Indexer

），提供统一的

qb64()

qb2()

raw()

code()

访问方式。所有类型的构造遵循一致的模式。

配套技能： 关于CESR编码理论和代码表，请参考cesr；关于KERI事件语义，请参考spec；关于ACDC凭证结构，请参考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

类型	用途	Trait	参考文档
`Verfer`	公钥验证密钥	Matter	cesr-primitives.md
`Signer`	私钥签名密钥（自动清零）	Matter	cesr-primitives.md
`Diger`	加密摘要	Matter	cesr-primitives.md
`Cigar`	无索引签名	Matter	cesr-primitives.md
`Siger`	带索引签名（多签）	Indexer	cesr-primitives.md
`Salter`	密钥派生盐（自动清零）	Matter	cesr-primitives.md
`Saider`	自寻址标识符（SAID）	Matter	cesr-primitives.md
`Prefixer`	KERI标识符前缀	Matter	cesr-primitives.md
`Seqner`	序列号（16字节）	Matter	cesr-primitives.md
`Number`	自动大小的无符号整数	Matter	cesr-primitives.md
`Dater`	ISO 8601时间戳	Matter	cesr-primitives.md
`Bexter`	Base64文本（Bext trait）	Matter	cesr-primitives.md
`Pather`	SAD路径解析器（Bext trait）	Matter	cesr-primitives.md
`Serder`	KERI事件序列化器	Sadder	sad-serialization.md
`Creder`	ACDC凭证序列化器	Sadder	sad-serialization.md
`Counter`	组帧结构	—	sad-serialization.md
`Tholder`	签名阈值逻辑	—	threshold-utils.md

Import Guide

导入指南

rust

// 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};

rust

// 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

文件	内容	大小
references/cesr-primitives.md	全部13种Matter/Indexer类型化原语——构造函数、方法、有效编码	11KB
references/sad-serialization.md	Sadder/Serder/Creder trait、Counter API、Ids/Ilkage常量	4KB
references/crypto.md	原生加密操作——签名/验证、哈希、拉伸、CSPRNG	5KB
references/data-errors.md	Value枚举、data::Number、Error（28种变体）、dat!宏	7KB
references/threshold-utils.md	Tholder（加权/非加权）、B64转换工具	6KB

Common Constructor Pattern

通用构造函数模式

All Matter primitives share the same constructor family:

rust

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.

所有Matter原语共享同一组构造函数：

rust

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>

构造优先级：按以下顺序取第一个非None值：raw → qb64b → qb64 → qb2。

Usage Patterns

使用示例

1. Generate Key Pair and Sign

1. 生成密钥对并签名

rust

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)?);

rust

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

2. Derive Keys from Salt

2. 从盐派生密钥

rust

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

rust

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

3. 创建并验证SAID

rust

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

rust

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

4. 构建KERI事件

rust

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

rust

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

5. 检查阈值满足情况

rust

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

rust

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

Anti-Patterns

反模式

DON'T: Store

Signer

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.

请勿： 存储

Signer

或

Salter

的原始字节——它们会在销毁时自动清零。请：结合分层路径使用

Salter::signers()

进行确定性密钥派生。

请勿： 使用

Cigar

实现多签——它不包含索引信息。请：使用

Siger

配合

sign_indexed()

进行多签协调。

请勿： 手动构造版本字符串。请：使用

versify()

deversify()

处理版本字符串。

请勿： 混淆

data::Number

（JSON数值包装器）与

core::Number

（CESR原语）。请：使用

core::Number

处理CESR编码整数，使用

data::Number

处理JSON值。

请勿： 将

Counter

作为Matter原语使用——它有自己的编码方案。请：使用

Counter::new_with_code_and_count()

实现流帧。