资助申请：将CoW Swap前端迁移至Viem与Wagmi

作者

@bleu @bsvalverde @ribeirojose

经验与资质

bleu 作为 Web3 技术和用户体验合作伙伴，与多家公司和 DAO 进行协作。我们是多个 CoW 协议核心开发者工具背后的团队，并对代码库有深入的理解。

我们在 CoW 方面的过往记录：

• [CoW] 框架无关 SDK：我们重构了 CoW SDK，以原生支持 Viem，从而消除了对 Ethers.js 的依赖。本次资助旨在将这项工作投入实际应用。
• [CoW] Playground 离线模式：（近期已批准）为后端工程师创建了支持离线签名的本地开发环境。
• [CoW] Hook dApps：集成了 Hook dApps 并开发了 cow-shed 模块。

资助描述

CoW Swap 前端目前依赖于 Web3React，这是一个已过时且基本无人维护的库，并使用旧的 Ethers.js 适配器来初始化 CoW SDK。这导致了技术债务、移动端连接不稳定，并且需要变通方案才能支持 EIP-6963（多注入提供商）等现代功能。

此外，当前的钱包和前端代码路径严重依赖 Ethers.js v5 和 TypeChain 生成的 ABI。

当前的 web3-react 技术栈给协议带来了日益增长的风险：

• 该库已无人维护；
• 现有的 EIP-6963 支持是基于 Web3React 的临时解决方案，仍可能导致钱包冲突。
• 当前的钱包集成很脆弱；像 Reown 这样的现代库提供了更卓越的可靠性。
• 集成新链或新钱包需要复杂的自定义代码，而非简单的配置。
• 与基于 Viem 的方法相比，基于 Ethers.js 和 TypeChain 的模式使得代码更难现代化和维护。

作为本次资助的一部分，我们将：

• 从前端完全移除 Web3React，
• 将 SDK 和钱包流程迁移到 Viem + Wagmi，
• 保持对所有现有钱包连接器的完全支持：EIP-6963、注入式浏览器扩展（window.ethereum，包括移动端 web3 浏览器）、WalletConnect、Coinbase Wallet 和 Gnosis Safe，以及
• 从前端钱包/连接层移除 Ethers.js 和 TypeChain（ethers-v5 目标），迁移到 viem 原生原语。

我们将使用 CoW Swap 现有的 LaunchDarkly 功能标志来并行运行新旧技术栈，从而实现逐步推出，并在检测到任何问题时能够即时回滚。

需要更新的关键依赖项

作为此次迁移的一部分，我们还将 Safe SDK 技术栈更新到其最新的主要版本，这些版本提供了 Viem 原生支持并移除了 Ethers.js：

影响

• 修复钱包连接的不稳定性可直接提高“连接钱包”的转化率，确保更少的用户在交易前流失。
• 原生 EIP-6963 支持意味着用户可以在 UI 中选择注入的钱包，而无需禁用浏览器扩展。这消除了对先前自定义 Web3React 变通方案的依赖。
• 将复杂的连接逻辑卸载给维护良好的库（Wagmi），减轻了 CoW 核心团队的维护负担，并降低了新开发者的上手难度。
• 将 DAO 先前对框架无关 SDK 的投资投入实际应用。
• 提高前端稳定性和可维护性，为未来开发提供更清晰的抽象，便于新开发者上手。

资助类型

基于里程碑的资助

里程碑

(*) 自接受/开始后的周数。部分里程碑时间重叠；预计整体在 10 周内完成。

M1：核心架构与 SDK 集成

任务：

• 安装 Viem、Wagmi 和 Reown。
• 在现有的 LaunchDarkly 功能标志后配置新的提供商架构（复用 CoW Swap 当前的标志基础设施）。
• 将 CoW SDK 切换为使用 ViemAdapter（利用我们之前的资助工作），同时保留 EthersV5Adapter 作为标志后的备用方案。
• 为遗留组件实现一个兼容性钩子，该钩子从单一接口提供钱包和链状态。该钩子将根据功能标志在内部决定是从旧技术栈还是新技术栈获取数据，从而允许所有组件在逐步迁移期间使用一致的 API。

交付成果：

• 使用新技术栈构建的功能性应用，已通过 LaunchDarkly 功能标志连接并隐藏。
• 简要架构文档，描述新的连接层、功能标志连接方式以及 SDK 集成（ViemAdapter 与 Ethers 适配器对比）。

M2：钱包连接与 EIP-6963

任务：

• 实现 Reown（AppKit）连接流程。
• 用 Wagmi 原生支持替换自定义的 EIP-6963 支持（修复多注入钱包冲突问题）。
• 将 Trezor 连接逻辑迁移至 Wagmi/Reown（或适配器），同时保持功能对等（账户选择、签名）。
• 为所有支持的钱包实现稳健的连接/断开处理。
• 在功能标志后并行运行现有的 Web3React 连接系统，以便安全比较和回退。

关于 Trezor 验证的说明：Trezor 硬件钱包验证需要 CoW 团队协助进行设备测试。我们将与拥有 Trezor 设备的团队成员协调测试会话，以验证账户选择、消息签名和订单签名流程。

交付成果：

• 所有现有钱包连接器（EIP-6963、包括移动端在内的注入扩展、WalletConnect、Coinbase 和 Gnosis Safe）均通过 Wagmi/Reown 连接；
• 不再保留任何自定义的 EIP-6963 补丁或基于 Web3React 的垫片；

M3：Safe 钱包集成

任务：

• 将 Safe SDK 技术栈（@safe-global/api-kit、@safe-global/protocol-kit、@safe-global/safe-core-sdk-types）升级至“关键待更新依赖项”中列出的目标版本，并移除 @safe-global/safe-ethers-lib。
• 集成 Safe Apps SDK v2。
• 实现 Safe 检测（Safe iframe 和通过 WalletConnect 的 Safe）。
• 确保 Safe 支持捆绑交易（批准 + 预签名流程）。
• 获取 Safe 元数据，如所有者、链和上下文，以优化用户体验。

交付成果：

• 与现有 Safe 功能对等。
• 经过测试的 Safe 连接、签名和捆绑交易流程；

M4：链选择与网络处理

任务：

• 将所有 11 个支持网络的链切换逻辑迁移至 Wagmi/Viem。
• 在用户界面中优雅地处理“不支持的网络”状态。
• 改进 RPC 错误消息，并在适当时自动切换流程。

交付成果：

• 通过 Wagmi 钩子实现稳健的网络切换，包括错误处理。
• 启用新连接层后，前端仅从该层读取链状态。

M5：质量保证、测试与分阶段发布

任务：

• 鉴于当前自动化覆盖有限，引入或显著扩展自动化端到端测试（例如 Cypress/Playwright），覆盖钱包连接/断开、链切换和基本交易流程。
• 在 iOS 和 Android 上测试移动端 WalletConnect（Reown AppKit）。
• 在 Staging 环境启用功能标志，并并行运行两个技术栈；
• 与 CoW Swap 前端团队协调，监控日志、指标和用户反馈以发现回归问题。

M6：前端路由迁移

任务：

• 在关键路由中更新钱包状态的使用：
  • 交换小部件
  • 订单历史
  • 余额
  • 限价订单
  • TWAP 及相关高级订单流程
• 确保组件不再直接依赖 Web3React 钩子，转而依赖 Wagmi/Viem（或在绝对必要时使用兼容性垫片）。
• 修复这些前端路由中与钱包/连接逻辑相关的任何剩余的基于 ethers 的模式。

交付成果：

• 所有目标路由均能使用新的钱包/链状态正常运行。
• 验证这些路由的视觉和行为对等性。
• 本里程碑涵盖的前端路由中无直接使用 Web3React 的情况。

M7：清理与文档

任务：

• 删除 Web3React 代码（47+ 个文件及相关辅助工具）。
• 从 package.json 中移除 @web3-react/* 包。
• 从前端路径中移除基于 Ethers.js 的钱包/连接使用（包括 SDK 的 EthersV5Adapter 代码路径）。
• 更新 TypeChain 配置和生成的类型，使前端合约交互使用与 Viem 兼容的类型/ABI，而非 ethers-v5 目标。
• 将剩余的基于 BigNumber 的钱包/前端代码迁移至 bigint/Viem 原语；
• 在生产环境稳定且新栈验证通过后，移除迁移功能标志。

交付成果：

• 整洁的代码库，具备：
  • 零 Web3React 导入或依赖。
  • 前端零 EthersV5Adapter 使用。
  • 本资助涵盖的钱包/前端路径中无 Ethers.js 使用。
• 移除 TypeChain，改用 SDK。
• 一份简短的架构/迁移说明（ADR 风格），向未来的维护者解释关键决策。

时长

（建议）开始日期：1月5日
预计完成时间：自开始之日起最多 10 周

资金申请

总资金：28,200 xDAI

付款信息

Gnosis Chain 地址：0x554866e3654E8485928334e7F91B5AfC37D18e04

条款与条件

通过提交此资助申请，我确认并同意受《CoW DAO 参与协议》和《CoW DAO 资助协议条款》的约束。