Macro ethcontract_derive::contract [−][src]
contract!() { /* proc-macro */ }
Expand description
Proc macro to generate type-safe bindings to a contract.
This macro accepts a path to an artifact JSON file. Note that this path
is rooted in the crate’s root CARGO_MANIFEST_DIR
:
contract!("build/contracts/WETH9.json");
Alternatively, other sources may be used, for full details consult the
ethcontract_generate::source
documentation. Some basic examples:
// HTTP(S) source
contract!("https://my.domain.local/path/to/contract.json")
// Etherscan source
contract!("etherscan:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2");
// NPM package source
contract!("npm:@openzeppelin/contracts@4.2.0/build/contracts/IERC20.json")
Note that Etherscan rate-limits requests to their API, to avoid this an
ETHERSCAN_API_KEY
environment variable can be set. If it is, it will use
that API key when retrieving the contract ABI.
Currently, the proc macro accepts additional parameters to configure some aspects of the code generation. Specifically it accepts the following.
-
format
: format of the artifact.Available values are:
truffle
(default) to use truffle loader;hardhat
to use hardhat loader in single export mode;hardhat_multi
to use hardhat loader in multi export mode.
Note that hardhat artifacts export multiple contracts. You’ll have to use
contract
parameter to specify which contract to generate bindings to. -
contract
: name of the contract we’re generating bindings to.If an artifact exports a single unnamed artifact, this parameter can be used to set its name. For example:
ⓘcontract!( "etherscan:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", contract = WETH9 );
Otherwise, it can be used to specify which contract we’re generating bindings to. Additionally, you can rename contract class by specifying a new name after the
as
keyword. For example:ⓘcontract!( "build/contracts.json", format = hardhat_multi, contract = WETH9 as WrappedEthereum );
-
mod
: name of the contract module to place generated code in.This defaults to the contract name converted into snake case.
Note that the root contract type gets re-exported in the context where the macro was invoked.
Example:
ⓘcontract!( "build/contracts/WETH9.json", contract = WETH9 as WrappedEthereum, mod = weth, );
-
deployments
: a list of additional addresses of deployed contract for specified network IDs.This mapping allows generated contract’s
deployed
function to work with networks that are not included in the artifact’s deployment information.Note that deployments defined this way take precedence over the ones defined in the artifact.
This parameter is intended to be used to manually specify contract addresses for test environments, be it testnet addresses that may defer from the originally published artifact or deterministic contract addresses on local development nodes.
Example:
ⓘcontract!( "build/contracts/WETH9.json", deployments { 4 => "0x000102030405060708090a0b0c0d0e0f10111213", 5777 => "0x0123456789012345678901234567890123456789", }, );
-
methods
: a list of mappings from method signatures to method names allowing methods names to be explicitly set for contract methods.This also provides a workaround for generating code for contracts with multiple methods with the same name.
Example:
ⓘcontract!( "build/contracts/WETH9.json", methods { approve(Address, U256) as set_allowance }, );
-
event_derives
: a list of additional derives that should be added to contract event structs and enums.Example:
ⓘcontract!( "build/contracts/WETH9.json", event_derives (serde::Deserialize, serde::Serialize), );
-
crate
: the name of theethcontract
crate. This is useful if the crate was renamed in theCargo.toml
for whatever reason.
Additionally, the ABI source can be preceded by a visibility modifier such
as pub
or pub(crate)
. This visibility modifier is applied to both the
generated module and contract re-export. If no visibility modifier is
provided, then none is used for the generated code as well, making the
module and contract private to the scope where the macro was invoked.
Full example:
contract!(
pub(crate) "build/contracts.json",
format = hardhat_multi,
contract = WETH9 as WrappedEthereum,
mod = weth,
deployments {
4 => "0x000102030405060708090a0b0c0d0e0f10111213",
5777 => "0x0123456789012345678901234567890123456789",
},
methods {
myMethod(uint256,bool) as my_renamed_method;
},
event_derives (serde::Deserialize, serde::Serialize),
crate = ethcontract_renamed,
);
See ethcontract
module level documentation for additional
information.