7.2 通用API

7.2.1 唤起迅雷链助手协议

唤起协议

合约执行必须通过迅雷链助手，由第三方应用唤醒迅雷链助手App或者通过迅雷链助手App扫码。迅雷链助手唤起协议为vchouyi://payment?

请求参数说明

• 若第三方业务是在非迅雷链助手接入(比如浏览器，第三方app)，callback可支持网页或协议app返回，会在业务完成后回调(表现为回到浏览器或第三方app)
• 若业务在迅雷链助手中接入(比如扫二维码在迅雷链助手中打开业务页面)，callback只支持网页协议返回，会在业务完成后回调(表现为在迅雷链助手打开网页）
• 若不传callback，建议第三方自己轮询业务结果或者等待服务器的callback回传
• 第三方可以通过查询web的UserAgent知晓业务是否在迅雷链助手中 关键字段'OneWallet' 下面是完整User-Agent

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参数说明

APP回调返回

(http://www.xx.com|scheme://host)?hash=交易回执&msg=错误描述(base64)&code=错误码&cb-data=透传信息&result=(success|fail|cancel)

7.2.2 合约constant方法查询

该方法用来做合约方法查询。该方法是用来执行指定的message call，不会创建交易，因此该方法的调用是试用不会改变区块链状态数据库的，合约中的constant方法应该调用这个方法。

请求

方法：POSTURL: /callBODY: JSON

参数说明：

params 详细

object 详细

• object - 交易调用对象

示例

{
    "jsonrpc": "2.0",
    "method": "eth_call",
    "params": [
        {
            "from": "",
            "to": "",
            "data": ""
        }, 
        "latest"
    ],
    "id": 1
}

响应

7.2.3 查询预估gas消耗(estimateGas)

功能

获取合约调用预估消耗的gas数量。用户在调用合约时需要传入gas_limit值，由于gas的消耗与区块链当前运行环境的难度值等相关，需实时计算。如果调用合约执行时out-of-gas(即gas消耗完但合约还未执行完毕)，则合约执行失败，并且已消耗的gas不会返还。如果调用合约执行时的gas小于或等于提供的gas，则合约执行完毕，将退还未消耗的gas。建议开发者在调用合约时，在此计算出的预计gas消耗值基础上加上一些，以保证合约执行成功。

请求

方法：POSTURL: /estimateGasBODY: JSON

参数说明：

params 详细

object 详细

• object - 交易调用对象

示例

{
    "jsonrpc": "2.0", 
    "method": "eth_estimateGas", 
    "params":[
        {
            "from": "",
            "to": "", 
            "data": "",
            "value": ""
        }
    ], 
    "id": 1
}

响应

7.2.4 获取合约执行所需的prepayId

• 测试环境：https://sandbox-blockchain.xunlei.com/getPrepayId
• 正式环境：https://rpc-blockchain.xunlei.com/getPrepayId

请求方式： post

请求格式与示例：

//为了保持和以太坊格式一致，请求post body数据要按照以下格式：
{
    "jsonrpc": "2.0",
    "method": "getPrepayId",
    "params": {
        "service_id": 0,
        "sign": "f93d2813227b68f77bf0db84c62011ca",
        "timeout": 1800
    }
}

• Timeout字段以秒为单位
• Timeout字段如果不输入或者输入负值,则生成的prepay_id默认超时时间为2小时[可配置]
• Timeout字段如果输入了超过默认最大的时间[可配置],则生成的prepay_id有效期为配置的最大时间,目前默认为一天

响应参数：

返回示例：

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

7.2.5 根据prepayId查询订单状态

请求url测试环境：https://sandbox-blockchain.xunlei.com/getOrderStatusByPrepayId正式环境：https://rpc-blockchain.xunlei.com/getOrderStatusByPrepayId

请求格式与示例：

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

响应参数：

data格式：

返回示例：

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

• 如果Prepay_id未失效,同时查询不到订单信息,那么获取订单信息返回”订单未支付”
• 如果Prepay_id已失效,同时查询不到订单信息,那么获取订单信息返回”Prepay_id无效”
• 如果查询到订单信息则正常返回

7.2.6 合约执行结果回调

交易成功后，区块链通知模块会把prepay_id回调接入方，接入方需要接收处理，并返回应答。对后台通知交互时，如果区块链通知模块收到接入方的应答不是成功或超时，区块链通知模块认为通知失败，区块链通知模块会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但区块链通知模块不保证通知最终能成功。 （通知频率为15/15/30/180/1800/1800/1800/1800/3600，单位：秒）

注意：同样的通知可能会多次发送给接入方系统。接入方系统必须能够正确处理重复的通知。

推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。特别提醒：接入方系统对于交易结果通知的内容一定要做签名验证，防止数据泄漏导致出现“假通知”。

区块链通知模块回调协议（post）：

示例：

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

其中的sign=md5(sha512(from=xxxxxx&prepay_id=xxxxxxxxxxxxx&status=1&timestamp=1512893272&to=xxxxx&value=xxxx&key=私钥))

接入方收到回调后，需要给区块链通知模块回应（response）：return_code=0&return_msg=ok