JSSDK

Part 1. Cocos-BCX链系统互操作API -- BCXJS

Javascript API，用于使用COCOS-BCX RPC API与基于COCOS-BCX的区块链集成。

Preparation:

Node.js版本8.9.3或更高版本

Build:

使用npm install安装本地依赖项。 使用开发构建npm run dev。

Browser Distribution

构建用于发布npm run release。 构建将在./build中找到

NPM

构建用于发布npm run release-npm。 构建将在./build-npm中找到

Import

Browser

NPM

在用 bcxjs 构建大型应用时推荐使用 NPM 安装。NPM 能很好地和诸如 webpack 或 Browserify 模块打包器配合使用

# 最新稳定版
$ npm install bcxjs-api

如果您有一个转换器，例如Babel，则支持在浏览器中使用ES6模块语法导入。

import BCX from "bcxjs-api"

Start:

实例化类库对象

var bcx=new BCX({
		default_ws_node:”ws://XXXXXXXXX” //节点rpc地址,选填。如果没有指定此项则会自动连接ws_node_list中速度最快的节点
		ws_node_list:[{url:"ws://xxxxxxx",name:"xxxxx"}]//API服务器节点列表，必填
		faucet_url:"http://xxx.xxx.xxx.xxx:xxxx", //注册入口
		networks:[{
			core_asset:"xxx",//核心资产符号
			chain_id:"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"//链id   
		}], 
		auto_reconnect:false,//当RPC断开时是否自动连接，默认为true
		app_keys:["xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"],//合约授权，不进行合约授权，则不用配置此选项
		real_sub:true//true：实时订阅，false:区块订阅，订阅通知频率为出块频率
		sub_max_op:13//订阅时最大处理OP数量
});

调用实例-转账

bcx.transferAsset({
     to:"test2",
     amount:1,
     assetId:"COCOS",
     memo:""
}).then(res=>{
     console.log('transferAsset res',res);
})

API说明

1.没有特殊说明均有一个可选参数callback

callback返回的result为Object对象,结构为{code:0,message:””}。 code=1时表示成功，无message状态描述。 code!=1时意味执行失败，message为失败状态描述。

2.没有殊说明均只有一个参数，该参数为一个对象，对象包含所有相关参数，其中也包含callback

调用示例：

bcl.getPrivateKey().then(res=>{});

3.除订阅类接口，其他接口在不传callback参数时均返回promise对象

4.接口的参数类型没有特殊说明均为字符串

5.接口的参数没有特殊说明均不能为空，callback为可选参数

6.查询类接口返回数据实例:{code:1,data:[]}

7.非查询类接口返回数据会多一个数据字段trxData,值为一个对象

示例：

trx_data:{
 block_num:*****,//区块高度
 trx_id:"************************"//交易ID
}

8.非查询类接口若涉及关联ID业务(如创建NH资产产生的ID)返回的数据中将包含data对象

//示例

data:{
  real_running_time: 387//运行时间
  result: "4.2.288"//关联业务id
}

状态码说明

Part 2. 区块链系统的互操作API

钱包模式

创建账户

方法：createAccountWithWallet
功能：钱包模式创建账户，钱包模式创建的账户不能用账户名密码登录。如果钱包模式已经存在账户，该操作会创建子账户，创建该子账户需要先成为终身会员账户
参数：
account：账户名注册规则，/^[a-z][a-z0-9.-]{4,63}$/，账户名长度为4-63位，由小写字母或数字构成且以字母开头
password：密码

备份钱包

方法：backupDownload
功能：备份钱包，调用该API会生成一个钱包文件，自动下载
参数：
callback：回调函数

加载备份钱包文件

方法：loadWalletFile
功能：对于web来说，file input绑定change事件，读取钱包文件
参数：
file：宿主环境若在web => file input 的 change事件触发返回的事件对象event.target，files[0]

从备份文件恢复钱包

方法：restoreWallet
功能：备份钱包，调用该API会生成一个钱包文件，自动下载。该API调用后，钱包处于锁定状态。
参数：
password：备份文件的钱包密码

导入私钥

方法：importPrivateKey
功能：导入私钥到钱包
参数：
privateKey：明文私钥
password：如果是已经创建钱包或恢复钱包，此时的密码为原来钱包的密码，否则是可以随意填写的临时密码

删除钱包

方法：deleteWallet
功能：删除钱包，使用账户模式时，最好让用户先执行删除钱包
参数：

获取钱包账户列表

方法：getAccounts
功能：获取钱包账户列表
参数：
callback:若有该参数，则内部会自动判断进行链初始化，否则直接返回数据，格式示例：

  {  
		"accounts": ["tom0002"],  
		"currentAccount": {  
			"account_id": "1.2.20",  
			"locked": true,  
			"account_name": "tom0002"  
		}
  }  

切换账户

方法：setCurrentAccount
功能：钱包模式切换当前使用账户
参数：
account：要切换的账户

解锁账户

方法：unlockAccount
功能：导入私钥或钱包模式才可以使用此方法解锁账户
参数：
password：导入私钥时设置的临时密码

锁定账户

方法：lockAccount
功能：锁定账户
参数：
callback：回调函数

账户模式

创建账户

方法：createAccountWithPassword
功能：账户注册。如果账户模式已经有账户登录，该操作会创建子账户，创建该子账户需要操作账户为终身会员账户
参数：
account：账户名注册规则，/^[a-z][a-z0-9.-]{4,63}$/，账户名长度为4-63位，由小写字母或数字构成且以字母开头
password：密码
autoLogin：boolean类型，指定是否自动登录，默认值为false
callback：回调函数

账户登录

方法：passwordLogin
功能：账户登录
参数：
account：账户名 password：密码

私钥登录

方法：privateKeyLogin
功能：之前这个API只是过渡，严格上导入私钥只存在于钱包模式。现在为了兼容，此API还暂时留在这里，依然可用调用
参数：
privateKey：私钥
password：设置的临时密码

退出登录

方法：logout
功能：该方法会清除用户相关缓存，其中包括清除加密后的密文key
参数：
callback：回调函数

修改密码

方法：changePassword
功能：只有账户模式，才能修改密码；修改密码成功后，API将会自动调用退出登录。
参数：
oldPassword：旧密码
newPassword：新密码

获取当前账户信息

方法：getAccountInfo
功能：当账户处于解锁状态，返回数据中将包含账户名name
参数：无

账户操作

公钥+账户名注册账户

方法：createAccountWithPublicKey 功能：通过随机生成的公钥和账户名创建账户。如果账户模式已经有账户登录，该操作会创建子账户，创建该子账户需要操作账户为终身会员账户 参数：
account(string):账户名注册规则，/^[a-z][a-z0-9.-]{4,63}$/，账户名长度为4-63位，由小写字母或数字构成且以字母开头
ownerPubkey(string):账户权限公钥 activePubkey(string):资金权限公钥

升级成为终身会员账户

方法：upgradeAccount
功能：购买终身会员账户后，可以创建子账户，此操作需消耗一定的手续费
参数：
callback：回调函数

导出用户私钥

方法：getPrivateKey
功能：获取用户active_private_key，本秘钥可用于为账户所有花费行为签名，返回的owner_private_key：可修改账户相关的各种设置，包括权限设置
参数：
callback：设置获取私钥成功后的回调函数

查询账户记录

方法：queryAccountOperations
功能：查询用户近期操作记录
参数：
account：账户名
limit：查询记录条数
startId:开始账户记录id,如果查询范围是整个账户记录，则最开始的账户记录则是startId
endId:结束账户记录id,如果查询范围是整个账户记录，则最新的账户记录则是endId

订阅用户操作记录变更

方法：subscribeToAccountOperations
功能：订阅用户操作记录变更
参数：
account：账户名
callback：只要用户操作记录有变化，就调用此callback：回调函数

查询账户信息

方法：queryAccountInfo
功能：账户信息中包含用户id用户名等信息
参数：
account：账户名

代币操作接口

代币资产转移

方法：transferAsset
功能：向目标对象发送代币
参数：
fromAccount：发款方账户名，不是发起提议，
toAccount：收款方账号名
amount：发送的代币数量
assetId：资产ID （如：X.X.X）或 代币符号（如：BTC）
memo：转账备注
isEncryption(boolean):是否加密备注
isPropose(boolean)：是否发起提议
callback：设置转账后的回调函数

创建资产

方法：createAsset
功能：创建token
参数：
assetId：资产符号，正则^[.A-Z]+$
precision：精度(小数位数)
maxSupply：最大资产总量
description: 资产描述，可不填
isBitAsset:是否锚定资产
callback：见统一API说明
chargeMarketFee(Object)：

		{  
			marketFeePercent:交易手续费率 (%),  
			maxMarketFee: 最大交易手续费 
		}  

bitassetOpts(Object)：  

		{  
			feedLifetimeSec(number):喂价有效时间（分钟）,
			minimumFeeds(number):最少喂价次数,
			forceSettlementDelaySec(number):强制清算发生前延迟时间（分钟）,
			forceSettlementOffsetPercent(number):强制清算价格偏离百分比,
			maximumForceSettlementVolum