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.
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.
--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.
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:
- It visits every chunk of the TrueBlock index and finds every appearance of this address anywhere on the chain,
- 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.
- 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)"
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…
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 \
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.