ERC-8049 컨트랙트 온체인 메타데이터 (Contract-Level Onchain Metadata)
Draft · 이름·메타데이터 · 2025-10-10 작성
어떤 컨트랙트든 자기 자신에 대한 정보를 키-값 쌍으로 체인 위에 직접 저장하고 지갑이나 탐색기가 외부 서비스 없이 그 값을 읽을 수 있게 하는 표준입니다.
왜 필요한가
지금까지 컨트랙트에 대한 설명 정보(메타데이터)는 대부분 URL이나 IPFS 같은 체인 밖(오프체인) 저장소에 두었습니다. 이 방식에서는 신뢰와 가용성 문제가 생깁니다. 서버가 내려가거나 도메인이 만료되면 정보가 사라지고 악의적인 운영자가 온체인 기록을 남기지 않고 내용을 바꿀 수도 있습니다. 지갑이나 블록 탐색기는 외부 서비스를 믿어야만 컨트랙트 정보를 보여 줄 수 있습니다. 이 표준은 메타데이터를 키-값 쌍으로 컨트랙트 안에 직접 저장하게 해서 검열에 강하고 누구나 검증할 수 있는 컨트랙트 정보를 외부 서비스에 기대지 않고 읽을 수 있게 합니다. 모든 변경은 이벤트로 남아 추적할 수 있습니다.
구현해야 하는 것
function metadata(string calldata key) external view returns (bytes memory);: 키에 해당하는 컨트랙트 수준 메타데이터 값을 bytes로 돌려줍니다. 이 표준의 유일한 필수 함수입니다.event MetadataSet(string indexed indexedKey, string key, bytes value);: 메타데이터가 설정될 때마다 발생하는 필수 이벤트입니다. 인덱스된 키로 변경 내역을 효율적으로 필터링할 수 있습니다.setMetadata(string calldata key, bytes calldata value): 선택 함수로, 메타데이터를 갱신합니다. 쓰기 권한 정책은 컨트랙트가 정합니다.function metadataAuthority() external view returns (address);: 선택 확장에서, 현재 이 컨트랙트의 메타데이터 쓰기 권한자를 돌려줍니다.event MetadataAuthoritySet(address indexed authority);: 메타데이터 권한자가 설정, 변경, 해제될 때마다 발생하는 이벤트입니다.
심층 설명
필수 인터페이스와 인터페이스 ID
구현 컨트랙트는 metadata(string)과 MetadataSet(string indexed indexedKey, string key, bytes value) 이벤트를 반드시 구현해야 하고 메타데이터가 설정될 때마다 이벤트를 발생시켜야 합니다. 갱신용 setMetadata(string calldata key, bytes calldata value) 함수는 선택이며 쓰기 정책은 컨트랙트가 정합니다. 인터페이스 ID는 metadata(string)의 셀렉터인 0x80a6dfa0입니다. 키는 string, 값은 bytes 타입이며 값에 적용되는 표준이 따로 명시되지 않으면 클라이언트는 UTF-8 문자열로 가정할 수 있습니다. 키에는 ERC-8119 방식의 파라미터를 붙여 "registration: 1"처럼 변형이나 인스턴스를 표현할 수 있습니다.
ERC-8048(토큰별 메타데이터)과의 이름 공유
함수 이름은 토큰별 메타데이터 표준인 ERC-8048과 같고 ERC-8048 쪽은 tokenId를 먼저 받는 metadata(uint256,string)과 setMetadata(uint256,string,bytes) 형태입니다. 두 형태는 셀렉터가 다른 Solidity 오버로드이므로 한 컨트랙트가 둘 다 구현할 수 있습니다. 일부 라이브러리는 인자만으로 오버로드를 구분하지 못하므로, ABI에 두 형태가 함께 있으면 클라이언트는 metadata(string), metadata(uint256,string)처럼 전체 시그니처로 호출하는 것이 권장됩니다. 이벤트도 MetadataSet(string,string,bytes)와 ERC-8048의 MetadataSet(uint256,string,string,bytes)는 topic0 값이 달라 인덱서가 구분해 필터링합니다.
AI 에이전트 메타데이터 프로필(ERC-20Agent)
ERC-20 토큰 컨트랙트를 하나의 AI 에이전트와 연결하는 예약 키 모음으로, 새 인터페이스나 함수, 이벤트를 추가하지 않고 기존 metadata(string)과 MetadataSet 이벤트를 그대로 씁니다. 예약 키는 context(에이전트 맥락, UTF-8 텍스트이며 마크다운 권장), endpoint[<type>](프로토콜별 접속 주소), address[<chain-id>](해당 체인의 기본 계정), account[<chain-id>][<index>](선택, 추가 계정)입니다. 키는 대소문자를 구분하며 예약된 endpoint 타입은 소문자 mcp, a2a, web, x402, ens입니다. 에이전트는 토큰 컨트랙트 전체에 속하고 특정 보유자나 잔액에 속하지 않습니다. 클라이언트는 자금을 address[<chain-id>]로 보내야 하고 account 키의 계정이 입금을 받는다고 가정하면 안 됩니다.
체인별 주소 표기(ERC-7930)
address[<chain-id>] 키에서 <chain-id>는 ERC-7930 체인 식별자(주소 부분 길이가 0인 상호운용 주소)를 소문자 0x 접두 16진수 문자열로 쓴 것입니다. 저장되는 값은 그 체인에 대한 ERC-7930 상호운용 주소의 주소 구성요소만이며 EVM 체인이면 20바이트 주소입니다. 예를 들어 이더리움 메인넷(체인 ID 1)의 체인 식별자는 0x00010000010100이므로, 에이전트의 메인넷 계정은 키 "address[0x00010000010100]"에 20바이트 주소로 저장됩니다. 추가 계정은 "account[0x00010000010100][0]"처럼 앞자리 0이 없는 10진수 인덱스로 구분합니다.
메타데이터 권한자 선택 확장
컨트랙트의 메타데이터를 별도의 권한자(metadata authority)가 쓰게 하는 확장입니다. 권한자는 계정이나 컨트랙트일 수 있고 컨트랙트 권한자는 키별로 다른 쓰기 주체를 허용하는 등 자체 규칙을 적용할 수 있습니다. 구현은 이 ERC와 ERC-165를 함께 구현하고 supportsInterface에서 0xa3703af1에 true를 돌려줘야 합니다. metadataAuthority()가 제로 주소가 아니면 setMetadata는 정확히 그 권한자만 허용해야 합니다. 제로 주소이면 컨트랙트 자체 쓰기 정책이 적용되며 갱신이 아예 불가능할 수도 있습니다. 인가에 실패한 호출은 되돌려야(revert) 하며 MetadataSet을 발생시키면 안 됩니다. 권한자가 설정, 변경, 해제될 때마다 MetadataAuthoritySet을 발생시켜야 합니다.
이미 배포된 컨트랙트를 위한 metadata_contract 확장
metadata 함수 없이 이미 배포되어 업그레이드가 어려운 컨트랙트를 위한 선택 확장입니다. contractURI 같은 컨트랙트 수준 URI 함수가 돌려주는 JSON 문서에 최상위 문자열 속성 "metadata_contract"를 넣어, 같은 체인에서 metadata(string)을 구현한 별도 메타데이터 컨트랙트의 주소를 가리킬 수 있습니다. 값은 0x 뒤에 16진수 40자여야 하고 클라이언트는 대소문자를 모두 받아들이되 이 형식이 아니면 무시해야 합니다. 이 확장만 쓰는 컨트랙트는 IERC8049를 구현할 필요가 없지만 참조된 컨트랙트는 metadata(string)을 구현해야 합니다. 클라이언트는 신뢰하지 않는 metadata_contract를 무시할 수 있습니다.
이전 리비전과의 비호환
이 Draft의 이전 리비전은 함수를 contractMetadata(string)과 setContractMetadata(string,bytes), 이벤트를 ContractMetadataUpdated, 인터페이스 ID를 0x8ec3f882로 정의했습니다. 그 리비전의 구현은 현재 버전과 호환되지 않으므로 다시 배포하거나 업그레이드해야 합니다. 그 외에는 기존 스마트 컨트랙트와 완전히 호환되며 지원하지 않는 클라이언트는 이 체계를 무시하면 됩니다.
제안 상태
이 문서는 2025년 10월 10일에 만들어진 Draft(초안) 상태의 제안입니다. 아직 확정되지 않았으므로 인터페이스나 예약 키가 앞으로 바뀔 수 있습니다. 실제로 이전 리비전에서 함수 이름과 인터페이스 ID가 한 차례 바뀐 이력이 있습니다.
쓸 때 주의할 점
- metadata_contract는 신뢰할 수 없는 입력입니다: metadata_contract는 URI가 가리키는 문서가 지정하는 것이므로, 그 컨트랙트가 돌려주는 바이트는 신뢰할 수 없습니다. 클라이언트는 새 컨트랙트와 상호작용할 때처럼 그 주소를 검증해야 합니다.