feat: Upgrade stellar crates and read events from specs (#371)

* chore: Upgrade stellar crates and read events from specs

* fix: Moving helpers funtions to helpers file

* fix: Fixing issue with compare_vec csv

* fix: Removing unnecessary function

* fix: Fixing issue decoding event identifier

* test: Adding integration test case

* fix: Removing print line

* test: Extending test coverage

* fix: Improving logic for extracting stellar values

* test: Adding test cases for csv compare_vec

* docs: Adding docs info for stellar events

* docs: Adding docs info

* docs: Fixing docs info

* docs: Fixing docs link

Author: NicoMolinaOZ

Cargo.lock

@@ -48,10 +48,10 @@ rust_decimal = "1.37.1"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 sha2 = "0.10.0"
-soroban-spec = "22.0.7"
-stellar-rpc-client = "22.0.0"
+soroban-spec = "23.0.2"
+stellar-rpc-client = "23.0.1"
 stellar-strkey = "0.0.13"
-stellar-xdr = "22.1.0"
+stellar-xdr = "23.0.0"
 sysinfo = "0.34.2"
 thiserror = "2.0.12"
 tokio = { version = "1.0", features = ["full"] }

Cargo.toml

@@ -1075,6 +1075,9 @@ The monitor uses a structured JSON format with nested objects for template varia
 | `*events.[index].args.[position]*`
 | Event parameters by position
 
+| `*events.[index].args.[param]*`
+| Event parameters by name (only in case the contract supports event parameters name)
+
 | `*functions.[index].args.[param]*`
 | Function parameters by name
 |===
@@ -1603,7 +1606,23 @@ When a Stellar parameter has `kind: "vec"`, its value can be either a CSV string
 
 *Event Parameter Access (Stellar)*
 
-Stellar event parameters are typically accessed by their numeric index as the base variable name (e.g., `0`, `1`, `2`). If an indexed event parameter is itself a complex type (like an array or map, represented as a JSON string), you can then apply the respective access methods:
+Starting with Stellar Protocol 23, Soroban contracts can include event definitions in their contract specifications. This enables two ways to access event parameters:
+
+*Access by Name (Protocol 23+):*
+When a contract specification includes event definitions, you can access event parameters by their defined names:
+
+* If an event has a parameter named `recipient` (kind: "Address"):
+** `recipient == 'GBBD...ABCD'`
+* If an event has a parameter named `amount` (kind: "U128"):
+** `amount > 1000000`
+* If an event has a parameter named `metadata` (kind: "Map") containing `'{"id": 123, "name": "Test"}'`:
+** `metadata.id == 123`
+** `metadata.name contains 'test'` (case-insensitive)
+* If an event has a parameter named `items` (kind: "array") containing `'["alpha", "beta"]'`:
+** `items contains 'beta'` (case-insensitive deep search)
+
+*Access by Index (Legacy):*
+For contracts without event definitions in their specification, or when working with older contracts, event parameters can be accessed by their numeric index (e.g., `0`, `1`, `2`):
 
 * If event parameter `0` (kind: "Map") is `'{"id": 123, "name": "Test"}'`:
 ** `0.id == 123`
@@ -1613,6 +1632,11 @@ Stellar event parameters are typically accessed by their numeric index as the ba
 ** `1[1].val == 'Beta'` (case-insensitive)
 ** `1 contains 'beta'` (case-insensitive deep search)
 
+[TIP]
+====
+Named access is recommended when available as it makes expressions more readable and maintainable. The monitor will automatically use named parameters if they're available in the contract specification, otherwise it falls back to indexed access.
+====
+
 ===== EVM Examples
 
 These examples assume common EVM event parameters or transaction fields.
@@ -1738,6 +1762,16 @@ Assume event parameter `0` is `12345` (u64), `1` (kind: "array") is `'["Val1", "
 "2.keyB < 1000"
 ----
 
+Now, after Stellar Protocol 23 we can access to Event parameters by name (first, make sure the contract supports the feature)
+
+----
+"0 > 10000"
+"param_name[0] == 'val1'"
+"param_name contains 'val2'"
+"param_name.keyA == 'DATAX'"
+"param_name.keyB < 1000"
+----
+
 [NOTE]
 ====
 With SEP-48 support, Stellar functions can now reference parameters by name (e.g., `amount > 1000`) instead of position (e.g., `2 > 1000`). Events still use indexed parameters until SEP-48 support is added for events.

docs/modules/ROOT/pages/index.adoc

@@ -602,6 +602,7 @@ cp examples/config/filters/stellar_filter_block_number.sh config/filters/stellar
 * The `contract_spec` field is optional for Stellar contracts. If not provided, the monitor automatically fetches the contract's SEP-48 interface from the chain
 * You can explore Stellar contract interfaces using the link:https://lab.stellar.org/smart-contracts/contract-explorer[Stellar Contract Explorer^]
 * The expression `"out_min > 1000000000"` monitors swaps with minimum output over 1 billion tokens
+* Now, you can also filter by parameters event's name (Stellar Protocol 23 has introduced this new feature). See this xref:index.adoc#stellar_specifics[section] for more details
 ====
 
 ==== Step 3: Notification Setup
@@ -636,6 +637,12 @@ cp examples/config/triggers/slack_notifications.json config/triggers/slack_notif
 }
 ----
 
+* If you want to include event details in the notification message body, you can also access event parameters by name. Here's an example:
+[source,bash]
+----
+"body": "${monitor.name} triggered because of a large swap from ${events.0.args.from} tokens | https://stellar.expert/explorer/public/tx/${transaction.hash}"
+----
+
 ==== Step 4: Run the Monitor
 
 **Local Deployment:**

docs/modules/ROOT/pages/quickstart.adoc

@@ -12,8 +12,10 @@ mod transaction;
 pub use block::{Block as StellarBlock, LedgerInfo as StellarLedgerInfo};
 pub use event::Event as StellarEvent;
 pub use monitor::{
+	ContractEvent as StellarContractEvent, ContractEventParam as StellarContractEventParam,
 	ContractFunction as StellarContractFunction, ContractInput as StellarContractInput,
 	ContractSpec as StellarContractSpec, DecodedParamEntry as StellarDecodedParamEntry,
+	EventParamLocation as StellarEventParamLocation,
 	FormattedContractSpec as StellarFormattedContractSpec, MatchArguments as StellarMatchArguments,
 	MatchParamEntry as StellarMatchParamEntry, MatchParamsMap as StellarMatchParamsMap,
 	MonitorMatch as StellarMonitorMatch, ParsedOperationResult as StellarParsedOperationResult,

src/models/blockchain/stellar/mod.rs

@@ -7,7 +7,8 @@ use stellar_xdr::curr::ScSpecEntry;
 use crate::{
 	models::{MatchConditions, Monitor, StellarBlock, StellarTransaction},
 	services::filter::stellar_helpers::{
-		get_contract_spec_functions, get_contract_spec_with_function_input_parameters,
+		get_contract_spec_events, get_contract_spec_functions,
+		get_contract_spec_with_event_parameters, get_contract_spec_with_function_input_parameters,
 	},
 };
 
@@ -172,14 +173,21 @@ impl std::ops::Deref for ContractSpec {
 pub struct FormattedContractSpec {
 	/// List of callable functions defined in the contract
 	pub functions: Vec<ContractFunction>,
+
+	/// List of events defined in the contract
+	pub events: Vec<ContractEvent>,
 }
 
 impl From<ContractSpec> for FormattedContractSpec {
 	fn from(spec: ContractSpec) -> Self {
-		let functions =
-			get_contract_spec_with_function_input_parameters(get_contract_spec_functions(spec.0));
+		let functions = get_contract_spec_with_function_input_parameters(
+			get_contract_spec_functions(spec.0.clone()),
+		);
 
-		FormattedContractSpec { functions }
+		let events =
+			get_contract_spec_with_event_parameters(get_contract_spec_events(spec.0.clone()));
+
+		FormattedContractSpec { functions, events }
 	}
 }
 
@@ -233,6 +241,53 @@ pub struct ContractInput {
 	pub kind: String,
 }
 
+/// Event parameter location (indexed or data)
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Default)]
+pub enum EventParamLocation {
+	/// Parameter is indexed (in topics)
+	#[default]
+	Indexed,
+	/// Parameter is in event data
+	Data,
+}
+
+/// Event parameter specification for a Stellar contract event
+///
+/// Describes a single parameter in a contract event, including its name,
+/// type, and whether it's indexed or in the event data.
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Default)]
+pub struct ContractEventParam {
+	/// Parameter name as defined in the contract
+	pub name: String,
+
+	/// Parameter type in Stellar's type system format
+	pub kind: String,
+
+	/// Whether this parameter is indexed or in data
+	pub location: EventParamLocation,
+}
+
+/// Event definition within a Stellar contract specification
+///
+/// Represents an event that can be emitted by a Stellar smart contract,
+/// including its name and parameters. This is parsed from the contract's
+/// ScSpecEventV0 entries.
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Default)]
+pub struct ContractEvent {
+	/// Name of the event as defined in the contract
+	pub name: String,
+
+	/// Prefix topics that are emitted before indexed parameters
+	/// These are metadata topics used to identify the event
+	pub prefix_topics: Vec<String>,
+
+	/// Ordered list of parameters in the event
+	pub params: Vec<ContractEventParam>,
+
+	/// Signature of the event
+	pub signature: String,
+}
+
 #[cfg(test)]
 mod tests {
 	use super::*;

src/models/blockchain/stellar/monitor.rs

@@ -24,11 +24,11 @@ pub use blockchain::evm::{
 };
 
 pub use blockchain::stellar::{
-	StellarBlock, StellarContractFunction, StellarContractInput, StellarContractSpec,
-	StellarDecodedParamEntry, StellarDecodedTransaction, StellarEvent,
-	StellarFormattedContractSpec, StellarLedgerInfo, StellarMatchArguments, StellarMatchParamEntry,
-	StellarMatchParamsMap, StellarMonitorMatch, StellarParsedOperationResult, StellarTransaction,
-	StellarTransactionInfo,
+	StellarBlock, StellarContractEvent, StellarContractEventParam, StellarContractFunction,
+	StellarContractInput, StellarContractSpec, StellarDecodedParamEntry, StellarDecodedTransaction,
+	StellarEvent, StellarEventParamLocation, StellarFormattedContractSpec, StellarLedgerInfo,
+	StellarMatchArguments, StellarMatchParamEntry, StellarMatchParamsMap, StellarMonitorMatch,
+	StellarParsedOperationResult, StellarTransaction, StellarTransactionInfo,
 };
 
 // Re-export core types

src/models/mod.rs

@@ -5,6 +5,7 @@
 
 use anyhow::Context;
 use async_trait::async_trait;
+use base64::{engine::general_purpose::STANDARD as BASE64_STANDARD, Engine as _};
 use serde_json::json;
 use std::marker::PhantomData;
 use stellar_xdr::curr::{Limits, WriteXdr};
@@ -642,14 +643,16 @@ impl<T: Send + Sync + Clone + BlockchainTransport> BlockChainClient for StellarC
 		let contract_instance_ledger_key = get_contract_instance_ledger_key(contract_id)
 			.map_err(|e| anyhow::anyhow!("Failed to get contract instance ledger key: {}", e))?;
 
-		let contract_instance_ledger_key_xdr = contract_instance_ledger_key
-			.to_xdr_base64(Limits::none())
+		let contract_instance_ledger_key_xdr_bytes = contract_instance_ledger_key
+			.to_xdr(Limits::none())
 			.map_err(|e| {
 				anyhow::anyhow!(
 					"Failed to convert contract instance ledger key to XDR: {}",
 					e
 				)
 			})?;
+		let contract_instance_ledger_key_xdr =
+			BASE64_STANDARD.encode(&contract_instance_ledger_key_xdr_bytes);
 
 		let params = json!({
 			"keys": [contract_instance_ledger_key_xdr],
@@ -675,11 +678,13 @@ impl<T: Send + Sync + Clone + BlockchainTransport> BlockChainClient for StellarC
 		let contract_code_ledger_key = get_contract_code_ledger_key(wasm_hash.as_str())
 			.map_err(|e| anyhow::anyhow!("Failed to get contract code ledger key: {}", e))?;
 
-		let contract_code_ledger_key_xdr = contract_code_ledger_key
-			.to_xdr_base64(Limits::none())
+		let contract_code_ledger_key_xdr_bytes = contract_code_ledger_key
+			.to_xdr(Limits::none())
 			.map_err(|e| {
-			anyhow::anyhow!("Failed to convert contract code ledger key to XDR: {}", e)
-		})?;
+				anyhow::anyhow!("Failed to convert contract code ledger key to XDR: {}", e)
+			})?;
+		let contract_code_ledger_key_xdr =
+			BASE64_STANDARD.encode(&contract_code_ledger_key_xdr_bytes);
 
 		let params = json!({
 			"keys": [contract_code_ledger_key_xdr],