蚂蚁区块链第15课 JS SDK概述及API接口速查

1，摘要

本文讲解蚂蚁BAAS的JavaScript SDK概述，说明JS SDK对应的API接口速查。其他语言包SDK参考官网其他章节说明即可。

2，JS SDK 说明

JavaScript SDK（简称 JS SDK）是业务端与区块链平台沟通的桥梁，提供基础的 API 功能，包括提交交易、账户操作、部署和调用合约、各类查询操作、交易模拟执行、监听事件等，同时实现了通过 TLS 和 HTTPS 协议与区块链平台交互，统一了 API 接口使用方式。因此，JS SDK 既可集成运行在 Node.js 环境，也可以运行在浏览器、Web 应用等环境，更加的灵活方便。

JS SDK 的使用方式简单，且对环境兼容友好。使用 TLS 协议时需要依赖 Node.js，使用 HTTPS 时可直接在浏览器环境集成使用。

版本说明

JS SDK 会不断的升级发布，完善功能，历史发布版本核心功能说明如下表。

版本	合约链支持说明	更新功能	下载链接
0.2.27	支持标准合约链； 支持 TEE 硬件隐私合约链； 不支持国密合约链	支持 TLS/HTTPS 协议； 支持账户合约操作、查询、事件订阅等功能 ； 支持 Solidity 和 C++ 合约 ；	alipay-mychain-0.2.27.tgz

说明：TEE 硬件隐私合约链、C++ 合约开发功能（编译为 wasm 字节码），仅供 蚂蚁区块链创新大赛 试用，尚未正式对外发布。

JS SDK 引用说明

不同运行环境下，JS SDK 的引用方式略有不同：

• Node 环境：

    const Chain = require("@alipay/mychain/index.node")
  

• Web 环境：

    const Chain = require("@alipay/mychain")
  

配置项说明

在初始化与区块链连接的实例之前，可进行选项配置，各配置项的具体说明如下。

说明：

• 如无特别说明，配置项的数据类型默认为 string 类型。
• 配置项中配置了账户相关的 Key 信息，包括账户公私钥、账户恢复公私钥。链的连接实例默认使用配置项中的账户 Key 信息进行交易签名。如果要切换账户，需要重新配置账户 Key 相关选项。详情参见 创建账户 中切换账户配置的使用示例。

配置项	必填	配置说明	示例值
host	true	区块链节点的 IP 或者主机名。使用 TLS 时为 IP 地址；使用 HTTPS 时为主机名。	127.0.0.1， https://www.alipay.com 或 https://127.0.0.1
port	true	区块链节点开放连接的端口号，类型为 number。	18130
clients	false	可设置多个 host:port，作为主节点（首个为主节点），次节点备份，当主节点出现连接问题，SDK 会切换到列表其它节点重试连接。如果配置此参数，可不用设置 host 和 port 参数。	[{host:’127.0.0.1’,port:18130},{host:’127.0.0.2’,port:18130}]
timeout	true	与区块链节点连接的超时时间配置，单位毫秒，类型为 number。	30000
ca	true	目标合约链的根证书。	在 BaaS 平台申请通过后下载 ，详情参考 申请证书
key	true	客户端生成的私钥文件，用于生成证书请求文件，进而申请证书。	使用 BaaS 提供 密钥生成工具 生成 ，详情参考 申请证书
userPublicKey	true	账户公钥，字符串内容为 16 进制。	0x971c77d38bf220572fe8294d7884b184adeeb9bac4d61c1b3e1e924575e526152145763eaba40c8713c82cc2961fba98f71c8b93984d4e3d10b2ff53ea039551
userPrivateKey	true	账户私钥，字符串内容为 16 进制。	0x4015e39643765014b874dbd35a53f1a01418c66f7c47da35f3a84122c743d9a3
userRecoverPublicKey	true	账户恢复公钥，字符串内容为 16 进制。	0xb961f6a1a43b9e7aa368be8d093ed7bec2d0ff85ff7646ec968d86bd546151efbd037cfe09933684b5c98978a1593074cdff465de3a3620089f5634911bf7b2e
userRecoverPrivateKey	true	账户恢复私钥，字符串内容为 16 进制。	0x44a973e5286f1d3513561360bb0214235425b942a4649c7d371f780ca1ee0e80
passphrase	true	TLS 或 HTTPS 链接的 client.key 文件的自定义密码。	123abc
checkServerIdentity	false	针对 TLS 协议的配置，类型为 boolean，含义为是否启用对服务端 hostname 的检查，即对比服务端证书的 CN 字段与 hostname 是否匹配，默认值为 false。	false
tx_querycount	false	对于交易类型，提交交易后会调用 QueryTransactionReceipt查询收据，此配置可设定重试的次数，类型为 number，默认值为 3。	5
tx_querytime	false	对于交易类型，提交交易后会调用 QueryTransactionReceipt查询收据，此配置可设定重试的时间间隔，类型为 number，单位为毫秒，默认值为 3000。	200

3，API 概览

汇总了合约平台支持的所有 JS API，并对接口调用的返回值予以说明。具体接口信息参见相关接口文档。

环境接口

接口	描述
Chain	初始化环境实例。

账户接口

接口	描述
CreateAccount	创建账户。
TransferBalance	转账。
SetRecoverkey	设置恢复公钥。
PreResetPubKey	预重置公钥。
ResetPubKey	重置公钥。
UpdateAuthMap	更新权重。

合约接口

接口	描述
contract	构造合约实例。
new	部署合约。
自定义合约方法名	调用合约。
update	升级合约。

查询接口

接口	描述
QueryBlockHeader	查询区块头。
QueryLastBlock	查询最后一个区块。
QueryBlock	查询指定的区块。
QueryTransaction	查询交易。
QueryTransactionReceipt	查询收据。
QueryAccount	查询账户。
QueryContract	查询合约账户。

本地执行接口

接口	描述
LocalTransaction	本地执行普通交易。
合约相关操作方法	本地执行合约相关交易。

原生存证接口

接口	描述
NativeDepositData	在合约链上对目标数据进行存证。

事件接口

接口	描述
event.account	订阅账户事件。
accountEvent.close	取消订阅账户事件。
event.contract	订阅合约事件。
contractEvent.close	取消订阅合约事件。
event.topic	订阅主题事件。
topicEvent.close	取消订阅主题事件。
event.block	订阅区块事件。
blockEvent.close	取消订阅区块事件。

辅助工具类接口

接口	描述
getHash	对给定字符串计算哈希。
toDecimal	将十六进制转换成十进制。
toUtf8	将十六进制字符串转换成 utf8 字符串。
getKeyInfo	获取账户信息。
decryptAESWithPassword	TEE 解密方法
decryptTXWithAES	TEE 硬件隐私合约链，解密 Transaction 方法。
generateAESKey	TEE 硬件隐私合约链，通过指定的 aesKey 和交易哈希派生目标交易的最终 AES 密钥。

返回值

JS SDK 多数接口都以相同的回调方式返回结果，对于合约相关接口，结果返回方式稍有不同。

• 普通接口返回值

参数	类型	说明
err	string	使用的账户名，用此账户来创建新账户。
data	object	交易回执的结果

• 合约部署和调用接口返回值

参数	类型	说明
err	string	错误信息，如果为 undefined，则说明无错误。
output	不确定	如果是合约部署，此字段为合约的 bytecode；如果是合约调用此字段，则与合约方法返回值类型相同。
data	object	交易回执的结果

以上 data 字段内容根据不同的接口返回不同内容，具体请查看接口返回值。

4，参考

（1）JS SDK 开发指南>API 参考>API 概览
https://tech.antfin.com/docs/2/107131
（2）Java SDK 开发指南>Java SDK 说明
https://tech.antfin.com/docs/2/101892
（3）C++ SDK 开发指南>C++ SDK 说明
https://tech.antfin.com/docs/2/107229