ERC-7730 구조화 데이터 클리어 서명 포맷 (Structured Data Clear Signing Format)
Draft · 서명·인증 · 2024-02-07 작성
트랜잭션이나 메시지에 서명하기 전에 지갑 화면에 그 내용을 사람이 이해할 수 있는 형태로 보여 주는 방법을 담은 JSON 포맷 표준입니다.
왜 필요한가
지갑 화면에서 서명할 내용을 직접 확인하는 것(클리어 서명, Clear Signing)은 블록체인 보안의 핵심 습관입니다. 그런데 서명할 데이터는 구조 설명서인 ABI나 EIP-712 타입 정보가 있어도 그대로 보여 주기에 부족합니다. 함수 이름은 개발자용이라 사용자의 의도를 전달하지 못하고 필드는 정수 같은 원시 타입뿐이라 퍼센트인지 날짜인지 알 수 없습니다. 토큰 금액은 소수 자릿수와 심볼 같은 추가 정보가 있어야 올바르게 표시할 수 있고 기밀 토큰처럼 값 자체가 암호화된 경우는 해독 맥락이 없으면 아예 해석할 수 없습니다. 결국 사용자는 뜻을 알 수 없는 데이터에 서명하게 되어 가짜 화면이나 피싱 공격에 취약해집니다. 이 표준은 앱 개발자가 표시 방법을 한 번만 파일로 적어 두면 이를 지원하는 여러 지갑에서 그대로 쓸 수 있게 하는 공개 포맷입니다.
심층 설명
적용 대상과 컨테이너 구조
이 표준은 타입 체계와 스키마가 있는 구조화 데이터 전반을 다룹니다. 현재 버전은 두 가지를 지원합니다. 첫째는 EVM 스마트 컨트랙트 calldata로, 스키마는 함수 ABI이고 컨테이너 구조는 RLP로 직렬화된 EVM 트랜잭션입니다. 둘째는 EIP-712 메시지로, 스키마는 display.formats 키에 담긴 타입 문자열에서 추출하며 메시지 자체에 EIP-712 방식으로 서명합니다. 컨테이너 구조는 구조화 데이터를 감싸는 바깥 구조로, 직렬화와 해시, 서명 알고리즘이 정의되어 있으며 구조화 데이터와 같은 타입 체계를 따르지 않을 수 있습니다. 필드 포맷팅에서 컨테이너의 값(보내는 주소, 받는 주소, 금액 등)을 참조해야 할 때도 있어 별도 참조 방법이 정의됩니다.
context 섹션의 바인딩 제약
context는 이 파일을 어떤 데이터에 적용해도 되는지 정하는 제약 집합이며 지갑은 포맷 적용 전에 이 제약 충족을 반드시 검증해야 합니다. 컨트랙트 바인딩은 contract.deployments 배열에 chainId와 address 쌍으로 배포 주소를 나열하며 대상 주소가 이 중 하나와 일치하거나 그중 하나를 가리키는 프록시여야 합니다. contract.factory는 팩토리가 배포한 컨트랙트를 다루며 트랜잭션 목적지 주소가 deployEvent 시그니처의 이벤트에 포함되고 그 이벤트 발행자가 팩토리 배포 주소와 일치하는지 확인합니다. EIP-712 바인딩은 eip712.domain의 키값 쌍 일치, eip712.deployments의 chainId와 verifyingContract 일치, 또는 eip712.domainSeparator 해시값 일치를 검증합니다. contract.abi와 eip712.schemas 키는 하위 호환용으로 남아 있으며 더 이상 권장되지 않습니다.
display.formats 키와 셀렉터 매칭
컨트랙트의 경우 각 키는 transfer(address to,uint256 value)처럼 매개변수 이름을 포함한 사람이 읽을 수 있는 ABI 함수 조각이어야 합니다. 키는 정식 Solidity 타입 이름만 쓰고(uint 같은 별칭 금지), 쉼표 뒤 공백은 금지되며 타입과 이름 사이는 공백 하나여야 합니다. 지갑은 키에서 매개변수 이름을 제거해 타입 전용 시그니처를 만들고 keccak256 해시의 앞 4바이트를 calldata 셀렉터와 비교해 매칭합니다. 같은 타입 전용 시그니처를 가진 키가 여럿이면 잘못된 디스크립터로 취급해야 합니다. 일치하는 키가 없으면 관련 없는 포맷을 적용해서는 안 되고 안전한 대체 표시를 보여 주어야 합니다. EIP-712의 경우 키는 기본 타입에 encodeType을 적용한 문자열이어야 하며 메시지에서 계산한 타입 해시와 키의 해시가 일치해야 합니다.
경로 참조 표기법
여러 JSON 문서에 걸친 값을 가리키기 위해 점 표기법만 쓰는 제한된 JSON 경로 표기를 사용합니다. 루트 기호가 세 가지입니다. #은 서명할 구조화 데이터로, 디코딩된 함수 인자나 EIP-712 메시지 필드를 가리킵니다. $는 includes 병합 후의 ERC-7730 파일 자체로, metadata의 상수나 enum, display.definitions의 공용 정의를 참조합니다. @는 컨테이너 값으로, @.value나 @.to처럼 트랜잭션 자체의 금액이나 목적지 주소를 가리킵니다. 루트를 생략하면 설명 중인 구조에 대한 상대 경로가 됩니다. bytes나 string 같은 가변 길이 타입에는 [0:20]이나 [-20:] 같은 슬라이스 선택자를 붙여 특정 바이트 구간을 가리킬 수 있으며 시작 인덱스는 포함이고 끝 인덱스는 제외입니다.
필드 포맷 명세와 intent 보간
각 필드 명세는 위치(path) 또는 상수(value), 표시 라벨(label), 변환 방식(format), 포맷별 매개변수(params)로 구성됩니다. visible 키로 표시 규칙을 정할 수 있는데 never, always, optional 외에 특정 값일 때만 보이는 ifNotIn, 값을 검사해 불일치 시 오류를 내는 mustMatch 규칙이 있습니다. encryption 키는 암호화된 필드에 scheme(암호화 방식), plaintextType(복호화된 값의 Solidity 타입), fallbackLabel(복호화 불가 시 표시 문구)을 지정합니다. interpolatedIntent는 {path} 문법으로 필드 값을 문장 안에 끼워 넣은 짧은 설명 문자열로, 지갑은 각 표현식의 경로를 해석하고 fields 배열의 해당 포맷을 적용해 값을 치환해야 하며 보간이 하나라도 실패하면 일반 intent 표시로 돌아가야 합니다. 보간 경로는 항상 보이는 필드만 참조해야 합니다.
metadata 섹션의 상수들
metadata는 context가 일치할 때 신뢰할 수 있는 상수를 담습니다. owner와 contractName은 상호작용 대상의 표시 이름이고, info는 배포 날짜와 공식 URL입니다. token 키는 ERC-20 인터페이스를 가진 컨트랙트가 name(), symbol(), decimals() 호출을 지원하지 않을 때만 name, ticker, decimals 값을 제공합니다. constants는 포맷터 매개변수로 재사용할 수 있는 키값 쌍입니다. maps는 체인 ID 등 트랜잭션 맥락에 따라 달라지는 상수를 표현하며 map과 keyPath로 참조하고 일치하는 값이 없으면 지갑은 그 파일을 해당 트랜잭션에 무효한 것으로 취급해야 합니다. enums는 고정된 값 집합을 갖는 매개변수의 표시 문자열을 정의해, 예를 들어 정수 1과 2를 stable과 variable 같은 읽기 쉬운 값으로 바꿉니다.
파일 포함과 스키마 버전 관리
includes 키는 다른 ERC-7730 파일의 URL을 가리키며 지갑은 두 파일을 하나로 병합하되 충돌 시 포함하는 쪽 파일을 우선합니다. 이를 통해 ERC-20 approve 같은 공용 인터페이스 정의를 공유하고 개별 컨트랙트가 threshold 같은 매개변수만 덮어쓸 수 있습니다. 스키마는 유의적 버전(Semantic Versioning)을 따르며 MAJOR 상승은 기존 유효 디스크립터를 무효화하는 변경, MINOR는 유효 집합을 넓히는 추가, PATCH는 비규범 문구 수정입니다. 디스크립터의 $schema 키가 적용할 버전을 정하며 지갑은 자신이 구현하지 않은 MAJOR 버전의 디스크립터를 무효로 취급해야 합니다. 정확한 버전 파일은 공개 후 불변이고 MAJOR 라인별 별칭 파일은 그 라인의 최신 릴리스 사본을 담습니다. 현재 1.0.0은 폐기, 2.1.0이 활성 버전이며 신규 통합은 활성 라인의 별칭 파일을 대상으로 하는 것이 권장됩니다.
제안 상태
이 제안은 Draft 상태입니다. 아직 검토와 수정이 진행 중인 단계이므로 명세의 세부 내용이 바뀔 수 있습니다. 실제로 원문 자체가 스키마 버전 관리 절차를 두고 여러 차례 개정을 거치고 있으며 contract.abi와 eip712.schemas처럼 이미 폐기 예정으로 표시된 키도 있습니다.