ERC-7846 지갑 연결·인증 API (Wallet Connection API)
Draft · 계정·지갑 · 2024-12-15 작성
앱이 지갑에 계정 연결과 서명 기반 로그인(Sign In With Ethereum)을 한 번의 JSON-RPC 호출로 동시에 요청할 수 있게 하는 지갑 연결 표준입니다.
왜 필요한가
지금까지 앱이 지갑에 연결하려면 eth_requestAccounts로 계정을 받고 로그인이 필요하면 personal_sign으로 서명을 또 요청해야 했습니다. 이 두 메서드는 확장성이 없어서 연결 과정에 인증이나 다른 부가 기능을 끼워 넣을 표준화된 방법이 없고 사용자는 연결과 서명을 위해 최소 두 번 지갑 창을 확인해야 합니다. 앱이 점점 더 복잡한 연결 흐름(인증, 권한, 메타데이터 공유 등)을 요구하면서 이런 분절된 방식 때문에 사용자 경험이 떨어지고 앱마다 구현도 제각각입니다. 연결을 끊는 절차도 표준이 없어 지갑과 앱이 서로 다른 방식으로 처리합니다.
구현해야 하는 것
type Request = { method: 'wallet_connect', params: [{ // JSON-RPC method version. version: string; // Optional capabilities to request (e.g. Sign In With Ethereum). capabilities?: Record<string, unknown>; }] }: 앱이 wallet_connect를 호출할 때 보내는 요청 형식으로, 버전과 요청할 capabilities를 담습니다.type Response = { accounts: { // Address of the connected account. address: `0x${string}`; // Capabilities granted that is associated with this account. capabilities: Record<string, unknown>; }[] }: wallet_connect 응답으로, 연결된 계정 주소들과 각 계정에 부여된 capabilities 결과를 배열로 돌려줍니다.type Request = { method: 'wallet_disconnect' }: 지갑에 연결된 계정과 부여된 capabilities를 해제하도록 요청하는 wallet_disconnect 호출 형식입니다.type Parameters = { signInWithEthereum: { nonce: string; chainId: string; // EIP-155 hex-encoded version?: string; scheme?: string; domain?: string; uri?: string; statement?: string; issuedAt?: string; expirationTime?: string; notBefore?: string; requestId?: string; resources?: string[]; } }: wallet_connect의 capabilities에 담아 ERC-4361 형식의 로그인 서명을 요청할 때 쓰는 파라미터입니다.type Response = { signInWithEthereum: { // Formatted SIWE message. message: string; // Signature over the EIP-191 personal_sign hash of the message. signature: `0x${string}`; } }: signInWithEthereum capability의 응답으로, 완성된 SIWE 메시지와 그 메시지에 대한 서명을 돌려줍니다.
심층 설명
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-4361 보안 원칙 적용: signInWithEthereum capability는 ERC-4361의 보안 고려사항을 그대로 따릅니다.
- capabilities 추가에 따른 예측 불가능한 상호작용: 더 많은 capabilities가 추가될수록 capability들 사이에서 예측하지 못한 상호작용이 생기지 않도록 주의해야 합니다.
- 주소·capability 데이터의 안전한 처리: 지갑 주소와 공유되는 capabilities 데이터는 데이터 유출이나 중간자 공격(man-in-the-middle)을 막기 위해 안전하게 처리해야 합니다.