REST and Socket connections

ADAMANT Node provides RESTful API to process clients' requests. REST requests are reliable and fit for most of tasks.

WebSocket

In some cases client needs to get new transactions instantly, allowing users superior performance. It is most important for messaging applications to provide smooth experience for chatting. This way nodes provide socket connections.

Node's configuration

To enable node for sockets, refer to wsClient section of config.json:

"wsClient": {
    "portWS": 36668,
    "enabled": true
}

To check if node offers socket connections, request status:

https://endless.adamant.im/api/node/status

{
  "success": true,
  "nodeTimestamp": 226901657,
  // ...
  "wsClient": {
    "enabled": true,
    "port": 36668
  }
}

Listen for updates

Clients are able to listen socket to get notified about all of transactions, including unconfirmed yet. New unconfirmed transactions has no block_timestamp. Most of transactions fetched by socket are new and unconfirmed as they just appeared in the ADAMANT network, and not stored in blockchain yet. Important to understand this fact to process transfer (amount > 0) transaction correctly, check if transaction confirmed in the network, and confirmation count.

Note

While an unconfirmed transaction hopes to be confirmed, it faces the risk of being rejected by the network's nodes if it violates its consensus

Nodes emit transactions of all types with newTrans event, and client app should filter them according to its needs (f. e., which ADM address, recipient or sender, transaction type). For socket connections, nodes store pool of transactions for 60 seconds.

Socket should be not the only connection, but additional to REST requests. This is because socket connection can be lost for some time, and fetching transactions by REST from time to time makes an application much more reliable. Still socket allows to send REST requests less often. When a new transaction received by socket, it should be checked with REST request for its status.

To listen to new transactions by socket, subscribe to node's newTrans event. Here is an example:

import {io} from 'socket.io-client';

const connection = io('https://endless.adamant.im/', {
  reconnection: false,
  timeout: 5000,
})

connection.on('connect', () => {
  console.log('connected')
})

connection.on('newTrans', (transaction) => {
  console.log(transaction)
})

connection.on('disconnect', (reason) => {
  console.log(`disconnected, reason: ${reason}`)
})

connection.on('connect_error', (error) => {
  console.warn(`connection error: ${error}`)
});

You can also filter the transaction by the address and transaction types:

connection.on('connect', () => {
  console.log('connected')

  // subscribe to incoming/outcoming transactions from the address 
  socket.emit('address', 'U1234567890123456');

  // subscribe to "transfer" and "chat message" transactions 
  socket.emit('types', [0, 8]);
})


// log new transactions
socket.on('newTrans', console.log.bind("Message/transfer transaction in the user's chat:"));

In addition, you can filter transactions by its asset.chat.type the same way you do it for transaction type:

connection.on('connect', () => {
  console.log('connected')

  // subscribe to incoming/outcoming transactions from the address 
  socket.emit('address', 'U1234567890123456');

  // subscribe to "transfer" and "chat message" transactions 
  socket.emit('assetChatTypes', 3);
})

This will make you automatically subscribe to message transaction type if you weren't subscribed to it.

CORS

By default, ADAMANT Node allows any origins to make requests. You can control CORS with the cors object option in config.json that accepts following properties:

• origin: Configures the Access-Control-Allow-Origin CORS header. Possible values:
  • Boolean - set origin to true to reflect the request origin, as defined by req.header('Origin'), or set it to false to disable CORS.
  • String - set origin to a specific origin. For example if you set it to "http://example.com" only requests from "http://example.com" will be allowed.
  • Array - set origin to an array of valid origins. For example ["http://example1.com", "http://example2.com/"] will accept any request from "http://example1.com" or "example2.com".
• methods: Configures the Access-Control-Allow-Methods CORS header. Expects a comma-delimited string (ex: 'GET,PUT,POST') or an array (ex: ['GET', 'PUT', 'POST']).

Example:

{
  "cors": {
    "origin": "http://example1.com",
    "methods": "GET,PUT,POST"
  }
}