# NRC20-Token对接指南

前提: 测试网chainId=2, 主网chainId=1

# 一、发起NRC20转账交易

对照接口说明文档中的接口编号

JSONRPC接口说明文档

RESTFUL接口说明文档

# 1. 钱包模式

调用4.4接口,创建并广播NRC20转账交易, 记录接口返回的交易hash。

# 2. 冷钱包模式

  • JSONRPC方式

    JSONRPC接口说明文档

    调用1.7接口,获取账户的NULS余额,与NULS的当前nonce值

    调用4.17接口 (可跳过),估算调用合约需要的GAS,可不估算,离线写一个合理的值

    调用4.22接口,离线组装NRC20转账交易

    调用1.15接口,签名交易

    调用3.3接口,广播交易,记录交易hash

  • RESTFUL方式

    RESTFUL接口说明文档

    调用1.10接口,获取账户的NULS余额,与NULS的当前nonce值

    调用4.17接口 (可跳过),估算调用合约需要的GAS,可不估算,离线写一个合理的值

    调用4.22接口,离线组装NRC20转账交易

    调用1.17接口,签名交易

    调用3.3接口,广播交易,记录交易hash

# 二、监控NRC20转账交易

# 1. 解析调用合约交易,交易类型是16,并取出交易hash

txType=16

# 2. 根据交易hash查询智能合约执行结果,三种查询方式任选其一

我们提供了RESTFULJSONRPC的HTTP请求方式获取数据, 也提供了JAVA-SDK查询执行结果

  • 通过RESTFUL接口/api/contract/result/{hash}

    • 测试网请求URL: http://beta.api.nuls.io/api/contract/result/{hash}
    • 主网请求URL: https://api.nuls.io/api/contract/result/{hash}
    • 请求以及返回结果示例 (Example部分)
  • 通过JSONRPC接口getContractTxResult

    • 测试网请求URL: http://beta.api.nuls.io/jsonrpc

    • 主网请求URL: https://api.nuls.io/api/jsonrpc

    • 请求以及返回结果示例 (Example部分)

    • 简单请求示例

      {
          "jsonrpc":"2.0",
          "method":"getContractTxResult",
          "params":[chainId, hash], // 测试网chainId=2, 主网chainId=1
          "id":1234
      }
      
  • 通过JAVA-SDK查询执行结果

    引入Mavan依赖

    <!-- JDK11环境下 -->
    <dependency>
        <groupId>io.nuls.v2</groupId>
        <artifactId>sdk4j</artifactId>
        <version>1.1.4.RELEASE</version>
    </dependency>
    
    <!-- JDK8环境下 -->
    <dependency>
        <groupId>io.nuls.v2</groupId>
        <artifactId>sdk4j-jdk8</artifactId>
        <version>1.1.9.RELEASE</version>
    </dependency>
    
    // 测试网SDK初始化
    NulsSDKBootStrap.initTest("http://beta.api.nuls.io/");
    
    // 主网SDK初始化
    NulsSDKBootStrap.initMain("https://api.nuls.io/");
    
    // 结果查询
    Result result = NulsSDKTool.getContractResult("f0d1257b4f7897c8b2188d89e65047cfee5e9958b8e1dba688d076e04a51f90f");
    if(result.isSuccess()) {
        Map<String, Object> resultMap = (Map<String, Object>) result.getData();
        Map<String, Object> dataMap = (Map<String, Object>) resultMap.get("data");
        // 判断合约是否执行成功
        boolean success = Boolean.parseBoolean(dataMap.get("success").toString());
        if(!success) {
            // 合约执行失败,不会存在token转账信息
            return;
        }
        // 获取tokenTransfers集合
        List<Map<String, Object>> tokenTransfers = (List<Map<String, Object>>) dataMap.get("tokenTransfers");
        // 遍历tokenTransfers集合
        for(Map<String, Object> tokenTransfer : tokenTransfers) {
            // NRC20合约地址
            String contractAddress = tokenTransfer.get("contractAddress").toString();
            // token转出地址, 请自行做空值校验
            String from = (String) tokenTransfer.get("from");
            // token转入地址, 请自行做空值校验
            String to = (String) tokenTransfer.get("to");
            // token转移数量
            BigInteger value = new BigInteger(tokenTransfer.get("value").toString());
            // token全称
            String name = tokenTransfer.get("name").toString();
            // token标识
            String symbol = tokenTransfer.get("symbol").toString();
            // token小数位数
            Integer decimals = Integer.parseInt(tokenTransfer.get("decimals").toString());
            //TODO something
            System.out.println();
        }
    }
    

# 3. 获取智能合约执行结果中的tokenTransfers数组对象

  • 此数组对象是公链底层系统针对NRC20合约的token转账事件(TransferEvent)进行的数据加工,补充了发生token转账的合约的基本信息 - name, symbol, decimals

示例: 截取合约执行结果的tokenTransfers数组对象,如下

"tokenTransfers": [
    {
        "contractAddress": "tNULSeBaN5hS7mwjNmCjbPPzMG1C6FnB9RHTKP",
        "from": "tNULSeBaMyfDzgv1NoNq67KUpekRHePnPyn5Vw",
        "to": "tNULSeBaMvEtDfvZuukDf2mVyfGo3DdiN8KLRG",
        "value": "11098552585",
        "name": "Btcoin",
        "symbol": "BTC",
        "decimals": 8
    }
]

注意1: 这里的value是合约token数值转换后的去小数化存储值,同以太坊token方式

注意2: 产生的token转账的合约地址不一定是当前调用的合约,所以在这个数据结构里有contractAddress属性,它不是冗余字段

注意3: 在交易所正常业务上看,from地址和to地址不会出现空值,但由于一些NRC20发行者的特殊业务,可能会出现空值,所以,from地址和to地址,请做空值校验

# 4. 名词解释

名词 描述
contractAddress NRC20合约地址
from token转出地址
to token转入地址
value token转移数量
name token全称
symbol token标识
decimals token小数位数

# 5. 根据tokenTransfers数组对象,处理业务相关数据

  • 请根据tokenTransfers数组对象中的contractAddress定位NRC20资产,由于存在合约内部可以调用另外的合约的场景,所以直接根据合约调用交易里的合约地址来锁定NRC20资产是不准确的。
Last Updated: 2021/1/26 下午2:35:53