FuelTS 项目中增强 addContracts 方法支持字符串合约 ID 的设计思考

在 FuelTS 项目的智能合约交互模块中，BaseInvocationScope 类的 addContracts 方法扮演着关键角色。该方法原本设计用于处理合约间的交叉调用场景，但当前实现存在一定的使用局限性，本文将探讨其优化方案和技术实现思路。

现有机制分析

当前 addContracts 方法仅接受合约实例数组作为参数，这种设计主要服务于两个核心功能：

1. 交易优化机制：通过获取交叉调用合约的 ID，自动为交易请求添加 InputContract 和 OutputContract，显著减少 dry run 次数，提升交易预估和提交效率。

2. 日志解码支持：保存交叉调用合约的 JSON ABI，使得 TS SDK 能够正确解析这些合约产生的日志数据。

现有方案的局限性

在实际开发场景中，开发者经常面临以下挑战：

• 当交叉调用的合约由第三方维护时，可能无法获取完整的合约实例
• 仅需合约 ID 进行交易优化的场景下，强制要求提供完整 ABI 显得不够灵活
• 与外部系统集成时，字符串形式的合约 ID 往往更容易获取和传递

技术优化方案

建议扩展 addContracts 方法，使其支持以下两种参数类型：

1. 传统合约实例：保持现有功能不变，同时处理合约 ID 和 ABI
2. 字符串合约 ID：仅用于交易优化，不包含 ABI 解析能力

这种混合参数支持需要建立类型守卫机制，在方法内部区分处理两种不同类型的输入。对于字符串 ID，应当跳过 ABI 的存储步骤，同时在文档中明确说明其功能限制。

实现考量要点

1. 类型系统设计：需要创建联合类型 ContractLike，包含 Contract 和 string 两种类型
2. 运行时类型检查：实现类型谓词函数 isContractInstance 进行运行时判别
3. 功能降级处理：当仅提供合约 ID 时，明确跳过日志解码相关逻辑
4. 开发者提示：在文档中清晰说明不同参数类型对应的功能差异

预期效益

该优化将带来以下改进：

• 提升与第三方合约的集成便利性
• 降低简单场景下的使用门槛
• 保持复杂场景的完整功能支持
• 增强 SDK 的灵活性和适用性

这种改进符合现代区块链开发工具的发展趋势，在保证核心功能的同时提供更灵活的使用方式，能够更好地满足不同层次的开发需求。