Skip to content

Latest commit

 

History

History
224 lines (157 loc) · 8.48 KB

README.md

File metadata and controls

224 lines (157 loc) · 8.48 KB
Raw

ethers-rs

A complete Ethereum and Celo Rust library

Github Actions Telegram Chat Crates.io

Warning We are deprecating ethers-rs for alloy. Learn how to use Alloy by visiting the book. See #2667 for more information on ethers-rs.

Quickstart

Add this to your Cargo.toml:

[dependencies]
ethers = "2.0"

And this to your code:

use ethers::prelude::*;

Documentation

View the API reference here or the online book here.

Examples are organized into individual crates under the /examples folder. You can run any of the examples by executing:

# cargo run -p <example-crate-name> --example <name>
cargo run -p examples-big-numbers --example math_operations

EVM-compatible chains support

There are many chains live which are Ethereum JSON-RPC & EVM compatible, but do not yet have support for EIP-2718 Typed Transactions. This means that transactions submitted to them by default in ethers-rs will have invalid serialization. To address that, you must use the legacy feature flag:

[dependencies]
ethers = { version = "2.0", features = ["legacy"] }

Polygon support

There is abigen support for Polygon and the Mumbai test network. It is recommended that you set the POLYGONSCAN_API_KEY environment variable. You can get one here.

Avalanche support

There is abigen support for Avalanche and the Fuji test network. It is recommended that you set the SNOWTRACE_API_KEY environment variable. You can get one here.

Optimism support

Optimism is supported via the optimism feature flag:

[dependencies]
ethers = { version = "2.0", features = ["optimism"] }

Optimism has a new transaction type: Deposited Transactions with type ID 0x7E, which requires 3 new fields:

  • sourceHash: The hash which uniquely identifies the origin of the deposit
  • mint: The ETH value to mint on L2.
  • isSystemTx: True if the tx does not interact with the L2 block gas pool

Note: the optimism and celo features are mutually exclusive.

Celo Support

Celo support is turned on via the feature-flag celo:

[dependencies]
ethers = { version = "2.0", features = ["celo"] }

Celo's transactions differ from Ethereum transactions by including 3 new fields:

  • fee_currency: The currency fees are paid in (None for CELO, otherwise it's an Address)
  • gateway_fee_recipient: The address of the fee recipient (None for no gateway fee paid)
  • gateway_fee: Gateway fee amount (None for no gateway fee paid)

The feature flag enables these additional fields in the transaction request builders and in the transactions which are fetched over JSON-RPC.

Note: the optimism and celo features are mutually exclusive.

Features

  • Ethereum JSON-RPC Client
  • Interacting and deploying smart contracts
  • Type safe smart contract bindings code generation
  • Querying past events
  • Event monitoring as Streams
  • ENS as a first class citizen
  • Celo support
  • Polygon support
  • Avalanche support
  • Optimism support
  • Websockets / eth_subscribe
  • Hardware Wallet Support
  • Parity APIs (tracing, parity_blockWithReceipts)
  • Geth TxPool API
  • WASM Bindings (see note)
  • FFI Bindings (see note)
  • CLI for common operations

Websockets

Websockets support is turned on via the feature-flag ws:

[dependencies]
ethers = { version = "2.0", features = ["ws"] }

Interprocess Communication (IPC)

IPC support is turned on via the feature-flag ipc:

[dependencies]
ethers = { version = "2.0", features = ["ipc"] }

HTTP Secure (HTTPS)

If you are looking to connect to a HTTPS endpoint, then you need to enable the rustls or openssl feature. feature-flags.

To enable rustls:

[dependencies]
ethers = { version = "2.0", features = ["rustls"] }

To enable openssl:

[dependencies]
ethers = { version = "2.0", features = ["openssl"] }

Note on WASM and FFI bindings

You should be able to build a wasm app that uses ethers-rs (see the example for reference). If ethers fails to compile in WASM, please open an issue. There is currently no plan to provide an official JS/TS-accessible library interface, as we believe viem or ethers.js serve that need very well.

Similarly, you should be able to build FFI bindings to ethers-rs. If ethers fails to compile in C library formats, please open an issue. There is currently no plan to provide official FFI bindings.

Getting Help

First, see if the answer to your question can be found in the API documentation. If the answer is not there, try opening an issue with the question.

Join the ethers-rs telegram to chat with the community!

Contributing

Thanks for your help improving the project! We are so happy to have you! We have a contributing guide to help you get involved in the ethers-rs project.

If you open a Pull Request, do not forget to add your changes in the CHANGELOG, ensure your code is properly formatted with cargo +nightly fmt and that Clippy is happy cargo clippy; you can even try to let clippy fix simple issues itself: cargo +nightly clippy --fix

Running the tests

Tests require the following installed:

  1. solc (>=0.8.0). We also recommend using svm for more flexibility.
  2. anvil
  3. geth

Additionally, the ETHERSCAN_API_KEY environment variable has to be set to run ethers-etherscan tests. You can get one here.

Projects using ethers-rs

Credits

This library would not have been possible without the great work done in:

A lot of the code was inspired and adapted from them, to a unified and opinionated interface, built with async/await and std futures from the ground up.