EIP-747 wallet_watchAsset RPC 메서드 (wallet_watchAsset RPC Method)
최종 확정 · 기타 · 원문 상태 Final · 2018-08-13 작성
웹사이트가 지갑에 특정 토큰을 추적 목록에 추가해 달라고 요청할 수 있는 RPC 메서드 wallet_watchAsset을 표준으로 정합니다.
왜 필요한가
지갑의 주요 기능 중 하나는 사용자가 가진 자산을 보여 주는 것입니다. 이 표준이 없으면 지갑은 두 가지 방법 중 하나를 골라야 합니다. 첫째, 승인된 자산 목록을 지갑이 미리 넣어 두는 방법입니다. 이 경우 지갑 팀이 목록의 보안을 책임져야 하고 알려진 자산을 대량으로 조회하느라 통신량 부담도 집니다. 원문은 자산 목록을 유지하는 일 자체가 정치적 행위가 되어 괴롭힘과 상장 압박을 부른다고 지적합니다. 둘째, 사용자가 토큰 주소를 직접 입력해 추가하는 방법인데, 사용 경험이 매우 나쁩니다. 한편 자산을 자동으로 전부 표시하면 관심 없는 토큰이 스팸처럼 쌓이고 피싱에 악용될 수 있습니다. 사용자가 토큰을 알게 되는 순간은 대개 웹사이트에서이고 그 순간에는 사이트와 사용자 모두 해당 토큰을 추적하길 원합니다. 이 자연스러운 접점에 양쪽이 협력할 수 있는 API를 두자는 것이 이 제안의 취지입니다.
무엇이 바뀌나
지금
- 지갑이 자산 목록을 자체 관리하거나 중앙화된 API에 잔액을 조회해야 합니다
- 사용자가 토큰을 보려면 계약 주소를 직접 입력해 수동으로 추가해야 합니다
- 중앙화 API를 조회하면 계정과 IP 주소를 연결 지을 수 있습니다
EIP-747 이후
- 웹사이트가 wallet_watchAsset 호출로 지갑에 토큰 추가를 제안할 수 있습니다
- 지갑은 요청을 검증한 뒤 사용자에게 추가 여부를 묻는 창을 띄웁니다
- 유명 토큰과 이름이나 심볼이 비슷하면 지갑이 경고를 보여 피싱을 막습니다
누구에게 영향이 있나
- 사용자: 토큰 주소를 복사해 붙여 넣는 수동 추가 없이, 웹사이트에서 띄운 확인 창을 승인하는 것만으로 토큰을 추적할 수 있습니다.
- 댑 개발자: 자기 서비스의 토큰을 사용자 지갑에 표시해 달라고 표준 방식으로 요청할 수 있습니다.
- 지갑 개발자: 승인 자산 목록을 미리 관리하는 부담이 줄지만 체크섬 검증, 유사 토큰 경고, SSRF 방어 같은 검증 책임을 집니다.
심층 설명
메서드 정의와 즉시 반환 규칙
wallet_watchAsset은 지갑 범위(wallet-scoped)의 새 RPC 메서드로, 지정한 자산을 사용자 지갑의 목록에 올려 달라고 요청합니다. 요청이 유효하면 사용자에게 프롬프트를 띄우기 전에 즉시 true를 반환해야 하고(MUST), 유효하지 않으면 오류를 반환해야 합니다. 성공 응답은 지갑이 요청을 인식했고 문제가 없었다는 뜻일 뿐, 사용자에게 프롬프트가 표시됐는지나 자산이 실제로 추가됐는지를 보장하지 않습니다. "지갑에 올린다"의 구체적 의미는 지갑 구현에 달려 있습니다.
파라미터 구조
메서드는 WatchAssetParameters 객체 하나를 파라미터로 받습니다. 구조는 type: string(자산의 인터페이스, 예: 'ERC1046')과 options: any입니다. type 문자열은 자산 계약이 구현한 인터페이스의 통용 명칭이어야 하며(SHOULD), 자산 타입별 전역 식별자를 정의하는 일은 이 EIP의 범위 밖입니다. options의 구조는 자산 type에 따라 확장되거나 수정되어야 하고(SHOULD), 그 변경은 별도의 EIP로 명세되어야 합니다(MUST).
반환값과 오류 조건
반환은 사용자 상호작용을 기다리지 않고 즉시 이루어집니다. 유효한 요청이면 불리언 true를, 유효하지 않으면 오류를 반환합니다. 원문이 예시한 오류 상황은 이렇습니다(전부는 아님). 자산 타입을 인식하지 못하거나 지원하지 않는 경우, 허용 목록(allowlist)이나 차단 목록(denylist)에 걸린 경우(근본 원인 해결에 개발자 조치가 필요하므로 '유효하지 않은' 요청으로 봅니다), 이미지 다운로드가 실패한 경우, 그리고 SSRF 공격 방지를 위해 지갑이 표시에 필요한 메타데이터 일부를 불러오지 않은 경우입니다.
ERC1046 타입
options는 address: string(필수)과 chainId?: number(선택)로 구성됩니다. address는 0x 접두사가 붙은 체크섬 16진수 계약 주소여야 하며(MUST), 체크섬 검증에 실패하면 요청은 무효로 처리되어야 합니다(MUST). chainId가 비어 있으면 현재 체인 ID를 기본값으로 쓰는데, 지갑이 chainId를 인식하지 못하거나 "활성 체인" 개념이 없는 지갑에 chainId가 비어 있으면 호출은 실패해야 합니다(MUST). 지갑은 ERC-1046 tokenURI를 가져와 interop 필드로 토큰 타입을 확인해야 하고(MUST), 파싱에 실패하거나 타입을 모르면 오류를 반환해야 합니다(MUST). name, symbol, address, chainId를 유명 토큰 목록과 대조해 이름이나 심볼이 비슷한데 주소가 다르면 경고를 표시해야 하며(SHOULD), SSRF 공격을 피하기 위해 특정 포트와 스킴을 화이트리스트 또는 블랙리스트로 관리해야 합니다(SHOULD).
레거시 ERC20 타입
options 구조와 검증 규칙은 ERC1046 타입과 같습니다. address는 필수이고 체크섬 검증에 실패하면 무효이며 chainId 처리 규칙도 동일합니다. 유명 토큰 목록과 대조해 유사 토큰 경고를 표시하는 규칙(SHOULD)도 같습니다. 다만 원문은 가능하면 이미지와 커스텀 메타데이터를 지원하는 ERC1046 타입을 대신 쓸 것을 권장합니다(RECOMMENDED).
보안 고려사항
세 가지를 다룹니다. 첫째, 서버 측 요청 위조(SSRF)입니다. 지갑이 임의 URL에 요청을 보내면 예를 들어 로컬에 호스팅된 redis 데이터베이스의 데이터를 수정하도록 속을 수 있으므로, 특정 스킴과 포트만 허용하는 방식으로 URI를 정제하길 권합니다. 둘째, 검증입니다. 심볼이나 이름이 다른 토큰과 같거나 비슷하면 피싱 사기를 막기 위해 사용자에게 경고해야 합니다. 셋째, 핑거프린팅입니다. 지갑의 동작이나 등록된 자산을 근거로 사용자를 식별하는 일을 막기 위해, RPC 호출은 사용자가 승인하거나 거부하기를 기다리지 않고 프롬프트가 뜨거나 오류가 나는 즉시 반환해야 합니다.
상태와 배경
이 EIP는 Final 상태의 Standards Track(Interface) 표준으로, 2018년 8월 13일에 만들어졌고 EIP-20, EIP-1046, EIP-1193을 요구합니다. Rationale은 자산 표시가 모든 댑 사용자가 기대하는 기본 기능인데, 중앙화 API 조회는 탈중앙성을 해치고 계정과 IP를 연결 짓게 하며 네트워크에서 자산 목록을 갱신하는 일은 대역폭이 제한된 기기에서 특히 비싸다고 설명합니다. 또 자산을 자동으로 등록하면 토큰이 스팸 메일처럼 되는데, 에어드랍 토큰이 이미 그런 사례이고 네트워크 혼잡의 주요 원인이라고 지적합니다.