ViteX Gateway Technical Specification
Introduction
This specification describes the API interface that 3rd party gateways need to implement for plugging into ViteX. It has been fully supported by Vite Web Wallet.
For how to integrate the gateway in wallet, please see Gateway Plug-in Tutorial
Attention
- HTTPS is required
- CORS (Cross-Origin Resource Sharing) must be supported
- Transfer amount should be expressed in minimum precision
Request
header
The following parameter(s) are appended in request header from Vite web wallet
Name | Description |
---|---|
lang | The wallet will pass the current locale, and the gateway should handle it to provide i18n support.zh-cn (Chinese simplified) and en (English) are currently supported in the wallet. |
version | The spec version number(s) currently supported by the web wallet, split by , |
Response
header
The following parameter(s) should be appended in response header from gateway
Name | Description |
---|---|
version | The spec version number(s) currently supported by the gateway, split by , |
body
{
"code": 0,//response code
"subCode": 0,//sub code filled in by gateway for debugging
"msg": null,//additional message filled in by gateway for debugging
"data":""//response data
}
Metadata API
/meta-info
Get gateway information by token id
Method:
GET
Request:
query string
Name Description Data Type Required tokenId Token id string true Response
Name Description Data Type Required type Binding type. Allowed value:
0
Independent address mode
1
Bind-by-comment modeint true depositState Deposit channel state. Allowed value: OPEN
,MAINTAIN
,CLOSED
string true withdrawState Withdrawal channel state. Allowed value: OPEN
,MAINTAIN
,CLOSED
string true
Binding Types
The web wallet needs use binding types to render different deposit/withdrawal UI(s) and build different requests, while the gateway needs use it to return different responses. At the time being the following two types have been defined:
0
Independent address mode: In this mode, the gateway will bind a separate inbound address to each user's Vite address. Examples of this type are BTC and ETH1
Bind-by-comment mode: In this mode, the gateway cannot bind separate inbound address to each user's Vite address, so that it is necessary to identify the user's VITE address with additional comment. Examples of this type are EOS and XMR
Example
Request
/meta-info?tokenId=tti_82b16ac306f0d98bf9ccf7e7
Response
{ "code": 0, "subCode": 0, "msg": null, "data": { "type": 0, "depositState": "OPEN", "withdrawState": "OPEN" } }
Deposit/withdrawal API
/deposit-info
Get deposit information by token id and user's Vite address. The gateway should bind user's Vite address to a source chain address, and the web wallet will display a deposit page based on the API response.
Method:
GET
Request:
query string
Name Description Data Type Required tokenId Gateway token id string true walletAddress User's Vite address string true Response
Name Description Data Type Required depositAddress Deposit address string true labelName Label name, required if type=1 string false label Label value, required if type=1 string false minimumDepositAmount Minimum deposit amount string true confirmationCount Confirmations on source chain int true noticeMsg Extra message filled in by gateway string false Example
Request
/deposit-info?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9
Response
According to binding type:
Deposit Process
- The gateway establishes the binding relationship between the user's VITE address and the source chain deposit address.
- The gateway listens to the source chain transactions on the deposit address and waits for necessary confirmations.
- After the gateway confirms the deposit transaction on the source chain, it initiates a transfer transaction to send the same amount of gateway tokens to user's Vite address on Vite chain.
- The gateway listens to the transfer transaction on Vite, and must resend the transaction in case it doesn't get confirmed.
/withdraw-info
Get withdrawal information by token id and user's Vite address. The web wallet will display a withdrawal page based on the API response.
Method:
GET
Request:
query string
Name Description Data Type Required tokenId Gateway token id string true walletAddress User's Vite address string true Response
Name Description Data Type Required minimumWithdrawAmount Minimum withdrawal amount string true maximumWithdrawAmount Maximum withdrawal amount string true gatewayAddress Gateway address on Vite chain. The web wallet will send an amount of gateway tokens to the address for withdrawal string true noticeMsg Extra message filled in by gateway string false Example
Request
/withdraw-info?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9
Response
{ "code": 0, "subCode": 0, "msg": null, "data": { "minimumWithdrawAmount": "1000000", "maximumWithdrawAmount": "10000000000", "gatewayAddress": "vite_42f9a5d93e1e392624b97dfa3d7cab057b79c2489d6bc13682", "noticeMsg": "" } }
/withdraw-address/verification
Verify withdrawal address. The web wallet will use this API to verify the source chain withdrawal address
Method:
GET
Request:
query string
Name Description Data Type Required tokenId Gateway token id string true withdrawAddress User's withdrawal address on the source chain string true Response
Name Description Data Type Required isValidAddress Is the user's withdrawal address valid? bool true Example
Request
/withdraw-address/verification?tokenId=tti_82b16ac306f0d98bf9ccf7e7&withdrawAddress=moEGgYAg8KT9tydfNDofbukiUNjWTXaZTm
Response
{ "code": 0, "subCode": 0, "msg": null, "data": { "isValidAddress": true } }
/withdraw-fee
Get gateway withdrawal fee
Method:
GET
Request:
query string
Name Description Data Type Required tokenId Gateway token id string true walletAddress User's Vite address string true amount Withdrawal amount string true containsFee Is the fee included in the original withdrawal amount?
If this is false, thenamount
refers to actual amount transferred. The gateway will calculate the transaction fee based on this amount.
If this is true, thenamount
refers to the sum of actual amount transferred and the transaction fee. The gateway will subsequently derive the actual amount transferred and the transaction fee. Usually this is used in a full withdrawal.bool true Response
Name Description Data Type Required fee Withdrawal fee string true Example
Request
/withdraw-fee?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9&amount=100000000000000&containsFee=true
Response
{ "code": 0, "subCode": 0, "msg": null, "data": { "fee": "1000000" } }
Withdrawal Process
- The user fills in a valid withdrawal amount and source chain withdrawal address, then hits the transfer button. At this time, the web wallet will send a corresponding amount of gateway tokens to the gateway address on Vite chain. The source chain withdrawal address is stored in the comment of the transaction.
- The gateway listens for the transactions on the withdrawal address and waits for necessary confirmations.
- After the gateway confirms the withdrawal transaction on Vite chain, it initiates a transfer transaction to send the same amount of the source chain tokens to user's withdrawal address on the source chain.
- The gateway listens for the transfer transaction on the source chain, and must resend the transaction in case it doesn't get confirmed.
Gateway Transaction Comment
According to VEP 8: AccountBlock Data Content Type Definition, a transaction comment is a concatenation of fixed and variable strings.
- Fixed part:
VEP-8 Type | Type |
---|---|
2 Byte,uint16 | 1 Byte,uint8 |
For gateway transactions, VEP-8 Type is fixed at 3011
, or 0x0bc3
in hexadecimal format
Type is the type
parameter returned by /meta-info
API
Variable part:
Deposit/withdrawal Records Query API
/deposit-records
Get historical deposit records
Method:
GET
Request:
query string
Name Description Data Type Required tokenId Gateway token id string true walletAddress User's Vite address string true pageNum Page index, starting from 1 int true pageSize Page size int true Response
Name Description Data Type Required totalCount Total deposit records int true depositRecords List of deposit records list false inTxExplorerFormat The transaction url on the source chain explorer. Replace {$tx} with the specific inTxHash
string true outTxExplorerFormat The transaction url on Vite explorer. Replace {$tx} with the specific outTxHash
string true Definition of
depositRecords
Name Description Data Type Required inTxHash The deposit transaction hash on the source chain string true outTxHash The deposit transaction hash on Vite chain string false amount Deposit amount string true fee Gateway fee string true state Transaction state. Allowed value:
OPPOSITE_PROCESSING
Awaiting confirmation on the source chain
OPPOSITE_CONFIRMED
Confirmed on the source chain
OPPOSITE_CONFIRMED_FAIL
Transaction failed on the source chain
BELOW_MINIMUM
Transaction aborted due to insufficient deposit amount
TOT_PROCESSING
Gateway tokens sent out on Vite chain
TOT_CONFIRMED
Deposit successfulstring true dateTime Deposit time in millisecond string true Example
Request
/deposit-records?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9&pageNum=1&pageSize=10
Response
{ "code": 0, "subCode": 0, "msg": null, "data": { "totalCount": 1, "depositRecords": [{ "inTxHash": "0x8e791fc2430761ce82f432c6ad1614fa1ebc57b1e1e0925bd9302a9edf8fd235", "outTxHash": "9fb415eb6f30b27498a174bd868c29c9d30b9fa5bfb050d19156523ac540744b", "amount": "300000000000000000", "fee": "0", "state": "TOT_CONFIRMED", "dateTime": "1556129201000" }], "inTxExplorerFormat": "https://ropsten.etherscan.io/tx/{$tx}", "outTxExplorerFormat": "https://explorer.vite.org/transaction/{$tx}" } }
/withdraw-records
Get historical withdrawal records
Method:
GET
Request:
query string
Name Description Data Type Required tokenId Gateway token id string true walletAddress User's Vite address string true pageNum Page index, starting from 1 int true pageSize Page size int true Response
Name Description Data Type Required totalCount Total withdrawal records int true withdrawRecords List of withdrawal records list false inTxExplorerFormat The transaction url on Vite explorer. Replace {$tx} with the specific inTxHash
string true outTxExplorerFormat The transaction url on the source chain explorer. Replace {$tx} with the specific outTxHash
string true Definition of
withdrawRecords
Name Description Data Type Required inTxHash The withdrawal transaction hash on Vite chain string true outTxHash The withdrawal transaction hash on the source chain string false amount Actual amount transferred string true fee Gateway fee string true state Transaction state. Allowed value:
TOT_PROCESSING
Awaiting confirmation on Vite chain
TOT_CONFIRMED
Confirmed on Vite chain
TOT_EXCEED_THE_LIMIT
Transaction failed due to exceeding the maximum limit
WRONG_WITHDRAW_ADDRESS
Transaction failed due to invalid withdrawal address
OPPOSITE_PROCESSING
Source chain tokens sent out
OPPOSITE_CONFIRMED
Withdrawal successfulstring true dateTime Withdrawal time in millisecond string true Example
Request
/withdraw-records?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9&pageNum=1&pageSize=10
Response
{ "code": 0, "subCode": 0, "msg": null, "data": { "totalCount": 2, "withdrawRecords": [{ "inTxHash": "b95c11ac34d4136f3be1daa3a9fab047e11ee9c87acef63ca21ba2cee388a80f", "outTxHash": "0x8096542d958a3ac4f247eba3551cea4aa09e1cdad5d7de79db4b55f28864b628", "amount": "190000000000000000", "fee": "10000000000000000", "state": "OPPOSITE_CONFIRMED", "dateTime": "1556129201000" }], "inTxExplorerFormat": "https://explorer.vite.org/transaction/{$tx}", "outTxExplorerFormat": "https://ropsten.etherscan.io/tx/{$tx}" } }
Error Code
Code | Description |
---|---|
0 | Request is successful |
1 | Invalid request parameter |
2 | Internal gateway error |
Version of the Specification
Current Version
v1.0
Historical Version(s)
Version | Description |
---|---|
v1.0 | Initial version |