Typescript SDK 概览

本文档介绍 Aptos SDK 的架构以及核心功能。

Aptos Typescript SDK 提供了可以与 Aptos 区块链交互的 API 和接口。您可以通过 SDK 连接到 Aptos REST API 从而实现与 Aptos 区块链的交互。REST API 可以将您的交易信息发送到 Aptos 区块链上，并且您也可以通过它来读取链上的状态。

下面是 Aptos Typescript SDK 的高级架构概览：

https://aptos.dev/img/docs/ts-sdk-light.svg

Aptos SDK 的核心功能

Aptos SDK 的核心功能如下：

• 密钥生成：Aptos SDK 为生成符合 Ed25519 标准的密钥对提供了方便的方法。Ed25519 公钥可用于推导链式账户地址，而私钥应保持私密，用于交易签名。详情可参考 class TransactionBuilderEd25519。

• 交易签署和提交：尽管 Aptos REST API 支持在服务器端签署原始交易，但在客户端使用 Aptos SDK 签署交易应该是首选，因为其更加安全。

• 交易状态查询：Aptos SDK 支持通过交易的哈希，来查询交易当前的状态（成功，失败，待定）。

• BCS 库：Aptos SDK 实现了一个 BCS (Binary Canonical Serialization) 库，用于交易签名和提交。Aptos 区块链使用 BCS 进行数据序列化和反序列化。详情可参考 Aptos SDK BCS。

• 信息检索方法：可以使用 Aptos SDK 来检索特定账户下的资源、模块和交易执行记录。

• Faucet 客户端：Aptos FaucetClient 是用来铸造测试代币的，用于开发。

• Token 客户端：Aptos SDK 提供了对 NFT 铸币和查询的内置支持。详情可参考 TokenClient。

Aptos Typescript SDK 的构件

Aptos Typescript SDK有三个逻辑层。请参考上面的高级架构图：

1. 传输层。

2. 核心 SDK 层。

3. 可选的应用层。

传输层负责向 REST API 终端发送 payload 信息。

核心 SDK 层暴露了大多数应用程序所需的功能，包括：

• 密钥生成。

• 交易签署和提交。

• 交易执行状态查询

• 各种各样的信息检索。

可选的应用层提供了对 NFT token API 的内置支持。

💡 提示： 在你开始使用 SDK 开发自己的应用 API 之前，你也可以参考这个 TokenClient API 作为 NFT token API 的一个例子。

OpenAPI 客户端

OpenAPI 客户端是一套基于 Aptos REST API 规范生成的类。参见 Typescript SDK OpenAPI 定义。

Aptos 账户类型

AptosAccount 类型提供了以下方法：

• 生成符合 Ed25519 标准的密钥对。

• 用 Ed25519 公钥签署一个字节缓冲区，以及

• 从公钥衍生出初始账户地址。

BCS 依赖库

BCS 依赖库是使用 Typescript 实现的，符合 BCS 子集的一个标准。

交易构建器

交易构建器包含用于构建交易 payload 的 Typescript 类型。Typescript SDK 中的交易生成器支持以下交易的 payload 的信息。

1. 入口函数 (Entry Function)

2. 脚本

AptosClient 组件

AptosClient 组件公开了检索账户下的资源、交易执行记录、模块和交易的 API。

此外，AptosClient 组件支持两种方法用于交易的签署和提交：

1. 提交 JSON 格式的交易，它将签名信息（输入到方法的入参）的创建委托给 API 服务器。这适用于使用 REST API 和 Aptos 服务器来生成签名信息、交易签名和提交签名后的交易到 Aptos 区块链。参考教程：你的第一笔交易。

2. 提交 BCS 格式的交易，它在客户端构建和签署原始交易。这种方法利用 BCS 库和交易构建器来构建交易的 payload 信息。参考教程：创建签名交易。

💡 提示： 第二种方法，即 BCS 格式，是向 Aptos 区块链提交交易的推荐方式。

TokenClient 组件

TokenClient 类提供了创建和查询 NFT 集合和令牌的方法。

Validation for Transaction Builder and BCS

对交易生成器和 BCS 的验证

BCS 用于组装和序列化交易的 payload 信息，以便签署和提交。

鉴于不同的编程语言有不同的原始类型约束（如字节长度、值范围等）和各种复合类型支持（如枚举、结构、类等），用于执行数据序列化的代码很难验证。

Aptos SDK 通过两种方式验证交易生成器和BCS：

1. 首先，通过单元测试和端到端（e2e）测试。

   💡 提示： 可以在 这里 找到 BCS 序列化器的单元测试用例。 可以在 这里 找到一个提交 BCS 交易的 e2e 测试用例。

2. 第二层验证是用测试矢量进行模糊测试。测试矢量是由 Aptos 区块链使用的相同代码产生的。测试向量是 JSON 对象的数组。每个 JSON 对象包含随机输入和预期输出。这些测试矢量可以被 Aptos SDK 解析和加载，以验证他们对交易构造器和 BCS 标准的实现。

以下是测试矢量的信息，其中的 payload 类型各不相同

• EntryFunction vector

• Script vector

测试矢量中的信息比较清晰。然而，我们使用了特殊的序列化方法以节省空间，同时避免数据溢出。细节描述如下：

• 所有账户地址都是十六进制编码

• EntryFunction 中的 args 是十六进制编码的

• U64 和 U128 数字被序列化为字符串，以避免数据被截断

• U8 被序列化为一个数字（而不是字符串）

• Script 和 ModuleBundle 中的 code 为十六进制编码

💡 提示： 关于 Typescript SDK 如何进行矢量验证，请参考这个代码示例。