-
Notifications
You must be signed in to change notification settings - Fork 78
Instruction for exchanges
Connect GXB wallet to exchanges is same as bitshares(BTS),both witness_node and cli_wallet are required to run.
witness_node Connect GXChain in a peer-to-peer manner, receiving updated block from the network, and broadcast locally signed transaction pack.
cli_wallet Connect witness_node through websocket and managing wallet files. Supporting transaction signature, broadcast through witness_node, and provide API via http rpc for other progarms.
- Ubuntu 14.04 LTS 64-bit, with 4.4.0-63-generic kernel or higher.
- RAM: 8GB+.
- Free hard disk space: 50GB+.
- Dependency Package: not required
- witness_node require system calibrate current time, NTP service need to be installed：
sudo apt-get install ntpChoose either link to install.
| platform | download link |
|---|---|
| github | https://github.com/gxchain/gxb-core/releases/download/v1.0.180403/gxb_1.0.180404.tar.gz |
| Alibaba Cloud | http://gxb-package.oss-cn-hangzhou.aliyuncs.com/gxb-core/gxb_1.0.180404.tar.gz |
Put the files in your deploy catalog, then execute：
tar zxvf gxb_1.0.180404.tar.gzGo to gxb catalog, start witness_node
# These parameter could be used for saving RAM： --track-account and --partial-operations=true
nohup ./programs/witness_node/witness_node --data-dir=trusted_node --rpc-endpoint=127.0.0.1:28090 \
--p2p-endpoint=0.0.0.0:6789 --log-file --track-account "\"1.2.2999\"" --track-account "\"1.2.3000\"" \
--partial-operations=true --data-transaction-lifetime=1 >>witness.out 2>&1 &--help (used to search command) witness_node start：
# assign directory for data and configuration files
--data-dir=trusted_node
# Assign monitor address and port for rpc service(port could be changed)，127.0.0.1: limit to local access rpc service, if you do not need to limit local access, 0.0.0.0 could be used.
--rpc-endpoint=127.0.0.1:28090
# For connecting p2p network, we do not recommend to change this parameter.
--p2p-endpoint=0.0.0.0:6789
# Output log file, log file will output to control panel without this parameter.
--log-file
# Historical transaction of specified account will be tracked in RAM, one can use multiple times to track multiple accounts. Please change 1.2.2999 to 1.2.account digital id(below the account name, there is a 5 digit number)
--track-account "\"1.2.2999\""
# "NUM" records will be saved for each accessed account in RAM, default: entire operation record will be saved.
--max-ops-per-account=NUM
# Combine --track-account and --max-ops-per-account two choices could further saving RAM, recommended.
--partial-operations=true
& denotes programs are running background.
# Replay all the downloaded blocks and rebuild indexes(time consuming).
--replay-blockchain
# Delete all the downloaded data, re-synchronize blockchain
--resync-blockchain
Currently, full node use more than 12GB RAM, when combine --track-account account_id(account id in the form of 1.2.x)and --partial-operations=true, only historical transaction from exchange would be saved, which could reduce RAM usage to 4 GB.
# Please change 1.2.2999 to 1.2.account digital id,"1.2." denotes the type is account. The account digital id is from the wallet registered on https://wallet.gxb.io
--track-account="\"1.2.2999\""
--partial-operations=true
It takes around 30 minutes to finish block synchronization. One could use trusted_node/logs/witness.log to check the status of block synchronization. Check the newest block on https://block.gxb.io After block synchronization, one could use command-line wallet.
Use command-line wallet, cli_wallet to connect witness_node:
./programs/cli_wallet/cli_wallet -s ws://127.0.0.1:28090 \
--enable-rpc-log -r 127.0.0.1:8091 --data-dir=trusted_nodecli_wallet start parameters：
# Connect websocket rpc address of witness_node
-s
# Output rpc log file
--enable-rpc-log
# cli_wallet provides websocket rpc address, start API service of cli_wallet
# note：do not configure as 0.0.0.0, because all the host could access your wallet.
-r 127.0.0.1:8091
# daemon mode
-d
& denote the program is running at background
Set a password for the wallet(The password is locally for unlock wallet)：
new >>> set_password my_password
# pass, then display:
locked >>>
# then unlock wallet:
locked >>> unlock my_password
# pass, then display：
unlocked >>>
info command could check current block synchronise status.
unlocked >>> info
info
{
"head_block_num": 3913758,
"head_block_id": "003bb81eec2abfdb2cf58ffdf4dd547ea190530e",
"head_block_age": "3 seconds old",
"next_maintenance_time": "0 second ago",
"chain_id": "4f7d07969c446f8342033acb3ab2ae5044cbe0fde93db02de75bd17fa8fd84b8",
"participation": "100.00000000000000000",
...
}
# head_block_age denotes the updated blocktime, 3 seconds for each block
# participation denotes the participation rate of the witnesses, participation rate must above 70.
For more cli_wallet API, checkwallet api documentation。
If you do not have an account, you need download GXB light wallet or visit online wallet and register an account(Do not forget backup private key file).
| GXB light wallet | https://www.gxb.io/#downLoad |
|---|---|
| Online wallet | https://wallet.gxb.io |
Regarding how to use wallet, refer https://steemit.com/blockchain/@gxshares/how-to-creat-a-wallet-on-gxchain-gxshare-wallet
Execute following commands at command-line wallet：
// import private key
unlocked >>> import_key account_name wif_key true
// Check all accounts controled by local wallet
unlocked >>> list_my_accounts
// Check account information
unlocked >>> get_account account_name
// Check account balance
unlocked >>> list_account_balances account_name
// Transfer(balance should > 0)
// GXS stands for GXShares, GXC stands for GXCoin(not for exchange)
unlocked >>> transfer from_account to_account 100 GXS "" true
// Check updated block height, will retuen head_block_number
unlocked >>> get_object 2.1.0
// Check block information, or check specific block
unlocked >>> get_block 881577
There are two command-line interface for transfer: transfer and transfer2, transfer2 execute successfully will return current transaction id.
After you import wallet private key, press "ctrl + c" to exit, local wallet file will be generated. Restart with -d &, as follows：
nohup ./programs/cli_wallet/cli_wallet -s ws://127.0.0.1:28090 \
--enable-rpc-log -r 127.0.0.1:8091 -d >>wallet.out 2>1 &
After start above commands, press "enter", then input "exit" at shell to exit terminal. Output from control panel is redirect to wallet.out
Besides command-line interface, cli_wallet provides JSON RPC interface. when wallet turn on http rpc API service, which is same as input command in wallet. Call through wscat or use http client(for instance, curl).
cli_wallet provides three API for check historical transactions：get_account_history, get_relative_account_history, and get_account_history_by_operations. get_account_history_by_operations will return transaction id(txID). More information for these three API, check wallet api documentation.
Take get_account_history_by_operations for example, as follows：
- Unlock wallet.
- Check account id by account name.
- Use account id to check historical transactions.
Below is the process in detail, using gxb-light as example：
// Unlock wallet，my_password is the password
curl --data '{"jsonrpc": "2.0", "method": "unlock", "params": ["my_password"], "id": 1}' http://127.0.0.1:8091/rpcSuccess, return：
{"id":1,"jsonrpc":"2.0","result":null}If account id is known, skip this step.
// get_account_id, use account name as a parameter to get account id
curl --data '{"jsonrpc": "2.0", "method": "get_account_id", "params": ["gxb-light"], "id": 1}' http://127.0.0.1:8091/rpcReturn as follows, account id is "1.2.3054", "1.2." denotes the type is account.
{"id":1,"result":"1.2.3054"}3. Call get_account_history_by_operations API, check account historical transaction, information returned include txID:
If wallet is locked, one cannot use memo to decrypt transaction. Only sender and receiver could decrypt memo.
// get_account_history_by_operations, the first parameter is account id; the second parameter is operation assay,[] could be used;the third parameter is initial number;the fourth parameter is limit, to get limit numbers of historical transaction.
curl --data '{"jsonrpc": "2.0", "method": "get_account_history_by_operations", "params": ["1.2.3054",[], 1, 10], "id": 1}' http://127.0.0.1:8091/rpc{
"id": 1,
"jsonrpc": "2.0",
"result": {
"total_without_operations": 3, // normally, this number is equal to limit parameter, which means found transactions before operation assay 数组过滤之前，实际查询到了多少笔交易； Already found newest transaction if the number is less than limit.
"details": [{ // details returned an array, each item is a transaction
"memo": "196702323", // decrypted memo, only sender and receiver could decrypt memo
"description": "Transfer 3099 GXS from gxb-light to yunbi-gxs -- Memo: 196702323 (Fee: 0.09493 GXS)", //description of the transaction
"op": { // operations in transaction
"id": "1.11.3436",
"op": [0, {// index0 denotes transfer
"fee": {
"amount": 9493,// Transaction fee is(9493/100000) GXS, all the digit should be divided by 100000
"asset_id": "1.3.1" // 1.3.1 denotes GXS
},
"from": "1.2.3054",// account that sending currency
"to": "1.2.2999",// account that receiving currency
"amount": {
"amount": 300000, // GXS amount is 300000/100000 (3GXS，all the digit should be divided by 100000)
"asset_id": "1.3.1"
},
"memo": {
"from": "GXC68o9LkFKv5ihSt6z9oTmc7wVALUmT5Kd75BTy9rMp38wSuWU5N",
"to": "GXC5yRwAseZhPBorMmxXhQvmvsDzoJJbQnau5fFboGr5V2zGZPWsk",
"nonce": "384187316390066",
"message": "1c05a47a362361c0cf2dba52d08f3517" // encrypted memo
},
"extensions": []
}],
"result": [0, {}],
"block_num": 1115034, // Height of the block
"trx_in_block": 0,// index for specific transaction in the block
"op_in_trx": 0,
"virtual_op": 3482
},
"transaction_id": "f9f8f8359c59ac1341516facdf30c98fd5d57b5b"
}, {
"memo": "",
"description": "Transfer 7100 GXS from yunbi-gxs to gxb-light (Fee: 1 GXC)",
"op": {
"id": "1.11.3331",
"op": [0, {
"fee": {
"amount": 100000,
"asset_id": "1.3.1"
},
"from": "1.2.2999",
"to": "1.2.3054",
"amount": {
"amount": 710000000,
"asset_id": "1.3.1"
},
"extensions": []
}],
"result": [0, {}],
"block_num": 1000766,
"trx_in_block": 0,
"op_in_trx": 0,
"virtual_op": 3377
},
"transaction_id": "7c64c51ee931043ca1bc6791efc942e94b8236af"
}]
}
}Attention：For exchange, asset_id must be 1.3.1(GXS)。
Call get_dynamic_global_properties API from cli_wallet, check current highest irreversible block number. All transactions is confirmed and irreversible in the block if it is lower than this number. This could be used for a reference when user withdraw GXS from exchange, make sure the block is irreversible then proceed withdraw.
curl --data '{"jsonrpc": "2.0", "method": "get_dynamic_global_properties", "params": [], "id": 1}' http://127.0.0.1:8091/rpcreturn：
{
"id": 1,
"result": {
"id": "2.1.0",
"head_block_number": 1724515, // block height
"head_block_id": "001a506300f6717c3e99b6d8d89b264d94f1793c",
"time": "2017-08-16T14:51:53",
"current_witness": "1.6.2",
"next_maintenance_time": "2017-08-16T15:00:00",
"last_budget_time": "2017-08-16T14:50:00",
"witness_budget": 0,
"accounts_registered_this_interval": 0,
"recently_missed_count": 1,
"current_aslot": 2426557,
"recent_slots_filled": "326968992855967788277935148493325729655",
"dynamic_flags": 0,
"last_irreversible_block_num": 1724507 // Highest irreversible block number is 1724507
}
}-
Error in block synchronization
Check: trusted_node/logs/witness.log, if continue errors occured, e.g."unlinkable block", "block does not link to known chain", which means error in block synchronization.
Solutions：
-
Error in block synchronization, local blockchain files may corrupted. Stop witness_node and delete trusted_node, then restart witness_node.
-
Add --resync-blockchain in startup Commands instead of delete trusted_node, system will re-synchronize blocks.
-
-
How to exit witness_node safely
- If witness_node is not running at background, press Ctrl + C, then wait the system saves data from the RAM and close automatically.
- If witness_node is running at background, execute
kill -s SIGINT $(pgrep witness_node),then wait the system saves data from the RAM and close automatically. One should not use kill -9, or index will be rebuild next, which slow down the startup nexttime.
-
After restart witness_node, one should restart cli_wallet. Reason: when cli_wallet is running at background, it will not close automatically. Method to close cli_wallet:
kill -s SIGINT $(pgrep cli_wallet) -
If system close abnormally, it may rebuild indexes when restart, which slows down startup. If witness_node abnormal, restart with --replay-blockchain (rebuild indexes manually)
-
After restart witness_node, cli_wallet should be restarted as well. If cli_wallet is running at background, cli_wallet will not close when witness_node closed.
-
cli_wallet shut down
If cli_wallet closed after running at background for a while, it may caused by terminal offline. We recommend close current terminal after cli_wallet running at background. Alternatively, add nohup before start command-line wallet:
nohup ./programs/cli_wallet/cli_wallet -s ws://127.0.0.1:28090 --enable-rpc-log -r 127.0.0.1:8091 -d >>wallet.out 2>1 &
- We recommend to use startup script (account id should be changed in script)： witness_nodes startup script and cli_wallet startup script
- Deposit Each transfer could use a memo for differentiate customers, exchanges could set memo style themselves. Memo is encrypted, only sender and receiver could decrypt memo.
- Transfer fee
The total fee is comprised of basic fee + memo fee. The basic fee is 0.05 GXS, memo fee is depend on the byte length of memo, which is 0.5GXS/
KB. Transfer fee: `0.05 + 0.5*(KBs of memo) GXS , Transfer fee is between 0.05 and 0.15 GXS, suppose memo length is less than 100 byte. - If exchange provide the memo is 1234567, user may input "my memo is 1234567!" Exchange should be prepared about this circumstance.
- Memo like GXS123456 is not recommended. There is no limitation for the length and content of memo, but we recommend the length of memo > 10, and start with digit.
- Wallet json rpc API, account name should be lower case instead of upper case.
- Customer support for user deposit problem: Ask the user to provide txID, which could make sure the uniqueness of deposit. Attention：**exchange should save txID that used by support staff, each txID could only be used for credit once. Please be wary about scammers use different account but same txID for claiming deposit.
- There are serveral asset in the system, id(asset_id)1.3.1 is for GXS. When monitoring user deposit, one must make sure the asset_id is 1.3.1.
- Customer withdraw When using transfer/transfer2 for withdraw, use array with double quote for transfer amount, as follows：
curl --data '{"jsonrpc": "2.0", "method": "transfer2", "params": ["from_account", "to_account", "100.01", "GXS", "", true], "id": 1}' http://127.0.0.1:8091/rpc
- Precision of GXS is 5(smallest unit is0.00001 GXS). There is no decimals in GXChain, all the numbers are amplified by 100000 times, as a result, numbers from get_account_history / get_account_history_by_operations, e.g. transfer amount, should be devided by 100000 to get the real result.
- Unlock wallet before proceed to transfer or check historical transactions.
- ** When using transfer/transfer2 for transfer, if the third parameter is a floating-point number, double quote must be used, or the transfer will fail. We recommend use double quotes for any transfer amount**
- witness_node startup script
- cli_wallet startup script
- Alternative cli_wallet startup script, this script provides 3 API for the main net, if local witness_node temporary unavailable, use this script for the main net.
- GXB cold wallet offline signature tutorial
- wallet api documentation