ERC-7572 컨트랙트 수준 메타데이터 표준 (Contract-level metadata via `contractURI()`)

Draft · 이름·메타데이터 · 2023-12-06 작성

컨트랙트가 contractURI() 함수 하나로 자신의 이름, 설명, 이미지 같은 소개 정보를 알려 주고 정보가 바뀌면 이벤트로 알릴 수 있게 하는 표준입니다.

왜 필요한가

이더리움 컨트랙트에는 이름이나 설명, 대표 이미지 같은 소개 정보를 담아 두는 공통 방법이 없었습니다. 그래서 블록체인 앱(댑, dapp)이나 체인 밖에서 데이터를 모으는 인덱서(indexer)는 컨트랙트에 대한 풍부한 정보를 보여 주려면 서비스마다 수동으로, 컨트랙트마다 따로 입력해야 했습니다. 사실 여러 댑이 이미 contractURI()라는 함수를 수년간 지원해 왔지만 참조할 공식 표준(ERC)이 없었습니다. 또 메타데이터가 바뀌었을 때 이를 알리는 공통 신호가 없어 체인 밖 서비스가 언제 정보를 다시 가져와야 할지 알기 어려웠습니다. 이 표준은 contractURI() 함수와 반환 JSON의 형식, 그리고 갱신을 알리는 ContractURIUpdated() 이벤트를 정해 이 문제를 해결합니다.

구현해야 하는 것

심층 설명

필수 인터페이스와 반환값 형식

컨트랙트는 IERC7572 인터페이스를 반드시 구현해야 합니다(MUST). 인터페이스는 문자열을 반환하는 view 함수 contractURI()와 이벤트 ContractURIUpdated() 두 가지로 구성됩니다. contractURI()가 반환하는 문자열은 체인 밖(오프체인) 자원을 가리키는 주소일 수도 있고 data:application/json;utf8,{} 형태로 JSON을 그대로 담은 온체인 데이터 문자열일 수도 있습니다(MAY). 즉 메타데이터를 어디에 두는지는 구현자가 선택하되, 읽는 쪽은 항상 같은 함수로 접근합니다.

ContractURIUpdated() 이벤트의 역할

컨트랙트 메타데이터가 갱신될 때 ContractURIUpdated() 이벤트를 발생시키는 것이 권장됩니다(SHOULD). 오프체인 인덱서는 이 이벤트를 보고 해당 컨트랙트의 메타데이터를 언제 다시 가져와야 할지 알 수 있습니다. 원문 Rationale도 이 이벤트가 인덱서의 재조회 시점을 알리기 위해 명세되었다고 설명합니다. 함수 이름 contractURI()는 댑들의 기존 구현을 근거로 선택되었습니다.

name()·symbol()과 충돌할 때의 우선순위

컨트랙트가 name()이나 symbol()처럼 contractURI 스키마와 겹치는 메서드를 이미 제공하는 경우, contractURI()가 반환하는 메타데이터가 우선하는 것이 권장됩니다(RECOMMENDED). 이렇게 하면 컨트랙트 제작자가 배포 후에도 컨트랙트 정보를 갱신하고 갱신 사실을 이벤트로 알릴 수 있습니다.

JSON 스키마 구성

contractURI()가 반환하는 JSON은 정해진 스키마를 따라야 합니다(MUST). 필수 필드는 name(컨트랙트 이름) 하나입니다. 선택 필드로 symbol(심벌), description(설명), image(프로필 사진처럼 쓰이는 대표 이미지 URI), banner_image(배너 이미지 URI), featured_image(하이라이트 구역에 쓰이는 대표 이미지 URI), external_link(외부 링크), collaborators(컨트랙트의 공인 편집자를 나타내는 이더리움 주소 배열)가 있습니다. 이후의 ERC가 이 표준을 상속해 스키마에 속성을 추가로 표준화할 수 있습니다(MAY).

참조 구현과 설정 함수

참조 구현은 _contractURI 문자열 변수를 두고 contractURI()에서 이를 반환하거나, 온체인 방식으로 data:application/json;utf8, 뒤에 JSON 문자열을 이어 붙여 반환하는 예를 보여 줍니다. 메타데이터를 바꾸는 setContractURI(string memory newURI) 함수는 새 URI를 저장하고 ContractURIUpdated() 이벤트를 발생시키는 제안된 설정 함수일 뿐, 이 ERC에 명시적으로 포함된 명세는 아닙니다.

제안 상태

이 문서는 2023년 12월 6일에 만들어졌고 현재 상태가 Draft(초안)입니다. 아직 확정된 표준이 아니므로 내용이 바뀔 수 있습니다.

쓸 때 주의할 점

ERC 원문 · ← ERCs