refactor(katana-rpc): getEvents include pending block (#2375)

crates/katana/primitives/Cargo.toml

@@ -25,6 +25,7 @@ flate2 = { workspace = true, optional = true }
 katana-cairo.workspace = true
 
 [dev-dependencies]
+assert_matches.workspace = true
 num-traits.workspace = true
 similar-asserts.workspace = true
 

crates/katana/primitives/src/event.rs

@@ -11,10 +11,21 @@ pub struct OrderedEvent {
     pub data: Vec<FieldElement>,
 }
 
+/// Represents a continuation token for implementing paging in event queries.
+///
+/// This struct stores the necessary information to resume fetching events
+/// from a specific point relative to the given filter passed as parameter to the
+/// `starknet_getEvents` API, [EventFilter][starknet::core::types::EventFilter].
+///
+/// There JSON-RPC specification does not specify the format of the continuation token,
+/// so how the node should handle it is implementation specific.
 #[derive(PartialEq, Eq, Debug, Default)]
 pub struct ContinuationToken {
+    /// The block number to continue from.
     pub block_n: u64,
+    /// The transaction number within the block to continue from.
     pub txn_n: u64,
+    /// The event number within the transaction to continue from.
     pub event_n: u64,
 }
 
@@ -27,7 +38,7 @@ pub enum ContinuationTokenError {
 }
 
 impl ContinuationToken {
-    pub fn parse(token: String) -> Result<Self, ContinuationTokenError> {
+    pub fn parse(token: &str) -> Result<Self, ContinuationTokenError> {
         let arr: Vec<&str> = token.split(',').collect();
         if arr.len() != 3 {
             return Err(ContinuationTokenError::InvalidToken);
@@ -66,7 +77,7 @@ mod test {
     #[test]
     fn parse_works() {
         fn helper(token: &str) -> ContinuationToken {
-            ContinuationToken::parse(token.to_owned()).unwrap()
+            ContinuationToken::parse(token).unwrap()
         }
         assert_eq!(helper("0,0,0"), ContinuationToken { block_n: 0, txn_n: 0, event_n: 0 });
         assert_eq!(helper("1e,ff,4"), ContinuationToken { block_n: 30, txn_n: 255, event_n: 4 });
@@ -75,31 +86,31 @@ mod test {
     #[test]
     fn parse_should_fail() {
         assert_eq!(
-            ContinuationToken::parse("100".to_owned()).unwrap_err(),
+            ContinuationToken::parse("100").unwrap_err(),
             ContinuationTokenError::InvalidToken
         );
         assert_eq!(
-            ContinuationToken::parse("0,".to_owned()).unwrap_err(),
+            ContinuationToken::parse("0,").unwrap_err(),
             ContinuationTokenError::InvalidToken
         );
         assert_eq!(
-            ContinuationToken::parse("0,0".to_owned()).unwrap_err(),
+            ContinuationToken::parse("0,0").unwrap_err(),
             ContinuationTokenError::InvalidToken
         );
     }
 
     #[test]
     fn parse_u64_should_fail() {
         matches!(
-            ContinuationToken::parse("2y,100,4".to_owned()).unwrap_err(),
+            ContinuationToken::parse("2y,100,4").unwrap_err(),
             ContinuationTokenError::ParseFailed(_)
         );
         matches!(
-            ContinuationToken::parse("30,255g,4".to_owned()).unwrap_err(),
+            ContinuationToken::parse("30,255g,4").unwrap_err(),
             ContinuationTokenError::ParseFailed(_)
         );
         matches!(
-            ContinuationToken::parse("244,1,fv".to_owned()).unwrap_err(),
+            ContinuationToken::parse("244,1,fv").unwrap_err(),
             ContinuationTokenError::ParseFailed(_)
         );
     }

crates/katana/rpc/rpc/Cargo.toml

@@ -22,6 +22,7 @@ katana-rpc-types-builder.workspace = true
 katana-tasks.workspace = true
 metrics.workspace = true
 starknet.workspace = true
+thiserror.workspace = true
 tracing.workspace = true
 
 [dev-dependencies]

crates/katana/rpc/rpc/src/lib.rs

@@ -10,3 +10,5 @@ pub mod metrics;
 pub mod saya;
 pub mod starknet;
 pub mod torii;
+
+mod utils;