NESTS - Named Entities in Simple Tiered Spaces

Command line interface

This document lists the command line functions available to NESTS users with different privilege levels.

NB, this document was created well before work started on coding the CLI functions. It is currently undergoing a major revision while the CLI functions and their tests are being written.

Therefore expect to find inconsistencies and omissions, especially in the numbering of the footnotes.

The first stable version is expected to be available soon.

This is currently a very limited set of functions, sufficient to meet the needs of an open money implementation but not yet for open measures.

There are two classes of user functions:

  1. Lower-level functions providing a CLI to the NESTS core library.

    These are scripts written in the same language as the NESTS core and all have *nix permission 0550.

  2. Shell script wrappers to enable remote calls to the NESTS CLI over SSH.

    These are created indvidually for each user to whom an SSH login account has been assigned 4.2.c, containing a unique authentication code generated automatically, and have *nix permission 0500.

Any user becomes a steward 5 once having been authorized to create an entity (whether a secondary identity), an account, a currency or a child namespace. That authorization comes from the steward(s) 5 of the namespace enclosing the new entity and they/it can suspend or revoke such authorization.

Notes:

  1. The initial implementation is written in Python, but its modular design makes it fairly easy to re-write components in Rust, Perl or Ruby. In due course, some additional components may be written in R.

  2. Most users are unlikely to have any use for command line execution over SSH, but for some it will provide a convenient, powerful and scriptable interface.

  3. It may be sufficient to set the permissions on such scripts to 0500, but at the very least a restricted login shell should be assigned in /etc/passwd and a better solution might be to write an ad hoc script for use as the login shell, allowing only the execution of the commands in this group and possibly combining them into a single script for the purpose. This will require some experimentation.

  4. The steward(s) of each namespace can choose whether the default policy is

    • permissive - authorizing immediate creation of a new entity in that namespace and revoking the authorization when a need arises
    or
    • restrictive - authorizing creation of any new entity in that namespace only after a request has been received and subsequently revoking the authorization when necessary.

    The policy 9 can be configured differently for each entity. For example, it might present too great an oversight burden to require explicit authorization from the steward(s) of that namespace each time a secondary identity, an account or a currency is created there.

    On the other hand, the creation of child namespaces requires more sensitivity to the needs of others, especially where assigned to a geographical equivalence (which may be a genuine needs case for some form of regional governance collective).

    Furthermore, authorization of the creation of a new account must also come from a steward 5 of the associated currency. Therefore a sensible default policy 9 might be

    • permissive authorization from the namespace steward(s)
    • restrictive authorization from the currency steward(s)


Table 1: commands available to users

This table lists the shell commands any registered NESTS user (i.e. having a primary identity) can use.

These include commands for the creation of a secondary identity, account, currency or namespace - each involving an implicit request to the stewards of that entity's parent namespace or, for an account, the stewards of the associated currency. Upon authorization, the user issuing such a request becomes the steward of that new entity. Therefore the only distinction between a steward and any other user (identity-holder) lies in the holding of stewardship within a particular domain.

Within the domain of entities 1 over which they hold stewardship, users have additonial commands available. Furthermore, the domain of currency stewards differs from that of namespace stewards.

An account lies almost exclusively within the domain of the identity to which it belongs. However, the stewards of the namespace in which it is contained and of the associated currency have a limited and conditional domain here as well when necessary, to suspend activity or to examine ledgers, but never to modify the value of an account in anyway that. Modification of an account is exclusively the right of its owner or, where granted, another identity to which write/update access has been granted (a situation unlikely to arise with any frequency but which may occasionally be useful).

available to
primary identity
secondary identity
namespace steward
currency steward
system administrator
command option parameter description
accounts
nests_list_own_accounts --show-balances List the accounts (by FPH or HRNS) belonging to the identity requesting. y y
--list-fph
--human-readable
-u | --identity-fph <requester identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_list_accounts_in_currency -c | --currency-fph <currency FPH>

List the accounts (by FPH or HRNS) associated with the currency specified.

The requesting identity must be a steward of that currency. Otherwise an error message is returned.

y
--show-balances
--list-fph
--human-readable
-u | --identity-fph <steward identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_list_accounts_in_namespace -n | --namespace-fph <namespace FPH>

List the accounts (by FPH or HRNS) contained within the namespace specified.

The requesting identity must be a steward of that namespace. Otherwise an error message is returned.

y
--show-balances
--list-fph
--human-readable
-u | --identity-fph <steward identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_pay -f | --payer-fph <payer account FPH> 2.c

Make a payment 7 from one account to another in the same currency. 6

Returns (to STDOUT, as a JSON structure) the record appended to the transaction journals of the payer, the payee and the currency's stewards.

y y n n n
-t | --payee-fph <payee account FPH> 2.c
-A | --amount <amount> 6
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_set_value 10 -a | --account-fph <account FPH> 2.c

Set the value of an account (scalar, vector or matrix).

The account FPH may be passed either to STDIN or via the -a | --account-fph parameter.

y y n n n
-A | --amount <amount> 6.a, 7
-S | --scalar <scalar value> 6.a
-V | --vector <vector value> 6.b
-M | --matrix <matrix value> 6.c
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_add_value 10 -a | --account-fph <account FPH> 2.c Add the value specified to an account (scalar, vector or matrix). y y n n n
-A | --amount <amount> 6.a, 7
-S | --scalar <scalar value> 6.a
-V | --vector <vector value> 6.b
-M | --matrix <matrix value> 6.c
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_subtract_value 10 -a | --account-fph <account FPH> 2.c

Subtract the value specified from an account (scalar, vector or matrix).

The account FPH may be passed either to STDIN or via the -a | --account-fph parameter.

y y n n n
-A | --amount <amount> 6.a, 7
-S | --scalar <scalar value> 6.a
-V | --vector <vector value> 6.b
-M | --matrix <matrix value> 6.c
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_multiply_by_value 10 -a | --account-fph <account FPH> 2.c

Multiply the account value (scalar, vector or matrix) by value the specified (scalar, vector or matrix).

The account FPH may be passed either to STDIN or via the -a | --account-fph parameter.

y y n n n
-S | --scalar <scalar value> 6.a
-V | --vector <vector value> 6.b
-M | --matrix <matrix value> 6.c
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_current_value 11 -a | --account-fph <account FPH> 2.c

Export 9 a JSON object showing the current state 10 of an account identified by FPH 2.c.

The account FPH may be passed either to STDIN or via the -a | --account-fph parameter.

y y y y y
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_list_transactions -a | --account-fph <account FPH> 2.c

List all transactions (CSV dump) on this account identified by FPH 2.c.

This action can be initated only by the account holder.

The transactions are exported as CSV.

y y n n n
-D | --starting <start date> 8
-E | --ending <end date> 8
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_create -Z | --account-name <account name>

An account is created in the specified namespace 1.a and associated with the specified currency 6.

The FPH of the account is returned as STDOUT.

y y n n y
-n | --namespace-fph <namespace FPH> 2.c
-c | --currency-fph <currency FPH> 2.c
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_suspend 12 -a | --account-fph <account FPH> 6

Disable/suspend a account.

n n y y y
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_enable 12 -a | --account-fph <account FPH> 2.c

Re-enable a account.

n n y y y
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_delete 12 -a | --account-fph <account FPH> 2.c

Delete account.

n n y y y
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_authorize_access -a | --account-fph <account FPH> 6 Authorize account access to the identity (primary or secondary). n n y n n
--identity <share identity FPH>
--read-only
--read-write
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_list_access -a | --account-fph <account FPH> 6 List identities to which account access has been authorized. n n y n n
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_account_authorize_creation -a | --account-fph <account FPH> 6 Authorize creation of account identified by FPH (STDIN). n n y n n
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
currencies
nests_currency_list_transactions 12, 13 -c | --currency-fph <currency FPH> 2.c

Export a CSV dump of all transactions on all accounts in a currency identified by FPH.

This action can be initated only by a steward of the currency or by a steward 5 of the containing namespace or one of its ancestors.

n n n y y
-D | --starting <start date> 9
-E | --ending <end date> 9
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_list_currency_stewards -c | --currency <currecncy FPH>

List all identities having stewardship of the specified currency. The listing may be restricted to a specified parent namespace if specified.

n n n y y
-n | --namespace <parent namespace FPH>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_list_own_currencies -n | --namespace <parent namespace FPH>

Export a CSV dump of all currencies over which the querying identity holds stewardship. The listing may be restricted to a specified parent namespace if specified.

n n n y y
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_currencies_list_available 14 -u | --identity-fph <user identity FPH> 2.c

List (potentially) available currencies to STDOUT.

These currencies may be listed either by their full human-readable name.namespace string (--hrn - the default behaviour) or by their FPH (--fph).

y y y n y
--hrn
--fph
--csv
--json
--permissiveness
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_currencies_list_prototypes 12 -u | --identity-fph <user identity FPH> 2.c List valid currency prototypes to STDOUT. y y y n y
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_currency_create 12 -C | --currency-name <currency name>

A currency of the type specified 6 is created and the initial stewardship 5 is assigned to the steward specified.

The currency's name is specified as a human-readable string while its namespace is specified by FPH.

The FPH 2.c of the new currency is returned as STDOUT.

y y y n y
-n | --namespace-fph <namespace FPH> 2.c
-s | --steward <steward FPH> 2.c, 17 [1 or more]
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_currency_suspend 12 -c | --currency-fph <currency FPH> 6

Disable/suspend a currency.

n n y y y
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_currency_enable 12 -c | --currency-fph <currency FPH> 2.c

Re-enable a currency.

n n y y y
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_currency_delete 12 -c | --currency-fph <currency FPH> 2.c

Delete currency.

n n y y y
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_currency_authorize_creation 12 -c | --currency-fph <currency FPH> Authorize creation of currency identified by FPH (STDIN). n n y n n
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_currency_set_policy 12 -c | --currency-fph <currency FPH> 2.c

Define the policy for the creation of accounts in this currency. 6

n n y y y
-l | --permissive
-r | --restrictive
-i | --inherited inherited 9
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
identities
nests_identity_create_primary -U | --identity-hrn <username> 2.a

A primary identity 1.b is created in the specified namespace 1.a.

The FPH 2.c of the new primary identity is returned as STDOUT.

If the primary identity exists already, the same command can be used to modify its properties.

n n y n y
-n | --namespace-fph <namespace FPH> 2.c
-P | --password <password> 4.2.a
-e | --email <email> 4.1.b
-T | --phone <mobile phone number> 4.1.c
-F | --surname <surname> 4.1.a
-G | --forenames <forename> 4.1.a
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_identity_create_secondary -u | --identity-fph <alias> 2.a

A secondary identity 2.a is created in the specified namespace 1.a and associated with the specified primary identity.

y n y n y
-n | --namespace-fph <namespace FPH> 2.c
-I | --primary-identity <primary identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_list_secondary_identities -u | --identity-fph <requester identity FPH>

List all secondary identities linked to the querying identity (whether primary or secondary) querying identity holds stewardship.

n n n y y
-n | --namespace <parent namespace FPH>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_identity_authorize_creation -u | --identity-fph <identity FPH> 4.2.c Authorize creation of primary identity or secondary identity identified by FPH 2.c (STDIN). n n y n n
-q | --notes <optional notes>
-p | --auth <authentication code> 4.2.c
-u | --identity-fph <user identity FPH> 2.c
-h | --help
-v | --version
nests_identity_suspend 12 -u | --identity-fph <identity FPH> 6

Disable/suspend a identity.

n n y y y
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_identity_enable 12 -u | --identity-fph <identity FPH> 2.c

Re-enable a identity.

n n y y y
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_identity_delete 12 -u | --identity-fph <identity FPH> 2.c

Delete identity.

n n y y y
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
namespaces
nests_list_own_namespaces -n | --namespace <parent namespace FPH>

Export a CSV dump of all namespaces over which the querying identity holds stewardship. The listing may be restricted to a specified parent namespace if specified.

n n n y y
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_namespace_create -N | --namespace-name <namespace name>

A namespace 2.a is created and the initial stewardship 5 is assigned to the stewards specified. 19

The FPH of the new namespace is returned as STDOUT.

y y y n y
-n | --namespace-fph <parent namespace FPH>
-s | --steward <steward FPH> 2.c, 17 [1 or more]
--root-namespace 19
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_namespace_authorize_creation -n | --namespace-fph <namspace FPH> Authorize creation of namespace identified by FPH (STDIN). n n y n n
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_namespace_suspend -n | --namespace-fph <namespace FPH> 2.c

Disable/suspend a namespace.

n n y y y
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_namespace_enable -n | --namespace-fph <namespace FPH> 2.c

Re-enable a namespace.

n n y y y
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_namespace_delete -n | --namespace-fph <namespace FPH> 2.c

Archive and delete a namespace along with all of its descendants.

n n y y y
-q | --notes <optional notes>
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_namespace_relocate -n | --namespace-fph <namespace to move FPH> 2.c

A namespace (identified by FPH) is relocated (along with all of its descendants) to a new parent namespace identified by HRN.

n n y y y
-N | --namespace-name <new parent namespace>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_namespace_set_policy -n | --namespace-fph <namespace FPH> 2.c

Define the policy 9 for the creation of namespaces.

n n y y y
-l | --permissive
-r | --restrictive
-i | --inherited inherited 9
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_namespace_roots_list -n | --namespace-fph <namespace FPH> 2.c

List the root namespaces by FPH and HRN to STDOUT (one per line, tab-separated).

n n y y y
-u | --identity-fph <user identity FPH>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_namespace_tree_show -n | --namespace-fph <namespace FPH> 2.c

Show the entire namespace tree below any namespace specified by FPH.

Each namespace is identified by both FPH and HRN. 18

Output to STDOUT. 18

n n y y y
--json 18
--human-readable 18
--show-fph 18
-u | --identity-fph <user identity FPH>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
primitive functions
nests_nspath_to_fph 3.a --hrnsp <namespace path> 2.a

Convert namespace 2.a path to FPH 2.b (STDOUT) 3. The namespace path string is taken from STDIN unless provided as a parameter.

Return FPH 2.b to STDOUT if namespace string is valid.
Otherwise return empty string.

y y y y y
-h | --help
-v | --version
nests_fph_to_nspath 3.a --fph <FIP>

Convert FIP 2.b (STDIN) to namespace path (STDOUT). 3

Return namespace path string if FPH 2.b is valid.
Otherwise return empty string.

y y y y y
-h | --help
-v | --version
nests_entity_type_from_fph --fph <FPH> 2.c Get entity type (STDOUT) identified by FPH 2.c (STDIN). y y y y y
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_entity_add_stewards --fph <entity FPH> 2.c Add one or more steward(s) to the entity. y y y y y
-s | --steward <steward FPH> 2.c, 17 [1 or more]
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_entity_remove_stewards --fph <entity FPH> 2.c Remove one or more steward(s) from the entity. y y y y y
-s | --steward <steward FPH> 2.c, 17 [1 or more]
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_entity_examine --fph <entity FPH> 2.c Get details (JSON > STDOUT) of entity from FPH 2.c (STDIN). y y y y y
-u | --identity-fph <user identity FPH> 2.c
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
other
nests_json_to_csv -p | --auth <authentication code> 4.2.c Converts a NESTS JSON export (STDIN) to CSV (STDOUT). y y y y y
-h | --help
-v | --version
nests_csv_to_json -p | --auth <authentication code> 4.2.c Converts a NESTS import 13 file from CSV (STDIN) to JSON (STDOUT). y y y y y
-h | --help
-v | --version
nests_dump_all 13 -p | --auth <authentication code> 4.2.c Create a dump 2.a (JSON) of all entities under the stewardship 5 of the identity invoking the command. Output to STDOUT. n n y y n
-h | --help
-v | --version
nests_import_tree 13 -p | --auth <authentication code> 4.2.c

Import a tree of specifications 2.a (JSON) defining a tree of entities of any type. Input from STDIN.

n n n n y
-h | --help
-v | --version
nests_validate_import_tree 13 -y | --type CSV | JSON

Return TRUE if input file (CSV or JSON) is valid.

y y y y y
-h | --help
-v | --version
nests_requests_list_pending --accounts List all pending requests for which the invoking identity has (or shares) stewardship 5. n n y y y
--currencies
--namespaces
--primary-identities
--secondary-identities
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_nodes_list_available -p | --auth <authentication code> 4.2.c List the nodes (hosts) across which this namespace tree is replicated. n n n y n
-h | --help
-v | --version
nests_contact_identity -U | --recipient-hrn <username> 2.a

Send a message to an identity.

By default, identities do not receive messages sent by other identities (only those generated by the NESTS system) but they may opt to do so.

Each identity can set its own policy for the receipt of messages. 15

An identity can also blacklist individual identities by FPH. 15

y y y y y
-R | --recipient-fph <recipient identity FPH>
-H | --message <message>
-e | --email <sender's email address>
-T | --phone <sender's mobile phone number>
-F | --surname <sender's surname>
-G | --forenames <sender's forename(s)>
-u | --sender-fph <sender's identity FPH>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests_contact_entity_steward -K | --entity-fph <entity FPH>

Send a message to the stewards of an entity.

Each collective of stewards can set its own policy for the receipt of messages. 16

y y y y y
-L | --subject-class 16 <message>
-H | --message <message>
-e | --email <sender's email address>
-T | --phone <sender's mobile phone number>
-F | --surname <sender's surname>
-G | --forenames <sender's forename(s)>
-u | --sender-fph <sender's identity FPH>
-p | --auth <authentication code> 4.2.c
-h | --help
-v | --version
nests -W | --list-commands

Get general information about the NESTS CLI.

y y y y y
-X | --help-all-cli
--about-nests
--alternative-access
-g | --hub-information
-h | --help
-v | --version

Notes for Table 1

  1. entity types

    1. namespace:

      Every entity is identified by a name contained within a namespace, including other namespaces.

    2. primary identity:

      Every user (individual, organization, device or other agent) is associated with a unique primary identity.

      Where appropriate or necessary (which is not always the case), this is used to identify the user within the physical world and to enable that user to authenticate itself with a NESTS hub.

    3. secondary identity:

      Any primary identity may be associated with an arbitrary set of secondary identities, each contained within any namespace (where authorized by its steward(s)). No name can be duplicated within a namespace, however.

      The authentication data (along with any other unique data identifying that user within the physical world) are those of the associated primary identity.

      However, the association between any secondary identity and the primary identity is generally invisible to any user other than a steward of the namespace containing either the primary identity or a secondary identity.

    4. currency:

      A currency is a variable type (not necessarily a scalar) with which an arbitrarily large set of accounts is associated. The currency defines the properties of that variable (including constraints and any associated symbol).

      An example of particular importance is that of open money where the currency is a scalar value, usually (but not necessarily) displayed to two a decimal places, the accounts associated with which sum to zero.

      A currency is managed by a self-organizing collective of stewards who share the responsibility for the stewardship (including, but limited to, authorization) of the associated accounts.

    5. account:

      An account is a variable the properties of which are defined by a currency.

      Each account belongs to an identity (no distinction being made here between a primary identity or a secondary identity).

      Where necessary, activity in any account may be suspended or (exceptionally) blocked by any of the following:

      • the stewards of the namespace containing the account;
      • the stewards of the currency;
      • the stewards of the namespace containing the currency; or
      • the stewards of the namespace containing any namespace listed above.

  2. identification of entities

    entity types

    1. HRN = Human-Readable Name:

      This is a UTF-8 encoded string (in order to support a wide diversity of character sets for the convenience of users).

      Every entity has an HRN, including namespaces.

      For every HRN, internally there is a corresponding directory the name of which is a non-cryptographic hash (xxHash) of the HRN.

      The HRN is used by humans to identify entities (including their own primary identity, any secondary identities they may have, any accounts they may hold, the accounts of payees, or currencies) via a GUI (Web interface or smartphone app).

      The HRN must also be used in the creation of any entity using the CLI. (Once the entity has been created, it can also be identified by FPH.)

    2. FIP = Full Internal Path:

      This is the full internal directory path (from /) to the entity.

      For many purposes, this is the most suitable internal representation since it is the fastest to process.

    3. FPH = Full Path Hash:

      This is a non-cryptographic hash (xxHash) of the FIP.

      Every FPH 2.c maps back to its corresponding FIP using a fast key:value read-optimized DBMS. The frequency of entity reads greatly exceeds that of their creation or moveent, so CDB is used.

    entity access

    • Internally, any entity may be identified uniquely by either its FIP or its FPH.

    • Externally, any entity may be identified uniquely by either its HRN or its FPH.

    1. These operations do not require user authentication because no useful information is exposed.
    2. These operations do not require user identification because the identity of the user cannot be identified from the entity (FPH or FIP).
  3. users

    identification, communication and location

    Every user has a primary identity in a namespace (its registry) and may also have any number of secondary identities in other namespaces (where authorized by the stewards of those namespaces) each of which links (via FIP 2.b) to the primary identity.

    As with any other entity type, these identities can all be identified externally by either HRN or FPH.

    However, the primary identity is also associated with two sets of data

    1. contact and verification details

      1. surname and forename(s):

        • UTF-8 string.
        • Checked for validity and rejected if not an acceptable name string.
        • Optional, but if provided can be used for authentication in communication with stewards.
      2. email address:

        • UTF-8 string.
        • Checked for validity and rejected if not an acceptable email address.
        • Optional, but if provided can be used for password recovery.
      3. mobile phone number:

        • UTF-8 string.
        • Checked for validity and rejected if not an acceptable phone number.
        • Optional, but if provided can be used for password recovery.
      4. grid reference

      5. postal address (in local format)

      6. postal code (in local format)

    2. authentication

      1. password:

        • Arbitrary UTF-8 string.

        • Checked for strength and rejected if too weak.

      2. SSH public key:

      3. authentication code:

        The authentication code may be any string. It is used to authorize operations (such as payment 7 instructions) issued over SSH.

      4. API access token:

  4. stewards, superusers and others:

    A restricted set of commands is available only to superusers - those responsible for the installation and maintainance of the NESTS software, backup, migration, etc., and, in exceptional circumstances, its diagnosis and repair.

    Therefore NESTS users fall into two main categories with regard to command line access:

    • superuser: able to create, examine, manage and delete any entities within the tree.
    • everybody else, whether or not a steward 5 of any entities.

    steward:

    • If not specified, the stewardship 5 is assigned to the steward initiating this action.
    • If the specified steward does not exist, the stewardship 5 is assigned to the steward initiating this action.
    • If the specified steward exists, the entity is created with its .pending_authorization flag. The process is complete only when that steward authorizes it. Therefore the initiating steward gets no immediate confirmation.
  5. currencies: amount/value/measure

    A currency is identifiable directly from its own FPH, FIP 2.b or HRN, or indirectly from the FPH, FIP 2.b or HRN of an associated account.

    All currencies fall into one of several categories, including, but not limited to, the following:

    1. scalar: amount, value, measure or count

      Integers (count) or decimal fractions.

      The decimal point is configured within the currency definition (identified by FPH). The default is '.' but many countries use ',' (for example).

      In the special case of open money, the amount is expressed as a string of digits with an optional decimal point.

    2. vector

    3. matrix

    4. n-tuple

    5. time series set

    These five types are mutually exclusive. Where more than one is provided as command line paramaters, the first value matching the list above will be used.

  6. payment

    A payment is an operation associated with a pair of scalar accounts in the same open money currency, both of which are adjusted simultaneously by the same amount, one positively and the other negatively.

    A payment instruction is executed only if both accounts are in the same currency. Otherwise an error message is returned to STDERR.

    amount

    The amount is expressed as a string of digits with an optional decimal point.

    The decimal point is configured within the currency definition (identified by FPH). The default is '.' but many countries use ',' (for example).

    An amount provided using the command line option -A is treated as a special case of scalar and, where both are provided, will take precedence over a value provided using the command line option -S.

  7. date format

    Dates can be specified in any of the following big-endian formats:

    • YYYYMMDD
    • YYYY-MM-DD
    • YYYY/MM/DD

  8. policy

    The policy configured may be

    • permissive - giving authorization automatically and immediately in response to a request;
    • restrictive - requiring explicit authorization in response to a request; or
    • inherited from the parent namespace.

    In any case, the authorization may be suspended or revoked by the stewards of the entity upon detection of possible unacceptable activity.

  9. This action can be initated only by the account holder.

  10. This action can be initated only by the account holder or by a steward of the associated currency.

  11. currency:

    • A valid (registered) currency type must be specified. Otherwise an error message is returned.

    In the case of an open money value, this will be a simple scalar (the balance) along with the date it was last changed and the FPH 2.c of the account from or to which a payment was made.

    In the case of an open measures value, the structure of the JSON object will generally be much richer.

  12. import/export format

    NESTS subtrees are imported and exported as JSON. The functions nests_json_to_csv and nests_csv_to_json are provided to allow convenient piping of commands.

  13. currencies available

    An identity may (request authorization to) create an account in any currency available to it.

    Depending on the policy decided by its stewards, a currency falls into only one of the following categories with regard to account creation:

    1. Available immediately to any identity.

      This category would be used typically where a user has scanned a QR code (e.g. where displayed by a merchant or on some publicity material).

    2. Available immediately to any identity to which an invitation has been sent by an existing account-holder.

      This category would be used typically within undiscoverable or private currencies.

      A typical used for such currencies would be in maintaining accounts around use of a particular shared or common resource (e.g. energy generated, stored and consumed within a microgrid; human-time exchanged for comparable services; water collected, stored, filtered or used within a co-operative arrangement; or just about any other measurable resource.

    3. Available to for any identity to request authorization to create an account.

      Such currencies would be classified as discoverable, with authorization awaiting the attention of a subset of its stewards (that subset and the rules of authorization being specified by stewards).

    4. Available to for any identity to create an account immediately, without waiting for authorization by the currency's stewards.

      Such currencies would also be classified as discoverable.

    5. In all cases, even where the stewards of a currency have granted permissive use by default, authorization may be withdrawn from an account-holder where a cause for concern has been raised. Typically, such withdrawal of authorization will be temporary, pending investigation or remedial action, but in exceptional cases an identity may be black-listed.
  14. receipt of messages

    By default, identities do not receive messages sent by other identities (only messages generated by the NESTS system) but they may opt to do so.

    Each identity can set its own policy for the receipt of messages, selectively enabling/rejecting messages by:

    1. currency
    2. identity (add to blacklist)
    3. namespace

    For each category, an identity may choose to:

    • reject incoming messages silently (default)
    • reject incoming messages with "not receiving" message
    • acknowledge receipt of the incoming message
  15. Messages will be received by the stewards of an entity only if a key phrase a fixed set is provided as the -L | --subject-class parameter. The set remains to be decided, but might include such examples as:

    • "Account creation request"
    • "Namespace creation request"
    • "Currency creation request"
    • "Secondary identity creation request"
    • "Why has my account been suspended?"
    • "Reply to stewards' communication"
    • "Reporting inappropriate activity"
  16. At least one steward must be specified (by FPH) at the time the entity (a currency or a namspace) is created. More stewards can be added at a later date.

    The identity creating the entity is not necessarily among the stewards (although it may well be).

  17. The tree may be output either as compact JSON or in a human-readable format with one namspace per line, each indented to the level at which it is nested.

    The JSON output includes both FPH and HRN as a key:value pair.

    With the human-readable format, inclusion of the FPH is optional (disabled by default).

  18. creation, authorization and stewardship of namepaces

    The identity creating a namespace need not necessarily be one of the stewards specified.

    A namespace may only be created in accordance with the policy defined by the stewards of the parent namespace. In some cases, permissive creation may be permitted. In general, however, the creation of the namespace can only be requested pending authorization by the stewards of the parent namespace.

    In the special case of a root namespace there is no parent namespace so authorization is required from the NESTS hub's system administrators.

    In most cases, a root namespace is probably going to represent a country (although other categories may apply) and will therefore almost certainly be hosted within its own distinct NESTS hub configured to meet local requirments.

use in scripts

These are typically use with | (pipe), > (redirection) and tee in shell scripts, e.g.

A custom filter (perhaps written in Python, Perl, AWK or Ruby, or using JQ) can be used to extract and process the output of nests_entity_examine.


remote execution over SSH

These functions can be executed remotely over SSH, with or without a wrapper script at the server end. For example:


Version 0.51 - 2021-09-28 12:45 - Copyright © 2021 John Waters


home