ChainMaker Nodejs SDK 接口说明

概述

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

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

约定概念

  • Node(节点):代表一个链节点的基本信息,包括:节点地址、连接数、是否启用TLS认证等信息

  • ChainClient(链客户端):所有客户端对链节点的操作接口都来自ChainClient

  • 压缩证书:可以为ChainClient开启证书压缩功能,开启后可以减小交易包大小,提升处理性能

1 用户合约接口

1.1 创建合约待签名payload生成

类名

  • userContractMgr

参数说明

类型:k-v Object对象

  • contractName: 合约名(string)

  • contractVersion: 版本号(string)

  • runtimeType: 合约运行环境(number)

  • contractFilePath: 合约二进制文件路径(string)

  • params: 合约初始化参数,(k-v Object对象)

	createContractCreatePayload({ contractName, contractVersion, runtimeType, contractFilePath, params })

1.2 升级合约待签名payload生成

类名

  • userContractMgr

参数说明

类型:k-v Object对象

  • contractName: 合约名(string)

  • contractVersion: 版本号(string)

  • runtimeType: 合约运行环境(number)

  • contractFilePath: 合约二进制文件路径(string)

  • params: 合约升级参数,(k-v Object对象)

	createContractUpgradePayload({ contractName, contractVersion, runtimeType, contractFilePath, params })

1.3 冻结合约payload生成

类名

  • userContractMgr

参数说明

类型:k-v Object对象

  • contractName: 合约名(string)

	createContractFreezePayload({ contractName })

1.4 解冻合约payload生成

类名

  • userContractMgr

参数说明

类型:k-v Object对象

  • contractName: 合约名(string)

	createContractUnfreezePayload({ contractName })

1.5 吊销合约payload生成

类名

  • userContractMgr

参数说明

类型:k-v Object对象

  • contractName: 合约名(string)

	createContractRevokePayload({ contractName })

1.6 合约管理获取Payload签名

类名

  • userContractMgr

参数说明

  • payload: 待签名payload

  • userInfoList: 需要签名的用户列表(array[class UserInfo])

	signContractManagePayload(payload, userInfoList)

1.7 合约管理Payload签名收集&合并

类名

  • userContractMgr

参数说明

  • signedPayloadBytesArray: 已签名payload列表(array[payloadBytes])

	mergeContractManageSignedPayload(signedPayloadBytesArray)

1.8 发送合约管理请求(创建、更新、冻结、解冻、吊销)

类名

  • userContractMgr

参数说明

  • mergedPayload: 多签结果

	async sendContractManageRequest(mergedPayload)

1.9 合约调用

类名

  • callUserContract

参数说明

类型:k-v Object对象

  • contractName: 合约名称(string)

  • method: 合约方法(string)

  • params: 合约参数(k-v Object对象)

	async invokeUserContract({ contractName, method, params })

1.10 合约查询接口调用

类名

  • callUserContract

参数说明

类型:k-v Object对象

  • contractName: 合约名称(string)

  • method: 合约方法(string)

  • params: 合约参数(k-v Object对象)

	async queryContract({ contractName, method, params })

1.11 构造待发送交易体

类名

  • callUserContract

参数说明

  • contractName: 合约名称(string)

  • method: 合约方法(string)

  • params: 合约参数(k-v Object对象)

	getTxRequest(contractName, method, params)

1.12 发送已构造好的交易体

类名

  • callUserContract

参数说明

  • request: 已构造好的交易体

  • txId: getTxRequest方法的返回值

	async sendTxRequest(request, txId)

2 系统合约接口

2.1 根据交易Id查询交易

类名

  • callSystemContract

参数说明

  • txId: 交易ID(string)

  async getTxByTxId(txId)

2.2 根据区块高度查询区块

类名

  • callSystemContract

参数说明

  • blockHeight: 区块高度,若为-1,将返回最新区块(number)

  • withRWSet: 是否返回读写集(boolean)

  async getBlockByHeight(blockHeight, withRWSet)

2.3 根据区块哈希查询区块

类名

  • callSystemContract

参数说明

  • blockHash: 区块哈希(string)

  • withRWSet: 是否返回读写集(boolean)

  async getBlockByHash(blockHash, withRWSet)

2.4 根据交易Id查询区块

类名

  • callSystemContract

参数说明

  • txId: 交易ID(string)

  • withRWSet: 是否返回读写集(boolean)

  async getBlockByTxId(txId, withRWSet)

2.5 查询最新的配置块

类名

  • callSystemContract

参数说明

  • withRWSet: 是否返回读写集(boolean)

  async getLastConfigBlock(withRWSet)

2.6 查询节点加入的链信息

类名

  • callSystemContract

参数说明

  • nodeAddr: 节点地址,如127.0.0.1(string)

  async getNodeChainList(nodeAddr)

2.7 查询链信息

类名

  • callSystemContract

参数说明

  • 包括:当前链最新高度,链节点信息

  async getChainInfo()

2.8 根据交易Id获取区块高度

类名

  • callSystemContract

参数说明

  • txId: 交易ID(string)

  async getBlockHeightByTxId(txId)

2.9 根据区块Hash获取区块高度

类名

  • callSystemContract

参数说明

  • blockHash: 区块哈希(string)

  async getBlockHeightByHash(blockHash)

2.10 查询当前最新区块高度

类名

  • callSystemContract

参数说明

  • 返回当前最新区块高度

  async getCurrentBlockHeight()

2.11 根据区块高度查询区块头

类名

  • callSystemContract

参数说明

  • blockHeight: 区块高度(number)

  async getBlockHeaderByHeight(blockHeight)

2.12 查询最新区块

类名

  • callSystemContract

参数说明

  • withRWSet: 是否返回读写集(boolean)

  async getLastBlock(withRWSet)

2.13 根据区块高度查询完整区块

类名

  • callSystemContract

参数说明

  • blockHeight: 区块高度(number)

  async getFullBlockByHeight(blockHeight)

3 链配置接口

3.1 查询最新链配置

类名

  • chainConfig

  async getChainConfig()

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

类名

  • chainConfig

参数说明

  • blockHeight: 区块高度(number)

  async getChainConfigByBlockHeight(blockHeight)

3.3 查询最新链配置序号Sequence

类名

  • chainConfig

  async getChainConfigSequence()

3.4 链配置更新获取Payload签名

类名

  • chainConfig

参数说明

类型:k-v Object对象

  • payload: 待签名payload

  • userInfo: 需要签名的用户(class UserInfo)

  signChainConfigPayload(payload, userInfo)

3.5 链配置更新Payload签名收集&合并

类名

  • chainConfig

参数说明

  • signedPayloadBytesArray: 签名之后的payload bytes数组(Array[payloadBytes])

  mergeChainConfigSignedPayload(signedPayloadBytesArray)

3.6 发送链配置更新请求

类名

  • chainConfig

参数说明

  • signPayloadBytes: 签名之后的payload bytes

  async sendChainConfigUpdateRequest(signPayloadBytes)

3.7 更新Block模块待签名payload生成

类名

  • chainConfig

参数说明

类型:k-v Object对象

  • txTimestampVerify: 是否需要开启交易时间戳校验(boolean)

  • (以下参数,若无需修改,请置为-1)

  • txTimeout: 交易时间戳的过期时间(秒),其值范围为[600, +∞)(number)

  • blockTxCapacity: 区块中最大交易数,其值范围为(0, +∞](number)

  • blockSize: 区块最大限制,单位MB,其值范围为(0, +∞](number)

  • blockInterval: 出块间隔,单位:ms,其值范围为[10, +∞](number)

  async createChainConfigBlockUpdatePayload({txTimestampVerify, txTimeout = -1, blockTxCapacity = -1, blockSize = -1, blockInterval = -1, userInfoList})

3.8 更新Core模块待签名payload生成

类名

  • chainConfig

参数说明

类型:k-v Object对象

  • txSchedulerTimeout: 交易调度器从交易池拿到交易后, 进行调度的时间,其值范围为[0, 60],若无需修改,请置为-1(number)

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

  async ceateChainConfigCoreUpdatePayload({txSchedulerTimeout = -1, txSchedulerValidateTimeout = -1,  userInfoList,})

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

类名

  • chainConfig

参数说明

类型:k-v Object对象

  • orgId: 组织Id(string)

  • root: 根证书(string)

  async createChainConfigTrustRootAddPayload({ orgId, root })

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

类名

  • chainConfig

参数说明

类型:k-v Object对象

  • orgId: 组织Id(string)

  • root: 根证书(string)

  async createChainConfigTrustRootUpdatePayload({ orgId, root })

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

类名

  • chainConfig

参数说明

类型:k-v Object对象

  • orgId: 组织Id(string)

  async createChainConfigTrustRootDeletePayload({ orgId })

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

类名

  • chainConfig

参数说明

类型:k-v Object对象

  • permissionResourceName: 权限名(string)

  • rule: 权限内容(string)

  • orgList: 组织列表(Array[string])

  • roleList: 权限列表(Array[string])

  async createChainConfigPermissionAddPayload({ permissionResourceName, rule,  orgList = [], roleList = [] })

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

类名

  • chainConfig

参数说明

类型:k-v Object对象

  • permissionResourceName: 权限名(string)

  • rule: 权限内容(string)

  • orgList: 组织列表(Array[string])

  • roleList: 权限列表(Array[string])

  async createChainConfigPermissionUpdatePayload({ permissionResourceName, rule,  orgList, roleList })

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

类名

  • chainConfig

参数说明

类型:k-v Object对象

  • permissionResourceName: 权限名(string)

  async createChainConfigPermissionDeletePayload({ permissionResourceName })

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

类名

  • chainConfig

参数说明

  • orgId: 节点组织Id(string)

  • nodeIds: 节点Id数组(Array[string])

  async createChainConfigConsensusNodeIdAddPayload(orgId, nodeIds)

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

类名

  • chainConfig

参数说明

  • orgId: 节点组织Id(string)

  • nodeId: 旧节点Id(string)

  • newNodeId: 新节点Id(string)

  async createChainConfigConsensusNodeIdUpdatePayload(orgId, nodeId, newNodeId)

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

类名

  • chainConfig

参数说明

  • orgId: 节点组织Id(string)

  • nodeId: 节点Id(string)

  async createChainConfigConsensusNodeIdDeletePayload(orgId, nodeId)

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

类名

  • chainConfig

参数说明

  • orgId: 节点组织Id(string)

  • nodeIds: 节点Id数组(Array[string])

  async createChainConfigConsensusNodeOrgAddPayload(orgId, nodeIds)

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

类名

  • chainConfig

参数说明

  • orgId: 节点组织Id(string)

  • nodeIds: 节点Id数组(Array[string])

  async createChainConfigConsensusNodeOrgUpdatePayload(orgId, nodeIds)

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

类名

  • chainConfig

参数说明

  • orgId: 节点组织Id(string)

  async createChainConfigConsensusNodeOrgDeletePayload(orgId)

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

类名

  • chainConfig

参数说明

  • kvs: 字段key、value对(k-v Object对象)

  async createChainConfigConsensusExtAddPayload(kvs)

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

类名

  • chainConfig

参数说明

  • kvs: 字段key、value对(k-v Object对象)

  async createChainConfigConsensusExtUpdatePayload(kvs)

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

类名

  • chainConfig

参数说明

  • keys: 字段key数组(Array[string])

  async createChainConfigConsensusExtDeletePayload(keys)

4 证书管理接口

4.1 用户证书添加

类名

  • certMgr

参数说明

  • 在response.ContractResult.Result字段中返回成功添加的certHash

  async addCert()

4.2 用户证书删除

类名

  • certMgr

参数说明

  • certHashes: 证书Hash列表(Array[string])

  async deleteCert(certHashes)

4.3 用户证书查询

类名

  • certMgr

参数说明

  • certHashes: 证书Hash列表(Array[string])

  async queryCert(certHashes)

4.4 获取用户证书哈希

类名

  • certMgr

参数说明

  async getCertHash()

4.5 生成证书管理操作Payload(三合一接口)

类名

  • certMgr

参数说明

  • method: CERTS_FROZEN(证书冻结)/CERTS_UNFROZEN(证书解冻)/CERTS_REVOCATION(证书吊销)

  • params: 证书管理操作参数

  async createCertManagePayload(method, params)

4.6 生成证书冻结操作Payload

类名

  • certMgr

参数说明

  • certs: 证书列表(Array[string])

  async createCertManageFrozenPayload(certs)

4.7 生成证书解冻操作Payload

类名

  • certMgr

参数说明

  • certs: 证书列表(Array[string])

  async createCertManageUnfrozenPayload(certs)

4.8 生成证书吊销操作Payload

类名

  • certMgr

参数说明

  • certCrl: 吊销证书的crl(string)

  async createCertManageRevocationPayload(certCrl)

4.9 待签payload签名

类名

  • certMgr

参数说明

  • payload: 待签名payload

  signCertManagePayload(payload)

4.10 证书管理Payload签名收集&合并

类名

  • certMgr

参数说明

  • signedPayloadBytesArray: 签名之后的payload bytes数组(Array[payloadBytes])

  mergeCertManageSignedPayload(signedPayloadBytesArray)

4.11 发送证书管理请求(证书冻结、解冻、吊销)

类名

  • certMgr

参数说明

  • payloadBytes: 签名之后的payload bytes

  async sendCertManageRequest(payloadBytes)

5 消息订阅接口

5.1 区块订阅

类名

  • subscribe

参数说明

  • startBlock: 订阅起始区块高度,若为-1,表示订阅实时最新区块(number)

  • endBlock: 订阅结束区块高度,若为-1,表示订阅实时最新区块(number)

  • withRwSet: 是否返回读写集(boolean)

  • callBack: 回调函数,第一个参数是监听到的的block区块,第二个参数是错误信息

  subscribeBlock(startBlock, endBlock, withRwSet, callBack)

5.2 交易订阅

类名

  • subscribe

参数说明

  • startBlock: 订阅起始区块高度,若为-1,表示订阅实时最新区块(number)

  • endBlock: 订阅结束区块高度,若为-1,表示订阅实时最新区块(number)

  • txType: 订阅交易类型,若为common.TxType(-1),表示订阅所有交易类型(number)

  • txIds: 订阅txId列表,若为空(null),表示订阅所有txId(Array[string])

  • callBack: 回调函数,第一个参数是监听到的交易,第二个参数是错误信息

  subscribeTx(startBlock, endBlock, txType, txIds, callBack)

5.3 合约事件订阅

类名

  • subscribe

参数说明

  • topic: 订阅的主题(string)

  • contractName: 智能合约名称(string)

  • callBack: 回调函数,第一个参数是监听到的合约事件,第二个参数是错误信息

  subscribeContractEvent(topic, contractName, callBack)

5.4 多合一订阅

类名

  • subscribe

参数说明

  • txType: 订阅交易类型,目前已支持:区块消息订阅(common.TxType_SUBSCRIBE_BLOCK_INFO)、交易消息订阅(common.TxType_SUBSCRIBE_TX_INFO)、合约事件订阅(common.TxType.CONTRACT_EVENT_INFO)

  • payloadBytes: 消息订阅参数payload

  • callBack: 回调函数,第一个参数是监听到的事件返回,第二个参数是错误信息

  subscribe(payloadBytes, txType, callBack)

6 证书压缩

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

6.1 启用压缩证书功能

类名

  • certCompression

参数说明

  async enableCertHash()

6.2 停用压缩证书功能

类名

  • certCompression

参数说明

  async disableCertHash()

7 工具类

7.1 将EasyCodec编码解码成map

类名

  • easyCodec

	easyCodecItemToParamsMap(easyCodecObj)

8 数据归档

8.1 获取已归档区块高度

类名

  • callSystemContract

参数说明

  async getArchivedBlockHeight()

8.2 构造数据归档区块Payload

类名

  • archive

参数说明

  • targetBlockHeight: 目标区块高度(number)

  createArchiveBlockPayload(targetBlockHeight)

8.3 构造归档归档数据恢复Payload

类名

  • archive

参数说明

  • fullBlock: 完整区块的bytes

  createRestoreBlockPayload(fullBlock)

8.4 获取归档操作Payload签名

类名

  • archive

参数说明

  • payloadBytes: 待签名payloadBytes

  signArchivePayload(payloadBytes)

8.5 发送归档请求

类名

  • archive

参数说明

  • mergeSignedPayloadBytes: 签名之后的payloadBytes

  async sendArchiveBlockRequest(mergeSignedPayloadBytes)

8.6 归档数据恢复

类名

  • archive

参数说明

  • fullBlock: 完整区块的bytes

  async restoreBlock(fullBlock)

8.7 根据交易Id查询已归档交易

类名

  • archive

参数说明

  • txId: 交易Id(string)

  async getArchivedTxByTxId(txId)

8.8 根据区块高度查询已归档区块

类名

  • archive

参数说明

  • blockHeight: 区块高度(number)

  • withRWSet: 是否返回读写集(boolean)

  async getArchivedBlockByHeight(blockHeight, withRWSet)

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

类名

  • archive

参数说明

  • blockHeight: 区块高度(number)

  async getArchivedFullBlockByHeight(blockHeight)

8.10 根据区块哈希查询已归档区块

类名

  • archive

参数说明

  • hash: 区块哈希(string)

  • withRWSet: 是否返回读写集(boolean)

  async getArchivedBlockByHash(hash, withRWSet)

8.11 根据交易Id查询已归档区块

类名

  • archive

参数说明

  • txId: 交易Id(string)

  • withRWSet: 是否返回读写集(boolean)

  async getArchivedBlockByTxId(txId, withRWSet)

9 系统类接口

9.1 SDK停止接口

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

	stop()

10 类构造函数

10.1 UserContract

参数说明

  • chainID: chainId(string)

  • userInfo: 用户类(calss UserInfo)

  • node: 节点类(class node)

	constructor(chainID, userInfo, node)

10.2 CallUserContract

参数说明

  • chainID: chainId(string)

  • userInfo: 用户类(calss UserInfo)

  • node: 节点类(class node)

	constructor(chainID, userInfo, node)

10.3 CallSystemContract

参数说明

  • chainID: chainId(string)

  • userInfo: 用户类(calss UserInfo)

  • node: 节点类(class node)

	constructor(chainID, userInfo, node)

10.4 ChainConfig

参数说明

  • chainID: chainId(string)

  • userInfo: 用户类(calss UserInfo)

  • node: 节点类(class node)

	constructor(chainID, userInfo, node)

10.5 CertMgr

参数说明

  • chainConfig: ChainConfig类(class ChainConfig)

  • chainID: chainId(string)

  • userInfo: 用户类(calss UserInfo)

  • node: 节点类(class node)

	constructor(chainConfig, chainID, userInfo, node)

10.6 Subscribe

参数说明

  • chainID: chainId(string)

  • userInfo: 用户类(calss UserInfo)

  • node: 节点类(class node)

	constructor(chainID, userInfo, node)

10.7 EasyCodec

	constructor()

10.8 Archive

参数说明

  • chainID: chainId(string)

  • userInfo: 用户类(calss UserInfo)

  • node: 节点类(class node)

  • callSystemContract: 系统合约调用类(class callSystemContract)

数据库参数,类型:k-v Object对象

  • type: 数据库类型,目前只支持mysql,默认为mysql,无需设置

  • dbHost: 数据库地址

  • dbPort: 数据库端口

  • dbUsername: 数据库用户名

  • dbPassword: 数据库密码

	constructor(chainID, userInfo, node, callSystemContract, { type = 'mysql', dbHost, dbPort, dbUsername, dbPassword })

10.9 UserInfo

参数说明

  • orgID: 组织ID

  • userSignKeyPath: 用户私钥路径

  • userSignCertPath: 用户证书路径

	constructor(orgID, userSignKeyPath, userSignCertPath)

10.10 Node

参数说明

  • requestTimeout: 延时,单位ms,默认3000

节点配置参数nodeConfigArray,类型:k-v Object数组(Array[Object])

  • nodeAddr: 节点地址,ip+端口(string)

  • tlsEnable: 是否开启tls(boolean)

  • options: 类型k-v Object(pem: 根ca证书Buffer, clientKey: 客户端私钥Buffer, clientCert: 客户端证书Buffer, hostName: 节点域名,对应证书中的sans字段)

	constructor(nodeConfigArray, requestTimeout)

10.11 Sdk

参数说明

  • chainID: chainId(string)

  • orgID: 组织ID

  • userSignKeyPath: 用户私钥路径

  • userSignCertPath: 用户证书路径

  • nodeConfigArray: 参考10.6nodeConfigArray

  • timeout: 延时,单位ms

  • archiveConfig: 参考10.8数据库参数

	constructor(chainID, orgID, userSignKeyPath, userSignCertPath, nodeConfigArray, timeout, archiveConfig = {})

10.12 LoadFromYaml

参数说明

  • configPath: 配置文件路径(string)

	constructor(configPath)