CAIP-25实施指南：迁移至空/未定义的必要命名空间

曾经，链切换是一项相当繁琐的操作。如果用户想要在以太坊上交换一些代币，然后在Optimism上进行操作，他们必须断开并重新连接钱包才能实现。

这种繁琐的链切换用户体验是需要解决的问题，我们通过WalletConnect v2.0实现了这一目标。得益于新版本的WalletConnect协议（该协议设计时考虑了链无关改进提案标准，特别是CAIP-25），用户首次可以在同一会话中切换链。这种方法意味着该协议是链无关、事件无关、方法无关，甚至钱包无关的，这使得外部拥有账户（EOA）钱包、智能合约钱包（SCW）或任何其他类型的钱包都有可能采用。

为实现这一目标，WalletConnect v2.0提供了一个开发者友好的抽象概念，称为"命名空间"，钱包和应用程序通过协商来定义给定钱包会话的"授权范围"，如CAIP-217所定义。CAIP-217本身是基于互联网工程任务组（IETF）为OAuth 2.0制定的RAR扩展建模的。

然而，我们最初对CAIP-25的抽象（该抽象定义了链无关提供商与钱包接口的授权程序，作为其初始化和/或"握手"协议的一部分）忽略了一些钱包所需的工作量。特别是基于智能合约的钱包，在用户体验和dapp接口方面，实现链选择和切换的方式彼此截然不同。我们感谢WalletConnect用户提醒我们注意这一点，并深深感谢您在我们努力解决这个问题时的耐心。

在为WalletConnect v2.0迁移做准备时，许多应用程序还选择在首次连接时要求所有最关键的链、方法和事件（即必要命名空间），而将其他链、方法和事件设为可选，以便最终用户灵活使用（即可选命名空间）。虽然这种实现方式对许多钱包效果良好，但对其他钱包则带来了挑战，最显著的是像Safe这样的智能合约钱包，它们出于设计考虑，一次只能在一个链上运行。如果一个应用程序将以太坊主网（chainID 1）设置为必要命名空间之一，那么一个仅在其自己的Gnosis链上运行的Safe钱包将不得不拒绝连接——这对最终用户体验来说并不理想！

鉴于这些原因，我们今天向钱包和应用程序提供关于CAIP-25和命名空间实施的新指南，以便我们作为一个生态系统能够确保全球web3用户的无缝用户体验。特别是，wagmi将在12月7日更新其命名空间设置，这就是为什么我们强烈建议您在此日期之前测试并确保对空/未定义的必要命名空间的支持。

钱包和应用程序的CAIP-25实施指南：必要和可选命名空间

应用程序在与钱包建立连接时，应仔细考虑其初始/默认设置是什么，以及如何对各种可能的响应做出反应。

另一方面，钱包在支持与应用程序的连接方面有更多选择。尽管如此，钱包还应分析其针对不同使用模式和边缘情况的代码路径，以最小化连接停滞和负面最终用户体验的数量。

如果您是钱包开发者：

确保您正在利用我们的命名空间构建器实用工具，该工具会为您解析命名空间。同时确保您已更新到以下Web3Wallet SDK或更高版本——Swift：1.8.6；Kotlin：BOM-1.17.0；JavaScript：^1.9.1。这将使您的钱包能够处理应用程序可能支持的所有命名空间场景，这些场景由CAIP-25支持。
为与命名空间相关的连接错误提供最终用户消息。
考虑围绕"渐进式授权"（随着时间的推移暴露更多命名空间，以解锁应用程序内更多实用功能和用户场景）的用户故事，以及这可能如何与默认设置或用户配置交互。

如果您选择不利用我们的命名空间构建器（不推荐）或它在您选择的平台上不可用，请确保至少您的钱包能够处理以下常见使用模式：

案例#1：所有应用程序的推荐默认设置

requiredNamespace为空/未定义
optionalNamespace已定义

案例#2

requiredNamespace已定义
optionalNamespace已定义

案例#3

requiredNamespace已定义
optionalNamespace为空/未定义

案例#4

requiredNamespace为空/未定义
optionalNamespace为空/未定义

您也可以在我们的文档中找到上述指南。

如果您是应用程序开发者：

未来，WalletConnect建议任何应用程序在其命名空间设置中为最终用户提供尽可能大的灵活性：

requiredNamespaces必须未定义/未设置。在ethereum-provider库中，requiredNamespaces由chains、methods和events属性表示。
应用程序支持的所有链必须在optionalNamespaces的范围内设置。
确保您正在监听钱包事件，因为它们可能会更新会话权限（例如添加新链）。

这种方法将使您的应用程序能够继续与EOA钱包连接，并且还将平滑其他类型钱包（特别是像Safe这样的智能合约钱包，以及下一代账户抽象钱包）的用户体验差异和连接可能性。

应用程序的技术实施指南

请根据您的设置按照以下说明操作。

Ethereum Provider包

如果您是使用Ethereum provider包的应用程序开发者，我们建议以下操作：

将所有链移动到optionalChains，并将chains属性保留为未定义/未设置。
将Events和Methods设置为未定义/未设置。
optionalMethods和optionalEvents默认由库填充，因此您不需要添加它们，除非您希望对为会话提议的方法和事件进行选择。

实施示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


const provider = await EthereumProvider.init({
  projectId: 'YOUR_PROJECT_ID',
  optionalChains:[1, 5, 56, 42161, 137],
  showQrModal: true,
  metadata: {
    name: "My Dapp",
    description: "My Dapp description",
    url: "https://my-dapp.com",
    icons: ["https://my-dapp.com/logo.png"],
  },
})

Web3Modal SDK

将wagmi更新到1.4.9或更高版本。请注意，此版本将于12月7日发布。

1

npm i wagmi@latest

Wagmi — WalletConnectConnector

将wagmi更新到1.4.9或更高版本。请注意，此版本将于12月7日发布。

您也可以在我们的文档中找到上述指南。

需要帮助——或想参与其中？

如果您遇到任何困难，WalletConnect团队随时为您提供帮助。您只需在WalletConnect GitHub上联系我们，并告知我们您面临的问题。

正如这篇博客文章所示，我们在WalletConnect所做的许多幕后工作都专注于web3标准，这些标准对于推动这个行业向前发展至关重要。如果您对技术和社区协调充满热情，我强烈鼓励您参与其中。

通知：Explorer API传统端点弃用

作为我们持续致力于提供安全、高效和最新服务的一部分，我们宣布将在2024年1月30日13:00（GMT）弃用Explorer API中的某些传统端点。此弃用仅影响仍在使用registry.walletconnect.ORG或此处列出的受影响端点的用户；您也可以在那里找到升级路径。

要了解我们的最新公告，请加入我们的Discord并在Twitter上关注我们。如果您是有兴趣集成WalletConnect的钱包或应用程序，请前往我们的网站并浏览我们的文档。