ERC-8048 토큰 레지스트리 온체인 메타데이터 (Onchain Metadata for Token Registries)
Draft · 이름·메타데이터 · 2025-09-30 작성
ERC-721, ERC-1155, ERC-6909 토큰에 문자열 키와 바이트 값으로 된 저장소를 더해, 메타데이터를 외부 서버 없이 블록체인 위에 직접 저장하고 읽을 수 있게 하는 표준입니다.
왜 필요한가
NFT나 멀티토큰의 메타데이터를 블록체인 위에 직접 저장하려는 수요는 오래전부터 있었지만 지금까지 통일된 방법이 없었습니다. 일부 프로젝트는 토큰의 주소 필드인 tokenURI에 데이터 URL(Data URL) 형태로 메타데이터를 통째로 넣는 방식을 썼는데, 이 방식은 가스(수수료) 면에서 비효율적이고 저장 증명(storage proof)을 복잡하게 만드는 등의 부작용이 있습니다. 또 프로젝트마다 저장 방식이 달라서 지갑이나 앱이 여러 토큰의 메타데이터를 한 가지 방법으로 읽을 수 없습니다. 이 표준은 기존 ERC-721, ERC-1155, ERC-6909 토큰과 호환되는 통일된 키-값 저장 인터페이스를 제공해 이 문제를 해결합니다.
구현해야 하는 것
function metadata(uint256 tokenId, string calldata key) external view returns (bytes memory);: 주어진 토큰 ID와 키에 해당하는 메타데이터 값을 바이트로 돌려줍니다.event MetadataSet(uint256 indexed tokenId, string indexed indexedKey, string key, bytes value);: 토큰의 메타데이터가 설정될 때마다 반드시 발생시켜야 하는 이벤트로, 변경 이력의 감사 기록이 됩니다.setMetadata(uint256 tokenId, string calldata key, bytes calldata value): 선택적으로 제공할 수 있는 쓰기 함수입니다. 누가 쓸 수 있는지는 컨트랙트의 쓰기 정책이 정합니다.function tokenMetadataAuthority() external view returns (address);: 선택 확장의 함수로, 컬렉션의 모든 토큰에 대한 현재 메타데이터 권한 주소를 돌려줍니다.event TokenMetadataAuthoritySet(address indexed authority);: 컬렉션의 메타데이터 권한이 설정, 변경, 해제될 때 발생하며 해제 시에는 0 주소를 담습니다.
심층 설명
핵심 인터페이스: 문자열 키, 바이트 값
구현 컨트랙트는 metadata(tokenId, key) 함수를 반드시 제공해야 합니다. 키는 string, 값은 bytes 타입이라서 문자열, 숫자, 해시 등 어떤 데이터든 직관적인 키로 저장할 수 있습니다. 쓰기 함수 setMetadata(uint256, string, bytes)는 선택이며 쓰기 정책은 컨트랙트가 정합니다. 메타데이터가 설정될 때는 MetadataSet(tokenId, indexedKey, key, value) 이벤트를 반드시 발생시켜야 하며 이 이벤트가 온체인 감사 기록 역할을 합니다. 이 표준은 ERC-721, ERC-1155, ERC-6909 호환 레지스트리가 선택적으로 붙일 수 있는 확장이며 기존 표준과 하위 호환됩니다. 키에는 "registration[1]"이나 "name[maria]"처럼 파라미터를 붙여 한 종류 메타데이터의 변형이나 인스턴스를 나타낼 수 있고 파라미터 키 형식은 ERC-8119를 따릅니다.
ERC-165 인터페이스 탐지
이 표준의 인터페이스 ID는 0xdf670be1입니다. IERC8048Metadata를 구현하는 컨트랙트는 ERC-165를 반드시 구현해야 하고 supportsInterface 호출에 대해 0xdf670be1(이 인터페이스)과 0x01ffc9a7(ERC-165 자체) 두 값 모두 true를 돌려줘야 합니다. 이렇게 하면 호출자가 레코드를 읽기 전에 해당 컨트랙트가 온체인 메타데이터를 지원하는지 먼저 확인할 수 있습니다. 메타데이터 권한 확장을 구현하는 경우에는 그 확장의 인터페이스 ID인 0x04f90b41에 대해서도 true를 돌려줘야 합니다.
에이전트 메타데이터 프로필(ERC-721T)
에이전트를 나타내는 ERC-721 토큰을 위해 예약 키 집합을 정의한 프로필로, 새 솔리디티 인터페이스나 ERC-165 ID, 이벤트를 추가하지 않고 기존 metadata 함수와 MetadataSet 이벤트를 그대로 씁니다. 예약 키는 context(UTF-8 텍스트, 마크다운 권장), endpoint[<type>](표준 타입은 mcp, a2a, web, x402, ens이며 키는 대소문자를 구분해 소문자 표기가 규범), address[<chain-id>](기본 계정), account[<chain-id>][<index>](추가 계정, index는 선행 0 없는 10진 정수)입니다. <chain-id>는 ERC-7930 체인 식별자로, 이더리움 메인넷은 0x00010000010100, Base는 0x0001000002210500입니다. 값은 해당 체인의 주소 바이트이며 EVM 체인은 20바이트입니다. 클라이언트는 자금을 address[<chain-id>]로 보내야 하고 account 키의 계정이 결제를 받는다고 가정하면 안 됩니다. tokenURI는 기존 마켓플레이스용으로 그대로 유지하고 에이전트 인식 클라이언트는 이 표준의 레코드에서 키를 읽되 엔드포인트와 context를 신뢰할 수 없는 입력으로 다뤄야 합니다.
메타데이터 권한 확장
컬렉션 전체 토큰의 메타데이터를 보유자 대신 하나의 메타데이터 권한(계정 또는 컨트랙트)이 쓰게 하는 선택 확장입니다. 읽기 함수 tokenMetadataAuthority()와 이벤트 TokenMetadataAuthoritySet만 표준화합니다. tokenMetadataAuthority()가 0이 아니면 setMetadata는 모든 토큰에 대해 예외 없이 그 주소만 허용해야 하고 0이면 누가 쓸 수 있는지는 컨트랙트 자체 쓰기 정책에 맡깁니다. 권한 실패 호출은 MetadataSet을 내지 않고 revert해야 합니다. 권한을 설정·변경·해제하는 방법은 구현마다 다르지만 반환 주소가 바뀔 때마다 이벤트를 발생시켜야 하고 배포 시 권한이 0이 아니면 배포 때도 발생시켜야 합니다. 컬렉션당 하나의 권한만 둔 이유는 토큰별 권한이면 권한 교체 때 토큰마다 이벤트가 필요하기 때문이고 여러 당사자가 서로 다른 키를 써야 하면 정책 컨트랙트를 권한으로 설정합니다. 원문 예시에서는 주택 토큰의 정책 컨트랙트가 주택청에는 크기, 감정관에는 평가액, 소유자에게는 usr.* 키만 쓰게 합니다.
기배포 컨트랙트를 위한 메타데이터 컨트랙트 참조
이미 배포된 레지스트리는 업그레이드 경로가 없으면 metadata 함수나 저장 공간을 추가할 수 없습니다. 이 선택 확장은 tokenURI나 uri가 돌려주는 JSON 문서에 최상위 문자열 속성 "metadata_contract"를 두어, 같은 체인에 있는 별도 메타데이터 컨트랙트 주소를 가리키게 합니다. 값은 0x 뒤에 40자리 16진수가 오는 20바이트 주소 문자열이어야 하며 클라이언트는 대소문자를 가리지 않고 받아들입니다. 형식이 맞지 않으면 무시합니다. 클라이언트는 같은 tokenId로 그 컨트랙트의 metadata(uint256,string)을 읽으며 결과는 토큰 컨트랙트가 직접 저장한 경우와 같습니다. 이 확장만 쓰는 레지스트리는 토큰 컨트랙트에 IERC8048Metadata를 구현할 필요가 없지만 참조된 컨트랙트는 해당 함수를 구현해야 합니다. 악의적이거나 잘못된 주소는 공격자가 조작한 바이트를 돌려줄 수 있으므로 신뢰할 수 있는 컨트랙트만 호출하도록 권고합니다.
초안(Draft) 상태
이 제안은 2025년 9월 30일에 만들어졌고 현재 상태가 Draft입니다. 아직 검토 과정에서 내용이 바뀔 수 있는 단계라는 뜻이므로, 구현하거나 의존하기 전에 최신 원문을 확인하는 것이 좋습니다. 이 제안은 ERC-165(인터페이스 탐지), ERC-7930(상호 운용 주소), ERC-8119(파라미터 키 형식)를 선행 요건으로 참조합니다.
쓸 때 주의할 점
- 권한 컨트랙트 교체 가능성: 메타데이터 권한으로 설정된 컨트랙트는 구현이 막지 않는 한 교체될 수 있습니다. 정책 컨트랙트의 규칙은 그 컨트랙트가 권한으로 남아 있는 동안에만 유효합니다.