subscriptions

book/SUMMARY.md

@@ -42,9 +42,10 @@
   - [Logs and filtering](events/logs-and-filtering.md)
   - [Solidity topics]()
 - [Subscriptions](./subscriptions/subscriptions.md)
-  - [Watch blocks]()
+  - [Watch blocks](./subscriptions/watch-blocks.md)
-  - [Subscribe events by type]()
+  - [Subscribe events by type](./subscriptions/events-by-type.md)
-  - [Subscribe logs]()
+  - [Subscribe logs](./subscriptions/logs.md)
+  - [Mulitple subscriptions](./subscriptions/multiple-subscriptions.md)
 - [Queries]()
   - [Blocks]()
   - [Contracts]()

book/subscriptions/events-by-type.md

@@ -0,0 +1,5 @@
+# Subscribe events by type
+
+```rust
+{{#include ../../examples/subscriptions/examples/subscribe_events_by_type.rs}}
+```

book/subscriptions/logs.md

@@ -0,0 +1,5 @@
+# Subscribe logs
+
+```rust
+{{#include ../../examples/subscriptions/examples/subscribe_logs.rs}}
+```

book/subscriptions/multiple-subscriptions.md

@@ -0,0 +1,58 @@
+# Mulitple Multiple Subscriptions
+
+You may need to handle multiple subscriptions simultaneously in your application. To manage multiple SubscriptionStreams, you can use the futures crate to efficiently process updates from all streams concurrently:
+
+```toml
+[dependencies]
+futures = "0.3"
+```
+
+Then, import the necessary components:
+
+```rust
+use futures::{stream, StreamExt, TryStreamExt};
+```
+
+Create multiple subscription streams and merge them into a single stream using the stream::select_all function:
+
+```rust
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create multiple subscription streams.
+    let mut block_stream = provider.subscribe_blocks().await?;
+    let mut log_stream = provider.subscribe_logs(filter).await?;
+    let mut event_stream = watcher.subscribe().await?;
+
+    // Merge the streams into a single stream.
+    let mut combined_stream = stream::select_all(vec![
+        block_stream.map_ok(|block| EventType::Block(block)),
+        log_stream.map_ok(|log| EventType::Log(log)),
+        event_stream.map_ok(|event| EventType::Event(event)),
+    ]);
+
+    // Your code to handle the events goes here.
+
+    Ok(())
+
+}
+```
+
+Now, you can listen to updates from all the subscription streams concurrently:
+
+```rust
+while let Some(event) = combined_stream.next().await {
+    match event {
+        Ok(event) => match event {
+            EventType::Block(block) => println!("New block: {:?}", block),
+            EventType::Log(log) => println!("New log: {:?}", log),
+            EventType::Event(event) => println!("New event: {:?}", event),
+        },
+        Err(e) => {
+            eprintln!("Error: {:?}", e);
+        }
+    }
+}
+```
+
+This approach allows you to efficiently handle multiple subscriptions in your application and react to various network activities in a unified manner.
+
+By leveraging the powerful subscription capabilities of ethers-rs, you can create responsive and dynamic applications that stay up-to-date with the latest events on the Ethereum network. The library's flexibility and ease of use make it an ideal choice for developers looking to build robust and performant applications that interact with smart contracts and the Ethereum blockchain.

book/subscriptions/subscriptions.md

@@ -0,0 +1,126 @@
+## Ethers-rs: Subscriptions
+
+In this section of the mdbook, we will discuss how to use `ethers-rs` to subscribe and listen to blocks, events, and logs. Subscriptions provide a way to receive real-time updates on various activities on the Ethereum blockchain, allowing you to monitor the network and react to changes as they happen.
+
+## Overview
+
+ethers-rs offers a convenient way to work with subscriptions, enabling you to listen to new blocks, transaction receipts, and logs. The main components you will work with are:
+
+1. Provider: The main struct used to interact with the Ethereum network.
+2. SubscriptionStream: A stream of updates you can subscribe to for real-time notifications.
+
+## Getting Started
+
+Before working with subscriptions, make sure you have ethers-rs added to your project's dependencies in Cargo.toml:
+
+```toml
+[dependencies]
+ethers = { version = "2.0.0", features = ["full"] }
+```
+
+Next, import the necessary components from the ethers-rs library:
+
+```rust
+use ethers::{prelude::\*,types::H256,};
+```
+
+## Subscribing to New Blocks
+
+To subscribe to new blocks, create a Provider instance and call the subscribe_blocks method:
+
+```rust
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+let provider = Provider::<Http>::try_from("http://localhost:8545")?;
+
+    let mut stream = provider.subscribe_blocks().await?;
+
+    // Your code to handle new blocks goes here.
+
+    Ok(())
+
+}
+```
+
+You can now listen to new blocks as they are mined:
+
+```rust
+while let Some(block) = stream.next().await {
+    match block {
+        Ok(block) => {
+            println!("New block: {:?}", block);
+        }
+        Err(e) => {
+            eprintln!("Error: {:?}", e);
+        }
+    }
+}
+```
+
+### Subscribing to Logs
+
+To subscribe to logs, create a Filter object that specifies the criteria for the logs you want to listen to. Then, pass the filter to the Provider's subscribe_logs method:
+
+```rust
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let provider = Provider::<Http>::try_from("http://localhost:8545")?;
+
+    let filter = Filter::new().address("0xcontract_address_here".parse()?);
+
+    let mut stream = provider.subscribe_logs(filter).await?;
+
+    // Your code to handle logs goes here.
+
+    Ok(())
+
+}
+```
+
+You can now listen to logs that match your filter criteria:
+
+```rust
+while let Some(log) = stream.next().await {
+    match log {
+        Ok(log) => {
+            println!("New log: {:?}", log);
+        }
+        Err(e) => {
+            eprintln!("Error: {:?}", e);
+        }
+    }
+}
+```
+
+### Subscribing to Events
+
+As we discussed in the previous section on events, you can subscribe to specific events emitted by smart contracts using the EventWatcher struct. To create a SubscriptionStream, call the subscribe method on your EventWatcher:
+
+```rust
+let mut stream = watcher.subscribe().await?;
+```
+
+Now, you can listen to events as they are emitted by the smart contract:
+
+```rust
+while let Some(event) = stream.next().await {
+    match event {
+        Ok(log) => {
+            println!("New event: {:?}", log);
+        }
+        Err(e) => {
+            eprintln!("Error: {:?}", e);
+        }
+    }
+}
+```
+
+By using the subscription features provided by ethers-rs, you can efficiently monitor and react to various activities on the Ethereum network. Subscriptions are a powerful tool for building responsive and dynamic applications that can interact with smart contracts and stay up-to-date with the latest network events.
+
+### Unsubscribing from Subscriptions
+
+In some cases, you may want to stop listening to a subscription. To do this, simply drop the SubscriptionStream:
+
+```rust
+drop(stream);
+```
+
+This will stop the stream from receiving any further updates.

book/subscriptions/watch-blocks.md

@@ -0,0 +1,5 @@
+# Watch blocks
+
+```rust
+{{#include ../../examples/subscriptions/examples/subscribe_blocks.rs}}
+```