Communications

4.1 - Create endpoints

To communicate with an NIS you need an endpoint object. The object contains the node host and port so it is easier to handle.

Examples 

// Custom endpoint
var endpoint = nem.model.objects.create("endpoint")("http://myNode", 7890);

// Using sdk data
var endpoint = nem.model.objects.create("endpoint")(nem.model.nodes.defaultTestnet, nem.model.nodes.defaultPort);

4.2 - API requests

Namespace: nem.com.requests

22 NIS API calls and a few other external requests are implemented and organised in namespaces:

nem.com.requests.account

  • data: Gets account data
  • forwarded: Gets the account data of the account for which the given account is the delegate account
  • harvesting.blocks: Gets harvested blocks
  • harvesting.stop: Stop delegated harvesting
  • harvesting.start: Start delegated harvesting
  • namespaces.owned: Gets namespaces that an account owns
  • mosaics.owned: Gets mosaics that an account owns
  • mosaics.allDefinitions: Gets all mosaic definitions that an account owns
  • mosaics.definitions: Gets mosaic definitions that an account has created
  • transactions.incoming: Gets incoming transactions
  • transactions.unconfirmed: Gets unconfirmed transactions
  • transactions.all: Gets all transactions
  • transactions.outgoing: Gets outgoing transactions
  • unlockInfo: Gets information about the maximum number of allowed harvesters and how many harvesters are already using the node

nem.com.requests.apostille

  • audit: Audit an apostille

nem.com.requests.chain

  • height: Gets the chain height
  • lastBlock: Gets the last block
  • time: Get network time

nem.com.requests.endpoint

  • heartbeat: Gets the node status

nem.com.requests.market

  • xem: Gets XEM price in BTC
  • btc: Gets BTC price in $

nem.com.requests.namespace

  • roots: Gets root namespaces
  • info: Gets the namespace with given id
  • mosaicDefinitions: Gets mosaic definitions of a namespace

nem.com.requests.supernodes

  • all: Gets all supernodes info

nem.com.requests.transaction

  • byHash: Gets a transaction by hash
  • announce: Announce a transaction to the network

4.3 - Usage

Requests are wrapped in Promises which allow to use then() for callbacks

Examples: 

// Gets chain height
nem.com.requests.chain.height(endpoint).then(function(res) {
	console.log(res)
}, function(err) {
	console.error(err)
})

// Gets account data
nem.com.requests.account.data(endpoint, "TBCI2A67UQZAKCR6NS4JWAEICEIGEIM72G3MVW5S").then(...);

4.4 - More

Consult src/com/requests for details about requests parameters.

  • See examples/browser/monitor for browser demonstration
  • See examples/node/requests for all requests in node

4.5 - WebSockets

Namespace: nem.com.websockets

Note: For now webSockets use two versions of SockJS to work in Node (v1.1.4) and the browser (v0.3.4). Using only latest SockJS v1.1.4, gives an error when used in browser:

XMLHttpRequest cannot load http://bob.nem.ninja:7778/w/messages/info?t=1429552020306. A wildcard '*' cannot be used in the 'Access-Control-Allow-Origin' header when the credentials flag is true. Origin 'null' is therefore not allowed access.

If anyone has a solution to that, it is welcome.

nem.com.websockets.connector

  • create: Create a connector object

nem.com.websockets.subscribe

  • errors: Subscribes to error channel

nem.com.websockets.subscribe.account

  • data: Subscribes to account data channel
  • transactions.recent: Subscribes to recent transactions channel
  • transactions.confirmed: Subscribes to confirmed transactions channel
  • transactions.unconfirmed: Subscribes to unconfirmed transactions channel

nem.com.websockets.subscribe.chain

  • height: Subscribes to new chain height channel
  • blocks: Subscribes to new blocks channel

nem.com.websockets.requests.account

  • data: Requests account data from channel
  • transactions.recent: Requests recent transactions from channel

4.6 - Usage

You first need to create a connector object pointing to the right endpoint then use this connector to open the connection.

If connection is a success, the connector.connect function will resolve a promise in a .then() function, in which you can request and subscribe to channels.

Subscription takes a connector and resolve in a simple callback function (.then() not supported), where your data will be received from the channel. It acts exactly like a .on('something').

Parameters

create
Name Type Description
endpoint object An endpoint object (using websocket port)
address string A NEM account address
All subscription methods
Name Type Description
connector object An open connector object
callback function A callback function where data will be received
address string A NEM account address (optional, for custom account subscription)
All request methods
Name Type Description
connector object An open connector object
address string A NEM account address (optional, for custom account request)

Example: 

// Create an endpoint object
var endpoint = nem.model.objects.create("endpoint")(nem.model.nodes.defaultTestnet, nem.model.nodes.websocketPort);

// Address to subscribe
var address = "TBCI2A67UQZAKCR6NS4JWAEICEIGEIM72G3MVW5S";

// Create a connector object
var connector = nem.com.websockets.connector.create(endpoint, address);

// Connect using connector
connector.connect().then(function() {
  // If we are here we are connected
  console.log("Connected");

  // Subscribe to new blocks channel
  nem.com.websockets.subscribe.chain.blocks(connector, function(res) {
    console.log(res);
  });

  // Subscribe to account data channel
  nem.com.websockets.subscribe.account.data(connector, function(res) {
    console.log(res);
  });

  // Request account data
  nem.com.websockets.requests.account.data(connector);

}, function (err) {
  // If we are here connection failed 10 times (1/s).
  console.log(err);
});

4.7 - More

Consult src/com/websockets for details.

  • See examples/browser/websockets for browser demonstration
  • See examples/nodejs/websockets.js for Node demonstration