该存储库提供了一个入门项目,用于构建支持IBC 的Solidity 合约,通过vIBC 核心合约将汇总连接到另一个 Polymer Hub 。
该存储库是GitHub 模板存储库,因此您可以单击“使用此模板”来创建您自己的项目存储库,而无需拥有模板的完整提交历史记录。
📚 文档
自述文件中有一些基本信息,但可以在官方 Polymer 文档中找到更全面的文档。
📋 先决条件
该存储库与 Hardhat 和 Foundry开发环境兼容。
已经安装了git
已安装节点(v18+)
已安装Foundry (运行时会安装 Hardhat npm install)
刚刚安装(推荐但不是绝对必要)
您需要来自第三方的一些 API 密钥:
Optimism Sepolia和BaseSepolia Blockscout Explorer API 密钥
拥有OP 和 Base Sepolia 的Alchemy API 密钥
尽管为了基本使用而抽象了细节,但还需要所有这些工具的一些基本知识。
🧰 安装依赖项
要编译合约并开始测试,请确保已安装所有依赖项。
从根目录运行:
just install
安装vIBC 核心智能合约和Polymer 注册表作为依赖项。
此外,Harhat 将作为开发依赖项安装,并附带一些有用的插件。检查package.json详尽的列表。
注意:如果您在使用配方时遇到依赖项问题just install,请检查所有先决条件是否已正确安装。如果 Forge 问题仍然存在,请尝试进行单独的依赖项安装...
版本兼容性
IBC-应用程序-Solidity vIBC核心 聚合物登记处 支持的?
v0.1.0 v1.0.0 X 已弃用
v0.2.0 v1.0.0 v0.1.0* 已弃用
v1.0.0 v2.0.0 v0.0.1 是的
注(*):v0.2.0使用POC版本
⚙️ 设置您的环境和配置
其想法是确保添加 PolymervIBC 的大多数配置都作为自定义数据添加到您的开发环境(例如 Hardhat 或 Foundry)的配置文件中。 (请注意,在撰写本文时,仅完全支持 Hardhat)。
确保将网络信息添加到您有兴趣构建的所有受支持网络的 Hardhat 配置中,遵循以下架构:
networks: {
// for OP testnet
optimism: {
url: 'https://sepolia.optimism.io',
alchemyRPC: `https://opt-sepolia.g.alchemy.com/v2/${process.env.OP_ALCHEMY_API_KEY}`,
accounts: [process.env.PRIVATE_KEY_1],
chainId: 11155420,
}
}
特别要确保添加链 ID,因为它将用于通过 ID 从 Polymer 注册表获取正确的数据,同时您可以在本地将链引用为您在 Hardhat 配置中指定的名称。
环境变量
将文件转换.env.example为.env文件。这将忽略未来 git 提交的文件并公开环境变量。如果您想自定义(高级使用功能),请添加您的私钥并更新其他值。
cp .env.example .env
这将使您能够使用您的私钥签署交易。如果未添加,justfile 中的脚本将失败。
配置文件
配置文件是存储所有重要数据的地方,仅用于命令和自动化。我们努力尽可能少地与配置文件进行直接交互。
默认情况下,配置文件存储在 config 文件夹中,名称为config.json.
💡 但是,建议将同一存储库中的不同合约/项目拆分到不同的配置文件中,以防您想在它们之间切换。
将备用配置文件存储在 /config 目录中,并在 Hardhat 配置文件中设置路径:
// path to configuration file the scripts will use for Polymer's vibc, defaulting to config/config.json when not set
vibcConfigPath: 'config/alt-config.json',
使用不同的配置文件。
与以前的版本相反,您必须通过指定您希望其包含的网络(来自 Hardhat 配置)来构建默认配置文件:
# Usage: just build-config SOURCE DESTINATION
just build-config optimismbase
获取测试网ETH
与您的私钥关联的账户必须同时拥有 Base Sepolia 和 Optimism Sepolia ETH。要获取测试网 ETH,请访问:
乐观 Sepolia 水龙头
底座 Sepolia 水龙头
🏃🏽🏃🏻♀️ 快速入门
该项目附带一个名为 x-counter 的内置虚拟应用程序(它可以跨远程链上的两个合约同步计数器)。您可以在目录中找到合约/contractsXCounterUC.sol 和 XCounter.sol(前者在使用通用通道时,后者在创建自定义 IBC 通道时)。
通用频道
最简单的加入方式是使用通用频道。通用通道是一个 IBC 通道,其中端口由每条链上的 Polymer 通用通道中间件合约拥有。
当用户部署通用通道兼容合约(这意味着继承UniversalChanIbcApp基础合约)时,它将能够连接到通用通道中间件,定义通用数据包,然后通用数据包将由通用通道处理程序包装成IBC数据包并解开通过目标链上的对应项(汇总)。然后,目标上的通用通道中间件将解开 IBC 数据包并将数据发送到目标上的应用程序。
在文档中了解有关通用通道的更多信息。
模板存储库中默认的配置文件允许通过运行以下命令快速发送数据包:
just send-packet base
在 Base Sepolia 上的 XCounterUC 合约与 OP Sepolia 之间发送数据包,反之亦然。
您可以在文档中找到通用通道中间件的详细信息。
在Polymer IBC explorer上检查数据包是否通过。
定制IBC通道
还有一个简单的方法可以快速尝试通过自定义 IBC 通道发送数据包。与通用通道相比,自定义 IBC 通道需要通道握手来打开专用 IBC 通道(这可能需要一段时间,具体取决于客户端延迟),但随后可以完全控制专用 IBC 通道,从而实现与其他应用程序的故障隔离。
要使您的应用程序与自定义 IBC 通道兼容,请让它继承CustomChanIbcApp基础合约。
使用默认的 XCounter.sol 合约运行以下命令对项目进行完整的 E2E 扫描:
# Usage: just do-it
just do-it
它在底层执行以下操作:
# Run the full E2E flow by setting the contracts, deploying them, creating a channel, and sending a packet
# Usage: just do-it
do-it:
echo "Running the full E2E flow..."
just set-contracts optimism XCounter false && just set-contracts base XCounter false
just deploy optimism base
just create-channel
just send-packet optimism
echo "You've done it!"
它确保您设置了正确的合约、部署新实例、创建通道并在创建后通过通道发送数据包。
注意:默认情况下,sim-client 用于改善延迟。这对于迭代开发和测试很有用,但也不安全,因为它不涉及证明。确保通过运行另一个 just 命令转移到带有证明的客户端......
# Usage: just switch-client
just switch-client
在Polymer IBC explorer上检查数据包是否通过。
💻 开发您的自定义应用程序
作为开发人员,您的主要工作是开发构成跨链逻辑的合约。
您可以使用“/contracts/base”目录中的合约作为基础合约来创建启用 IBC 的合约,这些合约可以通过通用通道发送数据包,也可以创建自己的通道来发送数据包。
Polymer 官方文档中提供了有关如何开发这些合约的完整演练。
🕹️与合约互动
当合约准备就绪后,您可以继续通过脚本与合约进行交互。最常见的命令有一个 Justfile,其底层脚本位于 /scripts 文件夹中。
脚本文件夹中的文件/private夹包含您不太可能需要接触的脚本。您(可能)与之交互的唯一脚本是:
项目中有三种类型的默认脚本:
允许deploy.js您部署应用程序合约。您可能想要向 Hardhat 脚本添加额外的部署逻辑。
在该/contracts文件夹中,您将找到arguments.js添加自定义构造函数参数以使用deploy.js脚本进行自动部署。
该send-packet.js脚本通过现有的自定义通道发送数据包,并且send-universal-packet.js专门用于通过通用通道发送数据包。您可能需要在发送数据包之前或之后添加额外的逻辑来自定义您的应用程序。
对于上述大多数操作以及更多操作,只有结合相关逻辑并以自动方式更新配置文件的配方。
注意:这些是提供的默认脚本。它们提供与合约最通用的交互来部署、创建通道和发送数据包。对于更复杂的用例,您需要根据您的用例自定义脚本。请参阅高级用法以获取更多信息。
部署
在部署之前,请确保使用您要部署到的每个链的合约类型更新 config.json。
将合约设置为配置
通过运行以下命令来执行此操作:
# Usage: just set-contracts [chain] [contract_type] [universal]
just set-contracts optimism MyContract true
将MyContract工件部署到 Optimism (Sepolia) 链。
重要提示:如果您的合约使用通用或自定义渠道,您可以在此处进行设置。确保这与您在开发应用程序时继承的基础合约(UniversalChanIbcApp 或 CustomChanIbcApp)相对应。
构造函数参数
默认情况下,任何继承基础 IBC 应用程序合约的应用程序都需要将调度程序或通用通道处理程序地址传递到构造函数中。显然,您可能还想添加其他构造函数参数。要仍然使用该just deploy source destination配方,请将参数添加到arguments.js 文件中
module.exports = {
"XCounter": [],
"XCounterUC": [],
// Add your contract types here, along with the list of custom constructor arguments
// DO NOT ADD THE DISPATCHER OR UNIVERSAL CHANNEL HANDLER ADDRESSES HERE!!!
// These will be added in the deploy script at $ROOT/scripts/deploy.js
};
最后:部署
然后运行:
# Usage: just deploy [source] [destination]
just deploy optimism base
其中脚本将自动检测您使用的是自定义还是通用 IBC 通道。
该脚本将获取部署的输出并使用所有相关信息更新配置文件。
在继续之前,您需要检查 .env 和配置文件中的变量是否与实际部署的合约中存储的变量一致……尤其是当您积极使用不同的配置文件和合约时。
要进行健全性检查,请运行:
# Usage: just sanity-check
just sanity-check
创建频道
如果您使用通用频道,则不需要创建频道。您的合约将从通用通道处理程序合约发送和接收数据包数据,该合约已经具有用于发送数据包的通用通道。在这种情况下,您可以直接继续发送(通用)数据包。
要创建自定义通道,请运行:
just create-channel
这在基础和乐观之间建立了一条通道。请注意订单很重要;如果您选择乐观作为上面的源链(第一个参数),默认情况下它将从乐观创建通道,反之亦然。
该脚本将获取通道创建的输出并使用所有相关信息更新配置文件。
查看资源管理器中的频道选项卡,了解与您的合约相关的正确频道 ID 是否已在配置中更新。
发送数据包
最后运行:
# Usage: just send-packet
just send-packet optimism
通过通道发送数据包(脚本查看配置的 isUniversal 标志以了解是否应该使用自定义数据包或通用数据包)。您可以选择乐观或基本来发送数据包。
验证,不要相信
作为入门值,sim-client 用于改善延迟。sim-client 对于迭代开发和测试很有用,但也不安全,因为它不涉及证明。通过将配置文件中的标志设置为 true,确保移动到带有证明的客户端:proofsEnabled
// In config/proof-config.json
{
...,
"proofsEnabled": true,
...
}
这将使用带有证明的操作栈客户端,确保中继器证明整个过程中每一步所提交的内容,确保中继器上没有信任假设。
🤝 贡献
我们欢迎并鼓励社区做出贡献!您可以通过以下方式做出贡献。
查看未解决的问题。如果某个问题带有“需要帮助”标签或“好第一期”,那么这些问题就可供争夺。将自己分配给该问题,以便人们知道您正在解决该问题。
或者,您可以针对新想法或反馈提出问题。
当您想贡献代码时,请按照以下步骤操作:
分叉存储库:首先分叉此存储库。
应用改进:想要优化某些内容或添加对其他开发人员工具的支持?添加您的更改!
创建拉取请求:准备好并测试添加的代码后,请向存储库提交 PR,我们将尽快进行审核。