EIP-3085: wallet_addEthereumChain RPC 方法

添加一个 RPC 方法来添加 EVM 兼容链

摘要

此 EIP 添加了一个钱包命名空间的 RPC 方法：wallet_addEtherereumChain，提供了一个用于将链添加到以太坊钱包的标准接口。

规范

本文档中的关键词“必须”，“禁止”，“需要”，“应该”，“不应该”，“推荐”，“可以”和“可选”应按照 RFC 2119 中的描述进行解释。

本提案定义了一个新的 RPC 方法 wallet_addEthereumChain。

wallet_addEthereumChain

wallet_addEthereumChain 方法用于向钱包建议将新链添加到钱包的链列表中。它接受一个参数，如果链成功添加则返回 null，如果链未添加则返回错误。

wallet_addEthereumChain 参数

wallet_addEthereumChain 方法接受一个参数，一个 EthereumChainAddRequest 对象，定义如下：

interface AddEthereumChainParameter {
  chainId: string;
  blockExplorerUrls?: string[];
  chainName?: string;
  iconUrls?: string[];
  nativeCurrency?: {
    name: string;
    symbol: string;
    decimals: number;
  };
  rpcUrls?: string[];
}

根据此规范，只有 chainId 是必需的，但钱包 MAY 需要任何其他列出的字段，对它们施加额外的要求，或者完全忽略它们。

如果某个字段不符合此规范的要求，并且钱包不忽略该字段，则钱包 MUST 拒绝该请求。

chainId 是链的整数 ID，表示为十六进制字符串，如 EIP-155 所示。blockExplorerUrls、iconUrls 和 rpcUrls 字段是字符串数组，每个字符串 MUST 是有效的 URL。nativeCurrency 字段是一个包含 name、symbol 和 decimals 字段的对象，其中 decimals 是一个非负整数，应按 EIP-20 中的方式解释。chainName 字段是一个字符串，是该链的人类可读名称。

如果 chainId 不是有效的十六进制字符串，或者 chainId 不是有效的链 ID，则钱包 MUST 拒绝该请求。

如果未提供 rpcUrls 字段，或者 rpcUrls 字段是一个空数组，则钱包 MUST 拒绝该请求。如果 rpcUrls 包含任何不是有效 URL 的字符串，则钱包 MUST 拒绝该请求。如果 chainId 与任何 RPC url 的 eth_chainId 方法的值不匹配，则钱包必须拒绝该请求。

如果提供了 nativeCurrency 字段，但缺少 name、symbol 或 decimals 字段中的任何一个，则钱包 MUST 拒绝该请求。如果 decimals 字段是一个负整数，则钱包 MUST 拒绝该请求。

如果提供了 blockExplorerUrls 字段，并且任何 URL 都不是有效 URL，则钱包 MUST 拒绝该请求。

如果提供了 iconUrls 字段，并且任何 URL 都不是有效 URL 或未指向有效的图像，则钱包 MUST 拒绝该请求。

钱包 MUST 拒绝任何使用 file: 或 http: 方案的 URL。

wallet_addEthereumChain 返回值

如果请求成功，则该方法 MUST 返回 null，否则返回错误。钱包 MAY 出于任何原因拒绝该请求。

即使钱包不拒绝该请求，也不应假定链已由钱包自动选择。

除非用户拒绝该请求或验证失败，否则添加已添加链的请求 SHOULD 成功。

钱包 MUST NOT 允许多次添加相同的 chainId。有关更多信息，请参见安全考虑。

理由

wallet_addEthereumChain 的设计刻意忽略了“添加”链到钱包的含义。 “添加”链到钱包的含义取决于钱包的实现。

调用该方法时，指定 chainId 始终是必要的，因为在以太坊链的宇宙中，EIP-155 链 ID 实际上是链 GUID。 其余参数相当于作者估计的，钱包为了有效地支持链并将其表示给用户而需要的最少信息。 网络 ID（根据 net_version RPC 方法）被省略，因为它实际上已被链 ID 取代。

出于安全原因，钱包应始终尝试验证请求者提供的链元数据，并且可以选择完全在其他地方获取元数据。 无论哪种方式，只有钱包才能知道它需要请求者提供哪些链元数据才能“添加”链。 因此，除了 chainId 之外的所有参数都被指定为可选参数，即使钱包在实践中可能需要它们。

如果钱包具有“活动”或“当前选择”链的概念，则本规范不强制要求钱包在成功请求后“切换”其“活动”或“当前选择”链。 就像“添加”链的含义一样，“切换”链是钱包的实现细节，因此超出范围。

安全考虑

wallet_addEthereumChain 是一种强大的方法，如果实现不正确，会将最终用户暴露于严重的风险中。 通过验证钱包中的请求数据，并在钱包 UI 中清楚地区分不同的链，可以避免许多这些风险。

链 ID

由于用于交易签名的链 ID 确定了交易有效的链，因此正确处理链 ID 至关重要。 钱包应该：

• 确保提交的链 ID 有效。
  • 它应该是一个 0x 前缀的十六进制字符串，根据 EIP-695，并解析为一个整数。
• 阻止多次添加相同的链 ID。
  • 有关如何处理多个 RPC 端点，请参见下一节。
• 仅使用提交的链 ID 对交易进行签名，绝不使用从 RPC 端点收到的链 ID。
  • 恶意或错误的端点可能会返回任意链 ID，并可能导致用户为意外的链签署交易。
• 验证指定的链 ID 是否与来自端点的 eth_chainId 的返回值匹配，如上所述。

RPC 端点和 RPC URL

钱包通常通过 RPC 端点与链进行交互，该端点由某些 URL 标识。 大多数钱包都附带一组链和相应的受信任的 RPC 端点。 rpcUrls 参数标识的端点不能被认为是诚实的、正确的，甚至不能被认为是指向同一条链。 此外，即使是受信任的端点也可能根据其数据收集实践将用户暴露于隐私风险。

因此，钱包应该：

• 通知用户，他们的链上活动和 IP 地址将暴露给 RPC 端点。
• 如果端点对钱包未知，请通知用户该端点可能会以意想不到的方式运行。
• 在与端点交互时，遵守良好的 Web 安全实践，例如需要 HTTPS。
• 清楚地告知用户，在任何给定时刻，哪个 RPC URL 被用于与链进行通信，并告知用户使用多个 RPC 端点与同一链进行交互的风险。

验证链数据

实现 wallet_addEthereumChain 的钱包应该期望遇到完全不为钱包维护者所知的链的请求。 也就是说，存在社区资源，可以用来验证对许多以太坊链的请求。 钱包应该维护一个已知链的列表，并根据该列表验证添加链的请求。 实际上，钱包甚至可能更喜欢自己的链元数据，而不是 wallet_addEthereumChain 请求中提交的任何内容。

用户体验

向钱包添加新链可能会对钱包的功能和用户体验产生重大影响。 未经用户的明确同意，不应添加链，并且应在钱包 UI 中清楚地区分不同的链。 为了实现这些目标，钱包应该：

• 在收到 wallet_addEthereumChain 请求时，显示一个确认信息，告知用户特定请求者已请求添加该链。
• 确保任何链元数据（例如 nativeCurrency 和 blockExplorerUrls）都经过验证并在 UI 中得到最大程度的利用。
• 如果通过 iconUrls 提供了任何图像，请确保用户了解这些图标可能会错误地表示实际添加的链。
• 如果钱包 UI 具有“当前选择”或“当前活动”链的概念，请确保用户了解何时使用 wallet_addEthereumChain 添加的链变为选中状态。

保护用户隐私

尽管通常应将添加已添加链的请求视为成功，但将此类请求视为_自动_成功会将用户已添加到其钱包的链的信息泄露给请求者。 为了保护用户隐私，wallet_addEthereumChain 的实施者应考虑即使在这些情况下也显示用户确认信息。 如果用户拒绝该请求，则钱包应返回与正常情况相同的用户拒绝错误，以便请求者无法在没有明确许可的情况下了解钱包支持哪些链。

版权

在 CC0 下放弃版权和相关权利。

Citation

Please cite this document as:

Erik Marks (@rekmarks), Pedro Gomes (@pedrouid), Pandapip1 (@Pandapip1), "EIP-3085: wallet_addEthereumChain RPC 方法 [DRAFT]," Ethereum Improvement Proposals, no. 3085, November 2020. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-3085.