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
kliand 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
| Area | keripy | libkeri | Why |
|---|---|---|---|
| Concurrency | Doers (hio) run parsing and the escrows continuously | No threads, locks or async in the core. The owner drives work: Habery::ingest parses, routes and then runs Kevery::process_escrows once per batch | libkeri lets each consumer choose its own model (CLI, server, embedding). Escrow timeouts are only checked when the owner calls in |
| State ownership | Habery, Hab and Kevery share state freely | Habery owns Manager, Baser, Kevery and Revery; Hab<'a> is a borrowing view | One copy of key state; Rust ownership |
Unverified receipt escrow values (ures, uwes) | qb64 values concatenated | Dot-separated: said.prefix.cigar and said.wig | qb64 never contains ., so values split without parsing sizes. Internal to the database |
| Delegation approval, delegate side | 1.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 found | Witness, 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 delegator | Neither side writes approval state for the other; on the wire it matches 1.2/main |
| Delegation approval, delegator side | kli 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 directly | krust 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 does | No mailbox in libkeri; works with 1.2/main delegates, whose witnesses hold the event before it asks |
| Witnessed group inception | Supported | Habery::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
| Area | keripy | libkeri |
|---|---|---|
dt in replies and queries (reply.rs, query.rs) | nowIso8601(): always 6 fractional digits and +00:00 | chrono::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 offset | Microseconds, 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 retried | Rejected 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) | Checked | Not 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 escrows | Stored with the event in udes (escrowPSEvent, escrowPWEvent, escrowOOEvent), reattached on retry and removed once accepted | Not stored, so a delegated event retried from escrow loses its seal |
/loc/scheme and /end/role replies | BADA rule: a later dt replaces an earlier one, older ones are ignored | Last reply wins (process_reply_nontrans) |
Not implemented
| keripy | libkeri 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 keys | Panics (unimplemented!, keeping/manager.rs) |
Pather.path, Pather.root | Panics (unimplemented!, cesr/pather.rs) |
| Group rotation and interaction, signator hidden Hab, passcode/aeid encryption | Not 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.
| keripy | Behaviour | Effect |
|---|---|---|
| 1.1 | The delegate sends its event to the delegator before its witnesses receipt it | A delegator without a mailbox (krust) never sees the request; scenario 09 marks it XFAIL (B1) |
| 1.1 | A 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 approval | A 1.1 kli can’t validate a delegate that witnessed first; scenario 08 marks it XFAIL (A8) |
| 1.1 | Its witness rejects a /fwd from a delegate identifier that is mid-rotation | krust sends the drt through the proxy, as upstream delegate.sh does |
| 1.2, main | A third party resolving a delegate’s witness OOBI stops at the dip; later drts stay escrowed | Same with keripy’s own delegate (scenario 11); scenario 08 checks the rotation through the delegator instead |
| 1.2 | delegate confirm waits for a drt with while eserder.sn < kever.sn (inverted; fixed in main cb512927) | The wait returns at once; harmless here |
| main | kli writes KERI 2.0 events unless given --version 1.0 | The harness passes --version 1.0; libkeri reads 1.0 only |
| main | HTTP content type application/cesr (1.x: application/cesr+json); each answers 406 to the other | libkeri-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:
- Fix it, or add it here under the right heading.
- If you add it here, cite the keripy symbol in the code (for example
keripy: core/eventing.py Kever.escrowPWEvent) soscripts/trace_check.pychecks the reference. - If a vector can show it, add one to
libkeri-interop/vectors/gen.pyand mark the Rust test#[ignore = "divergence: ..."]until it’s fixed.