README lacks good examples

[MattDodsonEnglish]

I think the README would benefit from having one or two examples of
how to use the utilities in more complex ways. Outside of checking the version, the only current
example is getBlock 100. This is a start, but it's pretty simple.

A good example would describe a use case that's more complex (while still being
fairly plausible/common.) For example, if you look at the man page for rsync.
there are lots of examples that have multiple options and multiple arguments. That
really helps us hit the ground running.

Besides that, I'm a little confused about what all the utilities are and how
to find them. I see that I can use <command> --help but I was getting tired
of doing that, and then I kept forgetting what I'd read :-).

Is there any location where all the utilities are listed in one place? If
so, I think that should go on the README too.

[tjayrush]

On Feb 11, 2021, at 4:26 PM, MattDodsonEnglish ***@***.***> wrote: I think the README would benefit from having one or two examples of how to use the utilities in more complex ways. Outside of checking the version, the only current example is getBlock 100. This is a start, but it's pretty simple.

Totally agree. One note before proceeding. All examples should be `chifra <tool>` and not <tool>. getBlock is tool, chifra blocks is how the examples should be There are an infinite number of possibilities, some quite complex. For example, chifra names -c Vitalik Returns one of Vitalik Buterins well-known early accounts chifra names -c Vitalik --no_header Remove the header chifra names -c Vitalik --no_header | cut -f2 Extracts the address only. On bash, chifra state `chifra names -c Vitalik --no_header | cut -f2` returns the current balance of that account in wei. chifra state --ether `chifra names -c Vitalik --no_header | cut -f2` Returns the same balance in ether. chifra state --dollars `chifra names -c Vitalik --no_header | cut -f2` Returns the balance in US dollars chifra names Dai Stablecoin ERC20 Returns the address of the DAI stable coin chifra tokens 0x6b175474e89094c44da98b954eedeac495271d0f 0x5ed8cee6b63b1c6afce3ad7c92f4fd7e1b8fad9f Returns the balance of DAI stable coins in Vitalik’s address And there’s a million more examples.

rA good example would describe a use case that's more complex (while still being fairly plausible/common.) For example, if you look at the man page for rsync. there are lots of examples that have multiple options and multiple arguments. That really helps us hit the ground running.

I think it’s an excellent idea to use great examples of man pages as the basis for our help. I don’t know if you’ve ever seen a program called IPFS (if not, you should check it out and download it). It has the best ‘onboarding’ of any project I’ve ever seen. It’s a command line tool with a top-level command (ipfs) with subcommands, etc. Really well done.

Besides that, I'm a little confused about what all the utilities are and how to find them. I see that I can use <command> --help but I was getting tired of doing that, and then I kept forgetting what I'd read :-).

A user familiar with the Ethereum data will better understand. Each command is named after a common part of the data — blocks, transactions, receipts, logs, traces, names, tokens, state, abis. These are all pretty familiar terms to users of Ethereum data. One other thing on this point. Most users probably won’t be quite so low level as the command line ‘chifra’ commands. Most will use the API and/or front end provided by the docker image and explorer respectively.

Is there any location where all the utilities are listed in one place?

There used to be — at the top level README file that you’re editing, but I removed all that so I could get to the introductory material. The folder structure along with a short explanation of each folder is below. The location for all utilities listed in one place (and the ultimate documentation) might parallel this structure ..

…

If so, I think that should go on the README too. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[tjayrush]

./trueblocks-core
├── bin:  Executable files — contents of this folder may be removed as they will be re-built.
│
├── docs: Holds all source code for auto-generated documentation. The actual documentation is in https://github.com/TrueBlocks/trueblocks-docs.
│
├── src:  Top-level folder for all source code
│   │
│   ├── apps: Accomplishes the primary functions of TrueBlocks (not open source licensed).
│   │   │
│   │   ├── acctExport:   The heart of TrueBlocks. This reads the indexed address appearances and exports specific data (tx, traces, accounting statements, etc) in any format (txt, csv, json).
│   │   ├── cacheStatus:  Reports on all aspects of the caches (blocks, tx, traces, monitors, abis, indexes, etc.).
│   │   └── chifra:       Overarching command-line tool for all other tools. A very thin layer that provides access under one umbrella.
│   │       └── internal: GoLang code for all tools and code ported away from C++ code.
│   │
│   ├── tools: Simple tools intended mostly to illustrate the use of the TrueBlocks libraries, each devoted to a particular part of the Ethereum data
│   │   │
│   │   ├── ethNames:     Manages mapping between Ethereum addresses and human readable names - customizable by end user for privacy.
│   │   ├── getBlock:     Extracts (and optionally caches) blocks (and any parts - tx, receipt, log, trace) by number, hash, or range. Optionally extracts address appearances.
│   │   ├── getTrans:     Extracts (and optionally caches) transactions (or any part) by tx.id, hash or range. Optionally extracts all address appearances.
│   │   ├── getReceipt:   Extracts (cached by txs) receipts by tx.id, hash or range. Optionally extracts all address appearances.
│   │   ├── getLogs:      Extracts (cached by txs) logs by tx.id, hash or range. Optionally extracts all address appearances.
│   │   ├── getTraces:    Extracts (and optionally caches) traces by tx.id, hash or range. Optionally extracts all address appearances.
│   │   ├── getState:     Extract state (nonce, balance, code, storage) of an Ethereum EOA or smart contract (excluding the account's list of historical transactions).
│   │   ├── getTokens:    Extra information about ERC20 or ERC721 tokens, its holders, balances, and related information.
│   │   ├── grabABI:      Get the programatic interface definition (ABI) for a given (or collection of) Ethereum smart contract(s)
│   │   └── ethslurp:     Fully optional component that provides simple Trueblocks-like queries to the Etherscan website. Useful in debugging and verifying Trueblocks data.
│   │
│   ├── libs: Various collections of useful code
│   │   │
│   │   ├── utillib:      Low level library to handle strings / time / caching-related code.
│   │   ├── etherlib:     A library related to interacting with and extracting or sending data to and from the Ethereum node.
│   │   ├── acctlib:      A library of code to manage Ethereum account state.
│   │   └── test-libs:    All library-related testing code.
│   │
│   ├── other: Shell scripts for testing and other useful code. Installation files including names database. Papers. Various playground experiments.
│   │   │
│   │   ├── articles:     Supporting data and early drafts of Medium and blog articles.
│   │   ├── build_assets: Various shell scripts, testing scripts).
│   │   ├── data-models:  Support for additional data models used in documentation but without the need for generated code.
│   │   ├── four_bytes:   Experiments in generating a four byte database.
│   │   ├── install:      Files needed during installation to establish a working system - a lot of this is simply copied on first build into ~/.quickBlocks folder).
│   │   └── papers:       Supporting data and early drafts of more academic articles.
│   │
│   ├── examples: Examples and tutorials. A bit out of date.
│   │
│   └── dev_tools: Development-related tools including a testing harness and automatic code generation tools.
│       │
│       ├── makeClass:    Reads class definition files and auto-generates a huge number of C++ files and headers for major classes in the libraries and many tools.
│       └── testRunner:   Runs all the tests based on .csv test files in ./dev_tools/testRunner/testCases...
│     
└── test: All test related output - tests run, produce files into the ‘working’ folder and compare themselves with identically named files in ‘gold’ folder. Test passes if files are identical. Fail otherwise.

[tjayrush]

From Mike Ghen:

Here are some additional export command examples I think would be helpful in the docs:

All mints from a token, would appear as inbound transfers from address(0)
All swaps on Uniswap for a specific token (Through the UniswapV2 router for example)
All internal Ethereum transfers

@tjayrush

(TrueBlocks/trueblocks-core#3301 (comment))
Thanks Mike. This is super helpful. I can add these to the website, under the blog, but before I do...help me with something...

I hired someone to write the website, so I don't know everything about it.

As you looked at our website, where did you find any existing example (if you found any at all on the website).

If you didn't find any existing examples on the website, where did you find them.

The reason I'm asking is because I'm looking for the most likely place to put new examples to make it easier for people.

[mikeghen]

@tjayrush Here's where I was looking for examples: https://trueblocks.io/chifra/using/, the tutorial.

I also think it would be helpful under the chifra export section of the docs: https://trueblocks.io/chifra/accounts/#chifra-export