docs: update root README with SDK and pluggable architecture

README.md

@@ -20,6 +20,10 @@ KERIOX is an open-source Rust implementation of the [ Key Event Receipt Infrastr
 
 KERI provides the same security and verifiability properties for transactions as a blockchain or distributed ledger can, without the overhead of requiring an absolute global ordering of transactions. Because of this, there is no need for a canonical chain and thus there is no "KERI Chain" or "KERI Network". KERI Identifiers can be generated independently in a self-sovereign and privacy-preserving manner and are secured via a self-certifying post-quantum resistant key management scheme based on blinded pre-rotation, auditable and flexible key events and a distributed conflict resolution algorithm called KAACE.
 
+## Architecture
+
+KERIOX is designed around pluggable abstractions that allow it to run in diverse environments. The `EventDatabase` trait abstracts storage so that backends can be swapped at compile time; `redb` is the default (feature-flagged as `storage-redb`), and an in-memory implementation is available for testing or custom backends. Notification dispatch is also pluggable via `NotificationBus`, which supports injectable dispatch strategies suitable for serverless environments such as SQS-backed message routing. The `KeriRuntime<D>` struct bundles the processor, storage, escrows, and notification bus into a single composable unit, enabling thin Lambda handlers or other lightweight entry points.
+
 ## License
 
 EUPL 1.2
@@ -39,3 +43,4 @@ This repository provides the implementation of the KERI protocol. [`keriox_core`
 - [Witness](./components/witness): the KERI Witness
 - [Watcher](./components/watcher): the KERI Watcher
 - [Controller](./components/controller): the client for accessing the infrastructure
+- [SDK](./keriox_sdk): high-level SDK providing `KeriRuntime` and `Controller` for KERI+TEL operations

components/controller/src/known_events.rs

@@ -64,16 +64,8 @@ impl KnownEvents {
 
         let oobi_manager = OobiManager::new(event_database.clone());
 
-        let (
-            mut notification_bus,
-            (
-                _out_of_order_escrow,
-                _partially_signed_escrow,
-                partially_witnessed_escrow,
-                _delegation_escrow,
-                _duplicates,
-            ),
-        ) = default_escrow_bus(event_database.clone(), escrow_config);
+        let (notification_bus, escrows) =
+            default_escrow_bus(event_database.clone(), escrow_config, None);
 
         let kel_storage = Arc::new(EventStorage::new(event_database.clone()));
 
@@ -106,7 +98,7 @@ impl KnownEvents {
             processor: BasicProcessor::new(event_database.clone(), Some(notification_bus)),
             storage: kel_storage,
             oobi_manager,
-            partially_witnessed_escrow,
+            partially_witnessed_escrow: escrows.partially_witnessed,
             tel,
         };
 

components/watcher/src/watcher/watcher_data.rs

@@ -99,7 +99,7 @@ impl WatcherData {
 
         let oobi_manager = OobiManager::new(events_db.clone());
 
-        let (mut notification_bus, _) = default_escrow_bus(events_db.clone(), escrow_config);
+        let (notification_bus, _escrows) = default_escrow_bus(events_db.clone(), escrow_config, None);
         let reply_escrow = Arc::new(ReplyEscrow::new(events_db.clone()));
         notification_bus.register_observer(
             reply_escrow.clone(),
@@ -112,7 +112,7 @@ impl WatcherData {
         let prefix = BasicPrefix::Ed25519NT(signer.public_key()); // watcher uses non transferable key
         let processor = BasicProcessor::new(events_db.clone(), Some(notification_bus));
 
-        let storage = Arc::new(EventStorage::new(events_db));
+        let storage = Arc::new(EventStorage::new_redb(events_db));
 
         // construct witness loc scheme oobi
         let loc_scheme = LocationScheme::new(

components/witness/src/tests.rs

@@ -99,7 +99,7 @@ fn test_not_fully_witnessed() -> Result<(), Error> {
             let not = Notice::Event(inception_event.clone());
             w.process_notice(not).unwrap();
             w.event_storage
-                .mailbox_data
+                .mailbox_data.as_ref().unwrap()
                 .get_mailbox_receipts(controller.prefix(), 0)
                 .into_iter()
                 .flatten()
@@ -185,7 +185,7 @@ fn test_not_fully_witnessed() -> Result<(), Error> {
     // first_witness.respond(signer_arc.clone())?;
     let first_receipt = first_witness
         .event_storage
-        .mailbox_data
+        .mailbox_data.as_ref().unwrap()
         .get_mailbox_receipts(controller.prefix(), 0)
         .unwrap()
         .map(Notice::NontransferableRct)
@@ -280,7 +280,7 @@ fn test_qry_rpy() -> Result<(), ActorError> {
     // send receipts to alice
     let receipt_to_alice = witness
         .event_storage
-        .mailbox_data
+        .mailbox_data.as_ref().unwrap()
         .get_mailbox_receipts(alice.prefix(), 0)
         .unwrap()
         .map(Notice::NontransferableRct)

components/witness/src/witness.rs

@@ -86,7 +86,7 @@ impl Notifier for WitnessReceiptGenerator {
 
 impl WitnessReceiptGenerator {
     pub fn new(signer: Arc<Signer>, events_db: Arc<RedbDatabase>) -> Self {
-        let storage = EventStorage::new(events_db.clone());
+        let storage = EventStorage::new_redb(events_db.clone());
         let prefix = BasicPrefix::Ed25519NT(signer.public_key());
         Self {
             prefix,
@@ -171,8 +171,8 @@ impl Witness {
 
         let events_db =
             Arc::new(RedbDatabase::new(&events_database_path).map_err(|_| Error::DbError)?);
-        let mut witness_processor = WitnessProcessor::new(events_db.clone(), escrow_config);
-        let event_storage = Arc::new(EventStorage::new(events_db.clone()));
+        let witness_processor = WitnessProcessor::new(events_db.clone(), escrow_config);
+        let event_storage = Arc::new(EventStorage::new_redb(events_db.clone()));
 
         let receipt_generator = Arc::new(WitnessReceiptGenerator::new(
             signer.clone(),

components/witness/src/witness_processor.rs

@@ -22,7 +22,7 @@ pub struct WitnessProcessor {
 impl Processor for WitnessProcessor {
     type Database = RedbDatabase;
     fn register_observer(
-        &mut self,
+        &self,
         observer: Arc<dyn Notifier + Send + Sync>,
         notifications: &[JustNotification],
     ) -> Result<(), Error> {
@@ -62,7 +62,7 @@ impl Default for WitnessEscrowConfig {
 
 impl WitnessProcessor {
     pub fn new(redb: Arc<RedbDatabase>, escrow_config: WitnessEscrowConfig) -> Self {
-        let mut bus = NotificationBus::new();
+        let bus = NotificationBus::new();
         let partially_signed_escrow = Arc::new(PartiallySignedEscrow::new(
             redb.clone(),
             escrow_config.partially_signed_timeout,

keriox_core/Cargo.toml

@@ -13,11 +13,12 @@ repository.workspace = true
 crate-type = ["cdylib", "rlib"]
 
 [features]
-default = []
+default = ["storage-redb"]
+storage-redb = ["redb"]
 query = ["serde_cbor"]
 oobi = ["url", "strum_macros", "strum"]
-oobi-manager = ["oobi", "query", "reqwest", "async-trait", "serde_cbor"]
-mailbox = ["query", "serde_cbor"]
+oobi-manager = ["oobi", "query", "storage-redb", "reqwest", "async-trait", "serde_cbor"]
+mailbox = ["query", "storage-redb", "serde_cbor"]
 
 [dependencies]
 bytes = "1.3.0"
@@ -43,7 +44,7 @@ chrono = { version = "0.4.18", features = ["serde"] }
 arrayref = "0.3.6"
 zeroize = "1.3.0"
 fraction = { version = "0.9", features = ["with-serde-support"] }
-redb = "2.3.0"
+redb = { version = "2.3.0", optional = true }
 
 # oobis dependecies
 async-trait = { version = "0.1.57", optional = true }

keriox_core/benches/bench.rs

@@ -20,8 +20,8 @@ fn setup_processor() -> (
 
     let events_db_path = NamedTempFile::new().unwrap();
     let events_db = Arc::new(RedbDatabase::new(events_db_path.path()).unwrap());
-    let (not_bus, (_ooo_escrow, _, _, _, _)) =
-        default_escrow_bus(events_db.clone(), EscrowConfig::default());
+    let (not_bus, _escrows) =
+        default_escrow_bus(events_db.clone(), EscrowConfig::default(), None);
 
     let (processor, storage) = (
         BasicProcessor::new(events_db.clone(), Some(not_bus)),

keriox_core/src/actor/error.rs

@@ -1,5 +1,6 @@
 use http::StatusCode;
 
+#[cfg(feature = "storage-redb")]
 use crate::database::redb::RedbError;
 use crate::event_message::cesr_adapter::ParseError;
 use crate::keys::KeysError;
@@ -74,6 +75,7 @@ impl From<VersionError> for ActorError {
     }
 }
 
+#[cfg(feature = "storage-redb")]
 impl From<RedbError> for ActorError {
     fn from(err: RedbError) -> Self {
         ActorError::DbError(err.to_string())

keriox_core/src/actor/simple_controller.rs

@@ -3,8 +3,10 @@ use std::{
     sync::{Arc, Mutex},
 };
 
+#[cfg(feature = "storage-redb")]
+use crate::database::redb::RedbDatabase;
 use crate::{
-    database::{redb::RedbDatabase, EscrowCreator, EventDatabase},
+    database::{EscrowCreator, EventDatabase},
     processor::escrow::{
         maybe_out_of_order_escrow::MaybeOutOfOrderEscrow,
         partially_witnessed_escrow::PartiallyWitnessedEscrow,
@@ -72,15 +74,16 @@ pub struct SimpleController<K: KeyManager + 'static, D: EventDatabase + EscrowCr
 }
 
 // impl<K: KeyManager, D: EventDatabase + Send + Sync + 'static> SimpleController<K, D> {
+#[cfg(feature = "storage-redb")]
 impl<K: KeyManager> SimpleController<K, RedbDatabase> {
     // incept a state and keys
     pub fn new(
         event_db: Arc<RedbDatabase>,
         key_manager: Arc<Mutex<K>>,
         escrow_config: EscrowConfig,
     ) -> Result<SimpleController<K, RedbDatabase>, Error> {
-        let (not_bus, (ooo, _, partially_witnesses, del_escrow, _duplicates)) =
-            default_escrow_bus(event_db.clone(), escrow_config);
+        let (not_bus, escrows) =
+            default_escrow_bus(event_db.clone(), escrow_config, None);
         let processor = BasicProcessor::new(event_db.clone(), Some(not_bus));
 
         Ok(SimpleController {
@@ -90,9 +93,9 @@ impl<K: KeyManager> SimpleController<K, RedbDatabase> {
             processor,
             storage: EventStorage::new(event_db.clone()),
             groups: vec![],
-            not_fully_witnessed_escrow: partially_witnesses,
-            ooo_escrow: ooo,
-            delegation_escrow: del_escrow,
+            not_fully_witnessed_escrow: escrows.partially_witnessed,
+            ooo_escrow: escrows.out_of_order,
+            delegation_escrow: escrows.delegation,
         })
     }