EOS钱包API终极指南：新手也能快速上手！

柚子币钱包API使用方法详解

1. 简介

柚子币（EOS），又名EOSIO，是一种旨在实现高性能、低延迟和可扩展性的区块链操作系统。其目标是提供一个类似于操作系统的平台，允许开发者构建和部署去中心化应用程序（DApps）。EOS钱包API是开发者与EOS区块链交互的关键接口，它提供了一系列功能强大的工具，用于管理EOS账户、进行交易、查询区块链数据等操作。

本详细指南旨在深入解析EOS钱包API的使用方法，旨在帮助开发者快速掌握其核心概念和技术细节，从而能够高效地构建和维护基于EOS区块链的应用程序。我们将全面覆盖EOS钱包API的各个方面，从基本的密钥管理和账户操作，到复杂的交易构建、签名和广播流程，以及区块链数据的查询和分析。我们还将深入探讨权限管理、资源抵押（Stake）、RAM购买和赎回等高级主题。

为了便于理解和实践，本文档将提供大量的示例代码片段，涵盖多种编程语言（如JavaScript、Python等），并提供详细的注释和解释。这些示例代码将演示如何使用EOS钱包API执行常见的操作，例如创建账户、转账、抵押资源、部署智能合约等。同时，我们还将讨论常见的错误处理方法和最佳实践，帮助开发者避免常见的陷阱并提高应用程序的健壮性和安全性。

通过阅读本文档，开发者将能够全面了解EOS钱包API的功能和用法，并具备构建和部署基于EOS区块链的应用程序所需的技能和知识。无论您是区块链开发新手，还是经验丰富的开发者，本文档都将为您提供有价值的指导和参考。

2. 环境配置

在使用EOS钱包API之前，配置完善的开发环境至关重要。这涉及到多个关键步骤，包括安装必要的软件依赖库、选择并配置EOS节点连接，以及设置开发工具等。 确保环境配置正确无误是成功使用EOS钱包API的基础。

你需要安装适用于你所使用编程语言的EOS SDK，例如JavaScript的`eosjs`、Python的`eospy`或C++的`eoslib`。 这些SDK通常可以通过包管理器进行安装，如npm (Node.js)、pip (Python) 或 vcpkg (C++)。 安装过程中，请务必参考官方文档，以确保安装的SDK版本与你的EOS网络兼容。

选择一个可用的EOS节点至关重要。你可以选择连接到公用的EOS节点，也可以运行自己的本地节点。 公用节点通常由社区维护，方便快速接入，但可能存在一定的延迟和审查风险。 运行本地节点则可以提供更高的自主性和隐私性，但也需要承担维护成本和技术挑战。 如果选择公用节点，务必选择稳定可靠且信誉良好的服务提供商。 如果选择本地节点，需要下载EOSIO软件并进行配置，同步区块链数据，并确保节点持续运行。

第三，你需要配置你的开发环境，使其能够与所选的EOS节点进行通信。 这通常涉及到设置API端点URL、链ID、以及任何必要的认证信息。 这些信息通常可以在EOS节点的文档或API提供商处找到。 确保API端点URL正确无误，链ID与目标EOS网络匹配，并且你拥有访问API所需的有效凭证。

建议使用诸如Postman或Insomnia等API测试工具，来验证你的环境配置是否正确。 通过这些工具，你可以发送简单的API请求到EOS节点，并检查返回结果是否符合预期。 如果API请求成功返回数据，则表明你的环境配置正确。 如果API请求失败，则需要检查你的配置信息，并参考EOS节点的文档或API提供商的帮助文档进行调试。

2.1 安装依赖

在JavaScript环境下进行EOSIO区块链开发，推荐使用 eosjs 作为官方维护且功能完善的JavaScript SDK。 eosjs 提供了与EOSIO区块链节点交互的各种API，包括账户管理、交易签名、合约部署和调用等功能。

可以通过npm（Node Package Manager）进行安装，确保你的开发环境中已经安装了Node.js和npm。使用以下命令安装最新版本的 eosjs ：

npm install eosjs@latest

此命令会将 eosjs 及其依赖项安装到你的项目目录下的 node_modules 文件夹中。 @latest 标签确保安装的是最新稳定版本。安装完成后，你可以在你的JavaScript代码中引入并使用 eosjs 。

对于Python开发者，可以选择使用 eospy 或 pyeos 这两个Python库。 eospy 是一个轻量级的EOSIO区块链交互库，而 pyeos 则提供了更全面的功能，包括智能合约开发和部署。

使用pip（Python包管理器）可以轻松安装 eospy 。执行以下命令：

pip install eospy

这将会从Python Package Index (PyPI) 下载并安装 eospy 及其相关的依赖项。安装成功后，你就可以在Python脚本中导入 eospy 模块，并开始与EOSIO区块链进行交互。

使用Python的pyeos库

想要在Python环境中使用EOS区块链， pyeos 库是一个常用的选择。 使用pip包管理器可以轻松安装：

pip install pyeos

安装完成后，你就可以在Python代码中引入并使用 pyeos 库提供的各种功能，例如连接EOS节点、创建交易、部署合约、查询区块链数据等。 具体使用方法可以参考 pyeos 的官方文档或相关教程。

其他编程语言的EOS SDK

除了Python之外，许多其他编程语言也提供了相应的EOS SDK，方便开发者使用自己熟悉的语言进行EOS区块链应用的开发。 例如，Java开发者可以使用 EOSEJava SDK。

EOSEJava 提供了Java语言对EOS区块链的接口，包括交易签名、账户管理、智能合约交互等功能。 开发者可以根据自己的需求选择合适的SDK，并参考相应的文档和示例代码进行开发。

在选择和使用EOS SDK时，需要注意SDK的版本兼容性、功能完整性以及社区活跃度等因素。 选择一个稳定、易用、并有良好社区支持的SDK，可以大大提高开发效率。

2.2 连接节点

与EOS区块链交互的第一步是连接到一个EOS节点。节点是EOS网络中的计算机，存储着区块链的完整副本，并负责处理交易和维护网络安全。您可以选择运行自己的EOS节点，或者利用公共节点提供的服务。运行自己的节点可以提供更高的控制权和隐私性，但需要一定的技术知识和硬件资源。而使用公共节点则更加便捷，许多知名的节点提供商如EOS Nation、Block.one以及其他信誉良好的组织都提供稳定的公共节点服务。

选择一个可靠且稳定的EOS节点对于确保您的应用程序或交易的可靠性和一致性至关重要。节点的性能直接影响到您与区块链交互的速度和成功率。延迟高或经常中断的节点可能会导致交易失败或应用程序出现错误。因此，在选择节点时，应考虑其声誉、地理位置、服务器性能和提供的服务级别协议 (SLA)。

配置节点信息是连接EOS节点的关键步骤。通常，这包括提供节点URL（统一资源定位符），即节点的网络地址，例如 http://api.eosn.io 或 https://mainnet.eos.dfuse.io 。节点URL指向节点提供的API端点，应用程序可以通过该端点与区块链进行通信。

除了节点URL之外，还需要配置链ID。链ID是用于唯一标识特定EOS网络的哈希值。不同的EOS网络（例如主网、测试网）具有不同的链ID。EOS主网的链ID为 aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906 。确保使用正确的链ID，否则您的应用程序将无法与目标网络进行通信。一些钱包和开发工具会自动检测链ID，但也需要手动配置。

3. 密钥管理

EOS 区块链依赖于非对称加密技术，使用公钥和私钥对来控制账户并进行交易。公钥如同银行账号，可以公开给他人用于接收资产，而私钥则类似于银行密码，用于授权交易和证明所有权。对私钥进行妥善管理至关重要，这是保障 EOS 账户安全的基础。任何未经授权的私钥访问都可能导致账户资产被盗。常见的私钥管理方法包括：

• 离线存储（冷存储）： 将私钥存储在与互联网断开连接的硬件设备或纸钱包中，例如硬件钱包、加密U盘或打印的纸质私钥备份。这种方式可以有效防止网络攻击，显著降低私钥泄露的风险。
• 硬件钱包： 专门用于安全存储私钥的物理设备，通常具有PIN码保护和交易确认功能。硬件钱包可以与电脑或手机连接，在进行交易时进行签名，但私钥始终保存在设备内部，不会暴露给外部环境。 Ledger 和 Trezor 是两种常见的硬件钱包。
• 软件钱包： 安装在电脑或手机上的应用程序，用于管理和存储私钥。虽然使用方便，但安全性相对较低，容易受到恶意软件和网络攻击的影响。使用软件钱包时，务必选择信誉良好且经过安全审计的钱包，并采取额外的安全措施，例如启用双因素身份验证。
• 多重签名（Multi-Sig）： 需要多个私钥授权才能完成交易，类似银行联名账户。这种方式可以提高账户的安全性，防止单点故障，即使某个私钥泄露，攻击者也无法单独控制账户。

务必采取适当的安全措施，例如：

• 备份私钥： 将私钥备份到安全的地方，以防止设备丢失或损坏导致私钥丢失。
• 使用强密码： 为保护钱包和硬件设备设置强密码，并定期更换密码。
• 警惕钓鱼攻击： 不要轻易点击不明链接或下载可疑文件，防止私钥被盗。
• 及时更新软件： 定期更新钱包软件和操作系统，以修复安全漏洞。

切记，任何声称可以“找回”私钥的服务都是骗局。私钥一旦丢失，将无法恢复，因此请务必妥善保管您的私钥，并采取有效的安全措施。

3.1 生成密钥对

在区块链开发中，生成密钥对是构建安全应用程序的基础。 eosjs 库，或者其他兼容的工具，例如Scatter或Cleos，都可以用于生成新的密钥对，包括私钥和公钥。 这些密钥对是控制区块链账户和执行交易的关键。

使用 eosjs-ecc 生成密钥对：

以下 JavaScript 代码展示了如何使用 eosjs-ecc 库异步生成新的密钥对。 请确保已经通过 npm 安装了 eosjs-ecc 库 ( npm install eosjs-ecc )。

const ecc = require('eosjs-ecc');

(async () => {
  try {
    const privateKey = await ecc.randomKey();
    const publicKey = ecc.privateToPublic(privateKey);

    console.log('Private Key:', privateKey);
    console.log('Public Key:', publicKey);
  } catch (error) {
    console.error('Error generating key pair:', error);
  }
})();

代码详解：

• require('eosjs-ecc') : 导入 eosjs-ecc 库，该库提供了用于生成密钥对的函数。
• ecc.randomKey() : 此函数异步生成一个新的随机私钥。私钥必须保密，因为它用于签署交易。
• ecc.privateToPublic(privateKey) : 此函数从私钥派生出对应的公钥。公钥可以安全地共享，因为它用于验证交易的签名。
• console.log() : 将生成的私钥和公钥打印到控制台。 注意：在实际应用中，绝对不要将私钥直接打印到控制台，或者以明文形式存储。 应该使用安全的存储机制，例如硬件钱包或加密的软件钱包。
• try...catch : 包含在 try 块中的代码会执行，如果抛出异常，则 catch 块会处理异常，这里主要捕获生成密钥对可能出现的错误。

安全提示：

• 私钥安全： 务必安全地存储私钥。丢失私钥意味着失去对账户的控制权。考虑使用硬件钱包或加密的软件钱包来保护私钥。
• 备份： 创建私钥的备份，并将其存储在安全的地方。
• 避免泄露： 切勿将私钥分享给任何人或将其上传到互联网。
• 随机性： 确保使用强大的随机数生成器来生成私钥。 eosjs-ecc 库使用加密安全的随机数生成器。

通过理解密钥对的生成和安全存储，开发者可以构建更安全、更可靠的区块链应用。

注意： 请务必妥善保管私钥。不要将私钥存储在不安全的地方，例如明文存储在代码中或上传到公共代码仓库。可以使用硬件钱包或其他安全存储方案。

3.2 导入现有密钥

可以使用 eosjs 库导入已存在的私钥，从而允许您使用该私钥签署交易并与区块链进行交互。通过这种方式，您可以利用现有的钱包或密钥管理方案，而无需在应用程序中重新生成或存储私钥。

eosjs 是一个强大的 JavaScript 库，用于与 EOSIO 区块链进行交互。它提供了各种功能，包括创建交易、签署交易、查询区块链数据以及管理密钥。

const { Api, JsonRpc, JsSignatureProvider } = require('eosjs');
const { TextEncoder, TextDecoder } = require('util');

以上代码段引入了 eosjs 库中的关键组件：

• Api : 用于与区块链进行交互的主要接口，它封装了交易创建、签名和广播等功能。
• JsonRpc : 用于与 EOSIO 节点建立连接，允许您查询区块链数据，例如账户信息、区块信息和合约状态。
• JsSignatureProvider : 一个用于管理私钥并对交易进行签名的签名提供者。在这个例子中，它使用 JavaScript 内存中的私钥。
• TextEncoder 和 TextDecoder : 用于在 JavaScript 字符串和 Uint8Array 之间进行编码和解码，这对于处理 EOSIO 区块链上的文本数据至关重要。

const privateKey = 'YOUR_PRIVATE_KEY'; // 替换成你的私钥
const signatureProvider = new JsSignatureProvider([privateKey]);

这段代码展示了如何创建一个 JsSignatureProvider 实例，并将其配置为使用您提供的私钥。请务必将 'YOUR_PRIVATE_KEY' 替换为您的实际私钥。 请注意，直接在代码中存储私钥存在安全风险，建议在生产环境中使用更安全的密钥管理方案，例如硬件钱包或密钥管理系统。

JsSignatureProvider 接收一个包含一个或多个私钥的数组。这允许你使用多个私钥签署同一笔交易，实现多重签名功能。

const rpc = new JsonRpc('YOUR_NODE_URL', { fetch }); // 替换成你的节点URL
const api = new Api({ rpc, signatureProvider, textDecoder: new TextDecoder(), textEncoder: new TextEncoder() });

这段代码创建了 JsonRpc 和 Api 实例，用于与 EOSIO 区块链进行交互。将 'YOUR_NODE_URL' 替换为您想要连接的 EOSIO 节点的 URL。例如： 'https://api.eos.miami' 或者 'http://127.0.0.1:8888' (如果你运行本地节点)。 fetch 函数用于发起 HTTP 请求，通常可以使用浏览器内置的 fetch 函数或者 Node.js 中的 node-fetch 库。

Api 实例接收 rpc , signatureProvider , textDecoder 和 textEncoder 作为参数，用于配置其与区块链进行交互的方式。 signatureProvider 用于对交易进行签名， textDecoder 和 textEncoder 用于处理文本数据。

4. 获取账户信息

在EOSIO区块链中，获取账户信息是常见的操作。通过EOSIO提供的API，可以查询特定账户的详细信息，包括但不限于账户余额（各种代币）、权限结构（owner, active等）、RAM使用情况、CPU和NET资源抵押情况、账户创建时间等。这些信息对于监控账户状态、了解资源使用情况以及进行权限管理至关重要。

以下JavaScript代码展示了如何使用 eosjs 库中的 rpc.get_account() 方法来获取指定EOS账户的详细信息。请注意，你需要事先安装并配置好 eosjs 库，并确保你的节点（例如通过 eosjs 连接的Hyperion或Antelope API端点）能够正确响应API请求。

get_account 方法允许开发者检索与特定帐户名称关联的账户信息。这包括有关其余额（包括不同的加密货币）、权限和其他相关数据（例如 RAM 配额、CPU 和网络使用情况）的详细信息。 使用此信息，开发者可以构建监控工具、创建个性化账户管理系统和实施复杂的逻辑，从而与 EOS 区块链中的账户交互。

javascript

(async  () => {
  try {
    const accountName = 'YOUR_ACCOUNT_NAME'; // 替换成你的账户名，例如 'myaccountname'
    const accountInfo = await rpc.get_account(accountName);
    console.log(JSON.stringify(accountInfo, null, 2)); // 以格式化的JSON字符串输出账户信息，方便阅读
  } catch (e) {
    console.error("获取账户信息失败:", e); // 打印错误信息，方便调试
    console.error("错误类型:", e.constructor.name); // 打印错误类型，帮助定位问题
    if (e.) {
        console.error("服务器返回的详细错误信息:", JSON.stringify(e., null, 2)); // 打印服务器返回的详细错误信息
    }
  }
})();

代码解释：

• accountName ：这是一个字符串变量，你需要将其替换为你想要查询的EOS账户名称。
• rpc.get_account(accountName) ：这个函数调用会向EOSIO区块链发送请求，获取指定账户的详细信息。它返回一个Promise对象，当请求成功时，Promise会resolve为包含账户信息的对象。
• JSON.stringify(accountInfo, null, 2) ：这个函数将账户信息对象转换为格式化的JSON字符串，方便在控制台中查看。 null 和 2 参数分别表示不使用任何替换函数，以及使用2个空格进行缩进。
• 错误处理： try...catch 语句用于捕获可能发生的错误，例如账户不存在、网络连接问题等。在 catch 块中，我们会打印错误信息，方便调试。我们还会尝试打印服务器返回的详细错误信息，这对于排查问题非常有帮助。
• e.constructor.name : 可以显示错误的类型，例如 RpcError , 方便根据错误类型去解决。
• e. : 包含了服务器返回的原始错误信息，这通常包含更详细的错误描述和上下文。

注意事项：

• 确保你已经正确安装了 eosjs 库，并且配置了正确的EOSIO节点URL。
• 替换 YOUR_ACCOUNT_NAME 为你实际想要查询的账户名。
• 根据你的实际需求，可以修改代码来提取和处理账户信息中的特定字段。
• 仔细检查错误信息，以便快速定位和解决问题。

5. 转账操作

转账是EOS钱包API最常用的功能之一，允许用户在EOS区块链网络上转移代币。以下是如何使用 eosjs 库进行转账的详细示例：

重要提示： 在进行任何转账操作之前，请确保你已经正确配置了 eosjs 实例，并连接到了可用的EOS节点。 同时请仔细核对账户名称以及转账金额，避免造成不必要的损失。

javascript

(async () => {
  try {
    // 替换成你的账户名，这是发起转账的账户。
    const accountName = 'YOUR_ACCOUNT_NAME';

    // 替换成收款账户名，这是接收转账的账户。
    const toAccount = 'RECIPIENT_ACCOUNT_NAME';

    // 替换成转账金额，格式为 "数量 EOS"，其中数量是带有4位小数点的数字。
    const amount = '1.0000 EOS';

    // 交易备注，可以包含任意信息，通常用于标识交易目的。
    const memo = 'Test transfer';

    // 使用 eosjs 的 transact 方法来构建和发送交易。
    const result = await api.transact({
      actions: [{
        // 指定要执行的合约账户，对于EOS代币转账，通常是 'eosio.token'。
        account: 'eosio.token',

        // 指定要调用的合约方法，转账是 'transfer'。
        name: 'transfer',

        // 授权信息，指定哪个账户以什么权限来执行此操作。
        authorization: [{
          actor: accountName, // 发起转账的账户。
          permission: 'active', // 使用 active 权限。
        }],

        // 交易数据，包含转账所需的参数。
        data: {
          from: accountName, // 发送方账户。
          to: toAccount, // 接收方账户。
          quantity: amount, // 转账数量，包含代币符号。
          memo: memo, // 交易备注。
        },
      }]
    }, {
      blocksBehind: 3, // 交易的有效区块延迟数，设置为3表示交易需要在最近3个区块内被确认。
      expireSeconds: 30, // 交易的过期时间，设置为30秒表示交易需要在30秒内被广播和确认。
    });

    // 打印交易ID，用于在区块链浏览器上查询交易状态。
    console.log('Transaction ID:', result.transaction_id);

  } catch (e) {
    // 捕获并打印错误信息，方便调试。
    console.error(e);
  }
})();

代码解释：
- accountName ：你的EOS账户名，用于发起转账。
- toAccount ：收款人的EOS账户名。
- amount ：转账金额，需要精确到小数点后4位，并包含 "EOS" 符号。
- memo ：转账备注，可选，可以用于记录转账信息。
- api.transact() ： eosjs 提供的方法，用于构建和广播交易。
- blocksBehind 和 expireSeconds ：用于设置交易的有效性和过期时间，防止交易被延迟执行或过期。

参数说明：

• account : 合约账户名，指定要调用的智能合约的账户名。例如，对于EOSIO网络上的标准代币合约，通常为 eosio.token 。这个参数告诉区块链网络应该调用哪个合约的代码。
• name : 交易名称，指定合约中要调用的特定操作或函数。例如，在 eosio.token 合约中，用于代币转移的操作通常被称为 transfer 。不同的智能合约可能具有不同的操作名称。
• authorization : 授权信息，一个数组，用于指定哪些账户和权限被授权执行此交易。每个授权对象包含一个账户名和一个权限名（例如， active 或 owner ），表明该账户在该权限下批准此交易。正确的授权对于安全地执行交易至关重要。
• data : 交易数据，一个JSON对象或二进制序列化数据，包含了交易所需的参数。对于 transfer 交易，它通常包括以下字段：
  • from : 转账的发送方账户名。
  • to : 转账的接收方账户名。
  • quantity : 转账的金额和代币符号，例如 "1.0000 EOS" 。
  • memo : 一个可选的备注字段，用于包含关于转账的额外信息。
  此数据必须按照合约定义的结构进行序列化。
• blocksBehind : 最大块延迟，指定交易可以被包含在当前最新区块之前的多少个区块内。这个参数用于防止交易过时，确保交易在链上得到及时确认。如果交易未能在指定数量的区块内被确认，则会被视为过期。
• expireSeconds : 交易过期时间，以秒为单位指定交易的有效期限。如果在指定的时间内交易未被打包到区块中，则该交易将失效。设置过期时间可以防止交易在网络拥塞或其他问题发生时无限期地挂起。

6. 资源抵押与赎回

EOS区块链上的账户运行需要消耗计算资源(CPU)和网络带宽资源(NET)。为了确保网络的安全性和可用性，EOS采用了一种资源抵押模型，用户需要抵押EOS代币以获取相应的CPU和NET资源配额。这意味着，每一个EOS账户在进行交易、部署智能合约或执行其他链上操作前，都必须预先抵押一定的EOS代币作为资源保障。

用户可以通过EOS提供的系统合约和API进行资源的抵押和赎回操作。抵押操作会将用户的EOS代币锁定，并赋予其相应的CPU和NET资源使用权。抵押的EOS数量决定了用户能够使用的资源上限，资源消耗完毕后，账户将无法继续执行需要消耗CPU或NET的操作。赎回操作则是将先前抵押的EOS代币解除锁定，返还给用户。需要注意的是，赎回操作通常存在一个解锁期（一般为72小时），在此期间，赎回的EOS代币无法被交易或转移。

具体的资源抵押和赎回操作可以通过命令行工具 cleos 或EOS SDK完成。例如，使用 cleos system delegatebw 命令可以将EOS抵押给指定的账户，以增加其CPU和NET资源。相反，使用 cleos system undelegatebw 命令则可以赎回之前抵押的资源。开发者也可以通过调用EOS的系统合约提供的API接口，在自己的应用程序中实现资源抵押和赎回功能。选择合适的资源抵押量，对于保证EOS账户的正常运行至关重要，用户需要根据自己的实际需求和网络拥堵情况，动态调整抵押的EOS数量。

6.1 抵押资源

在区块链网络中，资源抵押是指用户将一定数量的加密货币（例如EOS）锁定，以获得网络资源的使用权，例如网络带宽（Net）和计算能力（CPU）。抵押资源允许用户在不消耗实际代币的情况下，参与区块链的交易和计算活动。以下JavaScript代码演示了如何使用 eosio 合约的 delegatebw 操作来抵押EOS资源。

该代码片段使用 eosjs 库与EOS区块链进行交互。它首先定义了账户名、接收者账户（通常与抵押者相同），以及要抵押的EOS数量，分别用于网络带宽（ stakeNetQuantity ）和CPU（ stakeCpuQuantity ）。 transfer 参数设置为 0 ，表示不将抵押的EOS转移到接收者账户，而是将其作为抵押品锁定。

(async () =>  {
    try  {
        const accountName = 'YOUR_ACCOUNT_NAME'; // 替换为你的EOS账户名
        const  receiver  = accountName; // 资源接收者，通常是抵押者自身
        const stakeNetQuantity  = '0.1000 EOS'; // 抵押用于网络带宽的EOS数量
        const stakeCpuQuantity = '0.1000 EOS'; // 抵押用于CPU的EOS数量
        const transfer =  0;  // 0 表示不将EOS转移到receiver账户，仅作为抵押

        const  result = await api.transact({
            actions: [{
                account: 'eosio', // 使用eosio系统合约
                name: 'delegatebw', // 调用delegatebw操作
                authorization: [{
                    actor: accountName, // 授权账户
                    permission:  'active', // 使用active权限
                }],
                data: {
                    from: accountName, // 抵押资源的账户
                    receiver: receiver, // 接收资源委托的账户
                    stake_net_quantity: stakeNetQuantity, // 抵押的网络带宽数量
                    stake_cpu_quantity: stakeCpuQuantity, // 抵押的CPU数量
                    transfer:  transfer, // 是否转移抵押的EOS (0表示不转移)
                },
            }]
        }, {
            blocksBehind: 3, // 指定交易在链上的最大延迟区块数
            expireSeconds: 30, // 设置交易的过期时间，单位为秒
        });

        console.log('Transaction ID:', result.transaction_id); // 输出交易ID

    } catch (e) {
        console.error(e); // 捕获并打印错误信息
    }
})();

在 api.transact 方法中，定义了一个包含单个 delegatebw 操作的 actions 数组。该操作需要指定授权账户和权限，以及包含抵押数据的 data 对象。 blocksBehind 和 expireSeconds 参数用于配置交易的有效性和延迟。成功执行后，会返回交易的ID。 需要注意的是， YOUR_ACCOUNT_NAME 需要替换为实际的EOS账户名，并且需要确保该账户拥有足够的EOS余额来完成抵押操作。 抵押的数量可以根据实际需求进行调整，抵押更多的资源可以获得更多的网络带宽和CPU时间。 在使用该代码之前，需要正确配置 eosjs 库，并连接到正确的EOS区块链节点。

6.2 赎回资源

在EOSIO区块链上，用户可以通过赎回（Unstake）网络带宽（NET）和CPU资源（CPU）来释放之前抵押的EOS代币。这一过程涉及调用 undelegatebw 智能合约，该合约负责从用户的账户中解除抵押，并将相应的EOS代币返还给用户。以下JavaScript代码演示了如何使用 eosjs 库实现这一操作：

javascript (async () => { try { const accountName = 'YOUR ACCOUNT NAME'; // 替换为你的EOS账户名 const unstakeNetQuantity = '0.1000 EOS'; // 希望赎回的网络带宽数量，单位为EOS const unstakeCpuQuantity = '0.1000 EOS'; // 希望赎回的CPU资源数量，单位为EOS

    const result = await api.transact({
          actions: [{
               account:  'eosio', // 目标智能合约的账户名
               name: 'undelegatebw', // 调用的智能合约方法名称
               authorization: [{
                    actor: accountName, // 执行操作的账户名
                   permission:  'active', // 使用的权限等级，通常为'active'
                 }],
               data:  {
                     from: accountName, // 发起赎回请求的账户名
                     receiver: accountName, // 接收返还EOS的账户名，通常与发起账户相同
                     unstake_net_quantity: unstakeNetQuantity, // 赎回的网络带宽数量
                   unstake_cpu_quantity: unstakeCpuQuantity, // 赎回的CPU资源数量
                 },
         }]
    }, {
           blocksBehind: 3, // 交易可以追溯的最大区块数
            expireSeconds: 30, // 交易的过期时间，单位为秒
     });

    console.log('Transaction ID:', result.transaction_id); // 打印交易ID

} catch (e) {
      console.error(e); // 捕获并打印任何错误
}

})();

代码详解：

• accountName : 代表发起赎回请求的EOS账户名称。务必将其替换为你自己的账户名。
• unstakeNetQuantity : 指定需要赎回的网络带宽数量，以EOS为单位。请根据实际需求调整该数值。
• unstakeCpuQuantity : 指定需要赎回的CPU资源数量，同样以EOS为单位。根据实际情况调整该数值。
• api.transact() : eosjs 库提供的函数，用于构建和广播交易到EOSIO区块链。
• actions : 交易中包含的操作数组。这里只有一个操作，即调用 eosio 账户下的 undelegatebw 方法。
• authorization : 指定执行该操作所需的权限。 actor 表示授权账户， permission 表示授权等级。
• data : 传递给 undelegatebw 方法的参数。包括发起者 ( from )、接收者 ( receiver )、赎回的网络带宽数量 ( unstake_net_quantity ) 和赎回的CPU资源数量 ( unstake_cpu_quantity )。
• blocksBehind 和 expireSeconds : 用于配置交易的有效性。 blocksBehind 指定交易可以追溯的最大区块数， expireSeconds 指定交易的过期时间。
• result.transaction_id : 交易成功广播后，返回的交易ID，可用于在区块链浏览器中查询交易状态。

注意事项：

• 赎回资源后，赎回的EOS不会立即返回到你的账户。EOSIO协议规定，赎回的资源需要经过一段冷却期（通常为3天）才能真正可用。
• 请确保你的账户有足够的权限执行此操作。通常，使用 active 权限即可。
• 在修改 unstakeNetQuantity 和 unstakeCpuQuantity 时，请务必仔细核对数值，避免因错误操作导致不必要的损失。
• 在实际部署前，建议在测试网络上进行充分的测试，以确保代码的正确性和安全性。

7. 其他常用API

除了上述核心功能外，EOS钱包API还提供了诸多其他实用且强大的功能，开发者可以利用这些功能实现更复杂和精细化的操作，满足不同的应用场景需求。

• get_block : 该API用于获取指定区块的详细信息。通过提供区块高度或区块哈希值，可以检索到该区块包含的交易、时间戳、生产者信息以及其他重要的元数据。这对于区块链浏览器、数据分析以及节点同步等应用至关重要。 例如，通过分析区块数据，可以追踪特定资产的流动情况，监控网络性能，或验证交易的有效性。
• get_transaction : 此API允许开发者根据交易ID（transaction ID）检索特定的交易信息。返回的信息包括交易的状态（例如，成功或失败）、交易的执行结果、交易的签名、以及涉及的账户和操作。这个功能对于调试智能合约、追踪交易历史以及审计交易执行过程非常有用。 开发者可以使用它来确认交易是否被成功打包到区块中，以及查看交易执行过程中产生的具体数据。
• get_table_rows : EOS智能合约使用表格来存储链上数据。 get_table_rows API提供了一种便捷的方式来读取这些表格中的数据。开发者可以指定合约账户、表名、范围、索引类型以及查询条件，从而精确地检索所需的数据。这对于构建去中心化应用（DApps），查询用户信息、游戏资产、投票结果等链上数据至关重要。 通过分页查询和索引优化，可以高效地访问大量链上数据。
• push_transaction : 在通常情况下，EOS钱包会自动签名和广播交易。 然而，在某些特殊情况下，例如需要进行离线签名或多重签名时，开发者可能需要手动构建、签名交易，然后使用 push_transaction API将其广播到区块链网络。 该API接受一个已经签名好的交易作为输入，并将其发送到EOS节点进行验证和执行。 这为开发者提供了更大的灵活性和控制权，可以实现更高级的交易处理逻辑。 广播前务必确保交易签名有效且满足链上的资源要求，否则交易可能会被拒绝。

8. 错误处理

在使用EOS钱包API进行交易或数据交互时，周全的错误处理至关重要。API调用并非总是成功，可能因多种因素导致失败，包括但不限于节点连接不稳定、账户权限配置不当、区块链资源（如CPU或NET）分配不足以及智能合约执行过程中出现的异常。

因此，建议在代码中采用 try...catch 块来优雅地捕获潜在的异常，并依据返回的错误信息，执行相应的错误处理逻辑。这有助于增强应用程序的健壮性，并在出现问题时提供有用的调试信息。

以下列举了一些常见的EOSIO错误代码及其潜在含义，这些代码有助于诊断和解决API调用中遇到的问题：

• 3040005 tx_cpu_usage_exceeded : 表明交易执行所需的CPU资源超过了账户的可用额度。此情况通常发生在交易计算复杂度过高或账户抵押的CPU资源不足时。优化智能合约逻辑或增加抵押的CPU资源可以解决此问题。
• 3040008 tx_net_usage_exceeded : 指示交易需要发送的网络数据量超出了账户的NET资源限制。这可能是因为交易包含大量数据或账户抵押的NET资源不足。减少交易数据量或增加抵押的NET资源可缓解此问题。
• 10 assert_exception : 表示在智能合约执行期间，断言语句失败，通常是由于合约代码中的逻辑错误触发。需要仔细审查智能合约代码，查找导致断言失败的原因。
• 3080004 missing_auth_exception : 说明执行的操作需要特定的权限，但调用者未提供相应的授权。检查交易的授权列表，确保所有必需的权限都已正确添加。权限不足可能是因为账户私钥未正确签名交易，或者调用合约需要特定的角色或组权限。

详细解读和分析API返回的错误信息至关重要，有助于快速定位问题的根源，并采取适当的修复措施。例如，查看错误信息中的上下文数据可以帮助确定哪个智能合约函数调用导致了错误，或者哪个账户缺少必要的权限。查阅EOSIO官方文档和社区论坛可以获取更多关于特定错误代码的详细信息和可能的解决方案。

9. 安全注意事项

• 保护私钥： 私钥是访问和控制您的加密资产的唯一凭证。务必采取最高级别的安全措施来保护您的私钥。建议使用硬件钱包，这是一种专门设计用于安全存储私钥的设备。硬件钱包会将私钥离线存储，即使您的计算机受到恶意软件感染，私钥也不会泄露。同时，切勿将私钥以任何形式（例如文本文件、电子邮件、聊天记录）存储在计算机或移动设备上，更不要将其泄露给任何人，包括自称是技术支持人员或开发团队成员的人员。私钥一旦泄露，您的资产将面临被盗风险。备份私钥至关重要，但备份也应安全存储，例如使用加密的USB驱动器并存放在安全的地方。
• 使用HTTPS： 通过HTTPS（超文本传输安全协议）与区块链节点进行通信是至关重要的安全实践。HTTPS通过加密客户端（您的应用程序）和服务器（区块链节点）之间的数据传输来防止中间人攻击。中间人攻击是指攻击者拦截并篡改通信数据的行为。使用HTTPS可以确保您的交易信息、账户余额和其他敏感数据在传输过程中得到保护，避免被恶意第三方窃取或篡改。在配置您的应用程序或工具时，始终确保选择HTTPS连接，并验证证书的有效性。
• 验证节点： 选择一个信誉良好且可靠的节点提供商对于确保数据的完整性和安全性至关重要。节点提供商负责维护区块链的完整副本，并向您提供访问区块链数据的接口。选择节点提供商时，应考虑其声誉、正常运行时间、安全记录以及数据隐私政策。可信赖的节点提供商会采取各种安全措施来保护其基础设施，例如物理安全、网络安全和数据加密。仔细研究并选择一个符合您安全要求的节点提供商，可以降低遭受恶意攻击或数据泄露的风险。使用多个节点提供商作为备份也是一种有效的安全策略，以确保在某个节点出现问题时，您可以继续访问区块链数据。
• 限制权限： 最小权限原则是一种重要的安全原则，即只授予账户或应用程序执行其任务所需的最低权限。在与区块链交互时，避免使用具有管理员权限的账户执行日常操作。为不同的任务创建具有特定权限的独立账户，例如一个账户用于发送交易，另一个账户用于查询数据。这样，即使某个账户受到攻击，攻击者也无法访问您的所有资产或执行未经授权的操作。例如，智能合约应仅被授予访问和修改其自身数据的权限，而不能访问其他智能合约的数据。仔细审查并限制授予给每个账户或应用程序的权限，可以显著降低安全风险。
• 代码审计： 定期进行代码审计是识别和修复智能合约和区块链应用程序中潜在安全漏洞的关键步骤。代码审计是由专业的安全审计员对代码进行全面审查，以查找可能被攻击者利用的漏洞。这些漏洞可能包括缓冲区溢出、整数溢出、重入攻击、拒绝服务攻击等。审计员会检查代码的逻辑、输入验证、错误处理和安全配置等方面，并提供详细的报告，其中包含发现的漏洞和修复建议。进行代码审计可以帮助您在部署代码之前发现并修复漏洞，从而避免遭受重大损失。建议在每次发布新版本或更新代码时都进行代码审计。

10. 结语

本文档详细介绍了EOS钱包API的使用方法，涵盖了密钥管理、账户信息获取、转账操作、资源抵押与赎回等方面。 通过学习本文档，开发者可以快速上手并构建基于EOS的应用程序。记住，安全至关重要，始终将安全放在首位。