企业官网建设流程全解析

• 区块链

导读

cleos system delegatebw是 EOS 智能合约平台（eo/eos 仓库）中通过命令行将代币质押（stake）为 CPU 带宽与 NET 带宽的核心命令。在 EOSIO 资源模型中，账户执行交易需消耗 CPU 与 NET 资源，而这两种资源正是通过该命令把代币委托给目标账户获得的。本文以 docs/02_cleos/03_command-reference/system/system-delegatebw.md 为主体骨架，结合仓库内 programs/cleos/main.cpp 的 CLI 实现、eosio.system.abi 的智能合约 ABI 定义以及 eosio_system_tester.hpp 的单元测试，从位置参数、选项、实战示例到底层 action 构造原理，为你提供一份可复制、可运行的完整参考。

一、命令概述：什么是带宽委托（Delegate Bandwidth）

在 EOSIO 资源模型中，账户执行转账、部署合约、投票等链上操作时，需要消耗两类带宽资源：

• NET 带宽（Network Bandwidth）：与交易数据大小（字节数）挂钩的网络吞吐资源，用于限制账户在一段时间内可提交的交易数据总量；
• CPU 带宽（CPU Bandwidth）：与交易执行时间（毫秒）挂钩的计算资源，用于限制账户在一段时间内可消耗的 CPU 执行时间。

账户可通过cleos system delegatebw将代币质押给某个账户（可以是自己，也可以是其他账户），质押的代币不直接花费，而是锁定在系统合约中，为receiver账户换取相应的带宽配额。这是 EOSIO 资源模型的基础操作，其链上动作（action）名称为delegatebw，由系统合约（eosio 账户）执行。

命令语法如下：

cleos system delegatebw [OPTIONS] from receiver stake_net_quantity stake_cpu_quantity

其中四个位置参数均为必填，可选参数通过[OPTIONS]传入。

二、位置参数（Positional Arguments）详解

要点说明：

• 四个位置参数在 programs/cleos/main.cpp 中通过 CLI11 均标记为->required()，缺一不可；
• from与receiver既可以是不同账户（A 为 B 质押），也可以是同一账户（自己为自己质押），详见下文实战示例；
• stake_net_quantity与stake_cpu_quantity为 asset 类型（带精度与符号），字符串中必须包含代币符号（如EOS或SYS），且精度须与链上代币一致。例如在单元测试 eosio_system_tester.hpp 中即使用core_from_string("10.0000")形式传入带 4 位小数的资产量。

三、选项（Options）详解

3.1 通用交易选项

以下选项与 cleos 其他system子命令保持一致，由add_standard_transaction_options_plus_signing统一注入（见 programs/cleos/main.cpp）：

3.2 委托专属选项：--buyram / --buy-ram-bytes / --transfer

与大多数cleos system子命令不同，delegatebw还额外支持三个专属选项（源码见 programs/cleos/main.cpp）：

重要限制：源码 programs/cleos/main.cpp 中显式断言--buyram与--buy-ram-bytes不能同时设置：

ERROR: --buyram and --buy-ram-bytes cannot be set at the same time

若设置了--buyram，cleos 会在delegatebwaction 之后追加一个buyramaction；若设置了--buy-ram-bytes，则追加一个buyrambytesaction，从而将"质押带宽 + 购买 RAM"合并为一条多 action 交易（见 programs/cleos/main.cpp）。

--transfer对应链上 action 结构体中的transfer布尔字段，在测试辅助函数stake_with_transfer中被显式置为true（见 eosio_system_tester.hpp）。

四、实战示例：如何质押 CPU / NET 带宽

以下示例改编自仓库内实战指南 how-to-stake-resource.md，代币符号以该指南使用的SYS为例。

4.1 仅为接收方质押 NET 带宽

由bob账户出资，为alice账户质押0.01 SYS的 NET 带宽：

cleos system delegatebw alice bob "0.01 SYS" "0 SYS"

各参数含义：

• alice= 获得 NET 带宽的账户；
• bob= 支付0.01 SYS用于质押 NET 带宽的账户；
• "0.01 SYS"= 质押到 NET 带宽的 SYS 数量；
• "0 SYS"= 质押到 CPU 带宽的 SYS 数量（此处为 0）。

执行成功后，终端会输出类似如下的执行摘要：

executed transaction: 5487afafd67bf459a20fcc2dbc5d0c2f0d1f10e33123eaaa07088046fd18e3ae 192 bytes 503 us # eosio <= eosio::delegatebw {"from":"bob","receiver":"alice","stake_net_quantity":"0.01 SYS","stake_cpu_quanti... # eosio.token <= eosio.token::transfer {"from":"bob","to":"eosio.stake","quantity":"0.01 SYS","memo":"stake bandwidth"} # alice <= eosio.token::transfer {"from":"bob","to":"eosio.stake","quantity":"0.01 SYS","memo":"stake bandwidth"} # eosio.stake <= eosio.token::transfer {"from":"bob","to":"eosio.stake","quantity":"0.01 SYS","memo":"stake bandwidth"}

从输出可以看到交易内部的真实调用链：eosio::delegatebw动作触发后，代币从bob转账至中间托管账户eosio.stake，memo 为stake bandwidth。

4.2 仅为接收方质押 CPU 带宽

cleos system delegatebw alice bob "0 SYS" "0.01 SYS"

含义：bob为alice质押0.01 SYS到 CPU 带宽，NET 质押量为 0。

4.3 同时质押 NET 与 CPU 带宽

cleos system delegatebw alice bob "0.01 SYS" "0.02 SYS"

含义：bob为alice同时质押0.01 SYS到 NET、0.02 SYS到 CPU 带宽。这是最常用的组合式质押方式，也是部署合约、参与投票前的标准资源准备步骤。

4.4 账户自质押（Stake to Self）

账户可以将带宽质押给自己。将上述示例中的bob全部替换为alice即可，前提是alice账户持有足够的 SYS 代币。例如：

cleos system delegatebw alice alice "0.01 SYS" "0.02 SYS"

即alice为自己质押 NET 与 CPU 带宽。在单元测试中，stake(acnt, net, cpu)的默认实现正是调用stake(acnt, acnt, net, cpu)完成自质押（见 eosio_system_tester.hpp）。

4.5 指定权限、延迟与 JSON 输出

cleos system delegatebw alice bob "0.01 SYS" "0.02 SYS" \ -p bob@active \ --delay-sec 60 \ -j

• -p bob@active：显式指定以bob@active权限签名（默认即from@active，见 programs/cleos/main.cpp 的默认参数"from@active"）；
• --delay-sec 60：交易延迟 60 秒后生效；
• -j：以 JSON 格式输出执行结果，便于脚本解析。

五、源码级原理：从命令到链上 Action

5.1 cleos 端的命令解析与 Action 构造

cleos system delegatebw的完整实现位于 programs/cleos/main.cpp 的delegate_bandwidth_subcommand结构体：

1. 通过 CLI11 注册子命令delegatebw，描述文案为 "Delegate bandwidth"，并依次注册from、receiver、stake_net_quantity、stake_cpu_quantity四个必填位置参数；
2. 注册--buyram、--buy-ram-bytes、--transfer专属选项，并通过add_standard_transaction_options_plus_signing注入全套标准交易选项与签名密钥选项；
3. 在回调中构造 action 负载（payload）：

fc::variant act_payload = fc::mutable_variant_object() ("from", from_str) ("receiver", receiver_str) ("stake_net_quantity", to_asset(stake_net_amount)) ("stake_cpu_quantity", to_asset(stake_cpu_amount)) ("transfer", transfer);

4. 使用create_action(accountPermissions, config::system_account_name, "delegatebw"_n, act_payload)将动作发往系统账户eosio；
5. 若同时指定了--buyram或--buy-ram-bytes，则在动作序列末尾追加buyram/buyrambytesaction，最后通过send_actions一次性广播。

也就是说，一次cleos system delegatebw调用，最终在链上表现为：一个发往eosio系统合约的delegatebw动作（+ 可选的一个buyram/buyrambytes动作）。

5.2 链上 ABI 定义：delegatebw 结构

在系统合约 ABI 文件 unittests/contracts/eosio.system/eosio.system.abi 中，delegatebw结构体定义如下：

{ "name": "delegatebw", "base": "", "fields": [ { "name": "from", "type": "name" }, { "name": "receiver", "type": "name" }, { "name": "stake_net_quantity", "type": "asset" }, { "name": "stake_cpu_quantity", "type": "asset" }, { "name": "transfer", "type": "bool" } ] }

可见链上delegatebw动作共 5 个字段：from、receiver为账户名（name），两个质押数量为资产（asset），transfer为布尔值——与 cleos 端构造的 payload 一一对应。该结构体还在 ABI 的actions表中注册（见 eosio.system.abi），供序列化与反序列化使用。

5.3 测试验证：stake 与 stake_with_transfer

仓库单元测试 eosio_system_tester.hpp 提供了两个直接封装delegatebw的辅助函数，可作为理解参数语义的参考：

action_result stake( const account_name& from, const account_name& to, const asset& net, const asset& cpu ) { return push_action( name(from), "delegatebw"_n, mvo() ("from", from) ("receiver", to) ("stake_net_quantity", net) ("stake_cpu_quantity", cpu) ("transfer", 0 ) ); } action_result stake_with_transfer( const account_name& from, const account_name& to, const asset& net, const asset& cpu ) { return push_action( name(from), "delegatebw"_n, mvo() ("from", from) ("receiver", to) ("stake_net_quantity", net) ("stake_cpu_quantity", cpu) ("transfer", true ) ); }

其中stake_with_transfer将transfer置为true，对应命令行中的--transfer选项：质押给接收方的代币连同投票权与解质押权一并转移给接收方。此外，测试框架在创建带资源账户（create_account_with_resources）时，也会构造包含buyrambytes+delegatebw的多 action 交易，为新建账户预置 NET/CPU 资源（见 eosio_system_tester.hpp），这正是"质押带宽 + 购买 RAM"组合用法的真实落地场景。

六、关联操作：查询与解绑带宽

带宽委托并非单向操作，实际使用中常与以下命令配合：

undelegatebw与delegatebw的参数结构对称（from、receiver、两个资产数量，见 system-undelegatebw.md），其 cleos 实现同样位于 programs/cleos/main.cpp，构造发往eosio的undelegatebw动作。注意：解绑后代币不会立即回到账户余额，而是进入系统合约规定的解锁流程；若质押时使用了--transfer，则只有接收方才有权发起解绑。

七、注意事项与最佳实践

1. 质押数量必须为正且格式合法：stake_net_quantity与stake_cpu_quantity需符合 asset 格式（数量 + 空格 + 符号，如"1.0000 EOS"），且精度与代币精度一致，否则 cleos 解析（to_asset）会报错；
2. NET/CPU 可分别质押：可将某个方向设为"0 EOS"，实现只质押 CPU 或只质押 NET；
3. --transfer需谨慎：一旦转移，from将失去对质押代币的解绑权与相关投票权；
4. --buyram与--buy-ram-bytes互斥：二者同时设置会直接报错终止；
5. 离线检查：使用-d（不广播）先查看构造出的交易内容，确认 action 负载无误后再去掉-d正式广播；配合-j可获得 JSON 格式结果，便于自动化集成；
6. 权限控制：默认以from@active签名，也可通过-p显式指定其他权限级别。

八、总结

cleos system delegatebw是 EOSIO 资源模型中最核心的 CLI 入口之一。通过本文你可以掌握：

• 四个必填位置参数（from、receiver、stake_net_quantity、stake_cpu_quantity）与全部标准交易选项的准确语义；
• 三个专属选项（--buyram、--buy-ram-bytes、--transfer）的行为差异与互斥约束；
• 从命令行到链上eosio::delegatebwaction 的完整调用链（programs/cleos/main.cpp）以及 ABI 结构（eosio.system.abi）；
• 结合 how-to-stake-resource.md 的完整实战示例与 eosio_system_tester.hpp 的测试封装，理解transfer标志及组合购买 RAM 的真实用法。

无论是为新账户准备资源、为 DApp 运营调配 CPU/NET 配额，还是深度理解 EOSIO 资源质押机制，本文给出的命令、参数与源码依据均可直接用于实际开发与排障。

• 区块链