1. Go SDK 使用说明

1.1. 长安链SDK概述

整体介绍

长安链SDK是业务模块与长安链交互的桥梁，支持双向TLS认证，提供安全可靠的加密通信信道。

长安链提供了多种语言的SDK，包括：Go SDK、Java SDK、Python SDK、Nodejs SDK方便开发者根据需要进行选用。

提供的SDK接口，覆盖合约管理、链配置管理、证书管理、多签收集、各类查询操作、事件订阅等场景，满足了不同的业务场景需要。

名词概念说明

Node（节点）：代表一个链节点的基本信息，包括：节点地址、连接数、是否启用TLS认证等信息
ChainClient（链客户端）：所有客户端对链节点的操作接口都来自ChainClient
压缩证书：可以为ChainClient开启证书压缩功能，开启后可以减小交易包大小，提升处理性能

1.2. 环境准备

1.2.1. 软件环境依赖

golang ：版本为1.16或以上

下载地址：https://golang.org/dl/

若已安装，请通过命令查看版本：

$ go version
go version go1.16 linux/amd64

1.2.2. 下载安装sdk

进入您的Go项目，执行以下命令添加对sdk的引用：

go get chainmaker.org/chainmaker/sdk-go/v2@v2.3.1

1.2.3. 长安链环境准备

创建一条证书模式的长安链，并确保相关节点网络通畅，相关教程见：

1.3. 怎么使用SDK

1.3.1. 示例代码

1.3.1.1. 创建节点

设置节点信息，可用作创建与该节点连接的客户端

// 创建节点
func createNode(nodeAddr string, connCnt int) *NodeConfig {
 node := NewNodeConfig(
  // 节点地址，格式：127.0.0.1:12301
  WithNodeAddr(nodeAddr),
  // 节点连接数
  WithNodeConnCnt(connCnt),
  // 节点是否启用TLS认证
  WithNodeUseTLS(true),
  // 根证书路径，支持多个
  WithNodeCAPaths(caPaths),
  // TLS Hostname
  WithNodeTLSHostName(tlsHostName),
 )

 return node
}

1.3.1.2. 以参数形式创建ChainClient

更多内容请参看：sdk_client_test.go

注：示例中证书采用路径方式去设置，也可以使用证书内容去设置，具体请参看createClientWithCaCerts方法

// 创建ChainClient
func createClient() (*ChainClient, error) {
 if node1 == nil {
  // 创建节点1
  node1 = createNode(nodeAddr1, connCnt1)
 }

 if node2 == nil {
  // 创建节点2
  node2 = createNode(nodeAddr2, connCnt2)
 }

 chainClient, err := NewChainClient(
  // 设置归属组织
  WithChainClientOrgId(chainOrgId),
  // 设置链ID
  WithChainClientChainId(chainId),
  // 设置logger句柄，若不设置，将采用默认日志文件输出日志
  WithChainClientLogger(getDefaultLogger()),
  // 设置客户端用户私钥路径
  WithUserKeyFilePath(userKeyPath),
  // 设置客户端用户证书
  WithUserCrtFilePath(userCrtPath),
  // 添加节点1
  AddChainClientNodeConfig(node1),
  // 添加节点2
  AddChainClientNodeConfig(node2),
  )

 if err != nil {
  return nil, err
 }

 //启用证书压缩（开启证书压缩可以减小交易包大小，提升处理性能）
 err = chainClient.EnableCertHash()
 if err != nil {
  log.Fatal(err)
 }

 return chainClient, nil
}

1.3.1.3. 以配置文件形式创建ChainClient

注：参数形式和配置文件形式两个可以同时使用，同时配置时，以参数传入为准

func createClientWithConfig() (*ChainClient, error) {

 chainClient, err := NewChainClient(
  WithConfPath("./testdata/sdk_config.yml"),
 )

 if err != nil {
  return nil, err
 }

 //启用证书压缩（开启证书压缩可以减小交易包大小，提升处理性能）
 err = chainClient.EnableCertHash()
 if err != nil {
  return nil, err
 }

 return chainClient, nil
}

1.3.1.4. 部署wasm合约

下文，将演示通过sdk部署wasm合约，

sdk_user_contract_claim_test.go

func testUserContractClaimCreate(t *testing.T, client *ChainClient,
 admin1, admin2, admin3, admin4 *ChainClient, withSyncResult bool, isIgnoreSameContract bool) {

 resp, err := createUserContract(client, admin1, admin2, admin3, admin4,
  claimContractName, claimVersion, claimByteCodePath, common.RuntimeType_WASMER, []*common.KeyValuePair{}, withSyncResult)
 if !isIgnoreSameContract {
  require.Nil(t, err)
 }

 fmt.Printf("CREATE claim contract resp: %+v\n", resp)
}

func createUserContract(client *ChainClient, admin1, admin2, admin3, admin4 *ChainClient,
 contractName, version, byteCodePath string, runtime common.RuntimeType, kvs []*common.KeyValuePair, withSyncResult bool) (*common.TxResponse, error) {

 payloadBytes, err := client.CreateContractCreatePayload(contractName, version, byteCodePath, runtime, kvs)
 if err != nil {
  return nil, err
 }

 // 各组织Admin权限用户签名
 signedPayloadBytes1, err := admin1.SignContractManagePayload(payloadBytes)
 if err != nil {
  return nil, err
 }

 signedPayloadBytes2, err := admin2.SignContractManagePayload(payloadBytes)
 if err != nil {
  return nil, err
 }

 signedPayloadBytes3, err := admin3.SignContractManagePayload(payloadBytes)
 if err != nil {
  return nil, err
 }

 signedPayloadBytes4, err := admin4.SignContractManagePayload(payloadBytes)
 if err != nil {
  return nil, err
 }

 // 收集并合并签名
 mergeSignedPayloadBytes, err := client.MergeContractManageSignedPayload([][]byte{signedPayloadBytes1,
  signedPayloadBytes2, signedPayloadBytes3, signedPayloadBytes4})
 if err != nil {
  return nil, err
 }

 // 发送创建合约请求
 resp, err := client.SendContractManageRequest(mergeSignedPayloadBytes, createContractTimeout, withSyncResult)
 if err != nil {
  return nil, err
 }

 err = checkProposalRequestResp(resp, true)
 if err != nil {
  return nil, err
 }

 return resp, nil

1.3.1.5. 调用wasm合约

下文，将演示通过sdk调用wasm合约，

sdk_user_contract_claim_test.go

func testUserContractClaimInvoke(client *ChainClient,
 method string, withSyncResult bool) (string, error) {

 curTime := fmt.Sprintf("%d", CurrentTimeMillisSeconds())
 fileHash := uuid.GetUUID()
 params := map[string]string{
  "time":      curTime,
  "file_hash": fileHash,
  "file_name": fmt.Sprintf("file_%s", curTime),
 }

 err := invokeUserContract(client, claimContractName, method, "", params, withSyncResult)
 if err != nil {
  return "", err
 }

 return fileHash, nil
}

func invokeUserContract(client *ChainClient, contractName, method, txId string, params map[string]string, withSyncResult bool) error {

 resp, err := client.InvokeContract(contractName, method, txId, params, -1, withSyncResult)
 if err != nil {
  return err
 }

 if resp.Code != common.TxStatusCode_SUCCESS {
  return fmt.Errorf("invoke contract failed, [code:%d]/[msg:%s]\n", resp.Code, resp.Message)
 }

 if !withSyncResult {
  fmt.Printf("invoke contract success, resp: [code:%d]/[msg:%s]/[txId:%s]\n", resp.Code, resp.Message, resp.ContractResult.Result)
 } else {
  fmt.Printf("invoke contract success, resp: [code:%d]/[msg:%s]/[contractResult:%s]\n", resp.Code, resp.Message, resp.ContractResult)
 }

 return nil
}

1.3.1.6. 创建及调用evm合约

sdk-go/examples/user_contract_evm_balance/main.go(https://git.chainmaker.org.cn/chainmaker/sdk-go/-/blob/master/examples/user_contract_evm_balance/main.go)

1.3.2. 更多示例和用法

更多示例和用法，请参看单元测试用例

功能	单测代码
用户合约	`sdk_user_contract_test.go`
系统合约	`sdk_system_contract_test.go`
链配置	`sdk_chain_config_test.go`
证书管理	`sdk_cert_manage_test.go`
消息订阅	`sdk_subscribe_test.go`

1.4. 接口说明

请参看：《chainmaker-go-sdk》

1.4.1. 用户合约接口

1.4.1.1. 创建合约待签名payload生成

参数说明

contractName: 合约名
version: 版本号
byteCodeStringOrFilePath: 支持传入合约二进制文件路径或Hex或Base64编码的string
runtime: 合约运行环境
kvs: 合约初始化参数

 CreateContractCreatePayload(contractName, version, byteCodeStringOrFilePath string, runtime common.RuntimeType,
  kvs []*common.KeyValuePair) (*common.Payload, error)

1.4.1.2. 升级合约待签名payload生成

参数说明

contractName: 合约名
version: 版本号
byteCodeStringOrFilePath: 支持传入合约二进制文件路径或Hex或Base64编码的string
runtime: 合约运行环境
kvs: 合约升级参数

 CreateContractUpgradePayload(contractName, version, byteCodeStringOrFilePath string, runtime common.RuntimeType,
  kvs []*common.KeyValuePair) (*common.Payload, error)

1.4.1.3. 冻结合约payload生成

参数说明

contractName: 合约名

 CreateContractFreezePayload(contractName string) (*common.Payload, error)

1.4.1.4. 解冻合约payload生成

参数说明

contractName: 合约名

 CreateContractUnfreezePayload(contractName string) (*common.Payload, error)

1.4.1.5. 吊销合约payload生成

参数说明

contractName: 合约名

 CreateContractRevokePayload(contractName string) (*common.Payload, error)

1.4.1.6. 合约管理获取Payload签名

参数说明

payload: 待签名payload

 SignContractManagePayload(payload *common.Payload) (*common.EndorsementEntry, error)

1.4.1.7. 发送合约管理请求（创建、更新、冻结、解冻、吊销）

参数说明

payload: 交易payload
endorsers: 背书签名信息列表
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果

 SendContractManageRequest(payload *common.Payload, endorsers []*common.EndorsementEntry, timeout int64,
  withSyncResult bool) (*common.TxResponse, error)

1.4.1.8. 合约调用

参数说明

contractName: 合约名称
method: 合约方法
txId: 交易ID 格式要求：长度为64字节，字符在a-z0-9 可为空，若为空字符串，将自动生成txId
kvs: 合约参数
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果
limit: transaction limitation，执行交易时的资源消耗上限，设为nil则不设置上限

 InvokeContract(contractName, method, txId string, kvs []*common.KeyValuePair, timeout int64,
  withSyncResult bool) (*common.TxResponse, error)
 InvokeContractWithLimit(contractName, method, txId string, kvs []*common.KeyValuePair, timeout int64,
  withSyncResult bool, limit *common.Limit) (*common.TxResponse, error)

1.4.1.9. 合约查询接口调用

参数说明

contractName: 合约名称
method: 合约方法
kvs: 合约参数
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s

 QueryContract(contractName, method string, kvs []*common.KeyValuePair, timeout int64) (*common.TxResponse, error)

1.4.1.10. 构造待发送交易体

参数说明

contractName: 合约名称
method: 合约方法
txId: 交易ID 格式要求：长度为64字节，字符在a-z0-9 可为空，若为空字符串，将自动生成txId
kvs: 合约参数

 GetTxRequest(contractName, method, txId string, kvs []*common.KeyValuePair) (*common.TxRequest, error)

1.4.1.11. 发送已构造好的交易体

参数说明

txRequest: 已构造好的交易体
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果

 SendTxRequest(txRequest *common.TxRequest, timeout int64, withSyncResult bool) (*common.TxResponse, error)

1.4.2. 系统合约接口

1.4.2.1. 根据交易Id查询交易

参数说明

txId: 交易ID

 GetTxByTxId(txId string) (*common.TransactionInfo, error)

1.4.2.2. 根据交易Id查询包含rwset的交易

参数说明

txId: 交易ID

 GetTxWithRWSetByTxId(txId string) (*common.TransactionInfoWithRWSet, error)

1.4.2.3. 根据区块高度查询区块

参数说明

blockHeight: 指定区块高度，若为-1，将返回最新区块
withRWSet: 是否返回读写集

 GetBlockByHeight(blockHeight uint64, withRWSet bool) (*common.BlockInfo, error)

1.4.2.4. 根据区块高度查询完整区块

参数说明

blockHeight: 指定区块高度，若为-1，将返回最新区块

 GetFullBlockByHeight(blockHeight uint64) (*store.BlockWithRWSet, error)

1.4.2.5. 根据区块哈希查询区块

参数说明

blockHash: 指定区块Hash
withRWSet: 是否返回读写集

 GetBlockByHash(blockHash string, withRWSet bool) (*common.BlockInfo, error)

1.4.2.6. 根据交易Id查询区块

参数说明

txId: 交易ID
withRWSet: 是否返回读写集

 GetBlockByTxId(txId string, withRWSet bool) (*common.BlockInfo, error)

1.4.2.7. 查询最新的配置块

参数说明

withRWSet: 是否返回读写集

 GetLastConfigBlock(withRWSet bool) (*common.BlockInfo, error)

1.4.2.8. 查询最新区块

参数说明

withRWSet: 是否返回读写集

 GetLastBlock(withRWSet bool) (*common.BlockInfo, error)

1.4.2.9. 查询节点加入的链信息

返回ChainId清单

 GetNodeChainList() (*discovery.ChainList, error)

1.4.2.10. 查询链信息

包括：当前链最新高度，链节点信息

 GetChainInfo() (*discovery.ChainInfo, error)

1.4.2.11. 根据交易Id获取区块高度

参数说明

txId: 交易ID

 GetBlockHeightByTxId(txId string) (uint64, error)

1.4.2.12. 根据区块Hash获取区块高度

参数说明

blockHash: 指定区块Hash

 GetBlockHeightByHash(blockHash string) (uint64, error)

1.4.2.13. 查询当前最新区块高度

 GetCurrentBlockHeight() (uint64, error)

1.4.2.14. 根据区块高度查询区块头

参数说明

blockHeight: 指定区块高度，若为-1，将返回最新区块头

 GetBlockHeaderByHeight(blockHeight uint64) (*common.BlockHeader, error)

1.4.2.15. 系统合约调用

参数说明

contractName: 合约名称
method: 合约方法
txId: 交易ID 格式要求：长度为64字节，字符在a-z0-9 可为空，若为空字符串，将自动生成txId
kvs: 合约参数
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果

 InvokeSystemContract(contractName, method, txId string, kvs []*common.KeyValuePair, timeout int64,
  withSyncResult bool) (*common.TxResponse, error)

1.4.2.16. 系统合约查询接口调用

参数说明

contractName: 合约名称
method: 合约方法
kvs: 合约参数
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s

 QuerySystemContract(contractName, method string, kvs []*common.KeyValuePair, timeout int64) (*common.TxResponse, error)

1.4.2.17. 根据交易Id获取Merkle路径

参数说明

txId: 交易ID

 GetMerklePathByTxId(txId string) ([]byte, error)

1.4.2.18. 开放系统合约

参数说明

grantContractList: 需要开放的系统合约字符串数组

 CreateNativeContractAccessGrantPayload(grantContractList []string) (*common.Payload, error)

1.4.2.19. 弃用系统合约

参数说明

revokeContractList: 需要弃用的系统合约字符串数组

 CreateNativeContractAccessRevokePayload(revokeContractList []string) (*common.Payload, error)

1.4.2.20. 查询指定合约的信息，包括系统合约和用户合约

参数说明

contractName: 指定查询的合约名字，包括系统合约和用户合约

 GetContractInfo(contractName string) (*common.Contract, error)

1.4.2.21. 查询所有的合约名单，包括系统合约和用户合约

返回值说明

[]*common.Contract: 链上所有的合约列表，包括系统合约和用户合约

 GetContractList() ([]*common.Contract, error)

1.4.2.22. 查询已禁用的系统合约名单

返回值说明

[]string: 链上已禁用的系统合约名字列表

 GetDisabledNativeContractList() ([]string, error)

1.4.3. 链配置接口

1.4.3.1. 查询最新链配置

 GetChainConfig() (*config.ChainConfig, error)

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

参数说明

blockHeight: 指定区块高度如果当前区块就是配置块，直接返回当前区块的链配置

 GetChainConfigByBlockHeight(blockHeight uint64) (*config.ChainConfig, error)

1.4.3.3. 查询最新链配置序号Sequence

用于链配置更新

 GetChainConfigSequence() (uint64, error)

1.4.3.4. 链配置更新获取Payload签名

参数说明

payload: 待签名payload

 SignChainConfigPayload(payload *common.Payload) (*common.EndorsementEntry, error)

1.4.3.5. 发送链配置更新请求

参数说明

payload: 待签名payload
endorsers: 背书签名信息列表
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果

 SendChainConfigUpdateRequest(payload *common.Payload, endorsers []*common.EndorsementEntry, timeout int64,
  withSyncResult bool) (*common.TxResponse, error)

以下CreateChainConfigXXXXXXPayload方法，用于生成链配置待签名payload，在进行多签收集后(需机构Admin权限账号签名)，用于链配置的更新

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

参数说明

txSchedulerTimeout: 交易调度器从交易池拿到交易后, 进行调度的时间，其值范围为(0, 60], 若设置为0，则抛出错误
txSchedulerValidateTimeout: 交易调度器从区块中拿到交易后, 进行验证的超时时间，其值范围为(0, 60], 若设置为0，则抛出错误

 CreateChainConfigCoreUpdatePayload(txSchedulerTimeout, txSchedulerValidateTimeout uint64) (*common.Payload, error)

1.4.3.7. 更新链配置的区块相关参数待签名payload生成

参数说明

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

 CreateChainConfigBlockUpdatePayload(txTimestampVerify bool, txTimeout, blockTxCapacity, blockSize,
  blockInterval, txParamterSize uint32) (*common.Payload, error)

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

参数说明

trustRootOrgId: 组织Id
trustRootCrt: 根证书

 CreateChainConfigTrustRootAddPayload(trustRootOrgId string, trustRootCrt []string) (*common.Payload, error)

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

参数说明

trustRootOrgId: 组织Id
trustRootCrt: 根证书

 CreateChainConfigTrustRootUpdatePayload(trustRootOrgId string, trustRootCrt []string) (*common.Payload, error)

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

参数说明

trustRootOrgId: 组织Id

 CreateChainConfigTrustRootDeletePayload(trustRootOrgId string) (*common.Payload, error)

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

参数说明

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

 CreateChainConfigTrustMemberAddPayload(trustMemberOrgId, trustMemberNodeId,
  trustMemberRole, trustMemberInfo string) (*common.Payload, error)

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

参数说明

trustMemberInfo: 成员信息内容

 CreateChainConfigTrustMemberDeletePayload(trustMemberInfo string) (*common.Payload, error)

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

参数说明

permissionResourceName: 权限名
policy: 权限规则

 CreateChainConfigPermissionAddPayload(permissionResourceName string,
  policy *accesscontrol.Policy) (*common.Payload, error)

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

参数说明

permissionResourceName: 权限名
policy: 权限规则

 CreateChainConfigPermissionUpdatePayload(permissionResourceName string,
  policy *accesscontrol.Policy) (*common.Payload, error)

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

参数说明

permissionResourceName: 权限名

 CreateChainConfigPermissionDeletePayload(permissionResourceName string) (*common.Payload, error)

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

参数说明

nodeOrgId: 节点组织Id
nodeIds: 节点Id

 CreateChainConfigConsensusNodeIdAddPayload(nodeOrgId string, nodeIds []string) (*common.Payload, error)

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

参数说明

nodeOrgId: 节点组织Id
nodeOldNodeId: 节点原Id
nodeNewNodeId: 节点新Id

 CreateChainConfigConsensusNodeIdUpdatePayload(nodeOrgId, nodeOldNodeId, nodeNewNodeId string) (*common.Payload, error)

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

参数说明

nodeOrgId: 节点组织Id
nodeId: 节点Id

 CreateChainConfigConsensusNodeIdDeletePayload(nodeOrgId, nodeId string) (*common.Payload, error)

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

参数说明

nodeOrgId: 节点组织Id
nodeIds: 节点Id

 CreateChainConfigConsensusNodeOrgAddPayload(nodeOrgId string, nodeIds []string) (*common.Payload, error)

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

参数说明

nodeOrgId: 节点组织Id
nodeIds: 节点Id

 CreateChainConfigConsensusNodeOrgUpdatePayload(nodeOrgId string, nodeIds []string) (*common.Payload, error)

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

参数说明

nodeOrgId: 节点组织Id

 CreateChainConfigConsensusNodeOrgDeletePayload(nodeOrgId string) (*common.Payload, error)

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

参数说明

kvs: 字段key、value对

 CreateChainConfigConsensusExtAddPayload(kvs []*common.KeyValuePair) (*common.Payload, error)

1.4.3.23. 更新共识扩展字段待签名payload生成

参数说明

kvs: 字段key、value对

 CreateChainConfigConsensusExtUpdatePayload(kvs []*common.KeyValuePair) (*common.Payload, error)

1.4.3.24. 删除共识扩展字段待签名payload生成

参数说明

keys: 待删除字段

 CreateChainConfigConsensusExtDeletePayload(keys []string) (*common.Payload, error)

1.4.3.25. 修改地址类型payload生成

参数说明

addrType: 地址类型，0-ChainMaker; 1-ZXL

 CreateChainConfigAlterAddrTypePayload(addrType string) (*common.Payload, error)

1.4.3.26. 启用或停用Gas计费开关payload生成

 CreateChainConfigEnableOrDisableGasPayload() (*common.Payload, error)

1.4.3.27. 开启或关闭链配置的Gas优化payload生成

 CreateChainConfigOptimizeChargeGasPayload(enable bool) (*common.Payload, error)

1.4.3.28. 查询最新权限配置列表

 GetChainConfigPermissionList() ([]*config.ResourcePolicy, error)

1.4.4. 证书管理接口

1.4.4.1. 用户证书添加

参数说明

在common.TxResponse.ContractResult.Result字段中返回成功添加的certHash

go AddCert() (*common.TxResponse, error)

1.4.4.2. 用户证书删除

参数说明

certHashes: 证书Hash列表

 DeleteCert(certHashes []string) (*common.TxResponse, error)

1.4.4.3. 用户证书查询

参数说明

certHashes: 证书Hash列表 返回值说明
*common.CertInfos: 包含证书Hash和证书内容的列表

 QueryCert(certHashes []string) (*common.CertInfos, error)

1.4.4.4. 获取用户证书哈希

 GetCertHash() ([]byte, error)

1.4.4.5. 生成证书管理操作Payload（三合一接口）

参数说明

method: CERTS_FROZEN(证书冻结)/CERTS_UNFROZEN(证书解冻)/CERTS_REVOCATION(证书吊销)
kvs: 证书管理操作参数

 CreateCertManagePayload(method string, kvs []*common.KeyValuePair) *common.Payload

1.4.4.6. 生成证书冻结操作Payload

参数说明

certs: X509证书列表

 CreateCertManageFrozenPayload(certs []string) *common.Payload

1.4.4.7. 生成证书解冻操作Payload

参数说明

certs: X509证书列表

 CreateCertManageUnfrozenPayload(certs []string) *common.Payload

1.4.4.8. 生成证书吊销操作Payload

参数说明

certs: X509证书列表

 CreateCertManageRevocationPayload(certCrl string) *common.Payload

1.4.4.9. 待签payload签名

一般需要使用具有管理员权限账号进行签名 参数说明

payload: 待签名payload

 SignCertManagePayload(payload *common.Payload) (*common.EndorsementEntry, error)

1.4.4.10. 发送证书管理请求（证书冻结、解冻、吊销）

参数说明

payload: 交易payload
endorsers: 背书签名信息列表
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果

 SendCertManageRequest(payload *common.Payload, endorsers []*common.EndorsementEntry, timeout int64,
  withSyncResult bool) (*common.TxResponse, error)

1.4.5. 消息订阅接口

1.4.5.1. 区块订阅

参数说明

startBlock: 订阅起始区块高度，若为-1，表示订阅实时最新区块
endBlock: 订阅结束区块高度，若为-1，表示订阅实时最新区块
withRwSet: 是否返回读写集
onlyHeader: 若设置为true，将忽略withRwSet选项，仅返回区块头（common.BlockHeader）,若设置为false，将返回common.BlockInfo

 SubscribeBlock(ctx context.Context, startBlock, endBlock int64, withRWSet, onlyHeader bool) (<-chan interface{}, error)

1.4.5.2. 交易订阅

参数说明

startBlock: 订阅起始区块高度，若为-1，表示订阅实时最新区块
endBlock: 订阅结束区块高度，若为-1，表示订阅实时最新区块
contractName ：指定订阅指定合约的交易，可以传用户合约名称或系统合约名称，若为空，表示订阅所有合约的交易
txIds: 订阅txId列表，若为空，表示订阅所有txId

 SubscribeTx(ctx context.Context, startBlock, endBlock int64, contractName string,
  txIds []string) (<-chan interface{}, error)

1.4.5.3. 合约事件订阅

参数说明

startBlock: 订阅起始区块高度，若为-1，表示订阅实时最新区块
endBlock: 订阅结束区块高度，若为-1，表示订阅实时最新区块
contractName ：指定订阅的合约名称
topic ：指定订阅主题

 SubscribeContractEvent(ctx context.Context, startBlock, endBlock int64, contractName,
  topic string) (<-chan interface{}, error)

1.4.5.4. 多合一订阅

参数说明

txType: 订阅交易类型，目前已支持：区块消息订阅(common.TxType_SUBSCRIBE_BLOCK_INFO)、交易消息订阅(common.TxType_SUBSCRIBE_TX_INFO)
payloadBytes: 消息订阅参数payload

 Subscribe(ctx context.Context, payloadBytes *common.Payload) (<-chan interface{}, error)

1.4.6. 证书压缩

开启证书压缩可以减小交易包大小，提升处理性能

1.4.6.1. 启用压缩证书功能

 EnableCertHash() error

1.4.6.2. 停用压缩证书功能

 DisableCertHash() error

1.4.7. 层级属性加密类接口

注意：层级属性加密模块 Id 使用 / 作为分隔符，例如： Org1/Ou1/Member1

1.4.7.1. 生成层级属性参数初始化交易 payload

参数说明

orgId: 参与方组织 id
hibeParams: 传入序列化后的hibeParams byte数组

 CreateHibeInitParamsTxPayloadParams(orgId string, hibeParams []byte) ([]*common.KeyValuePair, error)

1.4.7.2. 生成层级属性加密交易 payload，加密参数已知

参数说明

plaintext: 待加密交易消息明文
receiverIds: 消息接收者 id 列表，需和 paramsList 一一对应
paramsBytesList: 消息接收者对应的加密参数，需和 receiverIds 一一对应
txId: 以交易 Id 作为链上存储 hibeMsg 的 Key, 如果不提供存储的信息可能被覆盖
keyType: 对明文进行对称加密的方法，请传入 common 中 crypto 包提供的方法，目前提供AES和SM4两种方法

 CreateHibeTxPayloadParamsWithHibeParams(plaintext []byte, receiverIds []string, paramsBytesList [][]byte, txId string,
  keyType crypto.KeyType) ([]*common.KeyValuePair, error)

1.4.7.3. 生成层级属性加密交易 payload，参数由链上查询得出

参数说明

contractName: 合约名
queryParamsMethod: 链上查询 hibe.Params 的合约方法
plaintext: 待加密交易消息明文
receiverIds: 消息接收者 id 列表，需和 paramsList 一一对应
paramsList: 消息接收者对应的加密参数，需和 receiverIds 一一对应
receiverOrgIds: 链上查询 hibe Params 的 Key 列表，需要和 receiverIds 一一对应
txId: 以交易 Id 作为链上存储 hibeMsg 的 Key, 如果不提供存储的信息可能被覆盖
keyType: 对明文进行对称加密的方法，请传入 common 中 crypto 包提供的方法，目前提供AES和SM4两种方法
timeout: （内部查询 HibeParams 的）超时时间，单位：s，若传入-1，将使用默认超时时间：10s

 CreateHibeTxPayloadParamsWithoutHibeParams(contractName, queryParamsMethod string, plaintext []byte,
  receiverIds []string, receiverOrgIds []string, txId string, keyType crypto.KeyType,
  timeout int64) ([]*common.KeyValuePair, error)

1.4.7.4. 查询某一组织的加密公共参数，返回其序列化后的byte数组

参数说明

contractName: 合约名
method: 查询的合约方法名
orgId: 参与方 id
timeout: 查询超时时间，单位：s，若传入-1，将使用默认超时时间：10s

 QueryHibeParamsWithOrgId(contractName, method, orgId string, timeout int64) ([]byte, error)

1.4.7.5. 已知交易id，根据私钥解密密文交易

参数说明

localId: 本地层级属性加密 id
hibeParams: hibeParams 序列化后的byte数组
hibePrivKey: hibe私钥序列化后的byte数组
txId: 层级属性加密交易 id
keyType: 对加密信息进行对称解密的方法，请和加密时使用的方法保持一致，请传入 common 中 crypto 包提供的方法，目前提供AES和SM4两种方法

 DecryptHibeTxByTxId(localId string, hibeParams []byte, hibePrvKey []byte, txId string,
  keyType crypto.KeyType) ([]byte, error)

1.4.8. 数据归档接口

（注意：请使用归档工具cmc进行归档操作，以下接口是归档原子接口，并不包括归档完整流程）

1.4.8.1. 获取已归档区块高度

参数说明

输出已归档的区块高度

 GetArchivedBlockHeight() (uint64, error)

1.4.8.2. 构造数据归档区块Payload

参数说明

targetBlockHeight: 归档目标区块高度

 CreateArchiveBlockPayload(targetBlockHeight uint64) (*common.Payload, error)

1.4.8.3. 构造归档数据恢复Payload

参数说明

fullBlock: 完整区块数据（对应结构：store.BlockWithRWSet）

 CreateRestoreBlockPayload(fullBlock []byte) (*common.Payload, error)

1.4.8.4. 获取归档操作Payload签名

参数说明

payload: 指向payload对象的指针

 SignArchivePayload(payload *common.Payload) (*common.Payload, error)

1.4.8.5. 发送归档请求

参数说明

payload: 指向payload对象的指针
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s

 SendArchiveBlockRequest(payload *common.Payload, timeout int64) (*common.TxResponse, error)

1.4.8.6. 归档数据恢复

参数说明

payload: 指向payload对象的指针
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s

 SendRestoreBlockRequest(payload *common.Payload, timeout int64) (*common.TxResponse, error)

1.4.8.7. 根据交易Id查询已归档交易

参数说明

txId: 交易ID

 GetArchivedTxByTxId(txId string) (*common.TransactionInfo, error)

1.4.8.8. 根据区块高度查询已归档区块

参数说明

blockHeight: 指定区块高度
withRWSet: 是否返回读写集

 GetArchivedBlockByHeight(blockHeight uint64, withRWSet bool) (*common.BlockInfo, error)

1.4.8.9. 根据区块高度查询已归档完整区块(包含：区块数据、读写集、合约事件日志)

参数说明

blockHeight: 指定区块高度

 GetArchivedFullBlockByHeight(blockHeight uint64) (*store.BlockWithRWSet, error)

1.4.8.10. 根据区块哈希查询已归档区块

参数说明

blockHash: 指定区块Hash
withRWSet: 是否返回读写集

 GetArchivedBlockByHash(blockHash string, withRWSet bool) (*common.BlockInfo, error)

1.4.8.11. 根据交易Id查询已归档区块

参数说明

txId: 交易ID
withRWSet: 是否返回读写集

 GetArchivedBlockByTxId(txId string, withRWSet bool) (*common.BlockInfo, error)

1.4.9. 隐私计算系统合约接口

1.4.9.1. 保存隐私合约计算结果，包括合约部署

参数说明

contractName: 合约名称
contractVersion: 合约版本号
isDeployment: 是否是部署合约
codeHash: 合约字节码hash值
reportHash: Enclave report hash值
result: 隐私合约执行结果
codeHeader: solodity合部署合约时合约字节码的header数据
txId: 交易Id
rwSet: 隐私合约执行产生的读写集
sign: Enclave对执行结果数据的结果签名
events: 合约执行产生的事件
privateReq: 用户调用隐私计算请求时的request序列化字节数组
withSyncResult: 是否同步返回调用结果
timeout: 发送交易的超时时间

 SaveData(contractName string, contractVersion string, isDeployment bool, codeHash []byte, reportHash []byte,
  result *common.ContractResult, codeHeader []byte, txId string, rwSet *common.TxRWSet, sign []byte,
  events *common.StrSlice, privateReq []byte, withSyncResult bool, timeout int64) (*common.TxResponse, error)

1.4.9.2. 保存远程证明

参数说明

proof: 远程证明
txId: 交易Id
withSyncResult: 是否同步返回调用结果
timeout: 交易发送超时时间

 SaveRemoteAttestationProof(proof, txId string, withSyncResult bool, timeout int64) (*common.TxResponse, error)

1.4.9.3. 构建上传Enclave CA证书的报文

参数说明

caCert: Enclave CA证书
txId: 交易Id

 CreateSaveEnclaveCACertPayload(caCert, txId string) (*common.Payload, error)

1.4.9.4. 获取Enclave CA证书

 GetEnclaveCACert() ([]byte, error)

1.4.9.5. 隐私计算调用者权限验证

参数说明

payload: 用户签名验证的payload内容
orgIds: 组织Id的slice，注意和signPairs里面SignInfo的证书顺序一致
signPairs: 用户多签的签名和证书slice

 CheckCallerCertAuth(payload string, orgIds []string, signPairs []*syscontract.SignInfo) (*common.TxResponse, error)

1.4.9.6. 获取Enclave的report

参数说明

enclaveId: Enclave的Id，当前固定为”global_enclave_id”

 GetEnclaveReport(enclaveId string) ([]byte, error)

1.4.9.7. 获取隐私证明材料

参数说明

enclaveId: Enclave的Id，当前固定为”global_enclave_id”

 GetEnclaveProof(enclaveId string) ([]byte, error)

1.4.9.8. 获取隐私合约计算结果

参数说明

contractName: 合约名称
key: 计算结果对应的键值

 GetData(contractName, key string) ([]byte, error)

1.4.9.9. 保存隐私目录

参数说明

orderId: 隐私目录的主键，供以后查询使用
txId: 交易ID
privateDir:
withSyncResult: 是否同步等待交易结果
timeout: 等待交易结果的超时时间

 SaveDir(orderId, txId string, privateDir *common.StrSlice, withSyncResult bool,
  timeout int64) (*common.TxResponse, error)

1.4.9.10. 获取用户部署的隐私合约

参数说明

contractName: 合约名称
codeHash: 代码哈希

 GetContract(contractName, codeHash string) (*common.PrivateGetContract, error)

1.4.9.11. 获取用户的隐私目录

参数说明

 GetDir(orderId string) ([]byte, error)

1.4.9.12. 构建上传隐私计算环境的report的报文

参数说明

enclaveId: 隐私计算环境的标识
report: 隐私计算环境的report
txId: 交易ID

 CreateSaveEnclaveReportPayload(enclaveId, report, txId string) (*common.Payload, error)

1.4.9.13. 获取隐私计算环境的加密公钥

参数说明

enclaveId: 隐私计算环境的标识

 GetEnclaveEncryptPubKey(enclaveId string) ([]byte, error)

1.4.9.14. 获取隐私计算环境的验签公钥

参数说明

enclaveId: 隐私计算环境的标识

 GetEnclaveVerificationPubKey(enclaveId string) ([]byte, error)

1.4.9.15. 获取隐私证明材料中的Challenge

参数说明

enclaveId: 隐私计算环境的标识

 GetEnclaveChallenge(enclaveId string) ([]byte, error)

1.4.9.16. 获取隐私证明材料中的Signature

参数说明

enclaveId: 隐私计算环境的标识

 GetEnclaveSignature(enclaveId string) ([]byte, error)

1.4.10. 系统类接口

1.4.10.1. SDK停止接口

关闭连接池连接，释放资源

 Stop() error

1.4.10.2. 获取链版本

 GetChainMakerServerVersion() (string, error)

1.4.11. 公钥身份类接口

1.4.11.1. 构造添加公钥身份请求

参数说明

pubkey: 公钥信息
orgId: 组织id
role: 角色，支持client,light,common

 CreatePubkeyAddPayload(pubkey string, orgId string, role string) (*common.Payload, error)

1.4.11.2. 构造删除公钥身份请求

参数说明

pubkey: 公钥信息
orgId: 组织id

 CreatePubkeyDelPayload(pubkey string, orgId string) (*common.Payload, error)

1.4.11.3. 构造查询公钥身份请求

参数说明

pubkey: 公钥信息

 CreatePubkeyQueryPayload(pubkey string) (*common.Payload, error)

1.4.11.4. 发送公钥身份管理请求（添加、删除）

参数说明

payload: 交易payload
endorsers: 背书签名信息列表
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果

 SendPubkeyManageRequest(payload *common.Payload, endorsers []*common.EndorsementEntry, timeout int64,
  withSyncResult bool) (*common.TxResponse, error)

1.4.12. 多签类接口

1.4.12.1. 发起多签请求

参数说明

payload: 待签名payload

 MultiSignContractReq(payload *common.Payload) (*common.TxResponse, error)

1.4.12.2. 发起多签投票

参数说明

payload: 待签名payload
endorser: 投票人对多签请求 payload 的签名信息
isAgree: 投票人对多签请求是否同意，true为同意，false则反对

 MultiSignContractVote(payload *common.Payload,
  endorser *common.EndorsementEntry, isAgree bool) (*common.TxResponse, error)

1.4.12.3. 根据txId查询多签状态

参数说明

txId: 需要查询的多签请求交易Id

 MultiSignContractQuery(txId string) (*common.TxResponse, error)

1.4.12.4. 根据发起多签请求所需的参数构建payload

参数说明

pairs: 发起多签请求所需的参数

 CreateMultiSignReqPayload(pairs []*common.KeyValuePair) *common.Payload

1.4.13. gas管理相关接口

1.4.13.1. 构造设置gas管理员payload

参数说明

address: gas管理员的地址

 CreateSetGasAdminPayload(address string) (*common.Payload, error)

1.4.13.2. 查询gas管理员

返回值说明

string: gas管理员的账号地址

 GetGasAdmin() (string, error)

1.4.13.3. 构造充值gas账户 payload

参数说明

rechargeGasList: 一个或多个gas账户充值指定gas数量

 CreateRechargeGasPayload(rechargeGasList []*syscontract.RechargeGas) (*common.Payload, error)

1.4.13.4. 查询gas账户余额

参数说明

address: 查询gas余额的账户地址

 GetGasBalance(address string) (int64, error)

1.4.13.5. 构造退还gas账户的gas payload

参数说明

address: 退还gas的账户地址
amount: 退还gas的数量

 CreateRefundGasPayload(address string, amount int64) (*common.Payload, error)

1.4.13.6. 构造冻结指定gas账户 payload

参数说明

address: 冻结指定gas账户的账户地址

 CreateFrozenGasAccountPayload(address string) (*common.Payload, error)

1.4.13.7. 构造解冻指定gas账户 payload

参数说明

address: 解冻指定gas账户的账户地址

 CreateUnfrozenGasAccountPayload(address string) (*common.Payload, error)

1.4.13.8. 查询gas账户的状态

参数说明

address: 解冻指定gas账户的账户地址 返回值说明
bool: true表示账号未被冻结，false表示账号已被冻结

 GetGasAccountStatus(address string) (bool, error)

1.4.13.9. 发送gas管理类请求

参数说明

payload: 交易payload
endorsers: 背书签名信息列表
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果

 SendGasManageRequest(payload *common.Payload, endorsers []*common.EndorsementEntry, timeout int64,
  withSyncResult bool) (*common.TxResponse, error)

1.4.13.10. 为payload添加gas limit

参数说明

payload: 交易payload
limit: transaction limitation，执行交易时的资源消耗上限

 AttachGasLimit(payload *common.Payload, limit *common.Limit) *common.Payload

1.4.13.11. 估算交易的gas消耗量

参数说明

payload: 待估算gas消耗量的交易payload 返回值说明
uint64: 估算出的gas消耗量

 EstimateGas(payload *common.Payload) (uint64, error)

1.4.13.12. 构造配置账户基础gas消耗数量 payload

参数说明

amount: 基础gas消耗数量

 CreateSetInvokeBaseGasPayload(amount int64) (*common.Payload, error)

1.4.14. 别名相关接口

1.4.14.1. 添加别名

 AddAlias() (*common.TxResponse, error)

1.4.14.2. 构造`更新别名的证书`payload

参数说明

alias: 带更新证书的别名
newCertPEM: 新的证书，此新证书将替换掉alias关联的证书

 CreateUpdateCertByAliasPayload(alias, newCertPEM string) *common.Payload

1.4.14.3. 签名`更新别名的证书`payload

参数说明

payload: 交易payload

 SignUpdateCertByAliasPayload(payload *common.Payload) (*common.EndorsementEntry, error)

1.4.14.4. 发起`更新别名的证书`交易

参数说明

payload: 交易payload
endorsers: 背书签名信息列表
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果

 UpdateCertByAlias(payload *common.Payload, endorsers []*common.EndorsementEntry,
  timeout int64, withSyncResult bool) (*common.TxResponse, error)

1.4.14.5. 查询别名详细信息

参数说明

aliases: 带查询的证书别名切片，根据这些别名查询返回AliasInfos

 QueryCertsAlias(aliases []string) (*common.AliasInfos, error)

1.4.14.6. 构造`删除别名`payload

参数说明

aliases: 带删除的证书别名切片

 CreateDeleteCertsAliasPayload(aliases []string) *common.Payload

1.4.14.7. 签名`删除别名`payload

参数说明

payload: 交易payload

 SignDeleteAliasPayload(payload *common.Payload) (*common.EndorsementEntry, error)

1.4.14.8. 发起`删除别名`交易

参数说明

payload: 交易payload
endorsers: 背书签名信息列表
timeout: 超时时间，单位：s，若传入-1，将使用默认超时时间：10s
withSyncResult: 是否同步获取交易执行结果当为true时，若成功调用，common.TxResponse.ContractResult.Result为common.TransactionInfo 当为false时，若成功调用，common.TxResponse.ContractResult为空，可以通过common.TxResponse.TxId查询交易结果

 DeleteCertsAlias(payload *common.Payload, endorsers []*common.EndorsementEntry,
  timeout int64, withSyncResult bool) (*common.TxResponse, error)

1.4.15. 交易池相关接口

1.4.15.1. 获取交易池状态

 GetPoolStatus() (*txpool.TxPoolStatus, error)

1.4.15.2. 获取不同交易类型和阶段中的交易Id列表

参数说明

txType: 交易类型在pb的txpool包中进行了定义
txStage: 交易阶段在pb的txpool包中进行了定义 返回值说明
[]string: 交易Id列表

 GetTxIdsByTypeAndStage(txType txpool.TxType, txStage txpool.TxStage) ([]string, error)

1.4.15.3. 根据txIds获取交易池中存在的txs，并返回交易池缺失的tx的txIds

参数说明

txIds: 交易Id列表 返回值说明
[]*common.Transaction: 交易池中存在的txs
[]string: 交易池缺失的tx的txIds

 GetTxsInPoolByTxIds(txIds []string) ([]*common.Transaction, []string, error)