Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Divergences from keripy

libkeri ports keripy (the reference KERI implementation) to Rust. This file lists where libkeri knowingly behaves differently. Any difference from keripy that isn’t listed here is a bug.

The evidence behind the rest:

  • tests/keripy_vectors.rs: events and receipts that keripy generated, which libkeri must reproduce byte for byte;
  • scripts/trace_check.py: every keripy symbol cited in the code must exist in the pinned keripy;
  • libkeri-interop: scenarios against kli and keripy witnesses.

Reference version: keripy 1.2.14 (bab95c16e), the version the vectors record.

Entries fall into three kinds:

  • Deliberate: a design choice. On the wire it matches keripy unless the entry says otherwise.
  • To fix: a known mismatch that should go.
  • Not implemented: keripy has it, libkeri doesn’t yet. Each entry says what libkeri does instead (panics, ignores, rejects).

Deliberate

AreakeripylibkeriWhy
ConcurrencyDoers (hio) run parsing and the escrows continuouslyNo threads, locks or async in the core. The owner drives work: Habery::ingest parses, routes and then runs Kevery::process_escrows once per batchlibkeri lets each consumer choose its own model (CLI, server, embedding). Escrow timeouts are only checked when the owner calls in
State ownershipHabery, Hab and Kevery share state freelyHabery owns Manager, Baser, Kevery and Revery; Hab<'a> is a borrowing viewOne copy of key state; Rust ownership
Unverified receipt escrow values (ures, uwes)qb64 values concatenatedDot-separated: said.prefix.cigar and said.wigqb64 never contains ., so values split without parsing sizes. Internal to the database
Delegation approval, delegate side1.1 Sealer: ask the delegator, then witness. 1.2/main Anchorer: witness, ask, then poll the delegator’s KEL (witq.query) and write the source seal couple (setAes) when foundWitness, ask (a /fwd to the delegator’s mailbox, as keripy), then a local watcher (libkeri-watcher) follows the delegator’s KEL from the delegator’s witness OOBIs. Habery::complete_delegation stores the couple only for a fully witnessed anchoring event that is the delegator’s last event at its sn, then the delegate publishes the event with -G and the delegator’s KEL to its witnesses and sends it to the delegatorNeither side writes approval state for the other; on the wire it matches 1.2/main
Delegation approval, delegator sidekli delegate confirm reads the delegable escrow (1.2+) or pses (1.1) that the mailbox fills; 1.2 writes the authorizer seal into its own db (_addAuthorizerSeal), main reprocesses the event directlykrust delegate confirm reads the delegable and misfit escrows; with no mailbox yet it fills them by watching the delegate’s witness OOBIs (--oobi). Habery::approve_delegation anchors the seal and reprocesses the event as local with that couple, as main doesNo mailbox in libkeri; works with 1.2/main delegates, whose witnesses hold the event before it asks
Witnessed group inceptionSupportedHabery::join_group_inception rejects a group inception with backers (“witnessed group inceptions are not supported yet”)Refuses rather than half-supports. The partially witnessed escrow now exists; the group flow is next

The escrow tables above are internal storage. A libkeri database isn’t meant to be opened by keripy, or the other way round.

To fix

Areakeripylibkeri
dt in replies and queries (reply.rs, query.rs)nowIso8601(): always 6 fractional digits and +00:00chrono::Utc::now().to_rfc3339(): up to 9 digits. keripy accepts it (it truncates to microseconds), but the bytes keripy would produce differ
help::helping::nowiso8601+00:00 offsetMicroseconds, but Z instead of +00:00, although its doc comment says it matches Python
Escrow timestamps (dtss)nowIso8601()to_rfc3339() (nanoseconds). Internal only
Partial-delegation escrow (escrowPDEvent, pdes/udes, processEscrowPartialDels)A delegated event whose delegating event is missing is escrowed and retriedRejected with MissingDelegationError (treated as escrowed by Habery::ingest but not stored): it must be sent again once the delegator’s KEL is known
Superseding rules for delegated recovery rotations (validateDelegation rules A–C)CheckedNot checked: a drt is accepted when its anchoring event is the delegator’s last event at that sn
Delegation source seal in the partial-signature, partial-witness and out-of-order escrowsStored with the event in udes (escrowPSEvent, escrowPWEvent, escrowOOEvent), reattached on retry and removed once acceptedNot stored, so a delegated event retried from escrow loses its seal
/loc/scheme and /end/role repliesBADA rule: a later dt replaces an earlier one, older ones are ignoredLast reply wins (process_reply_nontrans)

Not implemented

keripylibkeri behaviour when hit
Likely-duplicitous escrow (escrowLDEvent)Panics (todo!, Kevery::escrow_ld_event)
Receipt couples or transferable receipt quadruples attached to an event (not in a separate rct)Silently ignored: process_attached_receipt_couples and _quadruples return Ok, and route_message drops them
Replies signed by transferable AIDs (rpy with -F)Ignored, with a debug log (route_message)
Other message types (exn, ksn, TEL events, …)Ignored, with a debug log (route_message)
Manager.sign from a prefix and path, without keysPanics (unimplemented!, keeping/manager.rs)
Pather.path, Pather.rootPanics (unimplemented!, cesr/pather.rs)
Group rotation and interaction, signator hidden Hab, passcode/aeid encryptionNot available

keripy behaviour found by the delegation matrix

These are differences between keripy releases, or keripy bugs, that the libkeri-interop delegation scenarios (08–11) run into. They are recorded here so a failure against one keripy line isn’t mistaken for a libkeri bug.

keripyBehaviourEffect
1.1The delegate sends its event to the delegator before its witnesses receipt itA delegator without a mailbox (krust) never sees the request; scenario 09 marks it XFAIL (B1)
1.1A validator needs the -G couple; a 1.2+-style witness (keripy’s or libkeri’s) doesn’t store it for an event it witnessed before approvalA 1.1 kli can’t validate a delegate that witnessed first; scenario 08 marks it XFAIL (A8)
1.1Its witness rejects a /fwd from a delegate identifier that is mid-rotationkrust sends the drt through the proxy, as upstream delegate.sh does
1.2, mainA third party resolving a delegate’s witness OOBI stops at the dip; later drts stay escrowedSame with keripy’s own delegate (scenario 11); scenario 08 checks the rotation through the delegator instead
1.2delegate confirm waits for a drt with while eserder.sn < kever.sn (inverted; fixed in main cb512927)The wait returns at once; harmless here
mainkli writes KERI 2.0 events unless given --version 1.0The harness passes --version 1.0; libkeri reads 1.0 only
mainHTTP content type application/cesr (1.x: application/cesr+json); each answers 406 to the otherlibkeri-http retries a 406 with the other name

Components keripy bundles that live in separate crates here:

  • HTTP transport is in libkeri-http;
  • the witness server is in libkeri-witness;
  • the mailbox will be libkeri-mailbox;
  • the local KEL watcher for delegation approval is libkeri-watcher.

Adding an entry

When a vector, an interop scenario or a review finds a difference from keripy:

  1. Fix it, or add it here under the right heading.
  2. If you add it here, cite the keripy symbol in the code (for example keripy: core/eventing.py Kever.escrowPWEvent) so scripts/trace_check.py checks the reference.
  3. If a vector can show it, add one to libkeri-interop/vectors/gen.py and mark the Rust test #[ignore = "divergence: ..."] until it’s fixed.