Java SDK
1 前言
此SDK文档面向BitXHub平台的应用开发者，提供BitXHub Java SDK的使用指南。
2 接口使用流程示例
2.1 基础流程示例
为了更好的理解接口的使用，本示例将从初始化Client，部署合约，调用合约和返回值解析这个大致流程作介绍，具体详细接口可参考第三章SDK文档。
2.1.1 初始化Client
使用默认的配置类初始化Grpc Client。
例如：
GrpcClient client = new GrpcClientImpl(Config.defaultConfig());
使用定制化的配置类初始化Grpc Client。
例如：
Config config = Config.builder()
.host("localhost")
.port(60011)
.ecKey(new ECKeyP256())
.build();
GrpcClient client = new GrpcClientImpl(config);
2.1.2 部署合约
开发者需提供已经编译的WebAssembly文件。
例如：
byte[] contractBytes = IOUtils.toByteArray(new FileInputStream("./example.wasm"));
通过client部署合约，部署完成后可以获取合约地址contractAddress。
例如：
String contractAddress = client.deployContract(contractBytes);
2.1.3 调用合约
调用合约需传入合约地址、合约方法名和对应的参数。
例如：
ReceiptOuterClass.Receipt receipt =
client.invokeXVMContract(contractAddress, "a", Types.i32(1), Types.i32(1)); \\方法名为a，传参1，传参2
2.1.4 返回值解析
得到返回值结果后，获得状态码可以判断是否调用成功，若调用成功，解析返回值可看到调用之后的结果。
例如：
if (receipt.getStatus() == ReceiptOuterClass.Receipt.Status.SUCCESS) {
log.info(receipt.getRet().toStringUtf8());
}
2.1.5 完整示例
//获取wasm字节数组
byte[] contractBytes = IOUtils.toByteArray(
new FileInputStream("./example.wasm"));
//部署合约，获取合约地址
String contractAddress = client.deployContract(contractBytes);
//调用合约，获取交易回执
ReceiptOuterClass.Receipt receipt = client.invokeXVMContract(contractAddress, "a", Types.i32(1), Types.i32(1));
//判断合约调用交易成功与否，打印合约调用数据
if (receipt.getStatus() == ReceiptOuterClass.Receipt.Status.SUCCESS) {
log.info(receipt.getRet().toStringUtf8());
}
2.2 应用链管理流程示例
本示例展示应用链管理流程中的注册、审核以及注销操作。
2.2.1 应用链注册
调用BVM合约的Register方法，向BitXHub注册应用链。
例如：
ArgOuterClass.Arg[] args = Types.toArgArray(
Types.string(""), //validators
Types.i32(0), //consensus_type
Types.string("hyperchain"), //chain_type
Types.string("税务链"), //name
Types.string("趣链税务链"), //desc
Types.string("1.8")); //version
Types.string("")); //public key
ReceiptOuterClass.Receipt receipt = client.invokeBVMContract(BVMAddr.APPCHAIN_MANAGER_CONTRACT_ADDR, "Register", args);
获取到成功的交易回执后，解析交易回执内容。
例如：
{
"id": "0x5098cc26b0d485145fb8258d2e79c49886cd4662", \\应用链ID
"name": "税务链",
"validators": "",
"consensus_type": 0,
"status": 0,
"chain_type": "hyperchain",
"desc": "趣链税务链",
"version": "1.8",
"public_key": ""
}
2.2.2 应用链审核
调用BVM合约的Audit方法，向BitXHub审核应用链。
例如：
ArgOuterClass.Arg[] adultArgs = Types.toArgArray(
Types.string(appchainID), //应用链ID
Types.i32(1), //审核通过
Types.string("")); //描述信息
ReceiptOuterClass.Receipt adultReceipt = client.invokeBVMContract(BVMAddr.APPCHAIN_MANAGER_CONTRACT_ADDR, "Audit", adultArgs);
2.2.3 应用链注销
调用BVM合约的DeleteAppchain方法，向BitXHub注销应用链。
例如：
ArgOuterClass.Arg[] deleteArgs = Types.toArgArray(
Types.string(appchainID); //应用链ID
ReceiptOuterClass.Receipt deleteReceipt = client.invokeBVMContract(BVMAddr.APPCHAIN_MANAGER_CONTRACT_ADDR, "DeleteAppchain", deleteArgs);
2.3 验证规则使用示例
本示例展示验证规则中的注册、审核操作，以及WebAssembly合约示例。
2.3.1 验证规则注册
调用BVM合约的RegisterRule方法，向应用链注册验证规则（WebAssembly合约），这里我们需要先注册应用链和部署验证规则合约，然后获取应用链ID和合约地址。
例如：
ArgOuterClass.Arg[] ruleArgs = Types.toArgArray(
Types.string(appchainID),
Types.string(contractAddress));
ReceiptOuterClass.Receipt ruleReceipt = client.invokeBVMContract(BVMAddr.RULE_MANAGER_CONTRACT_ADDR, "RegisterRule", ruleArgs);
2.3.2 验证规则审核
调用BVM合约的Audit方法，向BitXHub审核验证规则。
例如：
ArgOuterClass.Arg[] adultArgs = Types.toArgArray(
Types.string(contractAddress), //验证规则的合约地址
Types.i32(1), //审核通过
Types.string("")); //描述信息
ReceiptOuterClass.Receipt adultReceipt = client.invokeBVMContract(BVMAddr.RULE_MANAGER_CONTRACT_ADDR, "Audit", adultArgs);
2.3.3 验证规则示例（WebAssembly合约, Fabric实例）
extern crate protobuf;
extern crate sha2;
use crate::crypto::ecdsa;
use crate::model::transaction;
use sha2::{Digest, Sha256};
pub fn verify(proof: &[u8], validator: &[u8]) -> bool {
let cap =
protobuf::parse_from_bytes::<transaction::ChaincodeActionPayload>(proof).expect("error");
let cap_act = cap.action.unwrap();
let endorsers = cap_act.endorsements;
let mut digest = Sha256::new();
let mut payload = cap_act.proposal_response_payload.to_owned();
payload.extend(&endorsers[0].endorser);
digest.input(&payload);
let digest_byte = digest.result();
return ecdsa::verify(
&endorsers[0].signature,
&digest_byte,
&validator,
ecdsa::EcdsaAlgorithmn::P256,
);
}
3 SDK文档
3.1 初始化
3.1.1 初始化Client
用途：调用该接口获取与BitXHub交互的Client。
GrpcClient client = new GrpcClientImpl(Config.defaultConfig());
入参：Config 是BitXHub的网络地址, 端口以及密钥的配置。
返回值：与BitXHub交互的Client。
3.1.2 停止Client
用途：调用该接口将与BitXHub交互的Client关闭。
public void stop() throws InterruptedException
3.2 交易接口
3.2.1 发送交易
用途：调用该接口向BitXHub发送交易，交易类型包括普通交易、跨链交易和智能合约交易。
参数：
transaction交易。opts跨链交易nonce。
public String sendTransaction(TransactionOuterClass.Transaction transaction, TransactOpts opts);
用例：
public void sendTransaction() {
TransactionOuterClass.Transaction unsignedTx = TransactionOuterClass.Transaction.newBuilder()
.setFrom(ByteString.copyFrom(from))
.setTo(ByteString.copyFrom(to))
.setTimestamp(Utils.genTimestamp())
.setPayload(TransactionOuterClass.TransactionData.newBuilder().setAmount(100000L).build().toByteString())
.build();
TransactionOuterClass.Transaction signedTx = SignUtils.sign(unsignedTx, config.getEcKey());
String txHash = client.sendTransaction(signedTx, null);
}
3.2.2 查询交易回执
参数：
hash交易哈希。
ReceiptOuterClass.Receipt getReceipt(String hash);
3.2.3 查询交易
参数：
hash交易哈希。
Broker.GetTransactionResponse getTransaction(String hash);
3.3 合约接口
合约类型：
-
BVM：BitXHub内置合约
-
XVM：WebAssembly合约
3.3.1 部署合约
用途：调用该接口向BitXHub部署XVM合约。
参数：
contract合约数据。
String deployContract(byte[] contract);
3.3.2 调用合约
用途：调用该接口向BitXHub调用BVM或者XVM合约。
参数：
vmType合约类型：BVM和XVM。contractAddress合约地址。method合约方法；args合约方法参数。ReceiptOuterClass.Receipt invokeContract(TransactionOuterClass.TransactionData.VMType vmType, String contractAddress, String method, ArgOuterClass.Arg... args);
用例：
public void invokeContract() throws IOException {
byte[] contractBytes = IOUtils.toByteArray(
new FileInputStream("./example.wasm"));
String contractAddress = client.deployContract(contractBytes);
ReceiptOuterClass.Receipt receipt = client.invokeContract(TransactionOuterClass.TransactionData.VMType.XVM
, contractAddress, "a", Types.i32(1), Types.i32(1));
}
3.4 区块接口
3.4.1 查询区块
参数：
value区块高度或者区块哈希。type查询类型。type类型。
BlockOuterClass.Block getBlock(String value, Broker.GetBlockRequest.Type type);
3.4.2 批量查询区块
用途：批量查询区块，返回指定块高度范围（start到end）的区块信息。
参数：
start指定范围的起始区块高度。end指定范围的结束区块高度。
Broker.GetBlocksResponse getBlocks(Long start, Long end);
3.4.3 查询区块Meta
用途：返回当前链的高度和区块哈希。
Chain.ChainMeta getChainMeta();
3.4.4 查询区块链状态
用途：返回当前区块链共识的状态（正常或者不正常）。
Broker.Response getChainStatus();
3.5 订阅接口
3.5.1 订阅事件
用途：调用该接口向BitXHub发起订阅事件。
参数：
streamObserver事件通道。type事件类型。
用例：
void subscribe(Broker.SubscriptionRequest.Type type, StreamObserver<Broker.Response> observer);
public void subscribe() throws InterruptedException {
CountDownLatch asyncLatch = new CountDownLatch(1);
StreamObserver<Broker.Response> observer = new StreamObserver<Broker.Response>() {
@Override
public void onNext(Broker.Response response) {
ByteString data = response.getData();
BlockOuterClass.Block block = null;
try {
block = BlockOuterClass.Block.parseFrom(data);
} catch (InvalidProtocolBufferException e) {
e.printStackTrace();
}
}
@Override
public void onError(Throwable throwable) {
throwable.printStackTrace();
asyncLatch.countDown();
}
@Override
public void onCompleted() {
asyncLatch.countDown();
}
};
client.subscribe(Broker.SubscriptionRequest.Type.BLOCK, observer);
asyncLatch.await();
}
3.6 其它接口
3.6.1 查询节点网络信息
用途：返回当前区块链网络的节点信息。
Broker.Response getNetworkMeta();
3.6.2 查询账户余额
参数：
address地址。
Broker.Response getAccountBalance(String address);