Book - Middleware Chapter (#2033)

* docs: added middleware intro page + diagram

* docs: added middleware sections + embed examples

* docs: simplified diagram

* docs: added `quorum` transport to diagram

* Removed duplicate style

* mermaid style file in the book root dir

* typo

Co-authored-by: Andrea Simeoni <>

book/SUMMARY.md

@@ -14,14 +14,14 @@
   - [Retry](./providers/retry.md)
   - [RW](./providers/rw.md)
   - [WebSocket](./providers/ws.md)
-- [Middleware]()
+- [Middleware](./middleware/middleware.md)
-  - [Builder]()
+  - [Builder](./middleware/builder.md)
-  - [Create custom middleware]()
+  - [Create custom middleware](./middleware/custom.md)
-  - [Gas escalator]()
+  - [Gas escalator](./middleware/gas-escalator.md)
-  - [Gas oracle]()
+  - [Gas oracle](./middleware/gas-oracle.md)
-  - [Nonce manager]()
+  - [Nonce manager](./middleware/nonce-manager.md)
-  - [Policy]()
+  - [Policy](./middleware/policy.md)
-  - [Signer]()
+  - [Signer](./middleware/signer.md)
   - [Time lag]()
   - [Transformer]()
 - [Contracts]()

book/getting-started/intro.md

@@ -14,24 +14,19 @@ We hope that these docs will help you get started with ethers-rs and give you a
 The following is a brief overview diagram of the  topis covered in this guide.
 
 ```mermaid
-graph LR
+{{#include ../mermaid-style.txt}}
-  %% The code below is for styling the graph 
-  %%-------------------------------------------------  
-  %%{init: {'theme':'dark', 'themeVariables':{'textColor':' #ffffff ', 'nodeBorder':'#ff2d00', 'edgeLabelBackground':'#000000'  ,'lineColor':'#87ff00', 'fontSize':'14px', 'curve':'linear'}}}%%
 
-  %%-------------------------------------------------
+graph LR  
-  %% Actual Diagram code is below
+  A[Ethers-rs <br> Manual] --> A1[Providers]
-  
-    A[Ethers-rs <br> Manual] --> A1[Providers]
 	A --> A2[Middleware]
-    A --> A3[Contracts]
+  A --> A3[Contracts]
-    A --> A4[Events]
+  A --> A4[Events]
-    A --> A5[Subscriptions]
+  A --> A5[Subscriptions]
-    A --> A6[Queries]
+  A --> A6[Queries]
-    A --> A7[Transactions]
+  A --> A7[Transactions]
-    A --> A8[Wallets]
+  A --> A8[Wallets]
-    A --> A9[Big numbers]
+  A --> A9[Big numbers]
-    A --> A10[Anvil]
+  A --> A10[Anvil]
 ```
 ```admonish bug 
 This diagram is incomplete and will undergo continuous changes.

book/mermaid-style.txt

@@ -0,0 +1,13 @@
+%%{
+    init: {
+      'theme':'dark', 
+      'themeVariables': {
+        'textColor':' #ffffff', 
+        'nodeBorder':'#ff2d00', 
+        'edgeLabelBackground':'#00000',
+        'lineColor':'#87ff00', 
+        'fontSize':'14px', 
+        'curve':'linear'
+        }
+      }
+}%%

book/middleware/builder.md

@@ -0,0 +1,5 @@
+# Middleware builder
+
+```rust
+{{#include ../../examples/middleware/examples/builder.rs}}
+```

book/middleware/custom.md

@@ -0,0 +1,5 @@
+# Create custom middleware
+
+```rust
+{{#include ../../examples/middleware/examples/create_custom_middleware.rs}}
+```

book/middleware/gas-escalator.md

@@ -0,0 +1,5 @@
+# Gas escalator
+
+```rust
+{{#include ../../examples/middleware/examples/gas_escalator.rs}}
+```

book/middleware/gas-oracle.md

@@ -0,0 +1,5 @@
+# Gas oracle
+
+```rust
+{{#include ../../examples/middleware/examples/gas_oracle.rs}}
+```

book/middleware/middleware.md

@@ -0,0 +1,37 @@
+# Middlewares
+In ethers-rs, middleware is a way to customize the behavior of certain aspects of the library by
+injecting custom logic into the process of interacting with the Ethereum JSON-RPC API.
+Middlewares act in a chain of responsibility and can be combined to achieve the desired behavior. 
+
+The library allows developers to create [custom middlewares](./custom.md), going beyond
+standard operations and unlocking powerful use cases.
+
+A JSON-RPC client instance can be constructed as a stack of middlewares, backed by a common instance of `Provider` of one specific type among `JsonRpcClient` and `PubSubClient`. 
+
+```mermaid
+{{#include ../mermaid-style.txt}}
+
+flowchart TB
+    subgraph ide1 [Client]
+    middleware2--inner-->middleware1--inner-->middleware0--inner-->provider
+    end
+    subgraph ide2 [Transport]
+    provider--PubSubClient-->ws
+    provider--PubSubClient-->ipc
+    provider--JsonRpcClient<br>PubSubClient-->http
+    provider--JsonRpcClient<br>PubSubClient-->retry
+    provider--JsonRpcClient<br>PubSubClient-->quorum
+    provider--JsonRpcClient<br>PubSubClient-->rw
+    end
+```
+
+The following middlewares are currently supported:
+
+- [Gas Escalator](./gas-escalator.md): Avoids transactions being stucked in the mempool, by bumping the gas price in background.
+- [Gas Oracle](./gas-oracle.md): Allows retrieving the current gas price from common RESTful APIs, instead of retrieving it from blocks.
+- [Nonce Manager](./nonce-manager.md): Manages nonces of transactions locally, without waiting for them to hit the mempool.
+- [Policy](./policy.md): Allows to define rules or policies that should be followed when submitting JSON-RPC API calls.
+- [Signer](./signer.md): Signs transactions locally, with a private key or a hardware wallet.
+- [Time lag](./time-lag.md): Poses a block delay on JSON-RPC interactions, allowing to shift the block number back of a predefined offset.
+- [Transformer](./transformer.md): Allows intercepting and
+  transforming a transaction to be broadcasted via a proxy wallet.

book/middleware/nonce-manager.md

@@ -0,0 +1,5 @@
+# Nonce manager
+
+```rust
+{{#include ../../examples/middleware/examples/nonce_manager.rs}}
+```

book/middleware/policy.md

@@ -0,0 +1,5 @@
+# Policy middleware
+
+```rust
+{{#include ../../examples/middleware/examples/policy.rs}}
+```

book/middleware/signer.md

@@ -0,0 +1,5 @@
+# Signer
+
+```rust
+{{#include ../../examples/middleware/examples/signer.rs}}
+```

book/middleware/time-lag.md

@@ -0,0 +1,3 @@
+# Time lag
+
+TODO

book/middleware/transformer.md

@@ -0,0 +1,3 @@
+# Transformer
+
+TODO