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：所有应用程序的推荐默认设置

1
2


requiredNamespace为空/未定义
optionalNamespace已定义

案例#2

1
2


requiredNamespace已定义
optionalNamespace已定义

案例#3

1
2


requiredNamespace已定义
optionalNamespace为空/未定义

案例#4

1
2


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的钱包或应用程序，请访问我们的网站并浏览我们的文档。