feat(papyrus_base_layer): add events api

crates/papyrus_base_layer/src/ethereum_base_layer_contract.rs

@@ -18,7 +18,7 @@ use starknet_api::hash::StarkHash;
 use starknet_types_core::felt;
 use url::Url;
 
-use crate::BaseLayerContract;
+use crate::{BaseLayerContract, L1Event};
 
 type EthereumBaseLayerResult<T> = Result<T, EthereumBaseLayerError>;
 
@@ -79,6 +79,15 @@ impl BaseLayerContract for EthereumBaseLayerContract {
         }))
     }
 
+    async fn events(
+        &self,
+        _from_block: u64,
+        _until_block: u64,
+        _event_identifiers: &[&str],
+    ) -> EthereumBaseLayerResult<Vec<L1Event>> {
+        todo!("Implmeneted in a subsequent commit")
+    }
+
     async fn latest_l1_block_number(&self, finality: u64) -> EthereumBaseLayerResult<Option<u64>> {
         Ok(self.contract.provider().get_block_number().await?.checked_sub(finality))
     }

crates/papyrus_base_layer/src/lib.rs

@@ -1,5 +1,9 @@
 use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
 use starknet_api::block::BlockHashAndNumber;
+use starknet_api::core::{ContractAddress, EntryPointSelector, EthAddress, Nonce};
+use starknet_api::transaction::fields::{Calldata, Fee};
+use starknet_api::transaction::L1HandlerTransaction;
 
 pub mod ethereum_base_layer_contract;
 
@@ -21,5 +25,32 @@ pub trait BaseLayerContract {
         finality: u64,
     ) -> Result<Option<BlockHashAndNumber>, Self::Error>;
 
+    /// Get specific events from the Starknet base contract between two l1 block numbers.
+    async fn events(
+        &self,
+        from_block: u64,
+        until_block: u64,
+        event_identifiers: &[&str],
+    ) -> Result<Vec<L1Event>, Self::Error>;
+
     async fn latest_l1_block_number(&self, finality: u64) -> Result<Option<u64>, Self::Error>;
 }
+
+/// Wraps Starknet L1 events with Starknet API types.
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+pub enum L1Event {
+    LogMessageToL2 { tx: L1HandlerTransaction, fee: Fee },
+    MessageToL2CancellationStarted(EventData),
+    MessageToL2Canceled(EventData),
+    ConsumedMessageToL1 { from_address: EthAddress, to_address: ContractAddress, payload: Calldata },
+}
+
+/// Shared fields in Starknet messaging.
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize, Default)]
+pub struct EventData {
+    pub from_address: EthAddress,
+    pub to_address: ContractAddress,
+    pub entry_point_selector: EntryPointSelector,
+    pub payload: Calldata,
+    pub nonce: Nonce,
+}