Documentation

# NULS2.0 API

NULS customized the NULS2.0 wallet version required for docking. The docking wallet embeds the NULS-API module. The module encapsulates the NULS-SDK function, uses the HTTP protocol to access the interface, and supports JSON-RPC and RESTful two formats.

mainnet and test wallet download address (opens new window)

NULS-API offline operation tool download address (opens new window)

# Settings

The default port number for the NULS-API module is 18004, which can be modified in the nuls.ncf configuration file (for the entire wallet chainbox) or the module.ncf configuration file (for the individual module), as follows:

[nuls-API]
#httpServerStart port
serverPort=18004

# Description

In order to better understand the related business of NULS2.0, and the meaning of the return value of the interface, do some explanation here in advance.

# Online & Offline

The nuls-api module provides several online and offline interfaces.

Online interface: The wallet must operate normally and be able to connect to other nodes in the network to properly synchronize blocks and broadcast data. Before calling the online interface, it is best to sync to the latest block. The data generated by the interface is saved in the wallet. For example, create an account, change a password, transfer money, get a block header, and so on.

Offline interface: NULS 2.0 provides a NULS-API tool for offline operation (opens new window) .No need to install a wallet, you can run independently on a server that is not connected to the network.The user receives the relevant parameters by calling the offline interface, and obtains the return value, and the corresponding data is not stored in the wallet.For example, creating an account offline, offline assembly transfer transactions, offline signatures, and the like.

# Field Description

chainId:

NULS2.0 supports multi-chain parallel and cross-chain transfers. Each chain is distinguished by chain ID. The chain ID of NULS MainNet is 1, and that of NULS TestNet is 2.

Chain Assets:

Besides the default asset, NULS2.0 supports the dynamic addition of assets to each chain according to business needs. Each asset in each chain is distinguished by a composit primary key of the chain ID and the asset ID. For example, NULS, the default asset of NULS MainNet, has the chainId = 1 and assetId = 1.

Transaction Type:

NULS2.0 has multiple transactions with different functions by default. When calling the interface to query transaction details, different transaction types can be distinguished by the type field. The following are the enum values of the transaction type (txType):

int COIN_BASE = 1;						//coinBase reward
int TRANSFER = 2;						//transfer
int ACCOUNT_ALIAS = 3;					//set account alias
int REGISTER_AGENT = 4;					//register consensus node
int DEPOSIT = 5;						//stake to join consensus
int CANCEL_DEPOSIT = 6;					//cancel staking
int YELLOW_PUNISH = 7;					//yellow card punishment
int RED_PUNISH = 8;						//red card punishment
int STOP_AGENT = 9;						//unregister consensus node
int CROSS_CHAIN = 10;					//cross-chain transfer
int REGISTER_CHAIN_AND_ASSET = 11;		//register chain
int DESTROY_CHAIN_AND_ASSET = 12;		//destroy chain
int ADD_ASSET_TO_CHAIN = 13;			//add asset to chain
int REMOVE_ASSET_FROM_CHAIN = 14;		//remove asset from chain
int CREATE_CONTRACT = 15;				//create contract
int CALL_CONTRACT = 16;					//call contract
int DELETE_CONTRACT = 17;				//delete contract
int CONTRACT_TRANSFER = 18;				//contract transfer
int CONTRACT_RETURN_GAS = 19;			//contract for returning fee
int CONTRACT_CREATE_AGENT = 20;			//contract for registering consensus node
int CONTRACT_DEPOSIT = 21;				//contract for staking to join consensus
int CONTRACT_CANCEL_DEPOSIT = 22;		//contract for canceling staking
int CONTRACT_STOP_AGENT = 23;			//contract for unregistering consensus node
int VERIFIER_CHANGE = 24;				// validator change

from and to in transaction：

Take the transfer transaction as an example: tx.type = 2

From is the sender of the transfer transaction. Each from is regarded as the amount of assets transferred by a sender. The nonce changes after each transfer and the latest nonce can be obtained by calling the interface: get account balance.

To is the receiver of the transfer transaction. Each to is considered as the amount of assets that the recipient receives, and lockTime is the lock-in time. When the lockTime is greater than 0, it means that the asset can be usable only if the actual time exceeds this value; when lockTime = -1, it means that the asset is locked permanently and can be unlocked with special transactions, such as joining staking and canceling staking.

Transaction fees = sum of main assets of this chain in from - sum of main assets of this chain in to

# Access Mode

  • JSON-RPC

Add request header: Content-Type: application/json;charset=UTF-8 HttpMethod: POST URL: http://${ip}😒{port}/jsonrpc

For example: http://127.0.1:18004/jsonrpc

Request Format:

```json

{
    "jsonrpc":"2.0",
    "method":"methodCMD", //interface name
    "params":[],  //all parameters of the interface passed in an array, and the order of parameters can not be changed. If the parameters are not required, you should also fill in null.
    "id":1234
}
```
  • RESTFUL

Add request header:

Content-Type: application/json;charset=UTF-8

For the rest, please refer to RESTFUL API Documentation (opens new window)

# API Documentation

We provide two types of API, namely JSON-RPC and Restful. Users can choose different docking methods according to their needs. Please see the interface documentation below for details:

JSON-RPC API Documentation (opens new window)

RESTFUL API Documentation (opens new window)

_ FYI: The official tool NULS-SDK-4J is available now, through which partners using JAVA can dock NULS-SDK-Provider module, see: NULS-SDK-4J Instructions (opens new window)

# API Debugging

We provide the import files of (JSON-RPC and RESTFUL) for Postman interface debug tool. Users can debug interfaces with the corresponding file imported.

JSON-PRC API Debugging-POSTMAN Import File (opens new window)

RESTFUL API Debugging-POSTMAN Import File (opens new window)