跨链网关接口协议

介绍

此文档描述网关接入 ViteX 需要实现的 API 接口,此协议规范支持无缝接入 Vite Web Wallet

有关如何接入网关的教程,请查看:网关接入教程

注意事项

  • 跨链网关服务需要 HTTPS 协议
  • 跨链网关服务需要支持 CORS 跨域
  • 所有金额都使用最小精度表示

统一请求格式

Web Wallet 需在请求 header 中添加如下参数

参数名 描述
lang Web Wallet 会根据当前语言设置传递参数,网关服务可自行处理以应对国际化需求
目前的枚举有 zh-cn 中文简体, en 英文
version Web Wallet 当前支持的跨链网关接口协议版本,兼容多个版本用 , 分隔

统一返回格式

header

跨链网关服务需在响应 header 中添加如下参数

参数名 描述
version 跨链网关服务实现的接口协议版本,兼容多个版本用 , 分隔

body

{
  "code": 0,//响应码,更多响应码见响应码表
  "subCode": 0,//子响应码 ,网关自行定义,用于问题排查
  "msg": null,//响应说明,网关自行定义,用于问题排查
  "data":""//响应数据,具体定义见接口列表
}

元信息类接口

/meta-info

获取跨链网关 TOT 的元信息。如 TOT 转入转出的通道状态、类型等。

  • Method: GET

  • Request: query string

    参数名 描述 数据类型 是否必传
    tokenId TOT id string true
  • Response

    参数名 描述 数据类型 是否必传
    type 通道类型,枚举值
    0 单地址模式
    1 通过备注区分地址模式
    int true
    depositState 转入通道状态,枚举值: OPENMAINTAINCLOSED string true
    withdrawState 转出通道状态,枚举值: OPENMAINTAINCLOSED string true

关于通道类型

Web Wallet 需根据不同的通道类型渲染不同的转入、转出的界面与请求结构,网关服务需根据不同的通道类型返回不同的响应结构。当前协议定义了两种类型,未来还会根据需要定义更多的类型,如 GRIN 的文件模式

  • 0 单地址模式:在这种类型下,网关会为每个用户 VITE 地址绑定一个独有的转入地址,比如 BTC、ETH
  • 1 通过备注区分地址模式:在这种类型下,网关无法为每个用户 VITE 地址绑定不同的转入地址,因此需要通过额外的备注标识对应的用户 VITE 地址,如 EOS、XMR
  • Example

    Request

    /meta-info?tokenId=tti_82b16ac306f0d98bf9ccf7e7
    

    Response

    {
      "code": 0,
      "subCode": 0,
      "msg": null,
      "data": {
        "type": 0,
        "depositState": "OPEN",
        "withdrawState": "OPEN"
      }
    }
    

转入转出交易类接口

/deposit-info

获取转入信息。如转入地址、转入确认次数、转入说明等。网关需要生成对手链转入地址并与用户 VITE 地址绑定,Web Wallet 根据响应展示跨链转入界面。

  • Method: GET

  • Request: query string

    参数名 描述 数据类型 是否必传
    tokenId TOT id string true
    walletAddress 用户 VITE 地址 string true
  • Response

    参数名 描述 数据类型 是否必传
    depositAddress 转入地址 string true
    labelName 标签名,type 为 1 时必传 string false
    label 标签值,type 为 1 时必传 string false
    minimumDepositAmount 最小转入金额 string true
    confirmationCount 对手链入账确认数 int true
    noticeMsg 注意事项描述,网关自行定义 string false
  • Example

    Request

    /deposit-info?tokenId=tti_82b16ac306f0d98bf9ccf7e7&walletAddress=vite_52ea0d88812350817df9fb415443f865e5cf4d3fddc9931dd9
    

    Response
    根据 /meta-info 中的参数 type 分为:

    关于跨链转入流程

    1. 网关建立 用户VITE地址对手链转入地址 的绑定关系。
    2. 网关监听对手链交易,如果交易和绑定的转入地址相匹配,等待合适的确认数。
    3. 网关确认对手链交易后,发起 VITE 上的 TOT 转出交易,交易目标地址为绑定的用户 VITE 地址。
    4. 网关监听 VITE 上的该笔 TOT 转出交易,如果交易没有最终被确认,需要重试发送。

    /withdraw-info

    获取转出信息。如最小转出金额,TOT 回收地址等。Web Wallet 根据响应展示跨链转出界面。

    • Method: GET

    • Request: query string

    参数名 描述 数据类型 是否必传
    tokenId TOT id string true
    walletAddress 用户 VITE 地址 string true
    • Response
    参数名 描述 数据类型 是否必传
    minimumWithdrawAmount 最小实际到账转出金额 string true
    maximumWithdrawAmount 最大实际到账转出金额 string true
    gatewayAddress 网关地址,web 钱包会签名一个以该地址为目标地址的 TOT 回收交易,用于回收 TOT string true
    labelName 标签名,type 为 1 时必传 string false
    noticeMsg 注意事项描述,网关自行定义 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

    校验转出地址。当用户在跨链转出界面中输入转出地址时进行校验。

    • Method: GET

    • Request: query string

    参数名 描述 数据类型 是否必传
    tokenId TOT id string true
    withdrawAddress 用户对手链转出地址 string true
    label 标签值,type 为 1 时必传 string false
    • Response
    参数名 描述 数据类型 是否必传
    isValidAddress 地址是否合法 bool true
    message 错误原因提示 string false
    • Example

      Request

      /withdraw-address/verification?tokenId=tti_82b16ac306f0d98bf9ccf7e7&withdrawAddress=moEGgYAg8KT9tydfNDofbukiUNjWTXaZTm
      

      Response

      {
        "code": 0,
        "subCode": 0,
        "msg": null,
        "data": {
          "isValidAddress": true
        }
      }
      

    /withdraw-fee

    获取网关收取的转出手续费。

    • Method: GET

    • Request: query string

    参数名 描述 数据类型 是否必传
    tokenId TOT id string true
    walletAddress 用户 VITE 地址 string true
    amount 金额 string true
    containsFee 传入的 amount 是否已包含手续费
    如果为 false,amount 为实际到账金额,网关以该金额为基数直接计算手续费
    如果为 true,amount 为实际到账金额 + 转出手续费,网关以 amount 为总额反推计算实际到账金额与手续费,用于全部转出场景
    bool true
    • Response
    参数名 描述 数据类型 是否必传
    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"
        }
      }
      

    关于跨链转出

    1. 当用户填写完合法的转出地址与金额并确认转出后,Web Wallet 会签名一笔 TOT 回收交易并发送至 VITE 网络。 用户填写的转出信息表示在交易的备注中
    2. 网关监听 VITE 链上的 TOT 回收交易,等待合适的确认数。
    3. 网关确认 VITE 链上的 TOT 回收交易后,发起对手链上的转出交易,交易目标地址为 TOT 回收交易的备注。
    4. 网关监听对手链上的该笔转出交易,如果交易没有最终被确认,需要重试发送。

    交易备注填写规范

    依据 VEP 8: AccountBlock Data Content Type 规范定义,由固定部分和可变部分拼接而成。

    • 固定部分为:
    VEP-8 Type Type
    2 Byte,uint16 1 Byte,uint8

    VEP-8 Type 固定为 3011 ,用 HEX 表示为 0x0bc3
    Type 为 /meta-info 中的参数 type

    • 可变部分为:

      转入转出记录查询类接口

      /deposit-records

      转入记录。

      • Method: GET

      • Request: query string

      参数名 描述 数据类型 是否必传
      tokenId TOT id string true
      walletAddress 用户 VITE 地址 string true
      pageNum 分页参数,起始页序号,从 1 开始 int true
      pageSize 分页参数,每页大小 int true
      • Response
      参数名 描述 数据类型 是否必传
      totalCount 总记录数 int true
      depositRecords 转入记录列表 list false
      inTxExplorerFormat 对手链浏览器,用 inTxHash 替换 {$tx} 为该交易区块浏览器地址 string true
      outTxExplorerFormat VITE 链浏览器,用 outTxHash 替换 {$tx} 为该交易区块浏览器地址 string true
      • 其中 depositRecords 参数如下
      参数名 描述 数据类型 是否必传
      inTxHash 对手链转入交易 hash string true
      inTxConfirmedCount 对手链转入交易已确认数 int false
      inTxConfirmationCount 对手链转入交易需要确认数 int false
      outTxHash VITE 链转出 TOT 交易 hash string false
      amount 转入金额 string true
      fee 网关收取的转入手续费 string true
      state 转入状态,枚举值
      OPPOSITE_PROCESSING 对手链转入交易确认中
      OPPOSITE_CONFIRMED 网关已确认对手链交易成功
      OPPOSITE_CONFIRMED_FAIL 网关已确认对手链交易失败
      BELOW_MINIMUM 对手链交易金额小于最小转入金额,转入流程结束
      TOT_PROCESSING 网关已发出 tot 转出交易
      TOT_CONFIRMED 网关已确认 tot 转出交易,转入流程结束
      string true
      dateTime 转入时间,timestamp 毫秒 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",
              "inTxConfirmedCount": 2,
              "inTxConfirmationCount": 12,
              "outTxHash": "9fb415eb6f30b27498a174bd868c29c9d30b9fa5bfb050d19156523ac540744b",
              "amount": "300000000000000000",
              "fee": "0",
              "state": "TOT_CONFIRMED",
              "dateTime": "1556129201000"
            }],
            "inTxExplorerFormat": "https://ropsten.etherscan.io/tx/{$tx}",
            "outTxExplorerFormat": "https://explorer.vite.org/zh/transaction/{$tx}"
          }
        }
        

      /withdraw-records

      转出记录。

      • Method: GET

      • Request: query string

      参数名 描述 数据类型 是否必传
      tokenId TOT id string true
      walletAddress 用户 VITE 地址 string true
      pageNum 分页参数,起始页序号,从 1 开始 int true
      pageSize 分页参数,每页大小 int true
      • Response
      参数名 描述 数据类型 是否必传
      totalCount 总记录数 int true
      withdrawRecords 转出记录列表 list false
      inTxExplorerFormat VITE 链浏览器,用 inTxHash 替换 {$tx} 为该交易区块浏览器地址 string true
      outTxExplorerFormat 对手链浏览器,用 outTxHash 替换 {$tx} 为该交易区块浏览器地址 string true
      • 其中 withdrawRecords 参数如下
      参数名 描述 数据类型 是否必传
      inTxHash VITE 链 tot 转入交易 hash string true
      inTxConfirmedCount VITE 链 tot 转入交易已确认数 int false
      inTxConfirmationCount VITE 链 tot 转入交易需要确认数 int false
      outTxHash 对手链转出交易 hash string false
      amount 实际转出到账金额 string true
      fee 网关收取的转出手续费 string true
      state 转出状态,枚举值
      TOT_PROCESSING VITE TOT 转入交易已发送,待确认
      TOT_CONFIRMED 网关已确认 VITE TOT 交易
      TOT_EXCEED_THE_LIMIT 超过限额
      WRONG_WITHDRAW_ADDRESS 转出地址错误
      OPPOSITE_PROCESSING 网关已发出对手链转出交易
      OPPOSITE_CONFIRMED 网关已确认对手链转出交易,转出流程结束
      string true
      dateTime 转出时间,timestamp 毫秒 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",
              "inTxConfirmedCount": 2,
              "inTxConfirmationCount": 300,
              "outTxHash": "0x8096542d958a3ac4f247eba3551cea4aa09e1cdad5d7de79db4b55f28864b628",
              "amount": "190000000000000000",
              "fee": "10000000000000000",
              "state": "OPPOSITE_CONFIRMED",
              "dateTime": "1556129201000"
            }],
            "inTxExplorerFormat": "https://explorer.vite.org/zh/transaction/{$tx}",
            "outTxExplorerFormat": "https://ropsten.etherscan.io/tx/{$tx}"
          }
        }
        

      错误码表

      code 描述
      0 请求成功
      1 请求参数校验不通过
      2 服务器内部异常

      协议版本

      当前版本

      v1.0

      历史版本

      版本号 更新说明
      v1.0 初始化版本