# MaidSafe Language of the Network
### general considerations
Nodes and data both live in the same XOR space which is addressed with a 2^512 bit key; a Network-Addressable-Element (NAE). A message flows from a NAE to a NAE. An operation can be performed on a message flow by a manager group.
A message flow from start to end can be represented by
< NAE_1 | manager | NAE_2 >
where the NAE can be a node (ie a vault or a client - Direct NAE) or a data element (Indirect NAE). The manager group operating on the message flow will act forward `manager | NAE_2 >` under normal / successful conditions. The manager will act backwards `< NAE_1 | manager` upon error.
If no operation is needed on the message flow then this special case is represented by
< NAE | NAE >
For a given message type `ACTION` the functions shall be named
< A::ACTION | B::ActOnACTION | C::PerformACTION >
The function `HandleACTION` is reserved for the VaultFacade. Currently these message types are Connect\*, ConnectResponse\*, FindGroup\*, FindGroupResponse\*, GetData, GetDataResponse, PutData, PostMessage, where message types with \* are completed in routing and exempt from this naming convention.
For clarity, a message is passed through RoutingNode and VaultFacade upto Persona according to following abstraction
RoutingNode::MessageReceived {
Parse; Filter; Cache; SendOn; Relay; Drop; Sentinel;
Switch RoutingNode::HandleMessage(MessageType /* */) {
Completed in routing or
VaultFacade::HandleACTION {
Switch on Authority & template on DataType {
Persona::ActOnACTION or // Currently both named HandleACTION
Persona::PerformACTION
}
}
}
}
The triplet structure `< A | B | C >` captures the general characteristic of every message flow. The structure is event-driven and the message id is preserved over the structure.
`< . ` corresponds to the creation of a new message flow. A single node or client can initiate a routing call where a random message id is generated by routing. It is noted that if a group starts a new message flow, the message id needs to be deterministically instantiated by routing.
`. | .` represents the full routing action over intermediate XOR space, as stated above,
Parse; Filter; Cache; SendOn; Relay; Drop; Sentinel;
where `Sentinel;` is the dominant logical contribution and as such `. | .` is simply referred to as "sentinel".
`. >` terminates the message flow, and is the successful end-state of the action. Only upon error is the flow reversed. From this it follows that the following functions should be implemented for a given action `< A | B | C >`
A::ACTION()
B::ActOnACTION()
B::ACTIONFailure()
C::PerformACTION()
Actions can be logically combined where the new start is identical to the preceding terminal,
< A | B | C > < C | D | E >
and the joint `| C > < C |` can be considered a full consensus mechanism for an Indirect NAE C - for a Direct NAE C this consensus mechanism is trivial. In this sense the operator `| C > < C |` transforms (a) message flow(s) into (a) new message flow(s). Note that this joint can be trivial and in such case does not require consensus.
Where before the message flow in the structure `< A | B | C >` passes over different persona's, such messages are called "interpersona messages". The operator `| C > < C |` introduces "intrapersona messages"; [ Should these be handled as a separate type of messages in routing ? ]
## Flows
### Maid GetData and GetDataResponse
< MaidClient | DataManager > < DataManager | MaidNode >
< MaidClient | DataManager > < DataManager | PmidNode > < PmidNode | MaidNode >
Here `| DataManager > < DataManager |` is a consensus mechanism to decide whether DataManager has the requested data in active memory or needs to continue the GetData request as new message flows from DataManager to the archiving PmidNodes. Note that based on Authority PmidNode can verify that the GetData request came from DataManager. In both lines only the final message flow is GetDataResponse.
If an explicit caching at DataManager on Get is desired the second line above can be replaced by
< MaidClient | DataManager > < DataManager | PmidNode > (< PmidNode | MaidNode > & < PmidNode | DataManager >)
where the two flows in parenthesis are both GetDataResponse. The DataManager simply adds the data to LRUcache again.
### Maid PutData
< MaidClient | MaidManager | DataManager > < DataManager | PmidManager | PmidNode >
Here `| DataManager > < DataManager |` can store the data in LRUcache and without delay trivially select K closest to D.name PmidNodes for archiving the data.
### Mpid Messaging
very brief, assumes knowledge on the MPID implementation
Send out message:
< MPN_A | MPM_A > < MPM_A | MPM_B > < MPM_B | MPN_B >
Retrieve message:
< MPN_B | MPM_B > < MPM_B | MPM_A > < MPM_A | MPN_B > < MPN_B | MPM_B >
where the last flow deviates from the existing implementation, but would notify MPM_B that the message has been retrieved and the header can be dropped.
### Remaining conventions:
D data
H() Hash512
H^n() n-th Hash512
Manager{Address};
{Address} omitted where evident,
e.g. MaidManagers{MaidNode}
### Terms and conventions for individual documentation
* ->> : represents a single to group message (no callback)
* -> : represents a single to single message (no callback)
* =>> : represents a single to group message (callback)
* => : represents a single to single message (callback)
* *->> : represents a group to group message (no callback)
* *-> : represents a group to single message (no callback)
* *=>> :represents a group to group message (callback)
* *=> : represents a group to single message (callback)
* So - Send On, this function which sends the message on to the next persona is implicitly mentioned in all above notations. They can be explicitly mentioned, when it matters
* Action.Sy : denotes synchronising the Action
* Ac - Accumulate, This function accumulates messages from previous
* Fw - Firewall, this function ensures duplicate messages are prevented from progressing and answers such messages with the calculated response (such as success:error:synchronising etc. and may include a message containing data)
* | : represents [Ac, FW]
* [*Operation1*, *Operation2*, .. *OperationN*] : denotes sequential operations
* {*Operation1*, *Operation2*, .. *OperationN*} : denotes parallel operations
* (*Operation1*)(*Operation2*) .. (*OperationN*) : denotes sequential dependent operations, for instance, *Operation2* requires results from *Operation1* and produces results for *Operation3*, $ may be used to represent the result from previous operation.
* condition ? A : B : C/C++ syntax
* condition ? A : represents _condition ? A : NoOp_
* ! denotes NOT
* __Bold__ represents Indirect Network Addressable Entities INAE
* _Italic_ represents Direct Network Addressable Entities DNAE