Note

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

These docs are also a work in progress. Some sections are not yet complete. Feel free to report any documentation-related issues to the issue tracker.

Check the Chain (ctc)

ctc is a tool for historical data analysis of Ethereum and other EVM chains

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

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 and sharing protocol specificity: includes functionality for protocols like Chainlink and Uniswap command line interface: performs many block explorer tasks in the terminal

Guide

• To install ctc, see Installation.

• To use ctc from the command line, see Command Line Interface.

• To use ctc in python, see Python Interface.

• To use ctc with specific protocols like Uniswap or Chainlink, see the Specific Protocols (cli) or Specific Protocols (python).

• To view the ctc source code, check out the GitHub Repository.

Datatypes

Datatype	CLI	Python	Source
ABIs	CLI	Python	Source
Addresses	CLI	Python	Source
Binary Data	CLI	Python	Source
Blocks	CLI	Python	Source
ERC20s	CLI	Python	Source
ETH Balances	CLI	Python	Source
Events	CLI	Python	Source
Transactions	CLI	Python	Source

Specific Protocols

Protocol	CLI	Python	Source
Aave V2	CLI	Python	Source
Balancer	CLI	Python	Source
Chainlink	CLI	Python	Source
Compound	-	Python	Source
Curve	CLI	Python	Source
ENS	CLI	Python	Source
Fei	CLI	Python	Source
Gnosis Safe	CLI	Python	Source
Multicall	CLI	Python	Source
Rari	CLI	Python	Source
Uniswap V2	CLI	Python	Source
Uniswap V3	CLI	Python	Source
Yearn	CLI	Python	Source

External Data Sources

Data Source	CLI	Python	Source
4byte	CLI	Python	Source
CoinGecko	CLI	Python	Source
Defi Llama	CLI	Python	Source
Etherscan	CLI	Python	Source

Installation

Basic Installation

Installing ctc takes 2 steps:

1. pip install checkthechain

2. ctc setup in the terminal to run the setup wizard (can skip most steps by pressing enter)

See Configuration for additional setup options.

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

Installation requires python 3.7 or greater. see Dependencies for more information.

Upgrading

Upgrading to a new version of ctc takes two steps:

1. pip install checkthechain -U

2. Rerun the setup wizard by running ctc setup (can skip most steps by pressing enter)

If you previously installed ctc directly from a git commit, you may need to first pip uninstall checkthechain before upgrading.

When upgrading you should also check the changelog for

Uninstalling

Fully removing ctc from a machine takes three steps:

1. Uninstall the package pip uninstall checkthechain

2. Remove the config folder: rm -rf ~/.config/ctc

3. Remove the data folder: rm -rf ~/ctc_data

You can always check whether a package has been uninstalled from your python environment by attempting to import it in a fresh shell. If you see a ModuleNotFoundError, the package has been uninstalled.

>>> import ctc
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'ctc'
>>> # ctc is not uninstalled

Special Installations

Installing from source

If you would like to install the latest version of ctc you can clone the repo directly:

git clone 
cd checkthechain
python -m pip install ./

Installing in develop mode / edit mode

If you would like to make edits to the ctc codebase and actively use those edits in your python programs, you can install the package in developer mode with the -e flag:

git clone 
cd checkthechain
python -m pip install -e ./

Libraries

On a fresh installation of Ubuntu or Debian, you may need to manually install the build-essential and python-dev packages. Machines that are used for active python development probably already have these packages installed.

PYTHON_VERSION=$(python3 -c "import sys; print('python' + str(sys.version_info.major) + '.' + str(sys.version_info.minor))")

python3 -m pip install $PYTHON_VERSION-dev
sudo apt-get install build-essential

Dependencies

TLDR

This page is only aimed at users that would like know what ctc depends on under the hood.

If you just want to install ctc then check out the Installation docs.

OS Dependencies

Usage of ctc requires python 3.7 or greater.

When using a fresh installation of Debian or Ubuntu, you may need to manually install build-essential and python-dev. These are libraries required by many python packages including ctc. If you are an active python user it’s likely that these are already installed on your machine. If you are setting up a new machine or environment, you may need to install them according to your operating system and python version.

To install these os dependencies on a fresh Debian / Ubuntu machine, can use the following:

PYTHON_VERSION=$(python3 -c "import sys; print('python' + str(sys.version_info.major) + '.' + str(sys.version_info.minor))")

python3 -m pip install $PYTHON_VERSION-dev
sudo apt-get install build-essential

Libraries

ctc depends on a few different types of external packages:

1. data science dependencies include standard python library packages including numpy and pandas.

2. IO dependencies include packages like aiohttp for network communication and toml for file io.

3. toolsuite dependencies are general python utilities coming the toolsuite set of repos. These are written by the same authors as ctc.

4. EVM/Cryptography dependencies include pycryptodome, rlp, and eth_abi.

Each of these dependencies has its own dependencies.

Reliance on these packages will be minimized in future releases to minimize attack surface and to maximize the number of environments in which ctc can be run. Some of the common libraries in the EVM ecosystem have incompatible requirements. For example, ethereum-etl requires older versions of web3py and eth_abi, and so a single environment cannot contain the most recent versions of all of these packages.

Type Checking

ctc uses mypy for static analysis of type annotations. This helps catch errors before they can appear at runtime. Custom types used by ctc can be found in the ctc.spec subpackage.

Checks are currently performed using mypy=0.930. Future mypy versions and features will be used as they become available. End users of ctc do not need mypy unless they are interested in running these type checks.

New python type annotation features will be used as they become available using typing_extensions. By using typing_extensions and from __future__ import annotations, new typing features can be used as they are released without sacrificing backward compatibility.

Testing

ctc tests are run using pytest 7.0.0 with the pytest-asyncio extension. These can be run using pytest . in the /tests directory.

Documentation

ctc documentation is built using sphinx 4.5.0. Source files and build instructions can be found in the Documentation Repository.

Databases

ctc stores much of the data it downloads in sql databases. Support for sqlite is currently in beta and support for postgresql is coming soon.

For more details see Data Storage

Configuration

TLDR

Run ctc setup on the command line to create the config. Run it again to edit the config.

ctc uses a configuration file to control its behavior.

Setting Config Parameters

Users do not need to directly create or edit ctc config files. Instead, all config parameters can be adjusted by using the setup wizard by running ctc setup on the command line. This can be used both for creating new configs and modifying the current config.

By default ctc will looks for a config file at ~/.config/ctc/config.json. But if the CTC_CONFIG_PATH environment variable is set, it will use that path instead.

ctc can also function under a “no-config” mode, where ctc setup does not need to be run. To use this mode, simply set the ETH_RPC_URL to an RPC provider url.

Config Parameters

The config file consists of key-value pairs. The keys:

• config_spec_version: the ctc version used to create the config

• data_dir: the directory where ctc stores its data

• providers: metadata about RPC providers

• networks: metadata about networks including their names and chain_id’s

• default_network: default network to use

• default_providers: default provider for each network

• db_configs: database configuration information

• log_rpc_calls: whether to log rpc calls

• log_sql_queries: whether to log sql queries

A python type specification for the config can be found in the config typedefs file.

Reading Config Parameters

On the command line, running ctc config will print information about the config including its location on the filesystem and its current values.

In python, the ctc.config module has many functions for getting config data:

from ctc import config

config_path = config.get_config_path()
data_dir = config.get_data_dir()
providers = config.get_providers()

Changelog

until version 1.0.0 is reached, will use 0.X.Y versioning where X is for breaking changes / major feature upgrades, and Y is for bug fixes / minor feature upgrades

0.3.0

September 25, 2022

This is a significant release that includes features such as: sql database integration, refactored documentation, streamlined syntax, performance optimizations, and many new types of data queries. This release also includes lots of small bug fixes and quality-of-life improvements not listed below.

DB

• integrate sql db for storing collected data

• create tables for: blocks, contract abis, contract creation blocks, ERC20 metadata, 4byte signatures, and Chainlink feeds

• add flags to functions for whether db should be used

• auto-intake collected data into db by default

Documentation

• create external documentation page https://ctc.readthedocs.io/en/latest

CLI

• add help messages and examples to each subcommand

• add color to cli output

• optimize cli startup times

• allow all cli commands to use ens names in place of addresses

• add many subcommands including

  • storage, limits, encode, proxy, bytecode, chains, selector

  • abi decompile command for decoding ABI of solidity and vyper contracts

  • (see ctc -h for proper full list)

  • XX do a diff with 3.10?

• add commands for events, candlestick charting

• add --json to many cli commands to output data as json

Config

• make configuration file optional by using a default config and looking for RPC provider in ETH_RPC_URL env var

• when loading old config versions, attempt to transparently convert it to new config version

• added better config validation

• add shell alias configuration to ctc setup

Protocols

• new protocol-specific functionality for Gnosis and Etherscan

• add subcommands to previous covered protocols

• use binary search to implement trade-to-price function for Uniswap V3 and other AMMs

Data Operations

• new transaction and call data decoding system

• automatically query proxy ABI when querying a contract’s ABI

  • if a function ABI or event ABI cannot be found, re-query contract proxy to check for ABI updates

• add functionality for fetching all transactions of a given address

• add functionality for predicting block numbers of future timestamps

Testing

• use tox for testing each python version

• create legacy test environment with minimal version of each dependency

• test that all cli commands have examples and test that the examples work

• enforce many coding conventions using tests

Performance

• utilize caches and concurrency when possible

• add appropriate rate limits for etherscan and 4byte for scraping

Python

• upgrade from setuptools / setup.py to flit / pyproject.toml

• use black for all py files in repo

• use strict mode for mypy typing annotations

• reduce number of implicit package dependencies by more than 50%

  • fork eth-abi package as eth-abi-lite to remove dependence on eth-abi, eth-utils, toolz and cytools

  • specify min and max version of each dependency to prevent future backwards incompability

Other

• add logging system and allow use of ctc log command to follow logs

• populate default data directory with metadata of: 22 networks, >1000 ERC20 tokens, and all Chainlink feeds

• add functions for converting block numbers into timestamps for x-axis labels of plots

Upgrade Guide

1. Run pip install -U checkthechain

2. Run ctc setup

3. There are some minor api changes (see below)

API Changes

Version 0.3.0 contains some breaking changes to make the API more consistent and intuitive. Care was taken to minimize these breaking changes. Future versions of ctc will aim to maximize backward compatilibity as much as possible.

• config (running ctc setup command will automatically upgrade old config and data directory)

  • new config schema using flat structure instead of nested hierarchy (see ctc.spec.typedefs.config_types)

  • new data directory schema that better reflects underlying data relationships (see ctc.config.upgrade_utils.data_dir_versioning)

• directory deprecated in favor of functions in config, db, and evm

• evm

  • decode_function_output() arg: package_named_results –> package_named_outputs

  • async_get_proxy_address() –> async_get_proxy_implementation()

  • erc20 balance and allowance functions:

    • arg address –> wallet

    • arg addresses –> wallets

    • async_get_erc20_holdings_from_transfers –> async_get_erc20_balances_from_transfers

    • async_get_block_timestamp() modes renamed from before, after, equal to <=, >=, ==

    • async_get_erc20_balance_of –> async_get_erc20_balance

    • async_get_erc20_balance_of_addresses –> async_get_erc20_balances_of_addresses

    • async_get_erc20s_balance_of –> async_get_erc20s_balances

    • async_get_erc20_balance_of_by_block –> async_get_erc20_balance_by_block

    • async_get_erc20s_allowances_by_address –> async_get_erc20s_allowances_of_addresses

• protocols

  • curve_utils.async_get_pool_addresses –> curve_utils.async_get_pool_tokens

  • rari_utils.get_pool_tvl_and_tvb –> rari_utils.async_get_pool_tvl_and_tvb

  • use for blockwise functions always use by_block rather than per_block

  • uniswap_v2_utils.async_get_pool_swaps –> uniswap_v2_utils.async_get_pool_trades

  • functions for querying data from specific DEX’s now all use unified a unified DEX syntax and API

• spec

  • ConfigSpec –> Config

  • PartialConfigSpec –> PartialConfig

  • ProviderSpec –> ProviderReference

• toolbox

  • move toolbox.amm_utils, toolbox.twap_utils, and toolbox.lending_utils under toolbox.defi_utils

• cli

  • all commands are standardized on --export rather than --output to specify data export targets

• for functions that print out summary information, instead of using a conventions of print_<X>() and summarize_<X>, use single convention print_X()

• only allow positional arguments for the first two arguments of every function

0.2.10

March 26, 2022

• add functionality for G-Uni Gelato, multicall

• add Fei yield dashboard analytics

• add commands for ABI summarization

• signficantly improve test coverage

0.2.9

March 18, 2022

• add Uniswap V3 functionliaty

• improve Chainlink functions, commands, and feed registry

• add twap_utils

• add cli aliases

• many small fixes

• handle various types of non-compliant erc20s

0.2.8

March 2, 2022

• fix str processing bug

0.2.7

March 2, 2022

• add robustness and quality-of-life improvements to data cache

• add 4byte functionality

• add Coingecko functionality

0.2.6

February 24, 2022

• fix many typing annotation issues

• add Curve functionality

• add Fei functionality

0.2.5

February 16, 2022

• add ENS functionality

• add hex, ascii, checksum, and lower cli commands

• add Rari lens

0.2.4

February 15, 2022

• python 3.7 compatibility fixes

0.2.3

February 14, 2022

• add many cli commands

• refactor existing cli commands

0.2.2

February 11, 2022

• add python 3.7 and python3.8 compatibility

0.2.1

February 9, 2022

initial public ctc release

FAQ

What are the goals of ctc?

• 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.

• Protocol-specific functionality: This means having built-in support for popular on-chain protocols.

• 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.

• 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.

• 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.

Obtaining Data

ctc collects data from a variety of sources, including RPC nodes, metadata databases, block explorers, and market data aggregators. After initial collection, much of this data is then stored.

Sources of Historical Data

ctc collects the majority of its data from RPC nodes using the EVM’s standard JSON-RPC interface. Collection of historical data (as opposed to recent data) requires use of an archive node.

There are 3 main ways to gain access to an RPC node:

1. Run your own node: Although this requires more time, effort, and upfront cost than the other methods, it often leads to the best results. Erigon is the most optimized client for running an archive node.

2. Use a 3rd-party private endpoint: Private RPC providers (e.g. Alchemy, Quicknode, or Moralis) provide access to archive nodes, either through paid plans or sometimes even through free plans.

3. Use a 3rd-party public endpoint: You can query data from public endpoints like Infura. This approach is not recommended for any significant data workloads, as it often suffers from rate-limiting and poor historical data availability.

ctc’s RPC config is created and modified by running the setup wizard.

Other types of data

Beyond RPC data there are other types of data that ctc collects, including:

• ABIs of Contracts, Functions, and Events from Etherscan and 4byte

• Market Data from DefiLlama and CoinGecko

Storing Data

ctc places much of the data that it retreives into local storage. This significantly improves the speed at which this data can be retrieved in the future and it also reduces the future load on data sources.

The default configuration assumes that most data is being queried from a remote RPC node. Some performance-minded setups, such as running ctc on the same server as an archive node, might achieve better tradeoffs between speed and storage space by tweaking ctc’s local storage features.

Data Storage Backends

ctc uses two main storage backends.

Filesystem

ctc stores some files on the filesystem. By default, ctc will place its data folder in the user’s home directory at ~/ctc_data. This is suitable for many setups. However, there are situations where it would be better to store data somewhere else, such as if the home directory is on a drive of limited size, or it the home directory is on a network drive with significant latency. The data directory can be moved by running the setup wizard ctc setup.

Total storage usage of ctc on the filesystem can be found by checking the size of the ctc data directory.

SQL Databases

ctc also stores lots of data in SQL database tables. Schemas for these tables can be found here. ctc currently supports sqlite with Postgresql support coming soon.

Total storage usage of ctc in the database can be found by running ctc db -v in the terminal.

You can connect to the currently configured database by running ctc db login in the terminal. Don’t do this unless you know what you’re doing.

Performance

TLDR

Even in suboptimal conditions, ctc uses optimizations that allow running many types of workloads at acceptable levels of performance. This page is for those who wish to squeeze additional performance out of ctc.

Optimizing Performance

There are many levers and knobs available for tuning ctc’s performance.

RPC Provider

Different 3rd party RPC providers can vary significantly in their reliability and speed. For example, some providers have trouble with large historical queries.

Operations in ctc that fetch external data are usually bottlenecked by the RPC provider, specifically the latency to the RPC provider. This latency can be reduced by running ctc as closely as possible to the archive node:

• Fastest = running ctc on the same server that is running the archive node

• Fast = running ctc on the same local network as the archive node

• Slower = running ctc in the same geographic region as the archive node

• Slowest = running ctc in a different geographic region than the archive node

If using a 3rd party RPC provider, you should inquire about where their nodes are located and plan accordingly.

ctc’s default configuration assumes that the user is querying an RPC node on a remote network. This leads ctc to locally store much of the data that it retrieves. However, it’s possible that alternate settings might be optimal in different contexts. For example if ctc is run on the same server as an archive node, then it’s possible that certain caches might hurt more than they help. Cache settings are altered using ctc setup on the command line.

Python Versions

More recent versions of python are generally faster. Upgrading to the latest python version is one of the easiest ways to improve code performance. In particular, the upcoming python 3.11 has much faster startup times and shows improvement across many benchmarks. This will make ctc’s cli commands feel especially quick and responsive.

Python Packages

By default, ctc tries to minimize its dependencies and minimize the number of build steps that happen during installation. This does carry a bit of performance cost. Faster versions of various packages can be installed using:

pip install checkthechain[performance]

If ctc detects that these additional performance packages are installed, it will use those instead of the default packages. This can produce a modest performance increase for some workloads.

Data Storage

ctc’s default data directory is ~/.config/ctc/ in the user’s home directory. If this directory is on a slow drive (especially a network drive), this will negatively impact performance. To optimize performance, place the data directory on as fast a drive as possible. This can be done by running the setup wizard ctc setup.

Data Caching

For tasks that require many RPC requests, or require lots of post-processing (or are demanding in other ways), you should consider caching the result in-memory or on-disk. One way to do this is with the toolcache package. With toolcache a simple decorator adds an in-memory or on-disk cache to the expensive function.

For example, if you are using ctc to create data payloads for a historical analytics dashboard, you might use a pattern similar to this:

import toolcache


async def create_data_payload(timestamps):
    return [
        compute_timestamp_stats(timestamp=timestamp)
        for timestamp in timestamps
    ]


# create an on-disk cache entry for each timestamp
@toolcache.cache('disk')
async def compute_timestamp_stats(timestamp):
    super_expensive_operation()

Logging

Logging of RPC requests and SQL queries consumes a non-zero amount of resources. If you don’t need logging, disabling it can squeeze out a bit of extra performance. This can be done by running the setup wizard ctc setup.

Benchmarking Performance

To truly optimize your environment and implementation, you will need to run your own benchmarks.

Benchmarking Speed

The simplest way to benchmark the speed of a CLI command is time. Running time <command> will run a given command and report the run time.

Benchmarking the speed of python code snippets is slightly more complicated but also has many tools available:

1. Synchronous code can be easily profiled used IPython’s built-in magics %timeit, %%timeit, %prun, and %%prun

2. If using a Jupyter notebook, the Execute Time extension can be extremely useful for getting a crude estimate of how long each code cell takes to run. This works for both synchronous and asynchronous code.

3. For a more programmatic approach you can use python’s built-in profilers or 3rd party profilers such as Scalene or pyflame.

Measuring Storage Usage

It is also valuable to measure ctc’s storage usage to check whether it falls into an acceptable range for a given hardware setup. Storage usage in the ctc data folder can be found by running a storage profiling command like du -h or dust. Storage usage in databases can be found by running ctc db -v.

Monitoring

Logging

ctc can log outgoing RPC requests and SQL queries. This functionality can be enabled or disabled using ctc setup.

Logs are stored in logs subdirectory of the ctc data dir (default = ~/ctc_data).

Running ctc log in the terminal will begin watching for changes to the log files. This provides a detailed view of external queries as they happen, which can be useful for debugging and ensuring that external calls are happening as expected.

Logs are written to disk using a non-blocking queue, making it suitable for async applications and imparting minimal impact on performance. These logs are also rotated once they reach a certain size (default = 10MB). However, being non-blocking also means that the timestamps in the logs lose a bit of temporal precision, and so they do not provide a precise picture of event timing.

Logs are managed by the Loguru package. Loguru must be installed for logging to be enabled (pip install loguru).

Other monitoring

Beyond the built-in logging, the best way to monitor ctc is through standard 3rd party tools.

Recommended utilities for profiling resource usage:

• CPU Usage: htop, btop

• Storage IO: iotop, btop

• Storage Capacity: du, dust, btop

• Network Usage: nethogs, btop

If your situation calls for a more programmatic monitoring approach, then you probably already know what tools you need.

Basic Usage

The ctc cli command performs operations related to processing EVM data, especially operations related to historical data analysis. Many different EVM datasets can be generated by individual calls to ctc.

Typical usage is ctc <subcommand> [options], using Subcommands. To view the complete list of subcommands use ctc -h.

Most of the cli documentation pages are copied from ctc’s in-terminal help messages.

Subcommands

Note

Click on a subcommand to view its documentation page.

usage:
    ctc <subcommand> [options]

description:
    ctc is a tool for historical data analysis of Ethereum and other EVM chains
    
    if using ctc for the first time, run:
        ctc setup
    
    for quick lookups of an address, block, tx, or timestamp, run:
        ctc QUERY
    
        where QUERY is an address, block number, tx hash, or timestamp

    to view help about a specific subcommand run:
        ctc <subcommand> -h

available subcommands:

    admin subcommands
    aliases             view and manage ctc shell aliases
    chains              display information about configured chains
    config              print current config information
    db                  display database status
    log                 display logs
    setup               run ctc setup wizard

    compute subcommands
    ascii               convert hex to ascii
    checksum            compute checksum of address
    create address      generate address in the style of CREATE or CREATE2
    decode              decode encoded EVM datatypes
    decode call         decode EVM call data
    encode              encode data as EVM datatypes
    hex                 convert text data to hex representation
    int                 convert data to integer
    keccak              compute keccak hash of data
    limits              display limits of various datatypes
    lower               convert string to lower case
    rlp encode          RLP encode data
    selector            compute 4byte function selector using function signature

    data subcommands
    abi                 display abi of contract
    abi diff            display diff of two contract ABI's
    address             summarize address
    address txs         output all transactions from address
    block               summarize block
    blocks              output information about blocks
    bytecode            get raw bytecode stored at address
    call                output result of a call
    call all            display outputs of all contract's read-only functions
    calls               output the result of multiple contract eth_call's
    chain               display chain_id of provider
    decompile           decompile contract abi
    dex chart           display candlestick chart of DEX pool trades
    dex pool            show information about a pool
    dex pools           list dex pools
    dex trades          get DEX swaps
    erc20               display information about ERC20
    erc20 balance       output an ERC20 balance
    erc20 balances      output ERC20 balances of blocks / addresses / tokens
    erc20 transfers     output information about ERC20 transfers
    eth balance         output ETH balance of address
    eth balances        output ETH balance across blocks or addresses
    events              get contract events
    gas                 output gas summary of block range
    proxy               print proxy information about contract
    proxy register      register custom proxy implementation of a contract
    storage             get value of storage slot
    symbol              convert ERC20 address to symbol, or symbol to address
    timestamp           get block of timestamp
    tx                  display transaction data, receipt, call data, & logs

    protocol subcommands
    4byte               lookup 4byte signature
    4byte build         build local copy of 4byte database
    aave                output aave usage statistics
    aave addresses      output aave-related addresses
    cg                  output coingecko market data
    chainlink           output Chainlink feed data
    chainlink feeds     list all Chainlink feeds
    curve pools         list curve pools
    ens                 summarize ENS entry
    ens exists          output whether ENS name exists
    ens hash            output hash of ENS name
    ens owner           output owner of ENS name
    ens records         output text records of ENS name
    ens resolve         resolve ENS name
    ens reverse         reverse ENS lookup address
    etherscan           open etherscan query in browser or fetch
    fei analytics       output data payload for app.fei.money/analytics
    fei depth           output FEI liquidity depth information
    fei dex             show information related to FEI on DEX's
    fei pcv             output summary of Fei PCV
    fei pcv assets      output summary of Fei PCV assets
    fei pcv deposits    output summary of Fei PCV deposits
    fei psms            display recent FEI redemptions
    gnosis              print information about a gnosis safe
    llama               output data from Defi Llama api
    llama chain         output data about a chain tracked by Defi Llama
    llama chains        output data about chains tracked by Defi Llama
    llama pool          output data about a pool tracked by Defi Llama
    llama pools         output data about pools tracked by Defi Llama
    llama protocol      output data about a protocol tracked by Defi Llama
    llama protocols     output data about protocols tracked by Defi Llama
    rari                summarize fuse pool, token, or platform
    rari pools          list all Rari fuse pools
    uniswap burns       output information about pool burns
    uniswap chart       chart price action of uniswap pools
    uniswap mints       output information about pool mints
    uniswap pool        summarize pool
    uniswap swaps       output information about pool swaps
    yearn               display summary of Yearn vaults
    yearn addresses     output Yearn addresses

    other subcommands
    cd                  change working directory to ctc-related location
    help                output help
    version             print cli version

Admin Subcommands

Note

Click on a subcommand to view its documentation page.

usage:
    ctc <subcommand> [options]

description:
    ctc is a tool for historical data analysis of Ethereum and other EVM chains
    
    if using ctc for the first time, run:
        ctc setup
    
    for quick lookups of an address, block, tx, or timestamp, run:
        ctc QUERY
    
        where QUERY is an address, block number, tx hash, or timestamp

    to view help about a specific subcommand run:
        ctc <subcommand> -h

admin subcommands:
    aliases             view and manage ctc shell aliases
    chains              display information about configured chains
    config              print current config information
    db                  display database status
    log                 display logs
    setup               run ctc setup wizard

aliases

usage:
    ctc aliases  [options]

description:
    view and manage ctc shell aliases
    
    these aliases allow you to call ctc subcommands without typing the "ctc" part
    
        for example, you can type 4byte 0xa9059cbb instead of ctc 4byte 0xa9059cbb
    
    these aliases must go in your shell config file
    
        this can be done using one of the following methods:
        1. use ctc aliases --append to append to autodetected config files
        2. use ctc aliases >> CONFIG_PATH to append the aliases to config file
        3. manually paste the aliases into your config file
    
        the path to your terminal file depends on shell:
        - bash: ~/.profile or ~/.bashrc
        - zsh: ~/.zshrc
        - fish: ~/.config/fish/config.fish
    
    to learn more about the underlying commands, run ctc help
    
    depending on preference, can use all aliases or just a subset of them

examples:
    ctc aliases 

    ctc aliases --raw

    ctc aliases --install

arguments:
    --raw        output aliases as raw script file
    --install    install/upgrade aliases in shell config (will ask for confirmation)

chains

usage:
    ctc chains  [options]

description:
    display information about configured chains

examples:
    ctc chains 
    ctc chains --verbose

arguments:
    --verbose, -v    display additional information including RPC urls

config

usage:
    ctc config  [options]

description:
    print current config information

examples:
    ctc config 
    ctc config --reveal
    ctc config --json

arguments:
    --reveal      show sensitive information in config
    --json        output config as json
    --no-color    do not use color

db

usage:
    ctc db  [options]

description:
    display database status

example:
    ctc db 

arguments:
    -v, --verbose    display additional information

log

usage:
    ctc log 

description:
    display logs

example:
    # tail logs
    ctc log 

setup

usage:
    ctc setup  [options]

description:
    run ctc setup wizard
    
    setup wizard sets up ctc config and ctc data directory
    
    each step is optional
    - by default, setup process will leave existing settings unchanged
    - setup can be rerun multiple times idempotently
    
    can run in headless mode (non-interactive mode) using `--headless`:
    - headless mode will use the default values for each unspecified parameter
    - headless mode is useful in scripts when user input is not possible
    - if config file already exists, headless mode must be run with `--overwrite`

examples:
    ctc setup 

    ctc setup --headless

    ctc setup --headless --overwrite

arguments:
    --headless                     run in headless mode
    --ignore-old-config            ignore settings specified in previous config
    --skip-networking              skip network configuration steps
    --rpc-url RPC_URL              url to use for RPC node
    --rpc-chain-id RPC_CHAIN_ID    chain id of RPC node given by `--rpc-url`
    --data-dir DATA_DIR            directory where to store ctc data
    --disable-logs                 disable ctc logs
    --skip-db                      skip creating db until it next time it is needed
    --overwrite                    overwrite old config file
    --skip-aliases                 disable ctc logs

Compute Subcommands

Note

Click on a subcommand to view its documentation page.

usage:
    ctc <subcommand> [options]

description:
    ctc is a tool for historical data analysis of Ethereum and other EVM chains
    
    if using ctc for the first time, run:
        ctc setup
    
    for quick lookups of an address, block, tx, or timestamp, run:
        ctc QUERY
    
        where QUERY is an address, block number, tx hash, or timestamp

    to view help about a specific subcommand run:
        ctc <subcommand> -h

compute subcommands:
    ascii               convert hex to ascii
    checksum            compute checksum of address
    create address      generate address in the style of CREATE or CREATE2
    decode              decode encoded EVM datatypes
    decode call         decode EVM call data
    encode              encode data as EVM datatypes
    hex                 convert text data to hex representation
    int                 convert data to integer
    keccak              compute keccak hash of data
    limits              display limits of various datatypes
    lower               convert string to lower case
    rlp encode          RLP encode data
    selector            compute 4byte function selector using function signature

ascii

usage:
    ctc ascii DATA

description:
    convert hex to ascii

examples:
    ctc ascii 0x766974616c696b
    ctc ascii 0x7475726475636b656e

arguments:
    DATA    hex data to convert

checksum

usage:
    ctc checksum ADDRESS

description:
    compute checksum of address

example:
    ctc checksum 0xd8da6bf26964af9d7eed9e03e53415d37aa96045

arguments:
    ADDRESS    address to get checksum of

create address

usage:
    ctc create address SENDER NONCE_OR_SALT [INIT_CODE]

description:
    generate address in the style of CREATE or CREATE2

examples:
    ctc create address 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 123
    ctc create address 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 0xaabb 0xaabbccdd

arguments:
    SENDER           sender address
    NONCE_OR_SALT    sender nonce (for CREATE) or salt (for CREATE2)
    INIT_CODE        initialization bytecode for CREATE2

decode

usage:
    ctc decode TYPE DATA

description:
    decode encoded EVM datatypes
    
    for simple datatypes, no quotes required
    
    for nested datatypes, enclose in quotes and quote contained addresses

examples:
    ctc decode address 0x0000000000000000000000006b175474e89094c44da98b954eedeac495271d0f
    ctc decode "(int64,int64,int64)" 0x00000000000000000000000000000000000000000000000000000000000000010000000000000000
0000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003

arguments:
    TYPE    type of data to decode
    DATA    data to decode


usage of subcommands:
    ctc decode can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc decode <subcommand> -h

available subcommands:
    call    decode EVM call data

decode call

usage:
    ctc decode call ARGS [options]

description:
    decode EVM call data
    
    syntax is one of
        1. ctc decode call CALL_DATA
        2. ctc decode call CONTRACT_ADDRESS CALL_DATA
        3. ctc decode call TX_HASH --tx

examples:
    ctc decode call 0xdac17f958d2ee523a2206206994597c13d831ec7 0xa9059cbb00000000000000000000000021dd5c13925407e5bcec3f
27ab11a355a9dafbe3000000000000000000000000000000000000000000000000000000003fd629c0
    ctc decode call 0xeefba1e63905ef1d7acba5a8513c70307c1ce441 0x252dba420000000000000000000000000000000000000000000000
00000000000000002000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000
0000000000000000000000000400000000000000000000000000000000000000000000000000000000000000100000000000000000000000000a658
03ad604668e26a81be92c9f1c90354255eae00000000000000000000000000000000000000000000000000000000000000400000000000000000000
000000000000000000000000000000000000000000044bba06f270000000000000000000000000a01960ddf19c59e43cbdf0b5ab9278d7459e76e00
0000000000000000000000e9822f18f2654e606a8dff9d75edd98367e7c0ae000000000000000000000000000000000000000000000000000000000
00000000000000000000000a65803ad604668e26a81be92c9f1c90354255eae00000000000000000000000000000000000000000000000000000000
00000040000000000000000000000000000000000000000000000000000000000000002451cff8d90000000000000000000000000a01960ddf19c59
e43cbdf0b5ab9278d7459e76e00000000000000000000000000000000000000000000000000000000
    ctc decode call 0xcb2931bd1c078f70106017f2e0c378fa9f648aa7d17c1d87240764b65e4626c9

arguments:
    ARGS        `CALL_DATA` or `CONTRACT_ADDRESS CALL_DATA` or `TX_HASH`
    --nested    whether to decode nested calls

encode

usage:
    ctc encode TYPE DATA [options]

description:
    encode data as EVM datatypes
    
    for simple datatypes, no quotes required
    
    for nested datatypes, enclose in quotes and quote contained addresses

examples:
    ctc encode address 0x6b175474e89094c44da98b954eedeac495271d0f
    ctc encode "(int64,int64,int64)" "[1,2,3]"

arguments:
    TYPE        datatype used for encoding
    DATA        data to be encoded
    --packed    encode like solidity's abi.encodePacked()

hex

usage:
    ctc hex TEXT [options]

description:
    convert text data to hex representation

examples:
    ctc hex vitalik
    ctc hex turducken

arguments:
    TEXT     ascii or other text data to convert
    --raw    omit the "0x" prefix

int

usage:
    ctc int DATA

description:
    convert data to integer

examples:
    ctc int 0xa00
    ctc int 0x123456789abdef

arguments:
    DATA    hex data to convert to integer

keccak

usage:
    ctc keccak DATA [options]

description:
    compute keccak hash of data
    
    by default, data treated as hex if it starts with "0x", or treated as text otherwise

examples:
    # take hash of hex data
    ctc keccak 0x678acb67

    # take hash of text
    ctc keccak vitalik

arguments:
    DATA      data to hash
    --text    treat input data as text instead of hex
    --hex     treat data as hex
    --raw     omit "0x" prefix on output

limits

usage:
    ctc limits  [options]

description:
    display limits of various datatypes

examples:
    ctc limits 
    ctc limits --verbose
    ctc limits --bits 256 512 1024

arguments:
    --verbose, -v      display all possible bit values
    --bits, -b BITS    specify number of bits, either single or as list

lower

usage:
    ctc lower TEXT

description:
    convert string to lower case

example:
    ctc lower 0x956F47F50A910163D8BF957Cf5846D573E7f87CA

arguments:
    TEXT    text to convert

rlp encode

usage:
    ctc rlp encode DATA

description:
    RLP encode data

examples:
    ctc rlp encode 1024
    ctc rlp encode cat
    ctc rlp encode 0x956f47f50a910163d8bf957cf5846d573e7f87ca

arguments:
    DATA    data to encode (can enclose with quotes)

selector

usage:
    ctc selector TEXT_SIGNATURE

description:
    compute 4byte function selector using function signature
    
    in most cli shells must enclose parentheses in quotes " "

examples:
    ctc selector "totalSupply()"
    ctc selector "transfer(address,uint256)"

arguments:
    TEXT_SIGNATURE    signature of function

Data Subcommands

Note

Click on a subcommand to view its documentation page.

usage:
    ctc <subcommand> [options]

description:
    ctc is a tool for historical data analysis of Ethereum and other EVM chains
    
    if using ctc for the first time, run:
        ctc setup
    
    for quick lookups of an address, block, tx, or timestamp, run:
        ctc QUERY
    
        where QUERY is an address, block number, tx hash, or timestamp

    to view help about a specific subcommand run:
        ctc <subcommand> -h

data subcommands:
    abi                 display abi of contract
    abi diff            display diff of two contract ABI's
    address             summarize address
    address txs         output all transactions from address
    block               summarize block
    blocks              output information about blocks
    bytecode            get raw bytecode stored at address
    call                output result of a call
    call all            display outputs of all contract's read-only functions
    calls               output the result of multiple contract eth_call's
    chain               display chain_id of provider
    decompile           decompile contract abi
    dex chart           display candlestick chart of DEX pool trades
    dex pool            show information about a pool
    dex pools           list dex pools
    dex trades          get DEX swaps
    erc20               display information about ERC20
    erc20 balance       output an ERC20 balance
    erc20 balances      output ERC20 balances of blocks / addresses / tokens
    erc20 transfers     output information about ERC20 transfers
    eth balance         output ETH balance of address
    eth balances        output ETH balance across blocks or addresses
    events              get contract events
    gas                 output gas summary of block range
    proxy               print proxy information about contract
    proxy register      register custom proxy implementation of a contract
    storage             get value of storage slot
    symbol              convert ERC20 address to symbol, or symbol to address
    timestamp           get block of timestamp
    tx                  display transaction data, receipt, call data, & logs

abi

usage:
    ctc abi ADDRESS NAMES [options]

description:
    display abi of contract

examples:
    ctc abi 0x956f47f50a910163d8bf957cf5846d573e7f87ca
    ctc abi 0x2b79b3c3c7b35463a28a76e0d332aab3e20aa337 Mint Burn Swap Sync
    ctc abi 0x2b79b3c3c7b35463a28a76e0d332aab3e20aa337 -f
    ctc abi 0x2b79b3c3c7b35463a28a76e0d332aab3e20aa337 -e
    ctc abi 0x956f47f50a910163d8bf957cf5846d573e7f87ca --json
    ctc abi 0x956f47f50a910163d8bf957cf5846d573e7f87ca --map-names --python

arguments:
    ADDRESS            address of contract
    NAMES              name of function or event
    --json             json only
    --json-raw         json only, without sorting or indentations
    --map-names        output ABI as map where names are the keys
    --map-selectors    output ABI as map where hash selectors are the keys
    -f, --functions    display function abi's only
    -e, --events       display event abi's only
    --search SEARCH    query of name of function or event abi
    --verbose, -v      include extra abi data
    --python           output data as pep8-formatted python syntax
    --update           re-import ABI from etherscan (e.g. if proxy has changed)


usage of subcommands:
    ctc abi can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc abi <subcommand> -h

available subcommands:
    diff    display diff of two contract ABI's

abi diff

usage:
    ctc abi diff FIRST_ADDRESS SECOND_ADDRESS [options]

description:
    display diff of two contract ABI's

example:
    ctc abi diff 0x5f4ec3df9cbd43714fe2740f5e3616155c5b8419 0xf79d6afbb6da890132f9d7c355e3015f15f3406f

arguments:
    FIRST_ADDRESS     first contract address
    SECOND_ADDRESS    second contract address
    --functions       show functions only
    --events          show events only

address

usage:
    ctc address ADDRESS [options]

description:
    summarize address
    
    for contracts, will display ABI

example:
    ctc address 0x956f47f50a910163d8bf957cf5846d573e7f87ca

arguments:
    ADDRESS                 address to get summary of
    -v, --verbose           emit extra output
    --raw                   emit abi in raw json
    --network NAME_OR_ID    network name or id to scan address of


usage of subcommands:
    ctc address can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc address <subcommand> -h

available subcommands:
    txs    output all transactions from address

address txs

usage:
    ctc address txs ADDRESS [options]

description:
    output all transactions from address

examples:
    ctc address txs 0xd8da6bf26964af9d7eed9e03e53415d37aa96045

    ctc address txs 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -v

arguments:
    ADDRESS          get transactions from this address
    -v, --verbose    display additional information

block

usage:
    ctc block [BLOCK] [options]

description:
    summarize block

examples:
    ctc block 14000000
    ctc block 14000000 --json
    ctc block --timestamp 1600000000

arguments:
    BLOCK                    block number
    --timestamp TIMESTAMP    specify block by timestamp
    --verbose, -v            emit extra information
    --json                   output block as raw json

blocks

usage:
    ctc blocks BLOCKS [options]

description:
    output information about blocks

examples:
    # get blocks 14000000 through 14000010
    ctc blocks 14000000:14000010

    # get blocks 14000000 through 15000000, every 100000 blocks
    ctc blocks 14000000:15000000:100000

    # get blocks 14000000 through 15000000, every 100000 blocks
    ctc blocks 14000000:15000000 -n 10

    # get blocks 14000000 through 14000100, with specific attributes
    ctc blocks 14000000:14000100 --attributes timestamp,number

arguments:
    BLOCKS                     block range to fetch
    -n N                       number of blocks in block slice
    --attributes ATTRIBUTES    attributes to fetch from each block
    --export EXPORT            file path for output (.json or .csv)
    --overwrite                specify that output path can be overwritten
    --provider PROVIDER        rpc provider to use

bytecode

usage:
    ctc bytecode ADDRESS

description:
    get raw bytecode stored at address

example:
    ctc bytecode 0x6b175474e89094c44da98b954eedeac495271d0f

arguments:
    ADDRESS    address where bytecode is stored

call

usage:
    ctc call ADDRESS FUNCTION ARGS [options]

description:
    output result of a call

examples:
    ctc call 0x956f47f50a910163d8bf957cf5846d573e7f87ca totalSupply
    ctc call 0x956f47f50a910163d8bf957cf5846d573e7f87ca 0x18160ddd
    ctc call 0x956f47f50a910163d8bf957cf5846d573e7f87ca '{"name": "totalSupply", "inputs": [], "outputs": [{"type": 
"uint256"}]}'

arguments:
    ADDRESS          address to point call toward
    FUNCTION         function name, 4byte selector, or ABI
    ARGS             function arguments
    --verbose, -v    show summary
    --from FROM      address where call should come from
    --block BLOCK    block number for call


usage of subcommands:
    ctc call can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc call <subcommand> -h

available subcommands:
    all    display outputs of all contract's read-only functions

call all

usage:
    ctc call all CONTRACT_ADDRESS [options]

description:
    display outputs of all contract's read-only functions
    
    currently only displays output of zero-parameter functions

examples:
    ctc call all 0x6c3f90f043a72fa612cbac8115ee7e52bde6e490
    ctc call all 0x240315db938d44bb124ae619f5fd0269a02d1271 --max-results 5

arguments:
    CONTRACT_ADDRESS             address of contract to call functions of
    --max-results MAX_RESULTS    for functions that output lists, limit display length
    --block BLOCK                block number for call

calls

usage:
    ctc calls ADDRESS_AND_OR_FUNCTION [options]

description:
    output the result of multiple contract eth_call's
    
    This command can be used in two ways:
    
    1) Multi-contract Calls: same call across multiple contracts
        - This is indicated by the --addresses parameter
        - Example: call <function> --addresses <addr1> <addr2> <addr3>
    
    2) Multi-block Calls: same call across multiple blocks
        - This is indicated by either of the --blocks or --time parameters
        - Example: call <addr1> <function> --time 30d
    
    in each case, <function> can be a name, a 4byte selector, or an ABI
    
    ## Multi-contract Calls
    
    Example use case: Get a wallet's balances for many ERC20 tokens
    
    Can use --block to select a specific block for calls
    
    By default will use the first address's function abi for all calls
        (Retrieve separate ABI's for each contract using --unique-abis)
    
    ## Multi-block Calls
    
    Example use case: Get the total supply of an ERC20 over time
    
    Can specify multi-block calls by blocks or by timestamps
    
    Ranges are inclusive of start and end boundaries
    
    ### Specifying multi-block calls using --blocks
    
    Example block specifications:
        --blocks 16000 16010 16020 16030
        --blocks 16010:16030:10
        --blocks 16010:16030 -n 4
        --blocks 16030:-20:10
        --blocks latest:-20:10
        (each of these examples would specify the same set of 4 blocks,
         if the latest block were 16030)
    
    Can also specify a block range sampled over a regular time interval:
        --blocks 15000000:16000000:1d --> samples block range once per day
    
    For block ranges with no interval specified, all blocks are used
    
    ### Specifying multi-block calls using --times
    
    Example time specifications:
        --times 20220701:20220730 -n 30
        --times 20220701:20220730:1d
        --times 20220701:29d -n 30
        --times 29d:20220701 -n 30
        (each of these examples specifies the same set of 30 timestamps)
    
    Can also use the current time as an implicit default:
        --times 100d::1d
        --times 100d -n 101
        --times 100d: -n 101
        --times 100d:: -n 101
        (each of these examples specifies the same set of 100 timestamps)
    
    Can indicate timestamps using a variety of formats:
    
            timestamp formats  │         meaning  │             examples  
        ───────────────────────┼──────────────────┼───────────────────────
              number + letter  │      timelength  │                 100d  
            (one of {yMdhms})  │                  │                  24h  
        ───────────────────────┼──────────────────┼───────────────────────
                         YYYY  │   start of year  │                 2018  
                               │                  │                 2022  
        ───────────────────────┼──────────────────┼───────────────────────
                       YYYYMM  │  start of month  │               201802  
                      YYYY-MM  │                  │              2022-06  
        ───────────────────────┼──────────────────┼───────────────────────
                     YYYYMMDD  │    start of day  │             20180228  
                   YYYY-MM-DD  │                  │           2022-06-01  
        ───────────────────────┼──────────────────┼───────────────────────
              YYYYMMDD_HHMMSS  │   minute in day  │             20180228  
             YYYY-MM-DD_HH:MM  │                  │     2022-06-01_04:30  
        ───────────────────────┼──────────────────┼───────────────────────
              YYYYMMDD_HHMMSS  │   second in day  │             20180228  
          YYYY-MM-DD_HH:MM:SS  │                  │  2022-06-01_04:30:40  
        ───────────────────────┼──────────────────┼───────────────────────
                 large number  │  unix timestamp  │           1600000000  
                               │                  │           1700000000  
    
    See the tooltime package for more information about time specifications
    
    A default of -n 25 is used if no -n is specified for time range
    
    ## Outputs
    
    A table of outputs is displayed by default, omit with --no-table
    
    Numerical outputs of multi-block calls are charted, omit with --no-chart
    
    Use --export to output data to a json or csv file
    More data is included when exporting to a file
    

examples:
    # 1) multi-contract template: same call across multiple addresses
    ctc calls <function> [<function_parameters>] --addresses <addresses>

    # 2) multi-block template: same call across multiple blocks
    ctc calls <address> <function> [<function_parameters>] --blocks <blocks>

    # Balance of DAI, USDC, and USDT in Curve 3pool
    ctc calls balanceOf 0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7 --addresses 
0x6b175474e89094c44da98b954eedeac495271d0f 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 
0xdac17f958d2ee523a2206206994597c13d831ec7 --normalize

    # Weekly balance of DAI in Curve 3pool throughout year 2021
    ctc calls 0x6b175474e89094c44da98b954eedeac495271d0f balanceOf 0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7 --times 
2021:2022:1w --normalize

    # Balance of DAI in Curve 3pool over the past 1 million blocks
    ctc calls 0x6b175474e89094c44da98b954eedeac495271d0f balanceOf 0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7 --blocks 
latest:-1000000 -n 20 --normalize

arguments:
    ADDRESS_AND_OR_FUNCTION      <see above>
    -b, --blocks BLOCKS          block list or block range (see above)
    -t, --times TIMES            timestamp list or time range (see above)
    -n N                         number of calls to make in given range
    -a, --addresses ADDRESSES    addresses to point calls toward
    --block BLOCK                block number for calls
    --unique-abis UNIQUE_ABIS    retrieve separate ABI for each address
    --export EXPORT              file path for output (.json or .csv)
    --overwrite                  specify that output path can be overwritten
    --no-table                   do not output a table
    --no-chart                   do not output a chart
    --from FROM                  address that calls should come from
    --normalize NORMALIZE        normalize output by value, default is 1) erc20 decimals or 2) "1e18"
    --blocks-gte-times           find the blocks >= timestamps instead of <=

chain

usage:
    ctc chain PROVIDER [options]

description:
    display chain_id of provider

examples:
    ctc chain https://rpc.flashbots.net/
    ctc chain https://arbitrumrpc.com

arguments:
    PROVIDER         url or configured name of RPC node
    --verbose, -v    display additional information about provider chain
    --config         display only chain_id from config, not reported chain_id
    --no-check       do not check reported chain_id against configured chain_id

decompile

usage:
    ctc decompile ADDRESS_OR_BYTECODE [options]

description:
    decompile contract abi

example:
    ctc decompile 0x956f47f50a910163d8bf957cf5846d573e7f87ca

arguments:
    ADDRESS_OR_BYTECODE    contract address or hex bytecode
    -v, --verbose          do not clip long names

dex chart

usage:
    ctc dex chart POOL [options]

description:
    display candlestick chart of DEX pool trades

examples:
    ctc dex chart 0xf4ad61db72f114be877e87d62dc5e7bd52df4d9b
    ctc dex chart 0xf4ad61db72f114be877e87d62dc5e7bd52df4d9b --invert

arguments:
    POOL                     Uniswap pool address
    --timescale TIMESCALE    size of candlesticks, e.g. 1h, 1d, or 1w
    --invert                 use inverse of price
    --no-volume              hide volume data

dex pool

usage:
    ctc dex pool POOL [options]

description:
    show information about a pool

examples:
    ctc dex pool 0xc5be99a02c6857f9eac67bbce58df5572498f40c
    ctc dex pool 0xc5be99a02c6857f9eac67bbce58df5572498f40c --block 14000000

arguments:
    POOL                 address of pool
    --network NETWORK    network to query
    --block BLOCK        block number

dex pools

usage:
    ctc dex pools TOKENS [options]

description:
    list dex pools

examples:
    ctc dex pools CRV
    ctc dex pools DAI --dex balancer
    ctc dex pools DAI --created 14000000:15000000

arguments:
    TOKENS               token symbols or addresses (separate using spaces)
    --update             run update to index all recently created pools
    --created CREATED    specify start and/or end of when pool was created
    --dex DEX            name of dex (e.g. balancer, curve, uniswap-v2)
    --factory FACTORY    address of pool factory
    --all-pools          display all pools instead of just the first 1000
    --compact            use compact view for higher information density
    --verbose, -v        show additional data
    --json               output data as json
    --csv                output data as json
    --export EXPORT      file path to save output to
    --overwrite          specify that output path can be overwritten
    --sort SORT          column to sort pools by

dex trades

usage:
    ctc dex trades POOL [options]

description:
    get DEX swaps

example:
    ctc dex trades 0xc5be99a02c6857f9eac67bbce58df5572498f40c --blocks 14000000:14010000

arguments:
    POOL                           pool to retrieve swaps from
    -b, --blocks BLOCKS            block range to retrieve swaps from
    --no-normalize NO_NORMALIZE    do not normalize by ERC20 decimals
    --export EXPORT                file path to save output to
    --overwrite                    specify that output path can be overwritten
    -v, --verbose                  output extra data

erc20

usage:
    ctc erc20 ERC20

description:
    display information about ERC20

examples:
    ctc erc20 DAI
    ctc erc20 0x6b175474e89094c44da98b954eedeac495271d0f

arguments:
    ERC20    ERC20 address or symbol


usage of subcommands:
    ctc erc20 can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc erc20 <subcommand> -h

available subcommands:
    balance      output an ERC20 balance
    balances     output ERC20 balances of blocks / addresses / tokens
    transfers    output information about ERC20 transfers

erc20 balance

usage:
    ctc erc20 balance ERC20_ADDRESS WALLET_ADDRESS [options]

description:
    output an ERC20 balance

examples:
    ctc erc20 balance 0x956f47f50a910163d8bf957cf5846d573e7f87ca 0x9928e4046d7c6513326ccea028cd3e7a91c7590a
    ctc erc20 balance 0x956f47f50a910163d8bf957cf5846d573e7f87ca 0x9928e4046d7c6513326ccea028cd3e7a91c7590a --raw
    ctc erc20 balance 0x956f47f50a910163d8bf957cf5846d573e7f87ca 0x9928e4046d7c6513326ccea028cd3e7a91c7590a --block 
14000000

arguments:
    ERC20_ADDRESS     address of ERC20 token
    WALLET_ADDRESS    address of wallet
    --block BLOCK     block number
    --raw             whether to normalize balance by ERC20 decimals

erc20 balances

usage:
    ctc erc20 balances ARGS [options]

description:
    output ERC20 balances of blocks / addresses / tokens

examples:
    # version 1: balance of single wallet across multiple tokens
    ctc erc20 balances WALLET --erc20s ERC20S [--block BLOCK]

    # version 2: balances of multiple wallets in single block (default = all wallets)
    ctc erc20 balances ERC20 [--block BLOCK] [--wallets WALLETS]

    # version 3: balance of single wallet across multiple blocks
    ctc erc20 balances ERC20 WALLET --blocks BLOCKS

arguments:
    ARGS                 <see above>
    --block BLOCK        block number
    --wallets WALLETS    wallets to get balances of
    --blocks BLOCKS      block numbers to get balances at
    --erc20s ERC20S      ERC20 addresses to get balances of
    --raw                whether to skip normalizing by ERC20 decimals
    --export EXPORT      file path for output (.json or .csv)
    --overwrite          specify that output path can be overwritten
    -n N                 show n data points

erc20 transfers

usage:
    ctc erc20 transfers ERC20 [options]

description:
    output information about ERC20 transfers

examples:
    ctc erc20 transfers 0x956f47f50a910163d8bf957cf5846d573e7f87ca

    ctc erc20 transfers 0x956f47f50a910163d8bf957cf5846d573e7f87ca --blocks 14000000:14001000

    ctc erc20 transfers 0x956f47f50a910163d8bf957cf5846d573e7f87ca --blocks 14000000:14001000 --include-timestamps

arguments:
    ERC20                   ERC20 address
    --blocks BLOCKS         block range of transfers
    --include-timestamps    include timestamps
    --export EXPORT         file path for output (.json or .csv)
    --overwrite             specify that output path can be overwritten

eth balance

usage:
    ctc eth balance ADDRESS [options]

description:
    output ETH balance of address

examples:
    ctc eth balance 0xd8da6bf26964af9d7eed9e03e53415d37aa96045
    ctc eth balance 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --raw
    ctc eth balance 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --block 14000000

arguments:
    ADDRESS          address of wallet
    --block BLOCK    block number
    --raw            skip normalizing balance by 1e18 decimals

eth balances

usage:
    ctc eth balances WALLETS [options]

description:
    output ETH balance across blocks or addresses

examples:
    # multiple wallets
    ctc eth balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 0xea674fdde714fd979de3edf0f56aa9716b898ec8 
0xbe0eb53f46cd790cd13851d5eff43d12404d33e8

    # multiple blocks
    ctc eth balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --blocks 14000000:14000100

    # multiple blocks with USD values
    ctc eth balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -v --blocks 14000000:14100000:1000

arguments:
    WALLETS            wallet addresses to get balances of
    --block BLOCK      block number
    --blocks BLOCKS    block numbers to get balances in
    --raw              skip normalizing by 1e18 decimals
    --export EXPORT    file path for output (.json or .csv)
    --overwrite        specify that output path can be overwritten
    -v, --verbose      display additional information

events

usage:
    ctc events CONTRACT EVENT [options]

description:
    get contract events

examples:
    ctc events 0x956f47f50a910163d8bf957cf5846d573e7f87ca Transfer

    ctc events 0x956f47f50a910163d8bf957cf5846d573e7f87ca Transfer --blocks 14000000:14010000

    ctc events 0x956f47f50a910163d8bf957cf5846d573e7f87ca Transfer --blocks 14000000:14010000 --include-timestamps

arguments:
    CONTRACT                contract address of event
    EVENT                   event name or event hash
    --blocks BLOCKS         block range
    --include-timestamps    include timestamps
    --export EXPORT         file path for output (.json or .csv)
    --overwrite             specify that output path can be overwritten
    --verbose, -v           display more event data

gas

usage:
    ctc gas  [options]

description:
    output gas summary of block range

examples:
    ctc gas 
    ctc gas --last 300

arguments:
    --block BLOCK      historical block to use
    --last N           number of blocks to include
    --export EXPORT    file path for output (.json or .csv)
    --overwrite        specify that output path can be overwritten
    -v, --verbose      output additional information

proxy

usage:
    ctc proxy CONTRACT_ADDRESS [options]

description:
    print proxy information about contract

example:
    ctc proxy 0xee6a57ec80ea46401049e92587e52f5ec1c24785

arguments:
    CONTRACT_ADDRESS    address to get proxy of
    --verbose, -v       print additional information
    --block BLOCK       block to query


usage of subcommands:
    ctc proxy can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc proxy <subcommand> -h

available subcommands:
    register    register custom proxy implementation of a contract

proxy register

usage:
    ctc proxy register PROXY_CONTRACT IMPLEMENTATION_CONTRACT [options]

description:
    register custom proxy implementation of a contract
    
    Implementation ABI will be downloaded for original contract
    
    Manual registration using this command is normally unnecessary
    
    This command is useful for custom proxy implementations

example:
    ctc proxy register 0xfb558ecd2d24886e8d2956775c619deb22f154ef 0xe16db319d9da7ce40b666dd2e365a4b8b3c18217 --confirm

arguments:
    PROXY_CONTRACT             contract that falls back to other contract
    IMPLEMENTATION_CONTRACT    contract that implements proxy contract
    --confirm                  confirm registration of proxy

storage

usage:
    ctc storage CONTRACT_ADDRESS SLOT [options]

description:
    get value of storage slot

examples:
    ctc storage 0x245cc372c84b3645bf0ffe6538620b04a217988b 0x0
    ctc storage 0x245cc372c84b3645bf0ffe6538620b04a217988b 0x0 --type address
    ctc storage 0x245cc372c84b3645bf0ffe6538620b04a217988b 0x0 --block 14000000

arguments:
    CONTRACT_ADDRESS    address of contract
    SLOT                address of storage slot
    --block BLOCK       block number
    --type TYPE         decode data using this datatype

symbol

usage:
    ctc symbol QUERY

description:
    convert ERC20 address to symbol, or symbol to address

example:
    ctc symbol DAI

arguments:
    QUERY    ERC20 address or symbol

timestamp

usage:
    ctc timestamp [TIMESTAMP]

description:
    get block of timestamp

example:
    ctc timestamp 1642114795

arguments:
    TIMESTAMP    timestamp (default = now)

tx

usage:
    ctc tx TRANSACTION [options]

description:
    display transaction data, receipt, call data, & logs

example:
    ctc tx 0xe981fe5c78d11d935a1dc35c579969e65e2dd6bb05ad321ea9670f8b1e203eaf

arguments:
    TRANSACTION    hash of transaction
    --sort SORT    attribute to sort logs by
    --json         output raw JSON of tx

Protocol Subcommands

Note

Click on a subcommand to view its documentation page.

usage:
    ctc <subcommand> [options]

description:
    ctc is a tool for historical data analysis of Ethereum and other EVM chains
    
    if using ctc for the first time, run:
        ctc setup
    
    for quick lookups of an address, block, tx, or timestamp, run:
        ctc QUERY
    
        where QUERY is an address, block number, tx hash, or timestamp

    to view help about a specific subcommand run:
        ctc <subcommand> -h

protocol subcommands:
    4byte               lookup 4byte signature
    4byte build         build local copy of 4byte database
    aave                output aave usage statistics
    aave addresses      output aave-related addresses
    cg                  output coingecko market data
    chainlink           output Chainlink feed data
    chainlink feeds     list all Chainlink feeds
    curve pools         list curve pools
    ens                 summarize ENS entry
    ens exists          output whether ENS name exists
    ens hash            output hash of ENS name
    ens owner           output owner of ENS name
    ens records         output text records of ENS name
    ens resolve         resolve ENS name
    ens reverse         reverse ENS lookup address
    etherscan           open etherscan query in browser or fetch
    fei analytics       output data payload for app.fei.money/analytics
    fei depth           output FEI liquidity depth information
    fei dex             show information related to FEI on DEX's
    fei pcv             output summary of Fei PCV
    fei pcv assets      output summary of Fei PCV assets
    fei pcv deposits    output summary of Fei PCV deposits
    fei psms            display recent FEI redemptions
    gnosis              print information about a gnosis safe
    llama               output data from Defi Llama api
    llama chain         output data about a chain tracked by Defi Llama
    llama chains        output data about chains tracked by Defi Llama
    llama pool          output data about a pool tracked by Defi Llama
    llama pools         output data about pools tracked by Defi Llama
    llama protocol      output data about a protocol tracked by Defi Llama
    llama protocols     output data about protocols tracked by Defi Llama
    rari                summarize fuse pool, token, or platform
    rari pools          list all Rari fuse pools
    uniswap burns       output information about pool burns
    uniswap chart       chart price action of uniswap pools
    uniswap mints       output information about pool mints
    uniswap pool        summarize pool
    uniswap swaps       output information about pool swaps
    yearn               display summary of Yearn vaults
    yearn addresses     output Yearn addresses

4byte

usage:
    ctc 4byte SIGNATURE [options]

description:
    lookup 4byte signature

examples:
    ctc 4byte 0x18160ddd
    ctc 4byte 0xa9059cbb
    ctc 4byte "totalSupply()"
    ctc 4byte "transfer(address,uint256)"

arguments:
    SIGNATURE    signature to look up
    --local      use local database
    --remote     use remote database


usage of subcommands:
    ctc 4byte can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc 4byte <subcommand> -h

available subcommands:
    build    build local copy of 4byte database

4byte build

usage:
    ctc 4byte build [DATATYPE]

description:
    build local copy of 4byte database
    
    scrapes from 4byte.directory

examples:
    # build function signature db
    ctc 4byte build functions

    # build event signature db
    ctc 4byte build events

arguments:
    DATATYPE    "functions" or "events", omit to build database of both

aave

usage:
    ctc aave [TOKEN] [options]

description:
    output aave usage statistics

examples:
    ctc aave 
    ctc aave --verbose
    ctc aave --block 14000000
    ctc aave DAI
    ctc aave DAI --time 1y -n 10
    ctc aave DAI --time 1y --verbose -n 10

arguments:
    TOKEN            show information related to this token
    --verbose, -v    show additional addresses
    --block BLOCK    block to get addresses of
    --time TIME      timescale to use for token-specific charts
    -n N             number of blocks to sample


usage of subcommands:
    ctc aave can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc aave <subcommand> -h

available subcommands:
    addresses    output aave-related addresses

aave addresses

usage:
    ctc aave addresses  [options]

description:
    output aave-related addresses

examples:
    ctc aave addresses 
    ctc aave addresses --verbose
    ctc aave addresses --block 15000000

arguments:
    --verbose, -v    show additional addresses
    --block BLOCK    block to get addresses of

cg

usage:
    ctc cg TOKENS [options]

description:
    output coingecko market data

examples:
    ctc cg 
    ctc cg CRV -t 100d
    ctc cg ETH / BTC
    ctc cg LINK / ETH -t 24h
    ctc cg --update

arguments:
    TOKENS             token to display information of
    -t, --time TIME    time of chart (e.g. 7d, 1y, max)
    -n N               number of entries to include in output
    --verbose, -v      include extra data
    --height HEIGHT    height, number of rows per asset
    --width WIDTH      width of sparklines
    --update           update stored coingecko token db

chainlink

usage:
    ctc chainlink FEED [options]

description:
    output Chainlink feed data

examples:
    ctc chainlink DAI_USD
    ctc chainlink 0xaed0c38402a5d19df6e4c03f4e2dced6e29c1ee9
    ctc chainlink DAI_USD --blocks 14000000:14001000

arguments:
    FEED                   name or address of feed
    --verbose, -v          show additional information
    --blocks BLOCKS        block range of datapoints
    --time TIME            historical duration to show feed data
    --export EXPORT        file path for output (.json or .csv)
    --overwrite            specify that output path can be overwritten
    --provider PROVIDER    rpc provider name or url
    --network NETWORK      network name or chain_id
    --all-fields           include all output fields
    --interpolate          interpolate all blocks in range
    --shell                open shell with Chainlink data


usage of subcommands:
    ctc chainlink can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc chainlink <subcommand> -h

available subcommands:
    feeds    list all Chainlink feeds

chainlink feeds

usage:
    ctc chainlink feeds [QUERY] [options]

description:
    list all Chainlink feeds

examples:
    ctc chainlink feeds 
    ctc chainlink feeds DAI

arguments:
    QUERY                partial match of feed name, case insensitive
    --network NETWORK    network to list feeds of

curve pools

usage:
    ctc curve pools  [options]

description:
    list curve pools

examples:
    ctc curve pools 
    ctc curve pools --verbose

arguments:
    --verbose, -v    include extra data

ens

usage:
    ctc ens NAME_OR_ADDRESS [options]

description:
    summarize ENS entry

examples:
    ctc ens 0xd8da6bf26964af9d7eed9e03e53415d37aa96045
    ctc ens vitalik.eth
    ctc ens vitalik.eth --verbose

arguments:
    NAME_OR_ADDRESS    ENS name(s) or address(es)
    --block BLOCK      block number
    --verbose, -v      display additional information


usage of subcommands:
    ctc ens can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc ens <subcommand> -h

available subcommands:
    exists     output whether ENS name exists
    hash       output hash of ENS name
    owner      output owner of ENS name
    records    output text records of ENS name
    resolve    resolve ENS name
    reverse    reverse ENS lookup address

ens exists

usage:
    ctc ens exists NAME [options]

description:
    output whether ENS name exists

examples:
    ctc ens exists vitalik.eth
    ctc ens exists vitalik.eth --block 14000000
    ctc ens exists fake-vitalik.eth

arguments:
    NAME             ENS name
    --block BLOCK    block number

ens hash

usage:
    ctc ens hash NAME

description:
    output hash of ENS name

example:
    ctc ens hash vitalik.eth

arguments:
    NAME    ENS name

ens owner

usage:
    ctc ens owner NAME [options]

description:
    output owner of ENS name

examples:
    ctc ens owner vitalik.eth
    ctc ens owner vitalik.eth --block 14000000

arguments:
    NAME             ENS name
    --block BLOCK    block number

ens records

usage:
    ctc ens records NAME

description:
    output text records of ENS name

example:
    ctc ens records vitalik.eth

arguments:
    NAME    ENS name

ens resolve

usage:
    ctc ens resolve NAME [options]

description:
    resolve ENS name

examples:
    ctc ens resolve vitalik.eth
    ctc ens resolve vitalik.eth --block 14000000

arguments:
    NAME             ENS name
    --block BLOCK    block number

ens reverse

usage:
    ctc ens reverse ADDRESS [options]

description:
    reverse ENS lookup address

examples:
    ctc ens reverse 0xd8da6bf26964af9d7eed9e03e53415d37aa96045
    ctc ens reverse 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --block 14000000

arguments:
    ADDRESS          address of reverse lookup
    --block BLOCK    block number

etherscan

usage:
    ctc etherscan QUERY [options]

description:
    open etherscan query in browser or fetch

examples:
    ctc etherscan 0xd3181ddbb2cea7b4954b8d4a05dbf85d8fc36aef

    ctc etherscan 0x146063226f2bc60ab02fff825393555672ff505afb352ff11b820355422ba31e

    ctc etherscan 14000000

    ctc etherscan vitalik.eth

    ctc etherscan vitalik.eth --holdings

    ctc etherscan vitalik.eth --erc20-transfers

    ctc etherscan DAI

    ctc etherscan DAI --holders

arguments:
    QUERY                address / tx / block / ERC20 symbol / ens
    --holdings           open page viewing holdings of address
    --erc20-transfers    open page viewing ERC20 transfers of address
    --internal           open page viewing internal txs of address
    --holders            open page viewing holders of ERC20 address
    --logs               open page viewing logs of transaction
    --changes            open page viewing state changes of transaction
    --abi                output only the json ABI of an address

fei analytics

usage:
    ctc fei analytics [TIMESCALE] [options]

description:
    output data payload for app.fei.money/analytics

example:
    # create default payload for app.fei.money
    ctc fei analytics 30d,1d

arguments:
    TIMESCALE      time window size and resolution
    --path PATH    path for data output (a .json file)
    --overwrite    allow overwriting an already-existing file

fei depth

usage:
    ctc fei depth  [options]

description:
    output FEI liquidity depth information

examples:
    ctc fei depth 
    ctc fei depth --prices "0.996" "0.997"

arguments:
    --prices PRICES    specify which price levels to output depths of
    --json             output data as json

fei dex

usage:
    ctc fei dex  [options]

description:
    show information related to FEI on DEX's

examples:
    ctc fei dex 
    ctc fei dex --block 14000000

arguments:
    --block BLOCK    block number to query

fei pcv

usage:
    ctc fei pcv  [options]

description:
    output summary of Fei PCV

examples:
    ctc fei pcv 
    ctc fei pcv --block 14000000

arguments:
    --block BLOCK    block number


usage of subcommands:
    ctc fei pcv can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc fei pcv <subcommand> -h

available subcommands:
    assets      output summary of Fei PCV assets
    deposits    output summary of Fei PCV deposits

fei pcv assets

usage:
    ctc fei pcv assets  [options]

description:
    output summary of Fei PCV assets

examples:
    ctc fei pcv assets 
    ctc fei pcv assets --block 14000000

arguments:
    --block BLOCK    block number

fei pcv deposits

usage:
    ctc fei pcv deposits  [options]

description:
    output summary of Fei PCV deposits

examples:
    ctc fei pcv deposits 
    ctc fei pcv deposits --block 14000000

arguments:
    --block BLOCK    block number

fei psms

usage:
    ctc fei psms  [options]

description:
    display recent FEI redemptions

examples:
    ctc fei psms 
    ctc fei psms --verbose

arguments:
    --time TIME      span of time to display
    --token TOKEN    filter by redemptions of a particular token
    --block BLOCK    block
    --limit LIMIT    limit number of mints/redeems shown
    --verbose, -v    display additional information

gnosis

usage:
    ctc gnosis ADDRESS [options]

description:
    print information about a gnosis safe

examples:
    ctc gnosis 0x245cc372c84b3645bf0ffe6538620b04a217988b
    ctc gnosis 0x245cc372c84b3645bf0ffe6538620b04a217988b --verbose

arguments:
    ADDRESS          address of gnosis safe
    --verbose, -v    display additional information

llama

usage:
    ctc llama 

description:
    output data from Defi Llama api

example:
    ctc llama 


usage of subcommands:
    ctc llama can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc llama <subcommand> -h

available subcommands:
    chain        output data about a chain tracked by Defi Llama
    chains       output data about chains tracked by Defi Llama
    protocol     output data about a protocol tracked by Defi Llama
    protocols    output data about protocols tracked by Defi Llama
    pool         output data about a pool tracked by Defi Llama
    pools        output data about pools tracked by Defi Llama

llama chain

usage:
    ctc llama chain CHAIN

description:
    output data about a chain tracked by Defi Llama

example:
    ctc llama chain Tezos

arguments:
    CHAIN    chain to describe

llama chains

usage:
    ctc llama chains  [options]

description:
    output data about chains tracked by Defi Llama

examples:
    ctc llama chains 
    ctc llama chains -n 50

arguments:
    -n N    number of chains to display

llama pool

usage:
    ctc llama pool POOL

description:
    output data about a pool tracked by Defi Llama

example:
    ctc llama pool 747c1d2a-c668-4682-b9f9-296708a3dd90

arguments:
    POOL    id of pool (obtain using --show-id on llama pools cmd)

llama pools

usage:
    ctc llama pools  [options]

description:
    output data about pools tracked by Defi Llama

examples:
    ctc llama pools 
    ctc llama pools --min-tvl 1000000
    ctc llama pools --stablecoin
    ctc llama pools --chain Ethereum
    ctc llama pools --min-tvl 1000000 --min-apy 10 --chain Ethereum

arguments:
    --chain CHAIN        filter pools by chain
    --project PROJECT    filter pools by project
    --stablecoin         filter pools by whether they are stablecoin-based
    --non-stablecoin     filter pools by whether they are not stablecoin-based
    --single             filter pools by whether they use a single asset
    --multi              filter pools by whether they use a multiple assets
    --min-apy MIN_APY    filter pools by minimum yield rate
    --max-apy MAX_APY    filter pools by maximum yield rate
    --min-tvl MIN_TVL    filter pools by miniumum TVL
    --max-tvl MAX_TVL    filter pools by maximum TVL
    -n N                 number of pools to display
    -v, --verbose        display additional information
    --show-id            show id of each pool in table

llama protocol

usage:
    ctc llama protocol PROTOCOL [options]

description:
    output data about a protocol tracked by Defi Llama

examples:
    ctc llama protocol Balancer
    ctc llama protocol Balancer --verbose

arguments:
    PROTOCOL         protocol to display information about
    -v, --verbose    display additional infromation

llama protocols

usage:
    ctc llama protocols  [options]

description:
    output data about protocols tracked by Defi Llama

examples:
    ctc llama protocols 
    ctc llama protocols --category Dexes
    ctc llama protocols --chain Tron

arguments:
    -v, --verbose          show additional information
    --category CATEGORY    filter protocols by category
    --chain CHAIN          filter protocols by chain
    -n N                   number of protocols to display

rari

usage:
    ctc rari [ARG] [options]

description:
    summarize fuse pool, token, or platform

examples:
    # summarize a pool
    ctc rari 8

    # summarize a token across all pools
    ctc rari 0x956f47f50a910163d8bf957cf5846d573e7f87ca

    # summarize all of Rari
    ctc rari 

arguments:
    ARG              pool index or token, omit to summarize platform
    --block BLOCK    block number


usage of subcommands:
    ctc rari can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc rari <subcommand> -h

available subcommands:
    pools    list all Rari fuse pools

rari pools

usage:
    ctc rari pools  [options]

description:
    list all Rari fuse pools

examples:
    ctc rari pools 
    ctc rari pools --verbose

arguments:
    --verbose    emit extra output

uniswap burns

usage:
    ctc uniswap burns POOL [options]

description:
    output information about pool burns

example:
    ctc uniswap burns 0xae461ca67b15dc8dc81ce7615e0320da1a9ab8d5 --blocks 14000000:14001000

arguments:
    POOL               pool address
    --blocks BLOCKS    block number range
    --export EXPORT    file path for export (.json or .csv)
    --overwrite        specify that output path can be overwritten

uniswap chart

usage:
    ctc uniswap chart POOL [options]

description:
    chart price action of uniswap pools

example:
    ctc uniswap chart 0x9928e4046d7c6513326ccea028cd3e7a91c7590a

arguments:
    POOL                     Uniswap pool address
    --timescale TIMESCALE    size of candlesticks, e.g. 1h, 1d, or 1w
    --invert                 use inverse of price
    --no-volume              hide volume data

uniswap mints

usage:
    ctc uniswap mints POOL [options]

description:
    output information about pool mints

example:
    ctc uniswap mints 0xae461ca67b15dc8dc81ce7615e0320da1a9ab8d5 --blocks 14000000:14001000

arguments:
    POOL               pool address
    --blocks BLOCKS    block number range
    --export EXPORT    file path for output (.json or .csv)
    --overwrite        specify that output path can be overwritten

uniswap pool

usage:
    ctc uniswap pool POOL [options]

description:
    summarize pool

example:
    ctc uniswap pool 0xae461ca67b15dc8dc81ce7615e0320da1a9ab8d5 --block 14000000

arguments:
    POOL               pool address
    --block BLOCK      block number range
    --depths DEPTHS    liquidity depths

uniswap swaps

usage:
    ctc uniswap swaps POOL [options]

description:
    output information about pool swaps

example:
    ctc uniswap swaps 0xae461ca67b15dc8dc81ce7615e0320da1a9ab8d5 --blocks 14000000:14001000

arguments:
    POOL               pool address
    --blocks BLOCKS    block number range
    --export EXPORT    file path for output (.json or .csv)
    --overwrite        specify that output path can be overwritten

yearn

usage:
    ctc yearn [QUERY] [options]

description:
    display summary of Yearn vaults

examples:
    ctc yearn 
    ctc yearn --min-tvl 1000000
    ctc yearn --sort TVL
    ctc yearn 0x9d409a0a012cfba9b15f6d4b36ac57a46966ab9a
    ctc yearn 0x9d409a0a012cfba9b15f6d4b36ac57a46966ab9a -v
    ctc yearn 0x9d409a0a012cfba9b15f6d4b36ac57a46966ab9a --harvests

arguments:
    QUERY                address or name of vault to show details of
    --sort SORT          vault field to sort by
    -n N                 number of vaults to display
    --min-apy MIN_APY    filter vaults by minimum APY
    --min-apr MIN_APR    filter vaults by minimum APR
    --min-tvl MIN_TVL    filter vaults by minimum TVL
    -v, --verbose        output additional information
    --harvests           show harvests when viewing individual vault


usage of subcommands:
    ctc yearn can also be used to invoke subcommands

    to view help about a specific subcommand, run:
        ctc yearn <subcommand> -h

available subcommands:
    addresses    output Yearn addresses

yearn addresses

usage:
    ctc yearn addresses  [options]

description:
    output Yearn addresses

examples:
    ctc yearn addresses 
    ctc yearn addresses -v

arguments:
    -v, --verbose    output additional addresses

Other Subcommands

Note

Click on a subcommand to view its documentation page.

usage:
    ctc <subcommand> [options]

description:
    ctc is a tool for historical data analysis of Ethereum and other EVM chains
    
    if using ctc for the first time, run:
        ctc setup
    
    for quick lookups of an address, block, tx, or timestamp, run:
        ctc QUERY
    
        where QUERY is an address, block number, tx hash, or timestamp

    to view help about a specific subcommand run:
        ctc <subcommand> -h

other subcommands:
    cd                  change working directory to ctc-related location
    help                output help
    version             print cli version

cd

usage:
    ctc cd DIRNAME

description:
    change working directory to ctc-related location

    directories:
    - code: directory where ctc code is stored
    - data: directory where ctc stores data
    - config: directory where ctc stores config

arguments:
    DIRNAME    name of directory

help

usage:
    ctc help SUBCOMMAND [options]

description:
    output help

arguments:
    SUBCOMMAND       
    -h, --help       
    --hidden         
    --reset-cache    reset help message cache

version

usage:
    ctc version  [options]

description:
    print cli version

arguments:
    -V, --version    

Useful Aliases

ctc makes it simple to perform many tasks from the command line. However, ctc can be made even more simple by using shell aliases that reduce the number of required keystrokes that must be typed. The ctc codebase includes an optional set of cli aliases for this purpose.

Such aliases make it so you do not need to type the “ctc” before a subcommand name. For example, instead of typing ctc keccak <address>, you just type keccak <address>. Instead of typing ctc 4byte <query>, you just type 4byte <query>. And so on, for many different ctc subcommands.

The ctc setup wizard can add these aliases to your shell configuation.

The Aliases

These aliases are chosen so as not to conflict with any common CLI tools.

# compute commands
alias ascii="ctc ascii"
alias hex="ctc hex"
alias keccak="ctc keccak"
alias lower="ctc lower"

# data commands
alias abi="ctc abi"
alias address="ctc address"
alias block="ctc block"
alias blocks="ctc blocks"
alias bytecode="ctc bytecode"
alias call="ctc call"
alias calls="ctc calls"
alias dex="ctc dex"
alias erc20="ctc erc20"
alias eth="ctc eth"
alias gas="ctc gas"
alias int="ctc int"
alias rlp="ctc rlp"
alias tx="ctc tx"

# protocol commands
alias 4byte="ctc 4byte"
alias aave="ctc aave"
alias cg="ctc cg"
alias chainlink="ctc chainlink"
alias curve="ctc curve"
alias es="ctc etherscan"
alias ens="ctc ens"
alias fei="ctc fei"
alias gnosis="ctc gnosis"
alias llama="ctc llama"
alias rari="ctc rari"
alias uniswap="ctc uniswap"
alias yearn="ctc yearn"

Similar CLI tools

ethereum-etl

ethereum-etl is a tool for collecting raw historical data from EVM chains, including blocks, transactions, erc20 transfers, and internal traces. Along with the rest of the blockchain-etl stack, it powers the popular BigQuery blockchain datasets. The primary use case of ethereum-etl and its associated stack is to index a significant portion of a chain’s history in preparation for large scale data analysis.

Prior to creating ctc, ethereum-etl was the primary data collection tool used by ctc’s authors. It was extensive use of ethereum-etl that inspired much of ctc’s design. Compared to ethereum-etl, ctc falls closer to the porcelain end of the plumbing-vs-porcelain spectrum, with goals such as:

• create more diverse datasets, such as datasets that rely on eth_call

• create more targeted datasets, such as datasets focused on specific protocols like Chainlink or Uniswap

• create tighter integration with the python ecosystem

• go beyond data collection by creating a data analysis toolkit that serves each stage of the data analysis lifecycle

• implement quality-of-life improvements for the lazy

  • store and manage metadata such as addresses of tokens, oracles, and pools

  • automate tasks such as data encoding/decoding

TrueBlocks

TrueBlocks is a tool for managing optimized local indices of EVM chain data. TrueBlocks then makes these local data copies accessible through an enhanced RPC interface. TrueBlocks delivers some of the highest performance ways to query chain data and it excels at tracing and querying all appearances of a given address throughout a chain’s history. Since TrueBlocks can provide its data over RPC, it could be used as an ultra high performance RPC provider for ctc.

There’s a decent amount of overlap between ethereum-etl, TrueBlocks, and ctc. Relatively speaking, ethereum-etl is plumbing, TrueBlocks is mostly plumbing with some porcelain, and ctc is mostly porcelain with some plumbing.

ethereal, seth, and cast

ethereal (go), seth (dapptools, bash+javascript), and cast (foundry, rust) are powerful command line utilities that each perform a wide range of EVM-related tasks.

ctc has lots of overlapping functionality with each. Where they differ is their focus. These other tools are more aimed at smart contract development, whereas ctc is more aimed at data collection and analysis. Compared to these tools, ctc’s biggest disadvantage is that it is limited to read-only operations. On the other hand ctc’s biggest advantage is its treatment of historical data as a first class feature.

Basic Usage

The top-level ctc module contains functions for generic EVM operations:

Example: Generic EVM Operations

import ctc

some_hash = ctc.keccak_text('hello')

encoded_data = ctc.abi_encode_packed((400, 6000), '(int128,int128)')

eth_balance = await ctc.async_get_eth_balance('0x6b175474e89094c44da98b954eedeac495271d0f')

erc20_balance = await ctc.async_get_erc20_balance(
    token='0x6b175474e89094c44da98b954eedeac495271d0f',
    wallet='0x6b175474e89094c44da98b954eedeac495271d0f'],
    block=15000000,
)

events = await ctc.async_get_events(
    '0xcbcdf9626bc03e24f779434178a73a0b4bad62ed',
    event_name='Swap',
)

Some points to keep in mind while using ctc:

• ctc uses functional programming. Instead of custom types or OOP, ctc uses simple standard datatypes including python builtins and numpy arrays. There is no need to initialize any objects. Simply import ctc and then call functions in the ctc.* namespace.

• ctc is asynchronous-first, which allows it to efficiently orchestrate large numbers of interdependent queries. Special consideration is needed to run code in an asynchronous context.

• ctc is designed with historical data analysis in mind. For any query of EVM state, ctc aims to support historical versions of that query. Most ctc query functions take parameters that can specify a block or block range relevant to the query.

The top-level ctc package covers generic EVM operations, which are described in more detail here. There are also a few other ctc subpackages that are relevant to specific use-cases described below.

RPC Client Subpackage ctc.rpc

ctc.rpc implements ctc’s custom RPC client. This client can be used for fine-grained control over RPC calls. Unless explcitly told not to do so.ctc will automatically encode requests to binary and decode requests from binary.

Example: get bytecode for contract, at specific block, using specific provider

import ctc.rpc

contract_bytecode = await ctc.rpc.async_eth_get_code(
    '0x6b175474e89094c44da98b954eedeac495271d0f',
    block_number=15000000,
    provider='https://some_rpc_node/',
)

Protocol-specific Subpackages ctc.protocols

ctc.protocols contains functions specific to many different protocols such as Chainlink or Uniswap. See a full list here.

Example: gather complete historical data for Chainlink’s RAI-USD feed

from ctc.protocols import chainlink_utils

feed_data = await chainlink_utils.async_get_feed_data('RAI_USD')

Other Subpackages

End users of ctc probably won’t need to use any of these directly.

• ctc.cli: command line interface

• ctc.config: configuration utilities

• ctc.db: local cache database

• ctc.spec: ctc specifications, mainly types for type annotations

• ctc.toolbox: miscellaneous python utilities

RPC Client

ctc.rpc is a low-level asynchronous RPC client that implements the EVM JSON-RPC standard. This standard consists of many methods such as eth_call and eth_getCode that query current and historical states of an EVM chain.

Implementation of Methods

For every method specified by the EVM JSON-RPC standard, ctc.rpc implements five python functions:

1. constructor function: create method requests

2. digestor function: process method responses

3. executor function: perform construction, dispatching, and digestion all in one step

4. batch construct: create method requests in bulk

5. batch execute: execute method requests in bulk

(there are no batch digestor functions because they compose naturally from the scalar digestor functions)

RPC Providers

Unless otherwise specified, requests will be sent to the default RPC provider in ctc’s config. Functions in ctc.rpc that send RPC requests also take an optional provider argument that can be used to specify other RPC providers.

For more details, see the RPC Provider section on the Data Sources page.

Typical RPC Request Lifecycle in ctc

1. a constructor function encodes request metadata and parameters into a RpcRequest python dict

2. the request is dispatched to an rpc provider using rpc.async_send_http()

3. the client awaits until the rpc provider returns a response

4. a digestor function decodes the response

For requests that execute contract code (like eth_call) or retrieve events (like eth_getLogs), ctc will encode/decode inputs/outputs using the relevant function abi’s and event abi’s.

Asynchronous Code

ctc uses async functions for network calls and database calls. This allows for high levels of concurrency and makes it easy to dispatch large numbers of complex interdependent queries.

async is an intermediate-level python topic with a bit of a learning curve. If you’ve never used async before, you should probably read a tutorial or two before trying to use it in ctc. To use async functions, they must be run from an event loop. These functions can be called from synchronous code as follows:

import asyncio

result = asyncio.run(some_async_function(input1, input2))

Inside of IPython or Jupyter notebooks, await can be used directly, without asyncio.run(). Many of the code examples in these docs assume this is the context and omit asyncio.run().

# no asyncio.run() necessary inside of IPython / Jupyter
result = await some_async_function(input1, input2)

If your code opens up network connections, you should also close those connections at the end of your script. For example:

from ctc import rpc

await rpc.async_close_http_session()

Datatypes

ctc has functions for collecting and analyzing many different EVM datatypes

Datatype	Examples	Reference
ABIs	Examples	Reference
Addresses	Examples	Reference
Binary	Examples	Reference
Blocks	Examples	Reference
ERC20s	Examples	Reference
ETH	Examples	Reference
Events	Examples	Reference
Transactions	Examples	Reference

ABIs

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

import ctc

Get contract ABI¶

In [2]:

# example contract: LUSD
contract_address = '0x5f98805a4e8be255a32880fdec7f6728c6568ba0'

In [3]:

contract_abi = await ctc.async_get_contract_abi(contract_address)

ctc.summarize_contract_abi(contract_abi)

---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
Input In [3], in <cell line: 3>()
      1 contract_abi = await ctc.async_get_contract_abi(contract_address)
----> 3 ctc.summarize_contract_abi(contract_abi)

AttributeError: module 'ctc' has no attribute 'summarize_contract_abi'

Get function ABI by name¶

In [4]:

function_abi = await ctc.async_get_function_abi(
    contract_address=contract_address,
    function_name='balanceOf',
)

function_abi

Out[4]:

{'inputs': [{'internalType': 'address', 'name': 'account', 'type': 'address'}],
 'name': 'balanceOf',
 'outputs': [{'internalType': 'uint256', 'name': '', 'type': 'uint256'}],
 'stateMutability': 'view',
 'type': 'function'}

Get function ABI by selector¶

In [5]:

function_abi = await ctc.async_get_function_abi(
    contract_address=contract_address,
    function_selector='0x70a08231',
)

function_abi

Out[5]:

{'inputs': [{'internalType': 'address', 'name': 'account', 'type': 'address'}],
 'name': 'balanceOf',
 'outputs': [{'internalType': 'uint256', 'name': '', 'type': 'uint256'}],
 'stateMutability': 'view',
 'type': 'function'}

Get event ABI by name¶

In [6]:

event_abi = await ctc.async_get_event_abi(
    contract_address=contract_address,
    event_name='Transfer',
)

event_abi

Out[6]:

{'anonymous': False,
 'inputs': [{'indexed': True,
   'internalType': 'address',
   'name': 'from',
   'type': 'address'},
  {'indexed': True,
   'internalType': 'address',
   'name': 'to',
   'type': 'address'},
  {'indexed': False,
   'internalType': 'uint256',
   'name': 'value',
   'type': 'uint256'}],
 'name': 'Transfer',
 'type': 'event'}

Get event ABI by hash¶

In [7]:

event_hash = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'

event_abi = await ctc.async_get_event_abi(
    contract_address=contract_address,
    event_hash=event_hash,
)

event_abi

Out[7]:

{'anonymous': False,
 'inputs': [{'indexed': True,
   'internalType': 'address',
   'name': 'from',
   'type': 'address'},
  {'indexed': True,
   'internalType': 'address',
   'name': 'to',
   'type': 'address'},
  {'indexed': False,
   'internalType': 'uint256',
   'name': 'value',
   'type': 'uint256'}],
 'name': 'Transfer',
 'type': 'event'}

Parse a function ABI¶

In [8]:

function_signature = ctc.get_function_signature(function_abi)
function_selector = ctc.get_function_selector(function_abi)
parameter_names = ctc.get_function_parameter_names(function_abi)
parameter_types = ctc.get_function_parameter_types(function_abi)
output_names = ctc.get_function_output_names(function_abi)
output_types = ctc.get_function_output_types(function_abi)

print('function_signature:', function_signature)
print('function_selector:', function_selector)
print('parameter_names:', parameter_names)
print('parameter_types:', parameter_types)
print('output_names:', output_names)
print('output_types:', output_types)

function_signature: balanceOf(address)
function_selector: 70a08231
parameter_names: ['account']
parameter_types: ['address']
output_names: ['']
output_types: ['uint256']

Parse an event ABI¶

In [9]:

event_hash = ctc.get_event_hash(event_abi)
event_signature = ctc.get_event_signature(event_abi)
event_indexed_names = ctc.get_event_indexed_names(event_abi)
event_indexed_types = ctc.get_event_indexed_types(event_abi)
event_unindexed_names = ctc.get_event_unindexed_names(event_abi)
event_unindexed_types = ctc.get_event_unindexed_types(event_abi)

print('event_hash:', event_hash)
print('event_signature:', event_signature)
print('event_indexed_names:', event_indexed_names)
print('event_indexed_types:', event_indexed_types)
print('event_unindexed_names:', event_unindexed_names)
print('event_unindexed_types:', event_unindexed_types)

event_hash: 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
event_signature: Transfer(address,address,uint256)
event_indexed_names: ['from', 'to']
event_indexed_types: ['address', 'address']
event_unindexed_names: ['value']
event_unindexed_types: ['uint256']

Decompile function ABIs from bytecode¶

In [10]:

import ctc.rpc

bytecode = await ctc.rpc.async_eth_get_code(contract_address)
function_abis = await ctc.async_decompile_function_abis(bytecode)

for function_abi in function_abis:
    print(function_abi['hex_signature'], function_abi['text_signature'])

0xa9059cbb transfer(address,uint256)
0xa9059cbb many_msg_babbage(bytes1)
0xa9059cbb transfer(bytes4[9],bytes5[6],int48[11])
0xa9059cbb func_2093253501(bytes)
0xb7f8cf9b borrowerOperationsAddress()
0xbb997bac sendToPool(address,address,uint256)
0xd505accf permit(address,address,uint256,uint256,uint8,bytes32,bytes32)
0xdd62ed3e allowance(address,address)
0xdd62ed3e remove_good(uint256[],bytes8,bool)
0xdd62ed3e _func_5437782296(address,address)
0xf698da25 domainSeparator()
0x5a4d28bb troveManagerAddress()
0x70a08231 balanceOf(address)
0x70a08231 branch_passphrase_public(uint256,bytes8)
0x70a08231 passphrase_calculate_transfer(uint64,address)
0x7ecebe00 nonces(address)
0x95d89b41 symbol()
0x95d89b41 link_classic_internal(uint64,int64)
0x9dc29fac burn(address,uint256)
0xa457c2d7 decreaseAllowance(address,uint256)
0x20c582be returnFromPool(address,address,uint256)
0x23b872dd transferFrom(address,address,uint256)
0x23b872dd gasprice_bit_ether(int128)
0x313ce567 decimals()
0x313ce567 available_assert_time(uint16,uint64)
0x39509351 increaseAllowance(address,uint256)
0x40c10f19 mint(address,uint256)
0x54fd4d50 version()
0x06fdde03 name()
0x06fdde03 message_hour(uint256,int8,uint16,bytes32)
0x095ea7b3 approve(address,uint256)
0x095ea7b3 sign_szabo_bytecode(bytes16,uint128)
0x0b622ab2 stabilityPoolAddress()
0x10ce43bd permitTypeHash()
0x18160ddd totalSupply()
0x18160ddd voting_var(address,uint256,int128,int128)

Reference

async ctc.evm.async_decompile_function_abis(bytecode, sort=None)

decompile solidity-style function ABI’s from contract bytecode

Return type

Sequence[Mapping[str, Any]]

async ctc.evm.async_get_contract_abi(contract_address, *, network=None, provider=None, use_db=True, db_query=None, db_intake=None, block=None, proxy_implementation=None, verbose=True)

retrieve abi of contract either from local database or block explorer

for addresses that change ABI’s over time, use db_query=False to skip cache

async ctc.evm.async_get_event_abi(*, contract_abi=None, contract_address=None, event_name=None, event_hash=None, event_abi=None, network=None)

get event ABI from local database or block explorer

async ctc.evm.async_get_function_abi(*, function_name=None, contract_abi=None, contract_address=None, n_parameters=None, parameter_types=None, function_selector=None, network=None)

get function ABI from local database or block explorer

ctc.binary.get_event_hash ctc.binary.get_event_indexed_names ctc.binary.get_event_indexed_types ctc.binary.get_event_signature ctc.binary.get_event_unindexed_names ctc.binary.get_event_unindexed_types ctc.binary.get_function_output_names ctc.binary.get_function_output_types ctc.binary.get_function_parameter_names ctc.binary.get_function_parameter_types ctc.binary.get_function_selector ctc.binary.get_function_signature

Contracts

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

import ctc

In [2]:

address = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'

Get proxy implementation¶

In [3]:

implementation = await ctc.async_get_proxy_implementation(address)

implementation

Out[3]:

'0xa2327a938febf5fec13bacfb16ae10ecbc4cbdcf'

In [4]:

await ctc.async_get_proxy_metadata(address)

Out[4]:

{'implementation': '0xa2327a938febf5fec13bacfb16ae10ecbc4cbdcf',
 'proxy_type': 'openzeppelin'}

Get contract creation block¶

In [5]:

block_number = await ctc.async_get_contract_creation_block(address)

block_number

Out[5]:

6082465

Check whether address is a contract¶

In [6]:

await ctc.async_is_contract_address(address)

Out[6]:

True

Resolve address¶

In [7]:

# for more detailed tools, see ctc.protocols.ens_utils

address = await ctc.async_resolve_address('vitalik.eth')
print(address)

address = await ctc.async_resolve_address('vitalik.eth', block=14000000)
print(address)

0xd8da6bf26964af9d7eed9e03e53415d37aa96045
0xd8da6bf26964af9d7eed9e03e53415d37aa96045

In [8]:

await ctc.async_resolve_addresses(
    ['vitalik.eth', 'paradigm.eth', 'tetranode.eth'],
)

Out[8]:

['0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
 '0xd61415f6c5d93027778ceab5f099f64c29f58fd7',
 '0x465e7c8cd7126dad1a905624ea5d85eb717ef41f']

In [9]:

await ctc.async_resolve_address_by_block(
    'tetranode.eth',
    blocks=[13000000, 14000000, 14500000, 15000000],
)

Out[9]:

['0xf7832ae2ae254326c9fb9b7ea1e1fa74d867f05c',
 '0xf7832ae2ae254326c9fb9b7ea1e1fa74d867f05c',
 '0xf7832ae2ae254326c9fb9b7ea1e1fa74d867f05c',
 '0x465e7c8cd7126dad1a905624ea5d85eb717ef41f']

Get address checksum¶

In [10]:

ctc.get_address_checksum(address)

Out[10]:

'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'

Get CREATE and CREATE2 addresses¶

In [11]:

# CREATE

ctc.get_created_address(sender=address, nonce=42)

Out[11]:

'0x1740e833ed8c289d79323054524cdbd52de500b8'

In [12]:

# CREATE2

ctc.get_created_address(
    sender=address,
    salt='0xdeadbeef',
    init_code='0xdeadbeef',
)

Out[12]:

'0x752083dd1c2e2f0b44de3a41a42ea21ed0345575'

Reference

async ctc.evm.async_get_contract_creation_block(contract_address, *, provider=None, use_db=True, **search_kwargs)

get block number of when contract was created

• behavior is undefined for functions that have undergone SELF-DESTRUCT(S)

• caches result in local database

Binary Data

Note

By default ctc will perform end-to-end encoding/decoding of many operations. The low-level functions listed here are only needed if you need to work directly with raw binary data.

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

import ctc

In [2]:

contract_address = '0x956f47f50a910163d8bf957cf5846d573e7f87ca'
wallet_address = '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655'

Get hash of data¶

In [3]:

ctc.keccak('0xdeadbeef')

Out[3]:

'0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1'

Get hash of text¶

In [4]:

ctc.keccak_text('goodbye')

Out[4]:

'0x795d549ea199f3d64ea49f5792287667c58f283ef1d500cba523a8fe1fc3d430'

Convert between binary formats¶

In [5]:

encoded = '0xdeadbeef'

print('prefix_hex:', ctc.binary_convert(encoded, 'prefix_hex'))
print()
print('raw_hex:', ctc.binary_convert(encoded, 'raw_hex'))
print()
print('integer:', ctc.binary_convert(encoded, 'integer'))
print()
print('binary:', ctc.binary_convert(encoded, 'binary'))

prefix_hex: 0xdeadbeef

raw_hex: deadbeef

integer: 3735928559

binary: b'\xde\xad\xbe\xef'

ABI Encoding / Decoding¶

In [6]:

data_to_encode = [
    ['int128', 4000],
    ['int16', 300],
    [['int128', 'int16'], (4000, 300)],
    [['int16', 'string', 'bool'], (123, 'hello there', False)],
]

In [7]:

# encode

for types, data in data_to_encode:
    encoded = ctc.abi_encode(data, types)
    as_hex = ctc.binary_convert(encoded, 'prefix_hex')
    print()
    print('original:', data)
    print('encoded:', as_hex)

original: 4000
encoded: 0x0000000000000000000000000000000000000000000000000000000000000fa0

original: 300
encoded: 0x000000000000000000000000000000000000000000000000000000000000012c

original: (4000, 300)
encoded: 0x0000000000000000000000000000000000000000000000000000000000000fa0000000000000000000000000000000000000000000000000000000000000012c

original: (123, 'hello there', False)
encoded: 0x000000000000000000000000000000000000000000000000000000000000007b00000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000b68656c6c6f207468657265000000000000000000000000000000000000000000

In [8]:

# encode packed

for types, data in data_to_encode:
    encoded = ctc.abi_encode_packed(data, types)
    as_hex = ctc.binary_convert(encoded, 'prefix_hex')
    print()
    print('original:', data)
    print('encoded:', as_hex)

original: 4000
encoded: 0x00000000000000000000000000000fa0

original: 300
encoded: 0x012c

original: (4000, 300)
encoded: 0x00000000000000000000000000000fa0012c

original: (123, 'hello there', False)
encoded: 0x007b68656c6c6f20746865726500

In [9]:

# decode

for types, data in data_to_encode:
    encoded = ctc.abi_encode(data, types)
    as_hex = ctc.binary_convert(encoded, 'prefix_hex')
    decoded = ctc.abi_decode(encoded, types)

    print()
    print('original:', data)
    print('encoded:', as_hex)
    print('decoded:', decoded)

original: 4000
encoded: 0x0000000000000000000000000000000000000000000000000000000000000fa0
decoded: 4000

original: 300
encoded: 0x000000000000000000000000000000000000000000000000000000000000012c
decoded: 300

original: (4000, 300)
encoded: 0x0000000000000000000000000000000000000000000000000000000000000fa0000000000000000000000000000000000000000000000000000000000000012c
decoded: (4000, 300)

original: (123, 'hello there', False)
encoded: 0x000000000000000000000000000000000000000000000000000000000000007b00000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000b68656c6c6f207468657265000000000000000000000000000000000000000000
decoded: (123, 'hello there', False)

RLP encoding / decoding¶

In [10]:

for types, data in data_to_encode:
    
    encoded = ctc.rlp_encode(data)
    
    decoded = ctc.rlp_decode(encoded, types)
#     if isinstance(types, str):
#         decoded = ctc.binary_convert(decoded, 'integer')

    print()
    print('original:', data)
    print('encoded:', encoded)
    print('decoded:', decoded)

original: 4000
encoded: 0x820fa0
decoded: 4000

original: 300
encoded: 0x82012c
decoded: 300

original: (4000, 300)
encoded: 0xc6820fa082012c
decoded: [4000, 300]

original: (123, 'hello there', False)
encoded: 0xce7b8b68656c6c6f20746865726580
decoded: [123, 'hello there', False]

Encode call data¶

In [11]:

function_abi = await ctc.async_get_function_abi(
    contract_address=contract_address,
    function_name='balanceOf',
)

In [12]:

encoded_call_data = ctc.encode_call_data(
    function_abi=function_abi,
    parameters=[wallet_address],
)

encoded_call_data

Out[12]:

'0x70a0823100000000000000000000000006cb22615ba53e60d67bf6c341a0fd5e718e1655'

Decode call data¶

In [13]:

decoded_call_data = ctc.decode_call_data(
    encoded_call_data,
    function_abi=function_abi,
)

decoded_call_data

Out[13]:

{'function_abi': {'inputs': [{'internalType': 'address',
    'name': 'account',
    'type': 'address'}],
  'name': 'balanceOf',
  'outputs': [{'internalType': 'uint256', 'name': '', 'type': 'uint256'}],
  'stateMutability': 'view',
  'type': 'function'},
 'function_selector': '0x70a08231',
 'parameters': ['0x06cb22615ba53e60d67bf6c341a0fd5e718e1655'],
 'named_parameters': {'account': '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655'}}

Decode function output¶

In [14]:

import ctc.rpc

In [15]:

raw_function_output = await ctc.rpc.async_eth_call(
    to_address=contract_address,
    call_data=encoded_call_data,
    decode_response=False,
)
auto_decoded_function_output = await ctc.rpc.async_eth_call(
    to_address=contract_address,
    call_data=encoded_call_data,
    function_abi=function_abi,
    decode_response=True,
)
manually_decoded_function_output = ctc.decode_function_output(
    encoded_output=raw_function_output,
    function_abi=function_abi,
)

print('raw_function_output:', raw_function_output)
print('auto_decoded_function_output:', auto_decoded_function_output)
print('manually_decoded_function_output:', manually_decoded_function_output)

raw_function_output: 0x00000000000000000000000000000000000000000000a5c8cfd416300389df58
auto_decoded_function_output: 782894794107289757933400
manually_decoded_function_output: 782894794107289757933400

Reference

[none]

.. autofunction:: ctc.binary.convert .. autofunction:: ctc.binary.decode_call_data .. autofunction:: ctc.binary.decode_function_output .. autofunction:: ctc.binary.decode_types .. autofunction:: ctc.binary.encode_call_data .. autofunction:: ctc.binary.encode_types .. autofunction:: ctc.binary.keccak .. autofunction:: ctc.binary.keccak_text

Blocks

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

import ctc

Get block¶

In [2]:

block = await ctc.async_get_block(14000000)

block

Out[2]:

{'base_fee_per_gas': 139541559304,
 'difficulty': 12316581093827601,
 'extra_data': '0x6175737472616c69612d736f75746865617374312d31',
 'gas_limit': 30058561,
 'gas_used': 8119826,
 'hash': '0x9bff49171de27924fa958faf7b7ce605c1ff0fdee86f4c0c74239e6ae20d9446',
 'logs_bloom': '0x083815041300081040f485088003de10046040491c3c0164189830ca3c2c0d1121040493008ba600924849820c8901130b0084038802610706000b6101b220d01210000400020b08480850880d0226a04024e107005114513410021080080451126063400a1084021c62bc08290008a0430081540c892545360c401410194021426103228249162800ac016601100d0520b96203432080086a00424d8214010b63180471318634d0ae00108041a1184488a10841a2610e0401e9001a504a4010098182020808155027009c02008e56070c28728114480490400801cac010290ae291a00ca0408b60204c128012601c100a24cc01e100897242832a825000c1e1',
 'miner': '0xea674fdde714fd979de3edf0f56aa9716b898ec8',
 'mix_hash': '0xa832679fcf3e71f0b29bd5913955151be5bf1fc59e135e3c7eb6e30f8442a5df',
 'nonce': '0x31e7e99df18e0424',
 'number': 14000000,
 'parent_hash': '0x0c9ef41f038aa58a4aa2810fda03d9d82aac9082c80283230fd74cb1cceb4b00',
 'receipts_root': '0xf7b9f8e92a4b420a27302ab91084e5499d3d711183a021f4956ff32de246e14e',
 'sha3_uncles': '0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347',
 'size': 58470,
 'state_root': '0xfb3df73e7a41d500a374ee236dd613bb24f1a5fa5b80615a7953ea75c26c6a6d',
 'timestamp': 1642114795,
 'total_difficulty': '38896129597749836221010',
 'transactions': ['0x3dac2080b4c423029fcc9c916bc430cde441badfe736fc6d1fe9325348af80fd',
  '0x82a6fdc276916a97a4723bb15ffc39b4e8efd2cd2044e7957b46a93c00e95b7c',
  '0x1dc98e66e46d8bbb0936b5d57ef9685caf2be3a561ae232fe35cc91d2f1f49d3',
  '0x28c466d01156df471dca4655c7199706afbcb4a849cc808e8640a7e7de89f7b2',
  '0x3b9c1f0a4a2e9eee54dea8c217711a3addb558d64fa2b7c70578fa2502edb0c3',
  '0x296cc22df5c8b951f297dc4e2cfd53562f67a774e80a089f479571b25670e66b',
  '0xb48403ca12261877e572c52d580dd978c275ebae9211e7a672ed857c8d5500f6',
  '0x627d63666c75192aec83ea65dc442df369decf696cf8144f68dbf7f187094039',
  '0x7781f35dc378a967e43dce46cd8607646a918be3bec904a8b7d2ef549e363417',
  '0x21ebb965dfcdaba5acd5be2b36edc33320f075dc39be2040e0927667f4457fb6',
  '0xa70fdd89ad3b69973359c2644fb2bf85d8c7e17f6e102eeb6477b19c38aa98bb',
  '0xdbd52ee92b76edd9db38da42856a51107433edd86cc77f85732f9fc34452fcdc',
  '0x5b8f2f0357dbdb278abd5d55b6f8fa138eb3c5bcb5eee853f359e3f12bda2838',
  '0x45113eb6abd490372fb22b9212adaa8dbbc882b4781fcee6cbb7643f7a338091',
  '0x9f6e14474230f412c1dd5034a2209372763539b6ee76acf7288836efc03bfd84',
  '0xda19521fd5f0ad64b33fe39c70f9a313bf432826aa1f37959a88381af34efa59',
  '0x26256210c64300cdef6bcd4663206676a918e0b7c4c2bef2058b839fe1bf5ade',
  '0xc26aac94c691040a0f126a0582c7342795af39034e79b54943c34ac99329c822',
  '0x8ab0f56e9cc352314368a20fcd73a7de622692983fd19e53087081578e889d57',
  '0x57d755615684d53415cf2d47004f46d78478fd81df886d86e0f6f2066f222b2f',
  '0x28aea3e818f854744bb6bb4a4f05cc5612026e5fb53eeffe750373bd6268c1b5',
  '0xfb81b965f0b55327d06b63e597cb80768d83227045e3065fd214982e3aae7ead',
  '0x58c03330f067e408fcb251bec67a18920bcf13b53f559fd7c99d90abb84c5751',
  '0xfe7efe42fb99036825c456c890f2da08ed58f22ef7c6b38d27d866eb69e31782',
  '0x3dfcf735a0acb9955a4457c5dfff589f16efc59926b7cfc4de74098fd17f4c79',
  '0xd49caad5d0fc7171266516ebb091da5662b36981138de47386e59677c6b73b2e',
  '0x12e72642adbfac3c0f2144e3f83a18c8a51aababea1940dfb458474aadd7d6fb',
  '0xb365be2030527975486f1a39427d846b8d33e052af1c0557eeec6aa902fee985',
  '0x7dc548e2551ae5b40170006c7a1f1c9d00006d43623f21fa77d9a9621da1960b',
  '0x814f18814e74e4e39393355ab9a21858e6894cd1bb74113f7f44f33c4441a310',
  '0xc9deea622c8901db67edd7c991d613c35b73fa2fca4fbd2bc59548cf34b42d88',
  '0xf55f98b1be7dabad23cff853ee0de0175b95ea3fdedc35ef323c126cc7df3ad9',
  '0x67b282062ff5ca96eb3d587b6ae4771bda0d170aec2e40a1ea93d23973443821',
  '0x60085d9f157a8426b3d2795de6cebbd4b50d541445be08e23f2b458d4bd0e60e',
  '0x6d7b7c7b43aeebece34dfb17c46a0bf83237693e57742d1c6166f1a74217125f',
  '0xb9768a9acddde75d8b80d4b9d661024086674341626837e31a3ac12c20ad7298',
  '0xf41ffd9f8a232dd5383328178999a3d859a8947b152ceb25650dbb4a0a9ff445',
  '0x7ad3c1541183fccb969fd4652e7a856b23026cec1e5153899c641579147df3e9',
  '0x73e5371291a6df1535f03573030bfca55c8185b65a939d6c59304778cbb59523',
  '0xc997cd28446ea82a660957535c8e6604885323d9fbd6c3189b1cc6e4bfc2ca32',
  '0x479806bdca2826848153f90caa7437e8b635639aab93f4cfabcc2bd914883780',
  '0xe4724b44a49cbf94d8f9657e619051fcf4ea4a5ea1bf98187b5a19b9623d910f',
  '0x37b618552833545cc294f42061ba5c43df47c71423ef58ea0fc71f7bc69cdfe8',
  '0x95d0cf5306b464b272445d80d5fcf264a4fba8ba908352e364aac0fb569d13b2',
  '0x71a5827a67459b7e7a1a7a84459174b8816441977b8b5be885cb2f05f2535319',
  '0x426e9c522f36c2bc8637616d7a125afd5dbac627d7e73e45f0477a282544f732',
  '0x1b8433d194a29b981d1a94a73b4e50de4de6e27cb3dd0f3a76e5919655fad73a',
  '0x937a105002120c54542d050270d81d618c70d702761630664d6a73d33085f993',
  '0xd6b6c532c065cd49a0485aa1af9bb067df5ad36704d30c799b248bd08eaf39ff',
  '0x2f002236f8f0d85cb411b7d5c958c266921ce2787ab14472afb8515cd3b1bcbd',
  '0x6851c2514310a597460ddffea524e1dd5b321124355dd83bd6b236b7c61ea1e9',
  '0x57b28d954dc03e9fbfb674fb100e96f721c27e9f1eaab9aaefb44729b2fd7ef3',
  '0xc303b7a2f54e89643b73c7ff11f165b2ba979878028f106686085da1b98302e4',
  '0xeaf6671ddf866fe0632612b80136032f50c096162198905ab6fd7544385ff64c',
  '0xd3607f690abf48d29c4d37ee117b0e9061dcf0e59919871dc2d4e0e25384ef4e',
  '0x108d74bf50d4cdfd5f778426f39facb32bd0773d53f5ce39167334824af6f376',
  '0xcac1e7878c91064571f7bd6c48c814b8c3bc39459f4e9ae7b034709b0f8c961e',
  '0x77ae0fe18ac9b3147e2e7542f4d352039c37c7ff3751a31e2bc69e27f5d72f55',
  '0xb5eb72b80b23698cf88dd445688109ee407cd98dc58f92e0617093fee529ba2a',
  '0xeb6b97eeb9e23275392757cb59140c05b67887c1d63d70b9d2e352ecc6927cb8',
  '0x077ad2efa19c7b4caeba6f175c2899b82382dff6c80cfe08571aad0189bd04a4',
  '0x56442cc66fc031cacf528aee196904d9665fe6d6da26d4de993e3ae6353d3ec5',
  '0x998340271bf5500ff7b4d732fd6d6cbc3c9d4fb9d8c367dec1a40fb9a130056e',
  '0x7a38f49483bf8270c05c0d168612b59e65b44acc6d0c465c447a90b356589b53',
  '0xeae63c92f6083e41292445909e5713e3227edc96bc7d84f85f43c739dba07de0',
  '0xc2ee70de2133d625f8033a4b4b08ea34b27dd0ab0da69dc62f010be2324bde3e',
  '0x028a22ee71202d985ab3c349aa5fd152bda1ca648a15392a9da1a9a9f8dd92dd',
  '0x6234a2669da8e91fcbe6c81458a0b89616a6d9ee81380b9e88d3d1b905a3a42f',
  '0x8a875ed36fa0116a9ce71bb289dddc24d84229a9e4b5b4329ad14c39234bc54d',
  '0xdfa69e312ba84abf6da37799b15171a5e553ec805aa23141f729da78fa00bfbe',
  '0xdb33606e300cc18a0f7d1d2ef8afc54f587117d75ae328d2cc1d21a281783b7f',
  '0x2cc9e8a5061bad4513ced54f4b14da3f49ffbb4fc662f5233a6cafe74e5e561f',
  '0x54f23a1418ee9ae058eafee2bd923087266fe0e4b92f477e9041444500cbe469',
  '0xaddf3bf9142cd7c2bface37492517e9eee2b4b29eb348f938ff7a4de16829150',
  '0xab0f76a492da23fdaf61a02de4cf4a9248c745262d16d9f3e3841a3d24f5ff9b',
  '0x031f831c69b9ada875b89de687114f6bdb58bad7db866e805b2a78326a392dc3',
  '0x4775c998bf82e2eea995deeae091df3e73f417ab27a2f5544348b7816af92127',
  '0xefddceb649e8b0d1b091fd9f7d768d13f2b085d50ae87becbc087c952879beaa',
  '0xc6c79ffb86f0f2efd16f49271224823d078a30a7892c465ba3cba20e87c0a36e',
  '0xccdeaf56bd85047cfd2d7c565341e862c55c139b81550bf35e2add633ddf3a47',
  '0xab8b149b54d17e86be6e817950be1ca7eeb92961189b5c378787eb6623f481d9',
  '0x62ddc128f28f1290b131a81fb1343fe865968d848fcb25ed6fc528a098e7e5f2',
  '0xdb3d3f5a611d7c7eba5aa9d262773d61a9b17053bec3b5b80ca32d693734ab9d',
  '0xb97a697052ae86df2bc654d0efaac8c5e8e6a8dd2b5e3f85b3405ea5aa8f3885',
  '0x8c776afd6a7788e60ba0f6a4cc481bd3aa83103c8c17181cf1258d22256d6c38',
  '0x8cf7be01b6b673636db8fcda3dfff311560c84d3415a7c0c1696f126955f02e9',
  '0x6b1672db798a679c676731595c2ed0a097e6f1289c0cbdd04b8a6294901017d5',
  '0x980458bce7ac5cd9298085fb9ad28d78ae05a32ef5957f34589bda023d28489a',
  '0x316614b6ff95f4dff67126c3823515b724b0dbb7b64b33d0c38fc3713e734c58',
  '0xf658c0e7cd445d33c51ab898a392e9be0b8993c9b488f2230e10053f2e06e464',
  '0xca36ca009002bfed0aab34e2f1956715ea87a6a2b9789510d7dedcb70d6caf93',
  '0x1f34dfdf44ba37e291a789a2f2ef2f50fd1c164f877bda42589011d78939fb03',
  '0xef3fbc478323963fddc3897fc87c2d5fde44723788bfdea8aee81d0112e4e9bf',
  '0x8fdda8443257b354f735edf389a2c21ec8b99622d4b1b7bfdc1dbd1da8794f0e',
  '0xe0c368234454e27f66d26b2d6fb56c3e69a5de50e0ac13ba8b551650a0a4889d',
  '0xb4fbcd7d03598433a5f62bf6c5b2b3439679ebc20ef70456f781c3b93de7f412',
  '0xef2a8b39cb701fb31de04f9012be4cf2afc926199712aa2ee84a9565900d9645',
  '0x3ee5d86e13de20224e294bde4e3ca05988b993c6c072da5dbfdbc91fea83a43c',
  '0x0d0022a1153b603ab7c366e53ed98519f42cdced8c4f6fa82ff91d5df3669e1e',
  '0x0c6bf6056445de030b248368fdab25b023775d8b83c29a42ccd9103d4f37400e',
  '0x9ea837318f53828f5cf1c41a9d37fafc84d9045823bf5c5f6a44d9cc36f2a796',
  '0x673c56108c17f9c3b72424212879e7a1e8af5250d7b5f902dcd640f9a0c9ab1a',
  '0xe2d6ec4a37beedad1b22c23086edbce75285eeb54fd84b6b38573d9e22553827',
  '0xb58330d5f922894800112c781831802d32b413eff2ee3b7656f3747ab3f8178a',
  '0x45552aea90d9a8ce86291a9b786d2b6106e625ccac44bb1984b9346ae84e50dc',
  '0x4db4831ae73afe2dba5079b4fbe50566f77bea28947078f46ef85d05b6beab41',
  '0xae264a00b982b439e21fea8a99845d3c3d1143b05d15b990ce5453579cd7ebc9',
  '0x5a80c76aa726b3bd0da69d1f3eaf4ab5d98ee9f95f337cc07799d2e5fd8f201a',
  '0x97abc3053b0e74381d52bfd3b278a135afdae0b7e1ee21a30dfbbc08dc20b422',
  '0x989240bc99820609573e19fbfa3b69780b06c6255163cb9059ac60dd0bec766c',
  '0x2f89ebd51377291f39b315a5feac7cbef0c8377f512bba32b128d59b086f6abe',
  '0x146063226f2bc60ab02fff825393555672ff505afb352ff11b820355422ba31e'],
 'transactions_root': '0x16b6ff83df3ef14f614c70ac29e8a05d102c6bed0e5882c284abf0120b89529c',
 'uncles': []}

Get blocks¶

In [3]:

blocks = await ctc.async_get_blocks(range(14000000, 14000100))

len(blocks)

Out[3]:

100

latest is a valid block number reference¶

In [4]:

block = await ctc.async_get_block('latest')

block['number']

Out[4]:

15613480

In [5]:

await ctc.async_get_latest_block_number()

Out[5]:

15613480

Get block number of timestamp¶

In [6]:

block_number = await ctc.async_get_block_of_timestamp(1650946000)

block_number

Out[6]:

14657968

Get block numbers of timestamps¶

In [7]:

timestamps = range(1650746000, 1650946000, 86400)

block_numbers = await ctc.async_get_blocks_of_timestamps(timestamps)

block_numbers

Out[7]:

[14643250, 14649567, 14655946]

Gas Statistics¶

In [8]:

await ctc.async_get_block_gas_stats(14000000)

Out[8]:

{'base_fee': 139.541559304,
 'min_gas_price': 140.0,
 'median_gas_price': 142.203313325,
 'mean_gas_price': 152.89720574486594,
 'max_gas_price': 230.0,
 'gas_used': 8119826,
 'gas_limit': 30058561,
 'n_transactions': 112}

Predicting future blocks¶

In [9]:

import tooltime

In [10]:

# predict timestamp of future block

block_number = 20000000
timestamp = await ctc.async_predict_block_timestamp(block_number)

print('timestamp:', timestamp)
print('timestamp pretty:', tooltime.timestamp_to_iso_pretty(timestamp))

timestamp: 1718757106
timestamp pretty: 2024-06-19 00:31:46Z

In [11]:

# predict block of future timesatmp

block_number = await ctc.async_predict_timestamp_block('2024-01-01')

block_number

Out[11]:

18735802

Reference

async ctc.evm.async_get_block(block, *, include_full_transactions=False, provider=None, use_db=True)

get block from local database or from RPC node

async ctc.evm.async_get_block_of_timestamp(timestamp, *, nary=None, cache=None, block_timestamps=None, block_timestamp_array=None, block_number_array=None, verbose=False, provider=None, use_db=True, use_db_assist=True, mode='>=')

search for the block that corresponds to a given timestamp

async ctc.evm.async_get_blocks(blocks, *, include_full_transactions=False, chunk_size=500, provider=None, use_db=True, latest_block_number=None)

get blocks from local database or from RPC node

async ctc.evm.async_get_blocks_of_timestamps(timestamps, *, block_timestamps=None, block_number_array=None, block_timestamp_array=None, nary=None, cache=None, provider=None, use_db=True, mode='>=')

search for blocks corresponding to list of timestamps

ERC20s

Note

functions that require multiple RPC calls will attempt to do so concurrently for maximum efficiency

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

import ctc

In [2]:

erc20 = '0x956f47f50a910163d8bf957cf5846d573e7f87ca'

erc20s = [
    '0x956f47f50a910163d8bf957cf5846d573e7f87ca',
    '0x5f98805a4e8be255a32880fdec7f6728c6568ba0',
    '0x6b175474e89094c44da98b954eedeac495271d0f',
]

Get ERC20 metadata¶

In [3]:

name = await ctc.async_get_erc20_name(erc20)
symbol = await ctc.async_get_erc20_symbol(erc20)
decimals = await ctc.async_get_erc20_decimals(erc20)

print('name:', name)
print('symbol:', symbol)
print('decimals:', decimals)

name: Fei USD
symbol: FEI
decimals: 18

Get ERC20s metadata¶

In [4]:

names = await ctc.async_get_erc20s_names(erc20s)
symbols = await ctc.async_get_erc20s_symbols(erc20s)
decimals = await ctc.async_get_erc20s_decimals(erc20s)

print('names:', names)
print('symbols:', symbols)
print('decimals:', decimals)

names: ['Fei USD', 'LUSD Stablecoin', 'Dai Stablecoin']
symbols: ['FEI', 'LUSD', 'DAI']
decimals: [18, 18, 18]

Get ERC20 state¶

In [5]:

total_supply = await ctc.async_get_erc20_total_supply(erc20)
address_balance = await ctc.async_get_erc20_balance(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
)

print('total_supply:', total_supply)
print('address_balance:', address_balance)

total_supply: 60925882.852203734
address_balance: 782894.7941072898

Get raw un-normalized ERC20 state¶

In [6]:

raw_total_supply = await ctc.async_get_erc20_total_supply(
    erc20,
    normalize=False,
)
raw_address_balance = await ctc.async_get_erc20_balance(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
    normalize=False,
)

print('raw_total_supply:', raw_total_supply)
print('raw_address_balance:', raw_address_balance)

raw_total_supply: 60925882852203735163742362
raw_address_balance: 782894794107289757933400

Normalize raw un-normalized ERC20 values¶

In [7]:

normalized_total_supply = await ctc.async_normalize_erc20_quantity(
    raw_total_supply,
    erc20,
)
normalized_values = await ctc.async_normalize_erc20_quantities(
    [raw_total_supply, raw_address_balance],
    erc20,
)

print('normalized_total_supply:', normalized_total_supply)
print('normalized_values:', normalized_values)

normalized_total_supply: 60925882.852203734
normalized_values: [60925882.852203734, 782894.7941072898]

Get historical ERC20 state from a specific block¶

In [8]:

total_supply = await ctc.async_get_erc20_total_supply(
    erc20,
    block=14000000,
)
address_balance = await ctc.async_get_erc20_balance(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
    block=14000000,
)

print('total_supply:', total_supply)
print('address_balance:', address_balance)

total_supply: 751748886.6295298
address_balance: 126538335.35590503

Get historical ERC20 state across multiple blocks¶

In [9]:

blocks = [14000000, 14100000, 14200000]

total_supplies = await ctc.async_get_erc20_total_supply_by_block(
    erc20,
    blocks=blocks,
)
address_balances = await ctc.async_get_erc20_balance_by_block(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
    blocks=blocks,
)

print('total_supplies:', total_supplies)
print('address_balances:', address_balances)

total_supplies: [751748886.62953, 528229617.5828952, 550695508.5094506]
address_balances: [126538335.35590503, 110223666.2844692, 122075790.9010594]

Get state of multiple ERC20s¶

In [10]:

total_supplies = await ctc.async_get_erc20s_total_supplies(erc20s)
address_balances = await ctc.async_get_erc20s_balances(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20s,
)

print('total_supplies:', total_supplies)
print('address_balances:', address_balances)

total_supplies: [60925882.852203734, 169451076.90321591, 6470667884.040302]
address_balances: [782894.7941072898, 0.0, 0.0]

Get ERC20 balance of multiple addresses¶

In [11]:

addresses = [
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    '0x9928e4046d7c6513326ccea028cd3e7a91c7590a',
    '0x2a188f9eb761f70ecea083ba6c2a40145078dfc2',
]

addresses_balances = await ctc.async_get_erc20_balances_of_addresses(
    addresses,
    erc20,
)

print('addresses_balances:', addresses_balances)

addresses_balances: [782894.7941072898, 13430875.390003089, 0.0]

Get ERC20 transfers¶

In [12]:

transfers = await ctc.async_get_erc20_transfers(erc20, verbose=False)

transfers

Out[12]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__from	arg__to	arg__amount
block_number	transaction_index	log_index
12168368	61	29	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	1302613195.326042
		32	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	1315770904.36974
		34	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	1315770904.36974
		42	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x0000000000000000000000000000000000000000	0.0
		46	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	500.0
...	...	...	...	...	...	...	...	...	...	...	...
15613010	41	309	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xaae39c6fe7493accb4638bf7c56ae46c8bce5fa0fa3d...	0xd5a6c5231f6f1a8b67ae6a5399ea1d827b0ad3edecd5...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xf2f400c138f9fb900576263af0bc7fcde2b1b8a8	0xba12222222228d8ba445958a75a0704d566bf2c8	185.469717
15613063	96	263	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x18107b4cd7d0f7271fa0a7acff48b39d50c0b765e06a...	0x0a249e10c1e5e74a08cb1f34313eeccc8d0208c4de08...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9435f1085584764b081177944033d4ed2cfd23ee	82.440313
15613067	47	148	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x5687eabcf6df0d3f400f8b56616b3a37391b927a8113...	0x992111315f732cb36397113171f30b12ab177cea53c1...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9435f1085584764b081177944033d4ed2cfd23ee	118.178479
15613072	119	257	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x5b390756df46a718f25302f6d0ce716bff2b862fe486...	0xd379f7a306705039563bb0f3673303a55688b9857305...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9435f1085584764b081177944033d4ed2cfd23ee	0xdf50fbde8180c8785842c8e316ebe06f542d3443	200.618792
15613170	3	34	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x0d8b43d3739d7d28d4ff9cbf08454a6e609979dbdead...	0xca4556984e83346d371ef525e4df96746354fe322908...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xba12222222228d8ba445958a75a0704d566bf2c8	0xdf50fbde8180c8785842c8e316ebe06f542d3443	847.083255

276957 rows × 9 columns

Get ERC20 balances from transfers¶

In [13]:

transfers = await ctc.async_get_erc20_transfers(
    erc20,
    normalize=False,
    verbose=False,
)
holders = await ctc.async_get_erc20_balances_from_transfers(transfers)

holders

Out[13]:

address
0x3a24fea1509e1baeb2d2a7c819a191aa441825ea     23649097120164751841622097
0x9928e4046d7c6513326ccea028cd3e7a91c7590a     13430875390003088310235460
0xc69ddcd4dfef25d8a793241834d4cc4b3668ead6      3367911210892676408060632
0xfafc562265a49975e8b20707eac966473795cf90      2634540334855403348554034
0xfea132a3b7b70089f3d58f04ec1d1c2f321ef660      2224435487972802282933177
                                                         ...             
0x5d2bea390f2a02734d4d4a427409be221c8a2f79                              0
0x5d1e8591452763486966752263c8298421f42fdd                              0
0x5d1aa8941d5bb8751000dec8a73cf3d293d221ff                              0
0x5d17b355538a9ea9b45a0018e11b36947fc16376                              0
0x0000000000000000000000000000000000000000    -60925882852203735163742362
Name: balance, Length: 21013, dtype: object

Reference

async ctc.evm.async_get_erc20_balance(wallet, token, *, block=None, normalize=True, provider=None, **rpc_kwargs)

get ERC20 balance

async ctc.evm.async_get_erc20_balances_of_addresses(wallets, token, *, block=None, normalize=True, provider=None, **rpc_kwargs)

get ERC20 balance of multiple addresses

async ctc.evm.async_get_erc20_balance_by_block(wallet, token, *, blocks, normalize=True, provider=None, empty_token=0, **rpc_kwargs)

get historical ERC20 balance over multiple blocks

async ctc.evm.async_get_erc20_decimals(token, *, block=None, use_db=True, provider=None, **rpc_kwargs)

get decimals of an erc20

async ctc.evm.async_get_erc20_balances_from_transfers(transfers, *, block=None, dtype=None, normalize=False)

compute ERC20 balance of each wallet using Transfer events

async ctc.evm.async_get_erc20_name(token, *, block=None, use_db=True, provider=None, **rpc_kwargs)

get name of an erc20

async ctc.evm.async_get_erc20_symbol(token, *, block=None, use_db=True, provider=None, **rpc_kwargs)

get symbol of an erc20

async ctc.evm.async_get_erc20_total_supply(token, *, block=None, normalize=True, provider=None, **rpc_kwargs)

get total supply of ERC20

async ctc.evm.async_get_erc20_total_supply_by_block(token, blocks, *, normalize=True, provider=None, **rpc_kwargs)

get historical total supply of ERC20 across multiple blocks

async ctc.evm.async_get_erc20_transfers(token, *, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False, normalize=True, convert_from_str=True, verbose=False, provider=None, **event_kwargs)

get transfer events of ERC20 token

async ctc.evm.async_get_erc20s_balances(wallet, tokens, *, block=None, normalize=True, provider=None, **rpc_kwargs)

get ERC20 balance of wallet for multiple tokens

async ctc.evm.async_get_erc20s_decimals(tokens, *, block=None, **rpc_kwargs)

get decimals of multiple erc20s

async ctc.evm.async_get_erc20s_names(tokens, block=None, **rpc_kwargs)

get name of multiple erc20s

async ctc.evm.async_get_erc20s_symbols(tokens, *, block=None, **rpc_kwargs)

get symbol of multiple erc20s

async ctc.evm.async_get_erc20s_total_supplies(tokens, *, block=None, normalize=True, provider=None, **rpc_kwargs)

get total supplies of ERC20s

async ctc.evm.async_normalize_erc20_quantities(quantities, token=None, *, provider=None, decimals=None, block=None)

normalize ERC20 quantites by adjusting radix by (10 ** decimals)

async ctc.evm.async_normalize_erc20_quantity(quantity, token=None, *, provider=None, decimals=None, block=None)

convert raw erc20 quantity by adjusting radix by (10 ** decimals)

ETH Balances

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

import ctc

In [2]:

address = '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'

addresses = [
    '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
    '0xf977814e90da44bfa03b6295a0616a897441acec',
]

Get ETH balance of address¶

In [3]:

balance = await ctc.async_get_eth_balance(address)

balance

Out[3]:

1183.9444491905404

Get raw un-normalized ETH balance of address¶

In [4]:

balance = await ctc.async_get_eth_balance(address, normalize=False)

balance

Out[4]:

1183944449190540293798

Get ETH balance of address in specific block¶

In [5]:

balance = await ctc.async_get_eth_balance(address, block=10000000)

balance

Out[5]:

30.625853991434212

Get ETH balance of address across multiple blocks¶

In [6]:

blocks = range(int(10e6), int(14e6), int(1e6))
balances = await ctc.async_get_eth_balance_by_block(address, blocks=blocks)

balances

Out[6]:

[30.625853991434212, 8.262617966894156, 7.209924409854158, 7606.165945835849]

Get ETH balance of multiple addresses¶

In [7]:

balances = await ctc.async_get_eth_balance_of_addresses(addresses)

balances

Out[7]:

[1183.9444491905404, 3957828.2878176, 2436827.477025209]

Reference

Events

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

import ctc

In [2]:

contract_address = '0x956f47f50a910163d8bf957cf5846d573e7f87ca'

Get events by name¶

In [3]:

events = await ctc.async_get_events(
    contract_address=contract_address,
    event_name='Transfer',
    verbose=False,
)

events

Out[3]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__from	arg__to	arg__value
block_number	transaction_index	log_index
12168368	61	29	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	1302613195326042426081658189
		32	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	1315770904369739824324907262
		34	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	1315770904369739824324907262
		42	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x0000000000000000000000000000000000000000	0
		46	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	500000000000000000000
...	...	...	...	...	...	...	...	...	...	...	...
15613010	41	309	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xaae39c6fe7493accb4638bf7c56ae46c8bce5fa0fa3d...	0xd5a6c5231f6f1a8b67ae6a5399ea1d827b0ad3edecd5...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xf2f400c138f9fb900576263af0bc7fcde2b1b8a8	0xba12222222228d8ba445958a75a0704d566bf2c8	185469717332960281460
15613063	96	263	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x18107b4cd7d0f7271fa0a7acff48b39d50c0b765e06a...	0x0a249e10c1e5e74a08cb1f34313eeccc8d0208c4de08...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9435f1085584764b081177944033d4ed2cfd23ee	82440313368426018120
15613067	47	148	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x5687eabcf6df0d3f400f8b56616b3a37391b927a8113...	0x992111315f732cb36397113171f30b12ab177cea53c1...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9435f1085584764b081177944033d4ed2cfd23ee	118178478503069594837
15613072	119	257	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x5b390756df46a718f25302f6d0ce716bff2b862fe486...	0xd379f7a306705039563bb0f3673303a55688b9857305...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9435f1085584764b081177944033d4ed2cfd23ee	0xdf50fbde8180c8785842c8e316ebe06f542d3443	200618791871495612957
15613170	3	34	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x0d8b43d3739d7d28d4ff9cbf08454a6e609979dbdead...	0xca4556984e83346d371ef525e4df96746354fe322908...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xba12222222228d8ba445958a75a0704d566bf2c8	0xdf50fbde8180c8785842c8e316ebe06f542d3443	847083254783738283116

276957 rows × 9 columns

Get events by hash¶

In [4]:

events = await ctc.async_get_events(
    contract_address=contract_address,
    event_hash='0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
    verbose=False,
)

events

Out[4]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__from	arg__to	arg__value
block_number	transaction_index	log_index
12168368	61	29	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	1302613195326042426081658189
		32	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	1315770904369739824324907262
		34	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	1315770904369739824324907262
		42	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x0000000000000000000000000000000000000000	0
		46	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	500000000000000000000
...	...	...	...	...	...	...	...	...	...	...	...
15613010	41	309	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xaae39c6fe7493accb4638bf7c56ae46c8bce5fa0fa3d...	0xd5a6c5231f6f1a8b67ae6a5399ea1d827b0ad3edecd5...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xf2f400c138f9fb900576263af0bc7fcde2b1b8a8	0xba12222222228d8ba445958a75a0704d566bf2c8	185469717332960281460
15613063	96	263	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x18107b4cd7d0f7271fa0a7acff48b39d50c0b765e06a...	0x0a249e10c1e5e74a08cb1f34313eeccc8d0208c4de08...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9435f1085584764b081177944033d4ed2cfd23ee	82440313368426018120
15613067	47	148	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x5687eabcf6df0d3f400f8b56616b3a37391b927a8113...	0x992111315f732cb36397113171f30b12ab177cea53c1...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9435f1085584764b081177944033d4ed2cfd23ee	118178478503069594837
15613072	119	257	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x5b390756df46a718f25302f6d0ce716bff2b862fe486...	0xd379f7a306705039563bb0f3673303a55688b9857305...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9435f1085584764b081177944033d4ed2cfd23ee	0xdf50fbde8180c8785842c8e316ebe06f542d3443	200618791871495612957
15613170	3	34	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x0d8b43d3739d7d28d4ff9cbf08454a6e609979dbdead...	0xca4556984e83346d371ef525e4df96746354fe322908...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xba12222222228d8ba445958a75a0704d566bf2c8	0xdf50fbde8180c8785842c8e316ebe06f542d3443	847083254783738283116

276957 rows × 9 columns

Get events from specific block range¶

In [5]:

events = await ctc.async_get_events(
    contract_address=contract_address,
    event_hash='0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
    verbose=False,
    start_block=14000000,
    end_block=14100000,
)

events

Out[5]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__from	arg__to	arg__value
block_number	transaction_index	log_index
14000000	0	25	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x9bff49171de27924fa958faf7b7ce605c1ff0fdee86f...	0x3dac2080b4c423029fcc9c916bc430cde441badfe736...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xbb2e5c2ff298fd96e166f90c8abacaf714df14f8	0x27239549dd40e1d60f5b80b0c4196923745b1fd2	58823967281975952181439
		28	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x9bff49171de27924fa958faf7b7ce605c1ff0fdee86f...	0x3dac2080b4c423029fcc9c916bc430cde441badfe736...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x27239549dd40e1d60f5b80b0c4196923745b1fd2	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	58823967281975952181439
14000003	60	62	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xcd22a09bfd8469b1925d9e19a74cd1c39e07d0806c4c...	0x1582ce5345df47d797d5b80c2cbb38ee0375b2875a61...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	73435661712369422675474
14000005	181	313	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x30cfbe428ed1968e1231798adf0b2ed6b07eeaaab627...	0xd09cf5bfab64ea8e01003ffbe5733e3eaf4f1eaa0f3d...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	0x9e2336aef4157944f201becd90ccb24e298660cb	14767355748583855822194
14000007	131	139	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x60fff3a3c4b64841f7ead1e4d8b4475fd0b82e79feb9...	0xdf6ef40edf4fd93945fad02033c9eef8445f4430d3d8...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	25820219943704516282552
...	...	...	...	...	...	...	...	...	...	...	...
14099877	158	264	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x1d7f74366a55c8ae48649bab4d1103cbfff27c3cba10...	0x9d6d8a7147e439efa1898a41bc4150b5edad338ead72...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0xad7575aefd4d64520c3269fd24eae1b0e13dbe7b	531497726956320332900
14099895	92	179	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x30e7fabe4aa9037c9fea24328586b2b8dfa6b87291d3...	0x17ec4301bc5bcc6198edb5883106b79220483c2ee216...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xdf50fbde8180c8785842c8e316ebe06f542d3443	0x220bda5c8994804ac96ebe4df184d25e5c2196d4	39986350026354596022200
		182	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x30e7fabe4aa9037c9fea24328586b2b8dfa6b87291d3...	0x17ec4301bc5bcc6198edb5883106b79220483c2ee216...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x220bda5c8994804ac96ebe4df184d25e5c2196d4	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	39986350026354596022200
14099898	83	173	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xb2ca06b6226be54c59ff3a47911b0e18e86e2d866a22...	0x5835247355b0797573934bef143ce26396d557c366df...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0xfad2a068f5765b7a3fdeef40f98beba5ed346839	24991357207226385107527
		177	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xb2ca06b6226be54c59ff3a47911b0e18e86e2d866a22...	0x5835247355b0797573934bef143ce26396d557c366df...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xfad2a068f5765b7a3fdeef40f98beba5ed346839	0xdf50fbde8180c8785842c8e316ebe06f542d3443	24972371054263013467815

11996 rows × 9 columns

Specify event timestamps¶

In [6]:

# query events over a specific time range

events = await ctc.async_get_events(
    contract_address=contract_address,
    event_hash='0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
    verbose=False,
    start_time='2021-01-01',
    end_time='2022-01-01',
)

events

Out[6]:

			block_hash	transaction_hash	contract_address	event_name	arg__from	arg__to	arg__value	address	event_hash
block_number	transaction_index	log_index
12168368	61	29	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	1302613195326042426081658189	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...
		32	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0x0000000000000000000000000000000000000000	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	1315770904369739824324907262	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...
		34	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	1315770904369739824324907262	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...
		42	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x0000000000000000000000000000000000000000	0	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...
		46	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	500000000000000000000	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...
...	...	...	...	...	...	...	...	...	...	...	...
13916105	136	288	0xfaffe0f4333160d4843875f613f2c305b9954d922a41...	0x13992e013aae7c7c12298d0d04f3c0f7821ccc26d1c3...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	60431153874598879800613	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...
13916130	95	294	0xdccb47f7c48fac79c3a3a25fe85be29b27da7df32d0a...	0xf3f8518c6dffbbfa98d7be53ef97af330f789159ce46...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xd8553552f8868c1ef160eedf031cf0bcf9686945	0x8639f60e8f9b984eaf62b0bd89f62d6161e182f9	11000000000000000000000	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...
13916150	121	270	0xe5720247372b46b2690ce3b7c22b70ec67cedc348b90...	0xa09e7d9a4e93be293a96eed9a4c33762eb77f8c8b00a...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xba12222222228d8ba445958a75a0704d566bf2c8	0x8bcf7e0ca3de9ec2637a76184eb746e844d2e2f6	8734901588905088209698	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...
	202	505	0xe5720247372b46b2690ce3b7c22b70ec67cedc348b90...	0xd6c36332d289c8d1cba11c63917392f2a1f665f8a386...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	0xf89ce5ed65737da8440411544b0499c9fad323b2	9052649229764771959302	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...
13916163	255	411	0x64d03ba946c50fe026034ff0b650371b2d55dcf7e789...	0x75ff937d6002c7fef42ba0244be91afd4073c84f55e6...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0x8639f60e8f9b984eaf62b0bd89f62d6161e182f9	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	11000000000000000000000	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...

183960 rows × 9 columns

In [7]:

# include block timestamps in output

events = await ctc.async_get_events(
    contract_address=contract_address,
    event_hash='0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
    verbose=False,
    start_time='2021-06-01',
    end_time='2021-06-02',
    include_timestamps=True,
)

events

Out[7]:

			timestamp	address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__from	arg__to	arg__value
block_number	transaction_index	log_index
12545224	11	28	1622505628	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x07f75ee169d207aa0ace5076ec062cbe7a2a28041b0d...	0x2b6a1ed787028fe44149d7d8af227176e25bf56e5600...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x4636650a4be0f6bfa226c31b537349e9d43df6c0	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	312396728160777272453828
12545238	72	131	1622505778	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x2a490f6f64d65dd0c5149b0569202fc6b3150ed0d6c7...	0x5b69c8489ef858798c918470d87f0de750f98013fe61...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xdf63be2e473ba04c26b1609e51d08cf0d78e0913	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	706291806832338833102925
	73	143	1622505778	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x2a490f6f64d65dd0c5149b0569202fc6b3150ed0d6c7...	0x31e0c09b21a629be1eb5253dccb38a76322a7fde53ef...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x8c54aa2a32a779e6f6fbea568ad85a19e0109c26	0x0000000089341e263b85d84a0eea39f47c37a9d2	29987500411601108523301
		146	1622505778	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x2a490f6f64d65dd0c5149b0569202fc6b3150ed0d6c7...	0x31e0c09b21a629be1eb5253dccb38a76322a7fde53ef...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000089341e263b85d84a0eea39f47c37a9d2	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	29987500411601108523301
12545241	0	1	1622505809	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xbb8722c65092712b36742f34dd4199846b6ed5917d3b...	0x5bdcbdf814281e7b25e26d7368779f5c2495e05071bd...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x5180545835bd68810fb7e11c7160bb7ea4ae8744	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	78336939301858730694074
...	...	...	...	...	...	...	...	...	...	...	...	...
12551643	2	7	1622591237	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x6034349536a447944a436bf71b357b0dcb9bb7cf39ca...	0x16cfa24ef00b2bceb5412bb847206a4a027ca4cd5cd3...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x8c54aa2a32a779e6f6fbea568ad85a19e0109c26	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	8643351664957109664094
12551657	9	20	1622591362	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x7477d41a8c513746371e96222b141d5e7226556d7567...	0x4e164d0531c321ba81835bb2d4daac19a667df8e4c5e...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x8c54aa2a32a779e6f6fbea568ad85a19e0109c26	0xfd3dfb524b2da40c8a6d703c62be36b5d8540626	1200029161280036122303287
		23	1622591362	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x7477d41a8c513746371e96222b141d5e7226556d7567...	0x4e164d0531c321ba81835bb2d4daac19a667df8e4c5e...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xfd3dfb524b2da40c8a6d703c62be36b5d8540626	0xc803698a4be31f0b9035b6eba17623698f3e2f82	1200029161280036122303287
12551679	4	17	1622591681	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x7f9e7bd6d750cd845206e2e1179765988f2d865e3ae9...	0x827905ca746061556c65e709aaae3acde7997fa19880...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	192589761774079078450234
12551685	0	3	1622591787	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x1ac9e7f913cbbde28ac816106863fd3f75ca909cb99b...	0x9a0126898a617db0f8d50d2c168488fa49e470a5bec5...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x8c54aa2a32a779e6f6fbea568ad85a19e0109c26	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	288849857323932058972006

933 rows × 10 columns

Reference

async ctc.evm.async_get_events(contract_address, *, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False, backend_order=None, keep_multiindex=True, verbose=True, provider=None, **query)

get events matching given inputs

Transactions

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

import ctc

In [2]:

transaction_hash = '0x6ff0860e202c61189cb2a3a38286bffd694acbc50577df6cb5a7ff40e21ea074'
address = '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'

Get transaction by hash¶

In [3]:

transaction = await ctc.async_get_transaction(transaction_hash)

transaction

Out[3]:

{'block_hash': '0xb7ae60b456f7733ae3d8bb927b03470eb662f0285f6c83d545b735c35634ede3',
 'block_number': 318528,
 'hash': '0x6ff0860e202c61189cb2a3a38286bffd694acbc50577df6cb5a7ff40e21ea074',
 'from': '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
 'gas': 530000,
 'gas_price': 50000000000,
 'input': '0x5a9809ed000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa960450000000000000000000000005ed8cee6b63b1c6afce3ad7c92f4fd7e1b8fad9f00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000001b48eb57e00000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000000010000000000000000000000001db3439a222c519ab44bb1144fc28167b4fa6ee600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
 'nonce': 0,
 'r': '0x76e2003e065da19c06351639b48624b7d7ac65c74c76370668d544dee730dd79',
 's': '0x4a25a8abc8e55a4c254d5019aea129bf02aee6e7a40438c26c83149719ade58f',
 'to': '0x7e2d0fe0ffdd78c264f8d40d19acb7d04390c6e8',
 'transaction_index': 1,
 'type': '0x0',
 'v': 27,
 'value': 120000000000000}

Get transaction count of address¶

In [4]:

transaction_count = await ctc.async_get_transaction_count(address)

transaction_count

Out[4]:

892

Get all transactions from address¶

In [5]:

transactions = await ctc.async_get_transactions_from_address(address)

transactions[0]

Out[5]:

{'block_hash': '0xb7ae60b456f7733ae3d8bb927b03470eb662f0285f6c83d545b735c35634ede3',
 'block_number': 318528,
 'hash': '0x6ff0860e202c61189cb2a3a38286bffd694acbc50577df6cb5a7ff40e21ea074',
 'from': '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
 'gas': 530000,
 'gas_price': 50000000000,
 'input': '0x5a9809ed000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa960450000000000000000000000005ed8cee6b63b1c6afce3ad7c92f4fd7e1b8fad9f00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000001b48eb57e00000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000000010000000000000000000000001db3439a222c519ab44bb1144fc28167b4fa6ee600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
 'nonce': 0,
 'r': '0x76e2003e065da19c06351639b48624b7d7ac65c74c76370668d544dee730dd79',
 's': '0x4a25a8abc8e55a4c254d5019aea129bf02aee6e7a40438c26c83149719ade58f',
 'to': '0x7e2d0fe0ffdd78c264f8d40d19acb7d04390c6e8',
 'transaction_index': 1,
 'type': '0x0',
 'v': 27,
 'value': 120000000000000}

Reference

async ctc.evm.async_get_transaction(transaction_hash)

get transaction

async ctc.evm.async_get_transaction_count(address)

get transaction count of address

Specific Protocols

ctc has functions for collecting and analyzing data from many on-chain and off-chain sources

4byte

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import fourbyte_utils

Query function signature¶

In [2]:

await fourbyte_utils.async_query_function_signatures('0x18160ddd')

Out[2]:

[{'id': 179,
  'created_at': '2016-07-09T03:58:45.230129Z',
  'hex_signature': '0x18160ddd',
  'text_signature': 'totalSupply()',
  'bytes_signature': '\x18\x16\rÝ'},
 {'id': 166702,
  'created_at': '2019-10-03T12:55:14.688679Z',
  'hex_signature': '0x18160ddd',
  'text_signature': 'voting_var(address,uint256,int128,int128)',
  'bytes_signature': '\x18\x16\rÝ'}]

Query event signature¶

In [3]:

event_hash = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'

await fourbyte_utils.async_query_event_signatures(event_hash)

Out[3]:

[{'id': 1,
  'created_at': '2020-11-30T22:38:00.801049Z',
  'hex_signature': '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
  'text_signature': 'Transfer(address,address,uint256)',
  'bytes_signature': 'ÝòR\xad\x1bâÈ\x9bi°hü7\x8dª\x95+§ñcÄ¡\x16(õZMõ#³ï'}]

Reference

async ctc.protocols.fourbyte_utils.async_build_event_signatures_dataset(signature_data=None)

Return type

None

async ctc.protocols.fourbyte_utils.async_build_function_signatures_dataset(signature_data=None)

Return type

None

async ctc.protocols.fourbyte_utils.async_query_event_signatures(hex_signature=None, *, id=None, bytes_signature=None, text_signature=None, use_local=True, use_remote=True)

Return type

Sequence[Entry]

async ctc.protocols.fourbyte_utils.async_query_function_signatures(hex_signature=None, *, id=None, bytes_signature=None, text_signature=None, use_local=True, use_remote=True)

Return type

Sequence[Entry]

Aave V2

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import aave_v2_utils

In [2]:

asset = '0x956f47f50a910163d8bf957cf5846d573e7f87ca'
pool_token = '0x683923db55fead99a79fa01a27eec3cb19679cc3'

Get pool token underlying asset¶

In [3]:

await aave_v2_utils.async_get_underlying_asset(pool_token=pool_token)

Out[3]:

'0x956f47f50a910163d8bf957cf5846d573e7f87ca'

Get interest rates¶

In [4]:

await aave_v2_utils.async_get_interest_rates(token=asset)

Out[4]:

{'supply_apr': 0.0,
 'supply_apy': 0.0,
 'borrow_apr': 0.47432923820762063,
 'borrow_apy': 0.606935956588601}

Get interest rates by block¶

In [5]:

blocks = [14000000, 14100000, 14200000]

await aave_v2_utils.async_get_interest_rates_by_block(asset, blocks=blocks)

Out[5]:

{'supply_apr': [0.0809241879131384, 0.13196183128104946, 0.08795041456240905],
 'supply_apy': [0.08428868956961622, 0.14106476861269135, 0.09193397621885202],
 'borrow_apr': [0.12384794470919762, 0.19833914841251457, 0.13425875687321126],
 'borrow_apy': [0.13184375504990453, 0.21937587033094874, 0.14368871521280768]}

Get reserve data information¶

In [6]:

await aave_v2_utils.async_get_reserve_data(asset)

Out[6]:

{'configuration': (184467950252545255676260,),
 'liquidity_index': 1053273089721002447096876573,
 'variable_borrow_index': 1083371393391169705567951230,
 'current_liquidity_rate': 0,
 'current_variable_borrow_rate': 474329238207620609074155595,
 'current_stable_borrow_rate': 454329238207620609074155595,
 'last_update_timestamp': 1664017295,
 'atoken_address': '0x683923db55fead99a79fa01a27eec3cb19679cc3',
 'stable_debt_token_address': '0xd89cf9e8a858f8b4b31faf793505e112d6c17449',
 'variable_debt_token_address': '0xc2e10006accab7b45d9184fcf5b7ec7763f5baae',
 'interest_rate_strategy_address': '0xf0ba2a8c12a2354c075b363765eae825619bd490',
 'id': 30}

Get reserve data information by block¶

In [7]:

blocks = [14000000, 14100000, 14200000]

await aave_v2_utils.async_get_reserve_data_by_block(asset, blocks=blocks)

Out[7]:

{'configuration': [(36893853501938873663488,),
  (36893853501938873663488,),
  (36893853547680668586888,)],
 'liquidity_index': [1027093192185602308632850363,
  1030957841716431311927096183,
  1034590546311825056817675224],
 'variable_borrow_index': [1040639071906878639807530852,
  1046590959580756373154811807,
  1052188787049286042548443674],
 'current_liquidity_rate': [80924187913138410537306359,
  131961831281049474271358767,
  87950414562409055280114949],
 'current_variable_borrow_rate': [123847944709197624729861055,
  198339148412514578291420400,
  134258756873211249157579590],
 'current_stable_borrow_rate': [103847944709197624729861055,
  178339148412514578291420400,
  114258756873211249157579590],
 'last_update_timestamp': [1642006170, 1643431118, 1644749395],
 'atoken_address': ['0x683923db55fead99a79fa01a27eec3cb19679cc3',
  '0x683923db55fead99a79fa01a27eec3cb19679cc3',
  '0x683923db55fead99a79fa01a27eec3cb19679cc3'],
 'stable_debt_token_address': ['0xd89cf9e8a858f8b4b31faf793505e112d6c17449',
  '0xd89cf9e8a858f8b4b31faf793505e112d6c17449',
  '0xd89cf9e8a858f8b4b31faf793505e112d6c17449'],
 'variable_debt_token_address': ['0xc2e10006accab7b45d9184fcf5b7ec7763f5baae',
  '0xc2e10006accab7b45d9184fcf5b7ec7763f5baae',
  '0xc2e10006accab7b45d9184fcf5b7ec7763f5baae'],
 'interest_rate_strategy_address': ['0xf0ba2a8c12a2354c075b363765eae825619bd490',
  '0xf0ba2a8c12a2354c075b363765eae825619bd490',
  '0xf0ba2a8c12a2354c075b363765eae825619bd490'],
 'id': [30, 30, 30]}

Get all deposits¶

In [8]:

deposits = await aave_v2_utils.async_get_deposits()

deposits

Out[8]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__reserve	arg__onBehalfOf	arg__referral	arg__user	arg__amount
block_number	transaction_index	log_index
11363052	76	126	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x8a1a55c5053a5deab69466e3ee92a2b147dddf62367f...	0x3081a4ac6666e748fee8bc216b86c47c91c43dfd1172...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2	0xc4a936b003bc223df757b35ee52f6da66b062935	0	0xdcd33426ba191383f1c9b431a342498fdac73488	100000000000000
11363059	168	243	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x48787c4adbf0e6cc34395003bbc0b23de154d85e490a...	0x6d18b83407c28345c8bb09f458b36cb4bbe0146e229d...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2	0xc4a936b003bc223df757b35ee52f6da66b062935	0	0xdcd33426ba191383f1c9b431a342498fdac73488	100000000000000
11367463	173	199	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x0432ed7d74339aa4e31420516af5e8b73125b6802093...	0x7f10004def891a9965e972e57ecb8b93c517b5d4d7e4...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9	0xdad4c11e8cc6a5c37808d3b31b3b284809f702d1	0	0xdad4c11e8cc6a5c37808d3b31b3b284809f702d1	100000000000000000
11367499	87	176	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x2037f971a8d3530b4f7aab4fdfefb99f98d535784afb...	0xdd1d259637c499ff61b0d142e7bb6639f3552b2dab37...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2	0xdad4c11e8cc6a5c37808d3b31b3b284809f702d1	0	0xdcd33426ba191383f1c9b431a342498fdac73488	1000000000000000
11367752	130	212	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0xe1ce4b8c2251d3f7a699f4eafe44cd06ee39bc2282f9...	0x870bf17a6373c10290d626134936230ada5f8ab0eee2...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2	0xbd723fc4f1d737dcfc48a07fe7336766d34cad5f	0	0xdcd33426ba191383f1c9b431a342498fdac73488	1000000000000000
...	...	...	...	...	...	...	...	...	...	...	...	...	...
15613442	219	556	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0xf1fc6712ffebf2a447c88bba3c9e59535cab89071e82...	0x2171e1c77ce1784b7011d6af7fd1cb8df09165eb6a29...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2	0x44bf2a060fee65ae23fd48f996dd742cd1c99cde	0	0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31	1300000000000000
15613446	53	210	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x11a8cb74b434c55684c37f6a2bc64ed5dd2eea1ae0d6...	0x58816da03db45ea9479886e360c17e78fa7d66cbe8eb...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0xc011a73ee8576fb46f5e1c5751ca3b9fe0af2a6f	0x0b5a6a15b975fd35f0b301748c8dabd35b50d8c5	0	0x0b5a6a15b975fd35f0b301748c8dabd35b50d8c5	27058755877323540610345
15613449	158	356	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x596fd05e6569e0c3de6a396144cad0f07966578e423e...	0x56d420bcb1dfaad69e4dffdf50c3355a51d7226c1207...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0x514910771af9ca656af840dff83e8264ecf986ca	0x72cf204877ed7fc3c31b87052fb4975b2efda940	3228	0x72cf204877ed7fc3c31b87052fb4975b2efda940	110605874591292246906
15613454	153	414	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x85dac8e6245651bf1d58c56609b94f89e18e97e5b384...	0x5f258542d5936014d593fde265308f78c4758bd926e8...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2	0x9ef1e5eea13131065d64e53a0595ea487746324a	0	0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31	10000000000000000
15613477	131	239	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0xa2ac32e37c661b1f74edf8c3174f2255ea7f50709092...	0x65c4a31c653ac2fc3c236d9634061aaa8863a697a39c...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Deposit	0xde6857219544bb5b7746f48ed30be6386fefc61b2f86...	0xc011a73ee8576fb46f5e1c5751ca3b9fe0af2a6f	0xc203f88cc0fcff70cbca89a28a5d1233c2cdbfe5	187	0xc203f88cc0fcff70cbca89a28a5d1233c2cdbfe5	24000000000000000000

352005 rows × 11 columns

Get all withdrawals¶

In [9]:

withdrawals = await aave_v2_utils.async_get_withdrawals()

withdrawals

Out[9]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__reserve	arg__user	arg__to	arg__amount
block_number	transaction_index	log_index
11367541	136	174	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0xcb87fe175f68c53964d24fff4c816224b520096ae697...	0x0c66ade8a26d0bedbc967005a75a00028cebf222ec45...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2	0xdcd33426ba191383f1c9b431a342498fdac73488	0xdcd33426ba191383f1c9b431a342498fdac73488	1000000000000000
11367770	247	230	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x83dfe27b0b320c18d1b6e4adf476f93f107c8bcc2d68...	0x25f636e7b49a599c765bcdac00853265ac76a5921953...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2	0xdcd33426ba191383f1c9b431a342498fdac73488	0xdcd33426ba191383f1c9b431a342498fdac73488	1000000000000000
11367843	117	126	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x3e856a21671d901986c62b5c901ba34373d87919386e...	0x17869b1999e221cb74ab4fc8c9f7087097e6e27b50dd...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0x6b175474e89094c44da98b954eedeac495271d0f	0xbd723fc4f1d737dcfc48a07fe7336766d34cad5f	0xbd723fc4f1d737dcfc48a07fe7336766d34cad5f	1000000000000000000
11373144	23	22	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x28f08c556d03b17932612a6497f7b643fe2980ca7a25...	0xae1083a26ffc90a681fc856b9bb087e37a16c037227a...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2	0xbd723fc4f1d737dcfc48a07fe7336766d34cad5f	0xbd723fc4f1d737dcfc48a07fe7336766d34cad5f	1000000000000000
11373481	159	279	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x0452e1d1eabafdd24668694d1bd4cb09b6c399fb04b9...	0xd12cbbad05aa4b7dbcf62ee862bf07c73ddfca58f035...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0x514910771af9ca656af840dff83e8264ecf986ca	0xff06ed0e20638f1299832b4141bc3adcc82f6207	0xff06ed0e20638f1299832b4141bc3adcc82f6207	73858303958775353
...	...	...	...	...	...	...	...	...	...	...	...	...
15613399	192	391	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x829110668a9d166b451a915c015db8f4014f293ab032...	0xf8aecf2c24286caeb574121135e3fb52ac32d8df0879...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0x514910771af9ca656af840dff83e8264ecf986ca	0x68b48bca2f5955df6af945bb71814edda5243712	0x68b48bca2f5955df6af945bb71814edda5243712	369688503364124390545
	223	465	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x829110668a9d166b451a915c015db8f4014f293ab032...	0xfe53d46dd1564ddc464bb303a0e248d15a9827c69ffb...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0xd533a949740bb3306d119cc777fa900ba034cd52	0x166b1948124307729a7ce48c3c336a5910598435	0x166b1948124307729a7ce48c3c336a5910598435	16816268189066430697221
15613408	58	200	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x167a50c67364fa82ea4f95366460309d7eddbaee1675...	0x6988276e3b5b640c3445c15cbd96b4f4c27633b9c066...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0xae7ab96520de3a18e5e111b5eaab095312d7fe84	0xa270f988e2dac7be0b1c86ae010e3f823a5a5e92	0xa270f988e2dac7be0b1c86ae010e3f823a5a5e92	20000000000000000000
15613449	158	336	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x596fd05e6569e0c3de6a396144cad0f07966578e423e...	0x56d420bcb1dfaad69e4dffdf50c3355a51d7226c1207...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48	0x72cf204877ed7fc3c31b87052fb4975b2efda940	0x72cf204877ed7fc3c31b87052fb4975b2efda940	865000000
15613466	576	311	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	0x6a9c65ba299149b5f2fe71f31b1dcc921228cc599355...	0x5d2a2244822f396ac9b5dda70bb1d3a08dd6409d7f90...	0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9	Withdraw	0x3115d1449a7b732c986cba18244e897a450f61e1bb8d...	0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48	0x9ef1e5eea13131065d64e53a0595ea487746324a	0x9ef1e5eea13131065d64e53a0595ea487746324a	100000000

252266 rows × 10 columns

Reference

async ctc.protocols.aave_v2_utils.async_get_deposits(*, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False, provider=None)

async ctc.protocols.aave_v2_utils.async_get_interest_rates(*, token=None, block=None, reserve_data=None)

async ctc.protocols.aave_v2_utils.async_get_interest_rates_by_block(token, blocks, *, reserve_data_by_block=None)

async ctc.protocols.aave_v2_utils.async_get_reserve_data(asset, block=None, *, provider=None)

async ctc.protocols.aave_v2_utils.async_get_reserve_data_by_block(asset, blocks, *, provider=None)

async ctc.protocols.aave_v2_utils.async_get_underlying_asset(pool_token, provider=None)

async ctc.protocols.aave_v2_utils.async_get_withdrawals(*, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False, provider=None)

Balancer

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import balancer_utils

In [2]:

pool_id = '0xc35bdda2e93c401c6645e0d8a0b2c86906c51710000200000000000000000111'
pool_address = '0xc35bdda2e93c401c6645e0d8a0b2c86906c51710'

Get pool metadata¶

In [3]:

await balancer_utils.async_get_pool_address(pool_id)

Out[3]:

'0xc35bdda2e93c401c6645e0d8a0b2c86906c51710'

In [4]:

await balancer_utils.async_get_pool_id(pool_address)

Out[4]:

'0xc35bdda2e93c401c6645e0d8a0b2c86906c51710000200000000000000000111'

In [5]:

await balancer_utils.async_get_pool_tokens(pool_address=pool_address)

Out[5]:

['0x956f47f50a910163d8bf957cf5846d573e7f87ca',
 '0xc7283b66eb1eb5fb86327f08e1b5816b0720212b']

In [6]:

await balancer_utils.async_get_pool_fees(pool_address=pool_address)

Out[6]:

0.003

Get pool weights¶

In [7]:

await balancer_utils.async_get_pool_weights(pool_address=pool_address)

Out[7]:

{'0x956f47f50a910163d8bf957cf5846d573e7f87ca': 0.10000762951094835,
 '0xc7283b66eb1eb5fb86327f08e1b5816b0720212b': 0.9000076295109484}

Get pool weights over time¶

In [8]:

blocks = [13900000, 14000000, 14100000, 14200000]

await balancer_utils.async_get_pool_weights_by_block(
    pool_address=pool_address, blocks=blocks
)

Out[8]:

{13900000: [0.4740023386036203, 0.5260129205271249],
 14000000: [0.378524825351098, 0.6214904337518591],
 14100000: [0.2143885819218613, 0.7856266771333252],
 14200000: [0.10000762951094835, 0.9000076295109484]}

Get pool balances¶

In [9]:

await balancer_utils.async_get_pool_balances(pool_address=pool_address)

Out[9]:

{'0x956f47f50a910163d8bf957cf5846d573e7f87ca': 5.6968e-14,
 '0xc7283b66eb1eb5fb86327f08e1b5816b0720212b': 2.181534e-12}

Get pool summary¶

In [10]:

await balancer_utils.async_summarize_pool_state(pool_address=pool_address)

Out[10]:

{'pool_tokens': ['0x956f47f50a910163d8bf957cf5846d573e7f87ca',
  '0xc7283b66eb1eb5fb86327f08e1b5816b0720212b'],
 'pool_fees': 0.003,
 'pool_weights': {'0x956f47f50a910163d8bf957cf5846d573e7f87ca': 0.10000762951094835,
  '0xc7283b66eb1eb5fb86327f08e1b5816b0720212b': 0.9000076295109484},
 'pool_balances': {'0x956f47f50a910163d8bf957cf5846d573e7f87ca': 5.6968e-14,
  '0xc7283b66eb1eb5fb86327f08e1b5816b0720212b': 2.181534e-12},
 'block': 15613495}

Get pool swaps¶

In [11]:

swaps = await balancer_utils.async_get_pool_swaps(pool_address=pool_address)

swaps

Out[11]:

			block_hash	transaction_hash	contract_address	event_name	arg__poolId	arg__tokenIn	arg__tokenOut	arg__amountIn	arg__amountOut	address	event_hash
block_number	transaction_index	log_index
13875964	204	312	0xee9f76842a8564480f150c8564baa42fa251fcdeb04e...	0x0b09e9be1e29d6784f1ec65b02e2a33e189d4dc8fddb...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	9282037308505057802273	8862947236144171799780	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...
13876219	130	155	0x80c1942ea8f77e4c7efeacfe8faa695f013ac194dfec...	0xedaa5fa750337f247e955e753341d1c6bee8f4a58ce6...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	0x956f47f50a910163d8bf957cf5846d573e7f87ca	6770515949298292329779	7425664489255906163987	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...
13876260	152	199	0xb4bd4ec34dca399c3550d0a022ad4239bd35de7da96f...	0x4f18f6cb47daf4f18efcea52f1cac7f37e5795a4d1d7...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	0x956f47f50a910163d8bf957cf5846d573e7f87ca	14130662641515379930887	15214927899208771740928	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...
13876558	263	498	0x2417372e1cb5569d55524d5a74948d96add4396d34ba...	0x150eaf7b7271da325fa067c6512fb16b681c6b03d2cf...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	0x956f47f50a910163d8bf957cf5846d573e7f87ca	14181099804346772686440	15589833329021211807661	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...
13876669	124	219	0x7b78aa102ae489e65aadc43aa36a0405c74136166cc0...	0x0f467d14428523705970c40c9f6a6a0767518c8b0ca2...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	0x956f47f50a910163d8bf957cf5846d573e7f87ca	93485409984034479616	103028232766980855821	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...
...	...	...	...	...	...	...	...	...	...	...	...	...	...
15423403	2	4	0x00048c148422b390b2f78f8a0a46854e502162c17344...	0x57b9735a44b5de014a3e69f0e8a564b0ac248343a800...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	0x956f47f50a910163d8bf957cf5846d573e7f87ca	4033490073421730937398	911931499638810770275	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...
15423473	5	24	0x742c397c1044d8c4b1c82e8b3097c58f22380251d03a...	0x2a0f16fb89fa69e690d4ac132f01a468f258971db432...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	918429602325991972769	4037765462202588666117	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...
15423526	2	12	0x32c4a753e8322eeb8e887be865f4a907dcd398c7fbbb...	0xe88deeffe0387b8518eee1a2512157b121b0e9c23bae...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	1171187367098000834500	5042903288618799623107	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...
15424132	105	30	0x2227c1e1ff4809206ca56539da601e7eebfd9e862983...	0x8b506c15a6029dbe41284efed0b792c2a5946129888b...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	1142575013928542396992	4809610304432969625612	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...
15431183	7	51	0xa280533250c08f73d67781dd7be203b27d4ef711f3bb...	0xacd745a361c67cfed48bb747b363c8323d6c15180c3a...	0xba12222222228d8ba445958a75a0704d566bf2c8	Swap	0xc35bdda2e93c401c6645e0d8a0b2c86906c517100002...	0xc7283b66eb1eb5fb86327f08e1b5816b0720212b	0x956f47f50a910163d8bf957cf5846d573e7f87ca	4125429707992706735197	975778707613648542701	0xba12222222228d8ba445958a75a0704d566bf2c8	0x2170c741c41531aec20e7c107c24eecfdd15e69c9bb0...

1680 rows × 11 columns

Reference

async ctc.protocols.balancer_utils.async_get_pool_address(pool_id, block=None)

async ctc.protocols.balancer_utils.async_get_pool_balances(*, pool_address=None, pool_id=None, block=None, vault=None, normalize=True, provider=None)

async ctc.protocols.balancer_utils.async_get_pool_fees(pool_address, *, block='latest', normalize=True)

async ctc.protocols.balancer_utils.async_get_pool_id(pool_address, block=None, *, provider=None)

async ctc.protocols.balancer_utils.async_get_pool_swaps(pool_address=None, *, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False)

async ctc.protocols.balancer_utils.async_get_pool_tokens(*, pool_address=None, pool_id=None, block=None)

async ctc.protocols.balancer_utils.async_get_pool_weights(pool_address, block='latest', *, normalize=True)

async ctc.protocols.balancer_utils.async_get_pool_weights_by_block(pool_address, blocks, *, normalize=True)

async ctc.protocols.balancer_utils.async_summarize_pool_state(pool_address, block='latest')

Chainlink

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import chainlink_utils

In [2]:

feed = 'ETH_USD'

Get feed address¶

In [3]:

await chainlink_utils.async_resolve_feed_address(feed)

Out[3]:

'0x5f4ec3df9cbd43714fe2740f5e3616155c5b8419'

Get current value of feed¶

In [4]:

await chainlink_utils.async_get_feed_datum(feed)

Out[4]:

1295.91

Get historical values of a feed¶

In [5]:

feed_data = await chainlink_utils.async_get_feed_data(feed)

feed_data

Out[5]:

block_number
10606572         399.33
10606572         399.37
10606572         399.33
10606573         399.37
10606573         399.33
               ...     
15613216        1287.27
15613248    1273.925028
15613287    1280.742804
15613305    1288.935935
15613347        1295.91
Name: answer, Length: 237563, dtype: object

Get interpolated historical values of a feed¶

In [6]:

feed_data = await chainlink_utils.async_get_feed_data(feed, interpolate=True)

feed_data

Out[6]:

block_number
10606572     399.330
10606573     399.320
10606574     399.325
10606575     399.320
10606576     399.320
              ...   
15613492    1295.910
15613493    1295.910
15613494    1295.910
15613495    1295.910
15613496    1295.910
Name: answer, Length: 5006925, dtype: float64

Get feed aggregator history¶

In [7]:

await chainlink_utils.async_get_feed_previous_aggregators(feed)

Out[7]:

['0xf79d6afbb6da890132f9d7c355e3015f15f3406f',
 '0xb103ede8acd6f0c106b7a5772e9d24e34f5ebc2c',
 '0x00c7a37b03690fb9f41b5c5af8131735c7275446',
 '0xd3fcd40153e56110e6eeae13e12530e26c9cb4fd',
 '0x37bc7498f4ff12c19678ee8fe19d713b87f6a9e6']

In [8]:

# blocks where aggregators updated

await chainlink_utils.async_get_feed_aggregator_history(feed)

Out[8]:

{'0xf79d6afbb6da890132f9d7c355e3015f15f3406f': 10606501,
 '0xb103ede8acd6f0c106b7a5772e9d24e34f5ebc2c': 10607120,
 '0x00c7a37b03690fb9f41b5c5af8131735c7275446': 11008985,
 '0xd3fcd40153e56110e6eeae13e12530e26c9cb4fd': 12187957,
 '0x37bc7498f4ff12c19678ee8fe19d713b87f6a9e6': 12453813}

Reference

async ctc.protocols.chainlink_utils.async_print_feed_summary(feed, *, start_block=None, n_recent=None, verbose=False)

Compound

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import compound_utils

In [2]:

ctoken = '0x35a18000230da775cac24873d00ff85bccded550'

Get supply APY¶

In [3]:

await compound_utils.async_get_supply_apy(ctoken)

Out[3]:

0.003777415895703129

Get borrow APY¶

In [4]:

await compound_utils.async_get_borrow_apy(ctoken)

Out[4]:

0.05932247119699485

Get supply APY by block¶

In [5]:

blocks = [14000000, 14100000, 14200000]

await compound_utils.async_get_supply_apy_by_block(ctoken, blocks=blocks)

Out[5]:

[0.0015700051686593497, 0.002428224167829729, 0.0017380529006516543]

Get borrow APY by block¶

In [6]:

blocks = [14000000, 14100000, 14200000]

await compound_utils.async_get_borrow_apy_by_block(ctoken, blocks=blocks)

Out[6]:

[0.04338541891628256, 0.050325319640804, 0.04485273411875479]

Reference

async ctc.protocols.compound_utils.async_get_borrow_apy(ctoken, block=None)

async ctc.protocols.compound_utils.async_get_borrow_apy_by_block(ctoken, blocks)

async ctc.protocols.compound_utils.async_get_supply_apy(ctoken, block=None)

async ctc.protocols.compound_utils.async_get_supply_apy_by_block(ctoken, blocks)

Gnosis Safe

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

[Examples coming soon]¶

Curve

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import curve_utils

In [2]:

factory_pool = '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655'

Get pool metadata¶

In [3]:

await curve_utils.async_get_pool_metadata(pool=factory_pool)

Out[3]:

{'token_addresses': ['0x956f47f50a910163d8bf957cf5846d573e7f87ca',
  '0x6c3f90f043a72fa612cbac8115ee7e52bde6e490'],
 'token_symbols': ['FEI', '3Crv'],
 'token_decimals': [18, 18],
 'A': 100}

Get pool state¶

In [4]:

await curve_utils.async_get_pool_state(pool=factory_pool)

Out[4]:

{'lp_total_supply': 1545685.4540038493,
 'token_balances': [782894.7941072898, 754331.3786528307],
 'A': 100}

Get pool state in a specific block¶

In [5]:

await curve_utils.async_get_pool_state(pool=factory_pool, block=14000000)

Out[5]:

{'lp_total_supply': 253036543.47482586,
 'token_balances': [126538335.35590503, 124462159.0647215],
 'A': 10}

Get virtual price¶

In [6]:

await curve_utils.async_get_virtual_price(pool=factory_pool)

Out[6]:

1005085631967785180

Get base pools¶

In [7]:

await curve_utils.async_get_base_pools()

Out[7]:

			factory	transaction_hash	pool
block_number	transaction_index	log_index
12904539	152	213	0xb9fc157394af804a3578134a6585c0dc9cc990d4	0xedfeb49642fb5c9f2220bbf3eddca5a3ef50a68713b8...	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7
12904585	85	220	0xb9fc157394af804a3578134a6585c0dc9cc990d4	0xcb6be4a26a2c224a32bad4fc9ba88652be0235dc82d5...	0x7fc77b5c7614e1533320ea6ddc2eb61fa00a9714
13495769	105	194	0xb9fc157394af804a3578134a6585c0dc9cc990d4	0xad288f471da6aca0625173e19030d80f3e02e4d736da...	0x93054188d876f558f4a66b2ef1d97d16edf0895b
15038268	13	26	0xb9fc157394af804a3578134a6585c0dc9cc990d4	0x7396aaa9548e8b67e85d9c39bac86becdd0f6bcb80d2...	0xdcef968d416a41cdac0ed8702fac8128a64241a2

Get meta pools¶

In [8]:

await curve_utils.async_get_meta_pools()

Out[8]:

			transaction_hash	factory	coin	base_pool	A	fee	deployer
block_number	transaction_index	log_index
11955325	16	25	0xfcf2e192b7fe9e094a111e7df4c00bef20af78056278...	0x0959158b6040d32d04c301a72cbfd6b39e21c9ae	0x865377367054516e17014ccded1e7d814edc9ce4	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	10	4000000	0x3fcb35a1cbfb6007f9bc638d388958bc4550cb28
11955333	61	73	0x298f34b7b6c496352effba8fdb91f5249e1cfbee24d9...	0x0959158b6040d32d04c301a72cbfd6b39e21c9ae	0xbc6da0fe9ad5f3b0d58160288917aa56653660e9	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	60	4000000	0xef422dbbf46120de627ffb913c9afad44c735618
11968730	110	187	0x1f2a0d4e1c1eca594bd7f27f9952480ccda422c3453e...	0x0959158b6040d32d04c301a72cbfd6b39e21c9ae	0x853d955acef822db058eb8505911ed77f175b99e	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	100	4000000	0x234d953a9404bf9dbc3b526271d440cd2870bcd2
11975574	213	33	0x4aeacf4bf11becac10f2bfbe3319e182af520927c91f...	0x0959158b6040d32d04c301a72cbfd6b39e21c9ae	0xa774ffb4af6b0a91331c084e1aebae6ad535e6f3	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	200	4000000	0x60cc20c5ff95cc46b4ed606d940f657ad054c309
11976084	132	152	0xd1db8f97364aed51707e7ec7abf158d43627b75decdc...	0x0959158b6040d32d04c301a72cbfd6b39e21c9ae	0x71df9dd3e658f0136c40e2e8ec3988a5226e9a67	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	200	4000000	0x60cc20c5ff95cc46b4ed606d940f657ad054c309
...	...	...	...	...	...	...	...	...	...
15533460	103	158	0x8a22bb0e79e20ce8df95ffe8a1aa139042c1f990d88a...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	0x0bc529c00c6401aef6d220be8c6ea1667f6ad93e	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	10	4000000	0x3ad578af2e96aad62088dc0b4350e1e3a7c7c1c3
15533481	45	64	0x84e9ab1f02821166c92643c1bf040b4de249c491af5d...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	0x0bc529c00c6401aef6d220be8c6ea1667f6ad93e	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	10	4000000	0x3ad578af2e96aad62088dc0b4350e1e3a7c7c1c3
15563580	58	104	0x1b3c187bbca6f8e7857d8a9485438705854e84c47ff5...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	0x3236a63c21fc524a51001ea2627697fdca86e897	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	10	98000000	0x34e2f0c6775afd9e8daf1dbc05194884e22721cd
15567683	128	138	0x939fb60fb569f88d0a692b148616c6e600a3699f6f12...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	0x3236a63c21fc524a51001ea2627697fdca86e897	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	10	100000000	0x34e2f0c6775afd9e8daf1dbc05194884e22721cd
15567841	236	446	0x3428bd9d19faaa9cc9719d42348b35077ab47a07f6be...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	0x3236a63c21fc524a51001ea2627697fdca86e897	0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7	10	100000000	0x34e2f0c6775afd9e8daf1dbc05194884e22721cd

199 rows × 7 columns

Get plain pools¶

In [9]:

await curve_utils.async_get_plain_pools()

Out[9]:

			transaction_hash	factory	coins	A	fee	deployer
block_number	transaction_index	log_index
12913531	22	37	0x024843f829ec485c27acb115f94d5374c19f14301ceb...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0x96e61422b6a9ba0e068b6c5add4ffabc6a4aae27',...	100	4000000	0xb424338eaa86953d82b5fabf042ce2eac544c043
12914704	169	31	0x471bb1cbfbca89c98ecc0eb3e00328c41c7e5d5d8490...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0xc581b735a1688071a1746c968e0798d642ede491',...	100	4000000	0x7eeac6cddbd1d0b8af061742d41877d7f707289a
12925098	158	233	0x177b4b07b92004c80b773e66ea3257c12ded04df5311...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0x95dfdc8161832e4ff7816ac4b6367ce201538253',...	100	4000000	0x2d407ddb06311396fe14d4b49da5f0471447d45c
12931794	112	106	0x2aa30ad95aa6b05c09c82320844d515a76bb5575639c...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0x96e61422b6a9ba0e068b6c5add4ffabc6a4aae27',...	100	4000000	0x2d407ddb06311396fe14d4b49da5f0471447d45c
12983315	221	310	0x0c9d012f02f83046b4556fe7e2d4d9a90888c4e966e2...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0xd38aeb759891882e78e957c80656572503d8c1b1',...	100	4000000	0xd3b74abc95169b9c183409218c3d0fbff4ae67ee
...	...	...	...	...	...	...	...	...
15415514	314	634	0xc80f1a8b853b54ed9eb73e879df9459b8aa0a14c6914...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0x4104b135dbc9609fc1a9490e61369036497660c8',...	10	4000000	0x22169e0694de4a74133bd06f01857556408f2ba2
15459059	214	267	0x2beeb915f6bfea7cc68722034694ebf813ceb1410f37...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0x0ec9f76202a7061eb9b3a7d6b59d36215a7e37da',...	10	4000000	0xb46bc1f36fc6482b540a3fc810c7dc7dd8ef512b
15499736	198	327	0x5951cb96a72043fe4be9632591bc706c9a7edb4569b6...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',...	100	4000000	0x5180db0237291a6449dda9ed33ad90a38787621c
15528387	123	210	0xdd3619f6a6ab1243db8683ab2d4685c0a3395e027d46...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0xd533a949740bb3306d119cc777fa900ba034cd52',...	50	15000000	0x0b634a8d61b09820e9f72f79cdcbc8a4d0aad26b
15532321	37	35	0xffd44e65bce7d268a793d06ff62a9aa31e2f606c174b...	0xb9fc157394af804a3578134a6585c0dc9cc990d4	('0x8d6cebd76f18e1558d4db88138e2defb3909fad6',...	500	4000000	0xad95a5fe898679b927c266eb2edfabc7fe268c27

87 rows × 6 columns

Reference

async ctc.protocols.curve_utils.async_get_base_pools(*, start_block=None, end_block=None, start_time=None, end_time=None, factory=None, provider=None, verbose=False)

async ctc.protocols.curve_utils.async_get_meta_pools(*, start_block=None, end_block=None, start_time=None, end_time=None, factory=None, provider=None, verbose=False)

async ctc.protocols.curve_utils.async_get_plain_pools(*, factory=None, start_block=None, end_block=None, start_time=None, end_time=None, provider=None, verbose=False)

async ctc.protocols.curve_utils.async_get_pool_metadata(pool, *, n_tokens=None, provider=None)

async ctc.protocols.curve_utils.async_get_pool_state(pool, *, n_tokens=None, block=None, provider=None, normalize=True)

async ctc.protocols.curve_utils.async_get_virtual_price(pool, *, provider=None, block=None)

Gnosis Safe

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

[Examples coming soon]¶

ENS

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import ens_utils

In [2]:

address = '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
name = 'vitalik.eth'

Get owner of ENS name¶

In [3]:

await ens_utils.async_get_owner(name)

Out[3]:

'0xd8da6bf26964af9d7eed9e03e53415d37aa96045'

Reverse lookup of ENS address¶

In [4]:

await ens_utils.async_reverse_lookup(address)

Out[4]:

'vitalik.eth'

Get whether name record exists¶

In [5]:

await ens_utils.async_record_exists(name)

Out[5]:

True

Get hash of ENS name¶

In [6]:

ens_utils.hash_name(name)

Out[6]:

'0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835'

Get text records of ENS name¶

In [7]:

await ens_utils.async_get_text_records(name='foda.eth')

Out[7]:

{'email': 'foda@hey.com',
 'url': 'https://just.is/foda',
 'com.twitter': '0xFoda',
 'avatar': 'eip155:1/erc721:0xe9edc636c70d2104df2a9d7444c94676fcbfe07f/0',
 'description': 'ⓕ™',
 'com.github': '',
 'com.instagram': 'https://instagram.com/foda.farm',
 'color': '#f0da91',
 'eth.ens.delegate': 'https://discuss.ens.domains/t/ens-dao-delegate-applications/815/765?u=foda',
 'snapshot': 'ipns://storage.snapshot.page/registry/0xF75Ed978170dFa5ee3d71d95979a34C91CD7042e/foda.eth'}

Get ENS name expiration¶

In [8]:

timestamp = await ens_utils.async_get_expiration(name)

timestamp

Out[8]:

2030347728

Get all registrations¶

In [9]:

registrations = await ens_utils.async_get_registrations()

registrations

Out[9]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__label	arg__owner	arg__parent_node
block_number	transaction_index	log_index
9380415	22	33	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0xa1cae6357f471b005baa1065cd5631cfae9e0587c4aa...	0x36a8544bc597d7d74ca66c118345e500cfc1dca0dbac...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0x4f5b812789fc606be1b3b16908db13fc7a9adf7ca726...	0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85	0x00000000000000000000000000000000000000000000...
9380428	34	21	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0x1191aa09f8d699c4cdc64efc64e9601034c9ace73217...	0x1842da220ed4eaf0ed21d5366ee800251feffbd1d281...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0x7926fb9208a20417f0b848065c6fe289da455821d6fc...	0x0904dac3347ea47d208f3fd67402d039a3b99859	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f...
9380515	7	7	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0x11493f7456a83455b3fbf09ba6c4eb5d01455c2d8741...	0x6f410b83a468197dd0de7eb31e3f18fcfe6bf961080f...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0xdec08c9dbbdd0890e300eb5062089b2d4b1c40e3673b...	0x4fe4e666be5752f1fdd210f4ab5de2cc26e3e0e8	0x00000000000000000000000000000000000000000000...
9380516	58	44	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0xb7106125148bd4b2e04af5c3fea3cec8cabf52f83e2d...	0x7311cdefc63aaf6226110ec9d682714f878ebdc115d0...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0xe5e14487b78f85faa6e1808e89246cf57dd34831548f...	0x084b1c3c81545d370f3634392de611caabff8148	0xa097f6721ce401e757d1223a763fef49b8b5f90bb185...
9380533	12	8	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0x425b28e5b1d989e3f6f7392d6556d00aa08aed6a8c1f...	0xf296f9b8d5143c6fca65b010cb9d621d0574dca1950b...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0x9dd2c369a187b4e6b9c402f030e50743e619301ea62a...	0xa2f428617a523837d4adc81c67a296d42fd95e86	0x00000000000000000000000000000000000000000000...
...	...	...	...	...	...	...	...	...	...	...	...
15613497	119	434	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0x3c6be87de804a10a95226e765a3af66b65d153229d22...	0xe15819ba8c67ac670bb58a6f9f62cf0a8c97dd58ead0...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0x8dc3f00834cd7dddee71f38756fba634206001225cad...	0xdc8feb4a071011ff903e87b55da4ac898cce607a	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f...
		438	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0x3c6be87de804a10a95226e765a3af66b65d153229d22...	0xe15819ba8c67ac670bb58a6f9f62cf0a8c97dd58ead0...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0xdd8cc1a54081e49db8115d5a2b804a45731328419b55...	0xdc8feb4a071011ff903e87b55da4ac898cce607a	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f...
		442	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0x3c6be87de804a10a95226e765a3af66b65d153229d22...	0xe15819ba8c67ac670bb58a6f9f62cf0a8c97dd58ead0...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0x264b517bb73fd766faff58728ce986c72d24259038af...	0xdc8feb4a071011ff903e87b55da4ac898cce607a	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f...
		446	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0x3c6be87de804a10a95226e765a3af66b65d153229d22...	0xe15819ba8c67ac670bb58a6f9f62cf0a8c97dd58ead0...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0x00d8aa131570d0b5c1dc83a87348b1ade3eb91c68d9f...	0xdc8feb4a071011ff903e87b55da4ac898cce607a	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f...
		450	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	0x3c6be87de804a10a95226e765a3af66b65d153229d22...	0xe15819ba8c67ac670bb58a6f9f62cf0a8c97dd58ead0...	0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e	NewOwner	0xce0457fe73731f824cc272376169235128c118b49d34...	0x2ee451b1258b2f89e0acf766e78ba9115866718cd8df...	0xdc8feb4a071011ff903e87b55da4ac898cce607a	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f...

5190069 rows × 9 columns

Get block number of when ENS name was registered¶

In [10]:

await ens_utils.async_get_registration_block(name)

Out[10]:

9430706

Reference

async ctc.protocols.ens_utils.async_get_expiration(name)

Return type

int

async ctc.protocols.ens_utils.async_get_owner(name, *, provider=None, block=None)

async ctc.protocols.ens_utils.async_get_registration_block(name)

Return type

int

async ctc.protocols.ens_utils.async_get_registrations()

async ctc.protocols.ens_utils.async_get_text_records(*, name=None, node=None, keys=None)

https://docs.ens.domains/ens-improvement-proposals/ensip-5-text-records

Return type

dict[str, str]

async ctc.protocols.ens_utils.async_record_exists(name, *, provider=None, block=None)

async ctc.protocols.ens_utils.async_reverse_lookup(address, *, provider=None, block=None)

ctc.protocols.ens_utils.hash_name(name)

Fei

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import fei_utils

Get PCV stats¶

In [2]:

pcv_stats = await fei_utils.async_get_pcv_stats()

pcv_stats

Out[2]:

{'pcv': 59598260820495064263161827,
 'user_fei': 58131106108824886492750185,
 'protocol_equity': 1467154711670177770411642,
 'valid': True}

Get PCV stats in a specific block¶

In [3]:

pcv_stats = await fei_utils.async_get_pcv_stats(block=14000000)

pcv_stats

Out[3]:

{'pcv': 782812519953585480931863885,
 'user_fei': 321723324105548204271934214,
 'protocol_equity': 461089195848037276659929671,
 'valid': True}

Print PCV asset summary¶

In [4]:

await fei_utils.async_print_pcv_assets()

┌────────────────┐
│ Fei PCV Assets │
└────────────────┘

total $59.60M

  asset  │   amount  │      price  │     total  
─────────┼───────────┼─────────────┼────────────
   LUSD  │        0  │      $1.03  │     $0.00  
   WETH  │   230.71  │  $1,287.97  │  $297.15K  
    DAI  │   58.13M  │      $1.00  │   $58.11M  
    BAL  │  226.44K  │      $5.26  │    $1.19M  

Print PCV deposit summary¶

In [5]:

await fei_utils.async_print_pcv_deposits()

┌──────────────────┐
│ FEI PCV Deposits │
└──────────────────┘

  asset  │    balance  │               name  │                                     address  
─────────┼─────────────┼─────────────────────┼──────────────────────────────────────────────
   LUSD  │      $0.00  │                     │  0x4378de2f2991fbed6616b34ac7727e7653713712  
   WETH  │      $0.00  │                     │  0xc6d675ca5217d39c3a5e366141060fc2d1ea2b82  
   WETH  │  $1.85e-13  │                     │  0xf24401f6992faeacbc5d6c6991db15b5f8364a1b  
   WETH  │  $1.29e-15  │                     │  0x6e5f2745c08249a190239763706473be0b72816d  
   WETH  │   $297.15K  │     Balancer Pool2  │  0xd8eb546726d449fc1ded06dfeca800a2fa8bb930  
    DAI  │      $0.00  │                     │  0x8ffae111ab06f532a18418190129373d14570014  
    DAI  │  $3.55e-12  │                     │  0xdf9ff5c077d9f3427ade67ac2d27a864be6f3187  
    DAI  │    $58.11M  │                     │  0x7842186cdd11270c4af8c0a99a5e0589c7f249ce  
    BAL  │      $0.00  │  Balancer BAL-WETH  │  0xcd1ac0014e2ebd972f40f24df1694e6f528b2fd4  
    BAL  │     $1.19M  │     Balancer veBAL  │  0x8cba3149b95084a61bbab9e01110b0fb92c9a289  
    BAL  │      $0.00  │                     │  0x66977ce30049cd0e443216bf26377966c3a109e2  

┌─────────────────┐
│ FEI Deployments │
└─────────────────┘

  asset  │  balance  │  name  │                                     address  
─────────┼───────────┼────────┼──────────────────────────────────────────────
    FEI  │   $2.63M  │        │  0x614d46b7eb2ac1a359b8835d64954f3ee4e6f676  

Create data payload for app.fei.money/analytics¶

In [6]:

payload = await fei_utils.async_create_payload(timescale='30d,1d')

Reference

async ctc.protocols.fei_utils.async_create_payload(*, blocks=None, timestamps=None, timescale=None, end_time=None, window_size=None, interval_size=None, provider=None)

create data payload from scratch

async ctc.protocols.fei_utils.async_get_pcv_stats(block=None, *, wrapper=False, provider=None)

async ctc.protocols.fei_utils.async_get_pcv_stats_by_block(blocks, *, wrapper=False, provider=None, nullify_invalid=True)

async ctc.protocols.fei_utils.async_print_pcv_assets(block=None)

async ctc.protocols.fei_utils.async_print_pcv_deposits(block=None)

Gnosis Safe

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

[Examples coming soon]¶

Defi Llama

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

[Examples coming soon]¶

Multicall

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

[Examples coming soon]¶

Rari

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import rari_utils

In [2]:

comptroller = '0xc54172e34046c1653d1920d40333dd358c7a1af4'
ctoken = '0xd8553552f8868c1ef160eedf031cf0bcf9686945'
underlying_token = '0x956f47f50a910163d8bf957cf5846d573e7f87ca'

Get all pools¶

In [3]:

fuse_pools = await rari_utils.async_get_all_pools()

len(fuse_pools)

Out[3]:

202

Get pool metadata¶

In [4]:

ctokens = await rari_utils.async_get_pool_ctokens(comptroller=comptroller)

ctokens

Out[4]:

('0xd8553552f8868c1ef160eedf031cf0bcf9686945',
 '0xfd3300a9a74b3250f1b2abc12b47611171910b07',
 '0xbb025d470162cc5ea24daf7d4566064ee7f5f111',
 '0x7e9ce3caa9910cc048590801e64174957ed41d43',
 '0x5ca8ffe4dad9452ed880fa429dd0a08574225936',
 '0xbfb6f7532d2db0fe4d83abb001c5c2b0842af4db',
 '0x30fa046ba48c193230722ec9068ba7234e40ffd2',
 '0xb723e1dbd267d215b40c2be756b158f83b68503b',
 '0x7259ee19d6b5e755e7c65cecfd2466c09e251185',
 '0x647a36d421183a0a9fa62717a64b664a24e469c7',
 '0x0d54596900df651e6954226e1e1141f1e4980258')

In [5]:

underlying_tokens = await rari_utils.async_get_pool_underlying_tokens(comptroller=comptroller)

underlying_tokens

Out[5]:

{'0xd8553552f8868c1ef160eedf031cf0bcf9686945': '0x956f47f50a910163d8bf957cf5846d573e7f87ca',
 '0xfd3300a9a74b3250f1b2abc12b47611171910b07': '0xc7283b66eb1eb5fb86327f08e1b5816b0720212b',
 '0xbb025d470162cc5ea24daf7d4566064ee7f5f111': '0x0000000000000000000000000000000000000000',
 '0x7e9ce3caa9910cc048590801e64174957ed41d43': '0x6b175474e89094c44da98b954eedeac495271d0f',
 '0x5ca8ffe4dad9452ed880fa429dd0a08574225936': '0xbaaa1f5dba42c3389bdbc2c9d2de134f5cd0dc89',
 '0xbfb6f7532d2db0fe4d83abb001c5c2b0842af4db': '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
 '0x30fa046ba48c193230722ec9068ba7234e40ffd2': '0x3d1556e84783672f2a3bd187a592520291442539',
 '0xb723e1dbd267d215b40c2be756b158f83b68503b': '0xcf84a3dc12319531e3debd48c86e68eaeaff224a',
 '0x7259ee19d6b5e755e7c65cecfd2466c09e251185': '0x7f39c581f595b53c5cb19bd0b3f8da6c935e2ca0',
 '0x647a36d421183a0a9fa62717a64b664a24e469c7': '0x5f98805a4e8be255a32880fdec7f6728c6568ba0',
 '0x0d54596900df651e6954226e1e1141f1e4980258': '0x559ebc30b0e58a45cc9ff573f77ef1e5eb1b3e18'}

Get pool state¶

In [6]:

tvl_and_tvb = await rari_utils.async_get_pool_tvl_and_tvb(comptroller=comptroller)

tvl_and_tvb

Out[6]:

{'tvl': 21484187.085672226, 'tvb': 18539823.760518614}

In [7]:

prices = await rari_utils.async_get_pool_prices(comptroller=comptroller)

prices

Out[7]:

{'0xd8553552f8868c1ef160eedf031cf0bcf9686945': 1.0075195576032028,
 '0xfd3300a9a74b3250f1b2abc12b47611171910b07': 0.2094838515,
 '0xbb025d470162cc5ea24daf7d4566064ee7f5f111': 1295.91,
 '0x7e9ce3caa9910cc048590801e64174957ed41d43': 1.0050559596000002,
 '0x5ca8ffe4dad9452ed880fa429dd0a08574225936': 1.004836828418787,
 '0xbfb6f7532d2db0fe4d83abb001c5c2b0842af4db': 1.0126434312735182,
 '0x30fa046ba48c193230722ec9068ba7234e40ffd2': 0.010655016237218972,
 '0xb723e1dbd267d215b40c2be756b158f83b68503b': 520.7037161447378,
 '0x7259ee19d6b5e755e7c65cecfd2466c09e251185': 1402.1244992788068,
 '0x647a36d421183a0a9fa62717a64b664a24e469c7': 1.0341835199999998,
 '0x0d54596900df651e6954226e1e1141f1e4980258': 1.0594131586349256}

Get ctoken state¶

In [8]:

await rari_utils.async_get_ctoken_state(ctoken)

Out[8]:

{'tvl': 12274901.507479219,
 'tvb': 12274901.507479219,
 'supply_apy': 0.024947221966542532,
 'borrow_apy': 0.026546236787341915}

Get ctoken state across multiple blocks¶

In [9]:

blocks = [14000000, 14100000, 14200000]

await rari_utils.async_get_ctoken_state_by_block(ctoken, blocks=blocks)

Out[9]:

{'tvl': [25592342.86812161, 27846764.4866587, 26131727.36829893],
 'tvb': [21279628.94118887, 25522233.17882379, 21041419.8055125],
 'supply_apy': [0.1577145831367548, 0.5777531640145352, 0.06528371436195024],
 'borrow_apy': [0.20572510722810078, 0.6961907149308775, 0.08695883809682425]}

Print Fuse summmary¶

In [10]:

await rari_utils.async_print_all_pool_summary()

Rari Fuse
─────────

- TVL: $176.47M
- TVB: $149.63M
- block: 15613498

    #  │                     pool  │       TVL  │       TVB  
───────┼───────────────────────────┼────────────┼────────────
  136  │                ICHI Pool  │   $64.97M  │   $63.83M  
    8  │   FeiRari (Fei DAO Pool)  │   $21.48M  │   $18.54M  
   18  │       Olympus Pool Party  │    $21.2M  │   $18.15M  
  156  │        Tribe Convex Pool  │   $14.54M  │   $14.41M  
  127  │      0xb1's Kitchen Sink  │   $13.57M  │   $13.38M  
    6  │         Tetranode's Pool  │   $12.97M  │     $2.7M  
   27  │           Stake DAO Pool  │    $5.55M  │    $4.29M  
    7  │     Tetranode's ETH Pool  │    $4.72M  │    $1.09M  
  144  │    Babylon's Gold Lender  │    $4.52M  │     $4.5M  
   90  │      Float Protocol Pool  │    $4.41M  │    $4.41M  
  146  │           Tribe ETH Pool  │    $3.15M  │    $3.15M  
  102  │  DeFiGeek Community Pool  │    $2.27M  │  $337.68K  
    9  │     FRAX RAI Stable Pool  │    $1.51M  │   $834.1K  
  116  │          handle globalFX  │  $864.62K  │        $0  
   31  │                NFTX Pool  │  $733.71K  │    $4.72K  

Print single token stats across multiple pools¶

In [11]:

await rari_utils.async_print_fuse_token_summary(underlying_token)

FEI Token Fuse Usage
────────────────────

- TVL: $24.77M
- TVB: $24.57M
- block: 15613499

                               pool  │       TVL  │         TVB  │    supply %  │   borrow %  │  util %  
─────────────────────────────────────┼────────────┼──────────────┼──────────────┼─────────────┼──────────
    Tetranode's Flavor of the Month  │   $12.27M  │     $12.27M  │       2.49%  │      2.65%  │    100%  
                  Tribe Convex Pool  │    $8.54M  │      $8.54M  │     124.35%  │    143.57%  │    100%  
                     Stake DAO Pool  │    $1.31M  │      $1.31M  │       2.15%  │      2.65%  │    100%  
              Babylon's Gold Lender  │  $857.84K  │    $857.54K  │     118.74%  │    159.82%  │  99.97%  
               Tetranode's ETH Pool  │  $716.05K  │    $715.62K  │     149.16%  │    168.52%  │  99.94%  
                Float Protocol Pool  │  $713.37K  │    $713.37K  │     853.32%  │  1,063.27%  │    100%  
                   Tetranode's Pool  │  $246.53K  │    $100.47K  │        3.1%  │      8.59%  │  40.75%  
                 Olympus Pool Party  │   $40.27K  │     $25.66K  │     682.04%  │    656.18%  │  63.72%  
                 UMA Community Pool  │   $32.29K  │     $28.41K  │     153.18%  │    238.92%  │     88%  
                      Fox and Frens  │   $31.38K  │      $3.92K  │        inf%  │       inf%  │  12.49%  
                        Badger Pool  │    $5.69K  │      $2.99K  │        inf%  │     31.65%  │  52.62%  
                          NFTX Pool  │    $4.02K  │      $49.62  │   0.002473%  │  0.248939%  │   1.23%  
                    Barnbridge pool  │    $1.38K  │     $888.26  │        3.2%  │      5.39%  │   64.6%  
                  Harvest FARMstead  │    $1.13K  │      $31.75  │        inf%  │       inf%  │   2.81%  
                     troopersGarage  │   $485.53  │  $2.681e-13  │          0%  │      2.53%  │      0%  
          Token Mass Injection Pool  │   $122.48  │   $1.04e-12  │     683.91%  │     31.65%  │      0%  
                    Index Coop Pool  │    $85.46  │  $1.569e-12  │          0%  │  0.000123%  │      0%  
                              G-UNI  │    $49.84  │  $2.587e-13  │  50,616.83%  │  1,151.29%  │      0%  
  Frax & Reflexer Stable Asset Pool  │    $10.31  │  $5.648e-13  │          0%  │  0.000003%  │      0%  

Get token stats across multiple pools¶

In [12]:

token_stats = await rari_utils.async_get_token_multipool_stats('0x956f47f50a910163d8bf957cf5846d573e7f87ca')

print('- aggregate stats:', token_stats['total'])
print('- # pools:', len(token_stats['per_pool']))
print('- stats given for each pool:', list(token_stats['per_pool'][comptroller].keys()))

- aggregate stats: {'tvl': 24772786.543556392, 'tvb': 24570960.8652956}
- # pools: 42
- stats given for each pool: ['tvl', 'tvb', 'ctoken', 'matches', 'supply_apy', 'borrow_apy', 'name', 'pool_index']

Reference

async ctc.protocols.rari_utils.async_get_all_pools(block=None, provider=None)

async ctc.protocols.rari_utils.async_get_ctoken_state(ctoken, *, block='latest', metrics=None, eth_price=None, in_usd=True)

async ctc.protocols.rari_utils.async_get_ctoken_state_by_block(ctoken, blocks, *, metrics=None, eth_price=None, in_usd=True)

async ctc.protocols.rari_utils.async_get_pool_ctokens(comptroller, *, block='latest')

async ctc.protocols.rari_utils.async_get_pool_prices(*, oracle=None, ctokens=None, comptroller=None, block='latest', to_usd=True)

async ctc.protocols.rari_utils.async_get_pool_tvl_and_tvb(*, comptroller=None, ctokens=None, oracle=None, block='latest')

async ctc.protocols.rari_utils.async_get_pool_underlying_tokens(*, ctokens=None, comptroller=None, block='latest')

async ctc.protocols.rari_utils.async_get_token_multipool_stats(token, block='latest', *, in_usd=True)

async ctc.protocols.rari_utils.async_print_all_pool_summary(block='latest', n_display=15)

async ctc.protocols.rari_utils.async_print_fuse_token_summary(token, *, block='latest', in_usd=True)

Uniswap V2

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import uniswap_v2_utils
from ctc.toolbox.defi_utils.dex_utils.amm_utils import cpmm

In [2]:

pool = '0x9928e4046d7c6513326ccea028cd3e7a91c7590a'

Get pool metadata¶

In [3]:

pool_tokens = await uniswap_v2_utils.async_get_pool_tokens(pool)
pool_symbols = await uniswap_v2_utils.async_get_pool_symbols(pool)
pool_decimals = await uniswap_v2_utils.async_get_pool_decimals(pool)

print('pool_tokens:', pool_tokens)
print('pool_symbols:', pool_symbols)
print('pool_decimals:', pool_decimals)

pool_tokens: ['0x956f47f50a910163d8bf957cf5846d573e7f87ca', '0xc7283b66eb1eb5fb86327f08e1b5816b0720212b']
pool_symbols: ['FEI', 'TRIBE']
pool_decimals: [18, 18]

Get pool state¶

In [4]:

pool_state = await uniswap_v2_utils.async_get_pool_state(pool)

pool_state

Out[4]:

{'x_reserves': 13430875.390003089,
 'y_reserves': 63585361.05796264,
 'lp_total_supply': 44686131.153790146}

Get pool state at a specific block¶

In [5]:

pool_state = await uniswap_v2_utils.async_get_pool_state(pool, block=14000000)

pool_state

Out[5]:

{'x_reserves': 153539933.09509552,
 'y_reserves': 125886010.40488024,
 'lp_total_supply': 215052578.20642424}

Get pool state across many historical blocks¶

In [6]:

blocks = list(range(14000000, 14100000, 20000))

pool_state_by_block = await uniswap_v2_utils.async_get_pool_state_by_block(
    pool,
    blocks=blocks,
)

pool_state_by_block

Out[6]:

{'x_reserves': [3902.2604757534364,
  3646.5911759325286,
  3320.412482258139,
  2803.750690192395,
  2753.4720320440665],
 'y_reserves': [3199.4282721811446,
  3031.4310322189203,
  3246.3249589194047,
  3832.6757137039026,
  3891.8368311451377],
 'lp_total_supply': [215052578.2064242,
  202288486.47575706,
  199698652.82397622,
  199313423.07966512,
  198957800.9702922]}

Show pool Summary¶

In [7]:

cpmm.print_pool_summary(**pool_state)

- X reserves: 153.54M

- Y reserves: 125.89M

- total lp tokens: 215.05M

- X / Y price: 1.22

- Y / X price: 0.819891

- X / Y liquidity depth: 

      depth  │   new price  │           X  │           Y  
    ─────────┼──────────────┼──────────────┼──────────────
       -10%  │   1.1 X / Y  │   buy 7.87M  │  sell 6.82M  
        -5%  │  1.16 X / Y  │   buy 3.88M  │  sell 3.28M  
        -2%  │   1.2 X / Y  │   buy 1.54M  │  sell 1.28M  
         0%  │  1.22 X / Y  │        0.00  │        0.00  
        +2%  │  1.24 X / Y  │  sell 1.53M  │   buy 1.24M  
        +5%  │  1.28 X / Y  │   sell 3.8M  │   buy 3.03M  
       +10%  │  1.34 X / Y  │  sell 7.51M  │   buy 5.85M  

- Y / X liquidity depth: 

      depth  │       new price  │           Y  │           X  
    ─────────┼──────────────────┼──────────────┼──────────────
       -10%  │  0.737902 Y / X  │   buy 6.45M  │  sell 8.32M  
        -5%  │  0.778896 Y / X  │   buy 3.18M  │  sell 3.99M  
        -2%  │  0.803493 Y / X  │   buy 1.26M  │  sell 1.56M  
         0%  │  0.819891 Y / X  │        0.00  │        0.00  
        +2%  │  0.836289 Y / X  │  sell 1.25M  │   buy 1.51M  
        +5%  │  0.860886 Y / X  │  sell 3.11M  │   buy 3.69M  
       +10%  │   0.90188 Y / X  │  sell 6.15M  │   buy 7.14M  

Model pool trade¶

In [8]:

trade = cpmm.trade(
    x_sold=500000,
    x_reserves=pool_state['x_reserves'],
    y_reserves=pool_state['y_reserves'],
)

trade

Out[8]:

{'x_bought': -500000,
 'x_sold': 500000,
 'y_bought': 407392.9793098554,
 'y_sold': -407392.9793098554,
 'fee_rate': 0.003,
 'new_pool': {'x_reserves': 154039933.09509552,
  'y_reserves': 125478617.42557038}}

Show trade summary¶

In [9]:

cpmm.print_trade_summary(
    x_sold=500000,
    x_reserves=pool_state['x_reserves'],
    y_reserves=pool_state['y_reserves'],
    x_name=pool_symbols[0],
    y_name=pool_symbols[1],
)

- FEI sold: 500,000
- TRIBE bought: 407,392.98
- fees: 1,500 FEI
- prices:

                 │   P_mean │  P_start │    P_end │ mean slippage │ end slippage 
    ─────────────┼──────────┼──────────┼──────────┼───────────────┼──────────────
     FEI / TRIBE │     1.23 │     1.22 │     1.23 │      0.006266 │     0.006514 
     TRIBE / FEI │ 0.814786 │ 0.819891 │ 0.814585 │     -0.006226 │    -0.006472 

- pool reserve sizes:

           │        before │          after │    change 
    ───────┼───────────────┼────────────────┼───────────
       FEI │ 153,539,933.1 │  154,039,933.1 │  0.003256 
     TRIBE │ 125,886,010.4 │ 125,478,617.43 │ -0.003236 

Get pool swaps¶

In [10]:

swaps = await uniswap_v2_utils.async_get_pool_swaps(pool)

swaps

Out[10]:

	transaction_hash	recipient	sold_id	bought_id	sold_amount	bought_amount
block_number
12168368	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0xbffb152b9392e38cddc275d818a3db7fe364596b	0	1	385878266.886967	119248224.557418
12168369	0x641b95d1f76a4a9e0101df94aab04aee23f95bca349f...	0x2ebd449e7b10b20135b6c1134b9e40c84f9fffde	1	0	469310.538337	1500858.802284
12168369	0x59e7772688fe9966abfeba79408ca9aedbf316bf4761...	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	1	0	305051.849919	966302.891883
12168369	0xb7dd780066a84cd1fc4716ed11673c64d8af03ca28ba...	0x155ab90755eefc6f521cb3bccba4c5aedcd4cdb7	1	0	207200.0	652232.187339
12168369	0x3a3fdaaa52f99c3004370494e2b0852f9c6fb9b02a4f...	0xe28b3058a2f7f251741a7289b633a902126260ea	1	0	7587.187036	23820.490941
...	...	...	...	...	...	...
15612495	0x69ae33f8e505e9c1b5abaa8260869fb057cea9602749...	0xc6cf51f57969129654c5014748e44e2a8f6ebd81	1	0	5262.738555	1104.225943
15612612	0xc91f8451da0f12c22349bb2fbafd48789d4cab599d49...	0xdde3e2024e270d6022d1bb4e8745e9dc6d82e0bc	0	1	564.466359	2674.236899
15612742	0xbeb5c2ad1d9839abd58014bc04a817de82b51a232c1f...	0xcbf181784a00459a9d2dec643e63d9f1565a1cee	0	1	24990.752129	118172.509804
15613010	0xd5a6c5231f6f1a8b67ae6a5399ea1d827b0ad3edecd5...	0xf2f400c138f9fb900576263af0bc7fcde2b1b8a8	1	0	880.67771	185.469717
15613067	0x992111315f732cb36397113171f30b12ab177cea53c1...	0x9435f1085584764b081177944033d4ed2cfd23ee	1	0	561.167131	118.178479

42679 rows × 6 columns

Get pool mints¶

In [11]:

mints = await uniswap_v2_utils.async_get_pool_mints(pool)

mints

Out[11]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__sender	arg__amount0	arg__amount1
block_number	transaction_index	log_index
12168368	61	57	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	2.605227e+08	2.000000e+08
12168392	5	9	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x650f7f511d4c36c5753e5c53a5a0a1be89c06ce04d88...	0xf23c71488efbcc9f7bb065aef33862a23f163e3a3e20...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	1.673037e+04	7.179388e+03
12168405	44	48	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0xddd3da1acfddc7f772c6c80a3e765f88dd44f4037e08...	0x7f302eeb37edd1a429b6dd8b6a29064b77a30b3a88cd...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	2.060025e+04	9.973594e+03
12168410	32	98	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x2f0a0bc05f1c8d1b846fac07d3b92d3fbb8f6d8f04f9...	0xddd0c0cc624e7db2808217e98d37282e553f98e697f0...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	4.751617e+03	2.356516e+03
12168414	222	59	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x4989fc640b4044afa6ccaba2d25a5c6e3257cf9148c4...	0x5258f324dfdc6c083e5802ae0045e3f4b86661f350f2...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	7.425795e+03	3.770426e+03
...	...	...	...	...	...	...	...	...	...	...	...
15121055	250	388	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x8c5a19294d630ad01ed205a8fdb662252bad819cc705...	0xe77d40f1798594ffc93241a4d790824c85bd4d0c8665...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	4.277380e-01	2.793056e+00
15153321	271	547	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x920636c5b77319c5539da8c407d255b7eced244e9a7b...	0xadc0361d11d36ebac3647006a307494f1ff7343ff44a...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	1.430650e+01	9.364430e+01
15328435	28	46	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x12342787e07e1f6423763e91c6a129248a7eb8175f76...	0x3716e7ebc7097737b96a67c1ab54241ff9022a8ec811...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	4.986920e+03	3.119037e+04
15397041	133	328	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x4508a1d5ec7c01c3b427c554c9d3c7802c8e744a9190...	0x1dd407108ac0de55406f3ceaab2b1e1594ed3a12688e...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	2.500589e+03	1.147334e+04
15557196	86	101	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0xbabc09363f96a7b99d1c6bec4d1bcf62572f21d4382d...	0x2470dcedbade0b9d7ee71677f1739211cf3520139555...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Mint	0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	2.000000e+00	8.846706e+00

10049 rows × 9 columns

Get pool burns¶

In [12]:

burns = await uniswap_v2_utils.async_get_pool_burns(pool)

burns

getting events from node, block range: [12125707, 15613506]
saving events to file: /home/storm/ctc_data/evm/networks/mainnet/events/contract__0x9928e4046d7c6513326ccea028cd3e7a91c7590a/event__0xdccd412f0b1252819cb1fd330b93224ca42612892bb3f4f789976e6d81936496/12125707__to__15613506.csv

Out[12]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__sender	arg__to	arg__amount0	arg__amount1
block_number	transaction_index	log_index
12168478	71	92	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9cbf1e47301905b3c876acc2c2db8762f333e3d1bbfa...	0x71d8939b4edf07087a69fd646bfaf509527ed9211411...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0xc01b33ae2e3a4cb75d0e3bcee2f0cc3eb3fe668a	148271.937203	89795.087503
12168483	123	157	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0xbd0256f088eeb51f8101a1b3b20d53fc35b532be0ebc...	0xab4f3a45eab31aa9a75ee961afba7b2b5b3bef745bca...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0xd683b78e988ba4bdb9fa0e2012c4c36b7cc96aad	4723.992545	2879.302038
12168529	140	297	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x0614693238887091262a3d86adddcd88e3020708ad1e...	0xbd4f8703249967542414af4246fb3433c222deafc122...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0x18a5d209d58852499abc1ee73cbb27cc743dd317	18653.702095	9522.864220
12168537	55	35	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x7c3f742344556505b91508e12fe45183553c5d575224...	0xd3bd1f7dc5453ac1ff625f8bfebbf2816e99f3bcc3ce...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0x4042f4142b026c9f980c7906060a80f57090d63b	8471.241203	4303.648906
12168561	104	149	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x7dd20b35ff12825a70eb73bab51cbb5f3902c6cc5bb1...	0xea3807c8e6a2a26e245c74a8f32f6b1834471549acf2...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0xbfe890aac8d9d8dd840115dcd2cff3c99089779d	96329.571186	44065.409781
...	...	...	...	...	...	...	...	...	...	...	...	...
15551821	71	136	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x901b3422c33ce7e6818a8432a4accfdc196cb400af4c...	0xcfa991c54911b7e355105bcf618e2d952093f0449ff7...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0x7e2e5d94f11f358345a4ee14c4f1a8521315c03b	85.255637	374.935175
15559412	174	390	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0xddd9480f4feede79b255b19101cd3e4fc6b6e013702e...	0x03b721863a7419ebb4714c3764939763856e601d1f66...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0x885d26765a096136cfeb1d216713ade4289641e0	64.535703	285.569863
15574518	215	386	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0xdccc0a9212e3f39ed6d48f5113bfa76b0ba9a02d7f79...	0x8e816ea1fe6abb4da0031f3ac9b5d617c310e23e384b...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0xdf632ea5ba8283488aae8538e17a2f802243a61a	596.256976	2739.482104
15612326	17	54	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9debdfcc6e2dc0bbecc377447257cd2c2e13210a417c...	0x2f9d506a91b1b65b0bab47f2fe08109956fd3812e361...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0xd2de083018d93c6a7c4fb154bf6f36e6f1833796	5756.744803	27333.163245
15613063	96	266	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x18107b4cd7d0f7271fa0a7acff48b39d50c0b765e06a...	0x0a249e10c1e5e74a08cb1f34313eeccc8d0208c4de08...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	Burn	0xdccd412f0b1252819cb1fd330b93224ca42612892bb3...	0x7a250d5630b4cf539739df2c5dacb4c659f2488d	0x9435f1085584764b081177944033d4ed2cfd23ee	82.440313	390.287643

5272 rows × 10 columns

Reference

async ctc.protocols.uniswap_v2_utils.async_get_pool_burns(pool_address, *, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False, replace_symbols=False, normalize=True, provider=None, verbose=False)

async ctc.protocols.uniswap_v2_utils.async_get_pool_decimals(pool=None, *, x_address=None, y_address=None, provider=None)

async ctc.protocols.uniswap_v2_utils.async_get_pool_mints(pool_address, *, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False, replace_symbols=False, normalize=True, provider=None, verbose=False)

async ctc.protocols.uniswap_v2_utils.async_get_pool_state(pool, *, block=None, provider=None, normalize=True, fill_empty=True)

async ctc.protocols.uniswap_v2_utils.async_get_pool_state_by_block(pool, *, blocks, provider=None, normalize=True)

async ctc.protocols.uniswap_v2_utils.async_get_pool_swaps(pool, *, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False, include_prices=False, include_volumes=False, label='index', normalize=True, provider=None, verbose=False)

async ctc.protocols.uniswap_v2_utils.async_get_pool_symbols(pool=None, *, x_address=None, y_address=None, provider=None)

async ctc.protocols.uniswap_v2_utils.async_get_pool_tokens(pool, provider=None)

Uniswap V3

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

In [1]:

from ctc.protocols import uniswap_v3_utils

In [2]:

pool = '0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d'

Get pool metadata¶

In [3]:

pool_metadata = await uniswap_v3_utils.async_get_pool_metadata(pool)

pool_metadata

Out[3]:

{'x_symbol': 'RAI',
 'y_symbol': 'DAI',
 'x_address': '0x03ab458634910aad20ef5f1c8ee96f1d6ac54919',
 'y_address': '0x6b175474e89094c44da98b954eedeac495271d0f',
 'fee': 500}

Get pool swaps¶

In [4]:

swaps = await uniswap_v3_utils.async_get_pool_swaps(pool)

swaps

searching for creation block of 0xcB0C5d9D92f4F2F80cce7aa271a1E148c226e19D
- trying block: 0
- trying block: 15613498
- trying block: 7806749
- trying block: 11710123
- trying block: 13661810
- trying block: 12685966
- trying block: 12198044
- trying block: 12442005
- trying block: 12320024
- trying block: 12381014
- trying block: 12350519
- trying block: 12365766
- trying block: 12373390
- trying block: 12377202
- trying block: 12375296
- trying block: 12374343
- trying block: 12374819
- trying block: 12375057
- trying block: 12375176
- trying block: 12375236
- trying block: 12375266
- trying block: 12375281
- trying block: 12375273
- trying block: 12375269
- trying block: 12375267
result: 12375267
getting events from node, block range: [12375267, 15613499]
saving events to file: /home/storm/ctc_data/evm/networks/mainnet/events/contract__0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d/event__0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67/12375267__to__15613499.csv
loading events (8.41MB across 1 files)

Out[4]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__sender	arg__recipient	x_amount	y_amount	arg__sqrtPriceX96	arg__liquidity	arg__tick
block_number	transaction_index	log_index
12376204	174	283	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0x732c37dec26a9b18dd5eae14c284135a6c94dfeac8e1...	0x4273d4c137dafc078d57d6bef59be638caf0befb6e3f...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0xe592427a0aece92de3edee1f18e0157c05861564	0x530cf036ed4fa58f7301a9c788c9806624cefd19	-2566.392073	7729.371943	137701145051790343205145302274	1279015072674050594682566	11055
12376300	284	324	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0xdec52387bfbeaca08c902e977d45adf010244206de23...	0x7f8c5d7d3b80e5bcc44bc69724df30c2a02e08dfc797...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0xe592427a0aece92de3edee1f18e0157c05861564	0xfa70fe951720d912eba9afa8cbf1b58f6c73d163	1000.000000	-3015.152438	137514372438639148649092841650	1279015072674050594682566	11028
12376313	98	145	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0xd4476cdad58210e7b679d84c2ceb4ccb840130f29f3d...	0x04dcec4d9568c9c546c8eca841bd1a3ae5cd90980c74...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0xe592427a0aece92de3edee1f18e0157c05861564	0xfa70fe951720d912eba9afa8cbf1b58f6c73d163	800.000000	-2406.239254	137365318749770594892820423408	1279015072674050594682566	11006
12376354	306	270	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0xa39d3cd53d20824f408257273ac11a8e995b0089ac1e...	0xd23e9b136c18fb7fb40402eb7891b2eac9edfdbb0d18...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0xe592427a0aece92de3edee1f18e0157c05861564	0x22f9dcf4647084d6c31b2765f6910cd85c178c18	-3664.080852	11028.455800	137472087145646725670697909903	8179643415011922565226242	11022
12377046	148	226	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0x8ace8c5b4669b873546e85e04d649489e16e9901f4e6...	0x31d3aaea23e8994c40df6319426dc9dfb152ea9b546a...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0xe592427a0aece92de3edee1f18e0157c05861564	0xc5a215cdbb69231b2e0f70613afdddbfc1e12c2d	-3454.270677	10412.397172	137569386092052975813204860490	8474322160704207337819030	11036
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
15613248	2	6	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0x88e729e7bda2a8fd56b14ee32db574f2b2fb56670e3e...	0xa9b500e6c785e3f4d884798956affa5c69fb1564b5c3...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0x0000000000007f150bd6f54c40a34d7c3d5e9f56	0x0000000000007f150bd6f54c40a34d7c3d5e9f56	2104.882553	-6006.778233	133873006685643048934614245587	379875942887692857622351809	10491
15613307	13	40	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0xc964e8e19629eef13bbcf2ef96bac3a98e7c5aa6336e...	0x450b156956a948482169845ea587ad2f48150580f19e...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0x0000000000007f150bd6f54c40a34d7c3d5e9f56	0x8ae720a71622e824f576b4a8c03031066548a3b1	-1051.682647	3004.213604	133873632940921688707618164694	379875942887692857622351809	10491
15613329	158	351	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0xd976fc81fc9f11f20b5c2433a211483fb91ea3adefe5...	0xcd37922bc3e8718c708258c92f23984c657c1e5caade...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0x0000000000304a767881fdccb30fceb51f6221e2	0x8ae720a71622e824f576b4a8c03031066548a3b1	-726.069290	2074.090024	133874065303595372065514727143	379875942887692857622351809	10491
15613351	4	12	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0xbd90741fd2f2e8516f635cfd697b37570ad99e053aef...	0xa7f57c6419cc6045e4f91627c6123737456f10f5d471...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0x0000000000007f150bd6f54c40a34d7c3d5e9f56	0x8ae720a71622e824f576b4a8c03031066548a3b1	-982.459699	2806.516369	133874650347111739584518944911	379875942887692857622351809	10491
15613391	46	142	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	0x8f5db4cfbf517712d69ffc8d6aad99ecff7c5e31c7bd...	0x81f8c1bf2aef89255db34b213cb1edeb630d5488cb84...	0xcb0c5d9d92f4f2f80cce7aa271a1e148c226e19d	Swap	0xc42079f94a6350d7e6235f29174924f928cc2ac818eb...	0x0000000000304a767881fdccb30fceb51f6221e2	0x8ae720a71622e824f576b4a8c03031066548a3b1	-672.522239	1921.156225	133875050829362923132566273186	379875942887692857622351809	10492

17410 rows × 13 columns

Quote trades¶

In [5]:

await uniswap_v3_utils.async_quote_exact_input_single(
    amount_in=int(500e18),
    token_in=pool_metadata['x_address'],
    token_out=pool_metadata['y_address'],
    fee=pool_metadata['fee']
)

Out[5]:

1426894839696235279726

In [6]:

await uniswap_v3_utils.async_quote_exact_output_single(
    amount_out=int(500e18),
    token_in=pool_metadata['x_address'],
    token_out=pool_metadata['y_address'],
    fee=pool_metadata['fee']
)

Out[6]:

175205370461472672533

Reference

async ctc.protocols.uniswap_v3_utils.async_get_pool_metadata(pool_address, **rpc_kwargs)

async ctc.protocols.uniswap_v3_utils.async_get_pool_swaps(pool_address, *, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False, replace_symbols=False, normalize=True)

async ctc.protocols.uniswap_v3_utils.async_quote_exact_input_single(token_in, token_out, *, fee, amount_in, sqrt_price_limit_x96=0, provider=None, block=None)

async ctc.protocols.uniswap_v3_utils.async_quote_exact_output_single(token_in, token_out, *, fee, amount_out, sqrt_price_limit_x96=0, provider=None, block=None)

Yearn

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

[Examples coming soon]¶

On-chain Protocols

Protocol	Examples	Reference	Source
Aave V2	Examples	Reference	Source
Balancer	Examples	Reference	Source
Chainlink	Examples	Reference	Source
Compound	Examples	Reference	Source
Curve	Examples	Reference	Source
ENS	Examples	Reference	Source
Fei	Examples	Reference	Source
Gnosis Safe	Examples	Reference	Source
Multicall	Examples	Reference	Source
Rari	Examples	Reference	Source
Uniswap V2	Examples	Reference	Source
Uniswap V3	Examples	Reference	Source
Yearn	Examples	Reference	Source

External Data Sources

Protocol	Examples	Reference	Source
4byte	Examples	Reference	Source
Coingecko	Examples	Reference	Source
Defi Llama	Examples	Reference	Source
Etherscan	Examples	Reference	Source

Similar Python Tools

web3.py

web3.py is a general purpose EVM library that is created and maintained by the Ethereum Foundation. Although web3.py and ctc have some overlapping functionality, they focus on different things. Web3.py supports full wallet functionality, whereas ctc is currently limited to read-only operations. Web3.py also supports a greater variety of communication protocols including websockets.

On the other hand, ctc is primarily aimed at historical data analysis. It contains more functions for aggregating historical datasets from various on-chain protocols. Additionally, web3.py is primarily synchronous, whereas ctc is primarily asynchronous.

ape

ape is another general purpose EVM library that aims to improve upon web3.py in a variety of areas. Ape features direct integrations with many tools for both the development and deployment of smart contracts. Ape has plugins for many popular languages and tools including vyper, solidity, foundry, and hardhat.

ethtx

ethtx is a library for decoding and summarizing individual transactions. You can see it in action at https://ethtx.info/. Although ctc has its own transaction summarizing capabilities, it is currently much more limited than ethtx when it comes to tracing internal transactions and revealing the resultant state changes. These types of features may come to ctc in a future release.