#![allow(clippy::return_self_not_must_use)] use crate::{log::LogMeta, stream::EventStream, ContractError, EthLogDecode}; use ethers_core::{ abi::{Detokenize, RawLog}, types::{BlockNumber, Filter, Log, Topic, H256}, }; use ethers_providers::{FilterWatcher, Middleware, PubsubClient, SubscriptionStream}; use std::{borrow::Cow, marker::PhantomData}; /// A trait for implementing event bindings pub trait EthEvent: Detokenize + Send + Sync { /// The name of the event this type represents fn name() -> Cow<'static, str>; /// Retrieves the signature for the event this data corresponds to. /// This signature is the Keccak-256 hash of the ABI signature of /// this event. fn signature() -> H256; /// Retrieves the ABI signature for the event this data corresponds /// to. fn abi_signature() -> Cow<'static, str>; /// Decodes an Ethereum `RawLog` into an instance of the type. fn decode_log(log: &RawLog) -> Result where Self: Sized; /// Returns true if this is an anonymous event fn is_anonymous() -> bool; /// Returns an Event builder for the ethereum event represented by this types ABI signature. fn new(filter: Filter, provider: &M) -> Event where Self: Sized, { let filter = filter.event(&Self::abi_signature()); Event { filter, provider, datatype: PhantomData } } } // Convenience implementation impl EthLogDecode for T { fn decode_log(log: &RawLog) -> Result where Self: Sized, { T::decode_log(log) } } /// Helper for managing the event filter before querying or streaming its logs #[derive(Debug)] #[must_use = "event filters do nothing unless you `query` or `stream` them"] pub struct Event<'a, M, D> { /// The event filter's state pub filter: Filter, pub(crate) provider: &'a M, /// Stores the event datatype pub(crate) datatype: PhantomData, } // TODO: Improve these functions impl Event<'_, M, D> { /// Sets the filter's `from` block #[allow(clippy::wrong_self_convention)] pub fn from_block>(mut self, block: T) -> Self { self.filter = self.filter.from_block(block); self } /// Sets the filter's `to` block #[allow(clippy::wrong_self_convention)] pub fn to_block>(mut self, block: T) -> Self { self.filter = self.filter.to_block(block); self } /// Sets the filter's `blockHash`. Setting this will override previously /// set `from_block` and `to_block` fields. #[allow(clippy::wrong_self_convention)] pub fn at_block_hash>(mut self, hash: T) -> Self { self.filter = self.filter.at_block_hash(hash); self } /// Sets the filter's 0th topic (typically the event name for non-anonymous events) pub fn topic0>(mut self, topic: T) -> Self { self.filter.topics[0] = Some(topic.into()); self } /// Sets the filter's 1st topic pub fn topic1>(mut self, topic: T) -> Self { self.filter.topics[1] = Some(topic.into()); self } /// Sets the filter's 2nd topic pub fn topic2>(mut self, topic: T) -> Self { self.filter.topics[2] = Some(topic.into()); self } /// Sets the filter's 3rd topic pub fn topic3>(mut self, topic: T) -> Self { self.filter.topics[3] = Some(topic.into()); self } } impl<'a, M, D> Event<'a, M, D> where M: Middleware, D: EthLogDecode, { /// Turns this event filter into `Stream` that yields decoded events. /// /// This will first install a new logs filter via [`eth_newFilter`](https://docs.alchemy.com/alchemy/apis/ethereum/eth-newfilter) using the configured `filter` object. See also [`FilterWatcher`](ethers_providers::FilterWatcher). /// /// Once the filter is created, this will periodically call [`eth_getFilterChanges`](https://docs.alchemy.com/alchemy/apis/ethereum/eth-getfilterchanges) to get the newest logs and decode them /// /// **Note:** Compared to [`Self::subscribe`], which is only available on `PubsubClient`s, such /// as Websocket, this is a poll-based subscription, as the node does not notify us when a new /// matching log is available, instead we have to actively ask for new logs using additional RPC /// requests, and this is done on an interval basis. /// /// # Example /// /// ``` /// # async fn test(contract: ethers_contract::Contract) { /// # use ethers_core::types::*; /// # use futures_util::stream::StreamExt; /// # use ethers_contract::{Contract, EthEvent}; /// /// // The event we want to get /// #[derive(Clone, Debug, EthEvent)] /// pub struct Approval { /// #[ethevent(indexed)] /// pub token_owner: Address, /// #[ethevent(indexed)] /// pub spender: Address, /// pub tokens: U256, /// } /// /// let ev = contract.event::().from_block(1337).to_block(2000); /// let mut event_stream = ev.stream().await.unwrap(); /// /// while let Some(Ok(approval)) = event_stream.next().await { /// let Approval{token_owner,spender,tokens} = approval; /// } /// /// # } /// ``` pub async fn stream( &'a self, ) -> Result< // Wraps the FilterWatcher with a mapping to the event EventStream<'a, FilterWatcher<'a, M::Provider, Log>, D, ContractError>, ContractError, > { let filter = self.provider.watch(&self.filter).await.map_err(ContractError::MiddlewareError)?; Ok(EventStream::new(filter.id, filter, Box::new(move |log| self.parse_log(log)))) } /// As [`Self::stream`], but does not discard [`Log`] metadata. pub async fn stream_with_meta( &'a self, ) -> Result< // Wraps the FilterWatcher with a mapping to the event EventStream<'a, FilterWatcher<'a, M::Provider, Log>, (D, LogMeta), ContractError>, ContractError, > { let filter = self.provider.watch(&self.filter).await.map_err(ContractError::MiddlewareError)?; Ok(EventStream::new( filter.id, filter, Box::new(move |log| { let meta = LogMeta::from(&log); Ok((self.parse_log(log)?, meta)) }), )) } } impl<'a, M, D> Event<'a, M, D> where M: Middleware, ::Provider: PubsubClient, D: EthLogDecode, { /// Returns a subscription for the event /// /// See also [Self::stream()]. pub async fn subscribe( &'a self, ) -> Result< // Wraps the SubscriptionStream with a mapping to the event EventStream<'a, SubscriptionStream<'a, M::Provider, Log>, D, ContractError>, ContractError, > { let filter = self .provider .subscribe_logs(&self.filter) .await .map_err(ContractError::MiddlewareError)?; Ok(EventStream::new(filter.id, filter, Box::new(move |log| self.parse_log(log)))) } pub async fn subscribe_with_meta( &'a self, ) -> Result< // Wraps the SubscriptionStream with a mapping to the event EventStream<'a, SubscriptionStream<'a, M::Provider, Log>, (D, LogMeta), ContractError>, ContractError, > { let filter = self .provider .subscribe_logs(&self.filter) .await .map_err(ContractError::MiddlewareError)?; Ok(EventStream::new( filter.id, filter, Box::new(move |log| { let meta = LogMeta::from(&log); Ok((self.parse_log(log)?, meta)) }), )) } } impl Event<'_, M, D> where M: Middleware, D: EthLogDecode, { /// Queries the blockchain for the selected filter and returns a vector of matching /// event logs pub async fn query(&self) -> Result, ContractError> { let logs = self.provider.get_logs(&self.filter).await.map_err(ContractError::MiddlewareError)?; let events = logs .into_iter() .map(|log| self.parse_log(log)) .collect::, ContractError>>()?; Ok(events) } /// Queries the blockchain for the selected filter and returns a vector of logs /// along with their metadata pub async fn query_with_meta(&self) -> Result, ContractError> { let logs = self.provider.get_logs(&self.filter).await.map_err(ContractError::MiddlewareError)?; let events = logs .into_iter() .map(|log| { let meta = LogMeta::from(&log); let event = self.parse_log(log)?; Ok((event, meta)) }) .collect::>>()?; Ok(events) } pub fn parse_log(&self, log: Log) -> Result> { D::decode_log(&RawLog { topics: log.topics, data: log.data.to_vec() }).map_err(From::from) } }