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

Design

No runtime in the libraries

keripy runs everything in hio “Doers”: generators that a scheduler resumes on every tick. libkeri has no threads, locks or async in its core, and neither do the crates around it. The owner (a CLI, a server, an embedded app) drives the work and picks its own concurrency model.

  • Habery owns the key manager, the database and the event processors. Hab is a borrowing view of one local identifier.
  • Every network call lives in libkeri-http or in an optional driver feature.
  • A library that has to wait on someone else is sans-IO: it says what to fetch and decides from what it is given. libkeri-watcher’s next_request and feed work this way; its http feature adds an async polling loop.

Escrows are retried when data arrives

An event that can’t be accepted yet (short of signatures or witness signatures, out of order, or waiting on a delegator) is stored, not rejected:

  1. the event, its signatures, its source and the time it was first escrowed go into the database, with an index row per escrow;
  2. Habery::ingest routes a batch of messages, then makes one pass over the escrows;
  3. each pass accepts an entry, leaves it waiting, or drops it as invalid or older than its timeout.

With no new input nothing runs. An owner that wants timeouts enforced on a clock calls Habery::process_escrows() on its own schedule. Crates added later (libkeri-tel, libkeri-acdc) follow the same rule: their own escrow tables, and a process_escrows call the owner makes after ingest.

Approvals are explicit calls

Where keripy waits in a loop for something to change, libkeri exposes a call. For delegation:

  • the delegator lists pending_delegations() and calls approve_delegation(...);
  • the delegate’s watcher calls complete_delegation(...) once the delegator’s KEL holds a fully witnessed anchoring event.

keripy is the reference

Behaviour follows keripy 1.2.14. Code ported from keripy cites the keripy symbol (for example keripy: core/eventing.py Kever.escrowPWEvent), and a lint checks that every cited symbol exists. Every known difference is listed in Divergences; any difference not listed there is a bug.