Modules ------- This is a more descriptive text file regarding the previously mentioned modules in the README file. While refactoring might be changing or work on its modules' code, the most significant product of them is packing the actual data and optionally other info or metadata about the data. As also mentioned already in the README file, a block holds the "action", "data" and "data_signature"[1] fields. Apart from the "data_signature" which is the cryptographic signature of the publisher upon the "data" field, the "action" field is a "reminder" to figure out which module produced the "data" field found in the same block. While the first grasping of the implementation was thought like "action" a not implied but surely needed field was also the name of the module. To do that, a divider of '/' was used to separate the value into two. The general rule is that the "action" field should actually be formatted as "module/action". Also, `ak enter` output makes that into two separate values. Grammatically speaking the form of an action is like "subject/verb" where the implied object is the "data" field. Moreover, the "data" field will be a hash pointing to some object which should be consisting of two fields at least: "ipfs" and "detach". The "ipfs" field is containing a hash pointing to file while "detach" holds the detached signature of the publisher against the file mentioned in the "ipfs" field. Finally, modules are stored at your $AK_MODULESDIR directory which by default is set to your $AK_WORKDIR/modules directory during install and can be executed as command line tools like this: ```bash ak -m [arguments] ``` I think that all to it, so with no further delay let's move to the modules coming with this repository! ## articles Prototype - Adds an article to your ZCHAIN It's supposed to be doing that, however the code is copied from the `news` module which is stable in some extend but it has incorporated some shortcomings and previously put thoughts into the module that are not considered to be at all checked lately as for if it's working or not. In other words, use the `news` module instead or make a PR if you happened to fix it. ## categories Prototype - Adds or references categories to the ZCHAIN It is also supposed to be doing that, haven't checked lately though. The idea to create a category, a tag if you may or a label either in general to use later in your ZCHAIN, or directly reference it to some other ZBLOCK. It is NOT thoroughly tested. ## comments References a comment to a ZBLOCK That is indeed working! Commenting on ZBLOCKS with this module is using the `references` module to combine the ZBLOCK containing the comment and the ZBLOCK hash that we comment upon. ## files Adds a file to the ZCHAIN It really does! Or did! Anyhow, the focus was then moved to `sm-files` and the whole AKFS story which might be interesting to read.[2] ## folders Prototype - Adds a folder to the ZCHAIN This is a script serving as a note to implement this. The hard part is how you can verify with a detached signature a whole folder. Also, "folder" should be "directory" instead but all hyped about the `files` module, I just made a copy of it to make the same but different. Only I don't remember doing that much about it. Also also, see the `sm-files` and AKFS stories as well. ## mixtapes Adds a mixtape to the ZCHAIN That's the first module developed. Remember, arching kaos is about a radio station. The point of this module is that whichever turn I turn to, this module is the bare minimum of working. So good news, everyone! A fully functional module. Below, the help message as seen when issuing the command: ``` $ ak -m mixtapes --help main.sh - AK mixtape block creator ================================== The following creates a mixtape data message Usage: -a <file> Adds a file with tags artist and title -h , --help -s , --specs ``` As you can see the bare minimum for a module is indeed to add something to the ZCHAIN. According to the arching-kaos-v1 non existing specification, the file has to be an Ogg Vorbis file encoded around 128-192kbits. The file should be around 1 hour with an upper limit to possibly 2 hours (which I propose now). As we can not enforce mixtapes being exactly 1 hour or 2 hours, we could measure the "hourly-limit" as ±15minues or even ±30minutes to loosen a check on duration on further developing the module. Note that such limits and/or checks do not happen. We blindly believe that the mixtape in the ZBLOCK will indeed be an audio mix which is kinda hard to guard. Also, in good faith, the module will be used by people that want to make this kind of publications. If bad people were to publish something outside the subject of the module, they would easily forge their own ZBLOCKS and spam[3] them. ## news Adds a news article to the ZCHAIN As mentioned already, unless you are skipping stuff, `news` is the second module created. No, I didn't say that before. Anyhow, the `news` module was initially a way to post news about the developments of the project. That happens from times to times, but of course arching kaos wouldn't be that if everything was kept together in a centralized manner. Long story, short, there are various places to get your arching kaos related news. Second anyhow, that paragraph got big. ``` $ ak -m news --help main.sh - 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 bei saved -s, --specs Print specs of data block -x, --html <zblock> Returns an appropriate html element from a NEWS zblock ``` So what you see here is that with text the thing got a bit more interesting. Still `--import` is a TODO which I also wonder if it's the same with `--add`. Good flags for sure are: - `--create`, - `--html`, - `--read`, - `--specs` and - `--local-index` ## profile Adds key-value pairs to the ZCHAIN Does what is says. ``` $ ak -m profile --help ak-profile - Profile module =========================== Indexes, shows, imports, adds, sets and gets values from and to the zchain and files. Usage: -h, --help Prints this help message -i, --index Show current status --show <data IPFS CIDv0> Show profile entry from specified DATA IPFS CIDv0 -s, --set <property> <value> Sets a profile value -g, --get <property> Gets a profile value from the on-disk file. Advanced (use with caution may produce duplicate entries): -a, --add <file> Creates a data file from the profile file you point (file should already be in ZPROFILEDIR). -i, --import <folder> Import a folder to zchain #TODO ``` Good flags: - `--set`, - `--get` and - `--index` ## reference Adds references to the ZCHAIN ``` $ ak -m reference --help main.sh - Quick description =========================== #TODO All you need to know is that there are two options available: -h, --help Prints this help message index Prints an indexed table of your references files import <file> #TODO add <file> Creates a data file from the references file you point to create [ref] [to] Vim is going to pop up, you will write and save your referencesletter and it's going to be saved ``` Good flags: - `create` ## repositories Adds repositories to the ZCHAIN The way we handle repositories (git repositories to be clear) is with making a bare clone of it and make an IPNS key for each of those. Since the first thought several occured so, spoiler alert, at some point a `patch` module will happen. ``` $ ak -m repositories --help -h, --help index | add | publish | update ``` Far minimal approach on the usage screen hard to remember by heart. TODO Research this code to figure out what I am actually doing TODO Possibly it doesn't use `$AK_LIBDIR/_ak_script` ## roadmap Prototype - Adds a roadmap to the ZCHAIN The drive for that was trac, that enhanced wiki and issue tracker for software development projects. ## transactions Prototype of transactions in the ZCHAIN No checks no nothings, it is like saying I give you 30. No unit, no check for validity, nothing. This will be useful when SCHAIN is further developed. ## sm-files Adds a split file's map to the ZCHAIN So after the great success on `files` module, I started thinking about how files are moving around into pieces all over the networks and media which are then reconstructed into one single file. ``` $ ak-sm-files --help ak-sm-files - file -h, --help Prints this help message add <file> Adds file to zchain as a zblock index List files full-index List all files ls-map-files List map files ``` As we can see, still... TODO Possibly it doesn't use `$AK_LIBDIR/_ak_script` Other than that, we see the 3 indexing options and the one `add` that would be a prototype of the idea leading to AKFS. Really, go ahead and read that at some point if you haven't already done so. In other words, this module is in unknown state. TODO Figure out maps for the AKFS files ## todos Prototype - Adds todo list to the ZCHAIN As you have already witnessed, prototype is another way of telling "will do" or "here is an idea". ## follow Prototype - Follows something! "Something" is completely accurate at this point as it is following nothing in particular. The purpose of introducing it was to be able to add a "follow/add" block to your chain, so in some sense to inform others that others exist too and you "follow" them as in the "social media" terminology. The place from which you are doing it though is vague. The first thought was to have the `ak-config` IPNS key in the list. An update on that key would fetch you the new latest of the zchain that this key point to, hence, being able to crawl the latest version of it. That was mostly cause the 'ak-config' output would be something like this: ```json { "profile": { "nickname": "someone", }, "genesis": "QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH", "gpg": "42A...", "zchain": "k51q...", "zlatest": "Qm..." } ``` Other than publishing that you follow or unfollow someone's ak-config IPNS key, the module doesn't do anything else. Privacy-wise, someone would not like to let others know what their follow list is. ## Notes - [1] "data_signature" is labeled as "detach" inside the block. - [2] README file mentions that the whole project is in experimental state, btw - [3] Read more at the NETWORKING file to understand how discoverability works