ERC-7811 지갑 자산 목록 조회 (Wallet Asset Discovery)

Draft · 계정·지갑 · 2024-11-07 작성

지갑이 사용자가 가진 자산 전체 목록을 앱에 알려 주는 JSON-RPC 메서드 wallet_getAssets를 정의합니다. 온체인 데이터만으로 찾기 어려운 자산도 지갑이 직접 제공할 수 있습니다.

왜 필요한가

지금 탈중앙 앱(Dapp)은 주로 블록체인에 기록된 온체인 데이터를 읽어 사용자의 잔액을 파악합니다. 이 방식에는 한계가 있습니다. 사용자가 여러 계정과 여러 체인에 나눠 가진 자산을 앱이 한 번에 알 수 없고 온체인 조회만으로는 드러나지 않는 자산도 놓칩니다. 그 결과 지갑 쪽에서는 처리할 수 있는 작업인데도 앱이 잔액이 부족하다고 판단해 사용자의 행동을 막는 일이 생깁니다. 정작 지갑은 온체인에 보이지 않는 것까지 포함해 사용자의 자산 정보를 이미 알고 있지만 그 정보를 앱에 전달할 표준 통로가 없습니다. 이 제안은 지갑이 아는 자산 목록을 앱에 넘겨 주는 공통 방법을 만들어 이 간극을 메웁니다.

심층 설명

요청 구조와 필수 필드

요청은 account, assetFilter, assetTypeFilter, chainFilter 네 필드로 이루어집니다. account는 어느 계정의 자산을 요청하는지 나타내는 유일한 필수(REQUIRED) 필드입니다. assetFilter는 체인 ID별로 address와 type을 가진 자산 식별자 목록을 받는 선택 필드이고 assetTypeFilter는 자산 타입 배열, chainFilter는 체인 ID 배열을 받는 선택 필드입니다. 체인 ID는 모두 유효한 EIP-155 chainId여야 합니다.

assetFilter가 다른 필터보다 우선합니다

assetFilter가 주어지면 지갑은 그 안에 명시된 자산만 반환해야 하며(MUST), 이때 assetTypeFilter와 chainFilter는 완전히 무시됩니다. 두 필터가 거를 내용이 assetFilter 안에 이미 암묵적으로 정의되어 있기 때문입니다. assetFilter를 생략하면 지갑은 그 계정의 모든 가용 자산을 반환해야 하고(SHOULD), 지갑이 추정한 가치 기준 내림차순으로 정렬해 주는 것이 권장(RECOMMENDED)됩니다.

필터는 가능한 한 좁게 설정합니다

이 메서드를 쓰는 쪽은 assetFilter, assetTypeFilter, chainFilter를 합리적인 범위에서 최대한 세밀하게 설정해야 합니다(SHOULD). 예를 들어 한 체인의 토큰 하나에만 관심 있는 앱이라면 그에 맞는 필터를 제공해야 합니다. 이렇게 하면 지갑과 하부 인프라가 과도한 비용을 치르지 않고 클라이언트 앱의 성능도 크게 좋아집니다.

응답 구조

응답은 EIP-155 chainId를 키로 하는(MUST) 객체이고 값은 자산 배열입니다. 각 자산은 address, balance, type, metadata 필드를 가집니다. address는 자산의 주소이며 네이티브 자산이면 native 문자열을 씁니다. balance는 16진수(Hex) 잔액입니다. type은 자산 종류를 나타내는 문자열로 erc20, erc721, native 등이 있지만 이에 한정되지 않습니다. metadata는 자산에 대한 추가 정보를 담는 선택 객체로, 자산 타입과 지갑 구현에 따라 필드가 달라질 수 있습니다.

잘 알려진 자산 타입의 최소 메타데이터

이 ERC를 따르는 구현이 잘 알려진 타입을 반환할 때는 정해진 metadata 필드를 최소한으로 포함해야 하며(MUST), 더 많은 필드를 넣을 수는 있습니다(MAY). erc20은 name, symbol, decimals를, erc721은 name, symbol, tokenId와 선택적 tokenURI를 담습니다. native는 address가 native이고 metadata가 없습니다. type은 일반 문자열이라 앱이 기대한 타입과 지갑이 돌려준 타입이 어긋날 수 있으므로, 두 자산이 같은 type을 공유하면 안 되고 새 자산 타입은 이후 ERC로 정의되어야 합니다.

지원 여부를 알리는 방법

CAIP-25 권한 방식을 쓰는 지갑은 eip155 네임스페이스의 sessionScopes 안 methods 배열에 wallet_getAssets를 포함해야 합니다(SHOULD). ERC-5792를 지원하는 지갑은 wallet_getCapabilities 요청에 assetDiscovery 키로 응답해야 하며(SHOULD), 값은 supported 키가 true인 객체입니다. 지갑은 이를 모든 chainId에 대해 포함하는 것이 좋습니다.

아직 Draft 단계인 제안입니다

이 제안은 상태가 Draft로, 내용이 앞으로 바뀔 수 있습니다. 원문의 Rationale과 Security Considerations 절도 아직 작성되지 않은 상태입니다. 구현 전에 최신 원문을 확인하는 것이 좋습니다.

ERC 원문 · ← ERCs