中移鏈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(
");

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(
"); 

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(
");

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]

參考資料