4 releases
0.10.1 | Jul 6, 2023 |
---|---|
0.10.0 | Apr 12, 2023 |
0.9.1 | Mar 10, 2023 |
0.9.0 | Dec 8, 2022 |
#20 in #nonce
56KB
1K
SLoC
Transaction Manager
The eth-tx-manager
is a Rust library for submitting transactions to the
blockchain.
It tries to account for the many scenarios that can befall a transaction sent
to the transaction pool and adjust accordingly.
Most notably, it:
- Manages nonces automatically.
- Resends transactions if necessary.
- Waits for a given number of block confirmations.
- Recovers from hard crashes.
Usage example
The code for this example is available at examples/send_transaction.rs.
You can run it with the cargo run --example send_transaction
command.
You need to have a local geth node running on dev mode.
To start sending transactions we must first instantiate a TransactionManager
object by calling its constructor.
TransactionManager::new(provider, gas_oracle, database, chain, configuration)
The chain
parameter is a Chain
object that holds a chain ID and a boolean
indicating whether or not the target blockchain implements the EIP-1559.
We can instantiate it by calling the Chain::new
or Chain::legacy
functions.
let chain = Chain::new(1337);
The provider
is an object that implements the ethers::providers::Middleware
trait.
(In our examples, we will send transactions to a local geth node running on
develop mode.)
let provider = Provider::<Http>::try_from("http://localhost:8545").unwrap();
The provider is responsible for signing the transactions we will be sending, therefore, we wrap it using a signer middleware.
let wallet = LocalWallet::new(&mut thread_rng()).with_chain_id(chain.id);
let provider = SignerMiddleware::new(provider, wallet);
The gas_oracle
and database
parameters are dependencies injected into the
transaction manager to, respectivelly, deal with gas prices and guarantee
robustness.
The configuration
is used for fine tuning internal waiting times.
We will discuss these in the next sections but, for now, we will use their
default provided implementations.
let gas_oracle = DefaultGasOracle::new();
let database = FileSystemDatabase::new("database.json".to_string());
let configuration = Configuration::default();
We can, then, instantiate the transaction manager:
let (manager, receipt) =
TransactionManager::new(provider, gas_oracle, database, chain, configuration)
.await
.unwrap();
assert!(receipt.is_none());
Note that the new
function is asynchronous and returns both a transaction
manager and a Option<ethers::types::TransactionReceipt>
.
We designed the transaction manager to be robust.
In case the manager fails or gets interrupted while sending a transaction (a
hardware crash, for example), it will try to confirm that transaction during
its next instantiation, thus, the possible receipt and the need for async
.
In essence, this guarantees that we always deal with pending transactions.
With the manager in hands we can send a transaction by calling the aptly named
send_transaction
method.
pub async fn send_transaction(
mut self,
transaction: Transaction,
confirmations: usize,
priority: Priority,
) -> Result<(Self, TransactionReceipt), Error<M, GO, DB>> {
The send_transaction
method takes a mut self
transaction manager,
effectivelly taking ownership of the manager instance.
When the function is done, it returns that instance alongside the expected
transaction receipt.
This enforces through the type system that (1) we will need to instantiate a new
manager in case the function fails and (2) we can only send transactions
sequentially.
Property 1 guarantees that any pending transactions will be managed by the
constructor and property 2 enforces synchronicity (concurrency leads to a lot
of undesired complexity).
The function also takes a confirmations
argument.
The number of confirmations is the number of blocks that must be mined, after
the transaction is placed in a block, so that the function returns successfully.
In other words, if the number of confirmations is 0, the function returns
immediatelly after the transaction gets mined, otherwise, it will wait for
confirmations
more blocks to be mined before returning.
(This basically accounts for network reorganizations.)
The priority
level is a parameter sent to the gas oracle to calculate the
appropriate gas fees. Higher priorities cost more, but reduce waiting times,
and vice-versa for lower priorities.
let transaction = Transaction {
from: wallet.address(),
to: H160::random(),
value: Value::Number(U256::from(1e9 as u64)),
call_data: None,
};
let result = manager
.send_transaction(transaction, 1, Priority::Normal)
.await;
assert!(result.is_err());
In our contrived example, we are sending funds from a random wallet, so it is pretty clear that that transaction will fail with an "insufficient funds" error.
Gas Oracle
TODO.
Database
TODO.
Configuration
TODO.
Inner workings
TODO.
Dependencies
~26–43MB
~688K SLoC