From 08f8e8771a29db88c538130e401a16cb1595ff5e Mon Sep 17 00:00:00 2001 From: Andrea Simeoni Date: Fri, 13 Jan 2023 19:25:32 +0100 Subject: [PATCH] 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 | 16 +++++++------- book/getting-started/intro.md | 27 ++++++++++------------- book/mermaid-style.txt | 13 +++++++++++ book/middleware/builder.md | 5 +++++ book/middleware/custom.md | 5 +++++ book/middleware/gas-escalator.md | 5 +++++ book/middleware/gas-oracle.md | 5 +++++ book/middleware/middleware.md | 37 ++++++++++++++++++++++++++++++++ book/middleware/nonce-manager.md | 5 +++++ book/middleware/policy.md | 5 +++++ book/middleware/signer.md | 5 +++++ book/middleware/time-lag.md | 3 +++ book/middleware/transformer.md | 3 +++ 13 files changed, 110 insertions(+), 24 deletions(-) create mode 100644 book/mermaid-style.txt create mode 100644 book/middleware/builder.md create mode 100644 book/middleware/custom.md create mode 100644 book/middleware/gas-escalator.md create mode 100644 book/middleware/gas-oracle.md create mode 100644 book/middleware/middleware.md create mode 100644 book/middleware/nonce-manager.md create mode 100644 book/middleware/policy.md create mode 100644 book/middleware/signer.md create mode 100644 book/middleware/time-lag.md create mode 100644 book/middleware/transformer.md diff --git a/book/SUMMARY.md b/book/SUMMARY.md index d3461cd5..6b222857 100644 --- a/book/SUMMARY.md +++ b/book/SUMMARY.md @@ -14,14 +14,14 @@ - [Retry](./providers/retry.md) - [RW](./providers/rw.md) - [WebSocket](./providers/ws.md) -- [Middleware]() - - [Builder]() - - [Create custom middleware]() - - [Gas escalator]() - - [Gas oracle]() - - [Nonce manager]() - - [Policy]() - - [Signer]() +- [Middleware](./middleware/middleware.md) + - [Builder](./middleware/builder.md) + - [Create custom middleware](./middleware/custom.md) + - [Gas escalator](./middleware/gas-escalator.md) + - [Gas oracle](./middleware/gas-oracle.md) + - [Nonce manager](./middleware/nonce-manager.md) + - [Policy](./middleware/policy.md) + - [Signer](./middleware/signer.md) - [Time lag]() - [Transformer]() - [Contracts]() diff --git a/book/getting-started/intro.md b/book/getting-started/intro.md index 245df94a..9d40f99a 100644 --- a/book/getting-started/intro.md +++ b/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 - %% The code below is for styling the graph - %%------------------------------------------------- - %%{init: {'theme':'dark', 'themeVariables':{'textColor':' #ffffff ', 'nodeBorder':'#ff2d00', 'edgeLabelBackground':'#000000' ,'lineColor':'#87ff00', 'fontSize':'14px', 'curve':'linear'}}}%% +{{#include ../mermaid-style.txt}} - %%------------------------------------------------- - %% Actual Diagram code is below - - A[Ethers-rs
Manual] --> A1[Providers] +graph LR + A[Ethers-rs
Manual] --> A1[Providers] A --> A2[Middleware] - A --> A3[Contracts] - A --> A4[Events] - A --> A5[Subscriptions] - A --> A6[Queries] - A --> A7[Transactions] - A --> A8[Wallets] - A --> A9[Big numbers] - A --> A10[Anvil] + A --> A3[Contracts] + A --> A4[Events] + A --> A5[Subscriptions] + A --> A6[Queries] + A --> A7[Transactions] + A --> A8[Wallets] + A --> A9[Big numbers] + A --> A10[Anvil] ``` ```admonish bug This diagram is incomplete and will undergo continuous changes. diff --git a/book/mermaid-style.txt b/book/mermaid-style.txt new file mode 100644 index 00000000..cca1d9cf --- /dev/null +++ b/book/mermaid-style.txt @@ -0,0 +1,13 @@ +%%{ + init: { + 'theme':'dark', + 'themeVariables': { + 'textColor':' #ffffff', + 'nodeBorder':'#ff2d00', + 'edgeLabelBackground':'#00000', + 'lineColor':'#87ff00', + 'fontSize':'14px', + 'curve':'linear' + } + } +}%% \ No newline at end of file diff --git a/book/middleware/builder.md b/book/middleware/builder.md new file mode 100644 index 00000000..b12ee2df --- /dev/null +++ b/book/middleware/builder.md @@ -0,0 +1,5 @@ +# Middleware builder + +```rust +{{#include ../../examples/middleware/examples/builder.rs}} +``` diff --git a/book/middleware/custom.md b/book/middleware/custom.md new file mode 100644 index 00000000..451c0867 --- /dev/null +++ b/book/middleware/custom.md @@ -0,0 +1,5 @@ +# Create custom middleware + +```rust +{{#include ../../examples/middleware/examples/create_custom_middleware.rs}} +``` diff --git a/book/middleware/gas-escalator.md b/book/middleware/gas-escalator.md new file mode 100644 index 00000000..def07126 --- /dev/null +++ b/book/middleware/gas-escalator.md @@ -0,0 +1,5 @@ +# Gas escalator + +```rust +{{#include ../../examples/middleware/examples/gas_escalator.rs}} +``` \ No newline at end of file diff --git a/book/middleware/gas-oracle.md b/book/middleware/gas-oracle.md new file mode 100644 index 00000000..9925b398 --- /dev/null +++ b/book/middleware/gas-oracle.md @@ -0,0 +1,5 @@ +# Gas oracle + +```rust +{{#include ../../examples/middleware/examples/gas_oracle.rs}} +``` \ No newline at end of file diff --git a/book/middleware/middleware.md b/book/middleware/middleware.md new file mode 100644 index 00000000..dce9c03f --- /dev/null +++ b/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
PubSubClient-->http + provider--JsonRpcClient
PubSubClient-->retry + provider--JsonRpcClient
PubSubClient-->quorum + provider--JsonRpcClient
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. \ No newline at end of file diff --git a/book/middleware/nonce-manager.md b/book/middleware/nonce-manager.md new file mode 100644 index 00000000..b51c26bc --- /dev/null +++ b/book/middleware/nonce-manager.md @@ -0,0 +1,5 @@ +# Nonce manager + +```rust +{{#include ../../examples/middleware/examples/nonce_manager.rs}} +``` \ No newline at end of file diff --git a/book/middleware/policy.md b/book/middleware/policy.md new file mode 100644 index 00000000..cad251f7 --- /dev/null +++ b/book/middleware/policy.md @@ -0,0 +1,5 @@ +# Policy middleware + +```rust +{{#include ../../examples/middleware/examples/policy.rs}} +``` \ No newline at end of file diff --git a/book/middleware/signer.md b/book/middleware/signer.md new file mode 100644 index 00000000..4d27808e --- /dev/null +++ b/book/middleware/signer.md @@ -0,0 +1,5 @@ +# Signer + +```rust +{{#include ../../examples/middleware/examples/signer.rs}} +``` \ No newline at end of file diff --git a/book/middleware/time-lag.md b/book/middleware/time-lag.md new file mode 100644 index 00000000..c2d3769b --- /dev/null +++ b/book/middleware/time-lag.md @@ -0,0 +1,3 @@ +# Time lag + +TODO \ No newline at end of file diff --git a/book/middleware/transformer.md b/book/middleware/transformer.md new file mode 100644 index 00000000..83319ef3 --- /dev/null +++ b/book/middleware/transformer.md @@ -0,0 +1,3 @@ +# Transformer + +TODO \ No newline at end of file