mirror of https://github.com/status-im/EIPs.git
Add ERC for wallet_getOwnedAssets (#2256)
* Add ERC for wallet_getOwnedTokens JSON-RPC method * Add EIP number & discussions URL to EIP-2256 * Fix wallet_getOwnedTokens input arguments * Add chainId as argument to wallet_getOwnedTokens As suggested in https://github.com/ethereum/EIPs/pull/2256#issuecomment-526204181 * Rename EIP-2256 method to wallet_getOwnedAssets, align data struct with EIP-747 Based on the discussions up to and including this comment: https://ethereum-magicians.org/t/eip-2256-add-wallet-getownedassets-json-rpc-method/3600/15 - rename `wallet_getOwnedTokens` to `wallet_getOwnedAssets` - use `options` in the response field, as EIP-747 proposes, to allow for different asset-specific information to be returned - use `asset` instead of `token` where generalization is needed - replace `interface` with `type`, to align with EIP-747 - add `types` as a filter field - add `decimals` as an optional field in `options` * Fix category for EIP-2256 - use Interface As suggested in https://github.com/ethereum/EIPs/pull/2256#discussion_r321153237 * Add justification field for EIP-2256, s/count/limit - add `justification` field in the request arguments, as suggested in https://github.com/ethereum/EIPs/pull/2256#issuecomment-527683267 - replace `count` with `limit`, as `count` is more ambiguous (as revealed in https://github.com/ethereum/EIPs/pull/2253#discussion_r320140105)
This commit is contained in:
Loredana Cirstea
Alex Beregszaszi
parent
43293216a2
commit
4c4dd7dd11
|
|
@ -0,0 +1,197 @@
|
||||||
|
---
|
||||||
|
eip: 2256
|
||||||
|
title: wallet_getOwnedAssets JSON-RPC Method
|
||||||
|
author: Loredana Cirstea (@loredanacirstea)
|
||||||
|
discussions-to: https://ethereum-magicians.org/t/eip-2256-add-wallet-getownedassets-json-rpc-method/3600
|
||||||
|
status: Draft
|
||||||
|
type: Standards Track
|
||||||
|
category: Interface
|
||||||
|
created: 2019-08-29
|
||||||
|
requires: 55, 155, 1474
|
||||||
|
---
|
||||||
|
|
||||||
|
## Simple Summary
|
||||||
|
|
||||||
|
This is a proposal for a new JSON-RPC call for retrieving from a wallet a selection of owned assets by an Ethereum address, with the user's permission.
|
||||||
|
|
||||||
|
## Abstract
|
||||||
|
|
||||||
|
There is no standardized way for a dApp to request a list of owned assets from a user. Now, each dApp needs to keep a list of all the popular or existing assets and check the user's balance against the blockchain, for each of these assets. This leads to duplicated effort across dApps. It also leads to the user being presented with asset options that the user does not care about, from various, unwanted airdrops.
|
||||||
|
|
||||||
|
## Motivation
|
||||||
|
|
||||||
|
There are financial dApps that require a list of owned assets from a user, for various purposes - calculating taxes, selecting customized payment options, etc. Each of these dApps are now forced to keep a list of popular assets (smart contract addresses, ABIs) and retrieve the user's data from the blockchain, for each asset. This leads to effort duplication and nonoptimal UX where the user is presented with either more or less asset options than the user would like - various airdrops, incomplete list of assets kept by the dApp.
|
||||||
|
|
||||||
|
This list of owned assets can be retrieved from the wallet used by the user. The wallet can allow the user to manage only the assets that the user is interested in. Therefore, a new JSON-RPC method is proposed: `wallet_getOwnedAssets`. This method is complementary to [EIP-747](https://eips.ethereum.org/EIPS/eip-747), which proposes a way for sites to suggest users new assets to watch on their wallet.
|
||||||
|
|
||||||
|
## Specification
|
||||||
|
|
||||||
|
New JSON-RPC method to be added to web3 browsers: `wallet_getOwnedAssets`. This method is for dApp-wallet communication and only targets the assets that have already been whitelisted by the wallet, for the user account.
|
||||||
|
|
||||||
|
**Arguments:**
|
||||||
|
- type `address`, Ethereum address that owns the assets
|
||||||
|
- options object, optional:
|
||||||
|
- `chainId` - type `uint`, chain id respecting [EIP-155](https://eips.ethereum.org/EIPS/eip-155); optional
|
||||||
|
- `limit` - type `uint`, the maximum number of owned assets expected by the dApp to be returned; optional
|
||||||
|
- `types` - type `string[]`, array of asset interface identifiers such as `['ERC20', 'ERC721']`; optional
|
||||||
|
- `justification` - type `string`, human-readable text provided by the dApp, explaining the intended purpose of this request; optional but recommended
|
||||||
|
|
||||||
|
**Result:**
|
||||||
|
- array with asset records:
|
||||||
|
- `address` - type `address`, Ethereum checksummed address
|
||||||
|
- `chainId` - type `uint`, identifier for the chain on which the assets are deployed
|
||||||
|
- `type` - type `string`, asset interface ERC identifier; e.g. `ERC20`; optional - [EIP-1820](https://eips.ethereum.org/EIPS/eip-1820) could be used
|
||||||
|
- `options` - an object with asset-specific fields; `ERC20` tokens example:
|
||||||
|
- `name` - type `string`, token name; optional if the token does not implement it
|
||||||
|
- `symbol` - type `string`, token symbol; optional if the token does not implement it
|
||||||
|
- `icon`- type `base64`, token icon; optional
|
||||||
|
- `balance` - type `uint`, the number of tokens that the user owns, in the smallest token denomination
|
||||||
|
- `decimals` - type `uint`, the number of decimals implemented by the token; optional
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
**1) A request to return all of the user's owned assets:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id":1,
|
||||||
|
"jsonrpc": "2.0",
|
||||||
|
"method": "wallet_getOwnedAssets",
|
||||||
|
"params": [
|
||||||
|
"0x3333333333333333333333333333333333333333",
|
||||||
|
{
|
||||||
|
"justification": "The dApp needs to know about all your assets in order to calculate your taxes properly."
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Result:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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) A request to return one `ERC20` owned asset, deployed on `chainId` 1:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id":1,
|
||||||
|
"jsonrpc": "2.0",
|
||||||
|
"method": "wallet_getOwnedAssets",
|
||||||
|
"params": [
|
||||||
|
"0x3333333333333333333333333333333333333333",
|
||||||
|
{
|
||||||
|
"chainId": 1,
|
||||||
|
"limit": 1,
|
||||||
|
"types": ["ERC20"],
|
||||||
|
"justification": "Select your token of choice, in order to pay for our services."
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Result:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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 Best Practices
|
||||||
|
|
||||||
|
The wallet should display a UI to the user, showing the request.
|
||||||
|
The user can:
|
||||||
|
- accept the request, in which case the dApp receives all the requested assets
|
||||||
|
- reject the request
|
||||||
|
- amend the request by lowering the number of owned assets returned to the dApp
|
||||||
|
|
||||||
|
|
||||||
|
If all owned assets are requested, the total number of owned assets will be shown to the user. The user can also choose to select the assets that will be returned to the dApp, amending the request.
|
||||||
|
|
||||||
|
If a selection is requested, the user will select from the list of owned assets.
|
||||||
|
|
||||||
|
As an optimization, wallets can keep a list of frequently used assets by the user, and show that list first, with the option of expanding that list with owned assets that the user uses less frequently.
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
|
||||||
|
In order to avoid duplication of effort for dApps that require keeping a list of all or popular assets and to provide optimal UX, the `wallet_getOwnedAssets` JSON-RPC method is proposed.
|
||||||
|
|
||||||
|
The `chainId` and `types` optional parameters enable dApps to provide options in order to restrict the selection list that the user will be presented with by the wallet, in accordance with the dApp's functionality. The `limit` parameter enables the dApp to tell the user an upper limit of accounts that the user can select. It remains to be seen if a lower bound should also be provided. At the moment, this lower bound can be considered as being `1`.
|
||||||
|
|
||||||
|
The `options` response field provides the dApp with asset-specific options, enabling better UX through using the same visual and text identifiers that the wallet uses, making it easier for the user to understand the dApp's UI.
|
||||||
|
|
||||||
|
The `address`, `type` response fields provide enough information about the asset, enabling dApps to provide additional asset-specific functionality.
|
||||||
|
|
||||||
|
The `balance` response field is an optimization, allowing dApps to show the user's balance without querying the blockchain. Usually, this information is already public.
|
||||||
|
|
||||||
|
|
||||||
|
## Backwards Compatibility
|
||||||
|
|
||||||
|
Not relevant, as this is a new method.
|
||||||
|
|
||||||
|
|
||||||
|
## Test Cases
|
||||||
|
|
||||||
|
To be done.
|
||||||
|
|
||||||
|
|
||||||
|
## Implementation
|
||||||
|
|
||||||
|
To be done.
|
||||||
|
|
||||||
|
|
||||||
|
## Copyright
|
||||||
|
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
|
||||||
Loading…
Reference in New Issue