Skip to content

Latest commit

 

History

History
177 lines (124 loc) · 4.75 KB

README.md

File metadata and controls

177 lines (124 loc) · 4.75 KB
Raw

Build Status Crates.io Docs.rs Rustc Version

ethcontract-rs

Crate used for generating code for Ethereum smart contracts. It provides a function procedural macro that generates safe bindings for contract interaction based on the contract ABI.

Getting Started

Add a dependency to the ethcontract crate in your Cargo.toml:

[dependencies]
ethcontract = "..."

Then generate a struct for interacting with the smart contract with a type-safe API:

ethcontract::contract!("path/to/truffle/build/contract/Contract.json");

This will generate a new struct ContractName with contract generated methods for interacting with contract functions in a type-safe way.

Minimum Supported Rust Version

The minimum supported Rust version is 1.52.

Generator API

As an alternative to the procedural macro, a generator API is provided for generating contract bindings from build.rs scripts. More information can be found in the ethcontract-generate README.

Running the Examples

In order to run local examples you will additionally need:

  • NodeJS LTS
  • Yarn

For all examples, the smart contracts must first be built:

cd examples/truffle
yarn && yarn build

Truffle Examples

Truffle examples rely on the local truffle development server. In a separate terminal run:

cd examples/truffle
yarn start

ABI:

The abi example deploys a simple contract and performs various eth_calls to illustrate how Solidity types are mapped to Rust types by ethcontract.

cargo run --example abi

Async/Await:

The async example deploys an ERC20 token and interacts with the contract with various accounts.

cargo run --example async

Manual Deployments:

The deployments example illustrates how the deployments parameter can be specified when generating a contract with the ethcontract::contract! macro. This can be useful for specifying addresses in testing environments that are deterministic but either not included, or inaccurate in the artifact's networks property (when for example the contract is developed upstream, but a separate testnet deployment wants to be used).

cargo run --example deployments

Events:

The events example illustrates how to listen to logs emitted by smart contract events.

cargo run --example events

Generator API (with build.rs script):

The generator example (actually a separate crate to be able to have a build script) demonstrates how the generator API can be used for creating type-safe bindings to a smart contract with a build.rs build script.

cargo run --package examples-generate

Contract Linking:

The linked example deploys a library and a contract that links to it then makes a method call.

cargo run --example linked

Rinkeby Example

There is a provided example that runs with Rinkeby and Infura. Running this example is a little more involved to run because it requires a private key with funds on Rinkeby (for gas) as well as an Infura project ID in order to connect to a node. Parameters are provided to the Rinkeby example by environment variables:

export PK="private key"
export INFURA_PROJECT_ID="Infura project ID"
cargo run --example rinkeby

Mainnet Examples

Sources:

This example generates contract bindings from online sources:

  • A verified contract on Etherscan
  • An npmjs contract

It also queries some contract state with Infura. Running this example requires an Infura project ID in order to connect to a node. Parameters are provided to the example by environment variables:

export INFURA_PROJECT_ID="Infura project ID"
cargo run --example sources

Past Events:

This example retrieves the entire event history of token OWL contract and prints the total number of events since deployment.

Note the special handling of the tokenOWLProxy contract and how it is cast into a tokenOWL instance using Contract's with_deployment_info feature.

export INFURA_PROJECT_ID="Infura project ID"
cargo run --example past_events

Sample Contracts Documentation

You can view example generated contract documentation by fist building the contracts and then generating documentation for the crate:

(cd examples/truffle; yarn && yarn build)
cargo doc --package examples-documentation --no-deps --open

This will open a browser at the documentation root.