ERC-7846 지갑 연결·인증 API (Wallet Connection API)

Draft · 계정·지갑 · 2024-12-15 작성

앱이 지갑에 계정 연결과 서명 기반 로그인(Sign In With Ethereum)을 한 번의 JSON-RPC 호출로 동시에 요청할 수 있게 하는 지갑 연결 표준입니다.

왜 필요한가

지금까지 앱이 지갑에 연결하려면 eth_requestAccounts로 계정을 받고 로그인이 필요하면 personal_sign으로 서명을 또 요청해야 했습니다. 이 두 메서드는 확장성이 없어서 연결 과정에 인증이나 다른 부가 기능을 끼워 넣을 표준화된 방법이 없고 사용자는 연결과 서명을 위해 최소 두 번 지갑 창을 확인해야 합니다. 앱이 점점 더 복잡한 연결 흐름(인증, 권한, 메타데이터 공유 등)을 요구하면서 이런 분절된 방식 때문에 사용자 경험이 떨어지고 앱마다 구현도 제각각입니다. 연결을 끊는 절차도 표준이 없어 지갑과 앱이 서로 다른 방식으로 처리합니다.

구현해야 하는 것

심층 설명

wallet_connect의 기본 동작

wallet_connect는 계정과 선택적 capabilities를 함께 요청하는 메서드입니다. 요청에는 JSON-RPC 메서드 버전을 나타내는 version 문자열과, ERC-5792 방식의 모듈형 capabilities 객체를 선택적으로 포함할 수 있습니다. 응답은 연결된 계정들의 address와 해당 계정에 부여된 capabilities 결과를 담은 accounts 배열입니다. 여러 계정을 반환할 수 있지만 실무에서는 대부분 앱이 배열의 첫 번째 계정만 사용할 것으로 예상됩니다.

wallet_disconnect의 동작

wallet_disconnect는 파라미터 없이 호출하는 메서드로, 연결된 계정 정보와 wallet_connect로 부여되었던 capabilities에 대한 접근 권한을 지갑이 회수(revoke)하도록 합니다. 명세는 이를 SHOULD로 규정합니다.

signInWithEthereum capability

signInWithEthereum은 ERC-4361(SIWE)을 이용한 오프체인 인증을 wallet_connect에 추가하는 capability입니다. 파라미터는 ERC-4361과 거의 동일하지만 다중 단어 필드가 kebab-case 대신 camelCase로 바뀌고 resources는 배열 필드입니다. nonce와 chainId(EIP-155 16진수)는 필수이며, version·scheme·domain·uri·statement·issuedAt·expirationTime·notBefore·requestId·resources는 선택입니다.

선택 파라미터의 기본값과 주소 일치 요구

version을 지정하지 않으면 ERC-4361이 허용하는 버전 중 하나가 기본값으로 쓰이고 domain과 uri를 지정하지 않으면 요청한 앱의 도메인과 uri가 기본값이 되며 issuedAt을 지정하지 않으면 현재 시각이 쓰입니다. 또한 wallet_connect가 반환하는 계정 주소는 SIWE 메시지에 들어간 주소와 반드시 일치해야 합니다(MUST).

메시지·서명 검증 요구사항

지갑은 요청된 파라미터와 정확히 일치하는 ERC-4361 형식의 메시지를 반환해야 하며(MUST), 그 메시지의 EIP-191 personal_sign 해시에 대한 서명도 함께 반환해야 합니다. 앱 쪽에서도 받은 메시지와 서명이 서로 일치하는지 검증하는 것이 권장됩니다(SHOULD).

다중 계정과 capabilities 반환의 의도

더 복잡한 상호작용을 원하는 앱에 일반성을 주고 기존 eth_requestAccounts와의 하위 호환성을 높이려고 여러 계정을 반환하도록 했습니다. 인증, 사용자 메타데이터 공유, 앱에 부여되는 권한 같은 다양한 활용을 열어주려고 capabilities 결과를 연결과 함께 반환하도록 했습니다.

하위 호환성과 확장성

이 표준은 기존 JSON-RPC 메서드 위에 구축되며 ERC-5792와 함께 향후 확장을 보완합니다. 지갑은 eth_requestAccounts 같은 기존(legacy) 메서드 지원을 계속 유지할 수 있습니다.

현재 상태

ERC-7846은 2024-12-15에 생성된 Draft 상태의 제안으로, 아직 확정되지 않았으며 세부 사항이 바뀌거나 논의가 중단될 수 있습니다.

쓸 때 주의할 점

ERC 원문 · ← ERCs