ERC-1328 WalletConnect URI 형식 (WalletConnect URI Format)

Final · 계정·지갑 · 2018-08-15 작성

앱과 지갑을 연결하는 데 필요한 정보를 wc: 로 시작하는 URI 한 줄에 담는 방법을 정합니다. 이 URI는 QR 코드나 링크로 보여 줄 수 있습니다.

왜 필요한가

웹사이트나 앱에서 지갑을 쓰려면 먼저 둘이 서로를 찾아 연결을 맺어야 합니다. 연결에 필요한 정보, 예를 들어 어느 대화 주제(topic)인지, 메시지를 어떤 키로 암호화할지, 어느 서버를 거쳐 중계할지를 담는 형식이 정해져 있지 않으면 지갑마다 다른 방식으로 읽어야 하고 QR 코드를 찍어도 그 뜻을 풀어내기 어렵습니다. 원문에 따르면 WalletConnect 프로토콜의 알파 버전은 QR 코드 안에 JSON을 넣었는데, 그 의도를 읽어 내는 처리가 매우 비효율적이었습니다. 이 표준은 연결 정보를 wc: 로 시작하는 URI 한 줄로 적도록 정해, 지갑이 QR 코드 해석기를 만들기 쉽게 하고 안드로이드의 인텐트(Intent) 체계로 링크를 지갑 앱에 넘길 수 있게 합니다.

심층 설명

URI의 기본 구조

요청 URI는 wc 뒤에 콜론을 붙이고 topic을 적는 것으로 시작합니다. 문법은 request = "wc" ":" topic [ "@" version ][ "?" parameters ] 입니다. topic은 문자열(STRING)이고 그 뒤에 @와 버전 번호를 붙일 수 있습니다. 버전은 1*DIGIT, 즉 숫자 한 자리 이상입니다. 마지막으로 ?를 붙이고 매개변수를 적습니다. 매개변수는 key=value 꼴 하나 이상을 &로 이은 것이며 key와 value는 모두 문자열입니다. 대괄호로 묶인 버전 부분과 매개변수 부분은 문법상 생략할 수 있게 적혀 있습니다.

버전 1.0 매개변수 (version=1)

WalletConnect 1.0 프로토콜을 쓰는 URI는 @1 로 표시하고 매개변수 두 개를 담습니다. key는 암호화에 쓰는 대칭 키입니다. bridge는 메시지를 중계하는 브리지 서버의 URL입니다. 원문 예시에서는 bridge 값으로 https://bridge.walletconnect.org 를 URL 인코딩해 넣고 key 값으로 16진수 문자열을 넣었습니다. 어떤 매개변수가 필요한지는 프로토콜 버전에 따라 달라지므로 지갑은 먼저 버전을 읽고 그에 맞는 매개변수를 찾아야 합니다.

버전 2.0 매개변수 (version=2)

WalletConnect 2.0 프로토콜을 쓰는 URI는 @2 로 표시하고 매개변수 다섯 가지를 정의합니다. symKey는 릴레이를 거쳐 오가는 메시지를 암호화하는 대칭 키입니다. methods는 페어링 topic에서 지원하는 JSON-RPC 메서드 목록입니다. relay-protocol은 메시지를 중계하는 전송 프로토콜입니다. relay-data는 중계에 쓰는 전송 데이터이며 생략할 수 있습니다. expiryTimestamp는 페어링이 만료되는 시각을 유닉스 시각(초 단위)으로 적은 값이며 역시 생략할 수 있습니다. 1.0 매개변수(key, bridge)와는 이름과 구성이 다릅니다.

원문 예시 읽기

1.0 예시는 wc:8a5e5bdc-a0e4-4702-ba63-8f1a5655744f@1 로 시작합니다. topic 자리에 UUID 꼴 문자열이 오고 @1 뒤에 bridge와 key 두 매개변수가 이어집니다. 2.0 예시는 wc:7f6e504bfad60b485450578e05678ed3e8e8c4751d3c6160be17160d63ec90f9@2 로 시작하며 topic 자리에 긴 16진수 문자열이 옵니다. 매개변수로는 relay-protocol=irn, symKey(16진수 문자열), methods=[wc_sessionPropose],[wc_authRequest,wc_authBatchRequest], expiryTimestamp=1705934757 이 들어 있습니다. methods 값은 메서드 이름을 대괄호로 묶은 묶음을 쉼표로 이어 적은 형태입니다.

JSON 대신 URI를 쓰는 이유

WalletConnect 프로토콜의 알파 버전은 QR 코드 안에 JSON을 넣었습니다. 원문은 이 방식이 QR 코드의 의도를 읽어 내는 데 매우 비효율적이었다고 설명합니다. 그래서 이 제안은 JSON을 버리고 URI 형식으로 옮겼습니다. 형식이 단순해지면 지갑이 구현할 QR 코드 해석 API를 더 잘 만들 수 있습니다. 또 QR 코드 안에 JSON 대신 URI를 넣으면 안드로이드의 인텐트(Intent) 체계를 활용할 수 있습니다.

버전 표기와 호환성

WalletConnect 프로토콜이 계속 발전할 수 있도록 URI 문법에 버전 표기(@version)를 넣었습니다. 새 버전이 나와도 URI의 버전 번호를 보면 어느 규칙으로 읽어야 하는지 알 수 있으므로 옛 버전과의 호환을 유지할 수 있습니다. 실제로 이 문서는 버전 1과 버전 2에서 서로 다른 매개변수 집합을 정의합니다. 지갑은 버전 번호에 맞춰 매개변수를 해석합니다. 이 표준의 상태는 Final 입니다.

쓸 때 주의할 점

ERC 원문 · ← ERCs