Events and query structure definitions

Cargo.toml

@@ -8,7 +8,7 @@ edition = "2021"
 default = ["debug", "cli"]
 cli = ["enable-serde", "stderrlog", "structopt"]
 debug = ["hex"]
-enable-serde = ["serde", "serde_json", "rust-elgamal/enable-serde"]
+enable-serde = ["serde", "serde_json", "rust-elgamal/enable-serde", "num-bigint/serde"]
 
 [dependencies]
 # rust-elgamal (via curve25519-dalek-ng) only works with digest 0.9, not 0.10
@@ -27,6 +27,7 @@ serde_json = {version = "1.0", optional = true}
 sha2 = "0.9"
 stderrlog = {version = "0.5", optional = true}
 structopt = {version = "0.3", optional = true}
+num-bigint = {version = "0.4.3", optional = true}
 
 [dev-dependencies]
 hex = "0.4"

src/helpers/mod.rs

@@ -1,5 +1,6 @@
 pub mod aggregation;
 pub mod event;
+pub mod models;
 pub mod privacy_budget;
 
 pub use aggregation::{

src/helpers/models.rs

@@ -0,0 +1,140 @@
+use num_bigint::BigInt;
+use serde::{Deserialize, Serialize};
+use std::fmt::{Debug, Formatter};
+use std::ops::Range;
+
+// Type aliases to indicate whether the parameter should be encrypted, secret shared, etc.
+// Underlying types are temporalily assigned for PoC.
+type CipherText = BigInt;
+type PlainText = String;
+type SecretShare = [CipherText; 3];
+type PBRange = Range<u8>;
+
+#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
+struct Event {
+    /// Secret shared and then encrypted match keys.
+    matchkeys: Vec<SecretShare>,
+
+    /// Date and time of the event occurence. Secret shared and encrypted.
+    timestamp: SecretShare,
+}
+
+#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
+struct SourceEvent {
+    event: Event,
+
+    /// A key to group sets of the events into.
+    breakdown_key: PlainText,
+}
+
+#[cfg(feature = "debug")]
+impl Debug for SourceEvent {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        write!(
+            f,
+            "SourceEvent:\n  matchkeys={:?}\n  breakdown_key={}",
+            &self.event.matchkeys, &self.breakdown_key
+        )
+    }
+}
+
+#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
+struct TriggerEvent {
+    event: Event,
+
+    /// Conversion value.
+    value: SecretShare,
+
+    /// Zero knowledge proof that the trigger value lies within a specific range
+    /// of values. The range is specified in [TriggerFanoutQuery].
+    zkp: PlainText,
+}
+
+#[cfg(feature = "debug")]
+impl Debug for TriggerEvent {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        write!(
+            f,
+            "TriggerEvent:\n  matchkeys={:?}\n  value={:?}",
+            &self.event.matchkeys, &self.value
+        )
+    }
+}
+
+#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
+enum QueryType {
+    SourceFanout,
+    TriggerFanout,
+}
+
+#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
+enum Node {
+    Helper1,
+    Helper2,
+    Helper3,
+}
+
+#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
+struct IPAQuery {
+    /// Caller authentication token.
+    auth_token: PlainText,
+
+    /// Initial MPC helper node to send the data to.
+    leader_node: Node,
+
+    /// List of match key providers to be used by the source and trigger events during an epoch.
+    mk_providers: Vec<String>,
+
+    /// Source-fanout or Trigger-fanout.
+    query_type: QueryType,
+
+    /// Percentage of epoch-level privacy budget this query should consume. Likely 1-100.
+    privacy_budget: PBRange,
+
+    /// A collection of source events. At least 100 (TBD) unique source events must be provided.
+    source_events: Vec<SourceEvent>,
+
+    /// A collection of trigger events. At least 10 (TBD) unique trigger events must be provided.
+    trigger_events: Vec<TriggerEvent>,
+}
+
+#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
+struct SourceFanoutQuery {
+    query: IPAQuery,
+
+    /// The maximum number of attributed conversion events that a single person can contribute
+    /// towards the final output.
+    cap: u8,
+}
+
+#[cfg(feature = "debug")]
+impl Debug for SourceFanoutQuery {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        write!(
+            f,
+            "SourceFanoutQuery:\n  {} source events\n  {} trigger events",
+            &self.query.source_events.len(),
+            &self.query.trigger_events.len()
+        )
+    }
+}
+
+#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
+struct TriggerFanoutQuery {
+    query: IPAQuery,
+
+    /// The range which all trigger event's conversion values must lie within.
+    value_range: Range<u32>,
+}
+
+#[cfg(feature = "debug")]
+impl Debug for TriggerFanoutQuery {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        write!(
+            f,
+            "TriggerFanoutQuery:\n  {} source events\n  {} trigger events",
+            &self.query.source_events.len(),
+            &self.query.trigger_events.len()
+        )
+    }
+}