ERC-681 트랜잭션 요청 URL 형식 (URL Format for Transaction Requests)

Final · 계정·지갑 · 2017-08-01 작성

이더나 ERC-20 토큰 결제 요청을 ethereum: 으로 시작하는 URL 한 줄로 적는 표준입니다. QR 코드나 링크에 담아 전달하면 사용자의 지갑 앱이 열리고 받는 주소와 금액이 미리 채워집니다.

왜 필요한가

누군가에게 이더를 보내 달라고 할 때 받는 주소 40자리와 금액을 따로 알려 주면 사용자가 지갑에 직접 옮겨 적어야 합니다. 주소를 한 글자라도 잘못 넣으면 돈이 엉뚱한 곳으로 갑니다. 금액 단위를 틀리면 자릿수가 어긋납니다. 토큰 결제는 더 복잡합니다. 토큰 컨트랙트 주소, 받는 주소, 수량을 모두 맞춰 넣어야 합니다. 원문은 비트코인이 결제 수단으로 널리 퍼진 데에는 결제 요청을 표준 URL 로 적는 편리함이 큰 몫을 했다고 설명합니다. 이더리움에는 그런 공통 형식이 없어 앱마다 다른 방식으로 요청을 주고받아야 했습니다. 이전에 있던 ERC-67 은 임의의 트랜잭션을 낮은 수준에서 표현하는 형식이었는데 이미 쓰이지 않게 되었습니다. 이 표준은 그 자리를 이어받아 결제 요청이라는 가장 흔한 경우에 집중하면서 ABI 로 정의된 다른 함수 호출도 요청할 수 있게 합니다.

심층 설명

URL 문법

URL 은 ethereum: 으로 시작하고 그 뒤에 선택 접두사 pay- 가 올 수 있습니다. 이어서 대상 주소(target_address), 선택적으로 @ 와 체인 ID(chain_id), / 와 함수 이름(function_name), ? 와 매개변수(parameters)가 붙습니다. 원문 ABNF 는 request = schema_prefix target_address [ "@" chain_id ] [ "/" function_name ] [ "?" parameters ] 입니다. 주소는 0x 뒤에 16진수 40자리이거나 ERC-137 의 ENS 이름입니다. 체인 ID 는 십진수입니다. 함수 이름과 문자열 값(STRING)은 URL 인코딩한 유니코드 문자열이며 구분 문자와 % 기호는 반드시 % 접두사로 16진수 인코딩해야 합니다. 향후 이 제안과 부분적으로라도 호환되지 않는 개정판은 pay- 가 아닌 다른 접두사를 대시(-) 문자로 구분해 써야 합니다.

매개변수 키와 숫자 표기

매개변수는 key=value 쌍을 & 로 잇습니다. 키는 value, gas, gasLimit, gasPrice 중 하나이거나 ABI 타입 이름(TYPE)입니다. 키가 value, gasLimit, gasPrice, gas 면 값은 반드시 number 여야 하고 그 외에는 키로 쓴 ABI 타입에 맞는 값이어야 합니다. number 는 부호, 숫자, 소수점, 그리고 e 또는 E 뒤의 지수로 이루어집니다. 지수는 10 의 거듭제곱 배수를 뜻하므로 2.014e18 은 2.014 곱하기 10 의 18 제곱입니다. 정수만 허용되므로 지수는 소수점 아래 자릿수보다 크거나 같아야 합니다. 원문은 금액을 적을 때 과학적 표기를 강하게 권장하며 읽기 쉽도록 지수는 이더면 18, ERC-20 토큰이면 토큰 컨트랙트의 decimals() 반환값으로 맞추라고 합니다.

대상 주소, 체인 ID, ENS 우선순위

target_address 는 필수이며 네이티브 토큰 결제의 수취인이거나 사용자가 상호작용할 컨트랙트 주소입니다. chain_id 는 선택이고 십진수 체인 ID 를 담아 테스트넷이나 사설 네트워크의 트랜잭션도 요청할 수 있습니다. 없으면 클라이언트의 현재 네트워크 설정이 그대로 적용됩니다. ENS 이름을 쓰면 해석은 결제자 몫이며 URL 을 받은 때부터 트랜잭션을 보내기 전까지 언제든 할 수 있습니다. 16진수 주소는 항상 ENS 이름보다 우선합니다. 0x 뒤에 16진수 40자리로 된 ENS 이름이 실제로 있더라도 절대 해석하지 않고 16진수 주소로 바로 써야 합니다. 0x 접두사는 관례를 따른 것이면서 영숫자 40자로 된 ENS 이름과 16진수 주소를 명확히 구분하는 역할도 합니다.

이더 결제 요청

function_name 이 없으면 블록체인의 네이티브 토큰, 즉 이더 결제를 요청하는 URL 입니다. 금액은 value 매개변수에 최소 단위(wei)로 적습니다. 원문 예시는 0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359 주소로 2.014 ETH 를 요청하는 ethereum:0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359?value=2.014e18 입니다. 지수를 18 로 맞추면 소수점 앞 숫자가 ETH 단위 금액과 같아 사람이 읽기 쉽습니다. 수취인 주소만 적는 이더 결제 요청은 이전 표준인 ERC-67 과도 호환됩니다.

ERC-20 토큰 결제 요청

토큰 결제는 토큰 컨트랙트의 transfer 함수 호출을 요청하는 형태입니다. target_address 에 토큰 컨트랙트 주소를 적고 function_name 을 transfer 로 둔 뒤, address 타입 매개변수에 수취인 주소를, uint256 타입 매개변수에 최소 단위 수량을 넣습니다. 원문 예시는 0x8e23ee67d1332ad560396262c48ffbb01f93d052 주소로 Unicorn 토큰 1 개를 요청하는 ethereum:0x89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7/transfer?address=0x8e23ee67d1332ad560396262c48ffbb01f93d052&uint256=1 입니다. 결제 요청이 중심이지만 같은 방식으로 ABI 로 정의된 다른 함수 호출도 요청할 수 있습니다.

금액과 가스는 제안값

URL 에 적힌 금액은 제안일 뿐이며 다른 인자들도 마찬가지입니다. 사용자는 자유롭게 바꿀 수 있습니다. 금액이 없으면 지갑은 사용자에게 보낼 금액을 입력하라고 요청해야 합니다. gasLimit 과 gasPrice 도 각각 가스 한도와 가스 가격의 제안값으로, 사용자가 편집할 수 있습니다. gasLimit 은 gas 로 줄여 쓸 수 있고 둘은 같은 뜻으로 처리합니다. 원문은 널리 쓰이는 용도가 실제로 나타나면 매개변수를 더 추가할 수 있다고 적었습니다.

비트코인 URL 을 닮게 만든 이유

형식은 사용자와 개발자가 이미 익숙한 bitcoin: URL 과 최대한 비슷하게 골랐습니다. 이더리움 생태계에서 자주 쓰는 단위 표기를 생략한 것도 그 때문입니다. 자릿수 차이는 지수로 처리해 bitcoin: 처럼 금액을 명목 단위로 적을 수 있게 했습니다. 전달 경로도 넓습니다. 원문에 따르면 안드로이드에서는 브로드캐스트 인텐트에 담긴 URL 이 앱을 실행하는 주된 방법이고 데스크톱 브라우저는 특정 스킴의 프로토콜 핸들러를 정의하는 표준 방법이 있습니다. 다른 데스크톱 앱은 URL 을 만나면 보통 브라우저를 띄웁니다. 그래서 결제 요청 URL 은 QR 코드, 웹 링크, 이메일, 채팅 메시지 등 다양한 채널로 전달할 수 있습니다.

쓸 때 주의할 점

ERC 원문 · ← ERCs