Running a Gateway
This guide provides information and links to the relevant documentation for exchanges to integrate with the IoTeX blockchain.
Deploy IoTeX Full Nodes
You'll need to deploy a few full nodes, for reading from and writing to the network. The full node stores the entire blockchain state, including pending actions/actions, and broadcasts new states (blocks, actions/actions) to the network.
Please follow this guide to setup a full node running with the gateway plugin enabled.
Optionally, please follow this guide to configure a dashboard for node monitoring. Alternatively, if you used the one-line upgrader to install the full node, you can just answer "Yes" to the following installer question:
Interact with IoTeX Full Nodes
Once the full nodes are fully synced, one can communicate with them via gRPC service specified in the configuration file: see the full API reference docs and the corresponding proto files on GitHub.
Generate New Accounts
A IoTeX account can be generated via this algorithm.
If you have not installed the latest ioctl Command line client, please check out the installation instructions.
New accounts can be generated using ioctl command line client, which will provide the private key and corresponding public keys and IoTeX address. See this example for more details about how to create a IoTeX account with ioctl.
gRPC Core API does not support the creation of new accounts.
Send IOTX
To send a signed action, the /APIService/SendAction gRPC endpoint can be used, or ioctl command line client can be used also: see this example for more details on how to send a signed action using ioctl.
For safety and auditing reasons, after a new action gets added to the blockchain (whether it's a user deposit or a withdraw) the exchange must retrieve the action data and verify the following:
The status of the receipt must equal 1 (success)
The action type must be "transfer"
The amount equals to the deposit [withdraw] amount
The sender and recipient matches with intended parties
The timestamp of the action roughly equals the actual time of sending the raw action to blockchain (within 5~10 seconds range)
Here's an example of the data associated to a IoTeX action.
Retrieve actions
One can retrieve confirmed actions as well as pending (unconfirmed) actions by using /APIService/GetActions endpoint. Examples are given below:
One can also use ioctl command line tool to query an action by hash.
Retrieve actions via contracts
One can retrieve confirmed actions via contracts by using /APIService/GetEVMTransfersByBlockHeight and /APIService/GetEVMTransfersByActionHash endpoints.
Examples are given below:
**Note that you need to turn on the System Action Log feature if you run your own node as gateway (see enableSystemLog setting in your config.yaml node configuration).
Retrieve Blocks
One can retrieve blocks that contain the target transfers by using /APIService/GetBlockMetas gRPC endpoint.
Examples are given below:
One can also use ioctl command line tool to query a block by height or hash.
Retrieve transaction Log
One can retrieve transaction logs that contain the target transfers by using /APIService/GetactionLogByBlockHeight and /APIService/GetactionLogByActionHash endpoints.
Examples are given below:
If you get an "unimplemented" error code, with a message like "feature not supported" when calling an action log APIs, please resync your node from 0, or download our latest snapshot with index data. Check out the Gateway node setup and snapshot download guides for more instructions.
Rosetta API support
One can deploy a rosetta gateway along with a IoTeX mainnet node and use the rosetta API instead. For more about Rosetta support see the Rosetta Integration document.
Testing
Once you've fully integrated with the IoTeX blockchain, please make accurate tests on both testnet and mainnet. All states of the IoTeX blockchain can be queried through either the ioctl command line tool or the official IoTeX explorers for (Mainnet and Testnet).
Please reach out to IoTeX Team if you have any question.
Last updated