EOSAPI完全指南：解密柚子币DApp开发秘籍

2025-03-08 03:36:23 102

柚子币 (EOS) API 使用方法

EOS，也常被称为柚子币，是一个旨在构建去中心化应用的区块链平台。它提供了一套强大的 API，允许开发者与 EOS 区块链进行交互，例如读取区块链数据、创建和部署智能合约、以及执行交易。 本文将深入探讨如何使用 EOS API，涵盖从基本概念到实际操作的各个方面。

EOS API 的主要组件

EOS API 的核心功能由 nodeos 节点软件提供，它是 EOS 区块链网络的基础设施组件。 nodeos 节点持续同步区块链数据，并通过精心设计的 HTTP API 接口对外提供服务，开发者可以通过这些接口与 EOS 区块链进行交互。这些 API 接口根据其功能特性，可以被划分成几个主要的类别：

  • Chain API: 这是 EOS API 中最常用的类别，它提供了一系列用于查询区块链底层数据的接口。通过 Chain API，开发者可以获取区块的详细信息，包括区块头、交易列表、时间戳等；可以检索特定交易的信息，例如交易 ID、发送者、接收者、交易状态等；还可以查询账户的详细信息，包括账户余额、权限信息、资源使用情况等。Chain API 是构建 EOS DApp 的基础。
  • History API: History API 专注于提供对历史交易记录的访问能力。需要注意的是，默认情况下， nodeos 节点为了节省存储空间和提高性能，并不启用 history_plugin 插件。因此，如果要使用 History API，需要在 nodeos 的配置文件中显式地启用 history_plugin 。启用后，可以通过 History API 查询特定账户的所有历史交易记录，这对于审计、分析等场景非常有用。
  • Wallet API: Wallet API 提供了一系列用于管理 EOS 钱包的接口。通过 Wallet API，可以创建新的 EOS 钱包，导入已有的私钥，对交易进行签名等操作。然而，需要特别注意的是，出于安全考虑，通常不建议在生产环境中使用 Wallet API。因为将私钥存储在运行 nodeos 节点的服务器上存在安全风险，容易受到攻击。更安全的做法是使用专门的硬件钱包或密钥管理服务来管理私钥。
  • Producer API: Producer API 专门为区块生产者 (BP) 设计，提供了管理 BP 相关功能的接口。通过 Producer API，BP 可以注册成为 EOS 网络的区块生产者，参与区块的生产和验证过程；可以对其他 BP 进行投票，参与 EOS 网络的治理；还可以管理 BP 的资源，例如 CPU 和 NET 资源。只有经过授权的 BP 才能使用 Producer API。
  • Net API: Net API 主要用于管理 nodeos 节点之间的网络连接信息。它提供了查询节点连接状态、节点对等信息等功能，允许开发者监控和管理节点在 EOS 网络中的网络连接状况。Net API 对于维护 EOS 网络的稳定性和可靠性至关重要。

使用 Chain API 获取区块链数据

Chain API 是与 EOS 区块链交互的核心，它提供了一系列接口，允许开发者查询区块链上的各种信息，例如账户数据、合约状态、交易记录等等。通过 Chain API，开发者无需维护自己的完整节点，就能轻松构建各种 EOS 区块链应用。以下是一些常用的 Chain API 接口及其使用方法，包含详细参数解释和常见用例：

1. `get_block` - 获取区块信息

此接口用于获取指定区块高度或区块哈希对应的区块详细信息，包括区块头、交易信息、生产者信息等。

  • 请求方法： POST
  • 请求参数：
    • `block_num_or_id`: (字符串或整数) 区块高度或区块哈希值。可以是十进制的区块高度数字，也可以是十六进制的区块哈希字符串。
  • 返回值： 一个 JSON 对象，包含区块的所有信息。包括但不限于：
    • `timestamp`: 区块生成的时间戳。
    • `producer`: 生产该区块的节点名称。
    • `transactions`: 区块中包含的交易列表，每笔交易都包含详细信息。
    • `block_extensions`: 区块扩展信息，用于存储一些附加数据。
    • `previous`: 前一个区块的哈希值。
  • 用例： 获取最新区块的信息，查询特定高度区块的交易内容。

2. `get_account` - 获取账户信息

此接口用于获取指定账户的详细信息，包括账户余额、权限信息、合约信息等。

  • 请求方法： POST
  • 请求参数：
    • `account_name`: (字符串) 要查询的账户名称。
  • 返回值： 一个 JSON 对象，包含账户的所有信息。包括但不限于：
    • `account_name`: 账户名称。
    • `core_liquid_balance`: 账户的核心代币余额（例如 EOS）。
    • `ram_quota`: 账户的 RAM 配额。
    • `ram_usage`: 账户的 RAM 使用量。
    • `permissions`: 账户的权限列表，包括 owner 和 active 权限。
  • 用例： 检查账户余额，验证账户权限设置，监控账户的资源使用情况。

3. `get_table_rows` - 获取表数据

此接口用于获取智能合约表中指定范围的数据，可以根据主键或二级索引进行查询。

  • 请求方法： POST
  • 请求参数：
    • `code`: (字符串) 合约账户名。
    • `scope`: (字符串) 表的作用域（通常与合约账户名相同）。
    • `table`: (字符串) 表名。
    • `lower_bound`: (字符串, 可选) 查询的起始主键值。
    • `upper_bound`: (字符串, 可选) 查询的结束主键值。
    • `limit`: (整数, 可选) 返回的最大行数。
    • `key_type`: (字符串, 可选) 主键类型，例如 `i64`。
    • `index_position`: (字符串, 可选) 索引位置，如果使用二级索引则需要指定。
    • `encode_type`: (字符串, 可选) 编码类型，通常为 `hex`。
    • `reverse`: (布尔值, 可选) 是否反向排序。
    • `show_payer`: (布尔值, 可选) 是否显示支付者。
  • 返回值： 一个 JSON 对象，包含表数据和更多信息。包括但不限于：
    • `rows`: 一个数组，包含表中的行数据。
    • `more`: 如果有更多数据，则为 true，否则为 false。
    • `next_key`: 下一页数据的起始主键值（如果 `more` 为 true）。
  • 用例： 查询智能合约中的数据，例如获取用户在某个游戏中的排名，查询某个代币的持有者列表。

4. `push_transaction` - 推送交易

此接口用于将签名后的交易推送到区块链上执行。

  • 请求方法： POST
  • 请求参数：
    • `signatures`: (字符串数组) 交易签名。
    • `compression`: (字符串) 压缩类型，通常为 `none`。
    • `packed_context_free_data`: (字符串) 上下文无关数据。
    • `packed_trx`: (字符串) 序列化后的交易数据。
  • 返回值： 一个 JSON 对象，包含交易的执行结果。包括但不限于：
    • `transaction_id`: 交易 ID。
    • `processed`: 交易处理结果，包含 CPU 和 NET 资源消耗信息。
  • 用例： 发送代币，调用智能合约，创建新账户。

5. `get_info` - 获取链信息

此接口用于获取区块链的全局信息，包括链 ID、最新区块高度、HEAD 区块 ID 等。

  • 请求方法： POST
  • 请求参数： 无
  • 返回值： 一个 JSON 对象，包含链的信息。包括但不限于：
    • `chain_id`: 链 ID。
    • `head_block_num`: 最新区块高度。
    • `head_block_id`: 最新区块 ID。
    • `head_block_time`: 最新区块生成时间。
  • 用例： 获取链的最新状态，用于同步数据或监控网络。

这些 Chain API 接口是开发者与 EOS 区块链交互的重要工具。通过灵活使用这些接口，可以构建各种功能强大的 EOS 区块链应用。在使用这些接口时，请务必注意参数的正确性，并根据实际需求选择合适的接口。

1. get_info

该接口提供区块链网络的关键元数据，便于应用程序了解链的状态。它返回一个包含区块链基本信息的JSON对象，例如：

  • 链 ID (chain_id): 区块链网络的唯一标识符，用于区分不同的区块链，例如主网、测试网等。 不同的链ID确保交易不会在错误的链上执行，避免潜在的安全风险和数据混乱。
  • 头区块高度 (head_block_num): 区块链当前最高区块的编号，代表链上已经确认的区块数量。 区块高度是衡量区块链进度的关键指标，也是同步节点和验证数据的依据。
  • 头区块 ID (head_block_id): 头区块的哈希值，用于唯一标识区块链中的最后一个区块。它通过密码学方法保证了区块的完整性和不可篡改性。
  • 头区块时间 (head_block_time): 头区块生成的时间戳，通常采用UTC时间。 时间戳用于追踪交易发生的顺序，并在时间相关的应用中起作用，如时间锁合约。
  • 最近不可逆区块高度 (last_irreversible_block_num): 区块链上被认为不可逆转的区块高度。 在这个高度之前的区块通常被认为是最终确认的，无法被篡改。这个参数对于需要高度确定性的应用至关重要。
  • 最近不可逆区块 ID (last_irreversible_block_id): 最近不可逆区块的哈希值。
  • 当前版本 (server_version): 节点所运行的区块链软件的版本信息。

应用程序可以使用此接口检索这些信息，以确定链的状态、网络共识进度和兼容性。例如，钱包应用程序会使用头区块高度来显示链的同步进度，并确保交易广播到最新的区块中。 智能合约可以使用链ID来区分不同的网络环境，并根据环境进行不同的操作。

请求方式: POST 请求地址: /v1/chain/get_info 请求体: 空 {}

响应示例:

以下 JSON 格式的响应示例展示了区块链节点所返回的信息，这些信息对于理解链的状态至关重要。

{ "server version": "v2.1.0", 节点软件的版本号，例如 v2.1.0 。此版本号对于调试和确保兼容性至关重要。

"chain id": "aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ff6cf55bdbb6b0c223", 链的唯一标识符，用十六进制字符串表示。不同的链具有不同的 chain_id ，确保连接到正确的网络。

"head block num": 123456789, 链上最新区块的编号，代表了当前区块链的高度。

"last irreversible block num": 123456780, 最后一个不可逆区块的编号。低于此编号的区块被认为是永久性的，不会被回滚。

"last irreversible block id": "075bcd4d6179d27d0c629f97c5057645f3b670a46999c54e4e0f26b51950b623", 最后一个不可逆区块的哈希值，用于验证区块的完整性。

"head block id": "075bcd4e1d7015dd9c00e990f852a679551c062b775db55a415e541f682693e4", 最新区块的哈希值，也称为区块头哈希，用于追踪链的增长。

"head block time": "2023-10-27T10:00:00.000", 最新区块生成的时间戳，通常以 ISO 8601 格式表示。

"head block producer": "eosio", 生成最新区块的区块生产者（也称为验证者或矿工）的名称。

"virtual block cpu limit": 200000, 每个虚拟区块的 CPU 使用上限，用于限制智能合约的计算资源消耗。

"virtual block net limit": 2097152, 每个虚拟区块的网络带宽使用上限，同样用于限制智能合约的网络资源消耗。

"block cpu limit": 199900, 实际区块的 CPU 使用上限，此限制略低于虚拟区块的限制。

"block net limit": 2096000, 实际区块的网络带宽使用上限，同样略低于虚拟区块的限制。

"server version string": "v2.1.0-v2.1.0" 节点的完整版本字符串，包含更详细的版本信息。 }

2. get_block

该接口的功能是查询并返回区块链中特定区块的详细信息。通过指定区块的高度或哈希值，可以检索该区块包含的交易、时间戳、区块头等关键数据。此接口对于区块链浏览器、数据分析平台以及需要验证交易状态的应用至关重要。

具体来说， get_block 接口通常会返回以下信息：

  • 区块头 (Block Header): 包含区块的元数据，例如：
    • 区块哈希 (Block Hash): 区块的唯一标识符，通过对区块头进行哈希运算生成。
    • 父区块哈希 (Parent Block Hash): 指向上一个区块的哈希值，构建了区块链的链式结构。
    • 时间戳 (Timestamp): 区块被创建的时间。
    • 难度目标 (Difficulty Target): 用于调整挖矿难度，确保区块产生的速度稳定。
    • Nonce: 矿工在工作量证明过程中使用的随机数。
    • Merkle 根 (Merkle Root): 区块中所有交易哈希值的根，用于快速验证交易是否包含在区块中。
    • 版本号 (Version): 区块协议的版本号。
  • 交易列表 (Transactions): 包含区块中所有交易的详细信息，包括：
    • 交易哈希 (Transaction Hash): 交易的唯一标识符。
    • 输入 (Inputs): 交易的输入，通常指向之前交易的输出。
    • 输出 (Outputs): 交易的输出，包含接收者的地址和金额。
    • 手续费 (Fee): 矿工因打包该交易而收取的费用。
    • 锁定时间 (Locktime): 用于延迟交易执行的时间戳或区块高度。
  • 区块高度 (Block Height): 区块在区块链中的位置。
  • 区块大小 (Block Size): 区块的大小（以字节为单位）。

在实际应用中，开发者可以通过 get_block 接口来获取区块的详细信息，进行数据分析、交易验证以及构建区块链应用。 例如，可以利用该接口构建区块链浏览器，让用户可以方便地查看区块和交易的信息。 也可以使用它来监控区块链的状态，检测异常交易和事件。

请求方式: POST 请求地址: /v1/chain/get_block

请求体:

请求体需要包含一个名为 block num or_id 的参数，用于指定要查询的区块。该参数可以接受两种类型的值：区块高度（整数）或区块哈希（十六进制字符串）。

使用区块高度：

如果您知道要查询的区块的高度，可以将 block num or_id 设置为一个整数。例如，以下请求体将查询高度为 123456789 的区块： 

{
  "blocknumor_id": 123456789
}

使用区块哈希：

如果您知道要查询的区块的哈希值，可以将 block num or_id 设置为一个十六进制字符串。区块哈希是一个唯一标识符，可以从之前的区块查询结果或其他区块链浏览器中获取。例如，以下请求体将查询哈希值为 "075bcd4e1d7015dd9c00e990f852a679551c062b775db55a415e541f682693e4" 的区块： 

{
  "blocknumor_id":  "075bcd4e1d7015dd9c00e990f852a679551c062b775db55a415e541f682693e4"
}

注意事项：

  • 请确保区块高度是一个有效的整数。
  • 请确保区块哈希是一个有效的十六进制字符串，并且其长度与区块链使用的哈希算法的输出长度相匹配（通常为 64 个字符）。
  • 如果提供的 block num or_id 既不是有效的区块高度也不是有效的区块哈希，API 将返回一个错误。
响应示例: (包含区块头、交易等详细信息，这里省略)

3. get_account

该接口， get_account ，允许开发者检索并获取区块链网络中特定账户的详细信息。通过提供账户地址作为输入参数，该接口能够返回与该账户关联的各种属性和状态，例如账户余额、交易历史、已部署合约、以及其他相关元数据。这为开发者提供了深入了解账户活动和状态的能力，是构建区块链应用程序、进行数据分析和执行审计任务的关键组成部分。

具体来说，返回的信息可能包括但不限于：

  • 账户地址： 用于唯一标识账户的公钥哈希值。
  • 账户余额： 当前账户持有的加密货币数量，通常以最小单位（例如，Wei）表示。
  • 交易计数器 (Nonce)： 一个递增的整数，用于防止重放攻击，确保每笔交易的唯一性。
  • 代码哈希 (Code Hash)： 如果账户是一个智能合约，则该字段包含合约代码的哈希值，用于验证合约的完整性。
  • 存储哈希 (Storage Hash)： 代表账户存储状态的哈希值，用于验证存储数据的完整性。
  • 其他元数据： 根据区块链平台的具体实现，可能包含其他账户相关的元数据，例如创建时间、权限设置等。

调用 get_account 接口需要提供有效的账户地址作为参数。无效或不存在的地址可能导致错误或返回空结果。 开发者应仔细验证输入地址的正确性，并妥善处理可能出现的异常情况。不同的区块链平台可能对账户地址的格式和验证规则有所不同，开发者需要参考相应的文档进行适配。

请求方式: POST 请求地址: /v1/chain/get_account

请求体:

在与区块链交互时，请求体是至关重要的组成部分，它承载了客户端向节点发送的具体指令和数据。对于获取账户信息的场景，一个典型的请求体可能如下所示： 

{
  "account_name":  "eosio"
}

字段详解：

  • account_name : 这是请求的核心参数，指定了需要查询信息的账户名称。在此例中， "eosio" 代表EOS区块链上的一个特定账户。账户名通常是一个字符串，遵循特定的命名规则（例如，长度限制、字符集限制等），不同区块链平台可能有不同的规定。确保提供的账户名是有效的，否则节点可能会返回错误。

补充说明：

  • 实际应用中，请求体可能会包含更多字段，以支持更复杂的查询或操作。例如，可能需要指定要查询的具体账户信息类型（如余额、权限等）。
  • 请求体通常采用JSON（JavaScript Object Notation）格式，这是一种轻量级的数据交换格式，易于阅读和解析。
  • 不同区块链项目使用的字段名称和格式存在差异。请务必参考目标区块链的官方API文档，确保请求体格式符合要求。
  • 发送请求时，通常会使用HTTP POST方法，并将请求体作为POST请求的数据部分发送到区块链节点的API端点。

响应示例:

以下 JSON 对象展示了一个账户信息的响应示例，常用于区块链节点查询，例如 EOSIO 链。

{ "account name": "eosio", "head block num": 123456789, "head block time": "2023-10-27T10:00:00.000", "privileged": true, "last code update": "1970-01-01T00:00:00.000", "created": "2018-06-01T12:00:00.000", "core liquid balance": "1000000.0000 EOS", "ram quota": 1048576, "net weight": 1000, "cpu weight": 1000, "net limit": { "used": 0, "available": 1000000, "max": 1000000 }, "cpu limit": { "used": 0, "available": 1000000, "max": 1000000 }, "ram_usage": 12345 }

字段解释：

account_name : 账户名称，例如 "eosio" 。

head_block_num : 账户所在的区块链的最新区块高度，表示区块链当前的进度。数值越高，区块链越新。

head_block_time : 账户所在的区块链的最新区块时间戳，例如 "2023-10-27T10:00:00.000" ，符合 ISO 8601 格式。

privileged : 布尔值，指示账户是否拥有特权。 true 表示拥有， false 表示没有。特权账户通常拥有更高的权限，例如修改系统参数等。

last_code_update : 账户代码最后一次更新的时间，例如 "1970-01-01T00:00:00.000"。如果账户从未更新过代码，通常显示为一个初始时间戳。

created : 账户创建的时间，例如 "2018-06-01T12:00:00.000"。

core_liquid_balance : 账户的 EOS 代币余额，例如 "1000000.0000 EOS"。这是账户可直接使用的代币数量。

ram_quota : 账户的 RAM 配额，单位为字节。RAM 用于存储账户数据，例如合约状态。 例如1048576字节，即 1MB。

net_weight : 账户抵押的 NET 资源数量，影响账户的网络带宽限制。数值越高，可用的网络带宽越大。 例如1000。

cpu_weight : 账户抵押的 CPU 资源数量，影响账户的 CPU 使用限制。数值越高，可用的 CPU 时间越多。 例如1000。

net_limit : 账户的网络资源使用限制，包含 used （已使用）、 available （可用）和 max （最大值）三个字段。 单位通常是微秒。

cpu_limit : 账户的 CPU 资源使用限制，包含 used （已使用）、 available （可用）和 max （最大值）三个字段。 单位通常是微秒。

ram_usage : 账户当前使用的 RAM 数量，单位为字节。

4. get_currency_balance

该API接口用于查询指定账户持有的特定加密通证余额。通过提供账户地址和通证标识符（例如，通证合约地址或符号），你可以精确地检索到该账户在该通证上的可用余额。此接口对于构建钱包应用、交易平台和资产管理工具至关重要，它允许开发者实时监控用户的资产状况。

更具体地说，此接口通常需要以下参数：

  • 账户地址： 需要查询余额的钱包地址或用户标识符。务必确保提供的地址格式正确，且与底层区块链网络兼容。
  • 通证标识符： 用于唯一标识要查询余额的通证。这通常是通证的合约地址（例如，ERC-20 通证在以太坊上的地址）或预定义的通证符号（例如，BTC、ETH、USDT）。

返回值通常是表示通证余额的数值。请注意，余额通常以最小单位表示（例如，以太坊中的 Wei），因此可能需要进行转换以获得更易于理解的单位（例如，以太币）。返回值可能还包含其他相关信息，例如通证的小数位数。

在使用此接口时，务必考虑安全性。例如，验证API密钥的有效性，防止未经授权的访问。同时，处理潜在的错误情况，例如无效的账户地址或通证标识符，并提供适当的错误处理机制。

请求方式: POST 请求地址: /v1/chain/get_currency_balance

请求体:

请求体用于向区块链节点或API服务器传递数据，以便执行特定的操作。以下是一个示例请求体，用于查询特定代币的信息： 

{
   "code": "eosio.token",
   "account":  "eosio",
   "symbol": "EOS"
}

字段解释：

  • code : 这个字段指定了智能合约的名称，该智能合约负责管理所查询的代币。 在这个例子中， "eosio.token" 是一个常见的代币合约名称，负责在EOSIO区块链上创建和管理代币。
  • account : 这个字段指定了拥有代币合约的账户名称。 在这个例子中， "eosio" 账户拥有 "eosio.token" 合约的权限。 某些情况下，代币合约可能部署在其他账户下，因此需要根据实际情况修改此字段。
  • symbol : 这个字段指定了需要查询的代币符号。 在这个例子中， "EOS" 代表EOS代币。 代币符号是代币的唯一标识符，用于区分不同的代币。 需要注意的是，代币符号通常采用大写字母表示。

请求体用法：

这个请求体通常用于向区块链节点的 /v1/chain/get_currency_stats API端点发送POST请求，以获取关于EOS代币的统计信息，例如总发行量、最大发行量和流通量等。 不同的API端点可能需要不同的请求体格式，因此需要参考具体的API文档。

注意事项：

  • 请求体通常采用JSON格式，确保JSON格式的正确性。 错误的JSON格式可能导致请求失败。
  • 确保提供的 code , account 和 symbol 信息与实际情况相符。 任何错误的信息都可能导致查询失败或返回错误的结果。
  • 根据不同的API端点，请求体可能需要包含其他字段。 仔细阅读API文档，确保请求体包含所有必需的字段。

响应示例:

以下示例展示了API可能返回的一种数据格式，代表着用户持有的加密货币资产信息。该信息以JSON数组的形式呈现，数组中的每一个元素代表一种加密货币的持有情况。

[ "1000000.0000 EOS" ]

解读：

在这个例子中，数组只包含一个元素，即字符串 "1000000.0000 EOS" 。该字符串由两部分组成，中间用空格分隔：

  • 1000000.0000 ：代表持有的EOS数量，小数点后四位表示精度。这是一个浮点数，表明EOS的持有量为一百万个单位。
  • EOS ：代表加密货币的符号，这里指的是EOS。

数据格式注意事项：

  • API返回的数据可能包含多个元素，每个元素代表用户持有的不同加密货币。例如： ["10.0000 BTC", "500.0000 ETH", "1000000.0000 EOS"]
  • 数量的精度可能因不同的加密货币而异。一些加密货币可能支持更高的精度。
  • 加密货币的符号可能会根据交易所或API提供商而有所不同。
  • 在实际应用中，需要对返回的字符串进行解析，提取数量和符号信息。
  • 这种简单格式可能只适用于某些API，更复杂的API可能返回包含更多信息的JSON对象，例如： [{"currency": "BTC", "amount": "10.0000"}, {"currency": "ETH", "amount": "500.0000"}]

5. get_table_rows

get_table_rows 接口是区块链数据检索的关键方法，用于高效地从EOSIO或其他兼容区块链上的智能合约中提取特定表的数据记录。 该接口允许开发者根据合约名称、表名称以及作用域等参数，精确地查询并获取存储在区块链状态数据库中的数据。

功能概述： 该接口的核心功能是从指定合约的指定数据表中检索数据。它通过提供灵活的查询参数，允许开发者根据特定条件过滤和排序结果，从而满足各种复杂的数据查询需求。 例如，可以根据主键范围、索引值或其他过滤条件来获取数据。

参数详解： 使用 get_table_rows 接口时，需要提供以下关键参数：

  • code : 部署智能合约的账户名。 例如，如果智能合约部署在名为 "mycontract" 的账户下，则 code 值为 "mycontract"。
  • scope : 表的作用域。 作用域可以理解为表数据的命名空间，它允许合约在同一张表中存储不同上下文的数据。 例如，在处理多个用户的数据时，每个用户可以拥有独立的作用域，从而避免数据冲突。
  • table : 要查询的数据表的名称。 合约通常包含多个表，每个表用于存储不同类型的数据。
  • lower_bound (可选): 查询结果的下限。 通常与主键或索引一起使用，用于指定查询范围的起始位置。
  • upper_bound (可选): 查询结果的上限。 与 lower_bound 结合使用，用于定义查询范围的结束位置。
  • limit (可选): 返回的最大行数。 通过设置 limit ，可以控制每次查询返回的数据量，避免一次性返回大量数据导致性能问题。
  • key_type (可选): 键类型，用于指定 index_position 的类型。 默认为 "i64"，表示 64 位整数。
  • index_position (可选): 要使用的索引的位置。 如果表定义了二级索引，则可以通过 index_position 指定要使用的索引。
  • reverse (可选): 是否按相反的顺序返回结果。 默认为 false ，表示按升序返回结果。 设置为 true 时，按降序返回结果。
  • show_payer (可选): 是否显示付款人。 默认为 false ，表示不显示付款人。 设置为 true 时，将在返回结果中包含每个数据记录的付款人信息。

使用场景： get_table_rows 接口在区块链应用开发中具有广泛的应用场景，例如：

  • 查询用户信息： 从存储用户信息的表中检索特定用户或一组用户的数据。
  • 获取产品列表： 从存储产品信息的表中获取产品列表，并根据价格、销量等条件进行排序和过滤。
  • 查询交易记录： 从存储交易记录的表中查询特定账户的交易历史。
  • 游戏数据查询： 在区块链游戏中，可以利用该接口查询玩家的资产、等级、成就等信息。

注意事项：

  • 频繁调用 get_table_rows 接口可能会对区块链节点的性能产生影响。 建议合理设置 limit 参数，并尽可能利用索引来优化查询性能。
  • 在使用二级索引时，需要确保 key_type 和 index_position 参数与表结构的定义一致。
  • 对于大型数据表，可以考虑使用分页查询的方式，分批获取数据。
请求方式: POST 请求地址: /v1/chain/get_table_rows

请求体:

请求体（Request Body）通常采用JSON格式，用于向区块链节点或API端点传递查询参数或执行特定操作的指令。以下是一个示例请求体，用于查询EOSIO区块链上的代币账户信息： 


{
   "code": "eosio.token",
  "scope": "eosio",
  "table": "accounts",
  "lower_bound": "eosio",
   "upper_bound": "eosio",
  "limit": 10,
  "": true
}

字段解释：

  • code : 合约账户名，指定包含目标数据的智能合约账户。在本例中， "eosio.token" 代表EOSIO官方代币合约。
  • scope : 作用域，通常与合约账户名相同或指定合约内的特定命名空间。这里 "eosio" 是指在该合约账户的eosio作用域内查找数据。
  • table : 数据表名，指定要查询的数据表。这里 "accounts" 是存储账户余额信息的表。
  • lower_bound : 查询下限，用于分页或指定查询范围。指定从哪个账户名称开始查询，例如从账户名 "eosio" 开始。
  • upper_bound : 查询上限，与 lower_bound 配合使用，限定查询范围。指定到哪个账户名称结束查询，例如到账户名 "eosio" 结束，如果和 lower_bound 相同，则只查询一个账户。
  • limit : 返回结果数量限制，指定最多返回多少条数据。这里 10 表示最多返回10个账户信息。
  • : 布尔值，指示是否将结果以JSON格式返回。 true 表示返回JSON格式的数据。某些API可能需要显式指定此参数。

这个请求体的作用是从 eosio.token 合约的 accounts 表中查询 eosio 账户的信息，结果限制为10条，并以JSON格式返回。

响应示例:

服务器返回的响应数据通常采用JSON格式，便于解析和处理。以下示例展示了账户余额查询的响应结构： 

  
    {
      "rows": [
        {
          "balance": "1000000.0000 EOS"
        }
      ],
      "more": false
    }

字段解释:

  • rows: 一个数组，包含账户余额信息。在实际应用中，如果涉及分页查询，可能包含多个账户的余额信息。
  • rows[0].balance: 账户余额，格式为 "数量 币种"。例如，"1000000.0000 EOS" 表示该账户拥有 1000000 个 EOS 代币。 余额数值通常精确到小数点后四位，以满足加密货币交易的精度要求。
  • more: 布尔值，指示是否还有更多数据需要获取。如果为 true ，表示服务端存在更多数据，客户端可以通过分页参数继续请求。如果为 false ，表示所有数据已返回。

注意事项:

  • 实际应用中，响应可能包含更多字段，例如账户ID、创建时间等。
  • 客户端应根据 more 字段的值，决定是否继续发送分页请求。
  • balance 字段返回的币种信息需要与请求时指定的币种一致。

使用 History API 查询历史交易

要深入了解区块链上的交易历史，EOSIO 提供了强大的 History API。此 API 允许开发者查询并检索关于特定账户、代币转移以及智能合约交互的历史数据。为了开始使用 History API，必须确保在 nodeos 区块链节点的配置文件中正确启用 history_plugin 。该插件负责索引和维护历史交易数据，从而使得快速高效的查询成为可能。

启用 history_plugin 之后，可以通过以下一组 API 接口来访问丰富的历史信息。这些接口提供了不同的查询选项，以满足各种开发需求。常见的接口包括：

  • get_account_history: 该接口允许你检索特定账户的所有相关交易记录。你可以通过指定账户名称，并设置起始位置和结果数量，来分页浏览账户的历史操作。这对于跟踪账户活动、分析交易模式以及审计财务记录至关重要。
  • get_transaction: 如果你已知某个交易的 ID（Transaction ID），可以使用此接口来获取该交易的完整详细信息。这包括交易的状态、包含的操作、签名以及其他相关元数据。
  • get_key_accounts: 通过提供一个公钥，此接口可以返回与该公钥关联的所有账户名称。这对于识别与特定身份相关联的所有账户非常有用。
  • get_controlled_accounts: 此接口允许你通过控制账户的账户名找到该账户控制的所有账户，适用于构建层次化账户体系的应用场景。

合理使用 History API，开发者可以构建出功能强大的应用程序，例如区块链浏览器、交易分析工具、审计系统以及其他需要访问历史交易数据的应用。在使用这些接口时，务必注意速率限制和数据分页，以避免对区块链节点造成过大的负担。

1. get_transaction

该接口 get_transaction 旨在检索区块链网络中特定交易的详细信息。通过提供唯一的交易哈希值（Transaction Hash），该接口能够返回与该交易相关的各种属性，例如：

  • 交易哈希 (Transaction Hash): 交易的唯一标识符，通常是一个十六进制字符串。
  • 区块哈希 (Block Hash): 包含此交易的区块的哈希值。
  • 区块高度 (Block Height): 区块在区块链中的位置，从创世区块开始计数。
  • 时间戳 (Timestamp): 交易被添加到区块中的时间。
  • 发送方地址 (Sender Address): 发起交易的钱包或账户地址。
  • 接收方地址 (Receiver Address): 交易资金发送到的钱包或账户地址。
  • 交易金额 (Amount): 转移的加密货币数量，以最小单位（例如，比特币的 Satoshi）表示。
  • 交易费用 (Transaction Fee): 矿工或验证者收取的交易处理费用。
  • 交易状态 (Transaction Status): 指示交易是否已成功确认 (Confirmed) 或仍在等待确认 (Pending)。
  • 输入 (Inputs): 此交易使用的UTXO（Unspent Transaction Outputs）列表，即未花费的交易输出。
  • 输出 (Outputs): 此交易创建的UTXO列表，代表新的加密货币所有权。
  • 确认数 (Confirmations): 该交易被包含的区块之后的区块数量，用于衡量交易的可靠性。确认数越高，交易被逆转的可能性越低。
  • 交易类型 (Transaction Type): 例如，标准交易、多重签名交易、合约调用等。
  • 交易数据 (Transaction Data/Payload): 交易中包含的额外数据，例如智能合约的函数调用数据或文本信息。

通过 get_transaction 接口获取的信息对于追踪交易状态、验证交易详情以及审计区块链活动至关重要。应用程序可以使用此接口来确认付款是否成功、监控钱包余额变化以及分析区块链上的数据流动。

请求方式: POST 请求地址: /v1/history/get_transaction

请求体:

请求体采用JSON格式，用于向服务器发送特定的数据以执行操作。以下是一个示例请求体，其中包含一个唯一的ID标识符： 

{
   "id": "a1b2c3d4e5f678901234567890abcdef01234567890abcdef0123456789abcdef"
}

字段说明：

  • id: 这是一个字符串类型的字段，用于唯一标识一个请求或者一个特定的资源。该ID通常是一个长度较长的十六进制字符串，例如UUID或者经过哈希算法处理后的结果。 长度为64个字符的十六进制字符串，具有高随机性和唯一性，用于确保不同请求之间的区分。

使用场景示例：

  • 数据查询： 当客户端需要查询特定ID对应的数据时，可以将该ID作为请求体的一部分发送给服务器。
  • 交易确认： 在区块链交易中，`id` 可以是交易哈希值，用于确认交易是否已被处理。
  • 状态更新： 用于唯一标识需要更新的对象，例如更新用户配置文件或修改订单状态。
  • 消息溯源: 在分布式系统中，`id` 可用于追踪消息的传递路径和处理状态。

注意事项：

  • `id` 的生成必须保证唯一性，避免不同请求之间发生冲突。
  • 服务器端需要对接收到的 `id` 进行校验，防止恶意请求。
  • 根据具体的业务需求，`id` 的格式和长度可能会有所不同。
响应示例: (包含交易的详细信息，这里省略)

2. get_actions

该接口 get_actions 用于检索和获取特定账户在区块链上执行的所有历史操作记录。这些操作记录包含了账户参与的各种交易和状态变更，例如代币转移、智能合约调用、资源抵押与赎回等。通过指定账户名称和可选的查询参数，可以获取该账户在特定时间段内的所有活动。

更具体地说，返回的数据通常包含每个操作的详细信息，包括：

  • 操作类型 (action type): 标识操作的具体种类，例如 transfer (代币转移) 或 delegatebw (资源委托)。
  • 操作发起者 (account name): 执行此操作的账户名称。
  • 操作时间戳 (timestamp): 操作被记录到区块链上的确切时间。
  • 交易 ID (transaction ID): 包含此操作的交易的唯一标识符。
  • 操作数据 (action data): 与操作相关的具体数据，例如转移的代币数量、接收账户、抵押的 CPU 和 NET 资源等。此数据通常以 JSON 格式呈现。
  • 授权信息 (authorization): 执行此操作所需的权限信息，包括所需的账户和权限级别。

get_actions 接口对于追踪账户活动、审计交易历史以及构建与区块链交互的应用程序至关重要。开发者可以利用这些信息来分析用户行为、监控账户余额变化、验证交易状态等。通过分页参数，可以获取大量操作记录，并按照时间顺序进行排序，方便进行历史数据分析。

请求方式: POST 请求地址: /v1/history/get_actions

请求体:

请求体用于指定查询账户历史记录的参数。以下是一个请求体示例，其中包含了账户名称、位置偏移量以及记录数量等关键信息。 

    
    {
       "account_name": "eosio",
      "pos":  -1,
       "offset": -20
    }

参数详解：

  • account_name : 指定需要查询历史记录的账户名称。例如， "eosio" 表示查询 eosio 账户的相关记录。务必确保账户名称的准确性，否则将无法获取有效结果。
  • pos : 定义查询起始位置。 -1 通常表示从最新的交易记录开始。可以使用具体的交易ID或序列号来指定起始位置，以便更精确地定位查询范围。如果不指定具体值，默认为最新位置。
  • offset : 指定从起始位置向前（或向后）追溯的记录数量。 -20 表示从起始位置向前追溯20条记录。正数表示向后追溯。这个参数决定了返回记录的范围大小，可以根据需要调整。如果请求的历史记录超过系统限制，可能会被截断。

注意事项：

  • pos 和 offset 的组合使用可以实现灵活的历史记录查询。例如，可以通过调整这两个参数来分页获取大量的历史记录。
  • 如果指定的 account_name 不存在，或者 pos 和 offset 超出有效范围，API可能会返回错误信息。请仔细检查请求参数，并处理可能出现的错误情况。
  • 返回结果的顺序取决于区块链的具体实现。一般而言，历史记录按照交易发生的先后顺序排列，但具体情况可能因不同的区块链平台而异。
  • 实际使用中，应根据具体的API文档调整参数，部分区块链可能使用不同的参数名称或格式。

发送交易 (Transaction)

发送交易至区块链网络需要经过签名的过程，以验证交易的合法性和发起者的身份。签名过程涉及使用私钥对交易数据进行加密，生成唯一的数字签名。未经签名的交易将被视为无效，无法被区块链网络接受和处理。通常，开发者会选择使用诸如 `cleos` 这样的命令行工具，或者集成专门的签名库到应用程序中，例如EOS SDK，来完成交易的签名。这些工具和库提供了便捷的API和安全的环境，用于管理私钥和执行签名算法。签名算法的选择取决于区块链平台的具体要求，例如EOSIO通常使用K1或R1曲线的椭圆曲线数字签名算法 (ECDSA)。

交易签名完成后，便可以使用 push_transaction API接口将该交易广播到区块链网络。 push_transaction 接口接收包含签名信息的完整交易数据，并将其提交给区块链节点进行验证和处理。区块链节点会对交易的签名进行验证，确认其有效性后，将交易打包到区块中，并添加到区块链中。需要注意的是，不同的区块链平台可能提供不同名称和参数的交易提交接口，例如以太坊使用 `eth_sendRawTransaction`。开发者需要查阅相应区块链平台的文档，了解具体的API调用方式和参数要求。在发送交易前，需要确保交易费用（gas fee）设置合理，以确保交易能够被及时处理。

请求方式: POST 请求地址: /v1/chain/push_transaction 请求体: (包含签名后的交易数据)

例如，使用 cleos 创建一个简单的转账交易：

bash cleos push transaction '{ "expiration": "2023-10-28T00:00:00", "refblocknum": 12345, "refblockprefix": 456789, "maxnetusagewords": 0, "maxcpuusagems": 0, "delaysec": 0, "contextfreeactions": [], "actions": [{ "account": "eosio.token", "name": "transfer", "authorization": [{ "actor": "sender", "permission": "active" }], "data": { "from": "sender", "to": "receiver", "quantity": "1.0000 EOS", "memo": "test transfer" } }], "transactionextensions": [] }'

注意：以上 cleos 命令仅为示例，实际使用时需要替换为正确的账户名、私钥等信息，并且需要先获取 ref_block_num 和 ref_block_prefix。 通常使用 get_info 接口获取。

常用开发工具和库

  • Cleos: EOS 命令行接口，是开发者的瑞士军刀，它允许你直接与 EOSIO 区块链互动。利用 Cleos，你可以创建和管理钱包，方便地存储和控制你的 EOS 账户私钥；部署智能合约，将你的代码上传到链上并使其生效；以及发送交易，执行合约中的函数并改变链的状态。Cleos 还支持查询区块链信息，例如账户余额、合约数据和区块信息，是调试和监控 EOSIO 应用不可或缺的工具。
  • EOSJS: JavaScript 库，是构建基于浏览器的 EOSIO 应用的首选。它提供了一组 API，允许你从 JavaScript 环境连接到 EOSIO 区块链。使用 EOSJS，你可以创建签名交易，这意味着你的应用可以在客户端完成交易的签名过程，而无需将私钥暴露在服务器端，从而提高安全性。EOSJS 还支持读取区块链数据，例如账户信息、合约状态和交易历史，使其成为构建用户界面和数据可视化的理想选择。
  • EOSpy: Python 库，为 Python 开发者提供了与 EOSIO 区块链交互的强大工具。EOSpy 提供了与 EOSJS 类似的功能，但针对 Python 环境进行了优化。你可以使用 EOSpy 创建和管理账户，部署智能合约，以及发送交易。EOSpy 还支持异步操作，这使得它非常适合构建需要高性能和并发性的 EOSIO 应用。它还提供了方便的工具来序列化和反序列化 EOSIO 数据，简化了与链上数据的交互。

错误处理

当API调用失败时，服务器会返回一个包含详细错误信息的JSON响应。开发者必须认真解析这些错误信息，并根据其具体含义采取适当的应对措施，以确保应用程序的稳定性和可靠性。 理解并正确处理错误是构建健壮的加密货币应用程序的关键环节。

以下列出了一些常见的HTTP状态码和特定于区块链平台的错误代码，以及它们可能代表的含义和潜在的解决方案：

  • 400 Bad Request: 此错误通常表示客户端发送的请求格式不正确或包含无效参数。开发者应仔细检查请求的URL、请求头、请求体以及所有参数是否符合API文档的要求。可能的原因包括参数类型错误、缺少必需参数、参数值超出范围等。仔细阅读API文档并使用有效的请求数据重试。
  • 500 Internal Server Error: 这是一个通用的服务器端错误，表明服务器在处理请求时遇到了未预料到的问题。这可能由于服务器内部的软件bug、数据库连接问题、资源耗尽或其他未处理的异常情况导致。开发者通常无法直接解决此问题，但可以尝试稍后重新发送请求，或联系API提供商寻求帮助。在报告此类错误时，提供详细的请求信息和时间戳有助于服务器管理员进行故障排除。
  • 3040001 Action validate exception: 此错误表明在执行交易操作时，区块链节点在验证交易的有效性时失败。这通常与权限控制或智能合约逻辑有关。可能的原因包括：
    • 账户权限不足，无法执行特定操作。
    • 智能合约的逻辑存在缺陷，导致交易不满足合约的约束条件。
    • 交易所需的资产不足（例如，gas费用或代币余额）。
    开发者需要仔细检查账户的权限设置，并审查相关的智能合约代码，以确定错误的根本原因。确保交易包含足够的gas来完成操作。
  • 1000000 Assert Exception: 此错误表示智能合约在执行过程中触发了断言失败。断言是一种用于在代码中添加安全检查的机制，当断言条件为假时，合约会立即停止执行并抛出异常。这通常表明合约代码中存在逻辑错误，导致某些预期条件未得到满足。开发者需要仔细审查智能合约的代码，特别是在断言失败的位置附近，以找出导致断言失败的原因。使用调试工具可以帮助开发者追踪变量的值并理解合约的执行流程。

安全注意事项

  • 保护私钥： 私钥是控制加密货币账户和数字资产的绝对控制权的关键，务必采取一切必要措施妥善保管。绝不要将私钥存储在容易泄露或被恶意访问的不安全环境中，例如公共代码仓库、未加密的配置文件、电子邮件、聊天记录，或者任何可能被截获或未经授权访问的在线平台。强烈建议使用硬件钱包或多重签名（Multi-Sig）钱包来增加私钥的安全性，并定期备份私钥至离线安全介质，例如加密的USB驱动器或纸质备份，并将备份存放在物理安全的地方。
  • 验证 API 响应： 在处理来自交易所、区块链节点或其他加密货币相关服务的API响应之前，必须对数据的完整性和真实性进行严格验证。验证的内容包括但不限于：检查数字签名以确认数据来源的可靠性，验证返回数据的格式和类型是否符合预期，以及确认所有数值都在合理的范围内。警惕任何异常或未经授权的数据修改，并采取适当的措施来防止恶意数据注入或中间人攻击。
  • 使用 HTTPS： 通过HTTPS（安全超文本传输协议）协议进行所有API调用，HTTPS使用TLS/SSL加密通道，可以有效防止数据在传输过程中被窃听或篡改。确保API端点使用有效的SSL/TLS证书，并且客户端代码强制使用HTTPS连接，避免使用不安全的HTTP协议。定期检查证书的有效性，并及时更新以应对安全漏洞。
  • 速率限制： 为了防止恶意攻击，如拒绝服务(DoS)攻击或暴力破解，对API调用实施速率限制至关重要。速率限制是指限制特定时间段内允许的API调用次数，例如每分钟或每小时的最大请求数。根据API的使用情况和服务器负载进行合理的速率限制设置，并实施适当的错误处理机制，以便在达到速率限制时优雅地处理请求，例如返回HTTP 429状态码（Too Many Requests）。还可以考虑使用更高级的流量控制技术，例如令牌桶算法或漏桶算法，以实现更精细的速率控制。

EOS API 提供了一套强大的工具，可以用于构建各种去中心化应用。 通过本文的介绍，希望能帮助开发者更好地理解和使用 EOS API，开发出更加安全、高效的 EOS 应用。

The End

发布于：2025-03-08，除非注明，否则均为币看点原创文章，转载请注明出处。