Skip to main content

libkeri/keri/core/eventing/
kevery.rs

1use crate::cesr::cigar::Cigar;
2use crate::cesr::dater::Dater;
3use crate::cesr::indexing::siger::Siger;
4use crate::cesr::indexing::Indexer;
5use crate::cesr::Parsable;
6use crate::cesr::prefixer::Prefixer;
7use crate::cesr::saider::Saider;
8use crate::cesr::seqner::Seqner;
9use crate::cesr::verfer::Verfer;
10use crate::keri::core::eventing::kever::{escrow_event, Kever};
11use crate::keri::core::eventing::{verify_sigs, ReplyEventBuilder};
12use crate::keri::core::parsing::Trqs;
13use crate::keri::core::serdering::{Rawifiable, SadValue, Serder, SerderKERI};
14use crate::keri::db::basing::Baser;
15use crate::keri::db::dbing::keys::{dg_key, sn_key};
16use crate::keri::db::subing::SuberError;
17use crate::keri::{Ilk, KERIError};
18use crate::Matter;
19use indexmap::IndexSet;
20use std::collections::{HashMap, VecDeque};
21use std::string::FromUtf8Error;
22use std::sync::Arc;
23use tracing::{debug, info};
24
25/// Kevery (Key Event Message Processing Facility) processes an incoming
26/// message stream composed of KERI key event related messages and attachments.
27/// Kevery acts a Kever (key event verifier) factory for managing key state of
28/// KERI identifier prefixes.
29///
30/// Only supports current version VERSION
31pub struct Kevery {
32    /// Database instance for KERI event storage
33    pub db: Arc<Baser>,
34
35    /// Notices of events needing receipt or requests needing response
36    pub cues: VecDeque<Cue>,
37
38    /// Optional recovery module
39    pub rvy: Option<Rvy>,
40
41    /// True means operate in promiscuous (unrestricted) mode,
42    /// False means operate in nonpromiscuous (restricted) mode
43    /// as determined by local and prefixes
44    pub lax: bool,
45
46    /// True means event source is local (protected) for validation
47    /// False means event source is remote (unprotected) for validation
48    pub local: bool,
49
50    /// True means cloned message stream so use attached datetimes from clone source not own
51    /// False means use current datetime
52    pub cloned: bool,
53
54    /// True means direct mode so cue notices for receipts etc
55    /// False means indirect mode so don't cue notices
56    pub direct: bool,
57
58    /// True means do not update the database in any non-idempotent way.
59    /// Useful for reinitializing the Kevers from a persisted KEL without
60    /// updating non-idempotent first seen .fels and timestamps.
61    pub check: bool,
62
63    /// Cache of kevers indexed by prefix
64    pub kevers: HashMap<String, Kever>,
65
66    /// Identifiers controlled locally (own AIDs and group AIDs). Owned here, not
67    /// in Baser, so there is exactly one copy; passed to Kever during validation.
68    pub locals: Locals,
69}
70
71/// Identifiers controlled by this process. `prefixes` are all local AIDs
72/// (including group AIDs); `groups` are the subset that are group multisig AIDs.
73#[derive(Debug, Clone, Default)]
74pub struct Locals {
75    pub prefixes: IndexSet<String>,
76    pub groups: IndexSet<String>,
77}
78
79/// Cue represents a notice of an event needing receipt or a request needing response
80#[derive(Debug, Clone)]
81pub struct Cue {
82    kin: String,
83    serder: SerderKERI,
84}
85
86/// Recovery module for Kevery
87pub struct Rvy {
88    pub db: Baser,
89}
90
91impl Kevery {
92    /// Timeout constants (in seconds)
93    pub const TIMEOUT_OOE: u64 = 1200; // seconds to timeout out of order escrows
94    pub const TIMEOUT_PSE: u64 = 3600; // seconds to timeout partially signed or delegated escrows
95    pub const TIMEOUT_PWE: u64 = 3600; // seconds to timeout partially witnessed escrows
96    pub const TIMEOUT_LDE: u64 = 3600; // seconds to timeout likely duplicitous escrows
97    pub const TIMEOUT_UWE: u64 = 3600; // seconds to timeout unverified receipt escrows
98    pub const TIMEOUT_URE: u64 = 3600; // seconds to timeout unverified receipt escrows
99    pub const TIMEOUT_VRE: u64 = 3600; // seconds to timeout unverified transferable receipt escrows
100    pub const TIMEOUT_KSN: u64 = 3600; // seconds to timeout key state notice message escrows
101    pub const TIMEOUT_QNF: u64 = 300; // seconds to timeout query not found escrows
102
103    /// Initialize a new Kevery instance
104    ///
105    /// # Parameters
106    /// * `cues` - Optional cues to initialize with
107    /// * `db` - Database instance
108    /// * `rvy` - Optional recovery module
109    /// * `lax` - True means operate in promiscuous (unrestricted) mode
110    /// * `local` - True means event source is local (protected) for validation
111    /// * `cloned` - True means cloned message stream so use attached datetimes from clone source
112    /// * `direct` - True means direct mode so cue notices for receipts etc
113    /// * `check` - True means do not update the database in any non-idempotent way
114    pub fn new(
115        cues: Option<VecDeque<Cue>>,
116        db: Arc<Baser>,
117        rvy: Option<Rvy>,
118        lax: Option<bool>,
119        local: Option<bool>,
120        cloned: Option<bool>,
121        direct: Option<bool>,
122        check: Option<bool>,
123    ) -> Result<Self, KERIError> {
124        let db = db;
125
126        Ok(Self {
127            cues: cues.unwrap_or_else(VecDeque::new),
128            db,
129            rvy,
130            lax: lax.unwrap_or(true),
131            local: local.unwrap_or(false),
132            cloned: cloned.unwrap_or(false),
133            direct: direct.unwrap_or(true),
134            check: check.unwrap_or(false),
135            kevers: HashMap::new(),
136            locals: Locals::default(),
137        })
138    }
139
140    /// Get a reference to the kevers dictionary
141    pub fn kevers(&self) -> &HashMap<String, Kever> {
142        &self.kevers
143    }
144
145    /// Get a mutable reference to the kevers dictionary
146    pub fn kevers_mut(&mut self) -> &mut HashMap<String, Kever> {
147        &mut self.kevers
148    }
149
150    /// Get the prefixes as an ordered set
151    pub fn prefixes(&self) -> &IndexSet<String> {
152        &self.locals.prefixes
153    }
154
155    /// Process one event serder with attached indexed signatures sigers
156    ///
157    /// # Parameters
158    /// * `serder` - Instance of event to process
159    /// * `sigers` - Instances of attached controller indexed sigs
160    /// * `wigers` - Instances of attached witness indexed sigs, otherwise None
161    /// * `delseqner` - Instance of delegating event sequence number.
162    ///                If this event is not delegated then seqner is ignored
163    /// * `delsaider` - Instance of delegating event SAID.
164    ///                If this event is not delegated then saider is ignored
165    /// * `firner` - Instance of cloned first seen ordinal.
166    ///             If cloned mode then firner maybe provided (not None)
167    /// * `dater` - Instance of cloned replay datetime.
168    ///            If cloned mode then dater maybe provided (not None)
169    /// * `eager` - True means try harder to find validate events by walking KELs.
170    ///            False means only use pre-existing information if any.
171    /// * `local` - True means local (protected) event source.
172    ///            False means remote (unprotected).
173    ///            None means use default .local.
174    pub fn process_event(
175        &mut self,
176        serder: SerderKERI,
177        sigers: Vec<Siger>,
178        wigers: Option<Vec<Siger>>,
179        delseqner: Option<Seqner>,
180        delsaider: Option<Saider>,
181        firner: Option<Seqner>,
182        dater: Option<Dater>,
183        eager: Option<bool>,
184        local: Option<bool>,
185    ) -> Result<(), KERIError> {
186        let eager = eager.unwrap_or(false);
187        // Use provided local or default to self.local, and force it to be a boolean
188        let local = match local {
189            Some(val) => val,
190            None => self.local,
191        };
192
193        // Fetch ked ilk, pre, sn, dig to see how to process
194        let pre = serder
195            .pre()
196            .ok_or_else(|| KERIError::ValueError("Missing pre in event".to_string()))?;
197        let ked = serder.ked();
198
199        // See if code of pre is supported and matches size of pre
200        match Prefixer::from_qb64(&pre) {
201            Ok(_) => (),
202            Err(e) => {
203                return Err(KERIError::ValueError(format!(
204                    "Invalid pre = {:?} for evt = {:?}. Error: {:?}",
205                    &pre, &ked, e
206                ))
207                .into());
208            }
209        }
210
211        let sn = serder
212            .sn()
213            .ok_or_else(|| KERIError::ValueError("Missing sn in event".to_string()))?;
214        let ilk = serder
215            .ilk()
216            .ok_or_else(|| KERIError::ValueError("Missing ilk in event".to_string()))?;
217        let said = serder
218            .said()
219            .ok_or_else(|| KERIError::ValueError("Missing said in event".to_string()))?;
220
221        if !self.kevers.contains_key(&pre) {
222            // First seen event for pre
223            if ilk == Ilk::Icp || ilk == Ilk::Dip {
224                // First seen and inception so verify event keys
225
226                // Create kever from serder
227                let kever = Kever::new(
228                    self.db.clone(),
229                    &self.locals,
230                    None, // state
231                    Some(serder.clone()),
232                    Some(sigers.clone()),
233                    wigers.clone(),
234                    None, // est_only
235                    delseqner,
236                    delsaider,
237                    if self.cloned { firner } else { None },
238                    if self.cloned { dater } else { None },
239                    Some(eager),
240                    Some(local),
241                    Some(self.check),
242                )?;
243
244                // Not exception so add to kevers
245                self.kevers.insert(pre.clone(), kever);
246
247                // At this point the inceptive event (icp or dip) given by serder
248                // together with its attachments has been accepted as valid with finality.
249                // Events that don't get to here have either been dropped as
250                // invalid by raising an error or have been escrowed as not
251                // yet complete enough to decide their validity.
252
253                // Handle cues for receipt or notice
254                if self.direct || self.lax || !self.locals.prefixes.contains(&pre) {
255                    // Create cue for receipt controller or watcher
256                    self.cues.push_back(Cue {
257                        kin: "receipt".to_string(),
258                        serder: serder.clone(),
259                    });
260                } else if !self.direct {
261                    // Notice of new event
262                    self.cues.push_back(Cue {
263                        kin: "notice".to_string(),
264                        serder: serder.clone(),
265                    });
266                }
267
268                // Handle witness cues if needed
269                if self.local && self.kevers[&pre].locally_witnessed(&self.locals, None, Some(&serder)) {
270                    // TODO: need to cue task here kin = "witness" and process
271                    // cued witness and then combine with receipt above so only
272                    // one receipt is generated not two
273                    self.cues.push_back(Cue {
274                        kin: "witness".to_string(),
275                        serder: serder.clone(),
276                    });
277                }
278            } else {
279                // Not inception so can't verify sigs etc, add to out-of-order escrow
280                self.escrow_oo_event(
281                    &serder,
282                    &sigers,
283                    delseqner.as_ref(),
284                    delsaider.as_ref(),
285                    Some(&wigers.unwrap_or_default()),
286                    local,
287                )?;
288
289                return Err(
290                    KERIError::OutOfOrderError(format!("Out-of-order event={:?}.", ked)).into(),
291                );
292            }
293        } else {
294            // Already accepted inception event for pre so already first seen
295            if ilk == Ilk::Icp || ilk == Ilk::Dip {
296                // Another inception event so maybe duplicitous
297                if sn != 0 {
298                    return Err(KERIError::ValueError(format!(
299                        "Invalid sn={} for inception event={:?}.",
300                        sn,
301                        serder.ked()
302                    ))
303                    .into());
304                }
305
306                // Check if duplicate of existing inception event since est is icp
307                let eserder = match self.fetch_est_event(&pre, sn) {
308                    Some(serder) => serder,
309                    None => {
310                        return Err(KERIError::ValueError(
311                            "Kever not found for known prefix".to_string(),
312                        ));
313                    }
314                };
315                if eserder.said().unwrap_or_default() == said {
316                    // Event is a duplicate but not duplicitous
317                    // May have attached valid signature not yet logged
318                    let kever = self.kevers.get(&pre).ok_or_else(|| {
319                        KERIError::ValueError("Kever not found for known prefix".to_string())
320                    })?;
321
322                    // Get unique verified lists of sigers and indices from sigers
323                    let (verified_sigers, _) = verify_sigs(
324                        &serder.raw(),
325                        sigers,
326                        &eserder.verfers().unwrap_or_default(),
327                    )?;
328
329                    let berfers = eserder.berfers().unwrap_or_default();
330                    let (verified_wigers, _) = if let Some(w) = wigers {
331                        verify_sigs(&serder.raw(), w, &berfers)?
332                    } else {
333                        (vec![], vec![])
334                    };
335
336                    if !verified_sigers.is_empty() || !verified_wigers.is_empty() {
337                        // At least one verified sig or wig so log evt
338                        // This allows late arriving witness receipts or controller
339                        // signatures to be added to the database
340                        kever.log_event(
341                            &self.locals,
342                            serder.clone(),
343                            verified_sigers,
344                            if verified_wigers.is_empty() {
345                                None
346                            } else {
347                                Some(verified_wigers)
348                            },
349                            None,  // wits
350                            false, // not first seen
351                            None,  // seqner
352                            None,  // saider
353                            None,  // firner
354                            None,  // dater
355                            local,
356                        )?;
357                    }
358                } else {
359                    // Escrow likely duplicitous event
360                    self.escrow_ld_event(&serder, &sigers, local)?;
361
362                    let msg = format!(
363                        "Likely Duplicitous Event sn={} type={:?} SAID={}",
364                        serder.sn().unwrap_or_default(),
365                        serder.ilk(),
366                        serder.said().unwrap_or_default()
367                    );
368                    debug!("{}", msg);
369                    debug!("Duplicitous event body=\n{}\n", serder.pretty(None));
370
371                    return Err(KERIError::LikelyDuplicitousError(msg).into());
372                }
373            } else {
374                // rot, drt, or ixn, so sn matters
375                let kever = self.kevers.get(&pre).ok_or_else(|| {
376                    KERIError::ValueError("Kever not found for known prefix".to_string())
377                })?;
378
379                let sno = kever.sner().map(|s| s.num()).unwrap_or_default() + 1; // proper sn of new inorder event
380
381                if sn > sno as u64 {
382                    // sn later than sno so out of order escrow
383                    self.escrow_oo_event(
384                        &serder,
385                        &sigers,
386                        delseqner.as_ref(),
387                        delsaider.as_ref(),
388                        Some(&wigers.unwrap_or_default()),
389                        local,
390                    )?;
391
392                    let msg = format!(
393                        "Out-of-order event sn={} type={:?} SAID={}",
394                        serder.sn().unwrap_or_default(),
395                        serder.ilk(),
396                        serder.said().unwrap_or_default()
397                    );
398                    debug!("{}", msg);
399                    debug!("Out-of-order event body=\n{}\n", serder.pretty(None));
400
401                    return Err(KERIError::OutOfOrderError(msg).into());
402                } else if (sn == sno as u64) || // inorder event (ixn, rot, drt) or
403                    (ilk == Ilk::Rot && // superseding recovery rot or
404                        kever.last_est().map(|l| l.s < sn && sn <= sno as u64).unwrap_or(false)) ||
405                    (ilk == Ilk::Drt && // delegated superseding recovery drt
406                        kever.last_est().map(|l| l.s <= sn && sn <= sno as u64).unwrap_or(false))
407                {
408                    // Verify signatures etc and update state if valid
409                    let kever = self.kevers.get_mut(&pre).ok_or_else(|| {
410                        KERIError::ValueError("Kever not found for known prefix".to_string())
411                    })?;
412
413                    kever.update(
414                        &self.locals,
415                        serder.clone(),
416                        sigers.clone(),
417                        wigers.clone(),
418                        delseqner,
419                        delsaider,
420                        if self.cloned { firner } else { None },
421                        if self.cloned { dater } else { None },
422                        eager,
423                        local,
424                        self.check,
425                    )?;
426
427                    // At this point the non-inceptive event (rot, drt, or ixn)
428                    // given by serder together with its attachments has been
429                    // accepted as valid with finality.
430
431                    // Handle cues for receipt or notice
432                    if self.direct || self.lax || !self.locals.prefixes.contains(&pre) {
433                        // Create cue for receipt controller or watcher
434                        self.cues.push_back(Cue {
435                            kin: "receipt".to_string(),
436                            serder: serder.clone(),
437                        });
438                    } else if !self.direct {
439                        // Notice of new event
440                        self.cues.push_back(Cue {
441                            kin: "notice".to_string(),
442                            serder: serder.clone(),
443                        });
444                    }
445
446                    // Handle witness cues if needed
447                    if self.local && kever.locally_witnessed(&self.locals, None, Some(&serder)) {
448                        // TODO: need to cue task here kin = "witness" and process
449                        // cued witness and then combine with receipt above so only
450                        // one receipt is generated not two
451                        self.cues.push_back(Cue {
452                            kin: "witness".to_string(),
453                            serder: serder.clone(),
454                        });
455                    }
456                } else {
457                    // Maybe duplicitous
458                    // Check if duplicate of existing valid accepted event
459                    let key = sn_key(&pre, sn);
460                    let ddig_res = self.db.kels.get_last::<_, Vec<u8>>(&[&key])?;
461
462                    if let Some(ddig) = ddig_res {
463                        let ddig_str = String::from_utf8(ddig).map_err(|_| {
464                            KERIError::ValueError("Invalid UTF-8 in digest".to_string())
465                        })?;
466
467                        if ddig_str == said {
468                            // Event is a duplicate but not duplicitous
469                            let eserder = self.fetch_est_event(&pre, sn).unwrap();
470
471                            // May have attached valid signature not yet logged
472                            let kever = self.kevers.get(&pre).ok_or_else(|| {
473                                KERIError::ValueError(
474                                    "Kever not found for known prefix".to_string(),
475                                )
476                            })?;
477
478                            // Get unique verified lists of sigers and indices from sigers
479                            let (verified_sigers, _) = verify_sigs(
480                                &serder.raw(),
481                                sigers,
482                                &eserder.verfers().unwrap_or_default(),
483                            )?;
484
485                            let wits = self.fetch_witness_state(&pre, sn)?;
486                            let werfers: Vec<Verfer> = wits
487                                .iter()
488                                .map(|wit| Verfer::from_qb64(wit))
489                                .collect::<Result<Vec<Verfer>, _>>()?;
490
491                            let (verified_wigers, _) = if let Some(w) = wigers {
492                                verify_sigs(&serder.raw(), w, &werfers)?
493                            } else {
494                                (vec![], vec![])
495                            };
496
497                            if !verified_sigers.is_empty() || !verified_wigers.is_empty() {
498                                // At least one verified sig or wig so log evt
499                                kever.log_event(
500                                    &self.locals,
501                                    serder.clone(),
502                                    verified_sigers,
503                                    if verified_wigers.is_empty() {
504                                        None
505                                    } else {
506                                        Some(verified_wigers)
507                                    },
508                                    None,  // wits
509                                    false, // not first seen
510                                    None,  // seqner
511                                    None,  // saider
512                                    None,  // firner
513                                    None,  // dater
514                                    local,
515                                )?;
516                            }
517                        } else {
518                            // Escrow likely duplicitous event
519                            self.escrow_ld_event(&serder, &sigers, local)?;
520
521                            let msg = format!(
522                                "Likely Duplicitous Event sn={} type={:?} SAID={}",
523                                serder.sn().unwrap_or_default(),
524                                serder.ilk(),
525                                serder.said().unwrap_or_default()
526                            );
527                            debug!("{}", msg);
528                            debug!("Duplicitous event body=\n{}\n", serder.pretty(None));
529
530                            return Err(KERIError::LikelyDuplicitousError(msg).into());
531                        }
532                    } else {
533                        // No existing event found, escrow as likely duplicitous
534                        self.escrow_ld_event(&serder, &sigers, local)?;
535
536                        let msg = format!(
537                            "Likely Duplicitous Event (no existing event) sn={} type={:?} SAID={}",
538                            serder.sn().unwrap_or_default(),
539                            serder.ilk(),
540                            serder.said().unwrap_or_default()
541                        );
542                        debug!("{}", msg);
543
544                        return Err(KERIError::LikelyDuplicitousError(msg).into());
545                    }
546                }
547            }
548        }
549
550        Ok(())
551    }
552
553    // These methods would be implemented as helper functions
554
555    /// Fetch the latest establishment event for a prefix at a sequence number
556    fn fetch_est_event(&self, pre: &str, sn: u64) -> Option<SerderKERI> {
557        let mut sn = sn;
558        loop {
559            let key = sn_key(&pre, sn);
560            match self.db.kels.get_last::<_, Vec<u8>>(&[&key]) {
561                Ok(dig_bytes) => {
562                    let ldig = match dig_bytes {
563                        Some(dig_bytes) => match String::from_utf8(dig_bytes) {
564                            Ok(ldig) => ldig,
565                            Err(_) => return None,
566                        },
567                        None => return None,
568                    };
569
570                    let dgkey = dg_key(pre, ldig);
571                    let raw = match self.db.evts.get::<_, Vec<u8>>(&[&dgkey]) {
572                        Ok(r) => r.unwrap(),
573                        Err(_) => return None,
574                    };
575
576                    let serder = SerderKERI::from_raw(&raw, None).unwrap();
577                    let ilk = serder.ilk();
578                    if ilk == Some(Ilk::Icp)
579                        || ilk == Some(Ilk::Dip)
580                        || ilk == Some(Ilk::Rot)
581                        || ilk == Some(Ilk::Drt)
582                    {
583                        return Some(serder);
584                    }
585
586                    sn = serder.sn().unwrap() - 1;
587                }
588                Err(_) => return None,
589            }
590        }
591    }
592
593    /// Fetch the witness state for a prefix at a sequence number
594    /// Witness list of `pre` in effect at `sn`: that of the last establishment
595    /// event at or before `sn` (as recorded in `.wits` by `Kever::log_event`).
596    fn fetch_witness_state(&self, pre: &str, sn: u64) -> Result<Vec<String>, KERIError> {
597        for s in (0..=sn).rev() {
598            let Some(dig) = self.db.get_ke_last(&crate::keri::db::dbing::keys::sn_key(pre, s))? else {
599                continue;
600            };
601            let dgkey = crate::keri::db::dbing::keys::dg_key(pre, dig.as_bytes());
602            let Some(raw) = self.db.get_evt(&dgkey)? else {
603                continue;
604            };
605            let serder = SerderKERI::from_raw(&raw, None)
606                .map_err(|e| KERIError::ValidationError(format!("bad event in KEL: {}", e)))?;
607            if matches!(
608                serder.ilk(),
609                Some(Ilk::Icp) | Some(Ilk::Rot) | Some(Ilk::Dip) | Some(Ilk::Drt)
610            ) {
611                let wits: Vec<Vec<u8>> = self
612                    .db
613                    .wits
614                    .get(&[&dgkey])
615                    .map_err(|e| KERIError::DatabaseError(format!("wits: {}", e)))?;
616                return Ok(wits
617                    .into_iter()
618                    .map(|w| String::from_utf8_lossy(&w).to_string())
619                    .collect());
620            }
621        }
622        Ok(Vec::new())
623    }
624
625    /// Run every escrow that is implemented, once each: out of order, partial
626    /// signatures, unverified witness and non-transferable receipts, partial
627    /// witnesses, then likely duplicitous. Out of order runs first so an event
628    /// whose prior event just arrived moves on to the signature escrows in the
629    /// same pass; unverified receipts run before partial witnesses so receipts
630    /// that arrived ahead of their event can complete it in the same pass.
631    /// keripy's order differs only in running partial signatures after partial
632    /// witnesses (keripy: core/eventing.py Kevery.processEscrows).
633    pub fn process_escrows(&mut self) {
634        if let Err(e) = self.process_escrow_out_of_orders() {
635            debug!("Kevery: out-of-order escrow pass failed: {}", e);
636        }
637        if let Err(e) = self.process_escrow_partial_sigs() {
638            debug!("Kevery: partial signature escrow pass failed: {}", e);
639        }
640        if let Err(e) = self.process_escrow_unver_witness() {
641            debug!("Kevery: unverified witness receipt escrow pass failed: {}", e);
642        }
643        if let Err(e) = self.process_escrow_unver_nontrans() {
644            debug!("Kevery: unverified receipt escrow pass failed: {}", e);
645        }
646        if let Err(e) = self.process_escrow_partial_wigs() {
647            debug!("Kevery: partial witness escrow pass failed: {}", e);
648        }
649        if let Err(e) = self.process_escrow_duplicitous() {
650            debug!("Kevery: likely duplicitous escrow pass failed: {}", e);
651        }
652    }
653
654    /// Retry events escrowed for missing signatures (keripy
655    /// `processEscrowPartialSigs`). Each escrowed event is reprocessed with
656    /// every signature stored for it so far. It stays escrowed while still
657    /// short of signatures, and leaves the escrow once accepted, stale (older
658    /// than [`Self::TIMEOUT_PSE`]) or invalid for any other reason. An event
659    /// that becomes fully signed but is short of witness signatures moves to
660    /// the partially witnessed escrow.
661    ///
662    /// Returns the number of events accepted.
663    pub fn process_escrow_partial_sigs(&mut self) -> Result<usize, KERIError> {
664        self.process_event_escrow(EventEscrow::PartialSigs)
665    }
666
667    /// Retry events escrowed for missing witness signatures (keripy
668    /// `processEscrowPartialWigs`), the same way as
669    /// [`Self::process_escrow_partial_sigs`] with [`Self::TIMEOUT_PWE`].
670    pub fn process_escrow_partial_wigs(&mut self) -> Result<usize, KERIError> {
671        self.process_event_escrow(EventEscrow::PartialWigs)
672    }
673
674    /// Retry events escrowed because their prior event wasn't accepted yet
675    /// (keripy `processEscrowOutOfOrders`). An entry stays while its prior
676    /// event is still missing, and leaves once accepted, stale (older than
677    /// [`Self::TIMEOUT_OOE`]) or invalid. One that now lacks only signatures
678    /// or witness signatures moves to that escrow.
679    pub fn process_escrow_out_of_orders(&mut self) -> Result<usize, KERIError> {
680        self.process_event_escrow(EventEscrow::OutOfOrder)
681    }
682
683    /// Retry events escrowed as likely duplicitous (keripy
684    /// `processEscrowDuplicitous`). An entry stays while it still conflicts
685    /// with the accepted event at its sn, which in practice is until it is
686    /// older than [`Self::TIMEOUT_LDE`]; until then it is kept, with its
687    /// signatures, as evidence of the conflicting event. It leaves early only
688    /// if it becomes valid or turns out invalid for another reason.
689    pub fn process_escrow_duplicitous(&mut self) -> Result<usize, KERIError> {
690        self.process_event_escrow(EventEscrow::LikelyDuplicitous)
691    }
692
693    fn process_event_escrow(&mut self, kind: EventEscrow) -> Result<usize, KERIError> {
694        let db = self.db.clone();
695        let index = match kind {
696            EventEscrow::PartialSigs => &db.pses,
697            EventEscrow::PartialWigs => &db.pwes,
698            EventEscrow::OutOfOrder => &db.ooes,
699            EventEscrow::LikelyDuplicitous => &db.ldes,
700        };
701        let empty: &[&[u8]] = &[b""];
702        let items = index
703            .get_item_iter(empty, false)
704            .map_err(|e| KERIError::DatabaseError(format!("{:?} escrow: {}", kind, e)))?;
705        let mut accepted = 0;
706        for (keys, edig) in items {
707            let snkey = join_keys(&keys);
708            let pre = String::from_utf8_lossy(&keys[0]).to_string();
709            let dig = String::from_utf8_lossy(&edig).to_string();
710            match self.unescrow_event(kind, &pre, &dig) {
711                Ok(()) => {
712                    accepted += 1;
713                    debug!("Kevery: unescrowed {:?} event {} {}", kind, pre, dig);
714                }
715                Err(e) if kind.still_waiting(&e) => continue,
716                Err(e) => debug!("Kevery: dropping {:?} escrow {} {}: {}", kind, pre, dig, e),
717            }
718            index
719                .rem(&[snkey.as_bytes()], Some(&edig))
720                .map_err(|e| KERIError::DatabaseError(format!("{:?} escrow: {}", kind, e)))?;
721        }
722        Ok(accepted)
723    }
724
725    fn unescrow_event(&mut self, kind: EventEscrow, pre: &str, dig: &str) -> Result<(), KERIError> {
726        let dg_keys = [pre, dig];
727        let esr = self
728            .db
729            .esrs
730            .get(&dg_keys)?
731            .ok_or_else(|| KERIError::ValidationError(format!("{:?}: missing event source at {}", kind, dig)))?;
732
733        self.check_escrow_age(pre, dig, kind.timeout())?;
734
735        let raw = self
736            .db
737            .get_evt(&dg_key(pre, dig.as_bytes()))?
738            .ok_or_else(|| KERIError::ValidationError(format!("{:?}: missing event at {}", kind, dig)))?;
739        let serder = SerderKERI::from_raw(&raw, None)
740            .map_err(|e| KERIError::ValidationError(format!("{:?}: bad event at {}: {}", kind, dig, e)))?;
741
742        let sigers = load_sigers(self.db.sigs.get(&dg_keys)?)?;
743        if sigers.is_empty() {
744            return Err(KERIError::ValidationError(format!("{:?}: missing signatures at {}", kind, dig)));
745        }
746        let wigers = load_sigers(self.db.wigs.get(&dg_keys)?)?;
747
748        self.process_event(
749            serder,
750            sigers,
751            (!wigers.is_empty()).then_some(wigers),
752            None,
753            None,
754            None,
755            None,
756            Some(true),
757            Some(esr.local),
758        )
759    }
760
761    /// Fail when the escrow entry for (pre, dig) has no timestamp or is older
762    /// than `timeout` seconds.
763    fn check_escrow_age(&self, pre: &str, dig: &str, timeout: u64) -> Result<(), KERIError> {
764        let dts: Vec<Vec<u8>> = self.db.dtss.get(&[pre, dig])?;
765        let dte = dts
766            .first()
767            .and_then(|d| std::str::from_utf8(d).ok())
768            .and_then(|d| chrono::DateTime::parse_from_rfc3339(d).ok())
769            .ok_or_else(|| KERIError::ValidationError(format!("escrow missing datetime at {}", dig)))?;
770        let age = chrono::Utc::now().signed_duration_since(dte);
771        if age > chrono::Duration::seconds(timeout as i64) {
772            return Err(KERIError::ValidationError(format!("stale escrow at {}", dig)));
773        }
774        Ok(())
775    }
776
777    /// Retry non-transferable receipts whose event was not yet known (keripy
778    /// `processEscrowUnverNonTrans`). A receipt for an event waiting in the
779    /// partially witnessed escrow adds its witness signature there; one for an
780    /// accepted event is stored as a wig or receipt couple.
781    pub fn process_escrow_unver_nontrans(&mut self) -> Result<usize, KERIError> {
782        let db = self.db.clone();
783        let empty: &[&[u8]] = &[b""];
784        let items = db
785            .ures
786            .get_item_iter(empty, false)
787            .map_err(|e| KERIError::DatabaseError(format!("ures: {}", e)))?;
788        let mut done = 0;
789        for (keys, val) in items {
790            let snkey = join_keys(&keys);
791            let pre = String::from_utf8_lossy(&keys[0]).to_string();
792            match self.unescrow_receipt(&pre, &keys, &val) {
793                Ok(()) => done += 1,
794                Err(KERIError::UnverifiedReceiptError(_)) => continue,
795                Err(e) => debug!("Kevery: dropping unverified receipt escrow {}: {}", snkey, e),
796            }
797            db.ures
798                .rem(&[snkey.as_bytes()], Some(&val))
799                .map_err(|e| KERIError::DatabaseError(format!("ures: {}", e)))?;
800        }
801        Ok(done)
802    }
803
804    fn unescrow_receipt(&mut self, pre: &str, keys: &[Vec<u8>], val: &[u8]) -> Result<(), KERIError> {
805        let sn = escrow_sn(keys)?;
806        let val = String::from_utf8_lossy(val).to_string();
807        let mut parts = val.split('.');
808        let (Some(said), Some(rpre), Some(sig), None) = (parts.next(), parts.next(), parts.next(), parts.next())
809        else {
810            return Err(KERIError::ValidationError(format!("bad unverified receipt escrow value {}", val)));
811        };
812        self.check_escrow_age(pre, said, Self::TIMEOUT_URE)?;
813        let verfer = Verfer::from_qb64(rpre)?;
814        let cigar = Cigar::from_qb64(sig, Some(verfer.clone()))?;
815
816        if self.find_unver_in_pwes(pre, sn, said, WitnessSig::Couple(&cigar))? {
817            return Ok(());
818        }
819        let Some(ldig) = self.db.get_ke_last(&sn_key(pre, sn))? else {
820            return Err(KERIError::UnverifiedReceiptError(format!(
821                "receipted event {} sn {} not yet seen",
822                pre, sn
823            )));
824        };
825        if ldig != said {
826            return Err(KERIError::ValidationError(format!("stale receipt for {} at sn {}", pre, sn)));
827        }
828        let raw = self
829            .db
830            .get_evt(&dg_key(pre, ldig.as_bytes()))?
831            .ok_or_else(|| KERIError::ValidationError(format!("missing receipted event {}", ldig)))?;
832        if !verfer.verify(&cigar.raw(), &raw)? {
833            return Err(KERIError::ValidationError(format!("bad escrowed receipt sig from {}", rpre)));
834        }
835        let wits = self.fetch_witness_state(pre, sn)?;
836        let dgk = [pre, ldig.as_str()];
837        if let Some(index) = wits.iter().position(|w| w == rpre) {
838            let wiger = cigar_to_wiger(&cigar, index as u32)?;
839            self.db.wigs.add(&dgk, &wiger.qb64().as_bytes())?;
840        } else {
841            let couple = [rpre.as_bytes(), cigar.qb64().as_bytes()].concat();
842            self.db.rcts.add(&dgk, &couple)?;
843        }
844        Ok(())
845    }
846
847    /// Retry indexed witness receipts whose event was not yet known (keripy
848    /// `processEscrowUnverWitness`). They can only complete an event waiting in
849    /// the partially witnessed escrow.
850    pub fn process_escrow_unver_witness(&mut self) -> Result<usize, KERIError> {
851        let db = self.db.clone();
852        let empty: &[&[u8]] = &[b""];
853        let items = db
854            .uwes
855            .get_item_iter(empty, false)
856            .map_err(|e| KERIError::DatabaseError(format!("uwes: {}", e)))?;
857        let mut done = 0;
858        for (keys, val) in items {
859            let snkey = join_keys(&keys);
860            let pre = String::from_utf8_lossy(&keys[0]).to_string();
861            let result = (|| {
862                let sn = escrow_sn(&keys)?;
863                let v = String::from_utf8_lossy(&val).to_string();
864                let (said, wig) = v
865                    .split_once('.')
866                    .ok_or_else(|| KERIError::ValidationError(format!("bad witness receipt escrow value {}", v)))?;
867                self.check_escrow_age(&pre, said, Self::TIMEOUT_UWE)?;
868                let wiger = Siger::from_qb64b(&mut wig.as_bytes().to_vec(), None)?;
869                if self.find_unver_in_pwes(&pre, sn, said, WitnessSig::Indexed(&wiger))? {
870                    Ok(())
871                } else {
872                    Err(KERIError::UnverifiedWitnessReceiptError(format!(
873                        "witness receipted event {} sn {} not yet seen",
874                        pre, sn
875                    )))
876                }
877            })();
878            match result {
879                Ok(()) => done += 1,
880                Err(KERIError::UnverifiedWitnessReceiptError(_)) => continue,
881                Err(e) => debug!("Kevery: dropping witness receipt escrow {}: {}", snkey, e),
882            }
883            db.uwes
884                .rem(&[snkey.as_bytes()], Some(&val))
885                .map_err(|e| KERIError::DatabaseError(format!("uwes: {}", e)))?;
886        }
887        Ok(done)
888    }
889
890    /// Find event `said` at (pre, sn) in the partially witnessed escrow and, if
891    /// the receipt is from one of its witnesses, verify it and add it to its
892    /// wigs (keripy `_processEscrowFindUnver`). The partially witnessed escrow
893    /// then accepts the event once enough wigs are stored.
894    fn find_unver_in_pwes(&self, pre: &str, sn: u64, said: &str, sig: WitnessSig) -> Result<bool, KERIError> {
895        let digs: Vec<Vec<u8>> = self
896            .db
897            .pwes
898            .get(&[sn_key(pre, sn)])
899            .map_err(|e| KERIError::DatabaseError(format!("pwes: {}", e)))?;
900        if !digs.iter().any(|d| d.as_slice() == said.as_bytes()) {
901            return Ok(false);
902        }
903        let raw = self
904            .db
905            .get_evt(&dg_key(pre, said.as_bytes()))?
906            .ok_or_else(|| KERIError::ValidationError(format!("missing escrowed event {}", said)))?;
907        let serder = SerderKERI::from_raw(&raw, None)?;
908        let wits = self.escrowed_event_wits(&serder)?;
909
910        let wiger = match sig {
911            WitnessSig::Couple(cigar) => {
912                let rpre = cigar.verfer().map(|v| v.qb64()).unwrap_or_default();
913                let Some(index) = wits.iter().position(|w| *w == rpre) else {
914                    return Ok(false); // not a witness of this event
915                };
916                cigar_to_wiger(cigar, index as u32)?
917            }
918            WitnessSig::Indexed(wiger) => {
919                let index = wiger.index() as usize;
920                if index >= wits.len() {
921                    return Err(KERIError::ValidationError(format!(
922                        "bad witness receipt index {} for {} sn {}",
923                        index, pre, sn
924                    )));
925                }
926                wiger.clone()
927            }
928        };
929        let verfer = Verfer::from_qb64(&wits[wiger.index() as usize])?;
930        if !verfer.verify(&wiger.raw(), &raw)? {
931            return Err(KERIError::ValidationError(format!(
932                "bad escrowed witness receipt sig for {} sn {}",
933                pre, sn
934            )));
935        }
936        self.db.wigs.add(&[pre, said], &wiger.qb64().as_bytes())?;
937        Ok(true)
938    }
939
940    /// Witness list in force for an escrowed (not yet accepted) event.
941    fn escrowed_event_wits(&self, serder: &SerderKERI) -> Result<Vec<String>, KERIError> {
942        match serder.ilk() {
943            Some(Ilk::Icp) | Some(Ilk::Dip) => Ok(serder.backs().unwrap_or_default()),
944            _ => {
945                let pre = serder.pre().unwrap_or_default();
946                let kever = self
947                    .kevers
948                    .get(&pre)
949                    .ok_or_else(|| KERIError::ValidationError(format!("no key state for {}", pre)))?;
950                let mut wits = kever.wits();
951                if matches!(serder.ilk(), Some(Ilk::Rot) | Some(Ilk::Drt)) {
952                    let cuts = serder.cuts().unwrap_or_default();
953                    wits.retain(|w| !cuts.contains(w));
954                    for add in serder.adds().unwrap_or_default() {
955                        if !wits.contains(&add) {
956                            wits.push(add);
957                        }
958                    }
959                }
960                Ok(wits)
961            }
962        }
963    }
964
965    /// Escrow an event whose prior event isn't accepted yet, so its key state
966    /// is unknown (keripy: core/eventing.py Kevery.escrowOOEvent). Retried by
967    /// [`Self::process_escrow_out_of_orders`]. The delegation source seal is
968    /// not stored yet (keripy keeps it in `udes`).
969    fn escrow_oo_event(
970        &self,
971        serder: &SerderKERI,
972        sigers: &[Siger],
973        _seqner: Option<&Seqner>,
974        _saider: Option<&Saider>,
975        wigers: Option<&[Siger]>,
976        local: bool,
977    ) -> Result<(), KERIError> {
978        escrow_event(&self.db, serder, sigers, wigers, local, &self.db.ooes)?;
979        debug!("Kevery: escrowed out of order event {}", serder.said().unwrap_or_default());
980        Ok(())
981    }
982
983    /// Escrow an event that conflicts with one already accepted at its sn: a
984    /// second inception, or a different event at an sn already in the KEL
985    /// (keripy: core/eventing.py Kevery.escrowLDEvent). Retried by
986    /// [`Self::process_escrow_duplicitous`]. Witness signatures aren't kept,
987    /// as in keripy. keripy records every such event as local (it doesn't pass
988    /// `local`); libkeri records the real source.
989    fn escrow_ld_event(&self, serder: &SerderKERI, sigers: &[Siger], local: bool) -> Result<(), KERIError> {
990        escrow_event(&self.db, serder, sigers, None, local, &self.db.ldes)?;
991        debug!("Kevery: escrowed likely duplicitous event {}", serder.said().unwrap_or_default());
992        Ok(())
993    }
994
995    /// Process one witness receipt serder with attached witness wigers (indexed signatures)
996    ///
997    /// # Parameters
998    /// * `serder` - Instance of serialized receipt message (not receipted event)
999    /// * `wigers` - Instances that with witness indexed signatures. Index is offset into
1000    ///             witness list of latest establishment event for receipted event.
1001    ///             Signature uses key pair derived from nontrans witness prefix in
1002    ///             associated witness list.
1003    /// * `local` - True means local (protected) event source.
1004    ///            False means remote (unprotected).
1005    ///            None means use default .local.
1006    ///
1007    /// Receipt dict labels
1008    /// * vs  - version string
1009    /// * pre - qb64 prefix
1010    /// * sn  - hex string sequence number
1011    /// * ilk - rct
1012    /// * dig - qb64 digest of receipted event
1013    pub fn process_receipt_witness(
1014        &self,
1015        serder: SerderKERI,
1016        wigers: Vec<Siger>,
1017        local: Option<bool>,
1018    ) -> Result<(), KERIError> {
1019        // Use provided local or default to self.local, and force it to be a boolean
1020        let local = match local {
1021            Some(val) => val,
1022            None => self.local,
1023        };
1024
1025        // Fetch pre, dig to process
1026        let ked = serder.ked();
1027        let pre = serder
1028            .pre()
1029            .ok_or_else(|| KERIError::ValueError("Missing pre in receipt".to_string()))?;
1030        let sn = serder
1031            .sn()
1032            .ok_or_else(|| KERIError::ValueError("Missing sn in receipt".to_string()))?;
1033
1034        // Only accept receipt if for last seen version of event at sn
1035        let sn_key = sn_key(&pre, sn);
1036
1037        // Retrieve dig of last event at sn
1038        let ldig = match self.db.kels.get_last::<_, Vec<u8>>(&[&sn_key])? {
1039            Some(dig_bytes) => String::from_utf8(dig_bytes)
1040                .map_err(|_| KERIError::ValueError("Invalid UTF-8 in digest".to_string()))?,
1041            None => {
1042                // No events to be receipted yet at that sn, so escrow
1043                // Get digest from receipt message not receipted event
1044                let receipt_dig = ked
1045                    .get("d")
1046                    .ok_or_else(|| {
1047                        KERIError::ValueError("Missing 'd' field in receipt".to_string())
1048                    })?
1049                    .as_str()
1050                    .ok_or_else(|| {
1051                        KERIError::ValueError("'d' field is not a string".to_string())
1052                    })?;
1053
1054                self.escrow_uw_receipt(&serder, &wigers, receipt_dig)?;
1055
1056                let msg = format!(
1057                    "Unverified witness receipt={}",
1058                    serder.said().unwrap_or_default()
1059                );
1060                info!("{}", msg);
1061                debug!("Event=\n{}\n", serder.pretty(None));
1062
1063                return Err(KERIError::UnverifiedWitnessReceiptError(msg).into());
1064            }
1065        };
1066
1067        // Verify the receipt is for the last event seen at sn (keripy compareSaid(ldig))
1068        if ked
1069            .get("d")
1070            .and_then(|d| d.as_str())
1071            .ok_or_else(|| KERIError::ValueError("Missing 'd' field in receipt".to_string()))?
1072            != ldig
1073        {
1074            // Stale receipt at sn, discard
1075            let msg = format!(
1076                "Stale receipt at sn = {:?} for rct = {:?}",
1077                ked.get("s").unwrap(),
1078                serder.said().unwrap_or_default()
1079            );
1080            info!("{}", msg);
1081            debug!("Stale receipt event body=\n{}\n", serder.pretty(None));
1082
1083            return Err(KERIError::ValueError(msg).into());
1084        }
1085
1086        // Retrieve receipted event at dig
1087        let dg_key = dg_key(&pre, &ldig);
1088        let raw =
1089            self.db.evts.get::<_, Vec<u8>>(&[&dg_key])?.ok_or_else(|| {
1090                KERIError::ValueError(format!("Event not found for dig={}", ldig))
1091            })?;
1092
1093        let lserder = SerderKERI::from_raw(&raw, None)?;
1094
1095        // Process each couple, verify sig and write to db
1096        let wits = self.fetch_witness_state(&pre, sn)?;
1097
1098        for wiger in wigers {
1099            // Assign verfers from witness list
1100            if wiger.index() >= wits.len() as u32 {
1101                continue; // Skip invalid witness index
1102            }
1103
1104            let wiger_verfer = Verfer::from_qb64(&wits[wiger.index() as usize])?;
1105
1106            // Skip transferable verfers
1107            if wiger_verfer.is_transferable() {
1108                continue; // Skip invalid witness prefix
1109            }
1110
1111            // Handle own witness scenarios
1112            if !self.lax && self.locals.prefixes.contains(&wiger_verfer.qb64()) {
1113                // Own is witness
1114                if self.locals.prefixes.contains(&pre) {
1115                    // Skip own receiptor of own event - sign own events not receipt them
1116                    info!(
1117                        "Kevery: skipped own receipt attachment on own event receipt={}",
1118                        serder.said().unwrap_or_default()
1119                    );
1120                    debug!("Event=\n{}\n", serder.pretty(None));
1121                    continue;
1122                }
1123
1124                if !local {
1125                    // Skip own receipt on other event when non-local source
1126                    debug!(
1127                        "Kevery: skipped own receipt attachment on nonlocal event receipt={}",
1128                        serder.said().unwrap_or_default()
1129                    );
1130                    debug!("Event=\n{}\n", serder.pretty(None));
1131                    continue;
1132                }
1133            }
1134
1135            // Verify signature
1136            if wiger_verfer.verify(&wiger.raw(), &lserder.raw())? {
1137                // Write receipt indexed sig to database
1138                self.db.wigs.add(&[&dg_key], &wiger.qb64().as_bytes())?;
1139            }
1140        }
1141
1142        Ok(())
1143    }
1144
1145    pub fn process_attached_receipt_couples(
1146        &mut self,
1147        _serder: SerderKERI,
1148        _firner: Option<Seqner>,
1149        _cigars: Vec<Cigar>,
1150    ) -> Result<(), KERIError> {
1151        // todo!("Implement process_attached_receipt_couples method")
1152        Ok(())
1153    }
1154
1155    pub fn process_attached_receipt_quadruples(
1156        &mut self,
1157        _serder: SerderKERI,
1158        _trqs: Vec<Trqs>,
1159        _firner: Option<Seqner>,
1160        _local: Option<bool>,
1161    ) -> Result<(), KERIError> {
1162        // todo!("Implement process_attached_receipt_quadruples method")
1163        Ok(())
1164    }
1165
1166    /// Process one receipt serder with attached cigars
1167    /// may or may not be a witness receipt. If prefix matches witness then
1168    /// promote to indexed witness signature and store appropriately. Otherwise
1169    /// signature is nontrans nonwitness endorser (watcher etc)
1170    ///
1171    /// # Parameters
1172    /// * `serder` - Receipt instance of serialized receipt message
1173    /// * `cigars` - Instances that contain receipt couple signature in .raw and public key in .verfer
1174    /// * `local` - True means local (protected) event source.
1175    ///            False means remote (unprotected).
1176    ///            None means use default .local.
1177    ///
1178    /// Receipt dict labels
1179    /// * vs  - version string
1180    /// * pre - qb64 prefix
1181    /// * sn  - hex string sequence number
1182    /// * ilk - rct
1183    /// * dig - qb64 digest of receipted event
1184    pub fn process_receipt(
1185        &mut self,
1186        serder: SerderKERI,
1187        cigars: Vec<Cigar>,
1188        local: Option<bool>,
1189    ) -> Result<(), KERIError> {
1190        // Use provided local or default to self.local, and force it to be a boolean
1191        let local = match local {
1192            Some(val) => val,
1193            None => self.local,
1194        };
1195
1196        // Fetch pre, dig to process
1197        let ked = serder.ked();
1198        let pre = serder
1199            .pre()
1200            .ok_or_else(|| KERIError::ValueError("Missing pre in receipt".to_string()))?;
1201        let sn = serder
1202            .sn()
1203            .ok_or_else(|| KERIError::ValueError("Missing sn in receipt".to_string()))?;
1204
1205        // Only accept receipt if for last seen version of event at sn
1206        let sn_key = sn_key(&pre, sn);
1207
1208        // Retrieve dig of last event at sn
1209        let ldig = if let Some(ldig) = self.db.get_ke_last(&sn_key)? {
1210            ldig
1211        } else {
1212            // No events to be receipted yet at that sn, so escrow
1213            // Get digest from receipt message not receipted event
1214            let receipt_dig = ked
1215                .get("d")
1216                .ok_or_else(|| KERIError::ValueError("Missing 'd' field in receipt".to_string()))?
1217                .as_str()
1218                .ok_or_else(|| KERIError::ValueError("'d' field is not a string".to_string()))?;
1219
1220            self.escrow_u_receipt(&serder, &cigars, receipt_dig)?;
1221
1222            let msg = format!("Unverified receipt = {}", serder.said().unwrap_or_default());
1223            info!("{}", msg);
1224            debug!("Event=\n{}\n", serder.pretty(None));
1225
1226            return Err(KERIError::UnverifiedReceiptError(msg).into());
1227        };
1228
1229        // Verify digs match
1230        // Verify the receipt is for the last event seen at sn (keripy compareSaid(ldig))
1231        if ked
1232            .get("d")
1233            .and_then(|d| d.as_str())
1234            .ok_or_else(|| KERIError::ValueError("Missing 'd' field in receipt".to_string()))?
1235            != ldig
1236        {
1237            // Stale receipt at sn, discard
1238            let msg = format!(
1239                "Stale receipt at sn = {:?} for rct = {:?}",
1240                ked.get("s").unwrap_or(&SadValue::String("".to_string())),
1241                serder.said().unwrap_or_default()
1242            );
1243
1244            return Err(KERIError::ValueError(msg).into());
1245        }
1246
1247        // Retrieve receipted event at dig
1248        let dg_key = dg_key(&pre, ldig.clone());
1249        let raw =
1250            self.db.evts.get::<_, Vec<u8>>(&[&dg_key])?.ok_or_else(|| {
1251                KERIError::ValueError(format!("Event not found for dig={:?}", ldig))
1252            })?;
1253
1254        let lserder = SerderKERI::from_raw(&raw, None)?;
1255
1256        // Process each cigar, verify sig and write to db
1257        for cigar in cigars {
1258            // Skip transferable verfers
1259            if cigar.verfer.clone().unwrap().is_transferable() {
1260                continue;
1261            }
1262
1263            // Handle own receiptor scenarios
1264            if !self.lax
1265                && self
1266                    .locals
1267                    .prefixes
1268                    .contains(&cigar.verfer.clone().unwrap().qb64())
1269            {
1270                // Own is receiptor
1271                if self.locals.prefixes.contains(&pre) {
1272                    // Skip own receipter of own event - sign own events not receipt them
1273                    debug!(
1274                        "Kevery process: skipped own receipt attachment on own event receipt={}",
1275                        serder.said().unwrap_or_default()
1276                    );
1277                    debug!("Event=\n{}\n", serder.pretty(None));
1278                    continue;
1279                }
1280
1281                if !local {
1282                    // Skip own receipt on other event when not local
1283                    debug!("Kevery process: skipped own receipt attachment on nonlocal event receipt={}",
1284                          serder.said().unwrap_or_default());
1285                    debug!("Event=\n{}\n", serder.pretty(None));
1286                    continue;
1287                }
1288            }
1289
1290            // Verify signature
1291            if cigar
1292                .verfer
1293                .clone()
1294                .unwrap()
1295                .verify(&cigar.raw(), &lserder.raw())?
1296            {
1297                // Get witness list for the event
1298                let wits = self.fetch_witness_state(&pre, sn)?;
1299                let rpre = cigar.verfer.clone().unwrap().qb64(); // prefix of receiptor
1300
1301                if wits.contains(&rpre) {
1302                    // It's a witness receipt, write in .wigs
1303                    let index = wits.iter().position(|w| w == &rpre).ok_or_else(|| {
1304                        KERIError::ValueError("Witness not found in witness list".to_string())
1305                    })?;
1306
1307                    // Witness indexed signature (keripy: Siger(raw=cigar.raw, index=...))
1308                    let wiger = cigar_to_wiger(&cigar, index as u32)?;
1309
1310                    // Write to db
1311                    self.db.wigs.add(&[&dg_key], &wiger.qb64().as_bytes())?;
1312                } else {
1313                    // Not witness receipt, write receipt couple to database .rcts
1314                    let couple = [
1315                        cigar.verfer.clone().unwrap().qb64().as_bytes(),
1316                        cigar.qb64().as_bytes(),
1317                    ]
1318                    .concat();
1319                    self.db.rcts.add(&[&dg_key], &couple)?;
1320                }
1321            }
1322        }
1323
1324        Ok(())
1325    }
1326
1327    /// Escrow unverified receipt (keripy `escrowUReceipt`): one entry per
1328    /// receipt couple, keyed snKey(pre, sn), valued `said.rpre.cigar`.
1329    fn escrow_u_receipt(
1330        &self,
1331        serder: &SerderKERI,
1332        cigars: &[Cigar],
1333        said: &str,
1334    ) -> Result<(), KERIError> {
1335        let pre = serder.pre().ok_or_else(|| KERIError::ValueError("receipt has no prefix".into()))?;
1336        let sn = serder.sn().ok_or_else(|| KERIError::ValueError("receipt has no sn".into()))?;
1337        self.put_escrow_time(&pre, said)?;
1338        for cigar in cigars {
1339            let Some(verfer) = cigar.verfer() else { continue };
1340            let val = format!("{}.{}.{}", said, verfer.qb64(), cigar.qb64());
1341            self.db
1342                .ures
1343                .add(&[sn_key(&pre, sn)], &val.into_bytes())
1344                .map_err(|e| KERIError::DatabaseError(format!("ures: {}", e)))?;
1345        }
1346        debug!("Kevery: escrowed unverified receipt for {} sn {} said {}", pre, sn, said);
1347        Ok(())
1348    }
1349
1350    /// Escrow unverified witness receipt (keripy `escrowUWReceipt`): one entry
1351    /// per indexed witness signature, keyed snKey(pre, sn), valued `said.wig`.
1352    fn escrow_uw_receipt(
1353        &self,
1354        serder: &SerderKERI,
1355        wigers: &[Siger],
1356        said: &str,
1357    ) -> Result<(), KERIError> {
1358        let pre = serder.pre().ok_or_else(|| KERIError::ValueError("receipt has no prefix".into()))?;
1359        let sn = serder.sn().ok_or_else(|| KERIError::ValueError("receipt has no sn".into()))?;
1360        self.put_escrow_time(&pre, said)?;
1361        for wiger in wigers {
1362            let val = format!("{}.{}", said, wiger.qb64());
1363            self.db
1364                .uwes
1365                .add(&[sn_key(&pre, sn)], &val.into_bytes())
1366                .map_err(|e| KERIError::DatabaseError(format!("uwes: {}", e)))?;
1367        }
1368        debug!("Kevery: escrowed unverified witness receipt for {} sn {} said {}", pre, sn, said);
1369        Ok(())
1370    }
1371
1372    /// Record the first escrow time for (pre, said); later calls keep it.
1373    fn put_escrow_time(&self, pre: &str, said: &str) -> Result<(), KERIError> {
1374        let existing: Vec<Vec<u8>> = self.db.dtss.get(&[pre, said])?;
1375        if existing.is_empty() {
1376            self.db.dtss.add(&[pre, said], &chrono::Utc::now().to_rfc3339().into_bytes())?;
1377        }
1378        Ok(())
1379    }
1380
1381    /// Process query mode replay message for collective or single element query.
1382    /// Assume promiscuous mode for now.
1383    ///
1384    /// # Parameters
1385    /// * `serder` - Query message serder
1386    /// * `source` - Identifier prefix of querier (optional)
1387    /// * `sigers` - List of Siger instances of attached controller indexed sigs (optional)
1388    /// * `cigars` - List of Cigar instances of attached non-trans sigs (optional)
1389    pub fn process_query(
1390        &mut self,
1391        serder: SerderKERI,
1392        source: Option<Prefixer>,
1393        sigers: Option<Vec<Siger>>,
1394        cigars: Option<Vec<Cigar>>,
1395    ) -> Result<(), KERIError> {
1396        let ked = serder.ked();
1397
1398        let ilk = ked
1399            .get("t")
1400            .ok_or_else(|| KERIError::ValueError("Missing ilk (t) in query".to_string()))?
1401            .as_str()
1402            .ok_or_else(|| KERIError::ValueError("Ilk (t) field is not a string".to_string()))?;
1403
1404        let route = ked
1405            .get("r")
1406            .ok_or_else(|| KERIError::ValueError("Missing route (r) in query".to_string()))?
1407            .as_str()
1408            .ok_or_else(|| KERIError::ValueError("Route (r) field is not a string".to_string()))?;
1409
1410        let qry = ked
1411            .get("q")
1412            .ok_or_else(|| KERIError::ValueError("Missing query data (q) in query".to_string()))?
1413            .as_object()
1414            .ok_or_else(|| {
1415                KERIError::ValueError("Query data (q) field is not an object".to_string())
1416            })?;
1417
1418        // Determine the destination for replies
1419        let dest = match (&source, &cigars) {
1420            (None, Some(cigars)) if !cigars.is_empty() => cigars[0].clone().verfer.unwrap().qb64(),
1421            (Some(source), _) => source.qb64(),
1422            _ => {
1423                return Err(
1424                    KERIError::ValueError("No valid destination for reply".to_string()).into(),
1425                )
1426            }
1427        };
1428
1429        match route {
1430            "logs" => {
1431                // Extract query parameters
1432                let pre = qry
1433                    .get("i")
1434                    .ok_or_else(|| {
1435                        KERIError::ValueError("Missing identifier (i) in query".to_string())
1436                    })?
1437                    .as_str()
1438                    .ok_or_else(|| {
1439                        KERIError::ValueError("Identifier (i) field is not a string".to_string())
1440                    })?;
1441
1442                let src = qry
1443                    .get("src")
1444                    .ok_or_else(|| {
1445                        KERIError::ValueError("Missing source (src) in query".to_string())
1446                    })?
1447                    .as_str()
1448                    .ok_or_else(|| {
1449                        KERIError::ValueError("Source (src) field is not a string".to_string())
1450                    })?;
1451
1452                // Optional parameters
1453                let anchor = qry.get("a").and_then(|v| v.as_str());
1454                let sn = qry
1455                    .get("s")
1456                    .and_then(|v| v.as_str())
1457                    .map(|s| i64::from_str_radix(s, 16))
1458                    .transpose()
1459                    .map_err(|_| {
1460                        KERIError::ValueError("Invalid sequence number format".to_string())
1461                    })?;
1462                let fn_num = qry
1463                    .get("fn")
1464                    .and_then(|v| v.as_str())
1465                    .map(|s| i64::from_str_radix(s, 16))
1466                    .transpose()
1467                    .map_err(|_| {
1468                        KERIError::ValueError("Invalid first seen number format".to_string())
1469                    })?
1470                    .unwrap_or(0);
1471
1472                // Check if we have the identifier
1473                if !self.kevers.contains_key(pre) {
1474                    self.escrow_query_not_found_event(
1475                        &serder,
1476                        source.as_ref(),
1477                        sigers.as_deref(),
1478                        cigars.as_deref(),
1479                    )?;
1480                    let msg = format!(
1481                        "Query not found error on event route={} SAID={}",
1482                        route,
1483                        serder.said().unwrap_or_default()
1484                    );
1485                    debug!("{}", msg);
1486                    debug!("Query Body=\n{}\n", serder.pretty(None));
1487                    return Err(KERIError::QueryNotFoundError(msg).into());
1488                }
1489
1490                let kever = &self.kevers[pre];
1491
1492                // Check anchor if provided
1493                if let Some(anchor) = anchor {
1494                    if !self.db.fetch_all_sealing_event_by_event_seal(pre, anchor)? {
1495                        self.escrow_query_not_found_event(
1496                            &serder,
1497                            source.as_ref(),
1498                            sigers.as_deref(),
1499                            cigars.as_deref(),
1500                        )?;
1501                        let msg = format!(
1502                            "Query not found error on event route={} SAID={}",
1503                            route,
1504                            serder.said().unwrap_or_default()
1505                        );
1506                        debug!("{}", msg);
1507                        debug!("Query Body=\n{}\n", serder.pretty(None));
1508                        return Err(KERIError::QueryNotFoundError(msg).into());
1509                    }
1510                }
1511                // Check sequence number if provided
1512                else if let Some(sn) = sn {
1513                    let current_sn = kever.sner().map(|s| s.num()).unwrap_or_default();
1514                    if current_sn < sn as u128 || !self.fully_witnessed(&kever.serder().unwrap()) {
1515                        self.escrow_query_not_found_event(
1516                            &serder,
1517                            source.as_ref(),
1518                            sigers.as_deref(),
1519                            cigars.as_deref(),
1520                        )?;
1521                        let msg = format!(
1522                            "Query not found error on event route={} SAID={}",
1523                            route,
1524                            serder.said().unwrap_or_default()
1525                        );
1526                        debug!("{}", msg);
1527                        debug!("Query Body=\n{}\n", serder.pretty(None));
1528                        return Err(KERIError::QueryNotFoundError(msg).into());
1529                    }
1530                }
1531
1532                // Get messages to replay
1533                let mut msgs = Vec::new();
1534
1535                // Clone prefix events starting from fn_num
1536                for msg in self.db.clone_pre_iter(pre, Some(fn_num as u64))? {
1537                    msgs.push(msg);
1538                }
1539
1540                // If there's a delegator prefix, clone its events as well
1541                if let Some(delpre) = kever.delpre() {
1542                    for msg in self.db.clone_pre_iter(&delpre, Some(0))? {
1543                        msgs.push(msg);
1544                    }
1545                }
1546
1547                // If we have messages to send, add a replay cue
1548                if !msgs.is_empty() {
1549                    let cue = Cue {
1550                        kin: "replay".to_string(),
1551                        serder,
1552                    };
1553                    self.cues.push_back(cue);
1554                }
1555            }
1556
1557            "ksn" => {
1558                // Extract query parameters
1559                let pre = qry
1560                    .get("i")
1561                    .ok_or_else(|| {
1562                        KERIError::ValueError("Missing identifier (i) in query".to_string())
1563                    })?
1564                    .as_str()
1565                    .ok_or_else(|| {
1566                        KERIError::ValueError("Identifier (i) field is not a string".to_string())
1567                    })?;
1568
1569                let src = qry
1570                    .get("src")
1571                    .ok_or_else(|| {
1572                        KERIError::ValueError("Missing source (src) in query".to_string())
1573                    })?
1574                    .as_str()
1575                    .ok_or_else(|| {
1576                        KERIError::ValueError("Source (src) field is not a string".to_string())
1577                    })?;
1578
1579                // Check if we have the identifier
1580                if !self.kevers.contains_key(pre) {
1581                    self.escrow_query_not_found_event(
1582                        &serder,
1583                        source.as_ref(),
1584                        sigers.as_deref(),
1585                        cigars.as_deref(),
1586                    )?;
1587                    let msg = format!(
1588                        "Query not found error on event route={} SAID={}",
1589                        route,
1590                        serder.said().unwrap_or_default()
1591                    );
1592                    debug!("{}", msg);
1593                    debug!("Query Body=\n{}\n", serder.pretty(None));
1594                    return Err(KERIError::QueryNotFoundError(msg).into());
1595                }
1596
1597                let kever = &self.kevers[pre];
1598
1599                // Get list of witness signatures to ensure we are presenting a fully witnessed event
1600                let dg_key = dg_key(pre, &kever.serder().unwrap().said().unwrap_or_default());
1601                let wigs = self.db.wigs.get_item_iter(&[&dg_key], false)?;
1602                let wigers: Vec<Siger> = wigs
1603                    .iter()
1604                    .map(|(_, wig)| Siger::from_qb64(&String::from_utf8_lossy(wig), None))
1605                    .collect::<Result<Vec<Siger>, _>>()?;
1606
1607                // Check if we have enough witness signatures
1608                if let Some(toader) = kever.toader() {
1609                    if wigers.len() < toader.num() as usize {
1610                        self.escrow_query_not_found_event(
1611                            &serder,
1612                            source.as_ref(),
1613                            sigers.as_deref(),
1614                            cigars.as_deref(),
1615                        )?;
1616                        let msg = format!(
1617                            "Query not found error on event route={} SAID={}",
1618                            route,
1619                            serder.said().unwrap_or_default()
1620                        );
1621                        debug!("{}", msg);
1622                        debug!("Query Body=\n{}\n", serder.pretty(None));
1623                        return Err(KERIError::QueryNotFoundError(msg).into());
1624                    }
1625                }
1626
1627                // Create reply with key state
1628                let _state = kever.state();
1629                let rserder = ReplyEventBuilder::new()
1630                    .with_route(format!("/ksn/{}", src))
1631                    .build()?;
1632                // Add reply cue
1633                let cue = Cue {
1634                    kin: "reply".to_string(),
1635                    serder: rserder,
1636                };
1637                self.cues.push_back(cue);
1638            }
1639
1640            "mbx" => {
1641                // Extract query parameters
1642                let pre = qry
1643                    .get("i")
1644                    .ok_or_else(|| {
1645                        KERIError::ValueError("Missing identifier (i) in query".to_string())
1646                    })?
1647                    .as_str()
1648                    .ok_or_else(|| {
1649                        KERIError::ValueError("Identifier (i) field is not a string".to_string())
1650                    })?;
1651
1652                let src = qry
1653                    .get("src")
1654                    .ok_or_else(|| {
1655                        KERIError::ValueError("Missing source (src) in query".to_string())
1656                    })?
1657                    .as_str()
1658                    .ok_or_else(|| {
1659                        KERIError::ValueError("Source (src) field is not a string".to_string())
1660                    })?;
1661
1662                let topics = qry
1663                    .get("topics")
1664                    .ok_or_else(|| KERIError::ValueError("Missing topics in query".to_string()))?
1665                    .as_array()
1666                    .ok_or_else(|| {
1667                        KERIError::ValueError("Topics field is not an array".to_string())
1668                    })?
1669                    .iter()
1670                    .map(|v| v.as_str().unwrap_or_default().to_string())
1671                    .collect::<Vec<String>>();
1672
1673                // Check if we have the identifier
1674                if !self.kevers.contains_key(pre) {
1675                    self.escrow_query_not_found_event(
1676                        &serder,
1677                        source.as_ref(),
1678                        sigers.as_deref(),
1679                        cigars.as_deref(),
1680                    )?;
1681                    let msg = format!(
1682                        "Query not found error on event route={} SAID={}",
1683                        route,
1684                        serder.said().unwrap_or_default()
1685                    );
1686                    debug!("{}", msg);
1687                    debug!("Query Body=\n{}\n", serder.pretty(None));
1688                    return Err(KERIError::QueryNotFoundError(msg).into());
1689                }
1690
1691                // Add stream cue
1692                let cue = Cue {
1693                    kin: "stream".to_string(),
1694                    serder,
1695                };
1696                self.cues.push_back(cue);
1697            }
1698
1699            _ => {
1700                // Invalid route
1701                let cue = Cue {
1702                    kin: "route".to_string(),
1703                    serder: serder.clone(),
1704                };
1705                self.cues.push_back(cue);
1706
1707                let msg = format!(
1708                    "Invalid query message {} for event route={} SAID={}",
1709                    ilk,
1710                    route,
1711                    serder.said().unwrap_or_default()
1712                );
1713                info!("{}", msg);
1714                debug!("Query Body=\n{}\n", serder.pretty(None));
1715
1716                return Err(KERIError::ValueError(msg).into());
1717            }
1718        }
1719
1720        Ok(())
1721    }
1722
1723    pub fn fully_witnessed(&self, serder: &SerderKERI) -> bool {
1724        let preb = serder.preb().unwrap_or_default();
1725        let said = serder.said().unwrap_or_default();
1726
1727        let key = dg_key(preb, said);
1728        match self.db.wigs.get::<_, Vec<u8>>(&[&key]) {
1729            Ok(wigs) => {
1730                let pre = serder.pre().unwrap();
1731                let kever = &self.kevers[&pre];
1732                let toad = kever.toader().unwrap().num();
1733                wigs.len() >= toad as usize
1734            }
1735            Err(_) => false,
1736        }
1737    }
1738
1739    /// Escrow a query that couldn't be processed because the requested event wasn't found
1740    fn escrow_query_not_found_event(
1741        &self,
1742        serder: &SerderKERI,
1743        _source: Option<&Prefixer>,
1744        _sigers: Option<&[Siger]>,
1745        _cigars: Option<&[Cigar]>,
1746    ) -> Result<(), KERIError> {
1747        // Implementation details would go here
1748        // This would store the query in an escrow database to be processed later
1749        // when the requested event becomes available
1750
1751        // For now we'll just log it
1752        debug!(
1753            "Escrowing query not found event with SAID: {}",
1754            serder.said().unwrap_or_default()
1755        );
1756
1757        // TODO: Implement proper escrow functionality
1758        Ok(())
1759    }
1760}
1761
1762/// Builder pattern for Kevery to make initialization more ergonomic
1763pub struct KeveryBuilder {
1764    db: Arc<Baser>,
1765    cues: Option<VecDeque<Cue>>,
1766    rvy: Option<Rvy>,
1767    lax: Option<bool>,
1768    local: Option<bool>,
1769    cloned: Option<bool>,
1770    direct: Option<bool>,
1771    check: Option<bool>,
1772}
1773
1774impl KeveryBuilder {
1775    /// Create a new KeveryBuilder instance
1776    pub fn new(db: Arc<Baser>) -> Self {
1777        Self {
1778            db,
1779            cues: None,
1780            rvy: None,
1781            lax: None,
1782            local: None,
1783            cloned: None,
1784            direct: None,
1785            check: None,
1786        }
1787    }
1788
1789    /// Set the cues for the Kevery instance
1790    pub fn with_cues(mut self, cues: VecDeque<Cue>) -> Self {
1791        self.cues = Some(cues);
1792        self
1793    }
1794
1795    /// Set the recovery module for the Kevery instance
1796    pub fn with_rvy(mut self, rvy: Rvy) -> Self {
1797        self.rvy = Some(rvy);
1798        self
1799    }
1800
1801    /// Set the lax mode for the Kevery instance
1802    pub fn with_lax(mut self, lax: bool) -> Self {
1803        self.lax = Some(lax);
1804        self
1805    }
1806
1807    /// Set the local flag for the Kevery instance
1808    pub fn with_local(mut self, local: bool) -> Self {
1809        self.local = Some(local);
1810        self
1811    }
1812
1813    /// Set the cloned flag for the Kevery instance
1814    pub fn with_cloned(mut self, cloned: bool) -> Self {
1815        self.cloned = Some(cloned);
1816        self
1817    }
1818
1819    /// Set the direct mode for the Kevery instance
1820    pub fn with_direct(mut self, direct: bool) -> Self {
1821        self.direct = Some(direct);
1822        self
1823    }
1824
1825    /// Set the check mode for the Kevery instance
1826    pub fn with_check(mut self, check: bool) -> Self {
1827        self.check = Some(check);
1828        self
1829    }
1830
1831    /// Build the Kevery instance from the provided options
1832    pub fn build(self) -> Result<Kevery, KERIError> {
1833        Kevery::new(
1834            self.cues,
1835            self.db.clone(),
1836            self.rvy,
1837            self.lax,
1838            self.local,
1839            self.cloned,
1840            self.direct,
1841            self.check,
1842        )
1843    }
1844}
1845
1846/// The escrows of events retried by reprocessing them whole.
1847#[derive(Debug, Clone, Copy)]
1848enum EventEscrow {
1849    PartialSigs,
1850    PartialWigs,
1851    OutOfOrder,
1852    LikelyDuplicitous,
1853}
1854
1855impl EventEscrow {
1856    fn timeout(self) -> u64 {
1857        match self {
1858            EventEscrow::PartialSigs => Kevery::TIMEOUT_PSE,
1859            EventEscrow::PartialWigs => Kevery::TIMEOUT_PWE,
1860            EventEscrow::OutOfOrder => Kevery::TIMEOUT_OOE,
1861            EventEscrow::LikelyDuplicitous => Kevery::TIMEOUT_LDE,
1862        }
1863    }
1864
1865    /// The error that keeps an entry in this escrow.
1866    fn still_waiting(self, e: &KERIError) -> bool {
1867        match self {
1868            EventEscrow::PartialSigs => matches!(e, KERIError::MissingSignatureError(_)),
1869            EventEscrow::PartialWigs => matches!(e, KERIError::MissingWitnessSignatureError(_)),
1870            EventEscrow::OutOfOrder => matches!(e, KERIError::OutOfOrderError(_)),
1871            EventEscrow::LikelyDuplicitous => matches!(e, KERIError::LikelyDuplicitousError(_)),
1872        }
1873    }
1874}
1875
1876/// A witness signature from a receipt: an unindexed couple (`-C`) or an
1877/// indexed witness signature (`-B`).
1878enum WitnessSig<'a> {
1879    Couple(&'a Cigar),
1880    Indexed(&'a Siger),
1881}
1882
1883/// Rebuild the dotted snKey string from the key parts an escrow iterator returns.
1884fn join_keys(keys: &[Vec<u8>]) -> String {
1885    keys.iter()
1886        .map(|k| String::from_utf8_lossy(k).to_string())
1887        .collect::<Vec<_>>()
1888        .join(".")
1889}
1890
1891/// Sequence number from the key parts of an snKey(pre, sn).
1892fn escrow_sn(keys: &[Vec<u8>]) -> Result<u64, KERIError> {
1893    let sn = keys
1894        .get(1)
1895        .and_then(|k| std::str::from_utf8(k).ok())
1896        .ok_or_else(|| KERIError::ValidationError("escrow key has no sn".into()))?;
1897    u64::from_str_radix(sn, 16).map_err(|e| KERIError::ValidationError(format!("bad escrow sn {}: {}", sn, e)))
1898}
1899
1900pub(crate) fn load_sigers(sigs: Vec<Vec<u8>>) -> Result<Vec<Siger>, KERIError> {
1901    sigs.into_iter()
1902        .map(|mut b| {
1903            Siger::from_qb64b(&mut b, None)
1904                .map_err(|e| KERIError::ValidationError(format!("bad escrowed signature: {}", e)))
1905        })
1906        .collect()
1907}
1908
1909/// Witness indexed signature at `index` from a receipt couple's signature,
1910/// using the indexed code for the cigar's signature suite.
1911pub(crate) fn cigar_to_wiger(cigar: &Cigar, index: u32) -> Result<Siger, KERIError> {
1912    use crate::cesr::indexing::idr_dex;
1913    use crate::cesr::mtr_dex;
1914    let code = match cigar.code() {
1915        mtr_dex::ED25519_SIG => idr_dex::ED25519_SIG,
1916        mtr_dex::ECDSA_256K1_SIG => idr_dex::ECDSA_256K1_SIG,
1917        mtr_dex::ECDSA_256R1_SIG => idr_dex::ECDSA_256R1_SIG,
1918        mtr_dex::ED448_SIG => idr_dex::ED448_SIG,
1919        other => {
1920            return Err(KERIError::ValueError(format!("Unsupported receipt signature code {}", other)))
1921        }
1922    };
1923    Ok(Siger::new(Some(cigar.raw()), Some(code), Some(index), None, cigar.verfer().cloned())?)
1924}
1925
1926/// Receipt couple signature (unindexed) for a witness indexed signature; the
1927/// inverse of [`cigar_to_wiger`].
1928pub(crate) fn wiger_to_cigar(wiger: &Siger, verfer: Verfer) -> Result<Cigar, KERIError> {
1929    use crate::cesr::indexing::idr_dex;
1930    use crate::cesr::mtr_dex;
1931    let code = match wiger.code() {
1932        idr_dex::ED25519_SIG | idr_dex::ED25519_CRT_SIG => mtr_dex::ED25519_SIG,
1933        idr_dex::ECDSA_256K1_SIG | idr_dex::ECDSA_256K1_CRT_SIG => mtr_dex::ECDSA_256K1_SIG,
1934        idr_dex::ECDSA_256R1_SIG | idr_dex::ECDSA_256R1_CRT_SIG => mtr_dex::ECDSA_256R1_SIG,
1935        idr_dex::ED448_SIG | idr_dex::ED448_CRT_SIG => mtr_dex::ED448_SIG,
1936        other => {
1937            return Err(KERIError::ValueError(format!("Unsupported witness signature code {}", other)))
1938        }
1939    };
1940    Ok(Cigar::new(Some(&wiger.raw()), Some(code), None, None, Some(verfer))?)
1941}
1942
1943#[cfg(test)]
1944mod tests {
1945    use super::*;
1946    use crate::keri::db::dbing::LMDBer;
1947
1948    #[test]
1949    fn test_kevery_new() -> Result<(), KERIError> {
1950        // Create a temporary database
1951        let lmdber = LMDBer::builder()
1952            .temp(true)
1953            .name("test_kevery")
1954            .build()
1955            .map_err(|e| KERIError::DatabaseError(format!("{}", e)))?;
1956
1957        let db =
1958            Baser::new(Arc::new(lmdber)).map_err(|e| KERIError::DatabaseError(format!("{}", e)))?;
1959
1960        // Create Kevery using the new function
1961        let kevery = Kevery::new(
1962            None,
1963            Arc::new(db),
1964            None,
1965            Some(true),
1966            Some(false),
1967            Some(false),
1968            Some(true),
1969            Some(false),
1970        )?;
1971
1972        assert!(kevery.lax);
1973        assert!(!kevery.local);
1974        assert!(!kevery.cloned);
1975        assert!(kevery.direct);
1976        assert!(!kevery.check);
1977        assert!(kevery.kevers().is_empty());
1978
1979        Ok(())
1980    }
1981
1982    #[test]
1983    fn test_kevery_builder() -> Result<(), KERIError> {
1984        // Create a temporary database
1985        let lmdber = LMDBer::builder()
1986            .temp(true)
1987            .name("test_kevery_builder")
1988            .build()
1989            .map_err(|e| KERIError::DatabaseError(format!("{}", e)))?;
1990
1991        let db =
1992            Baser::new(Arc::new(lmdber)).map_err(|e| KERIError::DatabaseError(format!("{}", e)))?;
1993
1994        // Create Kevery using the builder pattern
1995        let kevery = KeveryBuilder::new(Arc::new(db))
1996            .with_lax(true)
1997            .with_local(false)
1998            .with_cloned(false)
1999            .with_direct(true)
2000            .with_check(false)
2001            .build()?;
2002
2003        assert!(kevery.lax);
2004        assert!(!kevery.local);
2005        assert!(!kevery.cloned);
2006        assert!(kevery.direct);
2007        assert!(!kevery.check);
2008        assert!(kevery.kevers().is_empty());
2009
2010        Ok(())
2011    }
2012}