Node.js API

标签:java-sdk Client


Node.js SDK为区块链应用开发者提供了Node.js API接口,以服务的形式供外部调用。按照功能,Node.js API可以分为如下几类:

  • Web3jService:提供访问FISCO BCOS 2.0+节点JSON-RPC接口支持;提供部署及调用合约的支持。

  • PrecompiledService

    Precompiled合约(预编译合约)是一种FISCO BCOS底层内嵌的、通过C++实现的高效智能合约,提供包括分布式权限控制CNS、系统属性配置、节点类型配置等功能。PrecompiledService是调用这类功能的API的统称,分为:

    • PermissionService:提供对分布式权限控制的支持

    • CNSService:提供对CNS的支持

    • SystemConfigService:提供对系统配置的支持

    • ConsensusService:提供对节点类型配置的支持

    • CRUDService:提供对CRUD(增删改查)操作的支持,可以创建表或对表进行增删改查操作。

API调用约定

  • 使用服务之前,首先需要初始化全局的Configuration对象,用以为各个服务提供必要的配置信息。Configuration对象位于nodejs-sdk/packages/api/common/configuration.js,其初始化参数为一个配置文件的路径或包含配置项的对象。配置文件的配置项说明见配置说明

  • 如无特殊说明,Node.js SDK提供的API均为异步API。异步API的实际返回值是一个包裹了API返回值的Promise对象,开发者可以使用async/await语法then…catch…finally方法操作该Promise对象以实现自己的程序逻辑

  • 当API内部出现错误导致逻辑无法继续执行时(如合约地址不存在),均会直接抛出异常,所有异常均继承自Error类

Web3jService

位置nodejs-sdk/packages/api/web3j

功能:访问FISCO BCOS 2.0+节点JSON-RPC;部署合约;调用合约

接口名 描述 参数 返回值
getBlockNumber 获取最新块高 Object,结果位于result字段**
getPbftView 获取PBFT视图 同上
getObserverList 获取观察者节点列表 同上
getSealerList 获取共识节点列表 同上
getConsensusStatus 获取区块链节点共识状态 同上
getSyncStatus 获取区块链节点同步状态 同上
getClientVersion 获取区块链节点版本信息 同上
getPeers 获取区块链节点的连接信息 同上
getNodeIDList 获取节点及其连接节点的列表 同上
getGroupPeers 获取指定群组的共识节点
和观察节点列表
同上
getGroupList 获取节点所属群组的群组ID列表 同上
getBlockByHash 根据区块哈希获取区块信息 区块哈希 同上
getBlockByNumber 根据区块高度获取区块信息 区块高度 同上
getBlockHashByNumber 根据区块高度获取区块哈希 区块高度 同上
getTransactionByHash 根据交易哈希获取交易信息 交易哈希 同上
getTransactionByBlockHashAndIndex 根据交易所属的区块哈希、
交易索引获取交易信息
交易所属的区块哈希
交易索引
同上
getTransactionByBlockNumberAndIndex 根据交易所属的区块高度、
交易索引获取交易信息
交易所属的区块高度
交易索引
同上
getPendingTransactions 获取交易池内所有未上链的交易 同上
getPendingTxSize 获取交易池内未上链的交易数目 同上
getTotalTransactionCount 获取指定群组的上链交易数目 同上
getTransactionReceipt 根据交易哈希获取交易回执 交易哈希 同上
getCode 根据合约地址查询的合约数据 合约地址 同上
getSystemConfigByKey 获取系统配置 系统配置关键字,目前支持

- tx_count_limit
- tx_gas_limit
同上
sendRawTransaction 发送一个经过签名的交易,该交易随后会被链上节点执行并共识 接受数量可变的参数:当参数数量为1时,参数应为交易的RLP编码;当参数数量为3时,参数应为合约地址、方法签名及方法参数 同上
deploy 部署合约 合约路径
输出路径
同上
call 调用只读合约 合约地址
调用接口*
参数列表
同上

*调用接口:函数名(参数类型,…),例如:func(uint256,uint256),参数类型之间不能有空格

PrecompiledService

PermissionService

位置nodejs-sdk/packages/api/precompiled/permission

功能:提供对分布式权限控制的支持

接口名 描述 参数 返回值
grantUserTableManager 根据用户表名和外部账户地址设置权限信息 表名
外部账户地址
Number,表示成功改写权限表的行数
revokeUserTableManager 根据用户表名和外部账户地址去除权限信息 表名
外部账户地址
Number,表示成功改写权限表的行数
listUserTableManager 根据用户表名查询设置的权限记录列表(每条记录包含外部账户地址和生效块高) 表名 Array,查询到的记录
grantDeployAndCreateManager 增加外部账户地址的部署合约和创建用户表权限 外部账户地址 Number,表示成功改写权限表的行数
revokeDeployAndCreateManager 移除外部账户地址的部署合约和创建用户表权限 外部账户地址 Number,表示成功改写权限表的行数
listDeployAndCreateManager 查询拥有部署合约和创建用户表权限的权限记录列表 Array,查询到的记录
grantPermissionManager 增加外部账户地址的管理权限的权限 外部账户地址 Number,表示成功改写权限表的行数
revokePermissionManager 移除外部账户地址的管理权限的权限 外部账户地址 Number,表示成功改写权限表的行数
listPermissionManager 查询拥有管理权限的权限记录列表 Array,查询到的记录
grantNodeManager 增加外部账户地址的节点管理权限 外部账户地址 Number,表示成功改写权限表的行数
revokeNodeManager 移除外部账户地址的节点管理权限 外部账户地址 Number,表示成功改写权限表的行数
listNodeManager 查询拥有节点管理的权限记录列表 Array,查询到的记录
grantCNSManager 增加外部账户地址的使用CNS权限 外部账户地址 Number,表示成功改写权限表的行数
revokeCNSManager 移除外部账户地址的使用CNS权限 外部账户地址 Number,表示成功改写权限表的行数
listCNSManager 查询拥有使用CNS的权限记录列表 Array,查询到的记录
grantSysConfigManager 增加外部账户地址的系统参数管理权限 外部账户地址 Number,表示成功改写权限表的行数
revokeSysConfigManager 移除外部账户地址的系统参数管理权限 外部账户地址 Number,表示成功改写权限表的行数
listSysConfigManager 查询拥有系统参数管理的权限记录列表 Array,查询到的记录

CNSService

位置nodejs-sdk/packages/api/precompiled/cns

功能:提供对节点类型配置的支持

接口名 描述 参数 返回值
registerCns 根据合约名、合约版本号、合约地址和合约abi注册CNS信息 合约名
合约版本号
合约地址
合约abi
Number,表示成功增加的CNS条目记录数
getAddressByContractNameAndVersion 根据合约名和合约版本号(合约名和合约版本号用英文冒号连接)查询合约地址。若缺失合约版本号,默认使用合约最新版本 合约名 + ':' + 版本号 Object,查询到的CNS信息
queryCnsByName 根据合约名查询CNS信息 合约名 Array,查询到的CNS信息
queryCnsByNameAndVersion 根据合约名和合约版本号查询CNS信息 合约名
版本号
同上

SystemConfigService

位置nodejs-sdk/packages/api/precompiled/systemConfig

功能:提供对系统配置的支持

接口名 描述 参数 返回值
setValueByKey 根据键设置对应的值(查询键对应的值,参考Web3jService中的getSystemConfigByKey接口) 键名
Number,表示成功修改的系统配置的数目

ConsensusService

位置nodejs-sdk/packages/api/precompiled/consensus

功能:提供对节点类型配置的支持

接口名 描述 参数 返回值
addSealer 根据节点NodeID设置对应节点为共识节点 节点ID Number,表示成功增加的共识节点数目
addObserver 根据节点NodeID设置对应节点为观察者节点 节点ID Number,表示成功增加的观察数目
removeNode 根据节点NodeID设置对应节点为游离节点 节点ID Number,表示成功增加的游离数目

CRUDService

位置nodejs-sdk/packages/api/precompiled/crud

功能:提供对CRUD(增删改查)操作的支持

接口名 描述 参数 返回值
createTable 创建表 表对象
表对象需要设置其表名,主键字段名和其他字段名。其中,其他字段名是以英文逗号分隔拼接的字符串
Number,状态码,0代表创建成功
insert 插入记录 表对象 Entry对象
表对象需要设置表名和主键字段名;Entry是map对象,提供插入的字段名和字段值,注意必须设置主键字段
Number,表示插入的记录数
update 更新记录 表对象 Entry对象 Condtion对象
表对象需要设置表名和主键字段名;Condition对象是条件对象,可以设置查询的匹配条件
Array,查询到的记录
remove 移除记录 表对象 条件对象
表对象需要设置表名和主键字段名;Condition对象是条件对象,可以设置移除的匹配条件
Select 查询记录 表对象:表对象需要设置表名和主键字段值
Condtion对象:Condition对象是条件对象,可以设置查询的匹配条件
Number,成功查询的记录数
desc 根据表名查询表的信息 表名 Object,主要包含表的主键字段名和其他属性字段