chaintool-doc

Chaintool documentation
Info | Log | Files | Refs | README | LICENSE

README.in (5230B)

      1 # Chaintool documentation
      2 
      3 Chaintool is still very much a work-in-progress. So too is its documentation.
      4 
      5 This README, while still somewhat chaotic, aims to fill the void of a missing structured presentation, and make the introduction to chaintool a bit more friendly.
      6 
      7 
      8 ## Showcasing chaintool
      9 
     10 The most intuitive entry point to chaintool is most likely the `eth-monitor` tool. It can be installed directly from `pypi` using `pip install eth-monitor`.
     11 
     12 <video width="800" height="450" controls>
     13     <source src="https://defalsify.org/chaintool_pychain_pitch.mp4">
     14 Your browser cannot embed this video. Please use the links below instead.
     15 </video>
     16 
     17 Source:
     18 
     19 * [video file](https://defalsify.org/chaintool_pychain_pitch.mp4)
     20 * [video file signatures](https://defalsify.org/chaintool_pychain_pitch.mp4.asc)
     21 
     22 ## Code components
     23 
     24 Upstream souce of chaintool code is located at [git.defalsify.org](https://git.defalsify.org)
     25 
     26 
     27 ### Core layer
     28 
     29 All libraries that are considered part of the `chaintool` suite:
     30 
     31 * **funga**, **funga-eth** - message signing tools and daemon for development, with implementation for EVM.
     32 * **chainlib**, **chainlib-eth** - blockchain RPC interface with tooling and implementation for EVM nodes.
     33 * **chainsyncer** - blockchain RPC transaction sync driver.
     34 * **chainqueue** - blockchain RPC transaction queue control.
     35 * **eth-cache** - transparent proxy that stores local copies of RPC results.
     36 
     37 
     38 ### Higher layer
     39 
     40 Tools and daemons building on the core layer.
     41 
     42 * **eth-monitor** - Visualization and arbitrary code execution for mined transactions
     43 * **chaind**, **chaind-eth** - Full-duplex transaction queueing tool for ethereum
     44 
     45 
     46 ### Lower layer
     47 
     48 Libraries that were developed within the context of `chaintool`, but have a more generic scope.
     49 
     50 * **shep** - Multi-state key/value stores using bit masks.
     51 * **confini** - Parse and merge multiple ini files.
     52 * **aiee** - Common command line interfacing utils.
     53 * **leveldir** - Multi-level directory structure data stores.
     54 * **hexathon** - Common and uncommon hex string operations.
     55 * **potaahto** - Essentially: Convert between snake and camel case.
     56 
     57 The upstream code of these lower layer modules can be found at [holbrook.no/src](https://holbrook.no/src)
     58 
     59 
     60 ## Documentation for chaintool
     61 
     62 
     63 So far, documentation efforts have been made in four areas, in order of most recently updated first:
     64 
     65 
     66 ### Code components diagram
     67 
     68 Last time the author remembered to render it, it looked like this:
     69 
     70 <img src="@IMG_URL@" />
     71 
     72 The dependency graph is only available in as an unformatted **graphviz** document located at `$REPO_ROOT/deps.dot`. `make diagram` renders this SVG version.
     73 
     74 
     75 ### Man pages
     76 
     77 The `chainlib` module provides the script `chainlib-man.py` which provides an inheritance approach to generate man pages for CLI tools that build on the library.
     78 
     79 An immediate example can be found in the `chainlib-eth` repository, where the directory `$REPO_ROOT/man` demonstrates how to add hooks for overriding both section contents and argument options for individual tools.
     80 
     81 What override behavior is currently available should be straightforward to glean from reading the `$CHAINLIB_REPO_ROOT/scripts/chainlib-man.py` script.
     82 
     83 Invoking `make man` in the `chainlib-eth` and `eth-monitor` repositories will trigger a build of man pages for all the CLI tools provided.
     84 
     85 
     86 ### Descriptive documentation
     87 
     88 Some initial work for high-level documentation exists in the chainlib repository, specifically in `$REPO_ROOT/doc/texinfo`.
     89 
     90 The documentation can be generated by running `make doc` in the `$REPO_ROOT` of **this** repository. The HTML version of the documentation will be output as a single file to `$REPO_ROOT/build/out/index.html`
     91 
     92 
     93 ### Docstrings
     94 
     95 Not much to add here. Ye generic sphinx-doc invocation should do the trick.
     96 
     97 
     98 ## High-level implementations
     99 
    100 To compensate somewhat for the lack of exhaustive documentation, actual implementations using the library may help light the way somewhat.
    101 
    102 Aside from the "higher level" components listed above, two known EVM-based implementations that have some minimum level of maturity are:
    103 
    104 * [eth-erc20](https://git.defalsify.org/eth-erc20) - an implementation of the ERC20 token, which also includes an example token contract that lets authorized addresses arbitrarily mint tokens at any time.
    105 * [eth-erc721](https://git.defalsify.org/eth-erc721) - an implementation of the ERC721 "NFT" token, which also includes an example token contract that creates achievment badges for developed contributions.
    106 
    107 
    108 ## Known issues
    109 
    110 The requirements for testing (`test_requirements.txt`) under each repository include dependencies that use rust components which use unstable features.
    111 
    112 The authors have used a "nightly" toolchain provided by the [rustup](https://rustup.rs/) tool to build test requirements. However, this is failing with newer versions of the rust toolchain.
    113 
    114 The authors report having successfully built with the `nightly-2022-11-14` toolchain. Hopefully this will work for others aswell.
    115 
    116 If any other toolchain is succesfully used, please report this and/or submit a git diff of this documentation including the most recent compatible toolchain to: [chaintool@defalsify.org](mailto:chaintool@defalsify.org).
    117