Arching Kaos Tools
==================
> Warning: The tools and the whole project is in an experimental state.
> Everything is subject to change.
> Hint: Find the "Script usage" section for sum up of the scripts
Introduction
------------
Tools that help 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. The module
that is embedded inside the `ACTION` field is responsible for handling it
properly.
For the zchain to be valid, all the signatures must be verifiable against the
provided `GPG` key that is included in the `BLOCK`.
For more information, refer to the `arching-kaos-infochain` repository.
Previous developments
---------------------
1. A proof of work blockchain is introduced to synchronize the zchains among
them.
2. A miner prototype is introduced as well.
3. From a directory full of blocks, find the latest block of the longest chain
4. API for calling some of the bash scripts
Description
-----------
This is an installable repository which provides various tools for running
Arching Kaos and using it.
Generic tools:
- `ak` - The tools wrapper
- `ak zchain --crawl` - Can be used to crawl zchains.
- `ak zchain --rebase` - Can be used to rebase your zchain to a previous zblock.
- `ak zchain --reset` - Can be used to reset your zchain to zgenesis.
Modules:
You can use previously known modules or make new ones and put them into your
`modules/` directory. The tree has to be the bare minimum of:
```
modules/
└─ <module name>
├─ lib.sh
└─ main.sh
```
- `mixtapes` and `news` - Can be used to add content to your zchain.
- `profile` - Can be used to build up a profile of the contributor.
Based on your GPG, zchain and other values provided by `profile`, you can create
with `akconfig` a pointer to some basic information that you can share with
others in order for them to crawl your zchain or view your "profile".
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 file.
Requirements
------------
Some Linux machine will propably work. It's tested under Fedora Linux. External
programs used are:
- bash (v5.1.8)
- gpg (v2.3.4)
- curl (v7.79.1)
- git (v2.34.1)
- which (v2.21)
- jq (v1.6)
- nodejs (v16+)
- npm (v9.5.0)
- npx (v9.5.0)
How to install the repository
-----------------------------
Write on your terminal:
```
git clone https://github.com/arching-kaos/arching-kaos-tools
cd arching-kaos-tools
./install.sh
```
If you encounter any errors, please open an issue.
For more extended description on the installation process, refer to `INSTALL`
file.
Update
------
Navigate to your cloned repository and execute the following commands:
```
git pull
./update.sh
```
Uninstall
---------
Navigate to your cloned repository and execute the following command:
```
./uninstall.sh
```
This will output an archive with your aknet-gpg-keyring to your $HOME folder.
It will NOT remove your IPFS repository, neither is going to clean it.
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 .
```
Specialized ContainerFiles are available in `./podman/` for various
distributions:
- alpine
- archlinux
- debian
- fedora
- opensuse
More over there are two scripts for testing with podman:
1. `./test_with_podman.sh` - build one or all images
2. `./full_test_with_podman.sh` - build one image and bash in it
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)
- [x] - Clean up installation and filesystem usage
- [x] - 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)
Scripts' description
--------------------
Utilities
---------
- ak-log # Logging tools
- ak-clean # Cleans up temporary folders created by these tools
- ak-config # Publish your configuration to IPNS
- ak-get-zlatest # Returns zlatest ZBLOCK according to IPFS FS
- ak-gpg # Return your GPG key as IPFS CID
- ak-network # Network Tools (connect to, scan for, dump peers)
- ak-node-info # Returns IPFS CID or IPNS key for your online config
- ak-sblock # sblock tools
- ak-schain # schain tools
- ak-zblock # zblock tools
- ak-zchain # zchain tools
Modules
-------
- comments # References a comment to a ZBLOCK
- files # Adds a file to the ZCHAIN
- mixtapes # Adds a mixtape to the ZCHAIN
- news # Adds a news article to the ZCHAIN
- profile # Adds key-value pairs to the ZCHAIN
- reference # Adds references to the ZCHAIN
- repositories # Adds repositories to the ZCHAIN
- transactions # Prototype of transactions in the ZCHAIN
- smfiles # Adds a split file's map to the ZCHAIN
- articles PROTO Adds an article to your ZCHAIN
- categories PROTO Adds or references categories to the ZCHAIN
- folders PROTO Adds a folder to the ZCHAIN
- roadmap PROTO Adds a roadmap to the ZCHAIN
- todos PROTO Adds todo list to the ZCHAIN
- follow PROTO Follow IPNS keys of ZCHAIN for changes
PROTO refers to a prototype implementation of the module
Read more at the `./MODULES` file
Experimental
------------
- ak-mempool # TODO
- ak-mine PROTO Prototype miner
- ak-get-balances # Returns a balances from SCHAIN
Libraries
---------
- lib/_ak_ipfs
- lib/_ak_fs
- lib/_ak_gpg
- lib/_ak_newline
- lib/_ak_network
- lib/_ak_script
- lib/_ak_log
- lib/_ak_smfiles
IPFS Wrappers
-------------
- ak-ipfs-starter
- ak-ipfs
Deprecated
----------
- ak-json2bash
Debugging
---------
Setting `AK_DEBUG` shell variable to `"yes"` will make all log messages to
appear on your stderr (file descriptor 2). After setting this variable, run the
tools you want.
Example:
``` console
AK_DEBUG="yes"; ak zchain --crawl -l 1
```
Examples
--------
### Add a news article ( `ak -m news --add` )
You could use ZCHAIN with NEWS model. Or MIXTAPE model, or make your own.
``` bash
$ ak -m 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*. The ZBLOCK is then published over our IPNS zchain key.
Other options... let's try help!
``` console
$ ak -m news -h
ak-news - Module to read, create and add zblocks
================================================
-h, --help Prints this help message
-l, --local-index Prints an indexed table of your news files
-i, --import <file> #TODO
-a, --add <file> Creates a data file from the news file you point to
-r, --read <zblock> Reads a zblock as a news data
-c, --create Vim is going to pop up, you will write and save your
newsletter and it's going to be saved
-s, --specs Print specs of data block
```
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 ( `ak-zchain --crawl` )
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
$ ak zchain --crawl -h
ak zchain --crawl [-N | --no-verify] [-l | --limit <number>] [zblock]
ak zchain --crawl [-N | --no-verify] [-l | --limit <number>] -n <zchain>
Usage:
--help, -h Print this help and exit
--chain <ipns-link>, -n <ipns-link> Crawl specified chain
--no-verify, -N Don't verify signatures
<ipfs-link> Specify IPFS CID for entrance
Note that combined flags don't work for now
Running with no flags crawls your chain based on AK_ZLATEST environment
variable
```
### Connect to networks ( `ak network` )
```console
$ ak network
ak-network - AK Nettool
=======================
Network tools
Usage:
-h, --help Prints this help message
-c, --connect [ipfs|cjdns] Connect to network(s)
-p, --peers [ipfs|cjdns|stellar] Outputs peers found
-s, --scan [ipfs|cjdns|stellar] Scan network(s) for peers
Bonus: CJDNS network scanning flags
-s, --scan cjdns [-w|--whole] Scan using HIA's knowledge
-s, --scan cjdns [-d|--dump] Scan using CJDNS' dumpLinks (default)
```
FS tools
--------
- ak-fs
```bash
$ ak fs --help
Tools to add, get and cat files to/from the Arching Kaos File System
Usage:
-h, --help Prints this help message
--add, --import <file> Adds/Imports a file to the AKFS system
--get, --export <hash> <output file> Exports a file from the AKFS system
--cat <hash> Concatenates from given hash
```
