Expand description
kivi Rust SDK — the untrusting client for the kivi event ledger.
The SDK constitution, enforced here and tested by the conformance suite:
- an answer without a trace is UNREPRESENTABLE (
TracedAnswer::newrefuses an empty trace); - client-side verification is ON by default:
replayre-hashes every record, checks chain linkage and gapless numbering, and verifies Ed25519 seals — a lying server or wire returnsKiviError::Verification; - honest refusals map to a typed
KiviError—NotFoundis never a silentNone; - identity: a bearer token at dial time,
login()for kivi-user sessions, andwith_bearer()views for per-caller credentials over one shared channel — the server decides everything, per call.
Numbers travel as JSON strings end to end and are decoded with
serde_json, whose default Number holds any i64/u64 exactly (no float
detour) — int64 values round-trip exactly (conformance S2).
Modules§
Structs§
- Chain
Checker - Verifies a replay stream record by record: hash, gapless numbering, chain
linkage and (optionally) Ed25519 seals. A lying stream returns
KiviError::Verification— the server or the wire cannot get away with it. - Client
- The kivi client for Rust. Async-first (tokio). Cheap to clone: clones
share the underlying channel (tonic channels are already connection-pooled
and cloneable), and
with_bearergives a clone with its OWN credential. - Graph
Edge - One directed, traced relation edge: source —relation→ target, set by record
no. - Graph
Hop - One step of a path:
from—relation→to, via edge recordno. - Graph
Reached - A node found by a traversal, with its depth and the edge record numbers along the shortest discovering path (the proof).
- Head
- The cheap orientation answer: last record number + head hash (no audit).
- Receipt
- The proof of a write: record number, byte offset, hash.
- Record
Integrity Checker - Subscribe’s checker (G14): each record’s OWN hash/signature is verified, but — unlike ChainChecker — numbering gaps and prev_hash discontinuities are EXPECTED (server-side type filtering causes them by design) and are never treated as tampering.
- Session
- The result of a login: the bearer token plus its honest envelope.
- Similar
Answer - Similar
Hit - One traced similarity hit: the record’s address, its score, and the raw receipt itself — an untraced score does not exist.
- Traced
Answer - Value + the events that established it + the ledger scope it was derived from. Constructing one without a trace is refused — by design (the whole point of the second constitutional rule above).
- Verify
Report - Mirrors the server’s dataset-wide audit.
- View
Entry - One row of a paged view read: canonical key + decoded value (trace inside).
- View
Page - One page of a keyset walk over a compiled view.
next_keyempty = done.scope/hashstamp the SNAPSHOT: passscopeback asas_ofand every later page keeps describing that same moment. - View
State - A whole compiled view plus its canonical digest.
Enums§
- Kivi
Error - Honest refusals, typed.
NotFoundis never a fabricatedNone.
Functions§
- body_as
- Decode an already-fetched record’s BODY into a TYPED entity
T— the “entity out” for records fromreplay,subscribe,whyorget_record. Zero extra dependency (serde).