ERC-7496 NFT 동적 특성(트레잇) (NFT Dynamic Traits)
Draft · NFT·멀티토큰 · 2023-07-28 작성
ERC-721·ERC-1155 NFT에 체인 위에서 바뀔 수 있는 특성(트레잇, trait)을 기록하고 조회·수정하는 표준 인터페이스를 더합니다. 다른 컨트랙트가 이 값을 읽고 써서 변하는 속성을 다룰 수 있습니다.
왜 필요한가
NFT의 특성 값은 보통 체인 밖에 저장됩니다. 그래서 스마트 컨트랙트 코드 안에서 그 값을 조회하거나 바꾸기 어렵고 교환권처럼 쓰고 나면 상태가 달라지는 혜택을 체인 위에 확실하게 기록할 방법도 없습니다. 거래 안전이 더 큰 문제입니다. 마켓플레이스가 체인 밖 상태에 의존하면, 구매자가 특정 특성을 보고 제안을 넣었는데 거래가 체결되기 직전에 그 특성이 바뀌는 선행매매(frontrunning) 공격에 노출됩니다. 이 제안은 특성을 체인 위에 두고 표준 방법으로 읽고 쓰게 해서 특성 값을 근거로 한 입찰과 체결 시점 검증을 가능하게 하려는 것입니다. 실제로 이 제안을 만든 동기도 특정 특성을 조건으로 NFT를 사고팔 때 체결 시점까지 그 조건이 지켜지도록 사용자를 보호하는 데 있습니다.
구현해야 하는 것
event TraitUpdated(bytes32 indexed traitKey, uint256 tokenId, bytes32 traitValue);: 한 토큰의 특성 값이 바뀌었음을 알립니다.event TraitUpdatedRange(bytes32 indexed traitKey, uint256 fromTokenId, uint256 toTokenId);: 연속된 토큰 ID 범위(양 끝 포함)의 특성이 바뀌었음을 알립니다.event TraitUpdatedRangeUniformValue(bytes32 indexed traitKey, uint256 fromTokenId, uint256 toTokenId, bytes32 traitValue);: 연속 범위의 토큰이 모두 같은 값으로 바뀌었을 때 값과 함께 알립니다.event TraitUpdatedList(bytes32 indexed traitKey, uint256[] tokenIds);: 목록으로 지정한 토큰들의 특성이 바뀌었음을 알립니다. 순서는 자유입니다.event TraitUpdatedListUniformValue(bytes32 indexed traitKey, uint256[] tokenIds, bytes32 traitValue);: 목록의 토큰이 모두 같은 값으로 바뀌었을 때 값과 함께 알립니다.event TraitMetadataURIUpdated();: 특성 메타데이터가 바뀌었으니 다시 조회하라고 알립니다.function getTraitValue(uint256 tokenId, bytes32 traitKey) external view returns (bytes32 traitValue);: 한 토큰의 특정 특성 값을 읽습니다.function getTraitValues(uint256 tokenId, bytes32[] calldata traitKeys) external view returns (bytes32[] traitValues);: 한 토큰의 여러 특성 값을 한 번에 읽습니다.function getTraitMetadataURI() external view returns (string memory uri);: 특성 이름, 표시 방법, 검증 규칙이 담긴 메타데이터의 URI를 돌려줍니다.function setTrait(uint256 tokenId, bytes32 traitKey, bytes32 newValue) external;: 한 토큰의 특성 값을 새 값으로 바꿉니다. 값이 유효하지 않으면 실패해야 합니다.
심층 설명
인터페이스 요건과 식별자
이 표준은 ERC-721과 ERC-1155를 확장하는 IERC7496 인터페이스를 정의합니다. 구현 컨트랙트는 명세에 정의된 이벤트, 게터, 세터를 모두 포함해야 하고 ERC-165 supportsInterface에서 이 ERC의 4바이트 interfaceId인 0xaf332f3e에 대해 true를 반환해야 합니다. 조회는 getTraitValue와 getTraitValues, 설정은 setTrait, 메타데이터는 getTraitMetadataURI로 접근합니다. 값과 키는 모두 bytes32 하나로 표현하는 키-값 구조입니다.
traitKey 규칙과 오류 처리
traitKey는 특성 하나를 식별하는 유일한 bytes32 값이어야 하며 사람이 읽을 수 있는 특성 이름의 keccak256 해시를 쓰는 것이 권장됩니다(SHOULD). 메타데이터 스키마에 정의되지 않은 traitKey를 다루면 TraitDoesNotExist(traitKey)로 revert해야 합니다. 반면 특성은 정의되어 있지만 해당 토큰에 값이 설정되지 않았다면 revert하지 않고 기본값 bytes32(0)을 반환해야 합니다. 이 구분 덕분에 여러 토큰에 걸쳐 정의된 모든 특성 키를 실패 없이 일괄 조회할 수 있습니다. 존재하지 않는 tokenId면 TokenDoesNotExist(tokenId)로 revert해야 하며 토큰 컨트랙트가 이미 쓰는 커스텀 오류가 있으면 그것을 대신 써도 됩니다(MAY).
특성 메타데이터 스키마
특성 메타데이터는 지정된 스키마를 따라야 하며 URI는 데이터 URI이거나 오프체인 자원을 가리킬 수 있습니다. traits 객체의 키는 유일한 특성 이름이어야 하고 이름이 0x로 시작하는 32바이트 16진수 문자열이면 그 자체를 traitKey로 해석하며 아니면 이름의 keccak256 해시가 traitKey가 됩니다. 직접 쓴 traitKey는 다른 특성 이름의 해시와 충돌하면 안 됩니다. displayName도 서로 겹치면 안 됩니다. dataType에는 string(minLength, maxLength, valueMappings 가능), decimal(signed, decimals, minValue, maxValue 가능, decimals는 음이 아닌 정수), boolean(valueMappings가 없으면 bytes32(0)이 false, bytes32(uint256(1))이 true), epochSeconds(유닉스 기점 이후 초) 네 타입이 있습니다. valueMappings로 bytes32 값에 사람이 읽을 값을 매핑할 수 있고 값을 null로 바꾸면 오프체인 인덱서가 그 특성을 지우는 것으로 기대됩니다.
validateOnSale 판매 검증
validateOnSale은 토큰이 팔릴 때 마켓플레이스가 특성 값을 어떻게 검증할지 알리는 신호입니다. 기준을 충족하지 못하면 마켓플레이스 컨트랙트는 판매를 허용하면 안 됩니다. 값은 none(검증 불필요), requireEq(구매 제안 시점 값과 같아야 함), requireNeq(같으면 안 됨), requireUintLt·requireUintLte·requireUintGt·requireUintGte(bytes32를 uint256으로 해석해 제안 시점 값보다 작음·작거나 같음·큼·크거나 같음) 중 하나이며 지정이 없으면 none으로 간주합니다. 다만 명세는 구매자와 판매자가 마켓플레이스의 검증만 믿어서는 안 되고 거래 전에 스스로 현재 특성 값을 조사해야 한다고 덧붙입니다.
이벤트와 인덱싱 규칙
특성을 업데이트하면 TraitUpdated, TraitUpdatedRange, TraitUpdatedRangeUniformValue, TraitUpdatedList, TraitUpdatedListUniformValue 중 하나를 반드시 발생시켜야 합니다. Range 이벤트의 fromTokenId와 toTokenId는 연속된 토큰 ID 범위여야 하고 양 끝을 포함하는 범위로 다룹니다. List 이벤트의 tokenIds는 순서가 자유입니다. 모든 토큰의 값이 같다면 UniformValue 계열 이벤트 사용이 권장되는데, 인덱서가 값을 하나씩 조회하지 않고 대량 업데이트를 빠르게 처리할 수 있기 때문입니다. 메타데이터를 바꾸면 TraitMetadataURIUpdated를 반드시 발생시켜야 합니다. 또 특성 값은 블록 타임스탬프 같은 시간 의존 요인이나 암묵적 상태 변화에 기반하면 안 되고 모든 변경은 이벤트를 남기는 명시적 온체인 행동의 결과여야 합니다. 그래야 인덱서가 계속 다시 계산하지 않고 이벤트 처리만으로 현재 값과 동기화할 수 있습니다.
setTrait와 토큰 소유자 업데이트
특성 메타데이터에 tokenOwnerCanUpdateValue가 true로 정의되어 있으면, 토큰 소유자가 setTrait를 호출해 그 특성 값을 바꿀 수 있어야 합니다. 소유자가 설정하려는 값이 유효하지 않으면 트랜잭션은 revert해야 하고 유효하면 값을 업데이트하고 TraitUpdated 계열 이벤트 중 하나를 발생시켜야 합니다. 원하는 값에 대한 valueMappings 항목이 정의되어 있으면, 그에 대응하는 traitValue로 setTrait를 호출해야 합니다.
설계 이유와 호환성
이 명세는 최대한의 유연성을 위해 키-값 매핑으로 설계되었습니다. 특성마다 getFoo()·setFoo() 같은 전용 함수를 두면 호출하는 쪽이 게터와 세터의 함수 셀렉터와 매개변수를 모두 알아야 하지만 일반적인 get·set 함수를 명시적으로 정의하면 함수 시그니처가 고정되어 특성 키와 값만 알면 조회와 설정이 가능합니다. 컨트랙트 코드를 수정하지 않고도 나중에 새 특성을 추가할 수 있습니다. 호환성 측면에서는 온체인 특성이 ERC-721이나 ERC-1155 메타데이터 URI에 지정된 충돌하는 값을 반드시 덮어써야 한다는 점 외에 별도의 문제가 없습니다. 참고용 Foundry 테스트와 레퍼런스 구현이 자산 폴더에 포함되어 있습니다.
제안 상태
이 제안은 Draft 상태입니다. 아직 확정되지 않아 내용이 바뀔 수 있다는 점을 감안하고 구현해야 합니다.
쓸 때 주의할 점
- 세터 권한 제한: 외부에 노출되는 set 계열 메서드는 아무나 호출할 수 없도록 반드시 권한을 걸어, 선별된 역할이나 주소만 호출할 수 있게 해야 합니다.
- 오프체인 특성 상태 불신: 마켓플레이스는 선행매매가 가능하므로 특성의 오프체인 상태를 신뢰해서는 안 되며 전송 시점에 온체인 특성의 현재 상태를 확인해야 합니다. validateOnSale이 지정된 것처럼 NFT 가치를 바꾸는 특성(예: 교환 사용 여부)을 확인하거나, 모든 특성 값을 해시해 주문 생성 시점과 같은 상태임을 보장할 수 있습니다.