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
$ git clone https://github.com/ontio/ontology.git
Or
$ go get github.com/ontio/ontology
Use the third-party package management tool glide to manage the dependent libraries
$ cd $GOPATH/src/github.com/ontio/ontology
$ glide install
Compile source code with make
$ 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

  1. 1.
    Create wallet(not mandatory for sync node)
    • Create the wallet file - wallet.dat that is required for nodes running through the CLI
      $ ./ontology account add -d
      Use default setting '-t ecdsa -b 256 -s SHA256withECDSA'
      signature algorithm: ecdsa
      curve: P-256
      signature scheme: SHA256withECDSA
      Password:
      Re-enter Password:
      Index: 1
      Label:
      Address: AWVNFw74G8Sx9vcxGbmh4gT54ayuwb3bcm
      Public key: 02c17cd91acf618d497f65f1fc4f52de7952c8b2337883f898dda887953cd29dd7
      Signature scheme: SHA256withECDSA
      Create account successfully.
    • Directory Structure
      $ tree
      └── ontology
      ├── ontology
      └── wallet.dat
  2. 2.
    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:
    RESTFUL OPTIONS:
    --rest Enable restful api server
    --restport value Restful server listening port (default: 20334)
    WEB SOCKET OPTIONS:
    --ws Enable websocket server
    --wsport value Ws server listening port (default: 20335)

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.
Text
MainNet default port
Rest Port
20334
Websorcket
20335
Json RPC port
20336
Node port
20338

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.
$ ./ontology account add -d
Use default setting '-t ecdsa -b 256 -s SHA256withECDSA'
signature algorithm: ecdsa
curve: P-256
signature scheme: SHA256withECDSA
Password:
Re-enter Password:
Index: 1
Label:
Address: AWVNFw74G8Sx9vcxGbmh4gT54ayuwb3bcm
Public key: 02c17cd91acf618d497f65f1fc4f52de7952c8b2337883f898dda887953cd29dd7
Signature scheme: SHA256withECDSA
Create account successfully.
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:
$ ./ontology account add -n 100 -d -w wat.dat
Use default setting '-t ecdsa -b 256 -s SHA256withECDSA'
signature algorithm: ecdsa
curve: P-256
signature scheme: SHA256withECDSA
Password:
Re-enter Password:
Index: 1
Label:
Address: ATh1dt4pKZTASu45VeRChPi3iYmk8nYKJH
Public key: 03f8e59f0059d11dcec2902c44a9e7a2466adc9b25a61b1d94d2027d13f78ac45a
Signature scheme: SHA256withECDSA
Index: 2
Label:
Address: AdYpqD8kn3NwBkkDktqfLfT8jJMCaD7BrB
Public key: 03e05424e711faa1591ee62a20648b45d8328f40c1ad5c479484501445fea62c50
Signature scheme: SHA256withECDSA
Index: 3
Label:
Address: AY5hDhn2z8ND6F4JF9rQV1a4SDUT4aUr88
Public key: 03de554a6e3eea61aa9f78fa683ce9069ca8980a9f44b85eebe1d2c2e9a611875c
Signature scheme: SHA256withECDSA
....

Process Asset Transactions

Transaction docking program the exchange needs to develop

  1. 1.
    Monitor new blocks using CLI/API
  2. 2.
    Complete user deposit according to the transaction information
  3. 3.
    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.
    $ ./ontology info curblockheight
    CurrentBlockHeight:2
  • 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:
  1. 1.
    A user deposits tokens to the address - TA8MoGmzS4T6g3T1CMGEVFiNGkZnn7ixw9
  2. 2.
    Monitor block information by CLI ./ontology info block <block number | block hash>
    $ ./ontology info block 209304
    {
    "Hash": "83a70a5380532ededb4f3d65bcd4d3a8cd52f7f87bf1863d68bada59b95133d4",
    "Header": {
    "Version": 0,
    "PrevBlockHash": "e63ede75d1a1784c150edd537b2b5439cc3893be909d5e6970b7baa8b39a5437",
    "TransactionsRoot": "24ac1b3dbecedbac41413ef4578769dd858aab42ccb60b2918c879b129edbf5d",
    "BlockRoot": "8a03e9f3e9adb8abde5b129ba5f833a3555719ffbbf3dd97a931450620a6bbf0",
    "Timestamp": 1528959514,
    "Height": 3016,
    "ConsensusData": 8772979148630824583,
    "ConsensusPayload": "",
    "NextBookkeeper": "AQGN8sEz2dycryR5BxLCQCPYiqKPN5BMnx",
    "Bookkeepers": [
    "0217c25948722c14c1a6fa8e06b78691e722f4598585805671b0beaa7fd6c7662b"
    ],
    "SigData": [
    "a6faf7a3fe356e36977c249f858b8f0a11b719ae310470948e374b69cfb4c3f3d295ac3e81244ebbfc13a4ea94c3deee132ee9ef0caa745b4b6eaf21aeb92c40"
    ],
    "Hash": "83a70a5380532ededb4f3d65bcd4d3a8cd52f7f87bf1863d68bada59b95133d4"
    },
    "Transactions": [
    {
    "Version": 0,
    "Nonce": 4023588455,
    "GasPrice": 0,
    "GasLimit": 30000,
    "Payer": "f72c773b346d3cdf9672fcf9d1a9e0daababa270",
    "TxType": 209,
    "Payload": {
    "Code": "00c66b14e98f4998d837fcdd44a50561f7f32140c7c6c2606a7cc814dd803188dcc41329b6e9faa775a6085269b5db376a7cc808e8030000000000006a7cc86c51c1087472616e736665721400000000000000000000000000000000000000010068164f6e746f6c6f67792e4e61746976652e496e766f6b65",
    "GasLimit": 0
    },
    "Attributes": [],
    "Sigs": [
    {
    "PubKeys": [
    "0217c25948722c14c1a6fa8e06b78691e722f4598585805671b0beaa7fd6c7662b"
    ],
    "M": 1,
    "SigData": [
    "0160ade36dc83fc79e8aee00ca2d7553bbef876a14b511bb68555247903732853134ecae9b9ce053c61b0fb65167e9745fdf7e85bd85861fde901430c3fd4de516"
    ]
    },
    {
    "PubKeys": [
    "0250291da2e26b9f155e19d9a0aae1980124caa55760fcade32217fd93e8a0e750"
    ],
    "M": 1,
    "SigData": [
    "0106956ada8fb0fe2effe88215b39e607f7faa37f07428b5151a359868b03f701ff04b689bd9a96f5fb3272ee362d6176176f0a04959b953c0c85f220f1198d25f"
    ]
    }
    ],
    "Hash": "bce10eb97c6cd122131e448ddf415bcd15aabbddd466e6850074c6c839a26596"
    },
    {
    "Version": 0,
    "Nonce": 238868671,
    "GasPrice": 0,
    "GasLimit": 30000,
    "Payer": "f72c773b346d3cdf9672fcf9d1a9e0daababa270",
    "TxType": 209,
    "Payload": {
    "Code": "00c66b14e98f4998d837fcdd44a50561f7f32140c7c6c2606a7cc814dd803188dcc41329b6e9faa775a6085269b5db376a7cc808b0040000000000006a7cc86c51c1087472616e736665721400000000000000000000000000000000000000020068164f6e746f6c6f67792e4e61746976652e496e766f6b65",
    "GasLimit": 0
    },
    "Attributes": [],
    "Sigs": [
    {
    "PubKeys": [
    "0217c25948722c14c1a6fa8e06b78691e722f4598585805671b0beaa7fd6c7662b"
    ],
    "M": 1,
    "SigData": [
    "0167697964e63236565e81ca35670b7b160fe4c5365bd437d54d467a63c83084f1988dc6c429d683a71ee590520a5c3ee1735657a485a9f549a4bbef76258db67b"
    ]
    },
    {
    "PubKeys": [
    "0250291da2e26b9f155e19d9a0aae1980124caa55760fcade32217fd93e8a0e750"
    ],
    "M": 1,
    "SigData": [
    "01980eb20147a016b7ddf614107f4d178be3d7d66d56a5ecc56e80daa89bfed11b081f4a907c89338bbe1182d692307b2727d1227809f75c18662c5f3f9f0c43b4"
    ]
    }
    ],
    "Hash": "10ccaf9188e249a7ff61aa68e429f9e5a916ca01bbeb55ccaec38588b1227518"
    }
    ]
    }
  3. 3.
    Get all transaction information in the block according to Transaction Hash by CLI ./ontology info status
$ ./ontology info status bce10eb97c6cd122131e448ddf415bcd15aabbddd466e6850074c6c839a26596
Transaction states:
{
"TxHash": "bce10eb97c6cd122131e448ddf415bcd15aabbddd466e6850074c6c839a26596",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "0100000000000000000000000000000000000000",
"States": [
"transfer",
"Ad4pjz2bqep4RhQrUAzMuZJkBC3qJ1tZuT",
"Aby4Yw4tNEUN28cWY3cYK5Hk3t7opENq8q",
1000
]
}
]
}
"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:
  1. 1.
    Record user withdrawals and modify users' account balances.
  2. 2.
    Use the CLI command to transfer tokens to the user's withdrawal address:
$ ./ontology asset transfer --from Ad4pjz2bqep4RhQrUAzMuZJkBC3qJ1tZuT --to AS3SCXw8GKTEeXpdwVw7EcC4rqSebFYpfb --amount 10
Password:
Transfer ONT
From:Ad4pjz2bqep4RhQrUAzMuZJkBC3qJ1tZuT
To:AS3SCXw8GKTEeXpdwVw7EcC4rqSebFYpfb
Amount:10
TxHash:49a705f6beb6a15b92493db496f56e8bcddc95b803dac1e4a02b4579ce760b3f
Tip:
Using './ontology info status 49a705f6beb6a15b92493db496f56e8bcddc95b803dac1e4a02b4579ce760b3f' to query transaction status
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;
The minimum gas limit allowed for trading is 30,000. Transactions below this amount will not be packaged.
Gaslimit can be calculate by transaction pre-execution. (Of course by different execution context, such as time, this is not a definite value).
In order to make the use of ONT/ONG simpler, all methods of ONT/ONG are set to the lowest gas limit, ie, 30000 gas.
--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:
$ ./ontology info status 49a705f6beb6a15b92493db496f56e8bcddc95b803dac1e4a02b4579ce760b3f
Transaction states:
{
"TxHash": "49a705f6beb6a15b92493db496f56e8bcddc95b803dac1e4a02b4579ce760b3f",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "0100000000000000000000000000000000000000",
"States": [
"transfer",
"Ad4pjz2bqep4RhQrUAzMuZJkBC3qJ1tZuT",
"AS3SCXw8GKTEeXpdwVw7EcC4rqSebFYpfb",
10
]
}
]
}
  • Same as ”user deposit“, monitor transactions in new blocks and filter out successful transactions which are from exchange addresses to user's withdrawal addresses
  1. 1.
    Extract the transaction ID from the returned transaction details of Json format and record it in the database.
  2. 2.
    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.
  3. 3.
    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
com.github.ontio.account.Account acct = new com.github.ontio.account.Account(ontSdk.defaultSignScheme);
acct.serializePrivateKey();//Private key
acct.serializePublicKey();//Public key
acct.getAddressU160().toBase58();//base58 address
Create account based on private key
com.github.ontio.account.Account acct0 = new com.github.ontio.account.Account(Helper.hexToBytes(privatekey0), ontSdk.defaultSignScheme);
com.github.ontio.account.Account acct1 = new com.github.ontio.account.Account(Helper.hexToBytes(privatekey1), ontSdk.defaultSignScheme);
com.github.ontio.account.Account acct2 = new com.github.ontio.account.Account(Helper.hexToBytes(privatekey2), ontSdk.defaultSignScheme);

Use wallet management

Example
#### Create a batch of account in the wallet
ontSdk.getWalletMgr().createAccounts(10, "passwordtest");
ontSdk.getWalletMgr().writeWallet();
Create account randomly
AccountInfo info0 = ontSdk.getWalletMgr().createAccountInfo("passwordtest");
Create account based on private key
AccountInfo info = ontSdk.getWalletMgr().createAccountInfoFromPriKey("passwordtest","e467a2a9c9f56b012c71cf2270df42843a9d7ff181934068b4a62bcdd570e8be");
Get account
com.github.ontio.account.Account acct0 = ontSdk.getWalletMgr().getAccount(info.addressBase58,"passwordtest");

Address generation

The address includes single-signature address and multi-signature address, and the generation method is the same as the NEO address.
single-signature address generation
String privatekey0 = "c19f16785b8f3543bbaf5e1dbb5d398dfa6c85aaad54fc9d71203ce83e505c07";
String privatekey1 = "49855b16636e70f100cc5f4f42bc20a6535d7414fb8845e7310f8dd065a97221";
String privatekey2 = "1094e90dd7c4fdfd849c14798d725ac351ae0d924b29a279a9ffa77d5737bd96";
//Generate account and get address
com.github.ontio.account.Account acct0 = new com.github.ontio.account.Account(Helper.hexToBytes(privatekey0), ontSdk.defaultSignScheme);
Address sender = acct0.getAddressU160();
//base58 address decode
sender = Address.decodeBase58("AVcv8YBABi9m6vH7faq3t8jWNamDXYytU2");
//multi-signature address generation
Address recvAddr = Address.addressFromMultiPubKeys(2, acct1.serializePublicKey(), acct2.serializePublicKey());
Method Name
Parameter
Parameter Description
addressFromMultiPubkeys
int m,byte[]... pubkeys
The minimum number of signatures (<=the number of public keys),public key

ONT and ONG transfer

Example:Example

1. Initialization

String ip = "http://polaris1.ont.io";
String rpcUrl = ip + ":" + "20336";
OntSdk ontSdk = OntSdk.getInstance();
ontSdk.setRpc(rpcUrl);
ontSdk.setDefaultConnect(ontSdk.getRpc());

2. Query

Query ONT, ONG Balance
ontSdk.getConnect().getBalance("AVcv8YBABi9m6vH7faq3t8jWNamDXYytU2");
View ONT information:
System.out.println(ontSdk.nativevm().ont().queryName());
System.out.println(ontSdk.nativevm().ont().querySymbol());
System.out.println(ontSdk.nativevm().ont().queryDecimals());
System.out.println(ontSdk.nativevm().ont().queryTotalSupply());
View ONG information:
System.out.println(ontSdk.nativevm().ong().queryName());
System.out.println(ontSdk.nativevm().ong().querySymbol());
System.out.println(ontSdk.nativevm().ong().queryDecimals());
System.out.println(ontSdk.nativevm().ong().queryTotalSupply());
Query whether the transaction is in the transaction pool
ontSdk.getConnect().getMemPoolTxState("d441a967315989116bf0afad498e4016f542c1e7f8605da943f07633996c24cc")
response:transaction is in the tx pool
{
"Action": "getmempooltxstate",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"State":[
{
"Type":1,
"Height":744,
"ErrCode":0
},
{
"Type":0,
"Height":0,
"ErrCode":0
}
]
},
"Version": "1.0.0"
}
Or transaction is Not in the tx pool:
{
"Action": "getmempooltxstate",
"Desc": "UNKNOWN TRANSACTION",
"Error": 44001,
"Result": "",
"Version": "1.0.0"
}
Query whether the transaction is successful
Query pushing content of a smart contract
ontSdk.getConnect().getSmartCodeEvent("d441a967315989116bf0afad498e4016f542c1e7f8605da943f07633996c24cc")
response:
{
"Action": "getsmartcodeeventbyhash",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"TxHash": "20046da68ef6a91f6959caa798a5ac7660cc80cf4098921bc63604d93208a8ac",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "0100000000000000000000000000000000000000",
"States": [
"transfer",
"Ad4pjz2bqep4RhQrUAzMuZJkBC3qJ1tZuT",
"AS3SCXw8GKTEeXpdwVw7EcC4rqSebFYpfb",
1000000000
]
}
]
},
"Version": "1.0.0"
}
You can use the block height to query a smart contract event, and the event transaction detail will be returned.
ontSdk.getConnect().getSmartCodeEvent(10)
response:
{
"Action": "getsmartcodeeventbyhash",
"Desc": "SUCCESS",
"Error": 0,
"Result": [
{
"TxHash": "7e8c19fdd4f9ba67f95659833e336eac37116f74ea8bf7be4541ada05b13503e",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "0200000000000000000000000000000000000000",
"States": [
"transfer",
"AFmseVrdL9f9oyCzZefL9tG6UbvhPbdYzM",
"AFmseVrdL9f9oyCzZefL9tG6UbvhUMqNMV",
1000000000000000000
]
}
]
},
{
"TxHash": "fc82cd363271729367098fbabcfd0c02cf6ded1e535700d04658b596d53cf07d",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "0200000000000000000000000000000000000000",
"States": [
"transfer",
"AFmseVrdL9f9oyCzZefL9tG6UbvhPbdYzM",
"AFmseVrdL9f9oyCzZefL9tG6UbvhUMqNMV",
1000000000000000000
]
}
]
}
],
"Version": "1.0.0"
}
The list of chain interaction interfaces
No
Main Function
Description
1
ontSdk.getConnect().getGenerateBlockTime()
Query VBFT block-out time
2
ontSdk.getConnect().getNodeCount()
Query the number of nodes
3
ontSdk.getConnect().getBlock(15)
Query block info
4
ontSdk.getConnect().getBlockJson(15)
Query block info
5
ontSdk.getConnect().getBlockJson("txhash")
Query block info
6
ontSdk.getConnect().getBlock("txhash")
Query block info
7
ontSdk.getConnect().getBlockHeight()
Query current block height
8
ontSdk.getConnect().getTransaction("txhash")
Query transaction
9
ontSdk.getConnect().getStorage("contractaddress", key)
Query smart contract storage
10
ontSdk.getConnect().getBalance("address")
Query balance
11
ontSdk.getConnect().getContractJson("contractaddress")
Query smart contract
12
ontSdk.getConnect().getSmartCodeEvent(59)
Query the event in the smart contract
13
ontSdk.getConnect().getSmartCodeEvent("txhash")
Query the event in the smart contract
14
ontSdk.getConnect().getBlockHeightByTxHash("txhash")
Query the block height by transaction hash
15
ontSdk.getConnect().getMerkleProof("txhash")
Get merkle proof
16
ontSdk.getConnect().sendRawTransaction("txhexString")
Send transaction
17
ontSdk.getConnect().sendRawTransaction(Transaction)
Send transaction
18
ontSdk.getConnect().sendRawTransactionPreExec()
Send a pre-execution transaction
19
ontSdk.getConnect().getAllowance("ont","from","to")
Query Allowed Values
20
ontSdk.getConnect().getMemPoolTxCount()
Query total transaction volume in the transaction pool

3. ONT transfer

Construct transfer transaction and send
// Transferee and payee address
Address sender = acct0.getAddressU160();
Address recvAddr = acct1;
// Multiple address generation
//Address recvAddr = Address.addressFromMultiPubKeys(2, acct1.serializePublicKey(), acct2.serializePublicKey());
// Construct a transfer transaction
long amount = 1000;
Transaction tx = ontSdk.nativevm().ont().makeTransfer(sender.toBase58(),recvAddr.toBase58(), amount,sender.toBase58(),30000,0);
// Sign a transaction
ontSdk.signTx(tx, new com.github.ontio.account.Account[][]{{acct0}});
//Signature scheme of multiple address
ontSdk.signTx(tx, new com.github.ontio.account.Account[][]{{acct1, acct2}});
//If the addresses of the transferee and the payer who pay the network fee are different, the payer’s signature needs to be added.
// Send a transaction
ontSdk.getConnect().sendRawTransaction(tx.toHexString());
Method Name
Parameter
Parameter Description
makeTransfer
String sender,String recvAddr,long amount,String payer,long gaslimit,long gasprice
sender address, receiver address, amount, network fee payer address, gaslimit, gasprice
makeTransfer
State[] states, String payer, long gaslimit, long gasprice
A transaction contains multiple transfers
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.
// 1.Add single signature
ontSdk.addSign(tx,acct0);
// 2.Add multiple signatures
ontSdk.addMultiSign(tx,2,new com.github.ontio.account.Account[]{acct0,acct1});
One to multiple or multiple to multiple
  1. 1.
    Construct a transaction with multiple states
  2. 2.
    Signature
  3. 3.
    A transaction includes 1024 transfers at most
Address sender1 = acct0.getAddressU160();
Address sender2 = Address.addressFromMultiPubKeys(2, acct1.serializePublicKey(), acct2.serializePublicKey());
int amount = 10;
int amount2 = 20;
State state = new State(sender1, recvAddr, amount);
State state2 = new State(sender2, recvAddr, amount2);
Transaction tx = ontSdk.nativevm().ont().makeTransfer(new State[]{state1,state2},sender1.toBase58(),30000,0);
//The first transferee is a single-signature address, and the second transferee is a multiple-signature address
ontSdk.signTx(tx, new com.github.ontio.account.Account[][]{{acct0}});
ontSdk.addMultiSign(tx,2,new com.github.ontio.account.Account[]{acct1, acct2});
Use signature server to sign
  • Construct transaction and sign
  1. 1.
    Construct a transaction, serialize a transaction, send a transaction to the signature server
  2. 2.
    The signature server receives the transaction, deserializes, checks the transaction, and adds the signature
  3. 3.
    Send transaction
//Send serialized transaction to signature server
Transaction tx = ontSdk.nativevm().ont().makeTransfer(sender.toBase58(),recvAddr.toBase58(), amount,sender.toBase58(),30000,0);
String txHex = tx.toHexString();
//The receiver deserializes the transaction and signs it
Transaction txRx = Transaction.deserializeFrom(Helper.hexToBytes(txHex));
//View transfer content in the transaction
System.out.println(Transfers.deserializeFrom(Contract.deserializeFrom(txRx.code).args).json());
//Sign
ontSdk.addSign(txRx,acct0);
  • Sign data
Example
com.github.ontio.account.Account acct = new com.github.ontio.account.Account(ontSdk.defaultSignScheme);
byte[] data = "12345".getBytes();
byte[] signature = ontSdk.signatureData(acct, data);
System.out.println(ontSdk.verifySignature(acct.serializePublicKey(), data, signature));

4. ONG transfer

ONG transfer
The interface is similar to ONT:
ontSdk.nativevm().ong().makeTransfer...
Withdraw ONG
  1. 1.
    Check the balance of ONG
  2. 2.
    Create account
  3. 3.
    Construct transaction
  4. 4.
    Signature
  5. 5.
    Send transaction that withdraw ONG
//Query non-withdrawal ONG
String addr = acct0.getAddressU160().toBase58();
String ong = sdk.nativevm().ong().unboundOng(addr);
//Claim ong,withdraw ONG
com.github.ontio.account.Account account = new com.github.ontio.account.Account(Helper.hexToBytes(privatekey0), ontSdk.signatureScheme);
String hash = sdk.nativevm().ong().withdrawOng(account,toAddr,64000L,payerAcct,30000,500);
Method Name
Parameter
Parameter Description
makeClaimOng
String claimer, String to, long amount, String payer, long gaslimit, long gasprice
claimer, who to send,amount, network payer address, gaslimit, gasprice

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.
ONG locked list

Distribute ONG to users

View locked ONG Balances via the CLI:./ontology asset unboundong <address|index|label>
$ ./ontology asset unboundong 1
Unclaim Ong:
Account:Ad4pjz2bqep4RhQrUAzMuZJkBC3qJ1tZuT
ONG:23698.8755104
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.
$ ./ontology asset withdrawong 1
Password:
Claim Ong:
Account:Ad4pjz2bqep4RhQrUAzMuZJkBC3qJ1tZuT
Amount:23698.8755104
TxHash:c696033f1589a88c7b849dbd2ad0c13a9ca695c3220e4f846f9b1096d0972b80
Tip:
Using './ontology info status c696033f1589a88c7b849dbd2ad0c13a9ca695c3220e4f846f9b1096d0972b80' to query transaction status
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:
$ ./ontology asset transfer --from Ad4pjz2bqep4RhQrUAzMuZJkBC3qJ1tZuT --to AS3SCXw8GKTEeXpdwVw7EcC4rqSebFYpfb --amount 10 --asset ong
Password:
Transfer ONG
From:Ad4pjz2bqep4RhQrUAzMuZJkBC3qJ1tZuT
To:AS3SCXw8GKTEeXpdwVw7EcC4rqSebFYpfb
Amount:10
TxHash:76b19689042d255f3dac2aaf1b30c86fd83c5abfc983d80b8c64fdcc86f33f5e
Tip:
Using './ontology info status 76b19689042d255f3dac2aaf1b30c86fd83c5abfc983d80b8c64fdcc86f33f5e' to query transaction status
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:

OEP4 Token

OEP4 is ontology token protocol : OEP-4 instruction
Use Java SDK:
  1. 1.
    Set OEP4 contract hash to SDK:
    OntSdk wm = OntSdk.getInstance();
    wm.setRpc(rpcUrl);
    wm.setRestful(restUrl);
    wm.setDefaultConnect(wm.getRestful());
    wm.neovm().oep4().setContractAddress("55e02438c938f6f4eb15a9cb315b26d0169b7fd7");
  2. 2.
    transfer
    String txhash = ontSdk.neovm().oep4().sendTransfer(account, //from
    acct.getAddressU160().toBase58(), //to
    1000, //amount
    account, //payer
    20000, //gaslimit
    500); //gasprice
  3. 3.
    monitor contract events
    Object result = ontSdk.getConnect().getSmartCodeEvent(height)
    the result is:
    [
    {
    "GasConsumed":0,
    "Notify":[
    {
    "States":[
    "7472616e73666572",
    "e98f4998d837fcdd44a50561f7f32140c7c6c260",
    "9d1ce056ac1eb29d73104b3e3c7dfc793c879918",
    "00a0724e1809"
    ],
    "ContractAddress":"75a5cdc00164266a1ba859da785e31cd914ddbd0"
    }
    ],
    "TxHash":"be0430a6d01404350f4f7a724fabea5e5c3c939668e03979362c5bb6fad68fea",
    "State":1
    }
    ]
    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:
    byte[] bs =Helper.hexToBytes("7472616e73666572");
    String s = new String(bs); //s is "transfer"
    from address:
    Address from = Address.parse("e98f4998d837fcdd44a50561f7f32140c7c6c260");
    System.out.println("from is " + from.toBase58());
    to address:
    Address to = Address.parse("70a2ababdae0a9d1f9fc7296df3c6d343b772cf7");
    System.out.println("to is " + to.toBase58());
    amount:
    BigInteger amount = Helper.BigIntFromNeoBytes(Helper.hexToBytes("00a0724e1809"));
    System.out.println("amount is " + amount);
    Note amount value is contains the "decimal",you can get it by
    ontSdk.neovm().oep4().queryDecimals()
    for the sig server solution, please refer to the sigserver guide

    7. PAX token

    Pax 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 .
    browser

Native contract address

Name
Address (hex)
Address (base58)
ONT Token
0100000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6UbvhUMqNMV
ONG Token
0200000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6UbvhfRZMHJ
OntIDContract
0300000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6Ubvho7BUwN
ParamContract
0400000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6UbvhrUqmc2
AuthContract
0600000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6Ubvi9BuggV
GovernanceContract
0700000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6UbviEH9ugK
HeaderSyncContract
0800000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6UbviKTaSnK
CrossChainContract
0900000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6UbviRj6Fv6
LockProxyContract
0a00000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6UbviXz2jMT
OntFSContract
0b00000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6Ubvigeqa5R
SystemContract
ff00000000000000000000000000000000000000
AFmseVrdL9f9oyCzZefL9tG6UbwC9m2yJG

FAQ

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.