Skip to content

API Specification

Jump to bottom
adamant-al edited this page May 28, 2021 · 31 revisions

The library allows to send and retrieve transactions/messages, and get other data from blockchain.

Methods return formatted request results.

get

Performs GET-request to ADAMANT blockchain endpoints.

Format:

get(endpoint, params, maxRetries)

Parameters:

  • endpoint — node's endpoint, f. e., accounts/getPublicKey
  • params — endpoint parameters object, filters and options
  • maxRetries — how much re-tries to process a request, total tries is maxRetries+1. Before every re-try, the library performs new Heath Check and gets a new active node. Default is 3.

Returns:

Promise of formatted request results.

Example:

get('accounts/getPublicKey', { address: 'U6386412615727665758' })

getPublicKey

To get account's public key, you can use get, but getPublicKey() method is more convenient in many cases, and it caches public keys.

Format:

getPublicKey(address)

Parameters:

  • address — ADAMANT address

Returns:

Promise of public key, string. If unable to get public key for any reason, false.

Example:

getPublicKey('U6386412615727665758')

sendTokens

Creates Token Transfer transaction, signs it, and broadcasts to ADAMANT network.

Format:

sendTokens(passPhrase, address, amount, isAmountInADM = true, maxRetries)

Parameters:

  • passPhrase — senders's passPhrase. Sender's address will be derived from it.
  • addressOrPublicKey — recipient's ADAMANT address (preferred) or public key. If you'll pass public key, the library will derive address from it.
  • amount — amount to send, number or string
  • isAmountInADM — set true, if amount specified in ADM (default), or false, if in sats (10^-8 ADM)
  • maxRetries — how much re-tries to process a request, total tries is maxRetries+1. Before every re-try, the library performs new Heath Check and gets a new active node. Default is 4.

Returns:

Promise of formatted request results.

Example:

sendTokens('only ladder great same figure click organ metal main tide expand protect', 'U6386412615727665758', '10.09876543')

sendMessage

Encrypts a message, creates Message transaction, signs it, and broadcasts to ADAMANT network. Supports Basic, Rich and Signal Message Types. Along with sending a message, you can transfer ADM tokens in one transaction.

Format:

sendMessage(passPhrase, address, message, message_type = 'basic', amount, isAmountInADM = true, maxRetries)

Parameters:

  • passPhrase — senders's passPhrase. Sender's address will be derived from it.
  • addressOrPublicKey — recipient's ADAMANT address or public key. Using public key is faster, as the library wouldn't request it from the network. Though it caches public keys, and next request with address will be processed as fast as with public key.
  • message — message plain text in case of basic message. Stringified JSON in case of rich or signal messages. The library will encrypt a message.
  • message_type — type of message: basic, rich, or signal
  • amount — amount of ADM tokens to send with a message, number or string. If amount is set, message field will be used as a comment for ADM transfer of basic message.
  • isAmountInADM — set true, if amount specified in ADM (default), or false, if in sats (10^-8 ADM)
  • maxRetries — how much re-tries to process a request, total tries is maxRetries+1. Before every re-try, the library performs new Heath Check and gets a new active node. Default is 4.

Returns:

Promise of formatted request results.

Example of basic message:

sendMessage('only ladder great same figure click organ metal main tide expand protect', 'U6386412615727665758', 'Hi, Joe Doe!')

Example of token transfer with a comment:

sendMessage('only ladder great same figure click organ metal main tide expand protect', 'U6386412615727665758', 'It is a comment for a transfer', 'basic', '10.09876543')

Example of rich message for Ether in-chat transfer:

sendMessage('only ladder great same figure click organ metal main tide expand protect', 'U6386412615727665758', '{"type":"eth_transaction","amount":"0.002","hash":"0xfa46d2b3c99878f1f9863fcbdb0bc27d220d7065c6528543cbb83ced84487deb","comments":"I like to send it, send it"}')

Formatted request results

Get and send requests return an object with keys:

  • success — if http request was successful, and a node replied with success, true. Otherwise, false.
  • data — if http request was successful, contains node's reply. Otherwise, it's undefined.
  • details — additional information of http request
  • errorMessage — if success is false, contains an error message. Error message starts with Node's reply: when http request was successful, but a node haven't processed it (data.success is false). If success is true, errorMessage is undefined.

Node's reply data is an object returned by endpoint. Example:

{
  "success": true,
  "nodeTimestamp": 58665858,
  "account": {
    "address": "U777355171330060015",
    "unconfirmedBalance": "4509718944753",
    "balance": "4509718944753",
    "publicKey": "a9407418dafb3c8aeee28f3263fd55bae0f528a5697a9df0e77e6568b19dfe34",
    "unconfirmedSignature": 0,
    "secondSignature": 0,
    "secondPublicKey": null,
    "multisignatures": [],
    "u_multisignatures": []
  }
}

Http request details object includes:

  • status — http code of request
  • statusText — http status description
  • error — http response error info
  • message — additional error info, if available
  • response — full http response

Example of successful response results:

{
  "success": true,
  "data": {
    "success": true,
    "nodeTimestamp": 117734677,
    "delegate": {
      "username": "noisy_pool",
      "address": "U17540241492452900105",
      "publicKey": "677c6db63548c99674fed0571da522a6a9569d0c1da9669734a3625645519641",
      "vote": "197161968259285",
      "votesWeight": "68008019722789",
      "producedblocks": 135519,
      "missedblocks": 876,
      "rate": 71,
      "rank": 71,
      "approval": 0.64,
      "productivity": 99.36
    }
  },
  "details": {
    "status": 200,
    "statusText": "OK",
    "response": {
      "status": 200,
      "statusText": "OK",
      "headers": [Object],
      "config": [Object],
      "request": [ClientRequest],
      "data": [Object]
    }
  }
}

Successful http request, but a node haven't processed it:

{
  "success": false,
  "data": {
    "success": false,
    "nodeTimestamp": 117734954,
    "error": "Delegate not found"
  },
  "errorMessage": "Node's reply: Delegate not found",
  "details": {
    "status": 200,
    "statusText": "OK",
    "response": {
      "status": 200,
      "statusText": "OK",
      "headers": [Object],
      "config": [Object],
      "request": [ClientRequest],
      "data": [Object]
    }
  }
}

Unsuccessful http request:

{
  "success": false,
  "data": undefined,
  "errorMessage": "Error: Request failed with status code 404. Message: Cannot GET /api/delegates1/get?publicKey=677c6db63548c99674fed0571da522a6a9569d0c1da9669734a3625645519641",
  "details": {
    "status": 404,
    "statusText": "Not Found",
    "error": "Error: Request failed with status code 404",
    "message": "Cannot GET /api/delegates1/get?publicKey=677c6db63548c99674fed0571da522a6a9569d0c1da9669734a3625645519641",
    "response": {
      "status": 404,
      "statusText": "Not Found",
      "headers": [Object],
      "config": [Object],
      "request": [ClientRequest],
      "data": "Cannot GET /api/delegates1/get?publicKey=677c6db63548c99674fed0571da522a6a9569d0c1da9669734a3625645519641\n"
    }
  }
}
Clone this wiki locally