Exchange Docking Guide
There are two kinds of assets in ONT: native assets and contract assets. Native assets are ONT and ONG. When docking with the exchange, it mainly processes deposit and withdrawal of these two assets.
Deploy Ontology Synchronization Node
There are two ways to deploy Ontology synchronization nodes:
Get from source code
Clone ontology repository to $GOPATH/src/github.com/ontio directory
Or
Use the third-party package management tool glide to manage the dependent libraries
Compile source code with make
An executable program will be generated after a successful compilation (using make all
command will generate sig server under 'tools' directory )
ontology
: Node program/node control program provided by command line
Get from release
Server deployment
Create wallet(not mandatory for sync node)
Create the wallet file - wallet.dat that is required for nodes running through the CLI
Directory Structure
Start up node
start up command:
./ontology
By default, the node startup will close the websocket and the rest port. If you want to open above-mentioned ports, you can configure the following parameters:
Use CLI Client
Security policy
Mandatory: The exchange must use a whitelist or firewall to block external server requests, otherwise there will be a serious security risk.
The CLI does not provide remote open/close wallet function and there is no verification process when opening the wallet. Therefore, the security policy needs to be set by the exchange based on its own situation. Since the wallet must remain open in order to process the users' withdrawal, from a security point of view, the wallet must be running on a separate server, and the exchange configures the firewall with reference to the following table.
CLI instruction
Create wallet
The exchange needs to create an online wallet to manage user deposit address. A wallet is used to store account (including public and private keys), contract address and other information, which is the most important certificate for users to hold assets. It is important to keep wallet files and wallet passwords safe and prevent them from loss or disclosure. The exchange does not need to create a wallet file for each address. Usually a wallet file can store all the user's deposit addresses. You can also use a cold wallet (offline wallet) as a more secure storage.
The public and private key generation algorithms of ONT are consistent with NEO. The public key addresses of ONT and NEO corresponding to the same private key are the same.
Generate deposit address
Note: ONT and ONG address is case-sensitive
A wallet can store multiple addresses, and the exchange needs to generate a deposit address for each user.
There are two ways to generate deposit addresses:
When the user first deposits (ONT/ONG), the program dynamically creates the ONT address. Advantages: No manual creation of addresses is required. Disadvantages: It is inconvenient to back up the wallet.
To create an address dynamically, you can use the Java SDK's implementation and the program will return the created address. Please refer to Java SDK Create account randomly.
The exchange creates a batch of ONT addresses in advance and assigns the user an ONT address when the user deposits for the first time (ONT/ONG). Advantages: It is easy to back up wallet; disadvantages: Manually create ONT address when the address is insufficient.
To create a batch of addresses, executing the ./ontology account add -n [n] -w [wallet file] command in the CLI. The -d bracket is an optional parameter and the default value is 1. -w specifies the wallet file and the default file is wallet.dat. For example, to create 100 addresses at one time:
Process Asset Transactions
Transaction docking program the exchange needs to develop
Monitor new blocks using CLI/API
Complete user deposit according to the transaction information
Store transaction records of exchanges
User deposit
For user deposit, the exchange needs to understand the following:
In general, due to the different strategies of each exchange, the balance in the exchange's deposit address may not equal to the user's balance in the exchange.
Ontology address contains ONT and ONG assets. When processing the users' deposit, the exchange needs to judge the asset type so as not to mix up the ONT and ONG deposit.
The Ontology wallet is a full node. To synchronize the blocks, the wallet needs to be online. You can view the current block height through the CLI command and judge the node status.
Transfers between users within the exchange do not need to go through the blockchain, so the exchange can directly modify the users' balance in the database. Only deposit and withdrawal need to go through the blockchain.
Example:
A user deposits tokens to the address -
TA8MoGmzS4T6g3T1CMGEVFiNGkZnn7ixw9
Monitor block information by CLI
./ontology info block <block number | block hash>
Get all transaction information in the block according to Transaction Hash by CLI
./ontology info status
"State" is 1 representing transaction success, and 0 representing the failure
Parse the "Notify" array:
ContractAddress: Contract address: 0100000000000000000000000000000000000000
is for ONT
0200000000000000000000000000000000000000
is for ONG
States:array
The first element: "transfer" represents a transfer operation
The second element: From address
The third element: To address
The fourth element: The transfer amounts (The actual number of ONT is the number of ONT * 1, and the actual number of ONG is the number of ONG * 10^9)
To obtain the user's deposit record, you can filter the to address that is generated by the exchange for users.
Deposit record
Same as user deposit, the exchange needs to write code to monitor all transactions in all blocks, and record all deposit and withdrawal transactions in the database. If there is a deposit transaction, the exchange needs to modify the corresponding user's balance in the database.
Process user withdrawal request
With regard to user withdrawal, the exchange needs to complete the following operations:
Record user withdrawals and modify users' account balances.
Use the CLI command to transfer tokens to the user's withdrawal address:
The list of parameters for the command is as follows:
--wallet, -w Wallet specifies the wallet path of transfer-out account. The default value is: "./wallet.dat".
--gasprice The total ONG cost of a transaction is the gaslimit * Gasprice The gasprice parameter specifies the gas price of the transfer transaction. The gas price of the transaction cannot be less than the lowest gas price set by node's transaction pool, otherwise the transaction will be rejected. The default value is 0. When there are transactions that are queued for packing into the block in the transaction pool, the transaction pool will deal with transactions according to the gas price and transactions with high gas prices will be prioritized.
--gaslimit The gas limit is called the limit because it's the maximum amount of units of gas you are willing to spend on a transaction. However, the actual gas cost is determined by the number of steps or APIs executed by the VM, assuming the following two conditions: 1. gaslimit>= actual cost, the transaction will be executed successfully, and return the unconsumed gas; 2. Gaslimt< actual cost, the transaction will fail to execute and consume the gas that the VM has already executed;
--asset The asset parameter specifies the asset type of the transfer. Ont indicates the ONT and ong indicates the ONG. The default value is ONT.
--from The from parameter specifies the transfer-out account address.
--to The to parameter specifies the transfer-in account address.
--amount The amount parameter specifies the transfer amount. Note: Since the precision of the ONT is 1, if the input is a floating-point value, then the value of the fractional part will be discarded; the precision of the ONG is 9, so the fractional part beyond 9 bits will be discarded.
Confirm the transaction result:
Use the returned transaction hash to query directly:
Same as ”user deposit“, monitor transactions in new blocks and filter out successful transactions which are from exchange addresses to user's withdrawal addresses
Extract the transaction ID from the returned transaction details of Json format and record it in the database.
Wait for the blockchain confirmation. After confirmation, marking the withdrawal record as successful withdrawal.
Similar to monitoring the blockchain during deposit, the withdrawal process is also the same. If a certain transaction ID in the block is found to be equal to the transaction ID in the withdrawal record during monitoring, the transaction is confirmed and the withdrawal is successful.
If the transaction is not confirmed all the time, that is, the corresponding event log cannot be queried through the transaction hash, then
Check if the transaction is in the transaction pool via RPC/SDK interface(refer to Java SDK:ONT and ONG transfer), if it exists you need to wait for the consensus node to pack and then query
If not, the transaction can be considered as failure and the transfer operation needs to be executed again.
If the transaction is not packaged for a long time, it may be due to the gas price being too low.
Java SDK Tutorials
Java SDK Tutorials: Java SDK Tutorials
Account management
Do not use wallet management
Create account randomly
Create account based on private key
Use wallet management
Address generation
The address includes single-signature address and multi-signature address, and the generation method is the same as the NEO address.
ONT and ONG transfer
Example:Example
1. Initialization
2. Query
Query ONT, ONG Balance
Query whether the transaction is in the transaction pool
Query whether the transaction is successful
Query pushing content of a smart contract
You can use the block height to query a smart contract event, and the event transaction detail will be returned.
The list of chain interaction interfaces
3. ONT transfer
Construct transfer transaction and send
Multiple signatures
If the addresses of the transferee and the payer who pay the network fee are different, the payer’s signature needs to be added.
One to multiple or multiple to multiple
Construct a transaction with multiple states
Signature
A transaction includes 1024 transfers at most
Use signature server to sign
Construct transaction and sign
Construct a transaction, serialize a transaction, send a transaction to the signature server
The signature server receives the transaction, deserializes, checks the transaction, and adds the signature
Send transaction
Sign data
4. ONG transfer
ONG transfer
The interface is similar to ONT:
Withdraw ONG
Check the balance of ONG
Create account
Construct transaction
Signature
Send transaction that withdraw ONG
Distribute ONG to Users
NOTE: the following section unavailable since ontology 2.0 update on July 7th 2020
The exchange can choose whether to distribute the ONG to users. The ONG is used to pay for the Ontology blockchain bookkeeping fees, network fees, and other service fees.
What is ONG
The total number of ONG is 1 billion with a precision of 9. When the ONT transfer transaction occurs, the unlocked ONG will be authorized by the ONT contract to the transfer sender and receiver. The ONG quantity that the ONT holder can obtain is the percentage of the total amount of ONT owned by the ONT holder. If the transfer transaction has not been triggered, the ONG authorized to the ONT holder will be accumulated and will be issued at the time of the next transfer transaction. This part of the ONG needs to be manually withdrew into wallet address.
Calculate the amount of ONG that can withdraw
The number of unlocked ONGs is determined by the time interval. The unlock rule is as follows: Unlocking ONG once every second. The number of unlocked ONG is not constant and the unlocked number is determined by ontology unlocked distribution curve. Ontology unlocked distribution curve interval is [5, 4, 3, 3, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]. Approximately every 31536000 blocks, the unlocked value of ONG will be changed. After about 18 years, all ONGs will be unlocked.
Distribute ONG to users
View locked ONG Balances via the CLI:./ontology asset unboundong <address|index|label>
Withdraw unlocked ONG via CLI:./ontology asset withdrawong <address|index|label>
--wallet, -w Wallet specifies the wallet path of withdrawal account. The default value is: "./wallet.dat".
--gasprice The gasprice parameter specifies the gas price of the transfer transaction. The gas price of the transaction cannot be less than the lowest gas price set by node's transaction pool, otherwise the transaction will be rejected. The default value is 0. When there are transactions that are queued for packing into the block in the transaction pool, the transaction pool will deal with transactions according to the gas price and transactions with high gas prices will be prioritized.
--gaslimit The gaslimit parameter specifies the gas limit of the transfer transaction. The gas limit of the transaction cannot be less than the minimum gas limit set by the node's transaction pool, otherwise the transaction will be rejected. Gasprice * gaslimit is actual ONG costs. The default value is 30000.
Same as user deposit,you can use ./ontology info status c696033f1589a88c7b849dbd2ad0c13a9ca695c3220e4f846f9b1096d0972b80
to query the result of the ONG withdrawal.
Example:
Assuming that all addresses of the exchange are in one wallet, the following figure shows the process and calculation formula about how an exchange distributes ONG to a user:
Users withdraw ONG
The process of withdrawing the ONG is the same as the process of withdrawing the ONT, just specify the asset parameter as ong:
Use Java SDK to withdraw ONG, please refer to Java SDK:ONG transfer
Signature service
When your system doesn't support the SDKs and CLI, you can use the sign server to make and sign transactions:
Ontology Signature Server Tutorials
OEP4 Token
OEP4 is ontology token protocol : OEP-4 instruction
Use Java SDK:
Set OEP4 contract hash to SDK:
transfer
monitor contract events
the result is:
familiar with ONT and ONG:
"State":1 means the transaction is succeed
"ContractAddress":"75a5cdc00164266a1ba859da785e31cd914ddbd0" is the OEP4 contract hash
"States":[ "7472616e73666572", //method "e98f4998d837fcdd44a50561f7f32140c7c6c260", //from "9d1ce056ac1eb29d73104b3e3c7dfc793c879918", //to "00a0724e1809" //amount ]
For a standard OEP4 contract transfer , the event notify should contains "transfer",from address, to address and amount fields, currently all the OEP4 contracts is Neovm contract, so we need to do decode the fields like below:
method:
from address:
to address:
amount:
Note amount value is contains the "decimal",you can get it by
for the sig server solution, please refer to the sigserver guide
7. PAX tokenPax is an OEP4 Protocol stable token issued by Paxos on ontology,same with other OEP4 token , you just need to change the contractAddress to: 6bbc07bae862db0d7867e4e5b1a13c663e2b4bc8 .
Native contract address
FAQ
MainNet update note
please refer to the following note to check whether you need to upgrade your SDK version or not: Update note
ONT / ONG Decimals
please refer to this doc.
Last updated