EIP-2256: wallet_getOwnedAssets JSON-RPC 方法

简单总结

这是一个关于新的 JSON-RPC 调用的提案，用于在获得用户许可的情况下，从钱包中检索由以太坊地址拥有的资产选择。

摘要

目前还没有标准化的方法让 dApp 向用户请求拥有的资产列表。现在，每个 dApp 都需要维护一个所有流行的或现有的资产列表，并针对每个资产检查用户在区块链上的余额。这导致了 dApp 之间重复的工作。这还会导致用户看到他们不关心的，来自各种不需要的空投的资产选项。

动机

有一些金融 dApp 需要从用户那里获取拥有的资产列表，用于各种目的——计算税收、选择自定义支付选项等。现在，这些 dApp 都被迫维护一个流行的资产列表（智能合约地址，ABI），并从区块链中检索每个资产的用户数据。这导致了工作重复和非优化的用户体验，用户看到的资产选项多于或少于他们想要的——各种空投，dApp 维护的不完整的资产列表。

这个拥有的资产列表可以从用户使用的钱包中检索。钱包可以允许用户只管理用户感兴趣的资产。因此，提出了一个新的 JSON-RPC 方法：wallet_getOwnedAssets。这个方法是 EIP-747 的补充，后者提出了一种让网站建议用户在其钱包上关注新资产的方法。

规范

新的 JSON-RPC 方法将被添加到 web3 浏览器：wallet_getOwnedAssets。此方法用于 dApp-钱包通信，并且仅针对钱包已为用户帐户列入白名单的资产。

参数：

• 类型 address，拥有资产的以太坊地址
• options 对象，可选：
  • chainId - 类型 uint，链 id，遵循 EIP-155；可选
  • limit - 类型 uint，dApp 期望返回的拥有的资产的最大数量；可选
  • types - 类型 string[]，资产接口标识符数组，例如 ['ERC20', 'ERC721']；可选
  • justification - 类型 string，dApp 提供的可读文本，解释此请求的预期目的；可选但推荐

结果：

• 带有资产记录的数组：
  • address - 类型 address，以太坊校验和地址
  • chainId - 类型 uint，部署资产的链的标识符
  • type - 类型 string，资产接口 ERC 标识符；例如 ERC20；可选 - 可以使用 EIP-1820
  • options - 具有资产特定字段的对象；ERC20 代币示例：
    • name - 类型 string，代币名称；如果代币未实现，则为可选
    • symbol - 类型 string，代币符号；如果代币未实现，则为可选
    • icon - 类型 base64，代币图标；可选
    • balance - 类型 uint，用户拥有的代币数量，以最小的代币面额表示
    • decimals - 类型 uint，代币实现的十进制数；可选

例子

1) 请求返回用户的所有拥有的资产：

{
  "id":1,
  "jsonrpc": "2.0",
  "method": "wallet_getOwnedAssets",
  "params": [
    "0x3333333333333333333333333333333333333333",
    {
      "justification": "dApp 需要知道你所有的资产，以便正确计算你的税收。"
    }
  ]
}

结果：

{
  "id":1,
  "jsonrpc": "2.0",
  "result": [
    {
      "address": "0x0000000000000000000000000000000000000001",
      "chainId": 1,
      "type": "ERC20",
      "options": {
        "name": "TokenA",
        "symbol": "TKA",
        "icon": "data:image/gif;base64,R0lGODlhAQABAIABAP///wAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==",
        "balance": 1000000000000,
        "decimals": 18
      }
    },
    {
      "address": "0x0000000000000000000000000000000000000002",
      "chainId": 3,
      "type": "ERC20",
      "options": {
        "name": "TokenB",
        "symbol": "TKB",
        "icon": "data:image/gif;base64,R0lGODlhAQABAIABAP///wAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==",
        "balance": 2000000000000,
        "decimals": 18
      }
    },
    {
      "address": "0x0000000000000000000000000000000000000003",
      "chainId": 42,
      "type": "ERC721",
      "options": {
        "name": "TokenC",
        "symbol": "TKC",
        "icon": "data:image/gif;base64,R0lGODlhAQABAIABAP///wAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==",
        "balance": 10
      }
    },
  ]
}

2) 请求返回一个在 chainId 1 上部署的 ERC20 拥有的资产：

{
  "id":1,
  "jsonrpc": "2.0",
  "method": "wallet_getOwnedAssets",
  "params": [
    "0x3333333333333333333333333333333333333333",
    {
      "chainId": 1,
      "limit": 1,
      "types": ["ERC20"],
      "justification": "选择你选择的代币，以便支付我们的服务费用。"
    }
  ]
}

结果：

{
  "id":1,
  "jsonrpc": "2.0",
  "result": [
    {
      "address": "0x0000000000000000000000000000000000000001",
      "chainId": 1,
      "type": "ERC20",
      "options": {
        "name": "TokenA",
        "symbol": "TKA",
        "icon": "data:image/gif;base64,R0lGODlhAQABAIABAP///wAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==",
        "balance": 1000000000000,
        "decimals": 18
      }
    }
  ]
}

UI 最佳实践

钱包应向用户显示一个 UI，显示请求。 用户可以：

• 接受请求，在这种情况下，dApp 接收所有请求的资产
• 拒绝请求
• 通过减少返回给 dApp 的拥有的资产数量来修改请求

如果请求了所有拥有的资产，拥有的资产总数将显示给用户。用户还可以选择将返回给 dApp 的资产，从而修改请求。

如果请求选择，用户将从拥有的资产列表中进行选择。

作为一种优化，钱包可以维护一个用户经常使用的资产列表，并首先显示该列表，并可以选择使用用户较少使用的拥有的资产来扩展该列表。

理由

为了避免需要维护所有或流行的资产列表的 dApp 的工作重复，并提供最佳的用户体验，提出了 wallet_getOwnedAssets JSON-RPC 方法。

chainId 和 types 可选参数使 dApp 能够提供选项，以便根据 dApp 的功能限制钱包将向用户展示的选择列表。limit 参数使 dApp 能够告诉用户用户可以选择的帐户的上限。是否也应该提供下限还有待观察。目前，这个下限可以认为是 1。

options 响应字段为 dApp 提供了特定于资产的选项，通过使用钱包使用的相同的视觉和文本标识符来实现更好的用户体验，使用户更容易理解 dApp 的 UI。

address，type 响应字段提供了关于资产的足够信息，使 dApp 能够提供额外的特定于资产的功能。

balance 响应字段是一种优化，允许 dApp 显示用户的余额而无需查询区块链。通常，此信息已公开。

向后兼容性

不相关，因为这是一个新方法。

测试用例

待完成。

实现

待完成。

版权

版权和相关权利通过 CC0 放弃。

Citation

Please cite this document as:

Loredana Cirstea (@loredanacirstea), "EIP-2256: wallet_getOwnedAssets JSON-RPC 方法 [DRAFT]," Ethereum Improvement Proposals, no. 2256, August 2019. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-2256.