Nodes handler API

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

Methods: Open Pay (generate transaction) Set

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

Create

POST /api/v1/nodes/

[DEPRECATED] Close (disable node)

DELETE /api/v1/nodes-handlers/{uuid}/

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"
    }
}

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.

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.

List

GET /api/v1/contractors/

https://paper.dropbox.com/doc/Commands-specification-Clr2Q6huMBygwqhvNM6yn#:uid=904549593559328&h2=Contractors-/-List

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"]
  }
}

Open

POST /api/v1/contractors/{contractor_uuid}/trust-lines/

Close

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

Set

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

List

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

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.

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.

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

Updates outgoing trust amount of the trust line to the contractor node.

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

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.

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

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

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": []
  }
}

Pay (generate transaction)

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

Calculate max transaction amount

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

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

Specs: https://paper.dropbox.com/doc/Commands-specification-Clr2Q6huMBygwqhvNM6yn#:uid=803294973322817&h2=Contractors-/-Transactions-/-U

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"
    }
}

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"
    }
}

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:

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

Resp: Data is unavailable

<uuid> [space] 501 \n

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:

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

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

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

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

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

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

Object

UUID

string

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