docs: mdbook (#1994)

* mdbook init + summary

* Getting started section

* intro typos

* intro typos and wording

* intro typos and wording

* Big numbers section

* Big numbers: added section titles + docs refinement

* Removed index prefix from file names

* Update docs/mdbook/book.toml

Co-authored-by: Andrea Simeoni <>
Co-authored-by: Georgios Konstantopoulos <me@gakonst.com>

docs/mdbook/.gitignore

@@ -0,0 +1 @@
+book

docs/mdbook/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["The ethers-rs contributors"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Ethers.rs: The Ethereum Library for Rust"

docs/mdbook/src/SUMMARY.md

@@ -0,0 +1,89 @@
+# Summary
+
+# Getting started
+  - [Intro](./getting-started/intro.md)
+  - [Start a new project](./getting-started/start_a_new_project.md)
+  - [Connect to an Ethereum node](./getting-started/connect_to_an_ethereum_node.md)
+
+# Reference guide
+- [Providers]()
+  - [Http]()
+  - [IPC]()
+  - [Mock]()
+  - [Quorum]()
+  - [Retry]()
+  - [RW]()
+  - [WS]()
+- [Middleware]()
+  - [Builder]()
+  - [Create custom middleware]()
+  - [Gas escalator]()
+  - [Gas oracle]()
+  - [Nonce manager]()
+  - [Policy]()
+  - [Signer]()
+  - [Time lag]()
+  - [Transformer]()
+- [Contracts]()
+  - [Abigen]()
+  - [Compile]()
+  - [Creating Instances]()
+  - [Deploy Anvil]()
+  - [Deploy from ABI and bytecode]()
+  - [Deploy Moonbeam]()
+  - [Events]()
+  - [Events with meta]()
+  - [Methods]()
+- [Events]()
+  - [Logs and filtering]()
+  - [Solidity topics]()
+- [Subscriptions]()
+  - [Watch blocks]()
+  - [Subscribe events by type]()
+  - [Subscribe logs]()
+- [Queries]()
+  - [Blocks]()
+  - [Contracts]()
+  - [Events]()
+  - [Paginated logs]()
+  - [UniswapV2 pair]()
+  - [Transactions]()
+- [Transactions]()
+  - [Call override]()
+  - [Create raw transaction]()
+  - [Create typed transaction]()
+  - [Decode input]()
+  - [EIP-1559]()
+  - [ENS]() 
+  - [Estimate gas]()
+  - [Get gas price]()
+  - [Get gas price USD]()
+  - [Remove liquidity]()
+  - [Set gas for a transaction]()
+  - [Send raw transaction]()
+  - [Send typed transaction]()
+  - [Trace]()
+  - [Transaction receipt]()
+  - [Transaction status]()
+  - [Transfer ETH]()
+- [Wallets]()
+  - [Address book]()
+  - [Mnemonic]()
+  - [Ledger]()
+  - [Local]()
+  - [Permit hash]()
+  - [Sign message]()
+  - [Trezor]()
+  - [Yubi]()
+- [Big numbers](./big-numbers/intro.md)
+  - [Comparison and equivalence](./big-numbers/comparison-and-equivalence.md) 
+  - [Conversion](./big-numbers/conversion.md)
+  - [Creating Instances](./big-numbers/creating_instances.md)
+  - [Math operations](./big-numbers/math-operations.md)
+  - [Utilities](./big-numbers/utilities.md)
+- [Anvil]()
+    - [Boot anvil]()
+    - [Deploy contracts]()
+    - [Fork]() 
+    - [Testing]()
+

docs/mdbook/src/big-numbers/comparison-and-equivalence.md

@@ -0,0 +1,6 @@
+
+# Comparison and equivalence 
+
+```rust
+{{#include ../../../../examples/big-numbers/examples/comparison_equivalence.rs}}
+```

docs/mdbook/src/big-numbers/conversion.md

@@ -0,0 +1,5 @@
+# Conversion
+
+```rust
+{{#include ../../../../examples/big-numbers/examples/conversion.rs}}
+```

docs/mdbook/src/big-numbers/creating_instances.md

@@ -0,0 +1,5 @@
+# Creating instances
+
+```rust
+{{#include ../../../../examples/big-numbers/examples/create_instances.rs}}
+```

docs/mdbook/src/big-numbers/intro.md

@@ -0,0 +1 @@
+{{#include ../../../../examples/big-numbers/README.md}}

docs/mdbook/src/big-numbers/math-operations.md

@@ -0,0 +1,5 @@
+# Math operations
+
+```rust
+{{#include ../../../../examples/big-numbers/examples/math_operations.rs}}
+```

docs/mdbook/src/big-numbers/utilities.md

@@ -0,0 +1,5 @@
+# Utilities
+
+```rust
+{{#include ../../../../examples/big-numbers/examples/utilities.rs}}
+```

docs/mdbook/src/getting-started/connect_to_an_ethereum_node.md

@@ -0,0 +1,33 @@
+# Connect to an Ethereum node
+Ethers-rs allows application to connect the blockchain using web3 providers. Providers act as an interface between applications and an Ethereum node, allowing you to send requests and receive responses via JSON-RPC messages.
+
+Some common actions you can perform using a provider include:
+
+* Getting the current block number
+* Getting the balance of an Ethereum address
+* Sending a transaction to the blockchain
+* Calling a smart contract function
+* Subscribe logs and smart contract events
+* Getting the transaction history of an address
+
+Providers are an important part of web3 libraries because they allow you to easily interact with the Ethereum blockchain without having to manage the underlying connection to the node yourself.
+
+Code below shows a basic setup to connect a provider to a node:
+```rust
+/// The `prelude` module provides a convenient way to import a number 
+/// of common dependencies at once. This can be useful if you are working 
+/// with multiple parts of the library and want to avoid having 
+/// to import each dependency individually.
+use ethers::prelude::*;
+
+const RPC_URL: &str = "https://mainnet.infura.io/v3/your-project-id";
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {    
+    let provider = Provider::<Http>::try_from(RPC_URL)?;
+    let block_number: U64 = provider.get_block_number().await?;
+    println!("{block_number}");
+
+    Ok(())
+}
+```

docs/mdbook/src/getting-started/intro.md

@@ -0,0 +1,8 @@
+# Intro
+Welcome to the hands-on guide for the ethers-rs library!
+
+This documentation contains a collection of examples demonstrating how to use the library to build Ethereum-based applications in Rust. The examples cover a range of topics, from basic smart contract interactions to more advanced usage of ethers-rs.
+
+Each example includes a detailed description of the functionality being demonstrated, as well as complete code snippets that you can use as a starting point for your own projects.
+
+We hope that these docs will help you get started with ethers-rs and give you a better understanding of how to use the library to build your own web3 applications in Rust. If you have any questions or need further assistance, please don't hesitate to reach out to the ethers-rs community.

docs/mdbook/src/getting-started/start_a_new_project.md

@@ -0,0 +1,65 @@
+# Start a new project
+To set up a new project with ethers-rs, you will need to install the Rust programming language and the cargo package manager on your system.
+
+1. Install Rust by following the instructions at [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install).
+2. Once Rust is installed, create a new Rust project by running the following command:
+    ```bash
+    cargo new my-project
+    ```
+   This will create a new directory called my-project with the necessary files for a new Rust project.
+
+3. Navigate to the project directory and add ethers-rs as a dependency in your `Cargo.toml` file:
+   ```toml
+   [dependencies]
+   ethers = "1.0.0" 
+
+   # Most of ethers-rs features rely upon an async Rust runtime.
+   # Since Rust doesn't provide an async runtime itself, you can
+   # include the excellent tokio library
+   tokio = { version = "1.23.0", features = ["macros"] }
+   ```
+
+   If you want to make experiments and/or play around with early ethers-rs features link our GitHub repo in the `Cargo.toml`.
+
+    ```toml
+    [dependencies]
+    ethers = { git = "https://github.com/gakonst/ethers-rs" }
+
+    # Use the "branch" attribute to specify a branch other than master
+    [dependencies]
+    ethers = { git = "https://github.com/gakonst/ethers-rs", branch = "branch-name" }
+
+    # You can specify a tag or commit hash with the "rev" attribute
+    [dependencies]
+    ethers = { git = "https://github.com/gakonst/ethers-rs", rev = "1.0.2" }
+    ```
+   > **Note:** using a Git repository as a dependency is generally not recommended 
+   > for production projects, as it can make it difficult to ensure that you are using 
+   > a specific and stable version of the dependency. 
+   > It is usually better to specify a version number or range to ensure that your project 
+   > is reproducible.
+
+## Enable transports
+Ethers-rs enables interactions with Ethereum nodes through different "transport" types, or communication protocols.
+The following transport types are currently supported by ethers.rs:
+
+* **HTTP(S):** The HTTP(S) transport is used to communicate with Ethereum nodes over the HTTP or HTTPS protocols. This is the most common way to interact with Ethereum nodes. If you are looking to connect to a HTTPS endpoint, then you need to enable the `rustls` or `openssl` features:
+    ```toml
+    [dependencies]
+    ethers = { version = "1.0.0", features = ["rustls"] }
+    ```
+
+* **WebSocket:** The WebSocket transport is used to communicate with Ethereum nodes over the WebSocket protocol, which is a widely-supported standard for establishing a bi-directional communication channel between a client and a server. This can be used for a variety of purposes, including receiving real-time updates from an Ethereum node, or submitting transactions to the Ethereum network. Websockets support is turned on via the feature-flag ws:
+    ```toml
+    [dependencies]
+    ethers = { version = "1.0.0", features = ["ws"] }
+    ```
+
+* **IPC (Interprocess Communication):** The IPC transport is used to communicate with a local Ethereum node using the IPC protocol, which is a way for processes to communicate with each other on a single computer. This is commonly used in Ethereum development to allow applications to communicate with a local Ethereum node, such as geth or parity. IPC support is turned on via the feature-flag `ipc`:
+    ```toml
+    [dependencies]
+    ethers = { version = "1.0.0", features = ["ipc"] }
+    ```
+
+
+

examples/big-numbers/examples/comparison_equivalence.rs

@@ -1,5 +1,7 @@
 use ethers::types::U256;
 
+/// `U256` implements traits in `std::cmp`, that means `U256` instances
+/// can be easily compared using standard Rust operators.
 fn main() {
     // a == b
     let a = U256::from(100_u32);

examples/big-numbers/examples/conversion.rs

@@ -1,5 +1,13 @@
 use ethers::{types::U256, utils::format_units};
 
+/// `U256` provides useful conversion functions to enable transformation into native Rust types.
+///
+/// It is important to note that converting a big-number to a floating point type (such as a `f32`
+/// or `f64`) can result in a loss of precision, since you cannot fit 256 bits of information into
+/// 64 bits.
+///
+/// However, there may be cases where you want to perform conversions for presentation purposes.
+/// For example, you may want to display a large number to the user in a more readable format.
 fn main() {
     let num = U256::from(42_u8);
 

examples/big-numbers/examples/math_operations.rs

@@ -1,6 +1,9 @@
 use ethers::{types::U256, utils::format_units};
 use std::ops::{Div, Mul};
 
+/// `U256` implements traits in `std::ops`, that means it supports arithmetic operations
+/// using standard Rust operators `+`, `-`. `*`, `/`, `%`, along with additional utilities to
+/// perform common mathematical tasks.
 fn main() {
     let a = U256::from(10);
     let b = U256::from(2);

examples/big-numbers/examples/utilities.rs

@@ -8,7 +8,7 @@ fn main() {
     format_units_example();
 }
 
-/// DApps business logics handles big numbers in 'wei' units (i.e. sending transactions, on-chain
+/// dApps business logics handle big numbers in 'wei' units (i.e. sending transactions, on-chain
 /// math, etc.). We provide convenient methods to map user inputs (usually in 'ether' or 'gwei')
 /// into 'wei' format.
 fn parse_units_example() {
@@ -45,7 +45,7 @@ fn parse_units_example() {
     assert_eq!(num, U256::from(1000000000000000000_u128));
 }
 
-/// DApps business logics handles big numbers in 'wei' units (i.e. sending transactions, on-chain
+/// dApps business logics handle big numbers in 'wei' units (i.e. sending transactions, on-chain
 /// math, etc.). On the other hand it is useful to convert big numbers into user readable formats
 /// when displaying on a UI. Generally dApps display numbers in 'ether' and 'gwei' units,
 /// respectively for displaying amounts and gas. The `format_units` function will format a big