From 3a85db0d968eab5a88427a19a2a612332caec23f Mon Sep 17 00:00:00 2001
From: David Salami <31099392+Wizdave97@users.noreply.github.com>
Date: Mon, 21 Aug 2023 11:30:49 +0100
Subject: [PATCH] Canonical events (#72)

---
 ismp/src/events.rs | 47 ++++++++++++++++++++++++++++++++++++++++++++++
 ismp/src/lib.rs    |  1 +
 ismp/src/router.rs |  3 +++
 3 files changed, 51 insertions(+)
 create mode 100644 ismp/src/events.rs

diff --git a/ismp/src/events.rs b/ismp/src/events.rs
new file mode 100644
index 0000000..80f0214
--- /dev/null
+++ b/ismp/src/events.rs
@@ -0,0 +1,47 @@
+//! Canonical ISMP Events
+
+use crate::{
+    consensus::{ConsensusStateId, StateMachineHeight, StateMachineId},
+    router::{Get, Post, PostResponse},
+};
+use alloc::collections::BTreeSet;
+use codec::{Decode, Encode};
+use scale_info::TypeInfo;
+
+/// Emitted when a state machine is successfully updated to a new height after the challenge period
+/// has elapsed
+#[derive(Clone, Debug, TypeInfo, Encode, Decode)]
+#[cfg_attr(feature = "std", derive(serde::Serialize, serde::Deserialize))]
+pub struct StateMachineUpdated {
+    /// State machine id
+    pub state_machine_id: StateMachineId,
+    /// Latest height
+    pub latest_height: u64,
+}
+
+/// Emitted when a challenge period has begun for a consensus client
+#[derive(Clone, Debug, TypeInfo, Encode, Decode)]
+#[cfg_attr(feature = "std", derive(serde::Serialize, serde::Deserialize))]
+pub struct ChallengePeriodStarted {
+    /// Consensus client id
+    pub consensus_state_id: ConsensusStateId,
+    /// Tuple of previous height and latest height
+    pub state_machines: BTreeSet<(StateMachineHeight, StateMachineHeight)>,
+}
+
+/// This represents events that should be emitted by ismp-rs wrappers
+#[derive(Clone, Debug, TypeInfo, Encode, Decode)]
+#[cfg_attr(feature = "std", derive(serde::Serialize, serde::Deserialize))]
+pub enum Event {
+    /// Emitted when a state machine is successfully updated to a new height after the challenge
+    /// period has elapsed
+    StateMachineUpdated(StateMachineUpdated),
+    /// Emitted when a challenge period has begun for a consensus client
+    ChallengePeriodStarted(ChallengePeriodStarted),
+    /// An event that is emitted when a post request is dispatched
+    PostRequest(Post),
+    /// An event that is emitted when a post response is dispatched
+    PostResponse(PostResponse),
+    /// An event that is emitted when a get request is dispatched
+    GetRequest(Get),
+}
diff --git a/ismp/src/lib.rs b/ismp/src/lib.rs
index 7cac4fc..a6bba8b 100644
--- a/ismp/src/lib.rs
+++ b/ismp/src/lib.rs
@@ -28,6 +28,7 @@ extern crate core;
 
 pub mod consensus;
 pub mod error;
+pub mod events;
 pub mod handlers;
 pub mod host;
 pub mod messaging;
diff --git a/ismp/src/router.rs b/ismp/src/router.rs
index d45fba3..3624a02 100644
--- a/ismp/src/router.rs
+++ b/ismp/src/router.rs
@@ -64,6 +64,8 @@ pub struct Get {
     /// https://github.com/paritytech/substrate/blob/master/frame/support/src/storage/types/double_map.rs#L34-L44
     /// https://github.com/paritytech/substrate/blob/master/frame/support/src/storage/types/nmap.rs#L39-L48
     /// https://github.com/paritytech/substrate/blob/master/frame/support/src/storage/types/value.rs#L37
+    /// For fetching keys from EVM contracts each key should be 52 bytes
+    /// This should be a concatenation of contract address and slot hash
     pub keys: Vec<Vec<u8>>,
     /// Height at which to read the state machine.
     pub height: u64,
@@ -316,6 +318,7 @@ pub enum DispatchRequest {
 }
 
 /// The Ismp dispatcher allows [`IsmpModules`] to send out outgoing [`Request`] or [`Response`]
+/// [`Event`] should be emitted after successful dispatch
 pub trait IsmpDispatcher {
     /// Dispatches an outgoing request, the dispatcher should commit them to host state trie
     fn dispatch_request(&self, request: DispatchRequest) -> Result<(), Error>;