Js SDK¶
1 前言¶
此SDK文档面向BitXHub平台的应用开发者，提供BitXHub JS SDK的使用指南。
2 接口使用流程示例¶
为了更好的理解接口的使用，本示例将从初始化Client，部署合约，调用合约和返回值解析这个大致流程作介绍，具体详细接口可参考第三章SDK文档。
2.1 基本流程¶
2.1.1 安装并初始化Client¶
可以通过npm安装JS SDK并引入到JS的项目中
JS SDK分为几个磨块供用户分开进行调用，分别为：Client, PbType, Config, Transaction, Block, TripleDES以及AES。
用户在调用JS SDK与BitXHub进行交互时，主要是需要使用Client, PbType和Config这三个模块。
用户引入JS SDK的库以后首先需要配置网络地址和接口。
例如：
import { Config } from '@meshplus/js-bitxhub-client';
Config.setHosts(["localhost"]);
Config.setPorts(["9091"]);
初始化Client，所有操作将通过该对象与BitXHub交互。
例如：
2.1.2 部署合约¶
开发者需提供已经编译的WebAssembly文件。
例如：
通过client部署合约，部署完成后可以获取合约地址addr。
例如：
2.1.3 调用合约¶
调用合约需传入合约地址、合约方法名和对应的参数。
例如：
result = cli.InvokeContract(0, address, "a", PbType.pbInt32(1), PbType.pbInt32(2))
//第一个参数指定调用XVM合约还是BVM合约，第二个参数是合约地址， 方法名为a，传参1，传参2
2.1.4 完整示例¶
import { fs } from 'fs';
import { Client } from '@meshplus/js-bitxhub-client';
let contract = fs.readFileSync("./testdata/example.wasm");
let client = new Client(privateKey);
//部署合约，获取合约地址
let address = await cli.DeployContract(contract);
//调用合约，获取交易回执
result = cli.InvokeContract(1, address, "a", PbType.pbInt32(1), PbType.pbInt32(2));
//打印合约返回数据
console.log(result);
2.2 应用链管理流程示例¶
本示例展示应用链管理流程中的注册、审核以及注销操作。
2.2.1 应用链注册¶
调用BVM合约的Register方法，向BitXHub注册应用链。
例如：
let ret = cli.InvokeContract(0, InterchainContractAddr, "Register", PbType.pbString(validator),
PbType.pbInt32(0), PbType.pbString(chainType), PbType.pbString(name),
PbType.pbString(desc), PbType.pbString(version), PbType.pbString(pubKey)
);
获取到成功的交易回执后，得到交易回执内容。
例如：
{
"id": "0x5098cc26b0d485145fb8258d2e79c49886cd4662", \\应用链ID
"name": "税务链",
"validators": "",
"consensus_type": 0,
"status": 0,
"chain_type": "hyperchain",
"desc": "趣链税务链",
"version": "1.8"
}
2.2.2 应用链审核¶
调用BVM合约的Aduit方法，向BitXHub审核应用链。
例如：
let ret = cli.InvokeContract(0, InterchainContractAddr, "Aduit", PbType.pbString(address),
PbType.pbInt32(1), PbType.pbString(desc)
);
2.2.3 应用链注销¶
调用BVM合约的DeleteAppchain方法，向BitXHub注销应用链。
例如：
let ret = cli.InvokeContract(0, InterchainContractAddr, "DeleteAppchain", PbType.pbString(address));
2.3 验证规则使用示例¶
本示例展示验证规则中的注册、审核操作，以及WebAssembly合约示例。
2.3.1 验证规则注册¶
调用BVM合约的RegisterRule方法，向应用链注册验证规则（WebAssembly合约），这里我们需要先注册应用链和部署验证规则合约，然后获取应用链ID和合约地址。
例如：
let ret = cli.InvokeContract(0, RoleContractAddr, "RegisterRule", PbType.pbString(chainAddr), PbType.pbString(contractAddr));
2.3.2 验证规则审核¶
调用BVM合约的Aduit方法，向BitXHub审核验证规则。
例如：
let ret = cli.InvokeContract(0, RoleContractAddr, "Aduit", PbType.pbString(chainAddr),
PbType.pbInt32(1), PbType.pbString(desc)
);
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 发送交易¶
用途：调用该接口向中继链发送签名后的交易，交易类型包括普通交易、跨链交易和智能合约。若签名非法，仍会返回交易哈希，但是交易回执非法。
参数：
transaction交易实例。
3.1.2 发送交易并返回回执¶
用途：调用该接口向中继链发送签名后的交易，并返回交易回执。
参数：
transaction交易实例
3.1.3 发送只读交易¶
用途：调用该接口向中继链发送只读交易并返回交易回执。
参数：
transaction交易实例
3.1.4 查询交易回执¶
用途：调用该接口向BitXHub查询交易回执。
参数：
hash交易哈希。
3.1.5 查询交易¶
用途：调用该接口向BitXHub查询交易。
参数：
hash交易哈希。
3.2 合约接口¶
合约类型：
-
BVM：BitXHub内置合约。
-
XVM：WebAssembly合约。
3.2.1 部署合约¶
用途：调用该接口向BitXHub部署XVM合约，返回合约地址。
参数：
ctxwasm合约编译后的字节数据。
3.2.2 调用合约¶
用途：调用该接口向中继链调用合约获取交易回执。
参数：
-
vmType合约类型：BVM和XVM； -
address合约地址； -
method合约方法； -
args合约方法参数。
3.2.3 只读调用合约¶
用途：调用该接口向中继链只读调用合约获取交易回执。
参数：
-
vmType合约类型：BVM和XVM； -
address合约地址； -
method合约方法； -
args合约方法参数。
3.3 区块接口¶
3.3.1 查询区块¶
参数：
value区块高度或者区块哈希。type查询类型。
3.3.2 批量查询区块¶
用途：批量查询区块，返回指定块高度范围（start到end）的区块信息。
参数：
start指定范围的起始区块高度。end指定范围的结束区块高度。
3.3.3 查询区块Meta¶
用途：返回当前链的高度、区块哈希以及跨链交易数。
3.4 其他接口¶
3.4.1 查询账户nonce¶
用途：调用该接口获取当前账户地址下一笔跨链交易nonce。