fuels-rs Cookbook为 Fuel 节点自定义共识参数Custom chain / Consensus parameters并启动测试链【免费下载链接】fuels-rsFuel Network Rust SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs本文基于 fuels-rs 仓库的 Cookbook 文档 docs/src/cookbook/custom-chain.md在 docs/src/SUMMARY.md 中对应 Custom consensus parameters 一节展开。该指南演示了如何通过 SDK 的测试辅助工具启动一个底层链共识参数Consensus Parameters可定制的短生命周期 Fuel 节点并让Provider连接它。这在验证交易大小/ Gas 上限、手续费模型、区块 Gas 上限等链级行为时非常实用。读完本文你将掌握ConsensusParameters/ChainConfig的配置方法、创世币genesis coins的铸造流程以及setup_test_provider()的完整调用链与验证手段。场景为什么需要自定义链的测试节点默认的本地测试节点fuel-core自带配置通常已能覆盖绝大多数合约测试。但当你的测试用例需要验证如下行为时就需要显式覆盖链上共识参数单笔交易允许的Gas 上限max_gas_per_tx单笔交易允许的输入数量上限max_inputs例如批量转账、变量输出相关的场景手续费模型中的gas 价格因子gas_price_factor等FeeParameters合约大小、存储槽数量等其他ContractParameters类参数。这些参数由区块生产者fuel-core 节点在创世时固化。因此要在一个可控的、隔离的环境里验证最直接的办法就是先自定义一套参数再用它启动本地节点——这正是本文对应的custom_chain测试用例所做的事。完整可运行的示例位于 examples/cookbook/src/lib.rs 的custom_chain测试第 103–144 行下面逐段拆解。第一步引入依赖类型文档示例首先引入所需的类型use fuels::{ prelude::*, tx::{ConsensusParameters, FeeParameters, TxParameters}, };说明两点ConsensusParameters、FeeParameters、TxParameters由fuel_tx提供SDK 在 packages/fuels/src/lib.rs 的tx模块中做了统一转发pub use fuel_tx::{ConsensusParameters, ContractParameters, FeeParameters, TxParameters, ...}因此可以从fuels::tx导入。ChainConfig、NodeConfig以及稍后用到的setup_test_provider、setup_single_asset_coins等测试辅助项都通过prelude汇聚导出test_helpers::*见 packages/fuels/src/lib.rs所以use fuels::prelude::*即已覆盖。第二步定义共识参数并组装 ChainConfig构造自定义参数的核心代码块如下let tx_params TxParameters::default() .with_max_gas_per_tx(1_000) .with_max_inputs(2); let fee_params FeeParameters::default().with_gas_price_factor(10); let mut consensus_parameters ConsensusParameters::default(); consensus_parameters.set_tx_params(tx_params); consensus_parameters.set_fee_params(fee_params); let chain_config ChainConfig { consensus_parameters, ..ChainConfig::default() };这段代码展示了几种可定制的能力TxParameters交易级参数这里将max_gas_per_tx设为1_000、max_inputs设为2。它们分别限定了单笔交易能消耗的最大 Gas、以及单笔交易能够携带的输入Input/Coin个数上限。实际填写时应结合你的交易规模例如大量 UTXO 合并的转账会需要更多输入槽位。FeeParameters手续费参数with_gas_price_factor(10)调整了费用模型中的 gas 价格因子与区块生产者端--starting-gas-price之类的设置配合决定交易实际扣费。fuels-rs 自身的单元测试中也用类似手法如FeeParameters::default().with_gas_per_byte(2)来验证自定义费用参数能原样下发到节点。可变 setter 风格ConsensusParameters的字段通过set_tx_params/set_fee_params等方法逐个覆盖。默认值之外的常见选项还包括set_contract_params、set_block_gas_limit、set_block_transaction_size_limit等可在本仓库测试代码中见到它们的身影例如 packages/fuels-test-helpers/src/lib.rs 的testnet_chain_config以及 packages/fuels-test-helpers/src/accounts.rs 的generated_wallets_with_custom_chain_config。结构体更新语法..ChainConfig::default()只覆盖consensus_parameters其余链配置链名、创世时间等保持 fuel-core 的默认值。由此得到最终的ChainConfig它就是后续要喂给节点的整条链的创世共识。第三步铸造创世币并分配给一个地址启动节点前通常还要准备一些创世余额genesis coins否则后续交易没有可用于支付 Gas 的资产。示例使用setup_single_asset_coinslet signer PrivateKeySigner::random(mut thread_rng()); let coins setup_single_asset_coins( signer.address(), Default::default(), DEFAULT_NUM_COINS, DEFAULT_COIN_AMOUNT, );逐个参数解读对照 packages/fuels-test-helpers/src/lib.rs 中setup_single_asset_coins的实现owner这里为signer.address()这些币的持有者地址后续用同一个PrivateKeySigner构造钱包即可支配。asset_id这里为Default::default()资产 ID。Default即全零值AssetId::zeroed()也就是 Fuel 的基础资产Base Asset用于支付 Gas。若需要其它资产可传入自定义AssetId如AssetId::from([1u8; 32])。num_coins铸造的 UTXO 个数。常量DEFAULT_NUM_COINS 1。amount_per_coin每个 UTXO 的金额。常量DEFAULT_COIN_AMOUNT 1_000_000_000。这两个默认常量定义在 packages/fuels-test-helpers/src/wallets_config.rs。实现会为每个币生成随机UtxoId最终返回VecCoin。如果测试需要多种资产或更复杂的分配SDK 还提供了两个姊妹函数同文件setup_multiple_assets_coins(owner, num_asset, coins_per_asset, amount_per_coin)生成num_asset种资产其中一种固定为基础资产对应的多组币并返回(VecCoin, VecAssetId)setup_custom_assets_coins(owner, [AssetConfig])按AssetConfig { id, num_coins, coin_amount }列表精确控制每种资产的铸造数量与金额。第四步调用 setup_test_provider 启动节点把前面两样东西合到一起let node_config NodeConfig::default(); let _provider setup_test_provider(coins, vec![], Some(node_config), Some(chain_config)).await?;setup_test_provider的签名见 packages/fuels-test-helpers/src/lib.rs为pub async fn setup_test_provider( coins: VecCoin, messages: VecMessage, node_config: OptionNodeConfig, chain_config: OptionChainConfig, ) - ResultProvider第二个参数messages用于预置桥接消息示例传空vec![]第三个参数node_config是节点运行配置非链参数默认的NodeConfig使用内存数据库、Instant产块模式、开启utxo_validation与debug字段清单及默认值见 packages/fuels-test-helpers/src/node_types.rs第四个参数chain_config即上面自定义的链配置。若传NoneSDK 会回落到testnet_chain_config()——一个把交易大小上限放宽到 10,000,000、合约最大尺寸放宽到 1,000,000 的 testnet 风格配置同样定义在 packages/fuels-test-helpers/src/lib.rs这就是默认本地节点的行为来源。函数内部做三件事将coins/messages通过into_coin_configs/into_message_configs转成 fuel-core 的创世StateConfigpackages/fuels-test-helpers/src/utils.rs调用FuelService::start(node_config, chain_config, state_config)真正拉起节点packages/fuels-test-helpers/src/service.rs最后从节点绑定的地址创建并返回一个Provider同时把FuelService句柄 spawn 到后台使其存活。关于底层节点有两种运行形态值得注意默认情况下SDK 会查找PATH中的fuel-core可执行文件通过子进程方式启动packages/fuels-test-helpers/src/fuel_bin_service.rs它会把ChainConfig/StateConfig序列化成临时 snapshot 目录再以fuel-core run --snapshot ...的方式拉起节点并解析绑定端口若启用了fuel-core-libfeature则改为在进程内以库形式运行 fuel-coreCoreFuelService::new_node无需本地安装二进制。rocksdbfeature 则可配合fuel-core-lib提供持久化存储。两种 feature 的开启方式可参考 docs/src/connecting/short-lived.md。第五步验证自定义参数真正生效文档示例拿到_provider后即完成演示但在真实测试中你通常还需要确认节点确实运行在你自定义的参数之下。仓库测试给出了两种回读手段provider.consensus_parameters().await?直接取回节点上报的共识参数对象与本地构造值比较。见 packages/fuels-test-helpers/src/lib.rs 中test_setup_test_client_consensus_parameters_config——它设置max_inputs 58等值后启动节点再用assert_eq!(retrieved_parameters, consensus_parameters)断言一致。provider.chain_info().await?取回链信息再逐项核对chain_info.consensus_parameters.tx_params().max_inputs()与fee_params().gas_per_byte()。见同文件test_chain_config_and_consensus_parameters它甚至一并验证了自定义chain_name能正确下发。在 Cookbook 之外还有一类更高糖的入口let wallets launch_custom_provider_and_get_wallets( WalletsConfig::new(Some(num_wallets), Some(num_coins), Some(amount)), None, Some(chain_config), // 同样支持自定义 ChainConfig ) .await?;它内部为每个钱包生成确定性的私钥、铸造对应数量的币再调用setup_test_provider一次性返回一串连接了自定义节点、且带好余额的Walletpackages/fuels-test-helpers/src/accounts.rs。仓库用它在generated_wallets_with_custom_chain_config中验证了设置block_gas_limit、max_gas_per_tx后钱包回读到的tx_params().max_gas_per_tx()与自定义值一致。注意事项与使用建议参数与测试规模要匹配若把max_gas_per_tx设得过小而后续测试要执行复杂合约调用或大合约部署交易会因超出 Gas 上限而被拒max_inputs过小则会导致需要多输入拼凑金额的交易失败。反之本地测试通常建议参考testnet_chain_config()适当放宽限制。余额要能覆盖 Gas自定义链参数后手续费仍以基础资产结算请确保创世币中包含AssetId::zeroed()的基础资产且总量足以支付测试期间全部交易的 Gas。区分两类配置NodeConfig节点行为数据库、产块方式、UTXO 校验等与ChainConfig链的共识参数是两个不同的Option参数可分别定制只改链参数不需要动节点配置直接传Some(NodeConfig::default())或按需覆盖即可。运行前提若未启用fuel-core-libfeature需要本机PATH中存在与 SDK 兼容的fuel-core可执行文件启用fuel-core-lib则要求对应 feature 被开启详见 docs/src/connecting/short-lived.md。异步上下文custom_chain示例整体运行在#[tokio::test]中见 examples/cookbook/src/lib.rssetup_test_provider返回ResultProvider可结合Provider::launch之后的钱包、合约部署等能力继续扩展你的测试用例。小结自定义链是 fuels-rs 测试工具箱里容易被忽略、但极为关键的一环它让你能在隔离的本地节点上以任意一组链共识参数交易 Gas 上限、输入上限、手续费因子等验证 SDK 与合约的行为而无需依赖固定的外部测试网配置。围绕本文可进一步阅读 docs/src/connecting/short-lived.md短生命周期节点机制、docs/src/testing/chains.md对链的更精细操控以及本节 Cookbook 的其余配方如 deposit-and-withdraw 与 transfer-all-assets。【免费下载链接】fuels-rsFuel Network Rust SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考