checkthechain 0.3.9

ctc is a tool for collecting and processing historical EVM data

⛓🔍 Check the Chain (ctc) 🔎⛓

ctc is a tool for collecting and analyzing data from Ethereum and other EVM chains

It can be used as either 1) a python package or 2) a cli tool

ctc is in beta, please report bugs to the issue tracker

Features

• data collection: collects data from archive nodes robustly and efficiently
• data storage: stores collected data on disk so that it only needs to be collected once
• data coding: handles data encoding and decoding automatically by default
• data analysis: computes derived metrics and other quantitative data summaries
• data visualization: plots data to maximize data interpretability
• protocol specificity: includes functionality for protocols like Chainlink, Uniswap, ERC20, and more
• command line interface: performs many block explorer tasks in the terminal

For detailed information check out the documentation

Contents

1. Example Usage
   1. ERC20: get all token transfers and balances of an ERC20
   2. Uniswap: get swaps, mints, and burns of a Uniswap pair
   3. Chainlink: get historical data for a Chainlink feed
   4. DAO: get DAO proposals and votes
2. Installation
3. FAQ
4. Similar Projects

📜 Legal Disclaimer 📜 ctc is available under either the MIT license or the Apache license at your option. As stated in both licenses, ctc comes with no warranty of any kind. The authors of ctc accept no responsibility for any damages or negative outcomes that result from using ctc or ctc-derived data. ctc is not audited and using it as a basis for making financial decisions is not recommended.

Example Usage

for more examples see examples in the docs

Get all token transfers of an ERC20

# python

from ctc import evm

# get token transfers
transfers = await evm.async_get_erc20_transfers(
    token='0x956f47f50a910163d8bf957cf5846d573e7f87ca',
    event_name='Transfer',
)

# get holdings of each address for a given block
holdings = await evm.async_get_erc20_balances_from_transfers(transfers=transfers, block=12345789)

# bash

ctc erc20 transfers 0x956f47f50a910163d8bf957cf5846d573e7f87ca \
    --export transfers.csv

ctc erc20 balances 0x956f47f50a910163d8bf957cf5846d573e7f87ca \
    --export balances.csv \
    --block 12345789

Get DAO proposals and votes

# python

from ctc import evm

dao_address = '0x0bef27feb58e857046d630b2c03dfb7bae567494'

proposals = await evm.async_get_events(
    contract_address=dao_address,
    event_name='ProposalCreated',
)

votes = await evm.async_get_events(
    contract_address=dao_address,
    event_name='VoteCast',
    include_timestamps=True,
)

# bash

DAO="0x0bef27feb58e857046d630b2c03dfb7bae567494"

ctc events $DAO ProposalCreated --export proposals.csv
ctc events $DAO VoteCast --export votes.csv

Get historical data for a Chainlink feed

# python

from ctc.protocols import chainlink_utils

feed = '0x31e0a88fecb6ec0a411dbe0e9e76391498296ee9'

data = await chainlink_utils.async_get_feed_data(feed)

# bash

ctc chainlink 0x31e0a88fecb6ec0a411dbe0e9e76391498296ee9 --export data.csv

Get swaps, mints, and burns of a Uniswap pool

# python

from ctc.protocols import uniswap_v2_utils

pool = '0x94b0a3d511b6ecdb17ebf877278ab030acb0a878'

swaps = await uniswap_v2_utils.async_get_pool_swaps(pool)
mints = await uniswap_v2_utils.async_get_pool_mints(pool)
burns = await uniswap_v2_utils.async_get_pool_burns(pool)

# bash

POOL="0x94b0a3d511b6ecdb17ebf877278ab030acb0a878"

ctc uniswap swaps $POOL --export swaps.csv
ctc uniswap mints $POOL --export mints.csv
ctc uniswap burns $POOL --export burns.csv

Installation

Two steps:

1. pip install checkthechain
2. run ctc setup in terminal to specify data provider and data storage path

If your shell's PATH does not include python scripts you may need to do something like python3 -m pip ... and python3 -m ctc ...

Detailed instructions can be found in the installation documentation.

ctc requires python >= 3.7 (supports 3.7, 3.8, 3.9, 3.10, and 3.11).

FAQ

• What are the goals of ctc?
  1. Treat historical data as a first-class feature: This means having historical data functionality well-integrated into each part of the of the API. It also means optimizing the codebase with historical data workloads in mind.
  2. Protocol-specific functionality: This means having built-in support for popular on-chain protocols.
  3. Terminal-based block explorer: This means supporting as many block explorer tasks as possible from the terminal. And doing so in a way that is faster than can be done with a web browser.
  4. Clean API emphasizing UX: With ctc most data queries can be obtained with a single function call. No need to instantiate objects. RPC inputs/outputs are automatically encoded/decoded by default.
  5. Maximize data accessibility: Blockchains contain vast amounts of data, but accessing this data can require large amounts of time, effort, and expertise. ctc aims to lower the barrier to entry on all fronts.
• Why use async?
  • async is a natural fit for efficiently querying large amounts of data from an archive node. All ctc functions that fetch external data use async. For tips on using async see this section in the docs. Future versions of ctc will include some wrappers for synchronous code.
• Do I need an archive node?
  • If you want to query historical data, you will need an archive node. You can either run one yourself or use a third-party provider such as Alchemy, Quicknode, or Moralis. You can also use ctc to query current (non-historical) data using a non-archive node.
• Is ctc useful for recent, non-historical data?
  • Yes, ctc has lots of functionality for querying the current state of the chain.

Similar Projects

• ethereum-etl ETL tools for bulk data gathering in python
• Trueblocks optimized EVM local indexing engine
• cast cli EVM swiss army knife (rust)
• seth cli EVM swiss army knife (bash / js)
• ethereal cli EVM swiss army knife (go)
• web3.py official Ethereum python client
• ape general python framework for many tasks including smart contract dev
• ethtx.info EVM transaction trace visualizer