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