ethers-rs/ethers-middleware
DaniPopes 439a0c7de0
chore(deps): bump and use workspace dependencies (#2222)
* chore: update all deps

* chore: update dependabot

* chore: separate ethers package from workspace

* chore: package metadata

* chore: use package.*.workspace = true

* fix: docs.rs build

* chore: update examples manifests

* chore: use workspace dependencies for ethers-* crates

* fix: test

* chore: use workspace dependencies for all dependencies

* chore: pin rust-crypto

* chore: add license field to example crates

* fixes

* more fixes

* fix: test

* last fixes

* fix: wasm

* fix: docs.rs build

* fix

* fix: wasm-pack error

see also https://github.com/rustwasm/wasm-pack/issues/1238

* fix: wasm deps and example

* ci: update

* fix: wasm tests

* fix: eip712 tests

* fix: windows ci

* fix

* chore: update docsrs metadata

* chore: bump version to match crates.io

* chore: rm bad release.toml config

* chore: rm release.toml

bad configuration

* chore: add exclude to workspace

* fix: middleware

* fix: solc feature flags

* chore: run cargo upgrade

* chore: update deps

* chore: update remaining deps

* undo fix

* update lock

* bump yubi

* fix: update coins-* and fix spki breaking changes
2023-03-16 12:28:35 -07:00
..
contracts ci/test: improve CI jobs and tests (#2189) 2023-02-28 17:26:27 -07:00
src chore(deps): bump and use workspace dependencies (#2222) 2023-03-16 12:28:35 -07:00
tests/it chore(deps): bump and use workspace dependencies (#2222) 2023-03-16 12:28:35 -07:00
Cargo.toml chore(deps): bump and use workspace dependencies (#2222) 2023-03-16 12:28:35 -07:00
README.md docs: fix broken links, update documentation (#2203) 2023-02-27 13:03:17 -07:00

README.md

ethers-middleware

Your ethers application interacts with the blockchain through a Provider abstraction. Provider is a special type of Middleware that can be composed with others to obtain a layered architecture. This approach promotes "Open Closed Principle", "Single Responsibility" and composable patterns. The building process happens in a wrapping fashion, and starts from a Provider being the first element in the stack. This process continues having new middlewares being pushed on top of a layered data structure.

For more information, please refer to the book.

Available Middleware

  • Signer: Signs transactions locally, with a private key or a hardware wallet.
  • Nonce Manager: Manages nonces locally. Allows to sign multiple consecutive transactions without waiting for them to hit the mempool.
  • Gas Escalator: Bumps transactions gas price in the background to avoid getting them stuck in the memory pool. A GasEscalatorMiddleware supports different escalation strategies (see GasEscalator) and bump frequencies (see Frequency).
  • Gas Oracle: Allows getting your gas price estimates from places other than eth_gasPrice, including REST based gas stations (i.e. Etherscan, ETH Gas Station etc.).
  • Transformer: Allows intercepting and transforming a transaction to be broadcasted via a proxy wallet, e.g. DSProxy.

Examples

Each Middleware implements the trait MiddlewareBuilder. This trait helps a developer to compose a custom Middleware stack.

The following example shows how to build a composed Middleware starting from a Provider:

# use ethers_providers::{Middleware, Provider, Http};
# use ethers_signers::{LocalWallet, Signer};
# use ethers_middleware::{gas_oracle::GasNow, MiddlewareBuilder};
let key = "fdb33e2105f08abe41a8ee3b758726a31abdd57b7a443f470f23efce853af169";
let signer = key.parse::<LocalWallet>()?;
let address = signer.address();
let gas_oracle = GasNow::new();

let provider = Provider::<Http>::try_from("http://localhost:8545")?
    .gas_oracle(gas_oracle)
    .with_signer(signer)
    .nonce_manager(address); // Outermost layer
# Ok::<_, Box<dyn std::error::Error>>(())

The wrap_into function can be used to wrap Middleware layers explicitly. This is useful when pushing Middlewares not directly handled by the builder interface.

# use ethers_providers::{Middleware, Provider, Http};
# use std::convert::TryFrom;
# use ethers_signers::{LocalWallet, Signer};
# use ethers_middleware::{*,gas_escalator::*,gas_oracle::*};
let key = "fdb33e2105f08abe41a8ee3b758726a31abdd57b7a443f470f23efce853af169";
let signer = key.parse::<LocalWallet>()?;
let address = signer.address();
let escalator = GeometricGasPrice::new(1.125, 60_u64, None::<u64>);

let provider = Provider::<Http>::try_from("http://localhost:8545")?
    .wrap_into(|p| GasEscalatorMiddleware::new(p, escalator, Frequency::PerBlock))
    .wrap_into(|p| SignerMiddleware::new(p, signer))
    .wrap_into(|p| GasOracleMiddleware::new(p, GasNow::new()))
    .wrap_into(|p| NonceManagerMiddleware::new(p, address)); // Outermost layer
# Ok::<_, Box<dyn std::error::Error>>(())

A Middleware stack can be also constructed manually. This is achieved by explicitly wrapping layers.

# use ethers_providers::{Provider, Http};
# use ethers_signers::{LocalWallet, Signer};
# use ethers_middleware::{
#     gas_escalator::{GasEscalatorMiddleware, GeometricGasPrice, Frequency},
#     gas_oracle::{GasOracleMiddleware, GasCategory, GasNow},
#     signer::SignerMiddleware,
#     nonce_manager::NonceManagerMiddleware,
# };
// Start the stack
let provider = Provider::<Http>::try_from("http://localhost:8545")?;

// Escalate gas prices
let escalator = GeometricGasPrice::new(1.125, 60u64, None::<u64>);
let provider = GasEscalatorMiddleware::new(provider, escalator, Frequency::PerBlock);

// Sign transactions with a private key
let key = "fdb33e2105f08abe41a8ee3b758726a31abdd57b7a443f470f23efce853af169";
let signer = key.parse::<LocalWallet>()?;
let address = signer.address();
let provider = SignerMiddleware::new(provider, signer);

// Use GasNow as the gas oracle
let gas_oracle = GasNow::new();
let provider = GasOracleMiddleware::new(provider, gas_oracle);

// Manage nonces locally
let provider = NonceManagerMiddleware::new(provider, address);
# Ok::<_, Box<dyn std::error::Error>>(())