Crate ethers_middleware

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.

Warning

This library is in the process of being deprecated. See #2667 for more information.

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:

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

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.

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

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

// 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);

Re-exports

pub use gas_escalator::GasEscalatorMiddleware;

pub use gas_oracle::GasOracle;

pub use nonce_manager::NonceManagerMiddleware;

pub use transformer::TransformerMiddleware;

pub use signer::SignerMiddleware;

pub use policy::AllowEverything;

pub use policy::Policy;

pub use policy::PolicyMiddleware;

pub use policy::PolicyMiddlewareError;

pub use policy::RejectEverything;

pub use timelag::TimeLag;

pub use builder::MiddlewareBuilder;

Modules

builder

MiddlewareBuilder provides a way to compose many Middlewares in a concise way.

gas_escalator

The Gas Escalator middleware is used to re-broadcast transactions with an increasing gas price to guarantee their timely inclusion.

gas_oracle

The gas oracle middleware is used to get the gas price from a list of gas oracles instead of using eth_gasPrice. For usage examples, refer to the GasOracle trait.

nonce_manager

The Nonce Manager is used to locally calculate nonces instead of using eth_getTransactionCount

policy

The Policy is used to ensure transactions comply with the rules configured in the PolicyMiddleware before sending them.

signer

The SignerMiddleware is used to locally sign transactions and messages instead of using eth_sendTransaction and eth_sign.

timelag

The TimeLag middleware provides safety against reorgs by querying state N blocks before the chain tip.

transformer

The TransformerMiddleware is used to intercept transactions and transform them to be sent via various supported transformers, e.g., DSProxy.

Traits

Middleware

A middleware allows customizing requests send and received from an ethereum node.

MiddlewareError

MiddlewareError is a companion trait to crate::Middleware. It describes error behavior that is common to all Middleware errors.