ChainMaker Java SDK README

基本概念定义

Java SDK定义了User、Node、ChainClient和ChainManager和SdkConfig几个类，分别介绍如下：

User: 表示链的一个用户信息，主要包括证书和private key，用来给要发送的交易payload签名或者给多签的payload签名。
Node：表示链的一个节点信息，它定义了节点的各种属性，如节点连接的RPC地址，连接所用的密钥信息等，一个ChainClient对象需要包含一个或多个Node，这样才能对过节点实现各种功能。
ChainClient：客户端开发最重要也是使用最多的类，代表逻辑上的一条链，所有客户端对链的操作接口都来自ChainClient。
ChainManager：负责管理所有创建过的链，是一个链管理类，避免用户同一条链创建多个ChainClient。用户可以使用ChainManager来检查某条链是否已经创建，或者直接创建某条链，如果这条链已经创建，ChainManager会直接返回之前已经创建过的
SdkConfig: 创建ChainClient所需的配置类。

ChainClient对象给用户使用。数据结构定义如下：

public class User {
    // the organization id of the user
    private String orgId;
    // user's private key used to sign transaction
    private PrivateKey privateKey;
    // user's certificate
    private Certificate certificate;
    // user's private key used to sign transaction
    private PrivateKey tlsPrivateKey;
    // user's certificate
    private Certificate tlsCertificate;
    // the bytes of user's certificate
    private byte[] certBytes;
    // the hash of the cert
    private byte[] certHash;

    private CryptoSuite cryptoSuite;
}

public class Node {
    // node grpc address
    private String grpcUrl;
    // the organization's ca cert bytes
    private byte[][] tlsCertBytes;
    // the hostname in client certificate
    private String hostname;
    // TLS or PLAINTEXT
    private String negotiationType;
    // OPENSSL or JDK
    private String sslProvider;
    // node connect count
    private int connectCount;
}

public class ChainClient {
    // chainId is the identity of the chain
        private String chainId;
        // rpc connection Pool
        private ConnectionPool connectionPool;
        // archive config
        private ArchiveConfig archiveConfig;
        // the user used to sign transactions
        private User clientUser;
}

public class ChainManager {
    // chains' map
    private final Map<String, ChainClient> chains = new HashMap<>();
    // for singleton mode
    private static final ChainManager chainManager = new ChainManager();
}

ChainClient类接口定义

1 用户合约接口

1.1 生成用于创建合约的待签名payload

参数说明

contractName: 合约名
version: 版本号
runtimeType: 合约运行环境
params: 合约初始化参数
byteCodes: 合约字节数组

   public Request.Payload createContractCreatePayload(String contractName, String version, byte[] byteCode,
                                                          ContractOuterClass.RuntimeType runtime, Map<String, byte[]> params)

1.2 生成用于升级合约的待签名payload

参数说明

contractName: 合约名
version: 版本号
runtimeType: 合约运行环境
params: 合约初始化参数
byteCodes: 合约字节数组

public Request.Payload createContractUpgradePayload(String contractName, String version, byte[] byteCode,
                                                       ContractOuterClass.RuntimeType runtime, Map<String, byte[]> params)

1.3 生成用于冻结合约的待签名payload

参数说明

contractName: 合约名

public byte[] createContractFreezePayload(String contractName) {}

1.4 生成用于解冻合约的待签名payload

参数说明

contractName: 合约名

public byte[] createContractUnFreezePayload(String contractName) {}

1.5 生成用于吊销合约的待签名payload

参数说明

contractName: 合约名

public byte[] createContractRevokePayload(String contractName) {}

1.6 发送合约操作请求

参数说明

payload: 合约内容
endorsementEntries: 带签名的合约内容
rpcCallTimeout: 调用rcp接口超时时间, 单位：毫秒
syncResultTimeout: 同步获取执行结果超时时间，小于等于0代表不等待执行结果，直接返回（返回信息里包含交易ID），单位：毫秒

    public ResultOuterClass.TxResponse sendContractManageRequest(Request.Payload payload, Request.EndorsementEntry[] endorsementEntries,
                                                                     long rpcCallTimeout, long syncResultTimeout)

1.7 执行合约

参数说明

contractName: 合约名
method: 方法名
params: 执行参数
rpcCallTimeout: 调用rcp接口超时时间, 单位：毫秒
syncResultTimeout: 同步获取执行结果超时时间，小于等于0代表不等待执行结果，直接返回（返回信息里包含交易ID），单位：毫秒

    public ResultOuterClass.TxResponse invokeContract(String contractName, String method, String txId,  Map<String, byte[]> params,
                                                          long rpcCallTimeout, long syncResultTimeout)

1.8 查询合约接口

参数说明

contractName: 合约名
method: 方法名
txId: 交易id
params: 执行参数
rpcCallTimeout: 执行超时时间，单位毫秒

    public ResultOuterClass.TxResponse queryContract(String contractName, String method, String txId,
                                                         Map<String, byte[]> params, long rpcCallTimeout)

2 系统合约接口

2.1 根据交易Id查询交易

参数说明

txId: 交易ID
rpcCallTimeout：超时时间，单位毫秒

    ChainmakerTransaction.TransactionInfo getTxByTxId(String txId, long rpcCallTimeout)

2.2 根据区块高度查询区块

参数说明

blockHeight: 区块高度
withRWSet: 是否返回读写集
rpcCallTimeout：超时时间，单位毫秒

    public ChainmakerBlock.BlockInfo getBlockByHeight(long blockHeight, boolean withRWSet, long rpcCallTimeout)

2.3 根据区块哈希查询区块

参数说明

blockHash: 区块高度
withRWSet: 是否返回读写集
rpcCallTimeout：超时时间，单位毫秒

    public ChainmakerBlock.BlockInfo getBlockByHash(String blockHash, boolean withRWSet, long rpcCallTimeout)

2.4 根据交易Id查询区块

参数说明

txId: 交易Id
withRWSet: 是否返回读写集
rpcCallTimeout：超时时间，单位毫秒

    public ChainmakerBlock.BlockInfo getBlockByTxId(String txId, boolean withRWSet, long rpcCallTimeout)

2.5 查询上一个配置块

参数说明

withRWSet: 是否返回读写集
rpcCallTimeout：超时时间，单位毫秒

    ChainmakerBlock.BlockInfo getLastConfigBlock(boolean withRWSet, long rpcCallTimeout)

2.6 查询节点加入的链信息

参数说明

timeout：超时时间，单位毫秒

    public Discovery.ChainList getNodeChainList(long rpcCallTimeout)

2.7 查询链信息

参数说明

rpcCallTimeout：超时时间，单位毫秒

     public Discovery.ChainInfo getChainInfo(long rpcCallTimeout)

2.8 根据txId查询区块高度

参数说明

txId: 交易id
rpcCallTimeout：超时时间，单位毫秒

    public long getBlockHeightByTxId(String txId, long rpcCallTimeout) 

2.9 根据blockHash查询区块高度

参数说明

blockHash: 区块哈希
rpcCallTimeout：超时时间，单位毫秒

    public long getBlockHeightByBlockHash(String blockHash, long rpcCallTimeout)

2.10 根据区块高度查询完整区块

参数说明

blockHeight : 区块高度
rpcCallTimeout：超时时间，单位毫秒

    public Store.BlockWithRWSet getFullBlockByHeight(long blockHeight, long rpcCallTimeout)

2.11 查询最新区块信息

参数说明

withRWSet: 是否返回读写集
timeout：超时时间，单位毫秒

    public ChainmakerBlock.BlockInfo getLastBlock(boolean withRWSet, long rpcCallTimeout)

2.12 查询最新区块高度

参数说明

timeout：超时时间，单位毫秒

    public long getCurrentBlockHeight(long timeout) 

2.13 根据区块高度查询区块头

参数说明

区块高度: blockHeight
rpcCallTimeout：超时时间，单位毫秒

    public ChainmakerBlock.BlockHeader getBlockHeaderByHeight(long blockHeight, long timeout) 

2.14 系统合约调用

参数说明

method: 方法名
txId: 交易id
params: 执行参数
rpcCallTimeout: 调用rcp接口超时时间, 单位：毫秒
syncResultTimeout: 同步获取执行结果超时时间，小于等于0代表不等待执行结果，直接返回（返回信息里包含交易ID），单位：毫秒

    ResultOuterClass.TxResponse invokeSystemContract(String contractName, String method, String txId,  Map<String, byte[]> params,
                                                          long rpcCallTimeout, long syncResultTimeout)

2.15 系统合约查询

参数说明

method: 方法名
txId: 交易id
params: 执行参数
rpcCallTimeout: 调用rcp接口超时时间, 单位：毫秒

    public ResultOuterClass.TxResponse (String contractName, String method, String txId,
                                                         Map<String, byte[]> params, long rpcCallTimeout)

3 链配置接口

3.1 查询最新链配置

    ChainConfigOuterClass.ChainConfig getChainConfig(long rpcCallTimeout)

3.2 根据指定区块高度查询最近链配置

参数说明

blockHeight: 区块高度

    public ChainConfigOuterClass.ChainConfig getChainConfigByBlockHeight(long blockHeight, long rpcCallTimeout)

3.3 查询最新链配置序号Sequence

用于链配置更新

    public long getChainConfigSequence(long rpcCallTimeout)

3.4 更新Core模块待签名payload生成

参数说明

txSchedulerTimeout: 交易调度器从交易池拿到交易后, 进行调度的时间，其值范围为[0, 60]，若无需修改，请置为-1
txSchedulerValidateTimeout: 交易调度器从区块中拿到交易后, 进行验证的超时时间，其值范围为[0, 60]，若无需修改，请置为-1

    public Request.Payload createPayloadOfChainConfigCoreUpdate(int txSchedulerTimeout, int txSchedulerValidateTimeout, long rpcCallTimeout)

3.5 更新Core模块待签名payload生成

参数说明

txTimestampVerify: 是否需要开启交易时间戳校验
(以下参数，若无需修改，请置为-1)
txTimeout: 交易时间戳的过期时间(秒)，其值范围为[600, +∞)
blockTxCapacity: 区块中最大交易数，其值范围为(0, +∞]
blockSize: 区块最大限制，单位MB，其值范围为(0, +∞]
blockInterval: 出块间隔，单位:ms，其值范围为[10, +∞]

     public Request.Payload createPayloadOfChainConfigBlockUpdate(boolean txTimestampVerify, int txTimeout, int blockTxCapacity,
                                                            int blockSize, int blockInterval, long rpcCallTimeout)

3.6 添加信任组织根证书待签名payload生成

参数说明

trustRootOrgId: 组织Id
trustRootCrt: 根证书

    public Request.Payload createPayloadOfChainConfigTrustRootAdd(String trustRootOrgId, String[] trustRootCrt, long rpcCallTimeout)

3.7 更新信任组织根证书待签名payload生成

参数说明

trustRootOrgId: 组织Id
trustRootCrt: 根证书

    public Request.Payload createPayloadOfChainConfigTrustRootUpdate(String trustRootOrgId, String[] trustRootCrt, long rpcCallTimeout)

3.8 删除信任组织根证书待签名payload生成

参数说明

trustRootOrgId: 组织Id

    public Request.Payload createPayloadOfChainConfigTrustRootDelete(String trustRootOrgId, long rpcCallTimeout)

3.9 添加权限配置待签名payload生成

参数说明

permissionResourceName: 权限名
principle: 权限规则

    public Request.Payload createPayloadOfChainConfigPermissionAdd(String permissionResourceName,
                                                              PolicyOuterClass.Policy principal, long rpcCallTimeout)

3.10 更新权限配置待签名payload生成

参数说明

permissionResourceName: 权限名
principle: 权限规则

    public Request.Payload createPayloadOfChainConfigPermissionUpdate(String permissionResourceName,
                                                                 PolicyOuterClass.Policy principal, long rpcCallTimeout)

3.11 删除权限配置待签名payload生成

参数说明

permissionResourceName: 权限名

    public Request.Payload createPayloadOfChainConfigPermissionDelete(String permissionResourceName, long rpcCallTimeout)

3.12 添加共识节点地址待签名payload生成

参数说明

nodeOrgId: 节点组织Id
nodeAddresses: 节点地址

    public Request.Payload createPayloadOfChainConfigConsensusNodeAddrAdd(String nodeOrgId, String[] nodeAddresses, long rpcCallTimeout)

3.13 更新共识节点地址待签名payload生成

参数说明

nodeOrgId: 节点组织Id
nodeOldAddress: 节点原地址
nodeNewAddress: 节点新地址

    public Request.Payload createPayloadOfChainConfigConsensusNodeAddrUpdate(String nodeOrgId, String nodeOldAddress,
                                                                        String nodeNewAddress, long rpcCallTimeout)

3.14 删除共识节点地址待签名payload生成

参数说明

nodeOrgId: 节点组织Id
nodeAddress: 节点地址

    public Request.Payload createPayloadOfChainConfigConsensusNodeAddrDelete(String nodeOrgId, String nodeAddress, long rpcCallTimeout)

3.15 添加共识节点待签名payload生成

参数说明

nodeOrgId: 节点组织Id
nodeAddresses: 节点地址

    public Request.Payload createPayloadOfChainConfigConsensusNodeOrgAdd(String nodeOrgId, String[] nodeAddresses, long rpcCallTimeout)

3.16 更新共识节点待签名payload生成

参数说明

nodeOrgId: 节点组织Id
nodeAddresses: 节点地址

    public Request.Payload createPayloadOfChainConfigConsensusNodeOrgUpdate(String nodeOrgId, String[] nodeAddresses, long rpcCallTimeout)

3.17 删除共识节点待签名payload生成

参数说明

nodeOrgId: 节点组织Id

    public Request.Payload createPayloadOfChainConfigConsensusNodeOrgDelete(String nodeOrgId, long rpcCallTimeout)

3.18 添加共识扩展字段待签名payload生成

参数说明

params: Map<String, String>

    public Request.Payload createPayloadOfChainConfigConsensusExtAdd(Map<String, byte[]> params, long rpcCallTimeout)

3.19 添加共识扩展字段待签名payload生成

参数说明

params: Map<String, String>

    public Request.Payload createPayloadOfChainConfigConsensusExtUpdate(Map<String, byte[]> params, long rpcCallTimeout)

3.20 添加共识扩展字段待签名payload生成

参数说明

keys: 待删除字段

    public Request.Payload createPayloadOfChainConfigConsensusExtDelete(String[] keys, long rpcCallTimeout)

3.21 添加信任成员证书待签名payload生成

参数说明

trustMemberOrgId: 组织Id
trustMemberNodeId: 节点Id
trustMemberRole: 成员角色
trustMemberInfo: 成员信息内容

    public Request.Payload createChainConfigTrustMemberAddPayload(String trustMemberOrgId, String trustMemberNodeId, String trustMemberRole,
                                                                      String trustMemberInfo, long rpcCallTimeout)

3.22 删除信任成员证书待签名payload生成

参数说明

trustMemberInfo: 成员信息内容

     public Request.Payload createChainConfigTrustMemberAddPayload(String trustMemberInfo, long rpcCallTimeout)

3.23 发送链配置更新请求

    public ResultOuterClass.TxResponse updateChainConfig(Request.Payload payload, Request.EndorsementEntry[] endorsementEntries,
                                              long rpcCallTimeout, long syncResultTimeout)

4 证书管理接口

4.1 用户证书添加

参数说明

rpcCallTimeout: 发送rpc请求的超时时间

    public ResultOuterClass.TxResponse addCert(long rpcCallTimeout) 

4.2 用户证书删除

参数说明

payload: 合约内容
endorsementEntries: 带签名的合约内容

    public ResultOuterClass.TxResponse deleteCert(Request.Payload payload, Request.EndorsementEntry[] endorsementEntries,
                                                      long rpcCallTimeout, long syncResultTimeout)

4.3 用户证书冻结

参数说明

payload: 证书冻结的payload
endorsementEntries: 多签信息

   ResultOuterClass.TxResponse freezeCerts(Request.Payload payload, Request.EndorsementEntry[] endorsementEntries,
                                                      long rpcCallTimeout, long syncResultTimeout)

4.4 用户证书解冻

参数说明

payload: 证书冻结的payload
endorsementEntries: 多签信息

   public ResultOuterClass.TxResponse unfreezeCerts(Request.Payload payload, Request.EndorsementEntry[] endorsementEntries,
                                                      long rpcCallTimeout, long syncResultTimeout)

4.5 用户证书吊销

参数说明

payload: 证书冻结的payload
endorsementEntries: 多签信息

 public ResultOuterClass.TxResponse revokeCerts(Request.Payload payload, Request.EndorsementEntry[] endorsementEntries,
                                                     long rpcCallTimeout, long syncResultTimeout)

4.6 冻结证书payload

参数说明

certHashes: 冻结证书列表

    public Request.Payload createCertFreezePayload(String[] certHashes)

4.7 解冻证书payload

参数说明

certHashes: 冻结证书列表

    public Request.Payload createPayloadOfUnfreezeCerts(String[] certHashes)

4.8 吊销证书

参数说明

certCrl: 证书吊销crl

    public Request.Payload createPayloadOfRevokeCerts(String certCrl)

4.9 用户证书查询

参数说明

certHashes: 证书Hash列表

    public ResultOuterClass.CertInfos queryCert(String[] certHashes, long rpcCallTimeout)

5 消息订阅接口

5.1 区块订阅

参数说明

startBlock: 订阅起始区块高度，若为-1，表示订阅实时最新区块
endBlock: 订阅结束区块高度，若为-1，表示订阅实时最新区块
withRwSet: 是否返回读写集
onlyHeader: 是否只返回区块头

    public void subscribeBlock(long startBlock, long endBlock, boolean withRwSet, boolean onlyHeader,
                                   StreamObserver<ResultOuterClass.SubscribeResult> blockStreamObserver)

5.2 交易订阅

参数说明

startBlock: 订阅起始区块高度，若为-1，表示订阅实时最新区块
endBlock: 订阅结束区块高度，若为-1，表示订阅实时最新区块
txType: 订阅交易类型,若为pb.TxType(-1)，表示订阅所有交易类型
txIds: 订阅txId列表，若为空，表示订阅所有txId

    public void subscribeTx(long startBlock, long endBlock, String contractName, String[] txIds,
                                StreamObserver<ResultOuterClass.SubscribeResult> txStreamObserver)

5.3 事件订阅

参数说明

topic: 订阅话题
contractName: 订阅合约名

    public void subscribeContractEvent(String topic, String contractName,
                                          StreamObserver<ResultOuterClass.SubscribeResult> contractEventStreamObserver)

6 归档类接口

6.1 数据归档payload生成

参数说明

targetBlockHeight: 归档区块高度

    public Request.Payload createArchiveBlockPayload(long targetBlockHeight)

6.2 归档恢复payload生成

参数说明

payload: 归档恢复payload

    public ResultOuterClass.TxResponse sendRestoreBlockRequest(Request.Payload payload, long timeout)

6.3 发送数据归档请求

参数说明

payload: 数据归档payload

    public ResultOuterClass.TxResponse sendArchiveBlockRequest(Request.Payload payload, long timeout)

6.4 发送归档恢复请求

参数说明

payloadBytes: 归档恢复payload

    public ResponseInfo sendRestoreBlockRequest(byte[] payloadBytes, long timeout) 
            throws ChainMakerCryptoSuiteException, ChainClientException {
    }

6.5 获取归档数据

参数说明

targetBlockHeight: 归档区块高度

    public Store.BlockWithRWSet getArchivedFullBlockByHeight(long blockHeight) 
            throws InvalidProtocolBufferException, SQLException, ClassNotFoundException {
    }

6.6 获取归档区块信息

参数说明

targetBlockHeight: 归档区块高度
withRWSet: 是否获取读写集

    public ChainmakerBlock.BlockInfo getArchivedBlockByHeight(long blockHeight, boolean withRWSet) 
            throws InvalidProtocolBufferException, SQLException, ClassNotFoundException {
    }

7 管理类接口

7.1 SDK停止接口：关闭连接池连接，释放资源

public void stop()

使用过程

客户端使用SDK的过程如下：

创建SdkConfig对象
获取ChainManager对象
使用ChainManager获取或创建链对象，创建ChainClient时需要将SdkConfig对象作为参数传入
调用ChainClient对象的接口进行操作

使用示例

初始化，创建ChainClient

   public void init() {
       Yaml yaml = new Yaml();
       InputStream in = TestBase.class.getClassLoader().getResourceAsStream(SDK_CONFIG);

       SdkConfig sdkConfig;
       sdkConfig = yaml.loadAs(in, SdkConfig.class);
       assert in != null;
       in.close();

       for (NodeConfig nodeConfig : sdkConfig.getChain_client().getNodes()) {
           List<byte[]> tlsCaCertList = new ArrayList<>();
           for (String rootPath : nodeConfig.getTrustRootPaths()){
               List<String> filePathList = FileUtils.getFilesByPath(rootPath);
               for (String filePath : filePathList) {
                   tlsCaCertList.add(FileUtils.getFileBytes(filePath));
               }
           }
           byte[][] tlsCaCerts = new byte[tlsCaCertList.size()][];
           tlsCaCertList.toArray(tlsCaCerts);
           nodeConfig.setTrustRootBytes(tlsCaCerts);
       }

       chainManager = ChainManager.getInstance();
       chainClient = chainManager.getChainClient(sdkConfig.getChain_client().getChainId());

       if (chainClient == null) {
           chainClient = chainManager.createChainClient(sdkConfig);
       }
   }

创建合约

   public void testCreateContract() throws IOException, InterruptedException, ExecutionException, TimeoutException {
       byte[] byteCode = FileUtils.getResourceFileBytes(CONTRACT_FILE_PATH);
   
       // 1. create payload
       byte[] payload = chainClient.createPayloadOfContractCreation(CONTRACT_NAME,
               "1", Contract.RuntimeType.WASMER_RUST, null, byteCode);
   
       // 2. create payloads with endorsement
       byte[] payloadWithEndorsement1 = chainClient.signPayloadOfContractMgmt(payload);
   
       // 3. merge endorsements using payloadsWithEndorsement
       byte[][] payloadsWithEndorsement = new byte[1][];
       payloadsWithEndorsement[0] = payloadWithEndorsement1;
       byte[] payloadWithEndorsement = chainClient.mergeSignedPayloadsOfContractMgmt(payloadsWithEndorsement);
   
       // 4. create contract
       ResponseInfo responseInfo = chainClient.createContract(payloadWithEndorsement, 5000, 5000);
   }

调用合约

   public void testInvokeContract() throws Exception {
       ResultOuterClass.TxResponse responseInfo = null;
       try {
           responseInfo = chainClient.invokeContract(CONTRACT_NAME, INVOKE_CONTRACT_METHOD,
                   null, null, rpcCallTimeout, syncResultTimeout);
       } catch (Exception e) {
           e.printStackTrace();
           Assert.fail(e.getMessage());
       }
       Assert.assertNotNull(responseInfo);
   }

SDK Jar包引用方式

编译

git clone -b v2.0.0 https://git.chainmaker.org.cn/chainmaker/chainmaker-sdk-java.git
// 说明：需要使用openjdk 1.8.151+并提前安装gradle，也可以使用intelliJ IDEA打开项目进行编译
cd chainamker-sdk-java
./gradlew build

使用

导入Jar包，这里使用IntelliJ为示例引用Jar包，将编译好的jar包拷贝到需要使用sdk的项目下（一般可以在项目下建一个libs目录），然后打开IntelliJ IDEA->File->Project Structures，如下图点击“+”号，选择JARs or Directories，选中Jar包点击open即可。

引用

在要使用sdk的源文件里使用import引用sdk包，如下：
```
import org.chainmaker.sdk.*;
```