ethers-rs/examples/contracts
Andrea Simeoni 10310ce3ad
refactor: examples (#1940)
* ToC

* Big numbers section

* Middleware examples: builder

* Middleware examples: gas_escalator

* Middleware examples: gas_oracle

* Middleware examples: signer

* Middleware examples: missing stubs

* review: applied DaniPopes suggestions to big numbers

* typo

* Middleware examples: nonce_manager

* cargo +nightly fmt

* update roadmap

* Middleware examples: policy

* Middleware examples: added docs

* Contracts examples: created folder; included abigen example

* Contracts examples: refactor abigen docs. Fixed cargo example reference

* Contracts examples: contract_events; minor docs changes

* Moved each example under its own crate.
Cargo builds locally
TODO: Fix broken examples CI

* Big numbers examples: used regular operators for math

* Single examples run correctly (missing overall CI execution)
Example crates dependencies
Removed duplicates

* review: Applied gakonst note to remove commented items in workspace manifest

* review: Applied gakonst note to restore visibility on contract constructor

* ci:
- Run/Build  examples in a single step to avoid duplicated scripts
- Removed ci.yaml step "Build all examples"

* cargo +nightly fmt

* ci: fix WASM step error

* Removed deprecated EthGasStation example

* WASM example uses local copy of `contract_abi.json`. In this way we keep the WASM example auto-consistent, at the cost of a small duplication

* Cargo.lock aligned to master branch

* Removed useless comments in examples

* review: Applied gakonst note to add panic!() on the policy middleware example

* review: Applied gakonst suggestion to add a custom middleware example

* typos in docs

* Update examples/big-numbers/examples/bn_math_operations.rs

review: Accepted commit suggested by DaniPopes

Co-authored-by: DaniPopes <57450786+DaniPopes@users.noreply.github.com>

* review: Applied DaniPopes suggestion on assert_eq!

* Update examples/big-numbers/README.md

review: Accepted DaniPopes suggestion on big-numbers docs

Co-authored-by: DaniPopes <57450786+DaniPopes@users.noreply.github.com>

* review: All imports now reference the "ethers" crate

* ci: added features ["ws", "rustls"] where needed
cargo +nigthly fmt

* Examples with special features (e.g. ipc, trezor etc.) are built alongside them. This is expressed as a "default" requirement in their respective Cargo.toml

* cargo +nightly fmt

* Examples: Gas oracle API keys from env
Added missing features in middleware Cargo.toml

* typo: use expect() instead of unwrap()

* Updated ToC
Moved 2 examples under more relevant folders

* Gas oracle examples raise panic on middleware errors

* review: removed useless [[example]] in Cargo.toml

* review: removed #[allow(unused_must_use)] from gas_escalator example

* review: Removed prefixes from file names

* review: removed useless [[example]] in Cargo.toml

* docs: Updated description to run examples in the workspace README.md

Co-authored-by: Andrea Simeoni <>
Co-authored-by: DaniPopes <57450786+DaniPopes@users.noreply.github.com>
2022-12-29 14:53:11 +02:00
..
examples refactor: examples (#1940) 2022-12-29 14:53:11 +02:00
Cargo.toml refactor: examples (#1940) 2022-12-29 14:53:11 +02:00
README.md refactor: examples (#1940) 2022-12-29 14:53:11 +02:00

README.md

Contracts

In this guide, we will go over some examples of using ethers-rs to work with contracts, including using abigen to generate Rust bindings for a contract, listening for contract events, calling contract methods, and instantiating contracts.

Generating Rust bindings with abigen

To use a contract with ethers-rs, you will need to generate Rust bindings using the abigen tool. abigen is included with the ethers-rs library and can be used to generate Rust bindings for any Solidity contract.

Generate a Rust file

This method takes a smart contract's Application Binary Interface (ABI) file and generates a Rust file to interact with it. This is useful if the smart contract is referenced in different places in a project. File generation from ABI can also be easily included as a build step of your application.

Running the code below will generate a file called token.rs containing the bindings inside, which exports an ERC20Token struct, along with all its events and methods. Put into a build.rs file this will generate the bindings during cargo build.

Abigen::new("ERC20Token", "./abi.json")?.generate()?.write_to_file("token.rs")?;

Generate inline Rust bindings

This method takes a smart contract's solidity definition and generates inline Rust code to interact with it. This is useful for fast prototyping and for tight scoped use-cases of your contracts. Inline Rust generation uses the abigen! macro to expand Rust contract bindings.

Running the code below will generate bindings for the ERC20Token struct, along with all its events and methods.

abigen!(
    ERC20Token,
    r#"[
        function approve(address spender, uint256 amount) external returns (bool)
        event Transfer(address indexed from, address indexed to, uint256 value)
        event Approval(address indexed owner, address indexed spender, uint256 value)
    ]"#,
);

Another way to get the same result, is to provide the ABI contract's definition as follows.

abigen!(ERC20Token, "./abi.json",);

Contract instances

Contract methods

Contract events