From eaaa01a7d6d7da93fa359dc5113c545d37442dcf Mon Sep 17 00:00:00 2001 From: 0xKitsune <77890308+0xKitsune@users.noreply.github.com> Date: Tue, 17 Jan 2023 14:19:34 -0500 Subject: [PATCH] Book - Providers Chapter (#2023) * started building out providers chapter for the book, updated the intro for the chapter as well as the Http section. Added advanced usage section. * Updated WS and Ipc chapter, working on usage, furthering descriptions * updated ipc section, added code snippets * updating the ws section, adding code snippet for example using the subscribe_pending_tx method * Updated the provider section to include info on the ens and _node_client fields, udpated the advanced usage section to include CallBuilder and raw_call. * added examples to ipc and ws chapters, cleared todos * added note about windows ipc named pipes * added spaces to comments * fixed comment, removed all usage of unwrap() * updated Http provider to initialize without :: --- book/SUMMARY.md | 4 +- book/providers/advanced_usage.md | 116 +++++++++++++++++++++++++ book/providers/http.md | 142 ++++++++++++++++++++++++++++++- book/providers/ipc.md | 79 ++++++++++++++++- book/providers/providers.md | 29 +++++++ book/providers/ws.md | 81 +++++++++++++++++- 6 files changed, 444 insertions(+), 7 deletions(-) create mode 100644 book/providers/advanced_usage.md create mode 100644 book/providers/providers.md diff --git a/book/SUMMARY.md b/book/SUMMARY.md index 6b222857..a3de1adb 100644 --- a/book/SUMMARY.md +++ b/book/SUMMARY.md @@ -6,14 +6,16 @@ - [Connect to an Ethereum node](./getting-started/connect_to_an_ethereum_node.md) # Reference guide -- [Providers]() +- [Providers](./providers/providers.md) - [Http](./providers/http.md) + - [WebSocket](./providers/ws.md) - [IPC](./providers/ipc.md) - [Mock](./providers/mock.md) - [Quorum](./providers/quorum.md) - [Retry](./providers/retry.md) - [RW](./providers/rw.md) - [WebSocket](./providers/ws.md) + - [Advanced Usage](./providers/advanced_usage.md) - [Middleware](./middleware/middleware.md) - [Builder](./middleware/builder.md) - [Create custom middleware](./middleware/custom.md) diff --git a/book/providers/advanced_usage.md b/book/providers/advanced_usage.md new file mode 100644 index 00000000..d777dbcd --- /dev/null +++ b/book/providers/advanced_usage.md @@ -0,0 +1,116 @@ +# Advanced Usage + + +## `CallBuilder` + +The `CallBuilder` is an enum to help create complex calls. `CallBuilder` implements `[RawCall](https://docs.rs/ethers/latest/ethers/providers/call_raw/trait.RawCall.html)` methods for overriding parameters to the `eth_call`rpc method. + +Lets take a quick look at how to use the `CallBuilder`. + +```rust +use ethers::{ + providers::{ Http, Provider}, + types::{TransactionRequest, H160}, + utils::parse_ether, +}; +use std::sync::Arc; + +#[tokio::main] +async fn main() -> eyre::Result<()> { + let rpc_url = "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"; + let provider: Arc> = Arc::new(Provider::::try_from(rpc_url)?); + + let from_adr: H160 = "0x6fC21092DA55B392b045eD78F4732bff3C580e2c".parse()?; + let to_adr: H160 = "0x000000000000000000000000000000000000dead".parse()?; + let val = parse_ether(1u64)?; + + let tx = TransactionRequest::default() + .from(from_adr) + .to(to_adr) + .value(val) + .into(); + + let result = provider.call_raw(&tx).await?; + + Ok(()) +} + +``` + +First, we initialize a new provider and create a transaction that sends `1 ETH` from one address to another. Then we use `provider.call_raw()`, which returns a `CallBuilder`. From here, we can use `await` to send the call to the node with exactly the same behavior as simply using `provider.call()`. We can also override the parameters sent to the node by using the methods provided by the `RawCall` trait. These methods allow you to set the block number that the call should execute on as well as give you access to the [state override set](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#3-object---state-override-set). + +Here is an example with the exact same raw call, but executed on the previous block. + +```rust +use ethers::{ + providers::{call_raw::RawCall, Http, Middleware, Provider}, + types::{BlockId, TransactionRequest, H160}, + utils::parse_ether, +}; +use std::sync::Arc; + +#[tokio::main] +async fn main() -> eyre::Result<()> { + let rpc_url = "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"; + let provider: Arc> = Arc::new(Provider::::try_from(rpc_url)?); + + let from_adr: H160 = "0x6fC21092DA55B392b045eD78F4732bff3C580e2c".parse()?; + let to_adr: H160 = "0x000000000000000000000000000000000000dead".parse()?; + let val = parse_ether(1u64)?; + + let tx = TransactionRequest::default() + .from(from_adr) + .to(to_adr) + .value(val) + .into(); + + let previous_block_number: BlockId = (provider.get_block_number().await? - 1).into(); + let result = provider.call_raw(&tx).block(previous_block_number).await?; + + Ok(()) +} +``` + +Let's look at how to use the state override set. In short, the state override set is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. The state override set allows you to override an account's balance, an account's nonce, the code at a given address, the entire state of an account's storage or an individual slot in an account's storage. Note that the state override set is not a default feature and is not available on every node. + + +```rust +use ethers::{ + providers::{ + call_raw::{spoof::State, RawCall}, + Http, Provider, + }, + types::{TransactionRequest, H160, U256, U64}, + utils::parse_ether, +}; +use std::sync::Arc; + +#[tokio::main] +async fn main() -> eyre::Result<()> { + let rpc_url = "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"; + let provider: Arc> = Arc::new(Provider::::try_from(rpc_url)?); + + let from_adr: H160 = "0x6fC21092DA55B392b045eD78F4732bff3C580e2c".parse()?; + let to_adr: H160 = "0x000000000000000000000000000000000000dead".parse()?; + let val = parse_ether(1u64)?; + + let tx = TransactionRequest::default() + .from(from_adr) + .to(to_adr) + .value(val) + .into(); + + let mut state = State::default(); + + // Set the account balance to max u256 + state.account(from_adr).balance(U256::MAX); + // Set the nonce to 0 + state.account(from_adr).nonce(U64::zero()); + + let result = provider.call_raw(&tx).state(&state).await?; + + Ok(()) +} +``` + +In this example, the account balance and nonce for the `from_adr` is overridden. The state override set is a very powerful tool that you can use to simulate complicated transactions without undergoing any actual state changes. \ No newline at end of file diff --git a/book/providers/http.md b/book/providers/http.md index 46e04a40..c8c0da9f 100644 --- a/book/providers/http.md +++ b/book/providers/http.md @@ -1,5 +1,141 @@ -# Http provider +# Http + +The `Http` provider establishes an Http connection with a node, allowing you to send RPC requests to the node to fetch data, simulate calls, send transactions and much more. + +## Initializing an Http Provider +Lets take a quick look at few ways to create a new `Http` provider. Since the `Http` provider implements the [`FromStr`](https://doc.rust-lang.org/std/str/trait.FromStr.html) one of the easiest ways to initialize a new provider is by using the `from_str()` method. ```rust -{{#include ../../examples/providers/examples/http.rs}} -``` \ No newline at end of file +use ethers::providers::{Http, Middleware, Provider}; + +#[tokio::main] +async fn main() -> eyre::Result<()> { + // Initialize a new Http provider + let rpc_url = "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"; + let provider = Provider::try_from(rpc_url)?; + + Ok(()) +} +``` + +The `Http` provider also supplies a way to initialize a new authorized connection. + +```rust +// Initializes a new HTTP Client with authentication +use ethers::providers::{Authorization, Http}; +use url::Url; +#[tokio::main] +async fn main() -> eyre::Result<()> { + let url = Url::parse("http://localhost:8545")?; + let provider = Http::new_with_auth(url, Authorization::basic("admin", "good_password")); + Ok(()) +} +``` + +Additionally, you can initialize a new provider with your own custom `reqwest::Client`. + +```rust +use ethers::providers::Http; +use url::Url; + +#[tokio::main] +async fn main() -> eyre::Result<()> { + let url = Url::parse("http://localhost:8545")?; + let client = reqwest::Client::builder().build()?; + let provider = Http::new_with_client(url, client); + Ok(()) +} +``` + +## Basic Usage + +Now that you have successfully established an Http connection with the node, you can use any of the methods provided by the `Middleware` trait. In the code snippet below, the provider is used to get the chain id, current block number and the content of the node's mempool. + +```rust +use ethers::providers::{Http, Middleware, Provider}; + +#[tokio::main] +async fn main() -> eyre::Result<()> { + let rpc_url = "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"; + let provider = Provider::try_from(rpc_url)?; + + let chain_id = provider.get_chainid().await?; + let block_number = provider.get_block_number().await?; + let tx_pool_content = provider.txpool_content().await?; + + Ok(()) +} +``` + +You can also use the provider to interact with smart contracts. The snippet below uses the provider to establish a new instance of a UniswapV2Pool and uses the `get_reserves()` method from the smart contract to fetch the current state of the pool's reserves. + +```rust +use std::{str::FromStr, sync::Arc}; + +use ethers::{ + prelude::abigen, + providers::{Http, Provider}, + types::H160, +}; + +abigen!( + IUniswapV2Pair, + r#"[function getReserves() external view returns (uint112 reserve0, uint112 reserve1, uint32 blockTimestampLast)]"# +); + +#[tokio::main] +async fn main() -> eyre::Result<()> { + let rpc_url = "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"; + let provider = Arc::new(Provider::try_from(rpc_url)?); + + // Initialize a new instance of the Weth/Dai Uniswap V2 pair contract + let pair_address = H160::from_str("0xA478c2975Ab1Ea89e8196811F51A7B7Ade33eB11")?; + let uniswap_v2_pair = IUniswapV2Pair::new(pair_address, provider); + + // Use the get_reserves() function to fetch the pool reserves + let (reserve_0, reserve_1, block_timestamp_last) = + uniswap_v2_pair.get_reserves().call().await?; + + Ok(()) +} +``` + +This example is a little more complicated, so lets walk through what is going on. The `IUniswapV2Pair` is a struct that is generated from the `abigen!()` macro. The `IUniswapV2Pair::new()` function is used to create a new instance of the contract, taking in an `Address` and an `Arc` as arguments, where `M` is any type that implements the `Middleware` trait. Note that the provider is wrapped in an [`Arc`](https://doc.rust-lang.org/std/sync/struct.Arc.html) when being passed into the `new()` function. + +It is very common to wrap a provider in an `Arc` to share the provider across threads. Lets look at another example where the provider is used asynchronously across two tokio threads. In the next example, a new provider is initialized and used to asynchronously fetch the number of Ommer blocks from the most recent block, as well as the previous block. + +```rust +use std::sync::Arc; + +use ethers::providers::{Http, Middleware, Provider}; + +#[tokio::main] +async fn main() -> eyre::Result<()> { + let rpc_url = "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"; + let provider = Arc::new(Provider::try_from(rpc_url)?); + + let current_block_number = provider.get_block_number().await?; + let prev_block_number = current_block_number - 1; + + // Clone the Arc and pass it into a new thread to get the uncle count of the current block + let provider_1 = provider.clone(); + let task_0 = + tokio::spawn(async move { provider_1.get_uncle_count(current_block_number).await }); + + // Spin up a new thread to get the uncle count of the previous block + let task_1 = tokio::spawn(async move { provider.get_uncle_count(prev_block_number).await }); + + // Wait for the tasks to finish + for task in [task_0, task_1] { + if let Ok(uncle_count) = task.await? { + println!("Success!"); + } + } + + Ok(()) +} +``` + +
+ +Before heading to the next chapter, feel free to check out the docs for the [`Http` provider](https://docs.rs/ethers/latest/ethers/providers/struct.Http.html). Keep in mind that we will cover advanced usage of providers at the end of this chapter. Now that we have the basics covered, lets move on to the next Provider, Websockets! \ No newline at end of file diff --git a/book/providers/ipc.md b/book/providers/ipc.md index ad4dc5eb..f4abb323 100644 --- a/book/providers/ipc.md +++ b/book/providers/ipc.md @@ -1,5 +1,80 @@ # IPC provider +The IPC (Inter-Process Communication) transport is a way for a process to communicate with a running Ethereum client over a local Unix domain socket. If you are new to IPC, you can [follow this link to learn more](https://en.wikipedia.org/wiki/Inter-process_communication). Using the IPC transport allows the ethers library to send JSON-RPC requests to the Ethereum client and receive responses, without the need for a network connection or HTTP server. This can be useful for interacting with a local Ethereum node that is running on the same machine. Using Ipc [is faster than RPC](https://github.com/0xKitsune/geth-ipc-rpc-bench), however you will need to have a local node that you can connect to. + +## Initializing an Ipc Provider +Below is an example of how to initialize a new Ipc provider. ```rust -{{#include ../../examples/providers/examples/ipc.rs}} -``` \ No newline at end of file +#[tokio::main] +async fn main() -> eyre::Result<()> { + + // We instantiate the provider using the path of a local Unix domain socket + // -------------------------------------------------------------------------------- + // NOTE: The IPC transport supports push notifications, but we still need to specify a polling + // interval because only subscribe RPC calls (e.g., transactions, blocks, events) support push + // notifications in Ethereum's RPC API. For other calls we must use repeated polling for many + // operations even with the IPC transport. + let provider = Provider::connect_ipc("~/.ethereum/geth.ipc").await?; + + Ok(()) +} +``` + +Note that if you are using Windows, you must use [Windows Ipc (Named pipes)](https://learn.microsoft.com/en-us/windows/win32/ipc/named-pipes). Instead of passing the provider the path to the `.ipc` file, you must pass a named pipe (`\\\pipe\`). For a local geth connection, the named pipe will look something like this: `\\.\pipe\geth` + +## Usage + +The `Ipc` provider has the same methods as the `Ws` provider, allowing it to subscribe and unsubscribe via a `NotificationStream`. + + +```rust +use ethers::providers::{Middleware, Provider, StreamExt, Ws}; + +#[tokio::main] +async fn main() -> eyre::Result<()> { + let provider = Provider::connect_ipc("~/.ethereum/geth.ipc").await?; + + // Create a new stream yielding pending transactions from the mempool + let mut tx_pool_stream = provider.subscribe_pending_txs().await?; + + while let Some(tx_hash) = tx_pool_stream.next().await { + println!("Pending tx: {:?}", tx_hash); + } + + Ok(()) +} +``` + + +Note that the `Ipc` provider, like all providers, has access to the methods defined by the `Middleware` trait. With this in mind, we can use the `Ipc` provider just like the `Http` provider as well, with the only difference being that we are connected to the node via a Unix socket now! + + +```rust +use std::{str::FromStr, sync::Arc}; + +use ethers::{ + prelude::abigen, + providers::{Http, Provider}, + types::H160, +}; + +abigen!( + IUniswapV2Pair, + r#"[function getReserves() external view returns (uint112 reserve0, uint112 reserve1, uint32 blockTimestampLast)]"# +); + +#[tokio::main] +async fn main() -> eyre::Result<()> { + let provider = Provider::connect_ipc("~/.ethereum/geth.ipc").await?; + + // Initialize a new instance of the Weth/Dai Uniswap V2 pair contract + let pair_address = H160::from_str("0xA478c2975Ab1Ea89e8196811F51A7B7Ade33eB11")?; + let uniswap_v2_pair = IUniswapV2Pair::new(pair_address, provider); + + // Use the get_reserves() function to fetch the pool reserves + let (reserve_0, reserve_1, block_timestamp_last) = + uniswap_v2_pair.get_reserves().call().await?; + + Ok(()) +} +``` diff --git a/book/providers/providers.md b/book/providers/providers.md new file mode 100644 index 00000000..fa81fc04 --- /dev/null +++ b/book/providers/providers.md @@ -0,0 +1,29 @@ +# Providers + +Providers play a central role in `ethers-rs`, enabling you to establish asynchronous [Ethereum JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC) compliant clients. + +Providers let your program connect to a node to get data, interact with smart contracts, listen to the mempool and much more. There are a few different types of default providers that are built into the library. The default providers are `Http`,`WS`,`Ipc`,`RWClient`,`Quorum`,`Mock` and `RetryClient`. In addition to all of these options, you can also create your own custom provider, which we will walk through later in this chapter. For now let take a look at what the `Provider` actually looks like. + + +```rust +#[derive(Clone, Debug)] +pub struct Provider

{ + inner: P, + ens: Option

, + interval: Option, + from: Option
, + /// Node client hasn't been checked yet= `None` + /// Unsupported node client = `Some(None)` + /// Supported node client = `Some(Some(NodeClient))` + _node_client: Arc>>, +} +``` + + +The `Provider` struct defines a generic type `P` that can be any type that implements the [`JsonRpcClient` trait](https://docs.rs/ethers/latest/ethers/providers/trait.JsonRpcClient.html). The `inner` field stores the type that implements the `JsonRpcClient` type, allowing the Provider to make RPC calls to the node. The `ens` field is an optional value that specifies the ENS address for the provider's default sender. The `interval` field is an optional value that defines the polling interval when for streams (subscribing to logs, block headers, etc.). The `from` field is an optional type that allows you to set a default "from" address when constructing transactions and making calls. Lastly, the `_node_client` field is another optional value that allows the user to specify the node they are using to access node specific API calls. + + +Note that all providers implement the [`Middleware` trait](https://docs.rs/ethers/latest/ethers/providers/trait.Middleware.html), which gives every provider access to [commonly used methods](https://docs.rs/ethers/latest/ethers/providers/struct.Provider.html#impl-Middleware-for-Provider%3CP%3E) to interact with the node. Later in this chapter, we will go over these methods and examples for how to use them in detail. Additionally, `Middleware` will be covered extensively in a later chapter. + +Now that you have a basis for what the `Provider` type actually is, the next few sections will walk through each implementation of the `Provider`, starting with the HTTP provider. + diff --git a/book/providers/ws.md b/book/providers/ws.md index ef6ca53a..261485c8 100644 --- a/book/providers/ws.md +++ b/book/providers/ws.md @@ -1,5 +1,84 @@ # WebSocket provider +The Ws provider allows you to send JSON-RPC requests and receive responses over WebSocket connections. The WS provider can be used with any Ethereum node that supports WebSocket connections. This allows programs interact with the network in real-time without the need for HTTP polling for things like new block headers and filter logs. Ethers-rs has support for WebSockets via Tokio. Make sure that you have the “ws” and “rustls” / “openssl” features enabled in your project's toml file if you wish to use WebSockets. + + + +## Initializing a WS Provider +Lets look at a few ways to create a new `WS` provider. Below is the most straightforward way to initialize a new `Ws` provider. + ```rust -{{#include ../../examples/providers/examples/ws.rs}} +#[tokio::main] +async fn main() -> eyre::Result<()> { + let ws_endpoint = ""; + let provider = Provider::::connect(ws_endpoint).await?; + Ok(()) +} +``` + +Similar to the other providers, you can also establish an authorized connection with a node via websockets. + +```rust +#[tokio::main] +async fn main() -> eyre::Result<()> { + let ws_endpoint = ""; + let auth = Authorization::basic("username", "password"); + + if let Ok(_provider) = Provider::::connect_with_auth(url, auth).await { + println!("Create Ws provider with auth"); + } + + Ok(()) +} +``` + +## Usage + +The `Ws` provider allows a user to send requests to the node just like the other providers. In addition to these methods, the `Ws` provider can also subscribe to new logs and events, watch transactions in the mempool and other types of data streams from the node. The default polling interval for the `Ws` provider is `7 seconds`. You can update the polling interval, by using the `provider.interval()` method. + +In the snippet below, a new `Ws` provider is used to watch pending transactions in the mempool as well as new block headers in two separate threads. + +```rust +use ethers::providers::{Middleware, Provider, StreamExt, Ws}; +use std::{sync::Arc, time::Duration}; +#[tokio::main] +async fn main() -> eyre::Result<()> { + let ws_endpoint = ""; + let mut provider = Provider::::connect(ws_endpoint).await?; + + // Update the polling interval + provider.set_interval(Duration::new(3, 0)); + + // Clone the providers to use in separate threads + let provider = Arc::new(provider); + let provider_0 = provider.clone(); + let provider_1 = provider.clone(); + + let mut handles = vec![]; + + let pending_tx_handle = tokio::spawn(async move { + let mut tx_pool_stream = provider_0.watch_pending_transactions().await?; + while let Some(tx_hash) = tx_pool_stream.next().await { + println!("Pending tx: {:?}", tx_hash); + } + }); + + let new_block_headers_handle = tokio::spawn(async move { + let mut new_block_headers_stream = provider_1.watch_blocks().await?; + while let Some(block_hash) = new_block_headers_stream.next().await { + println!("New block: {:?}", block_hash); + } + }); + + // Add the JoinHandles to a vec and wait for the handles to complete + handles.push(pending_tx_handle); + handles.push(new_block_headers_handle); + for handle in handles { + if let Err(err) = handle.await { + panic!("{}", err); + } + } + + Ok(()) +} ``` \ No newline at end of file