中移链Java-SDK实战使用

id:BSN_2021 公众号：BSN研习社 作者：中移信息

​ 中移链是基于EOS区块链框架改造，满足BSN开放联盟链要求，符合国内监管政策。BSN开放联盟链（BSN Open Permissioned Blockchain, 简称OPB）包括多条基于公有链框架和联盟链框架搭建的公用链，开发者可以选择适合应用业务需求的开放联盟链部署和运行智能合约和分布式应用，每条开放联盟链各有特点和优势，并均使用类似公有链的燃料机制通过人民币计价，使用方便简洁。在符合国家监管政策的前提下，实现“开箱即用、快速上链”。

​ 中移链Java-SDK，是一个用于与其底层区块链EOS交互的API工具包，可提高Java、Android等开发者操作中移链、EOS的规范性及便利性。本文是关于如何使用中移链Java-SDK的操作指南，适用于中移链或EOS的开发者实战参考，也可以帮助其他读者了解中移链及其底层的EOS。

一、 中移链Java-SDK简述

​ 中移链Java-SDK 本质上是一个用于与EOS底层区块链交互的API工具，其提供的主要接口功能可参考EOS自带的插件chain_api_plugin。

​ 中移链Java-SDK的核心库使用了插件式接口程序的体系结构，可以灵活地在多种环境中使用。主要涉及到4个Provider接口程序（RPC Provider、Signature Provider、Serialization Provider、ABI Provider）。其中ABI Provider在EOSIO Java-SDK中提供了具体的实现（ABIProviderImpl），其它3个Provider并不在EOSIO Java-SDK中实现，需要单独导入使用（参考下文第二部分的导入相关jar包）。

​ 中移链Java-SDK的核心功能类是TransactionSession和TransactionProcessor，利用这些Provider来准备和处理EOS交易。

• RPC Provider（RPC接口程序）

  负责对nodeos的所有RPC调用，以及一般的网络处理（可达性、重试、故障转移逻辑等）。

• Signature Provider（签名接口程序）

  Signature Provider使用指定可用的密钥来请求和获取交易事务签名。所用于配置的签名，可以是来自平台密钥库中的密钥的签名，也可以是来自终端用户设备上的钱包应用程序的签名。平台可以让用户按照自己的偏好来选择其中一种方式保管密钥。

• Serialization Provider（序列化接口程序）

  负责处理ABI驱动的交易事务以及Json和二进制数据表示之间的操作序列化和反序列化。

• ABI Provider（ABI接口程序）

  负责获取和缓存ABI，以便在序列化和反序列化期间使用。

二、 导入相关jar包

​ 可以使用gradle或Maven等依赖包管理工具来导入相关jar包，主要是EOSIO Java-SDK和3个Provider包（Signature Provider、RPC Provider、Serialization Provider）。

1. Gradle工具导入

implementation 'one.block:eosiojava:1.0.0'
implementation 'one.block:eosiojavasoftkeysignatureprovider:1.0.0'
implementation 'one.block:eosio-java-abieos-serialization-provider:1.0.0'
implementation 'one.block:eosio-java-rpc-provider:1.0.0'

2. Maven工具导入

<dependency>
  <groupId>one.block</groupId>
  <artifactId>eosiojava</artifactId>
  <version>1.0.0</version>
</dependency>

<dependency>
  <groupId>one.block</groupId>
  <artifactId>eosiojavasoftkeysignatureprovider</artifactId>
  <version>1.0.0</version>
</dependency>

<dependency>
  <groupId>one.block</groupId>
  <artifactId>eosio-java-abieos-serialization-provider</artifactId>
  <version>1.0.0</version>
</dependency>

<dependency>
  <groupId>one.block</groupId>
  <artifactId>eosio-java-rpc-provider</artifactId>
  <version>1.0.0</version>
</dependency> 

三、 配置相关初始化参数

主要初始化参数包括：

• 配置RPC Provider所连接的链URL地址；

• 配置Signature Provider的私钥。

IRPCProvider rpcProvider = new EosioJavaRpcProviderImpl("https://baseurl.com/v1/");
SoftKeySignatureProviderImpl signatureProvider = new SoftKeySignatureProviderImpl();
signatureProvider.importKey("xxxxx");  

四、 实现API调用

1. EOS链基本信息查询

​ EOS链基本信息查询可以通过实例化RPC Provider（RPC接口程序）来实现，只需配置RPC Provider所连接的链URL地址即可。

​ RPC Provider的常用API方法有：

getInfo();    // 调用返回区块链总体信息
getBlockInfo();   // 调用返回指定区块的详细数据
getRawAbi();   // 调用返回指定账号所托管合约的abi描述信息
getRequiredKeys();  // 调用返回签名一个交易时需要的公钥清单

示例程序：

// getInfo()
IRPCProvider rpcProvider = new EosioJavaRpcProviderImpl("https://baseurl.com/v1/"); 
GetInfoResponse getInfoResponse = rpcProvider.getInfo();
System.out.println(getInfoResponse.getHeadBlockNum());  
// getBlockInfo()  
BigInteger blockNum = BigInteger.valueOf(543210);
GetBlockInfoRequest getBlockInfoRequest = new GetBlockInfoRequest(blockNum);
GetBlockInfoResponse getBlockInfoResponse = rpcProvider.getBlockInfo(getBlockInfoRequest);
System.out.println(getBlockInfoResponse.getTransactionMroot());

2. EOS交易处理

​ EOS交易事务通过实例化的TransactionSession来执行，TransactionSession由配置4个Provider实例来构造而成。

​ 交易事务处理的一些参数可以通过使用TransactionConfig进行更改。这些参数是UselastReversible、blocksBehind和expiresSeconds。其默认值分别为UselastReversible等于true，blocksBehind等于3，expiresSeconds等于300。当UselastReversible为true时，将忽略blocksBehind，TransactionProcessor使用最后一个不可逆块和expiresSeconds来计算TAPO。否则，TransactionProcessor使用当前头块减去在blocksBehind和expiresSeconds中为TAPO指定的数字。TransactionConfig默认为UselastReversible，目的为减少在特定条件下进行交易事务微分叉的机会。

​ 示例程序：

// 4个Provider的实例化及初始化 
IRPCProvider rpcProvider = new EosioJavaRpcProviderImpl("https://baseurl.com/v1/");
ISerializationProvider serializationProvider = new AbiEosSerializationProviderImpl();
IABIProvider abiProvider = new ABIProviderImpl(rpcProvider, serializationProvider);
SoftKeySignatureProviderImpl signatureProvider = new SoftKeySignatureProviderImpl();
signatureProvider.importKey("xxxxx");

// 4个Provider实例构造成TransactionSession
TransactionSession session = new TransactionSession(
        serializationProvider,
        rpcProvider,
        abiProvider,
        signatureProvider
);
TransactionProcessor processor = session.getTransactionProcessor();

TransactionConfig transactionConfig = processor.getTransactionConfig();
// 按需修改transactionConfig配置
transactionConfig.setUseLastIrreversible(false);
transactionConfig.setExpiresSeconds(600);
// 使transactionConfig生效
processor.setTransactionConfig(transactionConfig);

// 组装交易参数
String jsonData = "{\n" +
        "\"from\": \"person1\",\n" +
        "\"to\": \"person2\",\n" +
        "\"quantity\": \"1.0000 EOS\",\n" +
        "\"memo\" : \"交易备注\"\n" +
        "}";
List<Authorization> authorizations = new ArrayList<>();
authorizations.add(new Authorization("myaccount", "active"));
List<Action> actions = new ArrayList<>();
actions.add(new Action("eosio.token", "transfer", authorizations, jsonData));
processor.prepare(actions);

// 交易提交及广播
SendTransactionResponse sendTransactionResponse = processor.signAndBroadcast();

// 从EOSIO 2.1开始，交易操作可以具有与之关联的返回值
ArrayList<Object> actionReturnValues = sendTransactionResponse.getActionValues();
System.out.println(actionReturnValues);

五、 参考链接

BSN开放联盟链^[1] 官方EOSIO Java-SDK^[2] 官方EOSIO的RPC Provider（RPC接口程序）^[3] 官方EOSIO的Signature Provider（签名接口程序）^[4] 官方EOSIO的Serialization Provider（序列化接口程序）^[5] 官方EOSIO的Android示例程序^[6]

参考资料