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>
复制代码
三、 配置相关初始化参数
主要初始化参数包括:
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]
参考资料
[1]
BSN 开放联盟链: https://opb.bsnbase.com/main/index
[2]
官方 EOSIO Java-SDK: https://github.com/EOSIO/eosio-java
[3]
官方 EOSIO 的 RPC Provider(RPC 接口程序): https://github.com/EOSIO/eosio-java-rpc-provider
[4]
官方 EOSIO 的 Signature Provider(签名接口程序): https://github.com/EOSIO/eosio-java-softkey-signature-provider
[5]
官方 EOSIO 的 Serialization Provider(序列化接口程序): https://github.com/EOSIO/eosio-java-abieos-serialization-provider
[6]
官方 EOSIO 的 Android 示例程序: https://github.com/EOSIO/eosio-java-android-example-app
评论