> For the complete documentation index, see [llms.txt](https://gushi10546.gitbook.io/aptos-kai-fa-zhe-wen-dang/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gushi10546.gitbook.io/aptos-kai-fa-zhe-wen-dang/guides-zhi-nan/xi-tong-ji-cheng-shang-zhi-nan.md). # 系统集成商指南 注意： 该文档目前正在构建中，并会定期添加更多文档 如果您向客户提供区块链服务并希望将 Aptos 区块链添加到您的平台，那么本指南适合您。本系统集成商指南将引导您完成将 Aptos 区块链集成到您的平台所需的一切。本指南假设您熟悉区块链。 ## 概述 本指南将概述与 Aptos 集成的以下主题： * 准备测试环境。 * 在区块链上创建一个帐户。 * 与区块链上的另一个实体交换帐户标识符，例如，执行交换。 * 创建交易。 * 获取gas估计并验证交易的正确性。 * 将交易提交到区块链。 * 等待交易结果。 * 查询给定账户与特定账户的历史交易和交互，即取款和存款。 ## 入门 与 Aptos 区块链集成有两种得到良好支持的方法： 1. 使用我们的独立测试网进行本地开发 2. Devnet——社区共享资源 ### 本地测试网 运行本地测试网有两种选择： 1. 直接运行本地测试网是按照【本指南】 2. 使用 CLI 1) \[使用 CLI 安装] 和 2) 使用水龙头启动 \[本地节点] 这将在 `http://127.0.0.1:8080/v1` 公开一个 REST API 服务，并在 `http://127.0.0.1:8000` 公开一个水龙头服务，用于选项 1 或 `http://127.0.0.1： 8081` 用于选项 2。应用程序将输出服务的位置。 ### 访问 Devnet 水龙头服务： REST API 服务： ### SDKs SDKs Aptos 目前有两个 SDK： 1. Python 2.Typescript ### 其他领域 * 使用 CLI，包括创建帐户、转移代币和发布模块 * Typescript SDK * Python SDK * REST API 规范 * 本地测试网开发流程 ## **Aptos 上的帐户** 账户代表 Aptos 区块链上可以发送交易的资源。每个帐户由一个特定的 32 字节帐户地址标识，并且是 Move 模块和 Move 资源的容器。在 Aptos 上，必须在涉及该账户的任何区块链操作之前在链上创建账户。 Aptos 框架支持在通过 `account::transfer` 或通过 `account::create_account` 显式转移 Aptos 代币时隐式创建帐户。 创建时，Aptos 帐户包含： * 包含 Aptos 代币的资源以及从该资源中存取代币。 * 与他们当前的公钥、私钥相关联的身份验证密钥。 * 一个严格递增的序列号，代表账户下一笔交易的序列号，以防止重放攻击。 * 添加到帐户的所有新类型代币的事件流。 ### 账户标识符 目前，Aptos 仅支持一个帐户的单一统一标识符。 Aptos 上的帐户普遍表示为 32 字节的十六进制字符串。短于 32 字节的十六进制字符串也应该是有效的，在这些情况下，十六进制字符串用前导零填充，例如，`0x1` => `0x0000000000000...01`。 ### **创建账户地址** 帐户地址在创建时被定义为来自用于帐户身份验证的公钥和签名算法的单向函数。 **阅读更多** 这在 \[Accounts] 文档中进行了深入介绍，并在 \[Typescript SDK]和\[Python SDK]。请注意，目前这些 SDK 仅演示如何从 Ed25519 单签名者生成地址。 ### 轮换密钥 Aptos 上的帐户具有轮换密钥的能力，因此可能被泄露的密钥不能用于访问帐户。密钥可以通过 `account::rotate_authentication_key` 函数。 **阅读更多** 在[账户地址](/aptos-kai-fa-zhe-wen-dang/gai-nian/zhang-hu.md#zhang-hu-di-zhi)中查看更多信息。 刷新密钥通常被认为是安全领域的良好卫生习惯。然而，这对习惯于使用助记符来表示私钥及其关联帐户的系统集成商提出了挑战。为了简化系统集成商的工作，Aptos 将在主网启动之前提供链上映射。链上数据将当前助记词定义的有效账户地址映射到实际账户地址。 ### 防止重放攻击 防止重放攻击 当 Aptos 区块链处理交易时，它会查看交易中的序列号，并将其与发送者账户中的序列号（以当前分类帐版本存储在区块链中）进行比较。仅当交易中的序列号与发送方帐户的序列号相同时才会执行交易，如果不匹配则拒绝。以这种方式，过去的交易，必然包含较旧的序列号，不能被重放，从而防止重放攻击。 **阅读更多** 在此处查看有关帐户序列号的更多信息。 ## **转账** Aptos 转账以 BCS（二进制规范序列化）编码。交易包含诸如发送者的帐户地址、发送者的身份验证、要在 Aptos 区块链上执行的所需操作以及发送者愿意为执行交易支付的 gas 量等信息。 ### **转账状态** 交易可能以下列状态之一结束： 1. 在区块链上提交并执行。这被认为是成功的交易。 2. 在区块链上提交并中止。中止代码指示转账执行失败的原因。 3. 交易提交过程中由于gas不足、交易格式无效、key不正确等验证检查而被丢弃。 4. 交易提交后但未尝试执行前丢弃。这可能是由于其他交易影响帐户而导致的超时或 gas 不足。 任何已提交的交易都将向发件人的账户收取gas。 在转账提交期间，提交者会收到提交成功或验证失败的原因的通知。 成功提交但最终被丢弃的交易可能在任何可访问的 Aptos 节点或 Aptos 网络中都没有可见状态。用户可以尝试重新提交相同的交易以重新验证交易。如果提交节点认为该交易仍然有效，这将返回一个错误，指出存在已提交的相同交易。 提交者可以尝试将 gas 成本增加一点点，以帮助取得进展并调整可能导致下游交易被丢弃的任何原因。 在 Aptos devnet 上，提交和确认之间的时间在几秒钟之内。 阅读更多 请参阅\[此处了解交易生命周期的全面描述 ### 构建转账 Aptos 支持两种构建转账的方法： * 构建 JSON 编码的对象并与 Web API 交互以生成本机转账。 * 使用 Aptos 客户端库生成本地转账。 ### **JSON 编码交易** **JSON 编码交易** JSON 编码的交易可以通过 [REST API](https://fullnode.devnet.aptoslabs.com/v1/spec#/) 生成，步骤如下： * 首先为`/transactions/encode_submission` 端点构造一个适当的 JSON 有效负载，如 [Python SDK](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L128)。 * 上面的输出包含一个包含“message”的对象，并且必须在本地使用发件人的私钥对其进行签名。 * 最后，使用签名信息扩展原始 JSON 有效负载并发布到`/transactions`\[端点]。这将返回一个转账提交结果，如果成功，该结果在“哈希” 中包含一个转账哈希。 JSON 编码的转账允许快速开发并支持将转账参数无缝 ABI 转换为本机类型。然而，大多数系统集成商更喜欢在他们自己的技术堆栈中生成交易。 \[TypeScript SDK] 和 \[Python SDK]都支持生成 BCS 交易。 ### **BCS 编码交易** BCS 编码的交易可以提交到`/transactions` 端点，但必须在 HTTP 标头中指定`Content-Type: application/x.aptos.signed_transaction+bcs`。这将返回一个转账提交结果，如果成功，该结果在“哈希”\[字段]中包含一个转账哈希。 ### 交易类型 交易类型 在给定转账中，执行目标可以是以下两种类型之一： * 入口点（以前称为脚本函数），和/或 * 脚本（有效负载）。 目前的 SDK：[Python](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L249) 和 [Typescript](https://github.com/aptos-labs/aptos-core/blob/76b654b54dcfc152de951a728cc1e3f9559d2729/ecosystem/typescript/sdk/src/aptos_client.test.ts#L98) 仅支持生成以入口点为目标的转账。本指南指出了其中许多入口点，例如`coin::transfer` 和`account::create_account`。 Aptos 区块链上的所有操作都应该可以通过入口点调用进行。虽然可以提交多个转账以串联调用入口点，但许多此类操作可能会受益于从单个转账中以原子方式调用。脚本有效负载转账可以调用任何模块中定义的任何入口点或公共函数。 Move Book 目前，本指南中没有关于脚本有效负载的教程，但 \[Move book]\(确实包含一些深度。 阅读更多 请参阅以下文档以生成有效交易： * [JSON 编码交易](/aptos-kai-fa-zhe-wen-dang/kai-fa-zhe-jiao-cheng/ni-de-di-yi-bi-jiao-yi.md)通过 Typescript、Python 和 Rust。 * [BCS 编码代币转移的 Python 示例](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/python/sdk/aptos_sdk/client.py#L240)。 * [BCS 编码代币转移的打字稿示例](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.test.ts#L122)。 * [基于 CLI 的转账发布](/aptos-kai-fa-zhe-wen-dang/aptos-cli/shi-yong-aptos-cli.md#fa-bu-ju-you-ming-ming-di-zhi-de-move-bao)。 * [发布您的第一个 Move 模块](/aptos-kai-fa-zhe-wen-dang/kai-fa-zhe-jiao-cheng/ni-de-di-yi-ge-move-mo-kuai.md) 通过 Typescript、Python 和 Rust。 ### **交易状态** 交易状态可以通过使用提交期间返回的哈希查询 API[`[/transactions/by_hash/{hash}]`](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_transaction_by_hash)的交易。 提交转账的合理策略是将其生命周期限制为 30 到 60 秒，并定期轮询该 API，直到成功或该时间过去几秒钟后。如果链上没有承诺，则交易很可能被丢弃。 ### **测试交易或交易预执行** 为了便于评估交易，Aptos 支持不需要也不应该包含交易有效签名的模拟 API。 模拟 API 的工作方式与交易提交 API 相同，只是它执行交易并返回结果以及使用的气体。可以通过向 [\[/transactions/simulate\]](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/simulate_transaction)提交交易来访问模拟 API。 阅读更多 这是一个示例，展示了如何在 [\[Typescript SDK\]](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.ts#L413)。(请注意，gas 使用量可能会根据帐户的状态而变化。我们建议最大gas量大于此 API 引用的量。 ## **查看当前和历史状态** 大多数与 Aptos 区块链的集成都受益于对区块链当前和历史状态的全面而全面的概述。 Aptos 提供历史交易、状态和事件，它们是交易执行的结果。 * 历史交易指定执行状态、输出以及与相关事件的关联。每笔交易都有一个与之关联的唯一版本号，该版本号指示其在区块链账本历史中的全局顺序。 * 状态是直到特定版本的所有交易输出的表示。换句话说，状态版本是包括该交易版本在内的所有交易的累积。 * 随着转账的执行，它们可能会发出事件。 [事件](/aptos-kai-fa-zhe-wen-dang/gai-nian/shi-jian.md)是关于链上数据变化的提示。 节点上的存储服务采用两种形式的修剪来擦除节点上的数据： 1. 状态，以及 2. 事件、交易和其他一切。 虽然其中任何一个都可能被禁用，但存储状态版本并不是特别可持续。 可以通过将 [`[enable_ledger_pruner]`](https://github.com/aptos-labs/aptos-core/blob/cf0bc2e4031a843cdc0c04e70b3f7cd92666afcf/config/src/config/storage_config.rs#L141)设置为禁用事件和转账修剪`false`。这将是主网中的默认行为。在不久的将来，Aptos 将提供索引器，以减少直接从节点查询的需要。 REST API 包含以下用于查询转账和事件的有用 API： * [账户交易](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_account_transactions) * [按版本交易](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_transaction_by_version) * [按事件句柄的事件](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_events_by_event_handle) ## **交换和跟踪代币** Aptos 有一个标准的 [代币类型](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/coin.move)。通过使用不同的结构来表示不同类型的代币，这些结构表示类型参数或`Coin`的泛型。 代币存储在资源“CoinStore”下的帐户中。在创建帐户时，每个用户都有资源 `CoinStore<0x1::aptos_coin::AptosCoin>` 或 `CoinStore`，简称。此资源中包含 Aptos 代币：`Coin`。 ### **在用户之间转移代币** 代币可以通过[`[coin::transfer]`](https://github.com/aptos-labs/aptos-core/blob/36a7c00b29a457469264187d8e44070b2d5391fe/aptos-move/framework/aptos-framework/sources/coin.move#L307)`所有代币的功能和`[account::transfer](https://github.com/aptos-labs/aptos-core/blob/36a7c00b29a457469264187d8e44070b2d5391fe/aptos-move/framework/aptos-framework/sources/account.move#L398) 用于 Aptos 代币。后一个函数的优点是，如果目标帐户不存在，它会创建它。 警告 {% hint style="info" %} 注意 如果一个帐户没有为给定的 T 注册一个`CoinStore`，那么任何类型 T 到该帐户的转移都将失败。 {% endhint %} ### **代币当前余额** `Coin` 的当前余额，其中 T 是 Aptos 代币，可在账户资源 url 获得：`https://{rest_api_server}/accounts/{address}/resource/0x1::coin::CoinStore< 0x1::aptos_coin::AptosCoin>`。余额存储在`coin::amount` 中。该资源还分别包含存款和取款事件的总数、`deposit_event` 和`withdraw_event` 中的`counter` 值。 ### 查询事件 Aptos 为所有代币的取款和存款提供清晰和规范的事件。这可以与相关交易协调使用，向用户展示他们的账户余额随时间的变化、发生时间以及原因。通过一些额外的解析，也可以共享交易类型和其他相关方等元数据。 事件可以通过事件句柄查询**：** https\://{rest\_api\_server}/accounts/{address}/events/0x1::coin::CoinStore<0x1::aptos\_coin::AptosCoin>/withdraw\_events 可以从生成事件的转账中收集更多信息。为此，请查询：https\://{rest\_server\_api}/transactions/by\_version/{version} , 其中在事件查询中，`{version}` 与 `{version}` 的值相同 。 该转账反过来提供了其他重要信息，以生成有关导致事件的原因的完整观点。例如，这给出了`时间戳` 交易执行时间、其他相关事件以及`gas使用`。交易包含要呈现给用户的所有相关信息，包括事件、执行的时间和所做的更改。 {% hint style="info" %} 当跟踪代币的全部运动时，通常事件就足够了。然而，`0x1::aptos_coin::AptosCoin` 还需要查看从给定帐户发送的每笔交易的`gas_used`。为了减少不必要的开销，由于交易而提取 gas 费用不会发出事件。可以从此 API 检索帐户的所有交易：`https://{rest_server_api}/accounts/{address}/transactions`。 {% endhint %} {% hint style="info" %} 要创建一些示例数据以供探索，请参阅[您的第一笔交易](/aptos-kai-fa-zhe-wen-dang/kai-fa-zhe-jiao-cheng/di-yi-ge-nft.md)要了解有关代币创建的更多信息，请参阅[你的第一枚代币](/aptos-kai-fa-zhe-wen-dang/kai-fa-zhe-jiao-cheng/di-yi-ge-dai-bi.md)。 {% endhint %}