ERC-7811: 钱包资产发现

钱包与 Dapp 共享用户完整资产列表的 JSON-RPC 方法，包括仅通过链上数据不易找到的资产

摘要

本 ERC 引入了一个新的 RPC 调用 wallet_getAssets，供钱包向 Dapp 声明用户拥有的资产。这允许更准确的资产发现，并使用无法在链上获得但可以由钱包提供的资产。

动机

目前，Dapp 主要依赖链上数据来确定用户的余额，这可能具有局限性。此外，Dapp 可能会限制用户发起钱包可以解决的操作，因为它无法考虑用户在不同账户或链上的总资产。

钱包已经拥有关于用户资产的信息，包括那些在链上不可见的信息，并且需要一种将该信息传递给 Dapp 的方法。

规范

本文档中的关键词“MUST”，“MUST NOT”，“REQUIRED”，“SHALL”，“SHALL NOT”，“SHOULD”，“SHOULD NOT”，“RECOMMENDED”，“MAY”和“OPTIONAL”应按照 RFC 2119 中的描述进行解释。

方法: wallet_getAssets

请求 schema

type Hex = `0x${string}`;
type Address = Hex;
type AssetType = "native" | "erc20" | "erc721" | string;
type Address = Hex;
type AddressOrNative = Address | "native";
type Eip155ChainId = Hex;

type WalletGetAssetsRequest = {
  account: Address;
  assetFilter?: Record<
    Eip155ChainId,
    {
      address: AddressOrNative;
      type: AssetType;
    }[]
  >;
  assetTypeFilter?: AssetType[];
  chainFilter?: Hex[];
};

account 是一个 REQUIRED 字段，指示要请求哪个账户的资产。

assetFilter 是 OPTIONAL 字段，接受资产标识符列表。 每个资产标识符都是一个对象，包含 address 和 type 字段，并且作用域由 chainId 限定，其中 ChainId MUST 是一个有效的 EIP-155 chainId。

如果提供了 assetFilter 字段，即使 assetTypeFilter 或 chainFilter 可能进一步筛选结果，钱包 MUST 仅返回其中指定的资产。 这实际上完全忽略了 assetTypeFilter 和 chainFilter 字段。 这样做的原因是它们已经在 assetFilter 中隐式定义。

如果省略了 assetFilter 字段，则钱包 SHOULD 返回所请求账户的所有可用资产。 RECOMMENDED 返回的资产应按钱包确定的估计值降序排列。

assetTypeFilter 是一个 OPTIONAL 字段，指定资产类型数组，如本 ERC 中所定义。如果提供了 assetTypeFilter 字段，钱包 MUST 仅在响应中包含这些类型的资产。

chainFilter 是一个 OPTIONAL 字段，指定链 ID 数组，其中数组中的每个值 MUST 是一个有效的 EIP-155 chainId

wallet_getAssets 的使用者 SHOULD 使用尽可能精细的值设置 assetFilter，assetTypeFilter 和 chainFilter。 例如，如果一个应用仅对与单个链上的单个 token 进行交互感兴趣，则应为此提供过滤器。 这样做既可以确保钱包和底层基础设施不会产生过高的成本，又可以显着提高客户端应用程序的性能。

示例请求

{
  "account": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "assetFilter": {
    "0x1": [
      {
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "type": "erc20"
      },
      {
        "address": "native",
        "type": "native"
      }
    ],
    "0xa": [
      {
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "type": "erc20"
      }
    ]
  },
  "assetTypeFilter": ["ERC20", "native"],
  "chainFilter": ["0x1"]
}

响应 schema

type Asset = {
  address: AddressOrNative;
  balance: Hex;
  type: string;
  metadata: any;
};
type WalletGetAssetsResponse = Record<Hex, Asset[]>;

键 MUST 是 EIP-155 chainId

资产字段：

address 是资产的地址，表示为 Hex 或 native 字符串（对于原生资产）。

balance 是资产的余额，表示为 Hex

type: 一个字符串，指示资产的类型。 常见的资产类型包括但不限于：

• erc20: 对于 ERC-20 tokens
• erc721: 对于 ERC-721 tokens (NFTs)
• native: 对于链的原生资产

metadata: 一个 OPTIONAL 对象，包含关于资产的附加信息。元数据对象中的特定字段可能因资产类型和钱包的实现而异。

示例响应

{
  "0x1": [
    {
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "balance": "0xcaaea35047fe5702",
      "type": "ERC20",
      "metadata": {
        "name": "Token",
        "symbol": "TOK",
        "decimals": 18
      }
    },
    {
      "address": "native",
      "balance": "0xcaaea35047fe5702",
      "type": "native"
    }
  ],
  "0xa": [
    {
      "address": "0x456",
      "balance": "0xcd5595",
      "type": "ERC721",
      "metadata": {
        //...
      }
    }
  ]
}

众所周知的资产类型

以下是众所周知的资产类型的 metadata 扩展。 符合此 ERC 并返回这些众所周知的资产类型的实现 MUST 在 metadata 中至少返回这些字段。 实现 MAY 返回比此处指定的字段更多的字段。 此 ERC 未指定资产类型的详尽列表。 由于类型是通用字符串，因此 Dapp 期望的类型与钱包返回的类型之间可能存在不匹配。 重要的是，没有两个资产共享相同的类型。 因此，应在未来的 ERC 中指定新的资产类型。

Native

type NativeAsset = {
  address: "native";
  balance: Hex;
  type: "native";
};

示例：

{
  "address": "native",
  "balance": "0xcaaea35047fe5702",
  "type": "native"
}

ERC-20 Token

type Erc20Asset = {
  address: Hex;
  balance: Hex;
  type: "erc20";
  metadata: {
    name: string;
    symbol: string;
    decimals: number;
  };
};

示例：

{
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "balance": "0xcaaea35047fe5702",
  "type": "erc20",
  "metadata": {
    "name": "Token",
    "symbol": "TOK",
    "decimals": 18
  }
}

ERC-721 Token

type Erc721Asset = {
  address: Hex;
  balance: Hex;
  type: "erc721";
  metadata: {
    name: string;
    symbol: string;
    tokenId: Hex;
    tokenURI?: string;
  };
};

示例：

{
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "balance": "0x01",
  "type": "erc721",
  "metadata": {
    "name": "Thor's hammer",
    "symbol": "THOR",
    "tokenId": "0x1",
    "tokenURI": "ipfs://hash"
  }
}

功能

如果钱包使用 CAIP-25 授权，则钱包 SHOULD 在 eip155 命名空间的 sessionScopes 的 methods 数组中包含 wallet_getAssets。

如果钱包支持 ERC-5792，则钱包 SHOULD 使用 assetDiscovery 键响应 wallet_getCapabilities 请求。 值应该是一个带有 supported 键和值 true 的对象 钱包 SHOULD 为每个 chainId 包含此项。

{
  "0xa": {
    "assetDiscovery": {
      "supported": true
    }
  }
}

理由

安全注意事项

版权

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

Citation

Please cite this document as:

Luka Isailovic (@lukaisailovic), Konrad Kopp (@kopy-kat), Derek Rein (@arein), Chris Smith (@chris13524), "ERC-7811: 钱包资产发现 [DRAFT]," Ethereum Improvement Proposals, no. 7811, November 2024. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7811.