ARMO project framework
Copyright © 2021 Olexandr (Alex) Troyanovs'kyy. All Rights Reserved
Description below reflects a very practical approach to the development of the project. Its critical point is to guarantee that receivables and payables of Programme participants are synchronized on every Operation Period (OP)--as stated in paragraph A.5. of the Concept--regardless of the number of participants. So it was decided that ARMO system itself must perform all ARMO transactions and provide all participants with their updated balances of obligations.
Programme Calendar
An ARMO programme lifespan comprises one or more Programme runs, and the Programme Calendar (PC) must be properly set up for the run. A run is started by the Programme Admin and is stopped when PC generates OP record with zero T2 field. Admin must be able to adjust PC to stop the run at specified OP. It seems reasonable to have lexicographical order of OPs' Labels corresponded to chronological order of OPs.System patrs
Every ARMO system running on some computer or computer cluster (CC) should consist of Programme Engine (PE) and optional Recognition System (RS). For every ARMO programme supported by any ARMO system its PE must provide functionality described in paragraphs B.1. - B.5. of the Concept and its RS must provide functionality described in paragraph B.6. (more details are provided here).Program Modes
PE must support any Programme running in one of two possible modes denoted as B and D. Mode B requires all the Programme Participants to report their Balances of obligations accrued by the end of current OP at the predefined moment of time (specifically, CurrentOP.T2 - dT2 where dT2 is expected delay of Participants' data arrival to the System). Mode D allows all the Programme Participants to post their Deals to the System at any time so that PE itself will take care about assigning posted deals to proper OP.Communication between a Participant and the System
Data exchange between a Programme participant and the System may be provided either by asynchronous messages or during an online session. Messages must be digitally signed automatically before sending and verified automatically upon receiving. If validation fails then message must be ignored by the recipient. A session must be protected by TLS protocol. These requirements mean that every ARMO system must obtain its Digital Certificate (DS). A Participant relying on sending messages to the System may also need DS (what does not preclude that Participant from communicating with the System via TLS session). Content of some messages or data transmitted during an online session is described here. An ARMO system must be setup with one or more URI so that each URI's scheme (enabled by CC's infrastructure) will tell the way of communication between the System and a Participant of a Programme supported by the System. All the System's URI must have the same host in their authority component.Unified Programme support
ARMO system functionality (presented on the Use Case diagram and related Activity diagrams) should be the same for any Programme running on corresponding CC so that PE (and RS, if any) processes/uses Programme's data located in the corresponding repository and invokes corresponding PC. It is implied that time required to compute ARMO-results for any Programme running on the CC is less than duration of the shortest OP of that Programme. A Participant may also take part in several Programmes provided that Participant System (PS) runs on the computer [cluster] containing Programmes' data in their corresponding repositories. PS functionality is presented on the Use Case diagram and related Activity diagrams. Programme name must be passed along with other data travelling between PS and ARMO system. This diagram illustrates such multi-System/Programme environment.ARMO realm
A set of one or more ARMO programmes supported by one or more ARMO systems allowing people, businesses and other entities to participate in any suitable Programme (one or more) in accordance to the ARMO concept may be considered as an ARMO realm specified by its name. For a realm to exist some designated computer [cluster] should have the Registry named after the realm and enable registration of ARMO systems, ARMO programmes, Recognition Parameters (RP) for a given Programme (if necessary), and Comparison Modes (CM) which characterize functionality of Recognition Systems in the realm. All the information in the Registry should be available for existing and potential participants of any registered Programme. It seems reasonable to have only one ARMO realm (named ARMOLAND) to avoid taking care about yet another registry for different realms.Common pieces of software
Theoretically it's possible to develop one adjustable PC which will generate OPs based on the set of data or metadata created for the specific Programme run. That PC's distribution packages for popular computing platforms should contain manuals and may be uploaded to ARMOLAND for use in any Programme after downloading and installing in the Programme's repository on an ARMO system's CC. Similarly, it may be possible to develop one widely accepted PE, one widely accepted RS (which may use implemented CMs as plugins), and have their distribution packages on ARMOLAND. This Use Case diagram outlines how ARMOLAND may facilitate participation in any Programme which participants' geography is broad enough.Local Programmes
On the other hand, there may be local Programmes running on local Systems beyond ARMOLAND. Any local PS exchanging data with local PE should enable a Teller to work on behalf of Programme participants. Registration of a Participant to a local Programme with the PS should be similar to opening a bank account. As a result a Participant should get its PPID (to be used in every Programme's deal--what means no RS needed for any local System) and possibly the credentials to access the Programme resources remotely. Also, the record LocalParticipant in the P_name repository should be populated. Any local Programme should be running in D mode. Potential participants of any local Programme should get known about it from local sources. At the same time, an Admin of any local System/Programme may get necessary installation packagers (if any) from ARMOLAND. If a PE conducting a local Programme and a PS supporting the Programme run on the same CC (what means that PE and PS reside in the same ARMOLAND repository) then both systems can access the same collection of records (specifically: Deal, Deals_Journal, ARMO_Journal, and Run_Ledger) in the Programme repository. In this situation messages DEALS, RESULTS, and PENDING_DEALS may contain P_name only and may not be digitally signed.Naming
Certainly, every System name and every Programme name within an ARMO realm must be unique. Neither local Programmes nor local Systems supporting those programs should be registered with any ARMO realm, and their names must also be unique within their scope. So, following some naming conventions (e.g. suggested below) may be of use.Partners Recognition
When participants of some Programme know only their own PPIDs and local IDs of their partners it is necessary to recognize those partners as other participants of the same Programme and map those partners' local IDs to corresponding participants' PPIDs. It is feasible based on the following assumptions:- information about Participants' partners is presented in those Participants' [accounting] systems in the way that every partner has its unique local ID and some set of attributes,
- intersection of all Participants' sets of partner's attributes is not empty (let's call it common attributes).
Comparison Modes
Different Comparison Modes (CM) may be implemented and applied to different pieces of data represented as strings of symbols. An algorithm of every Mode must tell how to compute distance (float number) between two strings so that the more similar those strings are the lower that distance is. An implementation of a Mode's algorithm may be delivered either as a source code or as a compiled code ready to run in the corresponding environment. Fulfillments' registration is optional. Every Mode must be specified and may be implemented within any RS which declares support of the Mode in P_Setup.List_of_CMs. If the sum D of all distances computed for every pair of common attributes' data does not exceed some threshold D0 then two entities with those sets of attributes may be considered the same. So, if some Participant's partner with local ID1 appears to be another registered Participant PPID2 (with the tolerance D0) then that partner gets recognized and mapped as (ID1, PPID2). Certainly, it is necessary to define the amount and order of partners' attributes for every Programme (where partners recognition is necessary) and make that information available to any potential Participant of such Programme--what is provided in Registry's RP table.Compound Local ID
One more point to consider with regard to partners' recognition is specifics of participants' [accounting] systems. Some of them may have multidimensional local ID. For example, in Sage 50 Accounting (2013's version) tables tCustomr and tVendor store data about two types of partners. Every table has primary key (first field LId which the same particular values may occur in both tables) and several other fields describing the same sets of partners' attributes (Name, Street address1, Street address2, City, Province/State, Country, Postal/Zip Code). In this scenario every partner's unique local ID is a pair (partner type, partner LId) what may not be the case with regard to another accounting system. So it seems reasonable to introduce a universal form of any local ID--compound local ID (CLID) as a concatenation of all key components in order of their dimensions. In this case a Participant System (PS) should generate/parse CLID values based on the KeyFields_List field of the Programme setup record.Registration with ARMO system
Participant System (PS) must submit the following data to register a Participant's to a particular Programme:- P_name (name of the Programme register to),
- PPID (may be empty),
- URI (to receive messages from ARMO system),
- PWD (encrypted confirmed password set during registration via TLS session, if any),
- List of attributes' data (if partners' recognition is required).
Update of participants' data
Besides, the System should enable update of a Participant registration record(s) so that a Participant may add/change its URI and PWD and modify its attributes (if any). Modified attributes should be updated in the Self-Partner record with PPID_self and all the other records with PPID_partner equal to PPID_self.Messages description
| Message | Sender | Recipient | Message content | Comment |
|---|---|---|---|---|
| START | PE | PS | P_Name | Programme name |
| CurrentOP data | ||||
| EOM | End of Message | |||
| CONTINUE | PE | PS | P_Name | |
| NextOP data | ||||
| EOM | ||||
| DEALS | PS | PE | P_Name | |
| (mode D only) | Collection of Deal records | |||
| EOM | ||||
| BALANCES | PS | PE | P_Name | |
| (mode B only) | Collection of Run_Ledger records with OP_Label = CurrentOP.Label | |||
| EOM | ||||
| RESULTS | PE | PS | P_Name | |
| Collections of the following records with their OP_Label=CurrentOP.Label: Deals_Journal (in mode D only), ARMO_Journal, and Run_Ledger |
OR notification "NoResults" | |||
| EOM | ||||
| PENDING_DEALS | PE | PS | P_Name | |
| mode D only | Collection of Deal_Journal records with empty OP_Label | OR "NoPending" | ||
| EOM | ||||
| PARTNERS | PS | RS | P_Name | |
| Collection of Partner records: PPID_partner is empty & CLID is not empty | ||||
| EOM | ||||
| PARTICIPANTS | RS | PS | P_Name | |
| Collection of pairs (PPID, CLID) | ||||
| EOM |
OP data
| Name | Description/Comment | |
|---|---|---|
| Records | CurrentOP, NextOP | Generated by Programme Calendar |
| Field | Label | Unique string within a Programme lifespan |
| Field | T2 | UTC (time to close OP). Must be converted to/from a Participant's local time |
| EOR | End of Record |
System setup data
| Name | Description/Comment | |
|---|---|---|
| Record | S_Setup | For ARMO System on CC |
| Field | S_name | Must be unique for non-local System |
| Field | IsLocal | Yes | No |
| Field | PE_URI_List | Must be posted to ARMOLAND during registration of non-local System |
| Field | RS_URI_List | Similar to above, empty if partners' recognition is not required |
| EOR |
Programme data on the System's site
| Name | Description/Comment | |
|---|---|---|
| Record | P_Setup | In the System's P_name repository (for non local Programme only) |
| Field | P_mode | B | D |
| Field | D0 | Float >=0; field present only when partners' recognition is required |
| Field | List_of_CMs | List of Comparison Modes corresponding to the AttrData_List for the Programme; present only with D0 field |
| EOR | ||
| Record | Participant | In the System's P_name repository |
| Field | PPID | PK for non-local; Empty for local with only one record in the collection |
| Field | PS_URI | For sending messages to PS |
| Field | PWD | Encrypted Participant's password (Empty if not used); List of Teller's passwords for local PS |
| EOR | ||
| Record | Self-Partner | In addition to Participant record--when partners' recognition is required |
| Field | PPID_self | Self |
| Field | PPID_partner | Empty if Partner is not recognized; always Empty for Self |
| Field | CLID | Of the Partner; Empty for Self |
| Field | AttrData_List | List of corresponding fields' data in the order described in the Registry's RP table |
| EOR | ||
| Record | Deal | Posted by PPID_self or by Teller on behalf of PPID_self |
| Field | PPID_self | Self |
| Field | PPID_partner | Partner |
| Field | DT_amount | Positive if partner is debtor, zero if partner is creditor |
| Field | CR_amount | Zero if partner is debtor, positive if partner is creditor |
| Field | Explanation | Deal's comment or Reference number |
| EOR | ||
| Record | Deals_Journal | In the System's P_name repository |
| Field | OP_Label | Empty for pending deal |
| Field | PPID_self | |
| Field | PPID_partner | |
| Field | DT_amount | To increase AR balance of Self |
| Field | CR_amount | To increase AP balance of Self |
| Field | Explanation | Deal's comment or Reference number |
| EOR | ||
| Record | Run_Ledger | In the System's P_name repository |
| Field | OP_Label | Enables history of balances |
| Field | PPID_self | |
| Field | PPID_partner | |
| Field | AR_balance | Receivables: to be paid by Partner to Self |
| Field | AP_balance | Payables: to be paid by Self to Partner |
| EOR | ||
| Record | ARMO_Journal | In the System's P_name repository |
| Field | OP_Label | Of ARMO-results computed |
| Field | PPID_self | |
| Field | PPID_partner | |
| Field | DT_amount | To decrease AP balance of Self |
| Field | CR_amount | To decrease AR balance of Self |
| Field | Explanation | List of reduced cycles' numbers in order of reductions |
| EOR | ||
| Record | ARMO-results | Generated in the System's P_name repository based on ReducedCycle data |
| Field | PPID_self | |
| Field | PPID_partner | |
| Field | DT_amount | To decrease AP balance of Self |
| Field | CR_amount | To decrease AR balance of Self |
| Field | Explanation | List of reduced cycles' numbers in order of reductions |
| EOR | ||
| Record | GraphEdge | Corresponds to Run_Ledger record with positive Self's Payable |
| Field | Obligor | Debtor' PPID, i.e. Run_Ledger.PPID_self |
| Field | Obligee | Creditor' PPID, i.e. Run_Ledger.PPID_partner |
| Field | Amount | Run_Ledger.AP_balance of the OP being closed |
| [Other fields] | Depending on implementation of algorithm generating ReducedCycle records | |
| EOR | ||
| Record | ReducedCycle | Generated in the System's P_name repository |
| Field | CycleNumber | Number in order of cycles' reductions |
| Field | Node | PPID of the cycle's node |
| Field | AmountReduced | For any edge in the cycle |
| EOR |
Programme data on the Participant's site
| Name | Description/Comment | |
|---|---|---|
| Record | PS_Setup | In P_name repository on PS |
| Field | PPID | Filled when registered; empty for local Programme |
| Field | dT2 | milliseconds (expected delay of Balances' arrival to the System); >=0 for mode B, <0 for mode D (in particular for local) |
| Field | PE_URI_List | To communicate with the Programme Engine |
| Field | RS_URI_List | Empty if partners' recognition is not required |
| Field | KeyFields_List | In order used for generating/parsing CLID (present when RS_URI_List is not empty) |
| Field | AttrFields_List | Correspons Attributes_List in the Registry's RP table (present when RS_URI_List is not empty) |
| EOR | ||
| Record | PS_Partner | Present in P_name repository on PS only when partners' recognition is required |
| Field | PPID_partner | Empty if Partner is not recognized |
| Field | CLID | Of the Partner, not empty |
| Field | AttrData_List | List of corresponding fields' data in the order described in the Registry's RP table |
| EOR | ||
| Record | LocalParticipant | Present in P_name repository on PS for local Programme only |
| Field | PPID | Of local Participant |
| Field | URI | For sending messages to Participant (Empty if not used) |
| Field | PWD | Encrypted Participant's password (Empty if not used) |
| Field | AttrData_List | In predefined order--to verify a Participant by a Teller |
| EOR | ||
| Records | Deal, Deals_Journal, ARMO_Journal, and Run_Ledger are the same as on PE site |
A hypothetical fragment of ARMOLAND
Naming conventions and names examples
Any ARMO programme's name within ARMOLAND may have the following syntax:<Type>_<Region>[_<suffix>] where Type reflects application domain, Region describes Programme's participants' geography, and optional suffix assures the Programme name is unique. Each part of a name better not to contain underscore symbol. Below are some possible names of ARMO Programmes.
- B2B_CA - for participating businesses across Canada,
- B2B_CA-AB - within Alberta only,
- B2B_EU, B2B_GB, B2B_JP, etc,
- B2B_NorthAmerica - extending Free Trade approach by using some common unit of measuring participants' obligations,
- B2B_TransAtlantic and B2B_TransPacific (also based on some common UnitMO),
- FIN_CA - for participating banks, credit unions, and other financial institutions across Canada,
- LCTP_A0A0A0 - for Local Community Trading Programme in an area denoted by Canadian postal code. There may be an area name instead. Several LCTPs running in the same area on the same computer [cluster] must have different suffixes.
Prototyping and implementation considerations
The MS Access application was created to prototype some ARMO system functionality (as of August 2016) on a hypothetical Programme with partners' recognition based on seven common attributes. Two simple comparison modes were implemented. In the first one the distance between to equal strings is set to 0, otherwise to 1. The second mode calculates distance as number of different strings' symbols divided by the lenght of the shorter string. Certainly, more sophisticated comparison algorithms exist and may be used (e.g. Levenshtein distance). Prototype's VBA code doesn’t depend on the number and names of attributes' fields. This example demonstrates ARMO result computed by the System prototype on some test graph.It seems reasonable to have repositories as file folders so that every Programme's folder P_name resides within [root] folder ARMOLAND. Setup records may be just text files in the corresponding folders. Handles to DS may be included into setup files if needed. Some fields in the records/tables described above should be considered as meta-fields requiring further specification. Relational database model seems to be optimal for participants' and accounting data and for the Registry. On the other hand, utilizing a graph database (e.g. Neo4J) may be more efficient for processing graph of obligations. All files and record collections involved in the computation of ARMO results may be locked exclusively during batch processing.
Requests from PS (including those about history of reductions) should be specified and corresponding functionality should be implemented on both PE and PS.