EthSlurp - Drink the Blockchain

Display strings (summary)

EthSlurp allows you to export the slurped blockchain data in any format you wish. While it does provide three pre-canned formats (txt, csv, and html), the number of available formats is limitless. This is accomplished through a feature we call 'display strings.'

Blockchain data fields

Here's a list of all the fields in an Ethereum transaction:

  blockHash, blockNumber, confirmations, contractAddress, cumulativeGasUsed,
  from, gas, gasPrice, gasUsed, hash, input, nonce, timeStamp, to,
  transactionIndex, value

Jumping directly to an example: the display string for exporting a tab seperated text file (.txt) containing the data fields 'timeStamp,' 'from,' and 'value' would look like this:

 [{TIMESTAMP}]\t[{FROM}]\t[{VALUE}]\n                                       ~1

If, instead, you wanted to include 'blocknumber,' 'to,' 'gas,' and 'value,' your display string would look like this:

 [{BLOCKNUMBER}]\t[{TO}]\t[{GASUSED}]\t[{VALUE}]\n                          ~2

In display string '1' notice that the tab characters (\t) are outside of the square brackets. A token (that is, everything inside the square brackets) evaluates to empty if the field value (that is, everything inside the squiggly brackets) is empty. Because we want the tab to appear between all fields, empty or not, the tabis outside the ending square brackets. Display string '2' behaves identically.

If you wanted comma seperated values (.csv) so you could open the export file directly in MS Excel, you would use:

 ["{BLOCKNUMBER}"],["{TO}"],["{GASUSED}"],["{VALUE}"]\n                     ~3

In this case, we've replaced tabs between fields with commas, but we've also placed quotation marks inside the square brackets. If the field value is empty the quotation marks will dissapear. If we had placed the quotation marks outside the square brackets they would appear even if the field was emtpy. While this is not incorrect, it is more verbose than it needs to be.

If you wanted the resulting exported data to be a more easily understood by a human being, you might use:

 [{p:BLOCKNUMBER}:\t{BLOCKNUMBER}\n][{p:INPUT}:\t{INPUT}\n][{p:TO}:\t{TO}\n] ~4

Here we've seperated each field with a new line character (\n); however, we've put the newline inside the square brackets. In this case, if a field is empty, the entire line will disappear from the export. For example, if the new line character was outside the square brackets and the INPUT field was empty, the export might look like this:

blockNum:    14534123

to:          0xbb9bc244d798123fde783fcc1c72d3bb8c189413

If, instead, the new line character was inside the square brackets the export would look like this:

blockNum:    14534123
to:          0xbb9bc244d798123fde783fcc1c72d3bb8c189413

That is, the blank line gets eliminated becase if a field value evaluates to empty, the entire token does as well.

A further feature shown in display string '4' is the use of the prompt field specifier. This is explained in the details page.

A couple of things to note about display strings:

The field specifier is identical to name of the data field except it is in UPPERCASE;
Each field specifier is surrounded {directly} with squiggly brackets. A field specifier will not be recognized if it is not in UPPERCASE and surrounded directly with squiggly brackets;
Each field specifier is further surrounded with square brackets. Again the specifier will not be recognized without its square brackets; however, in this case, the square brackets do not need to be touching the squiggly brackets. There can be arbitrary intervening text;
If a data field's value evaluates to empty, the entire specifier (that is everything inside the [...]) will evaluate to empty.

Furthering the example, if the data for a transaction looked like this:

{
  "blockHash": "0xf61cc7b7d3ef647bcb6218a0.....a17b10364e255508",
  "blockNumber": "1491831",
  "confirmations": "7",
  "contractAddress": "",
  "cumulativeGasUsed": "408675",
  "from": "0x0ec97fcf4dd1a68a...",
  "gas": "121000",
  "gasPrice": "20000000000",
  "gasUsed": "74091",
  "hash": "0xa2b399a267ad13c2142e7fa388864ce7820....1616b81bb16a6c0a2e2",
  "input": "0x",
  "nonce": "3",
  "timeStamp": "1462885596",
  "to": "0xbb9bc244d798123...",
  "transactionIndex": "6",
  "value": "1000000000000000000"
}

(notice that it is not very easy to read), then the above display strings would render as follows (spaces below are tabs):

 [{TIMESTAMP}]\t[{FROM}]\t[{VALUE}]\n                                       ~1

   1462885596    0x0ec97fcf4dd1a68a...    1000000000000000000

 [{BLOCKNUMBER}]\t[{TO}]\t[{GASUSED}]\t[{VALUE}]\n                          ~2

   1491831        0xbb9bc244d798123...    74091    1000000000000000000

 ["{BLOCKNUMBER}"],["{TO}"],["{GASUSED}"],["{VALUE}"]\n                     ~3

   "1491831","0xbb9bc244d798123...","74091","1000000000000000000"

 [{p:BLOCKNUMBER}:\t{BLOCKNUMBER}\n][{p:INPUT}:\t{INPUT}\n][{p:TO}:\t{TO}\n] ~4

   Block Number:    1491831
   Input:           0x
   To:              0xbb9bc244d798123...

Note that the display string applies to each record separately. Our video explains it better.

What can you do with display strings?

We hear non-stop talk about the immortal, immutable, infinitely accessible, shared accounting ledger known as the Ethereum blockchain. "It will make all of our lives easier," they all say.

Until now, gaining access to this data has been anything but easy. We should know. We created EthSlurp in direct response to the great difficulty we had getting Ethereum blockchain data in a format we wanted. We trust that this tool will help you as well.