File System Example

The precise organisation of the exported files can be anything. We show an example structure that happens to be assumed by the tools included in this package, but this has no status and serves purely as an example.

A node in the Carbon Budget Open Data is described as "self" with a number of relations to other parties. The output of a time state is in one file that holds a JSON data structure and a PGP signature. History is a numbered sequence of these structures. This is rather flat, and can be represented in one directory.

  • 123.json.asc is the file with "seqnr": 123 in its "meta" structure.

  • latest.json.asc is a symbolic link to the latest public version.

  • greatest.json.asc is an optional symbolic link to the last correct version and will be used instead of lastest.json.asc to derive the "correct" value for the next iteration. It may be observed from the outside, though it provides no guarantees.

  • *uuid*.move-123json is a budget move relative to the 123.json.asc predecessor. Replace *uuid* with an arbitrary UUID in standard textual form. These are difficult to guess externally, have no meaning in the data structure, but may be explicitly shared with others for inspection. Values in these files can be negative, because they are to be added to an existing balance; only when the overall result ends in a negative value will an error ensue.

  • public-key.json is the public key used for the node, and can be stored in that fixed filename. Note that this does not occur in the naming schemes otherwise used. The location can be used in the node documentation.

  • 124.json is the pre-signing file for 124.json.asc and PGP can be used in the normal mode to produce a clear-signed file for publication. It is usually formed by starting with the greatest or latest predecessor, add 1 to the latest sequence number and introduce any *uuid*.json forms. When publishing, the (older) files *uuid*.json are removed and latest.json.asc is made to reference this new one, but this is blocked when the node is not in proper (internal) balance.

This integrates nicely with a standard web environment.

  • The .json and certainly the .json.asc extensions are uncommon on a web server, and not likely to coincide with files from web packages.

  • The .json.asc extension will not usually exist, but may be madded to the text/plain page type, while .json probably maps to application/json by default.

  • The move of latest.json.asc is atomic, namely by changing a symbolic link. The file underneath can be properly prepared, chacked, and finally published.

  • index.html can simply be added, and also index.en.html and so on, to support web servers in presenting a friendly introduction to the files, possibly even with JavaScript code to unravel the latest.json.asc data.

  • An E-Tag can be generated for the changing symbolic link, and it would be different after moving the link. For the historic files it would not see changes, and would yield a constant E-Tag.

  • It is perfectly possible to add latest.json.asc as an index file for the directory in the web server. This would cause it to yield the dynamic latest data on loading the directory, which "feels right". The underlying information files however, remain static as history ought to be.

The MQTT structures will be very similar to those of HTTP.

External Domains

A suggested layout for a web service may incorporate the local domain and others that it (indirectly) references to. This would produce a directory layer in the URL, before the aforementioned filenames. The domain of the "self" node may be followed by default if the server's / URL path is addressed.

This structure can in fact be a virtual server hosting multiple domains, and using the other domains, whether hosted or not, as extra information, even if it is served from the same virtual host and some if it is considered the primary domain (and a redirection for the / URL path) in other virtual hosts.

External Domains, especially for direct peers, are generally useful to allow external balance checking. It is possible to track external domains live with a subscription to its MQTT data. It is highly probably that this will also be done by independent auditing parties.

Tools

A couple of useful tools (to be) included in this package:

  • carbon-balance-check checks one .json or .json.asc file for internal balance.

  • carbon-init-self sets up a new directory with a zeroed initial balance.

  • carbon-move-budget extracts budget from some places, and inserts it elsewhere, storing a *uuid*.json file with the difference.

  • carbon-collect adds the *uuid*.move-123.json files to the greatest.json.asc and produces the following 124.json file. It then runs carbon-balance-check against that file. It removes the collected .json files but will keep any .json.asc files that may have been derived from them.

  • carbon-publish links latest.json.asc to the highest 124.json.asc file, demands no higher 125.json file, removes those *uuid*.json files that are older than 124.json or else 124.json.asc. All this is preceded by a carbon-balance-check on the 124.json.asc file.

  • carbon-diff outputs a difference between two file versions. It may be written to a *uuid*.json file if so desired. Its values may be negative.