diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 363 |
1 files changed, 211 insertions, 152 deletions
@@ -8,18 +8,21 @@ 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: +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. And the module -is responsible for handling it properly. +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. +provided `GPG` key that is included in the `BLOCK`. + +For more information, refer to the `arching-kaos-infochain` repository. Previous developments --------------------- @@ -29,7 +32,6 @@ Previous developments 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 @@ -69,18 +71,16 @@ programs used are: - bash (v5.1.8) - gpg (v2.3.4) -- wget (v1.21.2) - curl (v7.79.1) - git (v2.34.1) - which (v2.21) - jq (v1.6) -- nodejs (v18.14) +- 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 @@ -95,16 +95,15 @@ 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: ``` @@ -114,100 +113,8 @@ 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. -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) -``` - Podman (or Docker) ------------------ - There is a ContainerFile that you can use to build an image which you can then deploy in a container. @@ -231,7 +138,6 @@ More over there are two scripts for testing with podman: TODO ---- - Next things to come are: - [ ] - zblock manipulator to fix wrong previous block references and repack zblocks. @@ -240,20 +146,19 @@ Next things to come are: - [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 +- [ ] - ~~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) -Script usage ------------- +Scripts' description +-------------------- Utilities --------- @@ -264,75 +169,79 @@ Utilities - 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-pkg # Package manager - ak-sblock # sblock tools - ak-schain # schain tools - ak-zblock # zblock tools - ak-zchain # zchain tools -Experimental ------------- - - ak-mempool # TODO - - ak-mine PROTO Prototype miner - - ak-get-balances # Returns a balances from SCHAIN - Modules ------- - - articles PROTO Adds an article to your ZCHAIN - - categories PROTO Adds or references categories to the ZCHAIN - comments # References a comment to a ZBLOCK - files # Adds a file to the ZCHAIN - - folders PROTO Adds a folder 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 - - roadmap PROTO Adds a roadmap 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 + - encrypted # Encrypts data and publishes to ZCHAIN + - markdown # Adds markdown documents to ZCHAIN - Read more at the `./MODULES` file - -FS tools --------- - - ak-fs - -```bash -$ ak fs --help +PROTO refers to a prototype implementation of the module +Read more at the `./MODULES` file -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 -``` +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_checks + - lib/_ak_cjdns + - lib/_ak_coin + - lib/_ak_sblock + - lib/_ak_schain + - lib/_ak_smfiles + - lib/_ak_wallet + - lib/_ak_network_stellar + - lib/_ak_network_ipfs + - lib/_ak_sh + - lib/_ak_html - lib/_ak_network + - lib/_ak_network_cjdns + - lib/_ak_config + - lib/_ak_node + - lib/_ak_irc + - lib/_ak_maintainance - lib/_ak_script + - lib/_ak_fm + - lib/_ak_yggdrasil + - lib/_ak_hash_exchange + - lib/_ak_zchain + - lib/_ak_network_yggdrasil + - lib/_ak_utils + - lib/_ak_ipfs + - lib/_ak_settings + - lib/_ak_gpg + - lib/_ak_fs + - lib/_ak_pkg + - lib/_ak_zblock - lib/_ak_log - - lib/_ak_smfiles - -IPFS Wrappers -------------- - - ak-ipfs-starter - - ak-ipfs-daemon -Not completed or just odd -------------------------- +Wrappers +-------- + - `ak-ipfs -r` + - `ak-gpg -r` Deprecated ---------- @@ -341,7 +250,6 @@ Deprecated 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. @@ -351,3 +259,154 @@ Example: 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|yggdrasil|incoming] Outputs peers found +# -s, --scan [ipfs|cjdns|stellar|yggdrasil|incoming] Scan network(s) for peers +# +# Bonus: CJDNS network scanning modes +# +# -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 +# ak-fs - AKFS tools +# ================== +# +# 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 <roothash> <output file> Exports a file from the AKFS system +# --cat <roothash> Concatenates from given hash +# --list Lists names and roots available +# --net-cat-from-map <maphash> Concatenates from map via the network +# --net-get-from-map <maphash> Downloads from map via the network +# --cfm <maphash> Concatenates from map +# --gfm <maphash> Get file from map +# +``` + +Package manager +--------------- + - ak-pkg + +```bash +$ ak pkg --help +# ak-pkg - Package Manager +# ======================== +# +# Manager of packages that can be installed and run as modules invoking the +# `ak -m <module>` sequence. +# +# Usage: +# +# -h, --help Prints this help message +# --make-releases-from-local Makes releases from all local installation's module +# --make-release-from-local Makes release from a local installation's module +# --install-from-zblock <zblock> Installs from a zblock +# --install-from-akfs <maphash> Installs from an AKFS map +# --uninstall Uninstalls a module selected from a menu +# +``` + +Donations +--------- +While this project is developed with enthusiasm and it uses the spare time of +the only developer that is coding for it, donations would help allocating more +time on the project instead of the developer looking for different occupations +to support their life and project. + +If you do appreciate the project's goals and the developers efforts towards it, +take your time and consider donating some satoshis to the developer via BTC at +the following address + +``` +bc1q70rgp65t7acfgpwp74m7vdz0g4eduxm6a43gd8 +``` + +Thank you! |