Document for Exchange Developers

Table of Contents Frequently-Used Documents Standard Procedure A Brief Introduction of NEO-CLI Creating a wallet NEO-CLI NEO-GUI Generating Deposit Addresses User deposits and deposit records Detailed Introduction User withdrawals and withdrawal confirmation

Frequently-Used Documents

• NEO Whitepaper
• NEO Node Deployment in Linux
• NEO Node Deployment in Windows Server
• NEO Node API Reference
• NEO Blockchain Network Protocol

Standard Procedure

1. Deploy a NEO node on a server
   1. Install .net core on the server
   2. Install NEO CLI on the server
2. Do the following steps using NEO-CLI commands
   1. Create a wallet
   2. Generate addresses in batch
3. Import NEO addresses to the database
   1. Import NEO addresses into the database of the exchange
   2. Assign the addresses to the users when the users deposit
4. Develop programs to fulfil the following functions:
   1. Monitor new blocks through the API of the wallet (getblock method)
   2. User information based depositing
   3. Save the trading records related to the exchange
5. Other standard operations to connect to the website of the exchange

A Brief Introduction of NEO-CLI

NEO-CLI is a command-line client (wallet) for developers. Developers have two ways to interact with it:

• Using the CLI (command-line interface) commands. For example, you can create a wallet, generate an address, etc.
• Through Remote Procedure Call (RPC). For example, you can transfer to the designated address, acquire the block information of the designated height, acquire the information of the designated trade, etc.

NEO-CLI can be downloaded at:

github.com/neo-project/neo-cli/releases

NEO-CLI has three features as listed below:

1. Every NEO node optionally provides an API to retrieve blockchain data from the nodes. This facilitates the development of blockchain applications. The interfaces are provided through (JSON-RPC)http://www.jsonrpc.org/specification while the bottom communications use HTTP/HTTPS protocols.

To start a node which provides RPC service, you can run the following commands

Open the Command Prompt, go to the directory of NEO-CLI and enter:

     dotnet neo-cli.dll /rpc

NEO-CLI API Reference

2. It is a wallet controlled through the command line. You can manage your assets using commands. The basic functions include: creating a wallet, opening a wallet, rebuilding wallet index, showing all accounts, showing all assets, creating an address, importing/exporting private keys, and transferring assets.

How to start the wallet (NEO-CLI) program:

Open the Command Prompt, go to the directory of NEO-CLI and enter:

   dotnet AntSharesDaemon.dll

To check all the available commands:

After you have started NEO-CLI program, enter:

   help

3. It includes a consensus mechanism. You can run this mechanism to reach a consensus with the other nodes.

To start consensus:

After you have started NEO-CLI program, enter:

   start consensus

• Note: To participate in establishing the consensus, you must first be elected to be a NEO blockchain consensus node through voting.

Creating a wallet

A wallet is used to store the information of the accounts (both public keys and private keys) and the contracts. It is the most important proof that the users hold. Users must keep the wallet files and the wallet passwords secure. They must not lose or disclose these data.

The exchange must have an online wallet to manage the deposit addresses of the users. Both NEO-CLI and NEO-GUI can create wallets. The wallet files created by any of these two clients can be used by the other one.

Note: Exchanges do not have to create a wallet for every address. An online wallet usually keeps all deposit addresses of a user. A cold wallet (offline wallet) is another storage option which provides better security.

NEO-CLI

Download

How to create a wallet：

Enter the following command:

   create wallet <path>

< path > is the directory and the file name of the wallet. There is no limitation on the file extension. For example, you can type: create wallet mywallet.db3. You will be asked to set a password after you press Enter.

NEO-GUI

Download

How to create a wallet：

In the menu, click Wallet, then click New Wallet Database. Choose the directory to save the wallet file, and then set a password for the wallet.

Other operations related to the wallet can also be done using both clients. The wallet should be kept open all the time to respond to the withdrawal requests of the users. For security reasons, the wallets should be run in an independent server on which the firewall is configured properly.

Generating Deposit Addresses

A wallet can store multiple addresses. The exchange needs to generate a deposit address for each user.

There are basically two methods to generate a deposit address:

1. When the user deposit (NEO/NEO GAS) for the first time, the program dynamically generates NEO addresses. The advantage is that there is no need to generate addresses at fixed time intervals, while the disadvantage is that the exchange needs to pay extra effort to develop this function.
2. The exchange creates a batch of NEO addresses in advance. When the user charges (NEO/NEO GAS) for the first time, the exchange assigns a NEO address to him or her. The advantage is quick connections and no further development, while the disadvantage is the need to generate NEO addresses manually.

We suggest exchanges to adopt the 2nd method which ensures fast connections to the exchanges.

To generate NEO-CLI addresses in batch, you can use the CLI command:

   create address [n]

The addresses will be automatically exported to the file address.txt. The exchange needs to import these addresses into the database of the exchange, and distribute them to the users.

User deposits and deposit records

Regarding user deposit, the exchange need to be informed about the following:

1. NEO blockchain has only one main chain without side chains, will not fork, and will not have isolated blocks.
2. A transaction recorded in NEO blockchain cannot be tampered with, which mean a confirmation represents a deposit success.
3. There is no notification when the amount of asset in an address changes. The wallet does not have an interface to query all transactions for an address. See below for description on how to solve this.
4. In general, the balance of the deposit address in the exchange is not equal to the balance of that the user has in the exchange. The reason is that when transferring or withdrawing, the NEO wallet will look through one or more addresses in the wallet, find the minimal loose change that meets the requirement and adds up to the total sum of the transaction and then serve that as the input, instead of withdrawing from a specified address (unless the exchange rewrites some functions of NEO wallet to meet their own needs). There are also other operations that may lead to balance inequality. An example is if the exchange transfers part of the assets to its cold wallets.
5. There are more than two assets (NEO and NEO GAS) in a NEO address. More assets issued by users (such as stock or token) can be stored. The exchange should determine the type of assets when user deposit. Neither regard other assets as NEO shares or NEO GAS nor confuse the withdrawal of NEO with NEO GAS. The asset type need to be determined specifically.
6. NEO wallet is a full node, which needs to stay online to synchronize blocks. You can view the block synchronization status through the show state in the CLI, where the left side is the local block height, while the right side is the node block height.
7. In the exchange, the transfer between users should not be recorded through the blockchain. In general, it modifies the user's balance in the database directly. Only deposits and withdrawals should be recorded on the blockchain.

Regarding the 3rd point mentioned above:

The exchange needs to write code to monitor every transaction in a block and record all the transactions related to the exchanges addresses in the database. If a deposit occur, then the balance of the user should be updated.

Detailed Introduction

Developers can use getblock method of NEO-CLI API as follows:

getblock <index> [verbose]

<index> is the block index. [verbose] is 0 by default. When [verbose] is 0, the method returns the serialized block information in Hexadecimal. You should deserialize the hex string to get the detailed information of the block. When [verbose] is 1, the method returns the detailed information of the corresponding block in Json format.

The block information of a block includes the input and output of the transactions. The exchange needs to record all its related transactions. The output of the transactions is in fact the trading records of the withdrawals of a user. When the exchange sees any of its addresses in the output of the transactions, it will update the NEO/NEO GAS balance of the corresponding user who owns this deposit address. The exchange can also do as follows: if it finds an address within the exchange as the output of the transaction, then it records the deposit in its database and modifies the user’s balance after several confirmations. (If it is not going to match the operation with other blockchains, then it is not necessary to do this.)

• Note: Method getblockcount returns the count of the blocks in the main chain. The first parameter of Method getblock is <index> which is the block index. Block index = Block height = The count of the blocks – 1. If getblockcount returns 1234, you should use getblock 1233 to get the information of the latest block.
• The deposit and withdrawal transactions (NEO/NEO GAS) are all in a type named ContractTransaction. The exchanges only need to care about the ones of ContractTransaction type when they check through the transactions in a block.
• The first transaction of every block must be MinerTransaction. To traverse the blockchain, you can neglect or jump over the first transaction.
• Neo system takes the transaction as a record unit.

User withdrawals and withdrawal confirmation

Withdrawals can be done by following: 1. Record user withdrawal transaction and modify user balance. 2. (Optional) Customer service deals with withdrawal application. 3. Send transaction to user’s withdrawal address and record transaction ID in the database. 4. Wait for blockchain confirmation. After that, mark the withdrawal record as success.

The third step in detail:

First, open the wallet using open wallet <path> command in NEO-CLI (The following operations can be processed only after the wallet opened). Then use the sendtoaddress <asset_id> <address> <value> method in the API of NEO-CLI NEO-CLI. The <asset_id> refers to the asset ID, the <address> refers to the withdrawal address, and the <value> is for the withdrawal amount. When the transaction is sent, the transaction details are returned in the Json format. The transaction ID can be extracted from the transaction and be recorded in the database.

• Note: the <value> here refers to the actual amount, instead of the amount multiplied by 10^8.
• Note: NEO transfer amount must be an integer. If the decimal is transferred to NEO, then the blockchain will not confirm it since the loose change in the wallet will be inaccurate. It will be needed to rebuild wallet index, which is to recalculate the transactions and change of the wallet.

The fourth steps in detail:

Similar to deposit monitoring, withdrawals also need to be monitored. If the transaction ID of the withdrawal is found in the blockchain, then it means that this transaction has already been confirmed and is a successful withdrawal.