如何在 fuels-rs 合约调用交易中随调用一并转出自定义资产
【免费下载链接】fuels-rs Fuel Network Rust SDK 
项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs
在 fuels-rs 中调用已部署合约时，你通常希望这一次交易除了执行业务方法外，还顺带把某种资产（基础资产或合约资产）转给另一个地址，而不必再单独发一笔转账交易。fuels-rs 为此提供了 add_custom_asset() 构建方法：在构造合约调用的同时指定资产 ID、数量和目标地址，转账与合约调用会在同一笔交易里一起提交。
本文适用的前提是：你已经有部署好的合约和对应的合约实例（如通过 setup_program_test! 或 abigen! + Contract::load_from 部署得到），并且发起方钱包持有待转出资产的余额。
add_custom_asset() 的签名与用法
该方法定义在调用处理器的源码 call_handler.rs 中：
pub fn add_custom_asset(mut self, asset_id: AssetId, amount: u64, to: Option<Address>) -> Self
它不是独立的交易入口，而是调用链上的一个构建方法。源码注释中给出的形态是把它接在方法调用之后、.call() 之前：
let asset_id = AssetId::from([3u8; 32]);
let amount = 5000;
my_contract_instance.my_method(…).add_custom_asset(asset_id, amount, None).call()
三个参数分别是资产 ID（AssetId）、数量（u64）、目标地址（Option<Address>）。仓库示例里实际传递目标地址时使用的都是 Some(address) 形式。
准备调用环境
仓库示例 examples/contracts/src/lib.rs 使用 setup_program_test! 宏一次完成启动本地节点、创建钱包、生成绑定和部署合约。该宏的 Abigen 命令要求对应的 forc 项目已用 release 模式编译（见 setup_program_test! 宏文档）：
use fuels::prelude::*;
setup_program_test!(
Wallets("wallet", "wallet_2"),
Abigen(Contract(
name = "MyContract",
project = "e2e/sway/contracts/contract_test"
)),
Deploy(
name = "contract_instance",
contract = "MyContract",
wallet = "wallet"
)
);
其中 project 指向你的 forc 项目根目录，示例中指向的是仓库自带的 contract_test 测试合约；使用时替换为你自己的项目路径。如果你不走这个宏，也可以用 launch_provider_and_get_wallet() 加 Contract::load_from(…).deploy(…) 手工完成同一套准备，仓库多处示例采用了这种写法。
在合约调用中附带转出资产
仓库给出的最小示例（来自 custom-asset-transfer.md）：
let some_addr: Address = thread_rng().r#gen();
let amount = 1000;
let _ = contract_instance
.methods()
.initialize_counter(42)
.add_custom_asset(AssetId::zeroed(), amount, Some(some_addr))
.call()
.await?;
拆开看各部分的作用：
- initialize_counter(42) 是本次随交易一起执行的合约业务方法，示例用的这个来自 contract_test 合约，替换为你自己合约的方法即可；
- AssetId::zeroed() 表示基础资产（base asset），转合约资产时换成对应合约的 AssetId；
- Some(some_addr) 是接收地址。示例里 some_addr 是随机生成的地址，只用于演示编译通过，实际使用时必须是真实接收方地址；
- .call().await? 提交交易并等待返回。
如果需要在一笔交易里转多种资产，可以链式多次调用 add_custom_asset。仓库集成测试 test_add_custom_assets 就是这样做的：
let amount_1 = 5000;
let amount_2 = 3000;
let response = contract_instance
.methods()
.get(5, 6)
.add_custom_asset(asset_id_1, amount_1, Some(wallet_2.address()))
.add_custom_asset(asset_id_2, amount_2, Some(wallet_2.address()))
.call()
.await?;
注意调用本身照常返回合约方法的返回值，该测试中 get(5, 6) 的返回值为 11，说明转账没有改变业务调用自身的响应。
验证转账结果
验证方式是分别查询发起方和接收方钱包的资产余额。在 Fuel 网络中，每个 UTXO 对应一枚 coin，查询某资产余额就是对该资产所有未花费 coin 的数量求和（见 Checking balances and coins）。
上面集成测试的验证断言如下（数值来自测试本身：每个资产初始 100_000，分别转出 5000 和 3000）：
// 发起方余额应减少转出的数量
let balance_asset_1 = wallet_1.get_asset_balance(&asset_id_1).await?;
assert_eq!(balance_asset_1, (initial_amount – amount_1) as u128);
// 接收方余额应增加转出的数量
let balance_asset_1 = wallet_2.get_asset_balance(&asset_id_1).await?;
assert_eq!(balance_asset_1, (initial_amount + amount_1) as u128);
该测试的测试环境准备也很说明问题：用 AssetConfig 声明每种资产及其初始数量，再通过 WalletsConfig::new_multiple_assets 为两个钱包同时配置多资产：
let initial_amount = 100_000;
let asset_base = AssetConfig {
id: AssetId::zeroed(),
num_coins: 1,
coin_amount: initial_amount,
};
let asset_id_1 = AssetId::from([3u8; 32]);
let asset_1 = AssetConfig {
id: asset_id_1,
num_coins: 1,
coin_amount: initial_amount,
};
let assets = vec![asset_base, asset_1, asset_2];
let wallet_config = WalletsConfig::new_multiple_assets(num_wallets, assets);
let mut wallets = launch_custom_provider_and_get_wallets(wallet_config, None, None).await?;
按这套流程，你可以得到一条完整可核对的路径：配置资产 → 发起带 add_custom_asset 的调用 → 用 get_asset_balance 核对双方余额变化。
与 CallParameters 的区别
调用合约时向合约转发币用的是另一套机制：Call parameters 文档说明 CallParameters（通过 call_params 传入）用于把 amount、asset ID、gas 转发给合约本身。add_custom_asset() 则是在同一笔交易中把资产转给指定的目标地址，两者解决的是不同目标，不要混用。
参考文档：
- docs/src/calling-contracts/custom-asset-transfer.md
- docs/src/calling-contracts/call-params.md
- examples/contracts/src/lib.rs
- e2e/tests/contracts.rs
【免费下载链接】fuels-rs Fuel Network Rust SDK 项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
