Contract Parser

As part of Nansen Query, Nansen provides a contract parser to quickly generate table schemas for events emitted by smart contracts!
Parsing contracts for EVM chains involves 3 steps:
  1. 1.
    Use the Contract Parser tool or Table Definition CLI to generate table definition files
  2. 2.
    Create a pull request in one of the GitHub repositories: Ethereum ETL, Polygon ETL, other EVM Chain ETL
  3. 3.
    Request a review and wait for approval

Generating Table Definition

1a. Using the Contract Parser tool

(1) First, head over to this Contract Parser tool and paste in a smart contract address of your choice, e.g. 0x89f70fa9f439dbd0a1bc22a09befc56ada04d9b4. It’ll look something like this:
Hit submit, and some magic happens under the hood. You’ll see a new box:
In this case, we found 4 events and 12 functions in this Chainlink Oracle contract. Some smart contracts may not contain any events.
(2) Now, before downloading the table definitions, type in the name of your dataset. Some example datasets we already have are:
  • kyber (for Kyber Network)
  • zeroex (for 0x Project)
  • compound (for Compound)
  • ens (for Ethereum Name Service)
Stick to lowercase and _-separated names to keep things consistent.
Example: ethereum_projectName. See the blockchain-etl BigQuery project for other examples.
(3) Click “Download Table Definitions”. This will download 1 JSON file per event in the smart contract. Each file contains a description that lets us generate the parser for that event in BigQuery.

1b. Using the Table Definition CLI tool

This is a more flexible way to generate table definitions for any EVM chain, given you have the ABI of a smart contract.
(1) First download and save in a JSON file the ABI of the smart contract you’d like to parse. You can find ABIs in the respective explorer contact code page if you scroll down to the Contract ABI section:
Sample Smart Contract ABI
NOTE! Sometimes downloading an ABI file will include extra fields like “status” and “messages” which aren’t part of the ABI file. Try “Copy ABI to clipboard” save into a JSON file.
(2) Install Table Definition CLI tool following the instructions here:
pip install evmchain-etl-table-definition-cli
(3) Navigate to the directory where the ABI file is saved, run the following:
tabledefinition generate \
# select the ABI file
--abi-file example_uniswap_abi.json \
# create a name for the dataset, usually the project name: "uniswap"
--dataset-name uniswap \
# name the specific contract, for example, a factory contract
--contract-name UniV2_factory \
# The specific contract address to parse the data from
--contract-address 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984
The resulting config files will be saved in the output directory.
In case you want to parse some events in all contracts on the chain, you can leave the contract_address field null, like in the case of the Approval event.

Create a pull request in the correct GitHub repositories

(1) Select the chain that the smart contract is located, create a fork with your github account
(2) Clone the forked repository to your local machine, e.g. for EVM Chain ETL:
git clone https://github.com/<your-github>/evmchain-etl-table-definitions.git
(3) Go to new folder and create a new branch, e.g. in our case:
git checkout -b feature/<your-feature>
(4) Now paste the table definition files you downloaded above into a new folder, with the name of your dataset (for example: chainlink).
(5) Move this folder into the respective repository depending on the blockchain (see step 1):
For Ethereum and Polygon:
For other chains:
(6) Git add, commit, and push your changes:
git add dags/resources/stages/parse/table_definitions/
git commit -m "Added Chainlink events"
git push --set-upstream origin feature/<your-feature>
For other chains, change the directory to parse/table_definitions_{chain}/... Change the commit message to reflect what was added
Head to Github to complete the pull request!

Request a review and wait for approval

(1) Leave a comment on your PR, e.g.:
"Table definitions for Chainlink"
(2) Request a review from Evgeny: medvedev1088 on Github
(3) Wait for approval and deployment!