ethers-rs/ethers-providers/src/provider.rs

381 lines
13 KiB
Rust
Raw Normal View History

2020-06-01 21:31:32 +00:00
use crate::{
ens,
http::Provider as HttpProvider,
networks::{Mainnet, Network},
JsonRpcClient,
};
2020-05-27 11:32:44 +00:00
2020-05-31 16:01:34 +00:00
use ethers_core::{
abi::{self, Detokenize, ParamType},
2020-05-31 16:01:34 +00:00
types::{
Address, Block, BlockId, BlockNumber, Bytes, Filter, Log, NameOrAddress, Selector,
Transaction, TransactionReceipt, TransactionRequest, TxHash, U256,
},
utils,
2020-05-24 15:40:16 +00:00
};
2020-05-26 10:24:19 +00:00
use serde::Deserialize;
2020-06-01 21:31:32 +00:00
use thiserror::Error;
2020-05-26 10:24:19 +00:00
use url::{ParseError, Url};
2020-06-01 21:31:32 +00:00
use std::{convert::TryFrom, fmt::Debug};
2020-05-24 15:40:16 +00:00
/// An abstract provider for interacting with the [Ethereum JSON RPC
2020-05-28 16:34:06 +00:00
/// API](https://github.com/ethereum/wiki/wiki/JSON-RPC). Must be instantiated
/// with a [`Network`](networks/trait.Network.html) and a data transport
/// (e.g. HTTP, Websockets etc.)
2020-05-24 15:40:16 +00:00
#[derive(Clone, Debug)]
2020-06-01 21:31:32 +00:00
pub struct Provider<P>(P, Option<Address>);
#[derive(Debug, Error)]
/// An error thrown when making a call to the provider
pub enum ProviderError {
#[error(transparent)]
// dyn dispatch the error to avoid generic return types
JsonRpcClientError(#[from] Box<dyn std::error::Error>),
#[error("ens name not found: {0}")]
EnsError(String),
}
2020-05-24 15:40:16 +00:00
// JSON RPC bindings
2020-06-01 21:31:32 +00:00
impl<P> Provider<P>
where
P: JsonRpcClient,
ProviderError: From<<P as JsonRpcClient>::Error> + 'static,
{
2020-05-27 11:32:44 +00:00
////// Blockchain Status
//
// Functions for querying the state of the blockchain
2020-05-24 17:26:41 +00:00
/// Gets the latest block number via the `eth_BlockNumber` API
2020-06-01 21:31:32 +00:00
pub async fn get_block_number(&self) -> Result<U256, ProviderError> {
Ok(self.0.request("eth_blockNumber", None::<()>).await?)
2020-05-24 15:40:16 +00:00
}
2020-05-27 11:32:44 +00:00
/// Gets the block at `block_hash_or_number` (transaction hashes only)
pub async fn get_block(
&self,
block_hash_or_number: impl Into<BlockId>,
2020-06-01 21:31:32 +00:00
) -> Result<Block<TxHash>, ProviderError> {
Ok(self
.get_block_gen(block_hash_or_number.into(), false)
.await?)
2020-05-24 20:11:47 +00:00
}
2020-05-27 11:32:44 +00:00
/// Gets the block at `block_hash_or_number` (full transactions included)
2020-05-24 20:11:47 +00:00
pub async fn get_block_with_txs(
&self,
2020-05-27 11:32:44 +00:00
block_hash_or_number: impl Into<BlockId>,
2020-06-01 21:31:32 +00:00
) -> Result<Block<Transaction>, ProviderError> {
Ok(self
.get_block_gen(block_hash_or_number.into(), true)
.await?)
2020-05-24 20:11:47 +00:00
}
async fn get_block_gen<Tx: for<'a> Deserialize<'a>>(
&self,
id: BlockId,
include_txs: bool,
2020-06-01 21:31:32 +00:00
) -> Result<Block<Tx>, ProviderError> {
2020-05-24 20:11:47 +00:00
let include_txs = utils::serialize(&include_txs);
2020-06-01 21:31:32 +00:00
Ok(match id {
2020-05-24 20:11:47 +00:00
BlockId::Hash(hash) => {
let hash = utils::serialize(&hash);
let args = vec![hash, include_txs];
2020-06-01 21:31:32 +00:00
self.0.request("eth_getBlockByHash", Some(args)).await?
2020-05-24 20:11:47 +00:00
}
BlockId::Number(num) => {
let num = utils::serialize(&num);
let args = vec![num, include_txs];
2020-06-01 21:31:32 +00:00
self.0.request("eth_getBlockByNumber", Some(args)).await?
2020-05-24 20:11:47 +00:00
}
2020-06-01 21:31:32 +00:00
})
2020-05-24 20:11:47 +00:00
}
2020-05-27 11:32:44 +00:00
/// Gets the transaction with `transaction_hash`
pub async fn get_transaction<T: Send + Sync + Into<TxHash>>(
&self,
transaction_hash: T,
2020-06-01 21:31:32 +00:00
) -> Result<Transaction, ProviderError> {
2020-05-27 11:32:44 +00:00
let hash = transaction_hash.into();
2020-06-01 21:31:32 +00:00
Ok(self
.0
.request("eth_getTransactionByHash", Some(hash))
.await?)
2020-05-27 11:32:44 +00:00
}
/// Gets the transaction receipt with `transaction_hash`
2020-05-24 20:27:51 +00:00
pub async fn get_transaction_receipt<T: Send + Sync + Into<TxHash>>(
&self,
2020-05-27 11:32:44 +00:00
transaction_hash: T,
2020-06-01 21:31:32 +00:00
) -> Result<TransactionReceipt, ProviderError> {
2020-05-27 11:32:44 +00:00
let hash = transaction_hash.into();
2020-06-01 21:31:32 +00:00
Ok(self
.0
2020-05-24 20:27:51 +00:00
.request("eth_getTransactionReceipt", Some(hash))
2020-06-01 21:31:32 +00:00
.await?)
2020-05-24 20:27:51 +00:00
}
2020-05-27 11:32:44 +00:00
/// Gets the current gas price as estimated by the node
2020-06-01 21:31:32 +00:00
pub async fn get_gas_price(&self) -> Result<U256, ProviderError> {
Ok(self.0.request("eth_gasPrice", None::<()>).await?)
2020-05-27 11:32:44 +00:00
}
/// Gets the accounts on the node
2020-06-01 21:31:32 +00:00
pub async fn get_accounts(&self) -> Result<Vec<Address>, ProviderError> {
Ok(self.0.request("eth_accounts", None::<()>).await?)
2020-05-27 11:32:44 +00:00
}
/// Returns the nonce of the address
pub async fn get_transaction_count(
2020-05-24 15:40:16 +00:00
&self,
2020-05-27 11:32:44 +00:00
from: Address,
block: Option<BlockNumber>,
2020-06-01 21:31:32 +00:00
) -> Result<U256, ProviderError> {
2020-05-27 11:32:44 +00:00
let from = utils::serialize(&from);
let block = utils::serialize(&block.unwrap_or(BlockNumber::Latest));
2020-06-01 21:31:32 +00:00
Ok(self
.0
2020-05-27 11:32:44 +00:00
.request("eth_getTransactionCount", Some(&[from, block]))
2020-06-01 21:31:32 +00:00
.await?)
2020-05-24 15:40:16 +00:00
}
2020-05-27 11:32:44 +00:00
/// Returns the account's balance
pub async fn get_balance(
&self,
from: Address,
block: Option<BlockNumber>,
2020-06-01 21:31:32 +00:00
) -> Result<U256, ProviderError> {
2020-05-27 11:32:44 +00:00
let from = utils::serialize(&from);
let block = utils::serialize(&block.unwrap_or(BlockNumber::Latest));
2020-06-01 21:31:32 +00:00
Ok(self
.0
.request("eth_getBalance", Some(&[from, block]))
.await?)
2020-05-27 11:32:44 +00:00
}
2020-05-24 18:34:56 +00:00
/// Returns the currently configured chain id, a value used in replay-protected
/// transaction signing as introduced by EIP-155.
2020-06-01 21:31:32 +00:00
pub async fn get_chainid(&self) -> Result<U256, ProviderError> {
Ok(self.0.request("eth_chainId", None::<()>).await?)
}
2020-05-27 11:32:44 +00:00
////// Contract Execution
//
// These are relatively low-level calls. The Contracts API should usually be used instead.
/// Send the read-only (constant) transaction to a single Ethereum node and return the result (as bytes) of executing it.
/// This is free, since it does not change any state on the blockchain.
pub async fn call(
2020-05-25 15:35:38 +00:00
&self,
tx: TransactionRequest,
block: Option<BlockNumber>,
2020-06-01 21:31:32 +00:00
) -> Result<Bytes, ProviderError> {
let tx = utils::serialize(&tx);
let block = utils::serialize(&block.unwrap_or(BlockNumber::Latest));
2020-06-01 21:31:32 +00:00
Ok(self.0.request("eth_call", Some(vec![tx, block])).await?)
2020-05-25 15:35:38 +00:00
}
2020-05-27 11:32:44 +00:00
/// Send a transaction to a single Ethereum node and return the estimated amount of gas required (as a U256) to send it
/// This is free, but only an estimate. Providing too little gas will result in a transaction being rejected
/// (while still consuming all provided gas).
pub async fn estimate_gas(
&self,
tx: &TransactionRequest,
block: Option<BlockNumber>,
2020-06-01 21:31:32 +00:00
) -> Result<U256, ProviderError> {
2020-05-27 11:32:44 +00:00
let tx = utils::serialize(tx);
let args = match block {
Some(block) => vec![tx, utils::serialize(&block)],
None => vec![tx],
};
2020-06-01 21:31:32 +00:00
Ok(self.0.request("eth_estimateGas", Some(args)).await?)
2020-05-27 11:32:44 +00:00
}
/// Send the transaction to the entire Ethereum network and returns the transaction's hash
/// This will consume gas from the account that signed the transaction.
2020-06-01 21:31:32 +00:00
pub async fn send_transaction(
&self,
mut tx: TransactionRequest,
) -> Result<TxHash, ProviderError> {
2020-05-27 20:43:02 +00:00
if let Some(ref to) = tx.to {
if let NameOrAddress::Name(ens_name) = to {
2020-06-01 21:31:32 +00:00
// resolve to an address
2020-05-27 20:43:02 +00:00
let addr = self
.resolve_name(&ens_name)
.await?
2020-06-01 21:31:32 +00:00
.ok_or(ProviderError::EnsError(ens_name.to_owned()))?;
// set the value
2020-05-27 20:43:02 +00:00
tx.to = Some(addr.into())
}
}
2020-06-01 21:31:32 +00:00
Ok(self.0.request("eth_sendTransaction", Some(tx)).await?)
2020-05-24 15:40:16 +00:00
}
2020-05-27 11:32:44 +00:00
/// Send the raw RLP encoded transaction to the entire Ethereum network and returns the transaction's hash
/// This will consume gas from the account that signed the transaction.
2020-06-01 21:31:32 +00:00
pub async fn send_raw_transaction(&self, tx: &Transaction) -> Result<TxHash, ProviderError> {
let rlp = utils::serialize(&tx.rlp());
2020-06-01 21:31:32 +00:00
Ok(self.0.request("eth_sendRawTransaction", Some(rlp)).await?)
2020-05-24 15:40:16 +00:00
}
2020-05-27 11:32:44 +00:00
////// Contract state
2020-05-24 17:26:41 +00:00
2020-05-27 11:32:44 +00:00
/// Returns an array (possibly empty) of logs that match the filter
2020-06-01 21:31:32 +00:00
pub async fn get_logs(&self, filter: &Filter) -> Result<Vec<Log>, ProviderError> {
Ok(self.0.request("eth_getLogs", Some(filter)).await?)
2020-05-27 11:32:44 +00:00
}
// TODO: get_code, get_storage_at
////// Ethereum Naming Service
// The Ethereum Naming Service (ENS) allows easy to remember and use names to
// be assigned to Ethereum addresses. Any provider operation which takes an address
// may also take an ENS name.
//
// ENS also provides the ability for a reverse lookup, which determines the name for an address if it has been configured.
/// Returns the address that the `ens_name` resolves to (or None if not configured).
///
/// # Panics
///
/// If the bytes returned from the ENS registrar/resolver cannot be interpreted as
/// an address. This should theoretically never happen.
2020-06-01 21:31:32 +00:00
pub async fn resolve_name(&self, ens_name: &str) -> Result<Option<Address>, ProviderError> {
2020-05-27 11:32:44 +00:00
self.query_resolver(ParamType::Address, ens_name, ens::ADDR_SELECTOR)
2020-05-24 15:40:16 +00:00
.await
}
2020-05-24 17:26:41 +00:00
2020-05-27 11:32:44 +00:00
/// Returns the ENS name the `address` resolves to (or None if not configured).
2020-05-28 16:34:06 +00:00
/// # Panics
///
/// If the bytes returned from the ENS registrar/resolver cannot be interpreted as
/// a string. This should theoretically never happen.
2020-06-01 21:31:32 +00:00
pub async fn lookup_address(&self, address: Address) -> Result<Option<String>, ProviderError> {
2020-05-27 11:32:44 +00:00
let ens_name = ens::reverse_address(address);
self.query_resolver(ParamType::String, &ens_name, ens::NAME_SELECTOR)
.await
}
async fn query_resolver<T: Detokenize>(
2020-05-24 17:26:41 +00:00
&self,
2020-05-27 11:32:44 +00:00
param: ParamType,
ens_name: &str,
selector: Selector,
2020-06-01 21:31:32 +00:00
) -> Result<Option<T>, ProviderError> {
2020-05-27 15:43:43 +00:00
// Get the ENS address, prioritize the local override variable
2020-06-01 21:31:32 +00:00
let ens_addr = match self.1 {
2020-05-27 15:43:43 +00:00
Some(ens_addr) => ens_addr,
2020-06-01 21:31:32 +00:00
None => match Mainnet::ENS_ADDRESS {
2020-05-27 15:43:43 +00:00
Some(ens_addr) => ens_addr,
None => return Ok(None),
},
2020-05-27 11:32:44 +00:00
};
// first get the resolver responsible for this name
// the call will return a Bytes array which we convert to an address
let data = self
.call(ens::get_resolver(ens_addr, ens_name), None)
.await?;
let resolver_address: Address = decode_bytes(ParamType::Address, data);
if resolver_address == Address::zero() {
return Ok(None);
}
// resolve
let data = self
.call(ens::resolve(resolver_address, selector, ens_name), None)
.await?;
Ok(Some(decode_bytes(param, data)))
}
2020-05-28 16:34:06 +00:00
/// Overrides the default ENS address set by the provider's `Network` type.
2020-05-27 15:43:43 +00:00
pub fn ens<T: Into<Address>>(mut self, ens: T) -> Self {
2020-06-01 21:31:32 +00:00
self.1 = Some(ens.into());
2020-05-27 11:32:44 +00:00
self
2020-05-24 17:26:41 +00:00
}
2020-05-24 15:40:16 +00:00
}
2020-05-26 10:24:19 +00:00
2020-05-27 11:32:44 +00:00
/// infallbile conversion of Bytes to Address/String
///
/// # Panics
///
/// If the provided bytes were not an interpretation of an address
fn decode_bytes<T: Detokenize>(param: ParamType, bytes: Bytes) -> T {
let tokens =
abi::decode(&[param], &bytes.0).expect("could not abi-decode bytes to address tokens");
2020-05-27 11:32:44 +00:00
T::from_tokens(tokens).expect("could not parse tokens as address")
}
2020-06-01 21:31:32 +00:00
impl TryFrom<&str> for Provider<HttpProvider> {
2020-05-26 10:24:19 +00:00
type Error = ParseError;
fn try_from(src: &str) -> Result<Self, Self::Error> {
2020-06-01 21:31:32 +00:00
Ok(Provider(HttpProvider::new(Url::parse(src)?), None))
2020-05-27 11:32:44 +00:00
}
}
#[cfg(test)]
mod ens_tests {
use super::*;
#[tokio::test]
// Test vector from: https://docs.ethers.io/ethers.js/v5-beta/api-providers.html#id2
async fn mainnet_resolve_name() {
2020-06-01 21:31:32 +00:00
let provider = Provider::<HttpProvider>::try_from(
2020-05-27 11:32:44 +00:00
"https://mainnet.infura.io/v3/9408f47dedf04716a03ef994182cf150",
)
2020-05-27 15:43:43 +00:00
.unwrap();
2020-05-27 11:32:44 +00:00
let addr = provider
.resolve_name("registrar.firefly.eth")
.await
.unwrap();
assert_eq!(
addr.unwrap(),
"6fC21092DA55B392b045eD78F4732bff3C580e2c".parse().unwrap()
);
// registrar not found
let addr = provider.resolve_name("asdfasdffads").await.unwrap();
assert!(addr.is_none());
// name not found
let addr = provider
.resolve_name("asdfasdf.registrar.firefly.eth")
.await
.unwrap();
assert!(addr.is_none());
}
#[tokio::test]
// Test vector from: https://docs.ethers.io/ethers.js/v5-beta/api-providers.html#id2
async fn mainnet_lookup_address() {
2020-06-01 21:31:32 +00:00
let provider = Provider::<HttpProvider>::try_from(
2020-05-27 11:32:44 +00:00
"https://mainnet.infura.io/v3/9408f47dedf04716a03ef994182cf150",
)
2020-05-27 15:43:43 +00:00
.unwrap();
2020-05-27 11:32:44 +00:00
let name = provider
.lookup_address("6fC21092DA55B392b045eD78F4732bff3C580e2c".parse().unwrap())
.await
.unwrap();
assert_eq!(name.unwrap(), "registrar.firefly.eth");
let name = provider
.lookup_address("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA".parse().unwrap())
.await
.unwrap();
assert!(name.is_none());
2020-05-26 10:24:19 +00:00
}
}