Skip to content

node.md

Latest commit

 

History

History
780 lines (627 loc) · 31.3 KB

node.md

File metadata and controls

780 lines (627 loc) · 31.3 KB

GEO Network Client documentation



How to run

Installation

  1. Download/Build last node version from the repo;
    You can follow the links provided in releases changelogs to get desired version of the node build (currently, only BETA1 is available).

  2. Move geo_network_client to the desired FS location.
    The default location for the node in ~/node/, but you are free to chose any other location.
    If you are using provided WM image (or docker container) - it is already configured. No need to go through this step.

  3. Prepeare the configuration.
    Please, follow instructions from a section "Configuration".

  4. Start the node: ./geo_network_client
    In case of successfull fly node should report

  • core and required subsystems initialisation messages;
  • current observers chain height.

node_run.png

In case if node was not started as expected - please, refer to the operations.log. Usually it contains some details abot the error occured.

After the first launch of the node, the following objects appear in the node’s directory:

  • The io directory, that contains two files: storageDB and communicatorStorageDB. This two files stores all the node’s data: trustlines, keys, history, payments, routing tables, etc.
  • The fifo directory, that contains three files: commands.fifo, results.fifo and events.fifo. The node’s communication will happen through these files.
  • The operations.log file containing detailed log of network actions (still needs some polishing).
  • The process.pid file containing the PID of the runnig node.


Libraries required

GEO Network Client uses boost libraries and libsodium for the cryptography.
Please, enshure presense of this libraries in you env. before starting the node.

Configuration

Configuration contains network interfaces that should be used by the node and reported to the rest of the network, as well as addresses of the observers, that are expected to be present in the network.

Note: Beta 1 release supports only static, publicly available IPv4 addresses.
So, in case if you are planning to try to launch several nodes and perform some operations between them, - please, ensure, that all of them would be able to communicate to each other via UDP/IPv4 interface.

Note: Beta 1 release supports only statically listed observers list
The protocol itself is expected to support dynamically formed observers list, provided by the GSR [#todo link to GSR description].

Configuration file is named conf.json.
It is required to be located on the same FS level as geo_network_client.
node_settings_fs_level.png

The configuration file must contain addresses information of the node – addresses: all the addresses that identify the node (including ports, if related) and their types, as well as the list of the Observers – observers.

In the current version of the node only one type of addressing is supported – ipv4.

Currently, observers test. net is driven by only 4 observers. It is fully enough for providing all necessary operations for the GEO nodes and the GEO Network Test net. At the moment, observers do not check validity of the TSLs/Claims generated by the GEO Nodes, so this network is not suitable for production usage, but is able to provide observing functionality that fully covers BETA1 release needs. The production environment is expected to be driven by the 1024+ observers.

Configuration for the BETA1 test net:

{
  "addresses":
  [
    {
      "type":"ipv4",
      "address":"127.0.0.1:2000"
    }
  ],
	"observers":
  [
    {
      "address":"68.183.146.232:4000",
      "type":"ipv4"
    },													
    {
      "address":"46.101.51.158:4000",
      "type":"ipv4"
    },
    {
      "address":"206.189.84.116:4000",
      "type":"ipv4"
    },
    {
      "address":"159.89.115.33:4000",
      "type":"ipv4"
    }
  ]
}

The node’s addresses will be used to identify the node and they will be stored at other nodes with which the current node will communicate in either way: opening a trustline – TL, making payments, etc. Therefore, changing the address of the node after it has already opened some TLs will lead to incorrect work with the corresponding nodes.

How to use the node

Here we will describe several ways possible how to communicate with the node.
For the simplicity reasons, the documentation is provided in format of tutorial.

Basic overview

Node represents an account in GEO Network.
It is assumed, each one participant of the GEO Network would access the network via it's own node.
In contrast to some other decentralized networks, GEO Network does not delegate calculations to the miners, but assumes network participants would take part (only) in transactions, in which them are involved.

GEO Network Client implements such a node and provides low-level API for operations processing: assets transfers, trust-lines/channels accounting, etc.

For the simplicity reasons, in this tutorial we would use provided WM image. You can find the latest images with latest node build in GEO Network Client repo ("Releases" section of the description).

VirtualBox configuration

We would need SSH session to manipulate the nodes, so the WM should accept incoming TCP connections.
The simples way to achieve it is to configure NAT Ports Forwarding for the destination WM.

VirtualBox Network Adapter Settings



Pord Forwarding Settings



Network topology

In this tutorial we would use 3 nodes: node1, node2, node3.
We would use one WM to run all three nodes. You can follow this tutorial in the same way, or you can launch 3 different WMs and configure appropriate network layer so all the WMs would be able to communicate to each other WM.

Each one node needs one SSH session to be launched in, and one more SSH session for the commands transferring and results fetching. So in total, we are opening 6 SSH sessions to the WM.

SSH into the WM 



User: geo
Pass: geo

We should copy original node dir 3 times:

  1. cd ~
  2. cp ./node ./node1 -r
  3. cp ./node ./node2 -r
  4. cp ./node ./node3 -r

And make corresponding changes to the configuration files:

Then, we need to launch the nodes.
For it to be done, follow the next steps:

  1. Sitch to node1 SSH sesssion and do: cd ~/node1/ && ./geo_network_client
  2. Sitch to node2 SSH sesssion and do: cd ~/node2/ && ./geo_network_client
  3. Sitch to node3 SSH sesssion and do: cd ~/node3/ && ./geo_network_client

Please, refer to the "How to run" section of this doc for the details about how node could be started and what behaviour of it to expect in various cases.

Node communication

There are 3 possible ways to communicate to the GEO node:

  1. Via low-level GEO Node protocol
    This is the most performant and the most flexible way of communication, but in the same time, the most complex one. This communication channel should be used in production environments or embedded systems with maximum performance in mind, and to avoid addtional resource consupting layers of communication (for example, HTTP API).

  2. Via command-line interface [comming soon]
    This interface provides ability to communicate with node from the console in mode "one command at a time".
    It is useful during development, but it should not be considered to be used in production environments, due to the limitations of concurent commands processing, and relatively high resouce usage per command execution.

  3. Via JSON API [comming soon]
    This interface provides ability to communicate with node via HTTP API and to process more than one command at a time. It is useful during development, and also might be considered to be used in production environments, that are configured for communication with only one, or several nodes.

Low-level GEO Node protocol

How to send command to the node

All commands have to be transferred to the commands.fifo pipe. The node at the start opens this file for reading immediately, so once a command gets there, it will be processed at once.

The results of the command execution will be written by the node into the results.fifo pipe. This file must be opened for reading before the start of the node, otherwise the node will freeze at the first attempt to write a result. Since we do not have the results.fifo pipe (as well as other files) initially, we have to run the node first to form all these files. Then we have to stop it, and all the next times we will have to open the results.fifo file for reading before the node start.

The events.fifo file is planned for recording the node’s internal events (incoming payments, opening an outgoing TL, etc.). But this functionality is not implemented yet, so this file can be ignored so far.

All commands and results consist of plain text data separated by the tab symbol \t, and ends with the end of the line symbol \n. The command and the result start with a 16-byte command UUID (UUID4 hex representation) that should be generated by the command issuer.

Each command consist of command UUID, command name, and comamnd arguments.

You can use standard linux command echo to send command to the node directly from the shell:
echo -e "<command>" > fifo/commands.fifo
Argument -e forces echo to interpet \t as tab character and \n as line end character.

How to read command result

  1. Move to the node directory: cd ~/node
  2. Open ./fifo/results.fifo for reading. It is a linux-pipe (fifo-file), so it would not open, until the node is not launched as well (pipe opens in read mode only if there is another process that has opened it for the writing).
    cat ./fifo/results.fifo
    In this case, cat would hang, until node would be launched and some command-results would be written.

This approach might be combined with commands transferring in common shell in the next way:

> cat fifo/results.fifo & # read results in background

> echo -e "<command 1>" > fifo/commands.fifo
> echo -e "<command 2>" > fifo/commands.fifo
> ...
> echo -e "<command n>" > fifo/commands.fifo


Transaction: Initialise a Trust Line

INIT:contractors/trust-line
Argument Description
Number of contractor’s addresses How many addresses of the contractor would be included into the cpmmand
Vector of addresses of the contractor Vector of pairs (address type; address). As was mentioned above, the node currently supports only one type of address: IPv4, and its type code is 12
Equivalent ID ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.

This command initialises a Trust Line with contractor. The transaction involves both current node and contractor's node. Ensures cryptographic keys exchange.

Example

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tINIT:contractors/trust-line\t1\t12\t127.0.0.1:2002\t1\n" > fifo/commands.fifo

init_trust_line.png

Response

Code 200: OK, operation was performed well. No additional data is provided.


Transaction: Trust Lines List

GET:contractors/trust-lines
Argument Description
Offset Number of the trust line from which the scan should be started.
Count How many TLs should be returned.
Equivalent ID ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.

Returns no more than Count of Trust Lines that are present on the node and corresponds to the received offset and equivalent. todo: add link to te transaction in source code.

Example

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tGET:contractors/trust-lines\t0\t1\t1\n" > fifo/commands.fifo

init_trust_line.png

Response

  • The result code: 200 – completed successfully;
  • total number of TLs returned;
  • TL’s vector:
    • Contractor’s ID
    • Contractor’s addresses
    • TL state
    • Indication of the node's keys are present
    • Indication of the contractor’s keys are rpesent
    • Incoming Trust Amount (ITA)
    • Outgoing Trust Amount (OTA)
    • Current Balance (CB)

Contractor’s ID is a positive integer number (4B) that is used by the node for the simplified identification of other nodes, as well as for a number of subsequent commands.


Transaction Set Outgoing Trust Amount (OTA)

SET:contractors/trust-lines
Argument Type Description
Contractor ID uint32 Internal ID of the neighbor node, obtained from the TL List.
Amount Pos. BinInt,
up to 2^256		 New value of the Outgoing Trust Amount (OTA).
Equivalent ID uint32 ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.

This command sets/updates amount of outgoing Trust Line.
It is expected that trust line to the contractor with corresponding ID is already present (initialised). Transaction involves both current node and contractor's node. todo: add link to te transaction in source code.

Note: If you set a new OTA value to 0, then the Outgoing Trust Line will be closed.

Example

Change the OTA to the value of 5000 to the contractor with the ID 1 in the equivalent 1:

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tSET:contractors/trust-lines\t1\t5000\t1\n" > fifo/commands.fifo

init_trust_line.png

Response

Code 200: OK, operation was performed well. No additional data is provided.
Code different than 200 indicates an error. Please, refer to the node's codes list for the details.


Transaction: Closing Incoming Trust Line

DELETE:contractors/incoming-trust-line
Argument Type Description
Contractor ID uint32 Internal ID of the neighbor node, obtained from the TL List.
Equivalent ID uint32 ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.

This command is used to reject incoming Trust Line from the neigbor node. Transaction involves both current node and contractor's node. In case if contractor's node does not responds - operation is forced to be done on the current node. todo: add link to te transaction in source code.

Example

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tDELETE:contractors/incoming-trust-line\t0\t1\n" > fifo/commands.fifo

tl_close_incoming.png

Response

Code 200: OK, operation was performed well. No additional data is provided.
Code different than 200 indicates an error. Please, refer to the node's codes list for the details.


Transaction: Trust Line by Contractor’s ID

GET:contractors/trust-lines/one/id
Argument Type Description
Contractor ID uint32 Internal ID of the neighbor node, obtained from the TL List.
Equivalent ID uint32 ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.

Returns Trust Line with contractor, that has internal id Contractor ID

Example

Obtaining TL with a contractor with ID 2 in the equivalent 1:

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tGET:contractors/trust-lines/one/id\t2\t1\n" > fifo/commands.fifo

Response:

Result codes: 200 – completed successfully.
405 – TL is absent.

In case of code 200:

  • Contractor’s ID
  • State of the TL
  • Indication of your own keys presence
  • Indication of the contractor’s keys presence
  • Incoming Trust Amount (ITA)
  • Outgoing Trust Amount (OTA)
  • Current Balance (CB)

When receiving the code 405, no more data is returned.
An example of the command’s result:

13e5cf8c-5834-4e52-b65b-f9281dd1ff91\t200\t2\t2\t1\t1\t200\t5000\t300\n



Transaction: Trust Line by Contractor Address

GET: contractors/trust-lines/one/address
Argument Type Description
Number of addresses uint32 How many contractors would be list into the command.
List of addresses list List of addresses that are related to the contractor.
Equivalent ID uint32 ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.

Addresses fields

Field Type Description
Address type enum Only IPv4 Addresses are supported at the moment, code 12.
Address string Corresponding address representation.

Example

Obtaining TL with the contractor with the address 127.0.0.1:2000 in the equivalent of 1:

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tGET:contractors/trust-lines/one/address\t1\t12\t127.0.0.1:2000\t1\n" > fifo/commands.fifo

Response:

Result code: 200 - successfully completed.
405 - TL is absent.

In case of code 200:

  • Contractor’s ID
  • State of the TL
  • State of the TL
  • Indication of your own keys presence
  • Indication of the contractor’s keys presence
  • Incoming Trust Amount (ITA)
  • Outgoing Trust Amount (OTA)
  • Current Balance (CB)

* When receiving the code `405`, no more data is returned.

An example of the command’s result: ``` 13e5cf8c-5834-4e52-b65b-f9281dd1ff91\t200\t2\t2\t1\t1\t200\t5000\t300\n ```


Transaction: List Level 1 Neighbors (Contractors)

GET:contractors
Argument Type Description
Equivalent ID uint32 ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.
An example of getting the list of contractors command:

Returns information about all nodes, to/from which Trust Lines are present on the current node.

Example

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tGET:contractors\t1\n" > fifo/commands.fifo

Response

Result codes:

200 – completed successfully.

  • Number of contractors;
  • List of contractors;
  • Contractor’s ID;
  • Contractor’s address;

An example of the command result with 3 contractors: ``` 13e5cf8c-5834-4e52-b65b-f9281dd1ff91\t200\t3\t0\t1 127:0.0.1:2000\t2\t2 127.0.0.1:2001 127.0.0.1:2002\t5\t1 127.0.0.1:2005\n ``` If the equivalent is 0, then the list of all contractors in all the equivalents will be returned. If not 0, then only those contractors with which there are TLs in this equivalents will be shown. The 0 value is reserved, so it can not be used to denote any particular equivalent.


Transaction: List Equivalents

GET:equivalents

There are no parameters in this transaction.

Returns the list of equivalents in which the node has TLs.

Example

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tGET:equivalents\n" > fifo/commands.fifo

Response

  • 200 – completed successfully;
  • Number of equivalents;
  • List of equivalents;

An example of a command result with 5 equivalents:

13e5cf8c-5834-4e52-b65b-f9281dd1ff91\t200\t5\t1\t6\t8\t2002\t5\n



Transaction: Calculate Max Flow

GET:contractors/transactions/max/fully
Argument Type Description
Number of contractors uint32 How many contractors would be list into the command
Contractors list list List of contractors to which max payment flow should be calculated

Contractors fields

Field Type Description
Address type enum Only IPv4 Addresses are supported at the moment, code 12.
Address string Corresponding address representation.
Equivalent ID uint32 ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.

This transaction combines routing algorithm and flow prediciton algorithm and tries to efficiently scan the network topology and to calculate max. payment flow from the issuer node to each one node, that is listed in arguments. There is no need for direct TLs presence between issuer node and listed nodes: it would be enough if there would exist some paths that are connecting this nodes via some internal nodes. GEO Protocol supports paths that are up to nodes 7 long (icluding command issuer node and the destination node).

Example

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tGET:contractors/transactions/max/fully\t3\t12\t127.0.0.1:2001\t12\t127.0.0.1:2003\t12\t127.0.0.1:2000\t1\n" > fifo/commands.fifo

max_flow_prediction.png

Response

Code 200: OK, operation was performed well.
Code different than 200 indicates an error. Please, refer to the node's codes list for the details.

  • Number of contractors
  • Vector of payment possibilities
    • address type
    • address
    • payment possibility



Transaction: Payment

CREATE:contractors/transactions
Argument Type Description
Number of contractors uint32 How many contractors would be list into the command.
List of contractor addresses list List of addresses that are related to the contractor (node, that should receive the payment).
Amount Pos. BigInt Amount that should be sent to the contractor node.
Equivalent ID uint32 ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.

Addresses fields

Field Type Description
Address type enum Only IPv4 Addresses are supported at the moment, code 12.
Address string Corresponding address representation.

This command initilises payment operation from current node to the contractor. Addresses received in arguments are used for the communication with remote node. Only one address is used at a time.

Example

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tCREATE:contractors/transactions\t1\t12\t127.0.0.1:2003\t2000\t1\n" > fifo/commands.fifo

Response

Result codes:

201 – completed successfully.
401 – protocol error (some conditions are not met).
409 – consensus has not been reached (some nodes doesn't approved the operation).
412 – insufficient payment possibilities (isufficient funds).
444 – the contractor is not reachable (remote node seems to be down).
462 – no payment paths (no connection is possible between sender and receiver node).

When receiving the code 201, the result will also contains transaction UUID – UUID4 id of the transaction that was performed.


Transaction: Get History of Operations With a TL

GET:history/trust-lines

Returns list of records, that represents operations that was done with a Trust Line (except payments), for example: amount changes, opening datetime, closing datetime, etc.

Argument Type Description
Offset uint64 Number of the record from which the scan should be started.
Count uint64 Amount of records that should be returned.
Lower Datime/Time Bound UNIX timestamp Filter by the date/time (from). If not present - must be set to "null".
Upper Datime/Time Bound UNIX timestamp Filter by the date/time (up to). If not present - must be set to "null".

The Shift and the Number of operations parameters are used to get history in portions. The numbering of records starts with 0. Filters are UNIX timestamps. If no filtration is required, then these parameters must be set to null. It is possible to filter with both filters at the same time or with only one of them.

Example

An example of the getting history of operations with a TL command:

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tGET:history/trust-lines\t0\t100\tnull\t1536759923\t1\n" > fifo/commands.fifo

Response

  • 200 – completed successfully;
  • Number of operations returend;
  • List of operations:
    • transaction UUID;
    • Date/Time (UNIX timestamp);
    • Address of the contractor;
    • Type of operation with the TL;
    • Amount;

The type of operation with TL can be as follows: (`todo` specify ENUM of types) * Opening * Accepting * Setting * Updating * Closing * Rejecting * Closing Incoming * Rejecting Outgoing

The sum is different from zero only in Setting and Updating operations (change of trust), in the rest of the cases it equals 0.

If the offset and the cuont parameters will set more operations than the actual number of operations, then the result will only return the existing operations, that meet the command’s criteria.

Example of a history of operations with TLs result (3 operations):

13e5cf8c-5834-4e52-b65b-f9281dd1ff91\t200\t3\t1594425c-98d2-48a0-8802-460f94c73100\t1536759923\t1 127.0.0.1:2005\topening\t0\t355875db-8c2a-4fc2-8186-ba57a5313fd7\t1536458923\t1 127.0.0.1:2005\tsetting\t500\t564afd89-e156-44ac-a322-c23501849ff6\t1536759825\t1 127.0.0.1:2007\taccepting\t0\n



Transaction: Get Payment History

GET:history/payments
Argument Type Description
Offset uint64 Number of the record from which the scan should be started.
Count uint64 Amount of records that should be returned.
Lower Datime/Time Bound UNIX timestamp Filter by the date/time (from). If not present - must be set to "null".
Upper Datime/Time Bound UNIX timestamp Filter by the date/time (up to). If not present - must be set to "null".
Lower Amount Bound +BigInt
Up to 2^256		 Filter by the amount (from). If not present - must be set to "null".
Upper Amount Bound +BigInt
Up to 2^256		 Filter by the amount (up to). If not present - must be set to "null".
Command UUID UUID4 Filter by command. If not present - must be set to "null". if present - the search is carried out only on it without taking into account other parameters.

Example

An example of the receiving a history of operations with TL command:

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tGET:history/payments\t0\t100\tnull\t1536759923\t500\tnull\tnull\t1\n" > fifo/commands.fifo

Response

  • 200 – completed successfully
  • Number of operations
  • List of operations
  • transactionUUID
  • Time: UNIX timestamp
  • Address of the contractor
  • Type of payment
  • Amount
  • The node balance after the operation

The type of payment may be as follows:

  • Incoming (an incoming payment)
  • Outgoing (an outgoing payment)

The resulting balance after operation is the sum of balances for all TLs after the current operation in equivalent of the transaction.

Example of the history of payments command result (3 operations):

13e5cf8c-5834-4e52-b65b-f9281dd1ff91\t200\t3\t1594425c-98d2-48a0-8802-460f94c73100\t1536759923\t1 127.0.0.1:2005\tincoming\t500\t500\t355875db-8c2a-4fc2-8186-ba57a5313fd7\t1536458923\t1 127.0.0.1:2004\outgoing\t300\t200\t564afd89-e156-44ac-a322-c23501849ff6\t1536759825\t1 127.0.0.1:2007\toutgoing\t600\t-400\n



Transasction: Get History With Contractor

GET:history/contractor

Returns a history of TL operations and payments with a contractor that uses ALL the addresses stated in the command parameters.

Argument Type Description
Offset uint64 Number of the record from which the scan should be started.
Count uint64 Amount of records that should be returned.
Number of cont. addresses UNIX timestamp Filter by the date/time (from). If not present - must be set to "null".
List of ocnt. addresses UNIX timestamp Filter by the date/time (up to). If not present - must be set to "null".
Equivalent ID uint32 ID if the equivalent in which TL (Trust Line) should be opened: an integer greater than 0.

Addresses fields

Field Type Description
Address type enum Only IPv4 Addresses are supported at the moment, code 12.
Address string Corresponding address representation.

Example

> echo -e "13e5cf8c-5834-4e52-b65b-f9281dd1ff91\tGET:history/contractor\t0\t100\1\12\127.0.0.1:2005\t1\n" > fifo/commands.fifo

Result

The result codes: 200 – completed successfully

  • Number of operations;
  • List of operations:
    • Operation type (enum);
    • ;

The operation type can be Trustline and Payment.
Depending on the type of operation, there are further fields that describe this operation:

  • Trustline:

    • transactionUUID
    • Time: UNIX timestamp
    • Type of operation with the TL
    • Amount

  • Payment:

    • transactionUUID;
    • Time: UNIX timestamp;
    • Type of payment;
    • Amount;
    • The node balance after the operation;

An example of a history of operations with the contractor command (4 operations): 
13e5cf8c-5834-4e52-b65b-f9281dd1ff91\t200\t4\ttrustline\t1594425c-98d2-48a0-8802-460f94c73100\t1536759923\topen\t0\ttrustline\t355875db-8c2a-4fc2-8186-ba57a5313fd7\t1536458923\tset\t1000\tpayment\t564afd89-e156-44ac-a322-c23501849ff6\t1536759825\tincoming\t600\t600\tpayment\t355875db-8c2a-4fc2-8186-ba57a5313fd7\t1536734825\toutgoing\t400\t200\n