1. Document Description

1.1 Targeted Readers

This document is applicable for enterprise or individual developers that access to LinkToken exchange applications on the basis of Xunlei Blockchain technology.

1.2 Release Notes

20180406 v1.0

2. Beginner's Guide

2.1 Introduction to ThunderChain

2.1.1What is ThunderChain?

ThunderChain is a high-performance Blockchain with millions of tps high-concurrent processing capability and on-second-confirmation capability created by its Onething Technologies. On this basis, ThunderChain Open Platform is built to assist developers in quickly developing and deploying smart contracts. Enterprises or individuals can easily implement their products and services to take easier steps to develop Blockchain applications.

2.1.2 What is the ThunderChain Open Platform?

ThunderChain Open Platform is an open platform for Blockchain services built by Onething Technologies on the strength of the "ThunderChain". Xunlei opens more than ten years of distributed technology precipitation and its hundreds of millions of user base, shares millions of active individuals of LinkToken ecology to lead the industry with a high starting point, which jointly build the world-leading Blockchain ecology.

2.1.3 What is LinkToken exchange?

Make it possible for the user of LinkToken Pocket to activate the LinkToken Pocket Exchange Module by scanning or by skipping in the Merchant's APP, exchanging corresponding services easily.

2.1.4 What is the smart contract open platform?

ThunderChain provides stable, fast and low-cost blockchain services, helping developers reduce costs and create decentralized applications in various industries including financing, e-commerce, game and social media. It helps developers quickly deploy the smart contracts, allows enterprises to easily implement their products and services on the blockchain and develop blockchain applications more conveniently

2.2 How to register for an account and verify

2.2.1 Developer registration and login

Before an individual or enterprise developer wants to use the LinkToken exchange and the smart contract, you must firstly regist as the user of the platform. The phone number is the unique identification of the user. After successful registration, you can bind the E-mail. Login

Procedures of registration are as follows:

2.2.2 E-mail Binding

After binding the E-mail, it is convenient to receive the message notification, which is convenient for contacting with the official. If you forget your password, you can reset your password via E-mail. Binding Now

2.2.3 Forget Password

User may fail to login if he/she forgot the password; under the circumstance, the password can be reset by phone number or email address.

Reset password by phone number verification code

Reset password by E-mail verification

2.2.4 Personal Authentication

Individual developers who want to submit a contract or use the LinkToken exchange function must first verify their personal information. Please register as a platform user before performing personal authentication. Please have your ID card and the photos of both sides of the ID card (the photos must be clear, where your profile picture must be included).

Authentication Now

2.2.5 Enterprise Authentication

Enterprise developers need to conduct enterprise authentication whose information includes the name of the enterprise, the scanned copy of the business license, the scanned copy of the legal representative's ID card or the scanned copy of the authorization. After the enterprise authentication is passed, the LinkToken exchange and smart contract functions can be used.

Authentication Now

2.3 How to create an app

LinkToken exchange and smart contract are related to the app. Before using the functions, an app must be created. Or else, the functions cannot be used. The user needs to submit the app information to the open platform for approval.
The app is in two types, namely mobile app and web app. Software package for downloading or verification should be provided for mobile app. The accessible website page and website registration information must be provided for web app.

Create Mobile App

Create Web App

2.4 How to access the LinkToken exchange

LinkToken Exchange

3. LinkToken Exchange

3.1 Function Description

The mode of the exchange system module is completed in the mobile application APP of the accessing party. Exchange Function of LinkToken Pocket APP Code Scanning: the partner's own transaction system generates an exchange QR code according to LinkToken exchange protocol, and the user then completes the exchange mode by using the “RichScan”in the LinkToken Pocket App. Currently supported phone systems are: iOS (Apple), Android (Android).

3.2 Product Flow

3.2.1 Overview

The accessing party needs to follow the LinkToken Pocket APP protocol to generate order information from its own background and generate signature according to the rules (the signature is used to protect the order from being tampered with); The LinkToken Pocket converts this into transaction information on the Blockchain. After the user completes the exchange, the information is permanently recorded on the Blockchain. In order to optimize the access process of the accessing party, our company provides a background callback process for quickly notifying the accessing party of the status of the exchange process.

3.2.2 Accessing Party APP initiates the exchange process

• When the user has installed the LinkToken Pocket App

1. The user selects the corresponding service in the accessing party application, enters the exchange link, and chooses to confirm the exchange, as shown in Figure 1;
2. The user enters the LinkToken page to adjust the LinkToken exchange, and the interface of confirming exchange appears, as shown in Figure 2;
3. The user confirms the payee and the amount, clicks on the immediate exchange and the interface of entering password appears, as shown in Figure 3;
4. After entering the correct password, the LinkToken shows the exchange result, as shown in Figure 4;
5. Click Complete to automatically jump back to the accessing party application and personalize the order results based on the outcomes.

• When the user has no a LinkToken Pocket APP

1. The user selects the corresponding service in the accessing party application, enters the exchange link, and chooses to confirm the exchange, as shown in Figure 5;
2. The pop-up window prompts that the user has not downloaded the LinkToken Pocket and cannot complete the exchange, and it guides the user to download, as shown in Figure 6;
3. Go to the LinkToken Pocket download page (https://red.xunlei.com/html/guider.html)

3.2.3 Function of Exchange by LinkToken scanning code

1. The partner generates a QR code according to the requirements of its own accessing party according to the LinkToken exchange protocol, as shown in Figure 8;
2. The user opens the LinkToken Pocket and uses the code scanning function to enter the confirmation exchange interface after scanning, as shown in Figure 9;
3. After confirming the payee and the amount, the user chooses to exchange, and enters the correct password to display the exchange result;

3.3 Sequence diagram of the exchange initiated by the accessing party APP

1. The accessing party app initiates
2. Get prepay_id（see the Interface Section of the LinkToken Pocket）
3. For details, see 3.10How to calculate signature
4. Well-calculated sign, prepay_id, callback returns to the accessing party app
5. The accessing party app evokes the LinkToken Pocket app, as discussed in the following section
6. The LinkToken Pocket app encrypts the transaction data and sends it to the Blockchain background
7. When it is successful, the Blockchain background returns the result of the transaction to the LinkToken Pocket app
8. When the transaction is successful, the LinkToken Pocket app returns the result to the accessing party app. Whether it returns or not depends on the user behavior (the user may press the home button)
9. The accessing party periodically queries the Blockchain background on its background.
10. The transaction system calls back the callback passed in Step 4, notifying the transaction result with a limited number of callbacks whose time interval is increasing

3.4 Sequence diagram of LinkToken scan code exchange

1. The business party generates a QR code
2. LinkToken Pocket scans QR code to get action parameter request order information
3. The business background returns tx-data order information
4. LinkToken app for exchange
5. Blockchain background callbacks transaction results of business background
6. Business background actively queries the transaction results

3.5 QR code Format Definition

http://red.xunlei.com/html/guider.html?action=
Parameter
action ：Provided by the business party, which needs url encoding for the LinkToken Pocket request for transaction information

3.6 Backpack Structure

The structure returned by the accessing party after the LinkToken Pocket accesses the url pointed to by the action

// Result
{
"iRet":0,
"sMsg": "ok",
"data": {
    "tx_data": ""
  }
}

The interface of tx_data is as follows:

Parameter	Type	Description
desc	string	paymenttitle
callback	string	do url encoding and link the background callback
to	string	roll out the LinkToken Pocket address (all lowercase)
value	string	quantity of LinkToken (unit wei)
prepay_id	string	prepaid order number obtained from Blockchain interface
service_id	string	business id, need to apply for service_id and signature key from Onething Technologies
sign	string	signature value, refer to How to calculate signature

Need to do base64 encoding on tx_data as a whole Example：

callback=http%3A%2F%2F47.91.153.110%3A3000&desc=极速竞拍拍点充值&prepay_id=201712111442180000000377203337907978&service_id=3&sign=3b82f2275d9f84bbda82eae9bdf32fb7&to=0x8cfa8ab1ff90aa86714ffe731021f899a5ce4f35&value=10000000000000000000
callback=http%3A%2F%2F47.91.153.110%3A3000&desc=Extremely rapid aution point recharge &prepay_id=201712111442180000000377203337907978&service_id=3&sign=3b82f2275d9f84bbda82eae9bdf32fb7&to=0x8cfa8ab1ff90aa86714ffe731021f899a5ce4f35&value=10000000000000000000

Do base64 encoding on tx_data as a whole

{
"iRet":0,
"sMsg": "ok",
"data": {
    "tx_data": 
      "Y2FsbGJhY2s9aHR0cCUzQSUyRiUyRjQ3LjkxLjE1My4xMTAlM0EzMDAwJmRlc2M95p6B6YCf56ue5ouN5ouN54K55YWF5YC8Jm9yZGVyX2lkPTMmcHJlcGF5X2lkPTIwMTcxMjExMTQ0MjE4MDAwMDAwMDM3NzIwMzMzNzkwNzk3OCZzZXJ2aWNlX2lkPTMmc2lnbj0zYjgyZjIyNzVkOWY4NGJiZGE4MmVhZTliZGYzMmZiNyZ0bz0weDhjZmE4YWIxZmY5MGFhODY3MTRmZmU3MzEwMjFmODk5YTVjZTRmMzUmdmFsdWU9MTAwMDAwMDAwMDAwMDAwMDAwMDA="
  }
}

3.7 Process of the accessing Party Android APP evoking LinkToken Pocket APP

• Software Process

1. Add otcpay.jar to libsDirectory.
2. Add PayEntryActivity toAndroidManifest.xml

<activity android:name="onething.otcpay.PayEntryActivity"
        android:configChanges="keyboardHidden|orientation|screenSize"
        android:exported="false"
        android:screenOrientation="portrait"
        android:launchMode="singleTop"
        android:theme="@android:style/Theme.Translucent.NoTitleBar"/>

3. Call OtcPayManager.getInstance().callOtcPay(Activity context, byte[] tx_data, byte[] resource) in the Activity / Fragmentthat needs to be paid
4. RewriteonActivityResult() in the corresponding Activity / Fragment to handle the callback.

@Override
protectedvoidonActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  OtcPayManager.OtcPayCallBack(requestCode, resultCode, data, newOtcResultCallback() {
    @Override
    publicvoidonOtcTransferSuccess() {

            }
    @Override
    publicvoidonOtcPaySuccess() {

            }
    @Override
    publicvoidonOtcPayFail(interrorCode) {

            }
    @Override
    publicvoidonOtcPayCancel() {

    }
  });
}

• Parameter Description

Parameter	Type	Description
tx-data	byte[]	Base64 Encoding mainly contain the paid order information，key=value form，with & connection
resource	byte[]	Base64 Encoding source app, prompt [return XXX] after successful payment

• Parameter Description

Parameter	Type	Description
desc	string	paymenttitle
callback	string	need URLEncode and link the background callback
to	string	trasfer to LinkToken Pocket address
value	string	quantity of LinkToken (unit wei)
prepay_id	string	prepaid order number
service_id	string	business id, apply the transaction center for service_id and signature key (background fetch). Reserved field
sign	string	signature value

• APP Callback Description In the Blockchain system, the transfer operation process is

Initiate transfer -> Transfer successfully (deducted amount) -> Write to block -> Sync block-> Block verification succeeded (the other party receives the amount, and the payment gets success)

Since the synchronization of the block requires an indefinite time, different callbacks are needed to record the user's operating state.

1. If the callback is returned to the App immediately after successful payment, the callback is onOtcTransferSuccess(), indicating that the user has successfully initiated the transfer operation, and the successful debit payment waits for the block verification, hereafter it will not receive the callback of onOtcPaySuccess().
2. If the block verification succeeds after waiting for a few seconds, the returning App will receive a callback onOtcPaySuccess(), indicating that the other party has successfully received the transfer. The transaction is successfully completed and at the same time it will not receive the callback of onOtcTransferSuccess().
3. The payment failure callback isonOtcPayFail(int errorCode), and the currenterrorCodeis onlythe OtcPayManager#OTC_ERROR_CODE_INVALID_ARGUMENT, which is the parameter verification error when the payment is adjusted.
4. The payment cancellation callback is onOtcPayCancel().

• jar package jar

3.8 Process of scheme interface to adjust the LinkToken Pocket APP(iOS and Android areinterchangeable)

Evoke the agreement

The smart contract execution requests third-party app to wake LinkToken Pocket APP or code scanning through LinkToken Pocket APP.
LinkToken Pocket evoking agreement is otst://payment?

Request parameter description

Parameter	type	required	description
scheme	string	Yes	LinkToken Pocket scheme otst
host	string	Yes	LinkToken Pocket host value: payment
tx-data	byte[]	Yes	Base64 coding, mainly including order details for payment, key=value format, connected by &
resource	byte[]	Yes	Base64 coding, source app (source dealer name), restricted to 10 characters
cb-data	byte[]	No	Base64 coding (optional), payment caller needs extra information returned by LinkToken Pocket
x-source	string	No	source app scheme eg. wky-app (iOS callback optional, no processing for Android), reserved field
callback	string	No	url coding. After payment is completed, LinkToken callback address or schema http://www.xx.com or scheme://host/?hash=transaction receipt&msg=error description(base64)&code=error code&cb-data=transparent transmission information&result=(success|fail|cancel)

• If third-party business is not connected by LinkToken Pocket (i.e. browser, third-party app), callback can support webpage or protocol app return, and callback will be made after business completion (the indication is return to browser or third-party app)
• If the business is connected by LinkToken Pocket (i.e. open business page through scanning QR code in LinkToken Pocket), callback only supports webpage protocol return, and callback will be made after business completion (the indication is opening webpage in LinkToken Pocket)
• If callback is not sent, it is recommended that third party polls the business result or waits for server callback
• Third party can inquire web UserAgent to know whether the business is complete User-Agent under key field 'OneWallet' in LinkToken Pocket

  iOS-User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 11_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E302 OneWallet/2.0.3 (iPhone; iOS 11.3.1; Scale/3.00; origin/2; nc/IN)

tx-data Parameter Description

Parameter	Type	Required	Description
desc	string	Yes	smart contract execution description. The prefix “smart contract execution-” must be attached
callback	string	No	url coding. Third-party app background is to receive callback address after Blockchain transaction is completed
to	string	Yes	transfer-out LinkToken Pocket address
value	string	Yes	LinkToken number (unit wei), 1 LinkToken= 10 ** 18 wie, input integer, with no unit. For example, transfer of 1 LinkToken is1 000 000 000 000 000 000
prepay_id	string	Yes	prepayment order No. Get from interface getPrepayId
service_id	string	Yes	business id. Apply for LinkToken exchange service to get service_id and signature key
data	string	No	In case of smartcontract execution, input smart contract execution function and parameter code beginning with 0x. In case of LinkToken exchange, it is blank.
gas_limit	string	No	Maximum gas for payment: In contract transaction, it is estimated execution service fee; it is blank in case of LinkToken exchange service, and the default transaction fee is 0.01; If transaction fee is above actual execution deduction amount, exceeding amount will be refunded to the payer;
tx_type	string	No	In case of contract transaction, fixed value is contract; For LinkToken exchange, fixed value is tx_third; Default value is tx_third
sign	string	Yes	transaction signature sign=md5(sha512(callback=xxx&prepay_id=xxx&service_id=xxx&to=xxx&value=xxx&key= private key)) callback url here do not need coding

APP callback returns

(http://www.xx.com|scheme://host)?hash= transaction receipt &msg= error description (base64)&code= error code &cb-data= transparent transmission information&result=(success|fail|cancel)

• Example: Request/Response Mode

Call the LinkToken Pocket from the OneThing Cloud

otst://payment/?tx-data=ZGVzYz3nlLXlvbFYWFhYJnRvPTB4MTIzNDU2Nzg5MDEyMzQ1Njc4OTAmdmFsdWU9MTIzLjQwJmdhc2xpbWl0PTUwMDAwJmRhdGE9MHgwMTAyMDMwNDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDEmc2lnbj0wNEI3QTU1QzQ3NDQwRDk4NUE0NDgzNkZENTVFQkVCNw==&resource=d2t5&x-source=wky&callback=wky://x-callback-url/&cb-data=base64 encoded callback transparent transmission parameter

Specific Analysis

1. Smart contract execution business otst://payment
2. Name of source app，resource=d2t5, which is wky after decoding
3. Callback prefix of source app, x-source=wky
4. callback=www.bai.com||schema://host/，app callback url or schema
5. When calling back，directly return &cb-data=abcdefg
6. Transaction information tx-data=ZGVzYz3nlLXlvbFYWFhYJnRvPTB4MTIzNDU2Nzg5MDEyMzQ1Njc4OTAmdmFsdWU9MTIzLjQwJmdhc2xpbWl0PTUwMDAwJmRhdGE9MHgwMTAyMDMwNDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDEmc2lnbj0wNEI3QTU1QzQ3NDQwRDk4NUE0NDgzNkZENTVFQkVCNw==

The following information is included after decoding

1. Payment address &to=0x12345678901234567890
2. Quantity of LinkToken payment &value=123.4
3. Maximum payment amount &gaslimi=50000
4. Calling code &data=0x010203040000000000000000000000000000000000000000000000000000000000000001
5. For the title &desc= Film XXXX
6. sign transaction signature &sign=04B7A55C47440D985A44836FD55EBEB7

APP callback return

(http://www.xx.com|scheme://host)?hash= transaction receipt &msg= error description (base64)&code= error code &cb-data= transparent transmission information&result=(success|fail|cancel)

3.9 Common errors

ErrParams             = Error{Code: -3001, Message: "Parameter Error"}
ErrTxEmpty            = Error{Code: -3002, Message: "Transaction is empty"}
ErrTxSign             = Error{Code: -3003, Message: "Transaction signature is not valid"}
ErrTxFail             = Error{Code: -3004, Message: "Transaction failed"}
Err3rdSignErr         = Error{Code: -3016, Message: "Signature verification failed"}
ErrInvalidServiceID   = Error{Code: -3017, Message: "service_id is illegal"}

3.10 How to calculate signature

Sign generated by the business logic server

Transfer path

Business background-> Business front end->LinkToken Pocket app->Blockchain access->Blockchain

Signature algorithm：

sign=md5(sha512(callback=xxx&prepay_id=xxx&service_id=xxx&to=xxx&value=xxx&key= private key))，replace xxx with the parameter value.

3.11 LinkToken pocket code scanning url

As an operational resource, the LinkToken Pocket supports the ability to open the corresponding url page directly in the pocket by scanning the code.
Developers can contact the ThunderChain operation (open@onethingcloud.com) to apply for the corresponding domain name (must be https), which can achieve that the scan code can be opened to open the corresponding domain name page.

4. API List

4.1 Get prepay_id

• Test environment：https://sandbox-pocketapi.lianxiangcloud.com/getPrepayId
• Formal environment：https://walletapi.onethingpcs.com/getPrepayId

Request method: post

Parameter	Type	Description
service_id	int	business number, distributed by Onething Technologies
sign	string	signature, signature algorithm：md5(sha512("service_id= business number &key= private key"))， private key distributed by Onething Technologies
timeout	int	The lifetime of the generated prepay_id, in seconds

Request format and example：

//In order to maintain the same format as the Ethereum, request post body data is in accordance with the following format:
{
    "jsonrpc": "2.0",
    "method": "getPrepayId",
    "params": {
        "service_id": 0,
        "sign": "f93d2813227b68f77bf0db84c62011ca",
        "timeout": 1800
    }
}

• Timeout field in seconds
• If the Timeout field is not entered or a negative value is entered, the default timeout for the generated prepay_id is 2 hours [configurable]
• If the timeout field is more than the default maximum time [configurable], the generated prepay_id is valid for the configured maximum time. The current default is one day.

Response Parameter：

Parameter	Type	Description
iRet	int	0 success
sMsg	string	return description
data	json object	if succeed, return prepay_id: 'xxxx'，if failed, return the error information

Return example：

{
"iRet":0,
"sMsg": "ok",
"data": {\"prepay_id\":\"201711291656030000000101431771972107\"}
}

4.2 Querying Order Status

Request url
Test environment：https://sandbox-pocketapi.lianxiangcloud.com/getOrderStatusByPrepayId
Formal environment：https://walletapi.onethingpcs.com:443/getOrderStatusByPrepayId

Parameter	Type	Description
service_id	int	business number, distributed by Onething Technologies
prepay_id	string	obtain when the order is submitted

Request format and example：

{"jsonrpc":"2.0","method":"getOrderStatusByPrepayId","params":{"service_id":1,"prepay_id":"20171019xxxxxxxxxxxx"}}

Response Parameter:

Parameter	Type	Description
iRet	int	0 success
sMsg	int	return description
data	array	return data, json encoded string

dataformat:

Parameter	Type	Description
from	string	payment address
to	string	receiving address
value	string	LinkToken amount，string，unit：wei， for example："1000000000000000000"
status	string	order status，0 initial，1 success，2 failure
ctime	string	transaction time，for example：2017-10-19 15:37:00
hash	string	transaction hash
payload	string	transaction payload

Return example:

{  
    "iRet":0,
    "sMsg":"success",
    "data":{
        "from":"0x7b6837189a3464d3c696069b2b42a9ae8e17dda1",
        "to":"0x00a2810b56e763406cad8be8ee90b0b89b370829",
        "value":"1000",
        "ctime":"2018-12-28 11:56:00",
        "status":0,
        "hash":"0xe254b5a67458e8d2b20472028738baba7bf5f10c5fd19f471b31c6725e58b10e",
        "pay_load":""
    }
}

• If the Prepay_id is not expired and the order information is not queried, the order information is returned as “order unpaid”
• If Prepay_id has expired and no order information is queried,the order information is returned as“Prepay_id is invalid”
• Return if the order information is queried

4.3 Callback Protocol

After the successful transaction, the Blockchain notification module will callback the prepay_id to the accessing party which needs to receive the processing and return a response.
When the background notification interaction is performed, if it is unsuccessful or overtime that the Blockchain notification module receives the accessing party's response, the module will consider that the notification fails. It can periodically re-initiates the notification with a certain policy, as far as possible, to improve the success rate of notification, which does not guarantee that the notification will eventually succeed. (The notification frequency is 15/15/30/180/1800/1800/1800/1800/3600, unit: second)

Note: The same notification may be sent to the accessing system for multiple times. The accessing system must be able to handle duplicate notifications correctly.

The recommended practice is to first check the status of the corresponding service data when it receives the notification for processing, and determine whether the notification has been processed. If it has not been processed, continuing to do it. If it is processed, returning the successful result directly. Before the status check and processing of business data, data locks should be used for concurrent processing capability control to avoid data confusion caused by function reentry. Special reminder: The accessing system must perform signature verification on the content of the transaction result notification to prevent data leakage from causing “false notification”.

Blockchain notification module callback protocol（post）：

Parameter	Type	Description
prepay_id	string	prepay ID
from	string	payment address
to	string	receiving address
value	string	LinkToken amount，string，unit：wei， for example："1000000000000000000"
status	string	order status，0 initial，1 success，2 failure
timestamp	string	unix timestamp
sign	string	md5(sha512(from=xxxxxx&prepay_id=xxxxxxxxxxxxx&status=1&timestamp=1512893272&to=xxxxx&value=xxxx&key= private key ))

For example：

from=xxxxxx&prepay_id=xxxxxxxxxxxxx&status=1&timestamp=1512893272&to=xxxxx&value=100000000000000&sign=4124bc0a9335c2xxxxxxxxxxxxxx

one of them where sign=md5(sha512(from=xxxxxx&prepay_id=xxxxxxxxxxxxx&status=1&timestamp=1512893272&to=xxxxx&value=xxxx&key= private key ))

After the accessing party receives the callback, it needs to respond to the Blockchain notification module（response）：
return_code=0&return_msg=ok

5. Common FAQ

5.1 How to download the phone APP of the LinkToken Pocket in formal environment

Download and install by scanning code

5.2 How to download the phone APP of the LinkToken Pocket in test environment

Download and install by scanning code

5.3 How to get the Blockchain account

After the user downloads and installs the APP, the account can be generated through the APP.