Calling Smart Contracts with `chifra state --call`

This is a simple document describing how to use the TrueBlocks chifra command to query a smart contract from your command line. When combined with other features of chifra it allows for a very easy way to build a history of various values on a smart contract. For example, perhaps you want to print out the entire history of the supply of a given token.

In this article, we first show the commands available and explain them as simply as we can and then show an example of doing exactly that.

The Commands

There are two basic forms of the command. Both are part of the chifra state tool. In particular, both use the chifra state --call option.

The --call option takes one parameter, but it’s a bit of a complicated parameter that we present here as a graphic since we think that’s the easiest way to describe it.

First Version: Use the smart contract’s address, a function signature, and optional padded bytes:

Second version: Use the smart contract’s address, a four-byte, and the optional padded bytes:

Using the Call Option

Here’s a very quick example of using the --call option. There are other ways to do this, of course, in particular our amazing Dynamic Traverser feature, but that requires C++ programming. This runs from a command line.

Install TrueBlocks

Blah, blah, blah. See the many articles we’ve written describing installing TrueBlocks: http://trueblocks.io.

Running the Commands

First, we’ll pick an ERC20 token at random:

chifra names ERC20 | head -614 | tail -8 | head -1

When we do this with the current version of chifra we get

Tag             Address         Name       Symbol Decimals
50-Tokens:ERC20 0x2287b...f49bf SoundMoney SDM    18

Let’s use that. To get a list of every transaction (including internal incoming traces) in which this address has appeared, do this:

chifra list 0x2287bd440a11c4585058fdc090455786130f49bf

This command does three things:

1. It visits every chunk of the TrueBlock index and finds every appearance of this address anywhere on the chain,
2. As it does this, depending on your setup, it downloads and caches (i.e. pins on IPFS) those portions of the index that you’ve expressed interest in. In this way, you become part of the solution to making access to the Ethereum data permissionless.
3. It caches the list of appearances so the next time you run it, it’s almost instantaneous.

chifra list 0x2287bd440a11c4585058fdc090455786130f49bf --count

shows us that there were 453 transactions as of the data of the writing of this article.

Note that as of this point, chifra has not hit against the Ethereum node. It has hit against IPFS to download the index, but it hasn’t yet extracted any data from the chain. We do that next.

Extracting and Cacheing Ethereum Data

The next command extracts the actual transactional data from the chain for the above address:

chifra export 0x2287bd440a11c4585058fdc090455786130f49bf

You’ll notice that this takes a little longer to run than the list command. That’s because we’re actually extracting the transactional data from the node. Because this is a bit slower, we offer the --cache_txs option which, you will see if you use it, speeds up subsequent queries by 30–40 times.

time chifra export --cache_tx 0x2287b...f49bf

takes 14.43 seconds on our machine, whereas the same command subsequently takes only 1/2 of one second. 30 times faster.

Moving on. Our goal is to list the historical changes in the total supply of this ERC20.

Using the Chifra --call Option

See the above description of the --call option. We’ll need it. First, let’s do this command:

chifra abis 0x2287bd440a11c4585058fdc090455786130f49bf

This shows all the commands available on this smart contract. We want the one called totalSupply which returns this data:

name          four-byte   signature
totalSupply   0x18160ddd  totalSupply()

We will use the chifra state --call routine on the latest block:

chifra state --call "0x2287b...f49bf | totalSupply()"

Note that this tells you that you need to supply a return value. chifra needs this so it can decipher the result. The proper command is:

chifra state --call "0x2287b...f49bf | totalSupply()(uint)"

or

chifra state --call "0x2287b...f49bf | totalSupply() returns (uint)"

This returns the following results:

bn       addr          signature     encoding    compressedresult
13496062 0x2287...49bf totalSupply() 0x18160ddd  429

So, there were 429 tokens available at block 1,349,062. Interesting…

All Appearances

We’ll finish now with this series of commands left unexplained. We invite the reader to figure out what’s going on for themselves:

# Store the blocks this address appears in blocks.txt
chifra list 0x2287bd440a11c4585058fdc090455786130f49bf --no_header \
    | cut -f2 \
    | sort -u -n >blocks.txt
# count how many unique blocks appear (we get 152 blocks)
wc blocks.txt
# Cache the extracted transactions (this is optional, but may
# speed things up
chifra export --cache_txs 0x2287bd440a11c4585058fdc090455786130f49bf
# Using the blocks.txt file call the totalSupply routine
# on the address at every block
chifra state --call \
    "0x2287bd440a11c4585058fdc090455786130f49bf|totalSupply()()" \
    --file blocks.txt

That produces a ton of data. Actually 152 rows, and to finish, here’s a nice little chart:

Permissionless access to some data on Ethereum. Pretty cool in my opinion.

Support Our Work

TrueBlocks is totally self-funded from our own personal funds and a few grants such as The Etheruem Foundation (2018), Consensys (2019), Moloch DAO (2021), and most recently Filecoin/IPFS (2021).

If you like this article or you simply wish to support our work go to our GitCoin grant https://gitcoin.co/grants/184/trueblocks. Donate to the next matching round. We get the added benefit of a larger matching grant. Even small amounts have a big impact.

If you’d rather, feel free to send any token to our public Ethereum address at trueblocks.eth or 0xf503017d7baf7fbc0fff7492b751025c6a78179b.