NULS Document for Exchange

1. Introduction

This document gives a detailed definition of the RPC interface

provided by the node of NULS to the exchange. Any relevant technician,
please intensively read this document and follow by instruction.

2. Agreement

2.1 Protocol

HTTP protocol

2.2 Character Encoding

UTF-8

2.3 Input/ Output Format

Input: restful

Output：String (json String)

2.4 NULS Token Agreement

Unless otherwise specified, NULS tokens mentioned in this

document are all in Na. 1NULS = 100,000,000 Na
3. Start a NULS node (for Linux)

Download:

Unpack:

tar zxvf NULS-Wallet-*.-linux-x64.tar.gz

start node:

cd bin && start.sh

4. Configuration Instructions

4.1 Project Configuration File：conf/modules.ini

4.1.1 Network Module Configuration： [network]

network.server.port=8003 //Local P2P node server port number

network.max.in=20 // Passive connections maximum number

recommend 10-20

network.max.out=20 //Active connections maximum number

recommend 10-20

4.1.2 RPC Configuration： [client]

server.ip=127.0.0.1 // IP address of the RPC protocol

server.port=8001 //RPC protocol port number

request.white.sheet=127.0.0.1 //White list of IP address for accessing

RPC, separate multiple addresses by comma

5. Interface

The description regarding the RPC interface in the following chapter is only

limited to node of NULS to exchange, for SDK and the other interface

definition, see NULS Document for Interface and NULS Document for SDK

Interface.

5.1 Interface Description

5.1.1 Call interface

Access method：restful format

Access path：http://{server.ip}:{server.port}/api/xxxxx

e.g. ： http://127.0.0.1:8001/api/block/height/{height} //GET

request

Content-Type：application/json

parameter：

{para_a} : para_a is in url;

<para_b> : para_b is required;

[para_c] : para_c is optional.

5.1.2 Return Value

Return value Result is a json string, consisting of success (boolean)and

data (a jsonObject).
Successful example：

“success”: true,

“data”:{……} //jsonObject

Failed example: Return error code and error message

“success”:false,

“data”: {

“code”:”ACT500”,

“message”:”xxxxx…….”

5.2 Definition of Return Type

Unspent Transaction Output (UTXO) ：outputJson

outputJson: {

index: int, --index

address: String, --address

value: long, --the amount of tokens

createTime: long, --create time

lockTime: long, --Lock time. For details, please see Data definition in
5.3.2.

status: int --status： 0 Unspent, 1 Highly Locked, 2 Consensus

Locked, 3 Spent

Transaction input：inputJson

inputJson: {

index: int, --index

address: String, --address from output

fromHash: String, --transaction hash from output

fromIndex: int, --outIndex from output

value：Long --the amount of tokens from output

Transaction：txJson

txJson: {

hash: String, -- transaction hash

type: int, --type of transaction (For more details, please

see the definition of data type )

time: long, --start time of the transaction

blockHeight: long, --block height

fee: long, --transaction fee

remark: String, --remark: Hex.encode(byte[])

scrpitSig: String, --signature: Hex.encode(byte[])

size:int, --size of transaction

confirmCount：long, --frequency of confirmations

status:int. --transaction status: 0 indicates “to be

confirmed”, and 1 indicates “confirmed”
 inputs: [{inputJson},{inputJson},……],

outputs:[{outputJson},{outputJson},……]

Block Header：blockHeaderJson

blockHeaderJson: {

hash: String, --block hash ,

preHash: String, --previous block hash,

merkleHash: String, --Merkel hash,

time: long, --creation time of the block,

height: long, --block height,

txCount: int, --transaction count of the block,

packingAddress: String， --packing address,

scriptSig: String， --signature: Hex.encode(byte[])

extend: String, --extend information : Hex.encode(byte[])

size:int, --block size

confirmCount：long, --confirmation count

roundIndex:int, --rounds ID of consensus

consensusMemberCount：int, --the number of consensus member

roundStartTime：long, --start time for the current consensus round

packingIndexOfRound: int, --packing order of the current round

reward: long, --consensus reward

fee：long --package fees acquired

}
Account：accountJson

accountJson: {

address: String, --account address

alias: String, --alias

pubkey: String, --public key Hex.encode(byte[])

priKey: String, --private key Hex.encode(byte[])（exists only

when created offline without a password）

encryptedPriKey: String --encrypted private key Hex.encode(byte[])

（exists only when created offline with a
password）

createTime: long, --create time

extend: String --other information Hex.encode(byte[])

encrypted: boolean --encrypted or not

5.3 Definition of Data Type

5.3.1 Transaction Type: txJson.type

TX_TYPE_COIN_BASE = 1 //consensus reward

TX_TYPE_TRANSFER = 2 //transfer transaction

TX_TYPE_SET_ALIAS = 3 //set alias

TX_TYPE_REGISTER_AGENT = 4 //register consensus node

TX_TYPE_JOIN_CONSENSUS = 5 //join consensus

TX_TYPE_CANCEL_CONSENSUS = 6 //cancel consensus

TX_TYPE_YELLOW_PUNISH = 7 //yellow punishment

TX_TYPE_RED_PUNISH = 8 //red punishment

TX_TYPE_STOP_AGENT = 9 //unregister the consensus node

5.3.2 Definition of Lock Time for Unspent Transaction Output

outputJson.lockTime

lockTime = 0， //available

lockTime = -1, //not available because it is locked after participating in consensus

lockTime > 0, //There are two cases：

lockTime <= 1,000,000,000,000, UTXO is locked till latest block

height exceeds lockTime.

lockTime > 1,000,000,000,000，the UTXO is locked till

lockTime(Millisecond).

5.4 RPC Interface definition

5.4.1 Query Block Headers by Height

Function Query block header by height

URL /block/header/height/{height}

Type get

Input Name Type Instruction

<height> Long block height

Output “data”: {blockHeaderJson}

5.4.2 Query Block Header by Hash

Function Query block header by block hash

URL /block/header/hash/{hash}
 Type get

Input Name Type Instruction

<hash> String block hash

Output “data”: {blockHeaderJson}

5.4.3 Query Block by Block Height

Function Query block by block height

URL /block/height/{height}

Type get

Input Name Type Instruction

<height> Long block height

Output “data”: {

{blockJson},

“txList”: [{txJson}，{txJson}， ……]

5.4.4 Query Block by Hash

Function Query block through block height

URL /block/hash/{hash}

Type get

Input Name Type Instruction

<hash> string block hash

Output “data”: {

{blockJson},
 “txList”: [{txJson}，{txJson}， ……]

5.4.5 Query the Latest Block Header

Function Query latest block header

URL /block/newest

Type get

Input none

Output “data”: {blockHeaderJson}

5.4.6 Query the Latest Block Height

Function Query latest block height

URL /block/newest/height

Type get

Input none

Output “data”: {“value”:100, Long}

5.4.7 Query the Latest Block Hash

Function Query latest block hash

URL /block/newest/hash

Type get

Input none
 Output “data”: {“value”: blockHash, String}

5.4.8 Creating Accounts in Batches

Function Create accounts( online mode， accounts created in this way

are stored under the wallet)

URL /account

Type post

Input Name Type Instruction

[count] Int number of created accounts, 1 by

default.

[password] String The default password for the

account is blank. It is

recommended to set password

when the exchange is creating

the account.

Output “data”: {

“list”: [

address1, String //Generated address of

the account

address2, String

……

}
5.4.9 Query balance of account

Function get the balance of the local accounts

URL /account/balance/{address}

Type get

Input Name Type Instruction

<address> String account address

Output “data”: {

balance: long, --total tokens

usable: long, --the number of tokens available

locked: long --the number of tokens locked

5.4.10 Query Private Key

Function Query only the private key from local created or imported

account

URL /account/prikey/{address}

Type post

Input Name Type Instruction

<address> String account address

[password] String password

Output “data”: {

“value”: prikey， String //private key

}
5.4.11 Set password

Function set a password for the account without any password before

URL /account/password/{address}

Type post

Input Name Type Instruction

<address> String account address

<password> String password

Output “data”: {

“value”： encryptedPriKey, String //encrypted private key

5.4.12 Change password

Function change the password for account with password already

URL /account/password/{address}

Type put

Input Name Type Instruction

<address> String account address

<password> String original password

<newPassword> String new password

Output “data”: {

“value”：encryptedPriKey, String //encrypted

parameter

}
5.4.13 Transfer transaction

Function transfer

URL /accountledger/transfer/

Type post

Input Name Type Instruction

<address> String address of transfer

account

<toaddress> String address of the recipient

<amount> Long the amount of tokens

transferred

[password] String password of the

account

[remark] String transaction remark

output “data”: {

“value”: txhash，String //transaction

hash

5.4.14 Create offline accounts (offline mode)

Function create an offline account( the account will not be saved in

wallet)

URL /account/offline

Type post

Input Name Type Instruction

 <count> Int the number of accounts

created,

count: [1,100]

[password] String if password is null, the

accounts will not be

encrypted

Output “data”: {

“list”:[ {accountJson},……]

5.4.15 Set password for an offline account (offline mode)

Function encrypted private key for the offline account

URL /account/offline/password

Type post

Input Name Type Instruction

parameter <priKey> String unencrypted private key

<address> String account address

<password> String the password of the

account

Output “data”: {

“value”：encryptedPriKey, String //Encrypted

private key

}
5.4.16 Reset password of offline account (offline mode)

Function reset password of private key for offline account

URL /account/offline/password

Type put

Input Name Type Instruction

<priKey> String unencrypted private key

<address> String account address: verify the

validity of the private key

<password> String original password: decrypt

private key

<newPassword String new password: encrypt

> private key

Output “data”: {

“value”：encryptedPriKey, String //encrypted

private key

5.4.17 Create Transaction (offline mode)

Function Create transaction based on inputs&outputs.

Exchange fee= total balance of inputs - total balance of

output. Both values are required to fill in. A minimum value

would be generated according to transaction amount, any

transaction lower than this value will not be packaged. See

Document 5.3 about calculation method of transaction fees.

 URL /accountledger/transaction

Type post

Input Name Type Instruction

inputs jsonObject unspent transaction outputs

outputs jsonObject newly generated transaction

output

remark string transaction remark

e.g.

"inputs": [

"fromHash": "002023c66d10cf9047db35ff9c921a2ec22……",

"fromIndex": 4

],

"outputs": [

"address": "2CjPVMKST7h4Q5Dqa8Q9P9CwYSmN7mG",

"lockTime": 0,

"value": 1000000

},

"address": "2CXJEuoXZMajeTEgL6TgiSxTRRMwiMM",

"lockTime": 0,
 "value": 999999998000000

],

remark: “create tx demo”

}
 “data”:{

“value”: txHex，String //hexadecimal transaction

output
serialized string

5.4.18 Sign a Transaction (offline mode)

Function Encrypt private key for offline account

URL /accountledger/transaction/sign

Type post

Input Name Type Instruction

<priKey> String private key

<txHex> String hexadecimal transaction

serialized string

<address> String account address: verify

the validity of private key

[password] String encrypt password

Output “data”:{

“value”: txHex，String // hexadecimal transaction

serialized string after signing

5.4.19 Broadcast transaction (offline mode)

Function Private key re-encrypting of offline account

URL /accountledger/transaction/broadcast
 Type post

Input Name Type Instruction

<txHex> String Hexadecimal transaction

serialized string

Output “data”:{

“value”: txhash， String //transaction hash

6. Guide for Exchange

6.1 Create and Backup accounts

Online mode (Full-node wallet):

A memory file will be generated upon wallet mode running to store

new created account and UTXO.

Follow section 5.4.8 to create accounts. Address and regarding UTXO

will be stored in wallet after block analyze.

Advantages: Speedy address creation and auto store

Disadvantages:

1. You need to follow section 5.4.10 to backup private key for

every newly created account. Not easy-backup intelligent, require call

RPC to export account interface for backup

 2. Less safety guarantee when private key is stored within full-

node wallet.

Offline mode (Cold wallet, Recommended) :

NULS provides two methods to run cold wallet mode:

1. RPC interface

2. SDK (see NULS Documents for SDK.)

Follow section 5.4.14 interface to create multiple offline accounts in

batches while stored in local database. Accounts created in this way will

not be stored in wallet, Advantage:

1. It is easy to back up. Easy-back up intelligent.

2. Higher safety guarantee while Private key stored within intranet

server

Disadvantages:

1. Programming code required to analyze interface for select data.

6.2 Deposit and Withdraw

6.2.1 Deposit

Monitoring every block by programming code required within Exchange

to query block exchange inputs and outputs. Address related to

exchange should be kept accounts as user deposit record.

Irrespective of consensus node, transfer (txType=2) transactions is only

exchange relevant to the customers

6.2.2 Withdraw

Transfer transaction

Online mode (Full-node wallet):

Follow section 5.4.13 interface to create and broadcast the transfer

transaction, and record the transaction hash returned by the interface.

Offline mode (Cold wallet, Recommended):

1）Find sufficient unspent UTXO from the database, and call

interface in 5.4.17 to assemble transaction;

2）Call interface in 5.4.18 to sign the transaction;

3）Call interface in 5.4.19 to broadcast transaction;

4）Record the transaction hash returned by the interface.

Transaction Confirmation

Withdraw success will happen when one of the transaction hash

value in block equals to the input of withdraw record

1. The NULS blockchain generates a new block every 10 seconds. The

exchange is recommended to only store the data when it receives a

new block. After 12-36 heights are confirmed, the exchange will

process the transaction accordingly.

2. At present, NULS does not support multi-account transfers. It is

recommended that exchanges group tokens into one or more

accounts.

6.3 Calculation Formula for Transaction Fee

Transaction fee: unit price of transaction fee * the size of transaction

Unit price of transaction fee: 100000NA/1KB

The Calculation of the size of transaction:

fee = 124 + 50 * inputs.length + 38 * outputs.length + remark.length /1024

124 is the length of basic information,

50 is the length of a single input,

38 is the length of a single piece of output information.

Remark is an optional field, the length of byte is calculated according to the

UTF-8 character encoding.
 The size of the transaction is calculated in KB. The maximum value

of transaction is 300 KB, and the portion less than 1 KB is recorded as 1

KB.

If the fee is less than the reasonable range, the transaction will be

regarded as an illegal transaction and will not be packaged. The

difference between transaction input and output will be taken as

transaction fee with node verify while calculating the minimum amount

based on the transaction. Legal transaction packing will not happen if

the transaction fee less than the minimum amount.

7. Others

Currently, only Java version available to run SDK package in NULS

blockchain and the version 1.0 only provides basic interfaces for

address and transaction creation as well as other issues that are closely

related to the exchange. Other versions of the SDK package will be

released soon and more interfaces will continue to be updated.