ead8099109
* Rename existing wrapper, to match contract name * base contract: make member var public * json_schemas.py: stop storing copies of schemas! * .gitignore generated erc20_token.py wrapper * json schemas: allow uppercase digits in address * existing exchange wrapper: re-order methods to match method order in Solidity contract, to reduce noise in upcoming diffs of newly generated code vs. old manually-written code. * existing exchange wrapper: rename method params To match contract method param names * existing exchange wrapper: remove redundant member * existing exchange wrapper: make signatures bytes Not strings. * abi-gen/test-cli: show context on diff failure * abi-gen-templates/Py: fix broken event interface Previous changes had removed the `token_address` parameter from all generated methods, but this instance was missed because there weren't tests/examples using events for the first contract for which wrappers were generated (ERC20Token). * abi-gen: remove unused method parameters * abi-gen: convert Py method params to snake case * abi-gen: rewrite Python tuple handling * python-generated-wrappers: include Exchange * abi-gen-templates/Py: easy linter fixes * abi-gen-templates/Py: satisfy docstring linters * abi-gen-templates/Py: normalize bytes before use * contract_wrappers.py: replace Exchange w/generated * contract_wrappers.py: rm manually written Exchange * contract_wrappers.py/doctest: rename variables * abi-gen: fix misspelling in docstring Co-Authored-By: Fabio B <me@fabioberger.com> * Py docs: error on warning, and test build in CI * abi-gen: doc Py bytes params as requiring UTF-8 * abi-gen: git mv diff.sh test-cli/ * abi-gen: put Py wrapper in module folder, not file This leaves space for user-defined additions to the same module, such as for custom types, as shown herein. * abi-gen: customizable param validation for Python * contract_wrappers.py: JSON schema Order validation * CircleCI Build Artifacts For abi-gen command-line test output, for generated Python contract wrappers as output by abi-gen, for generated Python contract wrappers as reformatted and included in the Python package area, and for the "build" output folder in each Python package, which includes the generated documentation. * CHANGELOG updates for all components * abi-gen: grammar in comments Co-Authored-By: Fabio B <me@fabioberger.com> * abi-gen: CHANGELOG spelling correction Co-Authored-By: Fabio B <me@fabioberger.com> * order_utils.py: reverse (chronological) CHANGELOG * abi-gen-templates: reset CHANGELOG patch version * CHANGELOGs: use multiple entries where appropriate * abi-gen: enable devdoc solc output in test-cli * abi-gen-templates/Py: consolidate return type * abi-gen/test-cli: non-pure fixture contract method Added a method to the "dummy" test fixture contract that isn't pure. All of the other prior method cases were pure. * abi-gen/Py: fix const methods missing return type * abi-gen/Py: fix wrong return types on some methods Specifically, wrapper methods wrapping contract methods that modify contract state and return no return value. There was no test case for this. Now there is. * contract_wrappers.py: rm generated code in `clean` * Parallelize Py monorepo scripts (test, lint, etc)
ABI Gen
This package allows you to generate TypeScript contract wrappers from ABI files. It's heavily inspired by Geth abigen but takes a different approach. You can write your custom handlebars templates which will allow you to seamlessly integrate the generated code into your existing codebase with existing conventions.
Here are the templates used to generate the contract wrappers used by 0x.js.e
Installation
yarn add -g @0x/abi-gen
Usage
abi-gen
Options:
--help Show help [boolean]
--version Show version number [boolean]
--abis Glob pattern to search for ABI JSON files
[string] [required]
--output, -o, --out Folder where to put the output files [string] [required]
--partials Glob pattern for the partial template files [string]
--template Path for the main template file that will be used to
generate each contract [string] [required]
--backend The backing Ethereum library your app uses. Either 'web3'
or 'ethers'. Ethers auto-converts small ints to numbers
whereas Web3 doesn't.
[string] [choices: "web3", "ethers"] [default: "web3"]
--network-id ID of the network where contract ABIs are nested in
artifacts [number] [default: 50]
You're required to pass a glob template where your abi files are located. TL;DR - here is the example from 0x.js.
--abis 'src/artifacts/@(Exchange|Token|TokenTransferProxy|EtherToken|TokenRegistry).json
We could've just used --abis 'src/artifacts/*.json but we wanted to exclude some of the abi files.
The abi file should be either a Truffle contract artifact (a JSON object with an abi key) or a JSON abi array.
You need to also specify the location of your main template used for every contract --template as well as the partial templates --partials that can later be used from the main one.
How to write custom templates?
The best way to get started is to copy 0x.js templates and start adjusting them for your needs.
We use handlebars template engine under the hood.
You need to have a master template called contract.mustache. it will be used to generate each contract wrapper. Although - you don't need and probably shouldn't write all your logic in a single template file. You can write partial templates and as long as they are within a partials folder - they will be registered and available.
Which data/context do I get in my templates?
For now you don't get much on top of methods abi, some useful helpers and a contract name because it was enough for our use-case, but if you need something else - create a PR. See the type definition of what we pass to the render method.
Output files
Output files will be generated within an output folder with names converted to camel case and taken from abi file names. If you already have some files in that folder they will be overwritten.
Contributing
We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.
Please read our contribution guidelines before getting started.
Install dependencies
If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
yarn config set workspaces-experimental true
Then install dependencies
yarn install
Build
To build this package and all other monorepo packages that it depends on, run the following from the monorepo root directory:
PKG=@0x/abi-gen yarn build
Or continuously rebuild on change:
PKG=@0x/abi-gen yarn watch
Clean
yarn clean
Lint
yarn lint
CLI tests
The files in test-cli/ are used to test the CLI output against a set of dummy contracts.
Compile dummy contracts and generate wrappers:
yarn test_cli:prebuild
Build generated wrappers and unit tests:
yarn test_cli:build
Run unit tests and check diffs of generated wrappers vs known wrappers:
yarn test_cli
Known-good wrappers have been previously committed and are kept in test-cli/expected-output/{language}. They are intended to provide sample output and should be kept in sync with the generating code. When making changes to this project or @0x/abi-gen-templates, run yarn test_cli:prebuild to generate fresh code into test-cli/output/{language}, and then manually copy it to test-cli/expected-output/{language}.