Skip to content

for_exchanges

Jump to bottom
gxchain123 edited this page Dec 21, 2017 · 5 revisions

Step-By-Step Instructions for Exchanges

The purpose of this document is to describe how to interface your exchange with GXShares step-by-step.

The interface instructions of GXShares are the same as Bitshares, two components are required to run: witness_node and cli_wallet.

INSTALLATION

  • Basic hardware and software requirements:

    • 8GB+ memory, 50GB hard disk

    • Install 64-bit Ubuntu 14.04 LTS，kernel version: 4.4.0-63-generic+

  • Current package of the GXB-Core software for ubuntu 14.04 LTS 64bit, download from here. Or build from the sources according to Building from Sources .

  • Environmental preparation. Ubuntu system recommended to install NTP server, the method is:

sudo apt-get install ntp

RUNNING DAEMONS AND WALLET

Trusted Full Node

The trusted full node is your entry point to the GXChain P2P network. It will hold the blockchain, connect to other peers, and will receive new blocks in real-time.

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 &

witness_node executable options：

# pecifies directory containing databases, configuration file, etc.
--data-dir arg

# specifies endpoint for P2P node to listen on
--p2p-endpoint arg

# specifies endpoint for websocket RPC to listen on
--rpc-endpoint arg

# output logs into log file, not console
--log-file

# account ID to track history for (may specify multiple times)
--track-account arg

# Keep only those operations in memory that are related to account history tracking
--partial-operations arg

# Maximum number of operations per account will be kept in memory
--max-ops-per-account arg

# lifetime of data_transaction object in memory,  in hour
--data-transaction-lifetime

You can use ./programs/witness_node --help to view command parameters.

The last 24 hours of console logs are kept in the trusted_node/logs/witness.log.

Wallet

The wallet (cli_wallet) requires a running full node to connect to because it does not offer P2P or blockchain capabilities directly. The wallet will be used to transfer assets to the customers. It connects to the trusted full node and has spending privileges for the hot wallet.

Run the wallet in command line:

./programs/cli_wallet/cli_wallet -s ws://127.0.0.1:28090 \
  --enable-rpc-log -r 127.0.0.1:8091 --data-dir=trusted_node

cli_wallet executable options:

# specifies directory containing log files
--data-dir arg

# specifies witness_node server websocket RPC endpoint
-s arg

# specifies endpoint for wallet websocket RPC to listen on
-r arg

# run the wallet in daemon mode
-d

Run the wallet in daemon mode(without prompt):

nohup ./programs/cli_wallet/cli_wallet -s ws://127.0.0.1:28090 \
--enable-rpc-log -r 127.0.0.1:8091 --data-dir=trusted_node -d &

We assume that you already have an account on the GXChain. If not, please visit online wallet to create an account and backup your wallet.

We now use the opencli_walletto issue transfers and query the blockchain for more information. First of all, we create a new wallet and set a pass phrase:

new >>> set_password <password>
locked >>> unlock <password>
unlocked >>>

We now need to import the active key into thecli_wallet:

unlocked >>> import_key <account_name> <wif_key>

List all accounts controlled by this wallet:

unlocked >>> list_my_accounts

Get information about the given account:

unlocked >>> get_account <account_name>

List the balances of an account:

unlocked >>> list_account_balances <account_name>

Use transfer/transfer2 to transfer asset:

unlocked >>> transfer <from_account> <to_account> 10 GXS "this is memo" true

Use the info command to view the current synchronization:

unlocked >>> info

Get block by block_num:

unlocked >>> get_block 881577

List all commands supported by the wallet API:

unlocked >>> help

Using Wallet API

In order to use the wallet api, you need to run the cli_wallet.

RPC calls are state-less and accessible via regular JSON formated RPC-HTTP-calls. The correct structure of the JSON call is：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_account_id",
  "params": ["gxb-light"]
}
Example call with curl

Such as call can be submitted viacurl:

curl --data '{"jsonrpc": "2.0", "method": "get_account_id", "params": ["gxb-light"], "id": 1}' http://127.0.0.1:8091/rpc
Successful calls

The API will return a properly JSON formated response carrying the sameidas the request to distinguish subsequent calls.

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": "1.2.3054"
}
Errors

In case of an error, the resulting answer will carry anerrorattribute and a detailed description:

{
  "id": 0,
  "error": {
    "data": {
      "code": "error-code",
      "name": " .. name of exception ..",
      "message": " .. message of exception ..",
      "stack": [ .. stack trace .. ],
    },
    "code": 1
  }
}

Transfer asset via curl:

curl --data '{"jsonrpc": "2.0", "method": "transfer2", "params": ["from_account", "to_account", "100.1", "GXS", "",  true], "id": 3}' http://127.0.0.1:8091/rpc

Wallet specific commands, such astransfer, are only available if connecting tocli_walletbecause only the wallet has the private keys and signing capabilities and some calls will only execute of the wallet is unlocked.

WATCHING DEPOSITS

In order to distinguish customers, we make use of so called memos similar to BitShares, which are encrypted. Hence, in order to monitor deposits to the exchange , you don’t need to ever deal with addresses, you only need decode the memo and leave the funds where they are.

Similar to other crypto currencies, it is recommended to wait for several confirmations of a transcation. Also you can check the GXChain network status by command info and get_dynamic_global_properties.

In order to watch user deposits , you can use get_irreversible_account_history command / API to query the relative operations on the account of exchange. The parameters of get_irreversible_account_history are:

Parameters:
    name: the name or id of the account (type: string)
    [operation_types]: operation types, for example, [0] stands for transfer operation
    start: the sequence number where to start looping back throw the
    history (type: uint32_t),  1 stands for the earliest operation
    limit: the number of entries to return (type: int, must <= 100, starting from start)


Returns
    Returns the most recent operations on the named account. txID will be included in returned transactions.

How to get account history and transaction ids

Using account "gxb-light" for example.

1) use unlock to unlock your wallet

# unlock, your_password is your wallet password
curl --data '{"jsonrpc": "2.0", "method": "unlock", "params": ["your_password"], "id": 1}' http://127.0.0.1:8091/rpc

2) get account history

$ curl --data '{"jsonrpc": "2.0", "method": "get_irreversible_account_history", "params": ["gxb-light", [0], 1, 5], "id": 2}' http://127.0.0.1:8091/rpc
$ curl --data '{"jsonrpc": "2.0", "method": "get_irreversible_account_history", "params": ["gxb-light", [0], 16, 5], "id": 2}' http://127.0.0.1:8091/rpc

response :

{
  "id": 2,
  "jsonrpc": "2.0",
  "result": {
    "next_start_sequence": 16, // start for next call
    "result_count": 5, // total operations returned
    "details": [{
      "memo": "第1笔钱",  // memo
      "description": "Transfer 500000 GXC from nathan to init0 -- Memo: 第1笔钱   (Fee: 1.89843 GXC)",
      "op": {
        "id": "1.11.4",
        "op": [0, {
          "fee": {
            "amount": 189843,  // transaction fee
            "asset_id": "1.3.0"
          },
          "from": "1.2.17",  // transfer from account
          "to": "1.2.6",    // transfer to account
          "amount": {
            "amount": "50000000000",  // transfer amount, 50000000000 / 100000 --> 500000 GXS, devided by 10000
            "asset_id": "1.3.1" // 1.3.1 stands for GXS (GXShares)
          },
          "memo": {
            "from": "GXC6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
            "to": "GXC6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
            "nonce": "18376185717943059995",
            "message": "99eaca65bd6deb3148a52b5b4587b303"
          },
          "extensions": []
        }],
        "result": [0, {}],
        "block_num": 42,
        "trx_in_block": 1,
        "op_in_trx": 0,
        "virtual_op": 49
      },
      "transaction_id": "2bcdb1e2bf48d2f31a769b5e0b70842df9dbb384"
    }, {
      "memo": "第1笔钱",
      "description": "Transfer 1000000 GXC from nathan to test456 -- Memo: 第1笔钱   (Fee: 1.89843 GXC)",
      "op": {
        "id": "1.11.3",
        "op": [0, {
          "fee": {
            "amount": 189843,
            "asset_id": "1.3.0"
          },
          "from": "1.2.17",
          "to": "1.2.18",
          "amount": {
            "amount": "100000000000",
            "asset_id": "1.3.0"
          },
          "memo": {
            "from": "GXC6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
            "to": "GXC6ikt5hsnX8bMGAmJnKmcJ8Cha952GBHnQeyCDhP57yJipvbLyQ",
            "nonce": "7279316236102149689",
            "message": "76ca6d7119b996959cd83b7ea4eb7d29"
          },
          "extensions": []
        }],
        "result": [0, {}],
        "block_num": 42,  // block num
        "trx_in_block": 0,
        "op_in_trx": 0,
        "virtual_op": 48
      },
      "transaction_id": "83ec572e88999ca8f183cd4e8e54726822f640f1" // transaction id
    }]
  }
}

attachment:

  1. witness_node start script
  2. cli_wallet start script
  3. cli_wallet api document
Clone this wiki locally