Arching Kaos Tools ================== Introduction ------------ Tools that help you to create a blockchain called `zchain` by preparing small JSON objects that are pointing one to another in the following way: ``` ZBLOCK = BLOCK + SIGNATURE BLOCK = ACTION + DATA + DATA_SIGNATURE + TIMESTAMP + GPG + PREVIOUS_ZBLOCK DATA = IPFS_CID + SIGNATURE ( + key-pair values that are based on ACTION ) ``` Most of the times, IPFS_CID in DATA is expected to be a file. And the module is responsible for handling it properly. For the zchain to be valid, all the signatures must be verifiable against the provided GPG key. Description ----------- This is an installable repository which provides various tools for running Arching Kaos and using it. Generic tools: `enter` - Can be used to crawl zchains. `zchain-rebase` - Can be used to rebase your zchain to a previous zblock. `zchain-reset` - Can be used to reset your zchain to zgenesis. ACTION tools (modules): `mixtapes` and `news` - Can be used to add content to your zchain. `profile` - Can be used to build up a profile of the contributor. There are more tools available under the `bin` folder. Make sure you deeply understand what they are doing before using them. Changes are mentioned in `git log` of the repo, as well as in [CHANGELOG](https://github.com/arching-kaos/arching-kaos-tools/blob/master/CHANGELOG) file. Requirements ------------ Some Linux machine will propably work. It's tested under Fedora Linux. External programs used are: - bash (v5.1.8) or zsh (v5.8) - gpg (v2.3.4) - wget (v1.21.2) - curl (v7.79.1) - git (v2.34.1) - which (v2.21) - jq (v1.6) `json_pp` is also used put you cat remove it and change it with `jq` How to install the repository ----------------------------- Write on your terminal: ``` git clone https://github.com/arching-kaos/arching-kaos-tools cd arching-kaos-tools sh install.sh ``` If you encounter any errors, please open an issue. Update ------ Navigate to your cloned repository and execute the following commands: ``` git pull ./update.sh ``` Examples -------- ### Add a news article ( `news add` ) You could use ZCHAIN with NEWS model. Or MIXTAPE model, or make your own. ``` bash $ news create ``` This would pop up a vim editor for you to write a news article or whatever is text or markdown format with a title. Saving the file, will save it locally, add it to IPFS, sign it, pack detached signature with metadata on a JSON object. Then a block will be created packing your GPG public key, the news/add action with the JSON object and a detached signature of this, timestamp and finally an entry for the previous *zblock*. After that (!) we finally write this as a json object, add it to IPFS, sign it and pack a *zblock*. That, is published over our IPNS zchain key. Other options... let's try help! ``` console $ news help ak-news-cli -------------- #TODO All you need to know is that there are two options available: help Prints this help message index Prints an indexed table of your news files import #TODO add Creates a data file from the news file you point to create Vim is going to pop up, you will write and save your newsletter and it's going to be saved ``` Clearly there is a TODO item. Import is not working so avoid it, or fix it. Add is nice, you can add an already existing file directly. `news` is the second module after `mixtape`. Both modules need refactoring but they work at a level that someone can be productive with these tools. ### Explore chains ( `enter` ) You can view your zchain as a JSON object using `enter`. There are some flags in order to either view other zchains or change the depth of view ( includes or ignores data object and action ). ``` console $ enter -h enter - Crawl an arching kaos chain ----------------------------------- Usage: --help, -h Print this help and exit --chain , -n Crawl specified chain --show-zblocks-only, -z Show only zblocks --no-verify, -nV Don't verify signatures Specify IPFS CID for entrance Note that combined flags don't work for now Running with no flags crawls your chain ``` Podman (or Docker) ------------------ There is a ContainerFile that you can use to build an image which you can then deploy in a container. Use: ``` podman build -f ContainerFile -t arching-kaos-tools . ``` TODO ---- Next things to come are: - [ ] - zblock manipulator to fix wrong previous block references and repack zblocks. - [X] - zchain rebase-like procedure to move the zblocks to another seed or set another previous block (e.g. join chains) - [ ] - Clean up installation and filesystem usage - [ ] - Log rotate to gzip archives - [ ] - Filters for log searching for IPFS hashes or names - [ ] - Use of IPFS file system to store/pin sub chains, previous chains or other chains Concepts under thought ---------------------- - Base chain, derived from personal ones. - Daemon to monitor chains' states, update and sign new zblocks. - Find a minimum agreement of what is valid or not. (important) - Spam defence (e.g. how to protect the network from abuse cases) (important) - Reduce size of all parts of chain (stringify JSON) (improvement)