EIP-1193 이더리움 프로바이더 자바스크립트 API (Ethereum Provider JavaScript API)

최종 확정 · 기타 · 원문 상태 Final · 2018-06-30 작성

웹 앱이 지갑을 거쳐 이더리움과 대화할 때 쓰는 자바스크립트 객체인 프로바이더의 API를 표준화합니다. 메서드 하나(request)와 다섯 가지 이벤트만으로 모든 지갑이 같은 방식으로 동작하게 합니다.

왜 필요한가

웹에서 돌아가는 이더리움 앱(디앱)은 지갑이 웹페이지에 넣어 주는 자바스크립트 객체, 즉 프로바이더(Provider)를 거쳐 블록체인과 대화합니다. 그런데 이 표준이 나오기 전에는 지갑마다 프로바이더의 인터페이스와 동작이 제각각이었습니다. 어떤 지갑은 sendAsync를, 어떤 지갑은 send를 쓰고 이벤트 이름도 서로 달랐습니다. 앱 개발자는 지갑별로 다른 코드를 따로 짜야 했고 특정 지갑에서만 돌아가는 앱이 생겼습니다. EIP-1193은 모든 지갑이 똑같이 구현해야 하는 최소한의 공통 API를 정해 이 혼란을 정리합니다. 요청을 보내는 메서드 하나(request)와 다섯 가지 이벤트만 정의하고 전송 방식이나 RPC 프로토콜의 종류에는 관여하지 않아 어떤 환경에서도 쓸 수 있습니다. 새 RPC 메서드와 message 이벤트 타입을 더하는 식으로 기능을 쉽게 넓힐 수 있습니다.

무엇이 바뀌나

지금

EIP-1193 이후

누구에게 영향이 있나

심층 설명

request 메서드

프로바이더는 request(args) 메서드 하나로 모든 RPC 요청을 받습니다. 인자는 RequestArguments 인터페이스를 따르며 method는 호출할 RPC 메서드를 식별하는 문자열이고 params는 선택 항목으로 읽기 전용 배열 또는 객체입니다. 반환값은 Promise입니다. 성공하면 해당 RPC 메서드 명세가 정한 결과 값으로 해결되어야 하며(MUST), 메서드의 반환 타입이 그렇게 정의되지 않은 한 RPC 프로토콜 전용 응답 객체로 해결해서는 안 됩니다. 거부할 때는 반드시 ProviderRpcError로 거부해야 합니다. RPC 요청에 에러가 돌아오거나 프로바이더가 어떤 이유로든 요청 처리에 실패하면 반드시 거부하고(MUST), 프로바이더가 모든 체인에서 끊긴 상태면 코드 4900으로, 요청이 특정 체인을 향하는데 그 체인에만 연결이 없으면 코드 4901로 거부해야 합니다(SHOULD). 인가 실패에는 4100 에러로 거부할 것을 저자들이 권장합니다.

에러 표준과 프로바이더 에러 코드

모든 에러는 Error를 확장한 ProviderRpcError 인터페이스를 따릅니다. message는 사람이 읽을 수 있는 문자열이어야 하고(MUST), code는 정수여야 하며(MUST), data에는 그 밖의 유용한 정보를 담는 것이 권장됩니다(SHOULD). 코드와 메시지는 우선순위에 따라 첫째 프로바이더 에러 표, 둘째 에러를 낸 RPC 메서드 명세가 정한 에러, 셋째 CloseEvent 상태 코드를 따르는 것이 권장됩니다. 프로바이더 에러 표는 다섯 가지입니다. 4001 User Rejected Request(사용자가 요청을 거절), 4100 Unauthorized(요청한 메서드나 계정이 사용자에게 인가되지 않음), 4200 Unsupported Method(프로바이더가 지원하지 않는 메서드), 4900 Disconnected(모든 체인에서 끊김), 4901 Chain Disconnected(요청한 체인에만 연결이 없음)입니다. 4901은 다른 체인에는 연결되어 있다는 뜻을 함께 담습니다. 확정된 EIP에 정의된 RPC 메서드를 지원하지 않으면 4200 에러나 해당 메서드 명세의 에러로 거부하는 것이 권장됩니다.

연결 상태의 정의와 connect·disconnect 이벤트

프로바이더가 적어도 하나의 체인에 대해 RPC 요청을 처리할 수 있으면 '연결됨(connected)', 어느 체인에 대해서도 처리할 수 없으면 '끊김(disconnected)'으로 정의합니다. 요청을 처리한다는 것은 원격 지점에 요청을 성공적으로 보내고 응답을 받는다는 뜻이므로, 네트워크 문제로 클라이언트와 통신할 수 없으면 끊긴 상태입니다. 초기화 후 처음 체인에 연결되거나 disconnect 이벤트가 난 뒤 다시 연결되면 connect 이벤트를 반드시 발생시켜야 하며(MUST), 이때 ProviderConnectInfo 객체의 chainId에 연결된 체인의 정수 ID를 eth_chainId 방식의 16진수 문자열로 담아야 합니다. 모든 체인에서 끊기면 disconnect 이벤트를 ProviderRpcError 값과 함께 반드시 발생시켜야 하고, 이 에러의 code는 CloseEvent 상태 코드를 따라야 합니다.

상태 변화 이벤트: chainChanged와 accountsChanged

프로바이더는 on과 removeListener 두 이벤트 처리 메서드를 Node.js EventEmitter API대로 반드시 구현해야 합니다(MUST). 구현자는 EventEmitter 클래스를 확장해 번들하는 방법을 고려하라고 안내합니다. 연결된 체인이 바뀌면 chainChanged 이벤트를 새 체인의 정수 ID를 담은 16진수 문자열 chainId와 함께 반드시 발생시켜야 합니다. 프로바이더가 쓸 수 있는 계정이 바뀌면 accountsChanged 이벤트를 eth_accounts 방식의 계정 주소 배열과 함께 반드시 발생시켜야 합니다. '쓸 수 있는 계정'의 변화는 eth_accounts의 반환값이 바뀌는 것으로 정의합니다. 모든 이더리움 작업은 특정 체인을 향하므로 eth_chainId의 반환값이 정확하고 그 값이 바뀔 때마다 chainChanged가 발생하는 것이 보안상으로도 중요하다고 명시합니다.

message 이벤트와 구독 알림

message 이벤트는 다른 이벤트가 다루지 않는 임의의 알림을 위한 통로입니다. 발생할 때는 type 문자열과 data를 가진 ProviderMessage 객체를 반드시 전달해야 합니다(MUST). 프로바이더가 eth_subscribe 같은 이더리움 RPC 구독을 지원한다면, 구독 알림을 받을 때마다 message 이벤트를 반드시 발생시켜야 합니다. 이때 객체는 EthSubscription 형태로, type은 문자열 'eth_subscription'이고 data는 subscription 문자열과 result를 담습니다. 원문 예시에서는 eth_subscribe로 newHeads를 구독한 뒤 message 이벤트에서 type과 구독 ID를 확인해 새 블록을 받아 보는 흐름을 보여 줍니다.

설계 근거: 메서드 하나와 이벤트 다섯 개

프로바이더의 목적은 소비자에게 이더리움 접근을 제공하는 것이고, 웹 앱은 두 가지를 할 수 있으면 됩니다. 이더리움 RPC 요청을 보내는 것과, 체인·클라이언트·지갑의 상태 변화에 반응하는 것입니다. 명세는 메서드 하나와 이벤트 다섯 개로 구성되는데, 사실 request 메서드와 message 이벤트만으로도 완전한 프로바이더를 구현할 수 있습니다. 각각 임의의 RPC 요청과 임의의 메시지 전달을 맡도록 설계되었기 때문입니다. 나머지 네 이벤트는 두 범주로 나뉩니다. RPC 요청 능력의 변화를 알리는 connect와 disconnect, 그리고 어떤 앱이든 다뤄야 하는 흔한 클라이언트·지갑 상태 변화인 chainChanged와 accountsChanged입니다. 이 이벤트들은 작성 시점에 관련 패턴이 실제 서비스에서 널리 쓰이고 있어 포함되었습니다.

하위 호환성과 레거시 API

많은 프로바이더가 확정 전의 초안 버전을 먼저 채택했습니다. 현재 API는 레거시 버전의 엄격한 상위 집합으로 설계되어 그런 의미에서 완전히 하위 호환됩니다. 다만 이 명세만 구현한 프로바이더는 레거시 API를 대상으로 만든 기존 웹 앱과는 호환되지 않습니다. 레거시 API에서 sendAsync와 send 메서드는 request로, close 이벤트는 disconnect로, networkChanged 이벤트는 chainChanged로, notification 이벤트는 message로 대체되었습니다. 레거시 API는 완전히 표준화된 적이 없어 실제 구현 사이에 편차가 크며 저자들은 레거시 앱 지원 목적이 아니면 구현하지 말 것을 권장합니다.

보안 고려 사항: 프로바이더는 적대적 환경에 놓인다

프로바이더는 이더리움 클라이언트와 앱 사이에서 RPC 메시지를 전달하고 이벤트를 발생시킬 뿐, 개인 키나 계정 관리를 책임지지 않습니다. 계정 보안과 사용자 프라이버시는 프로바이더와 클라이언트 사이의 중간 계층, 즉 지갑에서 구현해야 합니다. 프로바이더는 웹사이트 같은 제3자가 통제하는 신뢰할 수 없는 환경에 노출되는 자바스크립트 객체이므로, 소비자가 모든 속성을 읽고 덮어쓸 수 있습니다. 따라서 공격자가 통제하는 객체처럼 다루는 것이 최선입니다. 구현자는 프로바이더에 사용자 비공개 데이터를 담지 않고 프로바이더와 지갑 프로그램을 서로 격리하며 지갑이나 클라이언트에서 요청을 속도 제한하고 모든 데이터를 검증해야 합니다. 또 사용자 프라이버시를 위해 계정을 기본으로 노출하지 말고 eth_requestAccounts(EIP-1102)나 wallet_requestPermissions(EIP-2255)처럼 명시적으로 계정 접근을 요청하는 RPC 메서드를 지원할 것을 권장합니다.

EIP 원문 · ← EIPs