Nodes handler API

Common types
Amount

Amount is the base type for all operations, that are requiring pair of amount and equivalent, for example, payment operations, or some operations with trust lines.

Positive BigInt representation in string format. The comma is ommited, because the number will be represented in 10**8 (power of 8) notation. For example, 1 dollar will be represented as 1 * 10**8 dollars in the system. Max value == 2**32.

string
Min length: 1
Nodes executors handler API

API for the nodes handler that manages internal nodes processes in the DC.

V1
Nodes
POST /api/v1/nodes/
DELETE /api/v1/nodes-handlers/{uuid}/
Create
POST /api/v1/nodes/

Creates and runs new node executor, by creating it’s directory with randomly generated node uuid;

Responses

201 Created
500 Internal Server Error

Examples

POST /api/v1/nodes-handlers/ HTTP/1.1 

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000"
    }
}
[DEPRECATED] Close (disable node)
DELETE /api/v1/nodes-handlers/{uuid}/
  • Stops node executor;
  • Marks it as disabled, by prefixing it’s directory with “(disabled-)”, so this account will be ignored on the next startup;

WARN: doesn’t removes account’s data. It may be neede for the restore purposes.

Path variables

uuid
string required

Responses

200 OK

Node was deactivated successfully.

404 Not Found

There is no node with exact uuid.

412 Precondition Failed

Node is present, but is alredy disabled.

GEO-Pay engine proxy API

Engine Proxy - distibuted HTTP Server, that provides access to nodes via HTTP API. This proxy server is used by the GEO Pay backend for reaching nodes info. Provied API methods take part on maintaining trust lines and transactions on them.

V1
Contractors
GET /api/v1/contractors/
List
GET /api/v1/contractors/

Responses

200 OK
500 Internal Server Error

Examples

No contractors

GET /api/v1/contractors/ HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "data": {
    "count": 0,
    "uuids": [] 
  }
}

Contractors present

GET /api/v1/contractors/ HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "data": {
    "count": 1,
    "uuids": ["1b822993-4515-4ee4-adb9-fa2b3347a705"]
  }
}
Trust Lines
POST /api/v1/contractors/{contractor_uuid}/trust-lines/
DELETE /api/v1/contractors/{contractor-uuid}/trust-lines/
PUT /api/v1/contractors/{contractor-uuid}/trust-lines/
GET /api/v1/contractors/trust-lines/
Open
POST /api/v1/contractors/{contractor_uuid}/trust-lines/

Initiates creating of the trust line to the contractor node with total credit amount = amount.

https://paper.dropbox.com/doc/Commands-specification-Clr2Q6huMBygwqhvNM6yn#:uid=401732180630833&h2=Contractors-/-Trust-Lines-/-Op

Path variables

contractor_uuid
string required

UUID of the node, to which the trust line should be opened.

Request parameters

amount
Amount required

Represents how much current node trusts to the contractor node

Responses

400 Bad request

Some param(s) is(are) ommited or is(are) invalid.

404 Node Not Found

No requested node is present in the system.

500 Internal Server Error

Some requests-delivering subsystem is broken, or, some unknown error has been occured on the server.

503 Node is gone

Node process is gone and doesn’t processes incomming commands.

Close
DELETE /api/v1/contractors/{contractor-uuid}/trust-lines/

Initiates closing the trust line to the contractor node.

In case if trust line doesn’t contains used debt - it would be automatically deleted. Otherwise - it would be only closed, so the debt-clearing operations would be allowed, and debt-usage operations would be rejected.

https://paper.dropbox.com/doc/Commands-specification-Clr2Q6huMBygwqhvNM6yn#:uid=342787301274818&h2=Contractors-/-Trust-Lines-/-Cl

Path variables

contractor-uuid
string required

Responses

400 Bad Request

Some param(s) is(are) ommited or is(are) invalid.

404 Node Not Found

No requested node is present in the system.

500 Internal Server Error

Some requests-delivering subsystem is broken, or, some unknown error has been occured on the server.

503 Service Unavailable: node is gone

Node process is goneand doesn’t processes incomming commands.

Set
PUT /api/v1/contractors/{contractor-uuid}/trust-lines/

Path variables

contractor-uuid
string required

Request parameters

amount
Amount required

New outgoing trust line amount.

Responses

400 Bad Request

Some param(s) is(are) ommited or is(are) invalid.

404 Node Not Found

No requested node is present in the system.

500 Internal Server Error

Some requests-delivering subsystem is broken, or, some unknown error has been occured on the server.

503 Service Unavailable: node is gone

Node process is gone and doesn’t processes incomming commands.

List
GET /api/v1/contractors/trust-lines/

Responses

200 OK
500 Internal Server Error

Examples

GET /api/v1/contractors/trust-lines/ HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "data": {
    "count": 1,
    "trust_lines": [
      {
        "uuid": "uuid",
        "incoming_trust_amount": "1000",
        "outgoing_trust_amount": "2000",
        "balance": "500"
      }
    ]
  }
}

No trust lines

GET /api/v1/contractors/trust-lines/ HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "data": {
    "count": 0,
    "trust_lines": []
  }
}
Transactions
POST /api/v1/contractors/{contractor_uuid}/transactions/
GET /api/v1/contractors/{contractor-uuid}/transactions/max/
Pay (generate transaction)
POST /api/v1/contractors/{contractor_uuid}/transactions/

Path variables

contractor_uuid
string required

Request parameters

amount
Amount required
purpose
string optional
[v1.1] Equivalent
string optional

[delayed to v1.1]

Responses

201 Created

Examples

OK

POST /api/v1/contractors/{contractor_uuid}/transactions/ HTTP/1.1 

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "data": {
        "transaction_uuid": "1b822993-4515-4ee4-adb9-fa2b3347a705"
    }
}
Calculate max transaction amount
GET /api/v1/contractors/{contractor-uuid}/transactions/max/

Returns max available credit amount from contractor node to the current node.

Path variables

contractor-uuid
string required

Request parameters

[v1.1] Equivalents
string optional

Responses

200 OK

Examples

GET /api/v1/contractors/{contractor-uuid}/transactions/max/ HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        "max_amount": "1000"
    }
}
Commands description
Stats
Balances
[Request] Total balance of the node

Estimated time complexity: <4s

Sends request to the node node_uuid. Returns it’s reported current total balance in string representation.


Format: <uuid> [space] GET:nodes/stats/balances/total/ [space] <node uuid> \n

Example: 550e8400-e29b-41d4-a716-446655440000 GET:nodes/stats/balances/total/ 3734898d-e294-4af9-9354-2467aa53a615


Respt: OK

<uuid> [space] 200 [space] <total incoming trust> [space] <total incoming trust used> [space] <total outgoing trust> [space] <total outgoing trust used> [space] \n

Notes:

  1. In case if node doesn’t have any contractors - it’s total balance is 0.
  2. Some values may be set to 0 too;
  3. total incoming trust used <= total incoming trust;
  4. total outgoing trust used <= total outgoing trust;

Resp: Data is unavailable

<uuid> [space] 501 \n

Total balance

Estimated time complexity: <1s

Returns total balance of the node in string representation.


Format: <uuid> [space] GET:/stats/balances/total [space] \n

Example: 550e8400-e29b-41d4-a716-446655440000 GET:stats/balances/total/


Resp: OK

<uuid> [space] 200 [space] <total incoming trust> [space] <total incoming trust used> [space] <total outgoing trust> [space] <total outgoing trust used> [space] \n

Notes:

  1. In case if node doesn’t have any contractors - it’s total balance is 0.
  2. Some values may be set to 0 too;
  3. total incoming trust used <= total incoming trust;
  4. total outgoing trust used <= total outgoing trust;
Open

Estimated time complexity: < 4s

Creates outgoing trust line to the contractor. Ensures accepting of the TL by the contractor’s side.


Format: <uuid> [\r] CREATE:contractors/trust-lines [\r] <contractor uuid> [\r] <amount> \n

Example: 550e8400-e29b-41d4-a716-446655440000\rCREATE:contractors/trust-lines\r06e0c9e9-15d0-4404-b7a9-d2c9ce5f004d\r1000


Resp: OK

<uuid> [\r] 200 \n


Resp: Trust line is already present

<uuid> [\r] 409 \n


Resp: Unexpected error

<uuid> [\r] 501 \n

Close

Estimated time complexity: < 4s

Closes outgoing trust line to the contractor. Ensures rejecting of the TL by the contractor’s side. This operation can’t be performed without manual user input token hash in case when TL contains debt.


Format: <uuid> [\r] REMOVE:contractors/trust-lines [\r] <contractor uuid> [\r] <optional: manual user input token hash> \n

Example:

  • 550e8400-e29b-41d4-a716-446655440000\rREMOVE:contractors/trust-lines\r06e0c9e9-15d0-4404-b7a9-d2c9ce5f004d
  • 550e8400-e29b-41d4-a716-446655440000\rREMOVE:contractors/trust-lines\r06e0c9e9-15d0-4404-b7a9-d2c9ce5f004d\raa83395f1aadd2fa296cb9e53a326b4e204d8616e6459f8b45dc9ce703246ff1

Resp: OK

<uuid> [\r] 200 \n


Resp: Trust line with received contractor is absent

<uuid> [\r] 404 \n


*Resp: Trust line contains debt and manual user input is absent or invalid *

<uuid> [\r] 409 \n


Resp: Unexpected error

<uuid> [\r] 501 \n

Update

Estimated time complexity: < 4s

Updates outgoing trust line to the contractor. Ensures updating of the TL by the contractor’s side. Operation can’t be performed in case when new trust line amount is less, than current debt.


Format: <uuid> [\r] SET:contractors/trust-lines [\r] <contractor uuid> [\r] <new amount> \n

Example: 550e8400-e29b-41d4-a716-446655440000 SET:contractors/trust-lines 06e0c9e9-15d0-4404-b7a9-d2c9ce5f004d 2000


Resp: OK

<uuid> [\r] 200 \n


Resp: Trust line is absent

<uuid> [\r] 404 \n


Resp: Trust line is present, but contains the debt, than is greater than new amount

<uuid> [\r] 409 \n


Resp: Unexpected error

<uuid> [\r] 501 \n

Calculate max transaction

Estimated time complexity: < 10s

Sends requests to the network and calculates max avaiable transaction to the contractor.


Format: <uuid> [\r] GET:contractors/transactions/max [\r] <contractor uuid> \n

Example: 550e8400-e29b-41d4-a716-446655440000\rGET:contractors/transations/max\r06e0c9e9-15d0-4404-b7a9-d2c9ce5f004d


Resp: OK

<uuid> [\r] 200 [\r] <max available amount> \n


Resp: Unexpected error

<uuid> [\r] 501 \n

Use credit

Estimated time complexity: < 10s

Attempts to use credit of the node <contractor>.


Format: <uuid> [\r] CREATE:payments/transaсtions [\r] <contractor uuid> [\r] <amount> [\r] <reason: text description why this operation is performed> \n

Example:

  • 550e8400-e29b-41d4-a716-446655440000\rCREATE:contractors/transations\r73928467-5d5c-4558-b843-fa1e6d8031c4\r100
  • 550e8400-e29b-41d4-a716-446655440000\rCREATE:contractors/transations\r73928467-5d5c-4558-b843-fa1e6d8031c4\r100\rtax payments

Resp: OK

<uuid> [\r] 200 [\r] <transaction UUID> [\r] <operation amount> [\r] <result code> [\r] timestamp transaction received [\r] timestamp transaction processed [\r] <reason> [\n]

See Transaction result for the details.


Resp: not enought credit amount

<uuid> [\r] 412 \n


Resp: Unexpected error

<uuid> [\r] 501 \n

Node handler
Object
UUID
string

UUID of the node (the same as node UUID of the user in the GEO-system)