ERC-7589 준대체 토큰 역할 관리 (Semi-Fungible Token Roles)
Draft · NFT·멀티토큰 · 2023-12-28 작성
ERC-1155 준대체 토큰(SFT)의 소유권은 그대로 둔 채, 토큰을 쓸 권한(역할)을 다른 계정에 기간 한정으로 맡길 수 있게 하는 표준입니다. 기한이 지나면 권한은 자동으로 사라집니다.
왜 필요한가
ERC-1155는 하나의 컨트랙트로 대체 가능 토큰과 대체 불가 토큰을 함께 발행할 수 있게 해 주었지만 누가 몇 개를 갖고 있는지(잔액)만 추적할 뿐 그 토큰을 누가 어떻게 쓸 수 있는지는 다루지 않습니다. 그런데 토큰의 쓸모에서 중요한 부분이 바로 사용 권한입니다. 소유자가 모든 권한을 직접 쓰는 경우도 있지만 게임 아이템처럼 소유권은 유지하면서 사용 권한만 다른 사람에게 빌려주고 싶은 경우도 많습니다. 표준화된 방법이 없으면 토큰 자체를 통째로 넘기거나 서비스마다 제각각인 방식을 써야 하고 빌려준 권한을 언제 어떻게 되돌려 받을지도 보장하기 어렵습니다. 이 표준은 토큰을 맡겨 두고(커밋) 만료일이 있는 역할을 부여하는 공통 인터페이스를 정의해 이 문제를 풉니다.
구현해야 하는 것
event RoleRevoked(uint256 indexed _commitmentId, bytes32 indexed _role, address indexed _grantee);: 역할이 철회되었을 때 발생하는 이벤트입니다.event TokensReleased(uint256 indexed _commitmentId);: 커밋된 토큰이 소유자에게 되돌려졌을 때 발생하는 이벤트입니다.event RoleApprovalForAll(address indexed _tokenAddress, address indexed _operator, bool _isApproved);: 다른 사용자를 대신해 역할을 관리할 운영자의 승인 상태가 바뀌었을 때 발생하는 이벤트입니다.function revokeRole(uint256 _commitmentId, bytes32 _role, address _grantee) external;: 부여된 역할을 철회합니다.function releaseTokens(uint256 _commitmentId) external;: 커밋된 토큰을 소유자에게 되돌려줍니다.function setRoleApprovalForAll(address _tokenAddress, address _operator, bool _approved) external;: 운영자가 자신을 대신해 역할을 부여하고 철회할 수 있도록 승인하거나 해제합니다.function grantorOf(uint256 _commitmentId) external view returns (address grantor_);: 커밋의 소유자(그랜터)를 돌려줍니다.function tokenAddressOf(uint256 _commitmentId) external view returns (address tokenAddress_);: 커밋된 토큰의 컨트랙트 주소를 돌려줍니다.function tokenIdOf(uint256 _commitmentId) external view returns (uint256 tokenId_);: 커밋된 토큰의 식별자를 돌려줍니다.function tokenAmountOf(uint256 _commitmentId) external view returns (uint256 tokenAmount_);: 커밋된 토큰 수량을 돌려줍니다.
심층 설명
토큰 커밋이라는 추상화
이 표준의 중심 개념은 토큰 커밋(token commitment)입니다. 커밋은 컨트랙트에 예치된 토큰이거나 동결된 잔액을 뜻하며 commitTokens(_grantor, _tokenAddress, _tokenId, _tokenAmount)가 고유한 commitmentId_를 돌려줍니다. _tokenAmount가 0이거나 msg.sender가 _grantor의 승인을 받지 않았으면 반드시 revert해야 합니다. 커밋의 내용은 grantorOf, tokenAddressOf, tokenIdOf, tokenAmountOf로 조회하며 이 조회 함수들은 각각 커밋된 토큰의 소유자, 주소, 식별자, 수량을 반드시 반환해야 합니다.
역할 식별자와 자동 만료
역할은 bytes32 식별자로 표현하며 역할 이름과 인자의 keccak256 해시를 쓰는 것이 권장됩니다(예: keccak256("Player(uint256)")). 만료일은 uint64이고 grantRole은 _expirationDate가 과거이거나 호출자가 승인받지 않았으면 반드시 revert해야 합니다. 역할을 끝내려고 매번 revokeRole을 부르는 대신, 앱이 roleExpirationDate를 현재 시각과 비교해 유효성을 판단하게 하여 가스를 아낍니다. uint64가 표현하는 최대 UNIX 타임스탬프는 약 5840억 년 뒤이므로, type(uint64).max를 쓰면 사실상 영구 역할을 나타냅니다.
철회 가능 여부와 revokeRole 규칙
grantRole의 _revocable 파라미터는 소유자가 만료 전에 역할을 거둘 수 있는지를 정합니다. 수령자가 대가를 지불한 경우처럼 중도 철회가 없다는 보장이 필요한 상황을 위한 장치입니다. 반면 수령자는 _revocable 값과 무관하게 언제나 역할을 철회할 수 있어서 원치 않는 부여를 없앨 수 있습니다. revokeRole은 역할 부여가 존재하지 않을 때, msg.sender가 소유자나 수령자의 승인을 받지 않았을 때, 그리고 소유자 측 호출인데 역할이 철회 불가이거나 만료된 경우 반드시 revert해야 합니다.
토큰 회수와 역할 승인
releaseTokens는 커밋이 존재하지 않을 때, msg.sender가 소유자가 아니고 승인도 받지 않았을 때, 그리고 만료되지 않은 철회 불가 역할이 하나라도 있을 때 반드시 revert해야 합니다. 한편 setRoleApprovalForAll과 isRoleApprovedForAll은 핵심 인터페이스에 포함된 필수 기능으로, 토큰 주소 단위로 운영자(operator)에게 역할 부여·철회를 맡길 수 있게 합니다. 이 승인은 토큰 보관 수준의 권한 없이 제3자 앱이 역할을 관리하게 해 주며 ERC-1155의 전송 승인과는 다른 것이므로 혼동하면 안 됩니다.
커스텀 데이터 _data
SFT의 쓰임새는 다양해서 모든 경우를 솔리디티 인터페이스로 정의하기 어렵습니다. 그래서 grantRole에 bytes 타입의 _data 파라미터를 두어 역할을 부여할 때 임의의 정보를 함께 담게 했습니다. 예를 들어 웹3 게임에서 흔한 수익 배분(profit-share) 값은 uint256 하나로 표현되는데, 이를 bytes로 인코딩해 grantRole에 넘기면 됩니다. 데이터 검증은 온체인에서도 오프체인에서도 할 수 있고 다른 컨트랙트는 roleData 함수로 이 정보를 조회할 수 있습니다.
ERC-1155의 확장이 아닌 독립 표준
이 표준은 의도적으로 ERC-1155의 확장이 아닙니다. 구현 방식에 중립적이기 위해서인데, 덕분에 SFT 컨트랙트 안에 직접 구현할 수도 있고 별도의 외부 컨트랙트로 구현할 수도 있습니다. 많은 SFT가 수정 불가능한 불변 컨트랙트로 배포되어 있다는 문제는 commitTokens가 tokenAddress 파라미터를 받도록 하여 해결합니다. 이미 배포된 SFT라도 외부의 독립 컨트랙트를 역할의 공식 출처로 삼아 역할 관리를 붙일 수 있습니다. ERC-165 식별자는 핵심 인터페이스가 0xc4c8a71d입니다.
세 가지 선택 확장
첫째, 단일 트랜잭션 확장(식별자 0x5c3d7d74)은 커밋과 역할 부여라는 두 단계를 commitTokensAndGrantRole 한 번의 호출로 처리합니다. 둘째, 역할 잔액 확장(식별자 0x2f35b73f)의 roleBalanceOf는 만료된 역할을 거르고 특정 역할로 수령자에게 부여된 수량의 합을 돌려주는데, 구현을 복잡하게 만들어 컨트랙트 위험을 키울 수 있어 선택 사항입니다. 셋째, 메타데이터 확장은 ERC-1155의 JSON 메타데이터에 roles 배열(id, name, description, inputs)을 더하며 inputs는 grantRole에 인코딩해 넘길 파라미터 형식을 설명합니다. 이 확장을 쓰는 DApp은 ERC-1155 메타데이터 확장도 구현해야 합니다.
제안 상태
이 문서는 2023년 12월 28일에 만들어졌고 현재 상태가 Draft(초안)입니다. 아직 확정된 표준이 아니므로 인터페이스와 규칙이 앞으로 바뀔 수 있다는 점을 염두에 두어야 합니다.
쓸 때 주의할 점
- 접근 제어 확인: 무단으로 역할이 부여되거나 철회되지 않도록 적절한 접근 제어를 갖춰야 합니다. 특히 commitTokens와 releaseTokens는 잔액을 동결하거나 옮길 수 있어 더욱 중요합니다.
- 재진입 등 공격 벡터 대비: 재진입(reentrancy) 같은 잠재적 공격 벡터를 고려하고 알맞은 안전장치를 마련해야 합니다.
- 만료일 확인: 사용자가 역할 부여를 이용하도록 허용하기 전에 항상 만료일을 확인해야 합니다.