2020-05-31 16:38:41 +00:00
#![ warn(
missing_debug_implementations ,
missing_docs ,
rust_2018_idioms ,
unreachable_pub
) ]
#![ deny(intra_doc_link_resolution_failure) ]
#![ doc(test(
no_crate_inject ,
attr ( deny ( warnings , rust_2018_idioms ) , allow ( dead_code , unused_variables ) )
) ) ]
#![ cfg_attr(docsrs, feature(doc_cfg)) ]
//! # ethers-rs
2020-05-22 18:37:21 +00:00
//!
2020-05-31 16:38:41 +00:00
//! > ethers-rs is a port of [ethers-js](github.com/ethers-io/ethers.js) in Rust.
2020-05-24 15:55:46 +00:00
//!
2020-06-11 08:40:07 +00:00
//! _Note: All examples using `await` are assuming that they are called from inside an `async`
//! function which is run in an async runtime. You are free to use any runtime and executor of
//! your preference._
2020-05-24 15:55:46 +00:00
//!
2020-06-11 08:40:07 +00:00
//! ## Quickstart: `prelude`
2020-06-04 18:44:02 +00:00
//!
2020-06-11 08:40:07 +00:00
//! A prelude is provided which imports all the important data types and traits for you. Use this
//! when you want to quickly bootstrap a new project.
//!
//! ```
//! # #[allow(unused)]
2020-06-04 18:44:02 +00:00
//! use ethers::prelude::*;
//! ```
//!
2020-06-11 08:40:07 +00:00
//! Examples on how you can use the types imported by the prelude can be found in
//! the [`examples` directory of the repository](https://github.com/gakonst/ethers-rs)
//! and in the `tests/` directories of each crate.
//!
//! # Quick explanation of each module in ascending order of abstraction
//!
//! ## `core`
//!
//! Contains all the [necessary data structures](core/types/index.html) for interacting
//! with Ethereum, along with cryptographic utilities for signing and verifying
//! ECDSA signatures on `secp256k1`. Bindings to the solidity compiler and `ganache-cli`
//! are also provided as helpers. To simplify your imports, consider using the re-exported
//! modules described in the next subsection.
//!
//! ## `utils`, `types`, `abi`
//!
//! These are re-exports of the [`utils`], [`types`] and [`abi`] modules from the `core` crate
2020-06-04 18:44:02 +00:00
//!
2020-06-11 08:40:07 +00:00
//! ## `providers`
2020-06-04 18:44:02 +00:00
//!
2020-06-11 08:40:07 +00:00
//! Ethereum nodes expose RPC endpoints (by default at `localhost:8545`). You can connect
//! to them by using the [`Provider`]. The provider instance
//! allows you to issue requests to the node which involve querying the state of Ethereum or
//! broadcasting transactions with unlocked accounts on the node.
2020-05-24 15:55:46 +00:00
//!
2020-06-11 08:40:07 +00:00
//! ## `signers`
2020-05-24 15:55:46 +00:00
//!
2020-06-11 08:40:07 +00:00
//! For security reasons, you typically do not want your private keys to be stored on the nodes.
//! This module provides a [`Wallet`] type for loading a private key which can be connected with a
//! [`Provider`] to produce a [`Client`]. The [`Client`] type is the object via which we recommend
//! users with local private keys to use when interacting with Ethereum.
2020-05-24 15:55:46 +00:00
//!
2020-06-11 08:40:07 +00:00
//! ## `contract`
2020-05-24 15:55:46 +00:00
//!
2020-06-11 08:40:07 +00:00
//! Interacting with Ethereum is not restricted to sending or receiving funds. It also involves
//! using smart contracts, which can be thought of as programs with persistent storage.
//!
//! Interacting with a smart contract requires broadcasting carefully crafted
//! [transactions](core/types/struct.TransactionRequest.html) where the `data` field contains
//! the [function's
//! selector](https://ethereum.stackexchange.com/questions/72363/what-is-a-function-selector)
//! along with the arguments of the called function. This module provides the
//! [`Contract`] and [`ContractFactory`] abstractions so that you do not have to worry about that.
//! It also provides typesafe bindings via the [`abigen`] macro and the [`Abigen` builder].
//!
//! [`Provider`]: providers/struct.Provider.html
//!
//! [`Wallet`]: signers/struct.Wallet.html
//! [`Client`]: signers/struct.Client.html
//!
//! [`ContractFactory`]: contract/struct.ContractFactory.html
//! [`Contract`]: contract/struct.Contract.html
//! [`abigen`]: contract/macro.abigen.html
//! [`Abigen` builder]: contract/struct.Abigen.html
//!
//! [`utils`]: core/utils/index.html
//! [`abi`]: core/abi/index.html
//! [`types`]: core/types/index.html
2020-05-22 18:37:21 +00:00
2020-05-26 11:00:56 +00:00
#[ cfg(feature = " contract " ) ]
2020-05-31 16:38:41 +00:00
#[ cfg_attr(docsrs, doc(cfg(feature = " contract " ))) ]
2020-06-11 08:40:07 +00:00
// This is copied over from the crate-level docs, is there a better way to do this?
/// Type-safe abstractions for interacting with Ethereum smart contracts
///
/// Interacting with a smart contract requires broadcasting carefully crafted
/// [transactions](core/types/struct.TransactionRequest.html) where the `data` field contains
/// the [function's
/// selector](https://ethereum.stackexchange.com/questions/72363/what-is-a-function-selector)
/// along with the arguments of the called function. This module provides the
/// [`Contract`] and [`ContractFactory`] abstractions so that you do not have to worry about that.
/// It also provides typesafe bindings via the [`abigen`] macro and the [`Abigen` builder].
///
/// [`ContractFactory`]: struct.ContractFactory.html
/// [`Contract`]: struct.Contract.html
/// [`abigen`]: macro.abigen.html
/// [`Abigen` builder]: struct.Abigen.html
2020-05-26 11:00:56 +00:00
pub mod contract {
pub use ethers_contract ::* ;
}
2020-05-24 16:43:47 +00:00
2020-05-26 11:00:56 +00:00
#[ cfg(feature = " providers " ) ]
2020-05-31 16:38:41 +00:00
#[ cfg_attr(docsrs, doc(cfg(feature = " providers " ))) ]
/// # Clients for interacting with Ethereum nodes
///
/// This crate provides asynchronous [Ethereum JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC)
2020-06-11 08:40:07 +00:00
/// compliant clients.
2020-05-31 16:38:41 +00:00
///
2020-06-11 08:40:07 +00:00
/// For more documentation on the available calls, refer to the [`Provider`](struct.Provider.html)
/// struct.
///
/// # Examples
///
/// ```no_run
2020-06-02 21:16:08 +00:00
/// use ethers::providers::{Provider, Http};
2020-05-31 16:38:41 +00:00
/// use std::convert::TryFrom;
///
2020-06-11 08:40:07 +00:00
/// # async fn foo() -> Result<(), Box<dyn std::error::Error>> {
2020-06-02 21:16:08 +00:00
/// let provider = Provider::<Http>::try_from(
/// "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"
2020-06-11 08:40:07 +00:00
/// )?;
2020-05-31 16:38:41 +00:00
///
2020-06-11 08:40:07 +00:00
/// let block = provider.get_block(100u64).await?;
/// println!("Got block: {}", serde_json::to_string(&block)?);
2020-06-15 20:10:27 +00:00
///
/// let code = provider.get_code("0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359", None).await?;
/// println!("Got code: {}", serde_json::to_string(&code)?);
2020-06-11 08:40:07 +00:00
/// # Ok(())
/// # }
2020-05-31 16:38:41 +00:00
/// ```
///
/// # Ethereum Name Service
///
/// The provider may also be used to resolve [Ethereum Name Service](https://ens.domains) (ENS) names
2020-06-11 08:40:07 +00:00
/// to addresses (and vice versa). The default ENS address is [mainnet](https://etherscan.io/address/0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e) and can be overriden by calling the [`ens`](struct.Provider.html#method.ens) method on the provider.
2020-05-31 16:38:41 +00:00
///
2020-06-11 08:40:07 +00:00
/// ```no_run
2020-06-02 21:16:08 +00:00
/// # use ethers::providers::{Provider, Http};
2020-05-31 16:38:41 +00:00
/// # use std::convert::TryFrom;
2020-06-11 08:40:07 +00:00
/// # async fn foo() -> Result<(), Box<dyn std::error::Error>> {
2020-06-02 21:16:08 +00:00
/// # let provider = Provider::<Http>::try_from(
/// # "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"
2020-06-11 08:40:07 +00:00
/// # )?;
2020-05-31 16:38:41 +00:00
/// // Resolve ENS name to Address
/// let name = "vitalik.eth";
2020-06-11 08:40:07 +00:00
/// let address = provider.resolve_name(name).await?;
2020-05-31 16:38:41 +00:00
///
/// // Lookup ENS name given Address
2020-06-11 08:40:07 +00:00
/// let resolved_name = provider.lookup_address(address).await?;
2020-05-31 16:38:41 +00:00
/// assert_eq!(name, resolved_name);
2020-06-11 08:40:07 +00:00
/// # Ok(())
/// # }
2020-05-31 16:38:41 +00:00
/// ```
2020-05-26 11:00:56 +00:00
pub mod providers {
pub use ethers_providers ::* ;
}
2020-05-22 18:37:21 +00:00
2020-05-26 11:00:56 +00:00
#[ cfg(feature = " signers " ) ]
2020-05-31 16:38:41 +00:00
#[ cfg_attr(docsrs, doc(cfg(feature = " signers " ))) ]
/// Provides a unified interface for locally signing transactions and interacting
/// with the Ethereum JSON-RPC. You can implement the `Signer` trait to extend
/// functionality to other signers such as Hardware Security Modules, KMS etc.
///
2020-06-11 08:40:07 +00:00
/// ```no_run
/// # use ethers::{
/// providers::{Http, Provider},
/// signers::Wallet,
/// core::types::TransactionRequest
/// };
2020-05-31 16:38:41 +00:00
/// # use std::convert::TryFrom;
2020-06-11 08:40:07 +00:00
/// # async fn foo() -> Result<(), Box<dyn std::error::Error>> {
2020-05-31 16:38:41 +00:00
/// // connect to the network
2020-06-11 08:40:07 +00:00
/// let provider = Provider::<Http>::try_from("http://localhost:8545")?;
2020-05-31 16:38:41 +00:00
///
/// // instantiate the wallet and connect it to the provider to get a client
/// let client = "dcf2cbdd171a21c480aa7f53d77f31bb102282b3ff099c78e3118b37348c72f7"
2020-06-11 08:40:07 +00:00
/// .parse::<Wallet>()?
/// .connect(provider);
2020-05-31 16:38:41 +00:00
///
/// // create a transaction
/// let tx = TransactionRequest::new()
/// .to("vitalik.eth") // this will use ENS
/// .value(10000);
///
/// // send it! (this will resolve the ENS name to an address under the hood)
2020-06-15 12:40:06 +00:00
/// let pending_tx = client.send_transaction(tx, None).await?;
2020-05-31 16:38:41 +00:00
///
/// // get the receipt
2020-06-15 12:40:06 +00:00
/// let receipt = pending_tx.await?;
///
/// // get the mined tx
/// let tx = client.get_transaction(receipt.transaction_hash).await?;
2020-05-31 16:38:41 +00:00
///
/// println!("{}", serde_json::to_string(&tx)?);
/// println!("{}", serde_json::to_string(&receipt)?);
///
/// # Ok(())
/// # }
2020-05-26 11:00:56 +00:00
pub mod signers {
pub use ethers_signers ::* ;
}
2020-05-23 00:01:20 +00:00
2020-05-31 16:01:34 +00:00
#[ cfg(feature = " core " ) ]
2020-05-31 16:38:41 +00:00
#[ cfg_attr(docsrs, doc(cfg(feature = " core " ))) ]
2020-06-11 08:40:07 +00:00
/// Ethereum types, cryptography and utilities.
/// _It is recommended to use the `utils`, `types` and `abi` re-exports instead of
/// the `core` module to simplify your imports._
2020-05-31 16:38:41 +00:00
///
/// This library provides type definitions for Ethereum's main datatypes along
/// with other utilities for interacting with the Ethereum ecosystem
///
/// ## Signing an ethereum-prefixed message
///
/// Signing in Ethereum is done by first prefixing the message with
/// `"\x19Ethereum Signed Message:\n" + message.length`, and then
/// signing the hash of the result.
///
/// ```rust
2020-05-31 18:46:49 +00:00
/// use ethers::core::types::{PrivateKey, Address};
2020-05-31 16:38:41 +00:00
///
/// let message = "Some data";
/// let key = PrivateKey::new(&mut rand::thread_rng());
2020-05-31 21:17:50 +00:00
/// let address = Address::from(&key);
2020-05-31 16:38:41 +00:00
///
/// // Sign the message
/// let signature = key.sign(message);
///
/// // Recover the signer from the message
/// let recovered = signature.recover(message).unwrap();
///
/// assert_eq!(recovered, address);
/// ```
///
/// ## Utilities
///
/// The crate provides utilities for launching local Ethereum testnets by using `ganache-cli`
/// via the `GanacheBuilder` struct. In addition, you're able to compile contracts on the
/// filesystem by providing a glob to their path, using the `Solc` struct.
///
/// # ABI Encoding and Decoding
///
/// This crate re-exports the [`ethabi`](http://docs.rs/ethabi) crate's functions
2020-06-15 11:29:50 +00:00
/// under the `abi` module, as well as the [`secp256k1`](https://docs.rs/libsecp256k1)
/// and [`rand`](https://docs.rs/rand) crates for convenience.
2020-05-31 16:01:34 +00:00
pub mod core {
pub use ethers_core ::* ;
2020-05-26 11:00:56 +00:00
}
2020-05-31 16:20:08 +00:00
2020-06-11 08:40:07 +00:00
// Re-export ethers_core::utils/types/abi
#[ cfg(feature = " core " ) ]
pub use ethers_core ::abi ;
#[ cfg(feature = " core " ) ]
pub use ethers_core ::types ;
2020-05-31 16:20:08 +00:00
#[ cfg(feature = " core " ) ]
pub use ethers_core ::utils ;
2020-06-11 08:40:07 +00:00
/// Easy imports of frequently used type definitions and traits
2020-05-31 16:20:08 +00:00
pub mod prelude {
#[ cfg(feature = " contract " ) ]
pub use ethers_contract ::* ;
#[ cfg(feature = " providers " ) ]
pub use ethers_providers ::* ;
#[ cfg(feature = " signers " ) ]
pub use ethers_signers ::* ;
#[ cfg(feature = " core " ) ]
pub use ethers_core ::types ::* ;
}