Skip to main content

libkeri/keri/core/eventing/
receipt.rs

1use crate::cesr::number::Number;
2use crate::cesr::Versionage;
3use crate::keri::core::serdering::{SadValue, SerderKERI};
4use crate::keri::{versify, Ilks, Kinds};
5use indexmap::IndexMap;
6use num_bigint::BigUint;
7use std::error::Error;
8
9/// Builder for creating KERI receipt events
10pub struct ReceiptEventBuilder {
11    pre: String,
12    sn: usize,
13    said: String,
14    version: String,
15    kind: String,
16}
17
18impl ReceiptEventBuilder {
19    /// Create a new ReceiptEventBuilder with required fields
20    ///
21    /// Parameters:
22    ///   pre - qb64 string of prefix of event being receipted
23    ///   sn - sequence number of event being receipted
24    ///   said - qb64 of said of event being receipted
25    pub fn new(pre: String, sn: usize, said: String) -> Self {
26        Self {
27            pre,
28            sn,
29            said,
30            version: "KERI10JSON000000_".to_string(),
31            kind: "JSON".to_string(),
32        }
33    }
34
35    /// Set the version string
36    pub fn with_version(mut self, version: String) -> Self {
37        self.version = version;
38        self
39    }
40
41    /// Set the serialization kind
42    pub fn with_kind(mut self, kind: String) -> Self {
43        self.kind = kind;
44        self
45    }
46
47    /// Build the receipt event serder
48    pub fn build(self) -> Result<SerderKERI, Box<dyn Error>> {
49        // Validate sequence number
50        let sner = Number::from_num(&BigUint::from(self.sn))?;
51
52        if !Kinds::contains(&self.kind) {
53            return Err(format!("Invalid kind = {} for rect.", self.kind).into());
54        }
55
56        // Create versified string
57        let vs = versify("KERI", &Versionage::from(self.version), &self.kind, 0)?;
58
59        // Create the key event dict (ked)
60        let mut ked = IndexMap::new();
61        ked.insert("v".to_string(), SadValue::String(vs));
62        ked.insert("t".to_string(), SadValue::String(Ilks::RCT.to_string()));
63        ked.insert("d".to_string(), SadValue::String(self.said));
64        ked.insert("i".to_string(), SadValue::String(self.pre));
65        ked.insert("s".to_string(), SadValue::String(sner.numh()));
66
67        // Create the serder
68        let serder = SerderKERI::from_sad_and_saids(&ked, None)?;
69        Ok(serder)
70    }
71}
72
73#[cfg(test)]
74mod tests {
75    use super::*;
76    use crate::keri::core::serdering::{Rawifiable, Serder};
77    use std::error::Error;
78
79    #[test]
80    fn test_receipt_event_builder_basic() -> Result<(), Box<dyn Error>> {
81        // Create identifier prefix
82        let pre = "DFs8BBx86uytIM0D2BhsE5rrqVIT8ef8mflpNceHo4XH".to_string();
83
84        // Sequence number
85        let sn = 3;
86
87        // SAID of event being receipted
88        let said = "EKKccCumVQdgxvsrSXvuTtjmS28Xqf3zRJ8T6peKgl9J".to_string();
89
90        // Create a basic receipt
91        let serder = ReceiptEventBuilder::new(pre.clone(), sn, said.clone()).build()?;
92
93        // Verify the key event data
94        let ked = serder.ked();
95
96        // Check it's a receipt event
97        assert_eq!(ked["t"].as_str().unwrap(), Ilks::RCT);
98
99        // Check basic fields
100        assert_eq!(ked["i"].as_str().unwrap(), pre);
101        assert_eq!(ked["s"].as_str().unwrap(), "3");
102        assert_eq!(ked["d"].as_str().unwrap(), said);
103
104        Ok(())
105    }
106
107    #[test]
108    fn test_receipt_event_custom_version_kind() -> Result<(), Box<dyn Error>> {
109        // Create identifier prefix
110        let pre = "DFs8BBx86uytIM0D2BhsE5rrqVIT8ef8mflpNceHo4XH".to_string();
111
112        // Sequence number
113        let sn = 5;
114
115        // SAID of event being receipted
116        let said = "EKKccCumVQdgxvsrSXvuTtjmS28Xqf3zRJ8T6peKgl9J".to_string();
117
118        // Create a receipt with custom version and kind
119        let serder = ReceiptEventBuilder::new(pre.clone(), sn, said.clone())
120            .with_version("KERI10".to_string())
121            .with_kind("CBOR".to_string())
122            .build()?;
123
124        // Verify the version string
125        let ked = serder.ked();
126        let version = ked["v"].as_str().unwrap();
127        assert!(version.starts_with("KERI10CBOR"));
128
129        Ok(())
130    }
131
132    #[test]
133    fn test_receipt_event_validation() -> Result<(), Box<dyn Error>> {
134        // Create identifier prefix
135        let pre = "DFs8BBx86uytIM0D2BhsE5rrqVIT8ef8mflpNceHo4XH".to_string();
136
137        // Invalid kind
138        let sn = 1;
139        let said = "EKKccCumVQdgxvsrSXvuTtjmS28Xqf3zRJ8T6peKgl9J".to_string();
140
141        let result = ReceiptEventBuilder::new(pre.clone(), sn, said.clone())
142            .with_kind("INVALID".to_string())
143            .build();
144
145        assert!(result.is_err());
146        let err = result.unwrap_err();
147        assert!(err.to_string().contains("Invalid kind"));
148
149        Ok(())
150    }
151
152    #[test]
153    fn test_receipt_event_serialization() -> Result<(), Box<dyn Error>> {
154        // Create identifier prefix
155        let pre = "DFs8BBx86uytIM0D2BhsE5rrqVIT8ef8mflpNceHo4XH".to_string();
156
157        // Sequence number
158        let sn = 4;
159
160        // SAID of event being receipted
161        let said = "EKKccCumVQdgxvsrSXvuTtjmS28Xqf3zRJ8T6peKgl9J".to_string();
162
163        // Create a receipt
164        let serder = ReceiptEventBuilder::new(pre.clone(), sn, said.clone()).build()?;
165
166        // Check raw serialization
167        let raw = serder.raw();
168
169        // Verify we can deserialize it back
170        let deserialized = SerderKERI::from_raw(&raw, None)?;
171
172        // Check that fields match
173        assert_eq!(deserialized.ked()["t"].as_str().unwrap(), Ilks::RCT);
174        assert_eq!(deserialized.ked()["i"].as_str().unwrap(), pre);
175        assert_eq!(deserialized.ked()["s"].as_str().unwrap(), "4");
176        assert_eq!(deserialized.ked()["d"].as_str().unwrap(), said);
177
178        Ok(())
179    }
180
181    #[test]
182    fn test_receipt_event_specific_structure() -> Result<(), Box<dyn Error>> {
183        // Create identifier prefix
184        let pre = "DFs8BBx86uytIM0D2BhsE5rrqVIT8ef8mflpNceHo4XH".to_string();
185
186        // Sequence number
187        let sn = 2;
188
189        // SAID of event being receipted
190        let said = "EGr9qTLviRyuWnmLCXkMJGqUVGczfKpELk7aBfKuwMnK".to_string();
191
192        // Create a receipt
193        let serder = ReceiptEventBuilder::new(pre.clone(), sn, said.clone()).build()?;
194
195        // Verify structure (especially compared to interaction events)
196        let ked = serder.ked();
197
198        // Receipt events have:
199        // 1. No 'p' field (previous event digest)
200        assert!(ked.get("p").is_none());
201
202        // 2. No 'a' field (attachments)
203        assert!(ked.get("a").is_none());
204
205        // 3. The 'd' field contains the receipted event's SAID
206        assert_eq!(ked["d"].as_str().unwrap(), said);
207
208        // 4. The 't' field is "rct"
209        assert_eq!(ked["t"].as_str().unwrap(), Ilks::RCT);
210
211        Ok(())
212    }
213
214    #[test]
215    fn test_receipt() -> Result<(), Box<dyn Error>> {
216        let pre = "DFs8BBx86uytIM0D2BhsE5rrqVIT8ef8mflpNceHo4XH";
217        let said = "EKKccCumVQdgxvsrSXvuTtjmS28Xqf3zRJ8T6peKgl9J";
218
219        let serder = ReceiptEventBuilder::new(pre.to_string(), 0, said.to_string()).build()?;
220
221        let ked = serder.ked();
222        assert_eq!(ked["t"].as_str().unwrap(), Ilks::RCT);
223        assert_eq!(ked["i"].as_str().unwrap(), pre);
224        assert_eq!(ked["s"].as_str().unwrap(), "0");
225
226        let raw = b"{\"v\":\"KERI10JSON000091_\",\"t\":\"rct\",\"d\":\"EKKccCumVQdgxvsrSXvuTtjmS28Xqf3zRJ8T6peKgl9J\",\"i\":\"DFs8BBx86uytIM0D2BhsE5rrqVIT8ef8mflpNceHo4XH\",\"s\":\"0\"}";
227        assert_eq!(raw, serder.raw());
228
229        let serder = ReceiptEventBuilder::new(pre.to_string(), 2, said.to_string()).build()?;
230
231        let ked = serder.ked();
232        assert_eq!(ked["t"].as_str().unwrap(), Ilks::RCT);
233        assert_eq!(ked["i"].as_str().unwrap(), pre);
234        assert_eq!(ked["s"].as_str().unwrap(), "2");
235
236        let raw = b"{\"v\":\"KERI10JSON000091_\",\"t\":\"rct\",\"d\":\"EKKccCumVQdgxvsrSXvuTtjmS28Xqf3zRJ8T6peKgl9J\",\"i\":\"DFs8BBx86uytIM0D2BhsE5rrqVIT8ef8mflpNceHo4XH\",\"s\":\"2\"}";
237        assert_eq!(raw, serder.raw());
238
239        Ok(())
240    }
241}