ERC-8257 AI 에이전트 툴 레지스트리 (Agent Tool Registry)
Draft · 기타 · 2026-04-17 작성
AI 에이전트가 쓰는 툴을 온체인에 등록해 메타데이터 해시로 위변조를 검증하고 외부 프레디케이트 컨트랙트로 접근 제어와 가격 비교까지 표준화하는 레지스트리입니다.
왜 필요한가
AI 에이전트가 쓰는 툴들은 지금 각자의 사설 카탈로그에 흩어져 있어 공통된 온체인 출처가 없고 에이전트가 툴을 찾거나 그 내용이 변조되지 않았는지 확인할 방법이 없습니다. 접근 제어 방식도 서비스마다 제각각이라 NFT 보유, 구독, 화이트리스트 같은 모델을 새로 지원할 때마다 레지스트리 자체를 고쳐야 합니다. 가격 정보도 표준화되어 있지 않으면 에이전트가 비슷한 기능을 하는 두 툴 중 어느 쪽이 더 싼지 호출 전에 비교할 수 없습니다. 이런 상태에서는 에이전트가 신뢰할 수 있는 툴을 자동으로 찾고 비용과 접근 조건을 미리 계산해 선택하는 일이 어렵습니다.
구현해야 하는 것
event ToolDeregistered(uint256 indexed toolId);: creator가 툴을 영구히 등록 해지했을 때 발생합니다.function deregisterTool(uint256 toolId) external;: creator만 호출할 수 있으며 툴을 영구히 등록 해지합니다.function setAccessPredicate(uint256 toolId, address newPredicate) external;: creator만 호출할 수 있으며 접근 프레디케이트를 바꿉니다. address(0)이면 공개 접근이 됩니다.function getToolConfig(uint256 toolId) external view returns (ToolConfig memory);: creator, metadataURI, manifestHash, accessPredicate로 구성된 툴 전체 설정을 조회합니다.function toolCount() external view returns (uint256);: 지금까지 등록된 툴의 총 개수(가장 높은 toolId)를 반환합니다.function name() external view returns (string memory);: 레지스트리 구현체를 식별하는 사람이 읽을 수 있는 이름을 반환합니다.function version() external view returns (string memory);: 레지스트리 구현체의 버전 문자열을 반환합니다.function name() external view returns (string memory);: 프레디케이트 구현체를 식별하는 이름을 반환합니다(예: ERC721OwnerPredicate).function getRequirements(uint256 toolId) external view returns (AccessRequirement[] memory requirements, RequirementLogic logic);: 에이전트가 접근 조건을 미리 알 수 있도록 요구사항 배열과 AND/OR 결합 방식을 반환합니다.
심층 설명
ToolConfig와 등록·해지 규칙
ToolConfig 구조체는 creator(등록 후 불변), metadataURI, manifestHash, accessPredicate 네 필드로 구성됩니다. registerTool은 msg.sender를 creator로 기록하고 순차적 toolId를 반환합니다. metadataURI가 빈 문자열이거나 2,048바이트를 넘으면 InvalidMetadataURI로, manifestHash가 bytes32(0)이면 InvalidManifestHash로 되돌립니다(revert). deregisterTool은 creator만 호출할 수 있고 영구적이며 이후 모든 조회는 ToolIsDeregistered로 되돌아가 '존재한 적 없음'과 구분됩니다. toolId는 재사용되지 않고 toolCount()는 항상 가장 높은 toolId와 같습니다.
접근 프레디케이트 패턴과 kind 네임스페이스
접근 제어는 레지스트리가 아니라 accessPredicate라는 외부 컨트랙트에 위임됩니다. Seaport의 zone, Uniswap v4의 hook, ERC-4337의 paymaster와 같은 '플러그인형 외부 컨트랙트' 패턴입니다. accessPredicate가 address(0)이면 완전 공개입니다. IAccessPredicate는 hasAccess, name, getRequirements 세 함수로 구성되며 getRequirements는 AccessRequirement 배열(kind, data, label)과 AND/OR 결합 방식(RequirementLogic)을 반환해 에이전트가 403을 받았을 때 무엇을 충족해야 하는지 조회할 수 있게 합니다. kind는 ERC-165 스타일 4바이트 식별자로, IERC721Holding(0xbdf8c428), IERC1155Holding(0xcb429230), ISubscription(0x44387cc2) 세 가지가 명세에 정의되어 있고 누구나 새 마커 인터페이스를 publish해 확장할 수 있습니다.
hasAccess와 tryHasAccess의 차이
hasAccess(toolId, account, data)는 단순화된 조회로, 프레디케이트 호출이 성공하고 정상적으로 true를 반환한 경우에만 true를 돌려줍니다. 되돌림(revert), 가스 초과, 비정형 반환값, 코드 없는 주소 등 어떤 오작동도 false로 처리되어 '명확한 거부'와 구분되지 않습니다. tryHasAccess는 (ok, granted) 두 값을 반환해 프레디케이트가 정상 응답했는지(ok)와 접근이 허용됐는지(granted)를 분리합니다. (false, true) 조합은 금지되며 등록되지 않았거나 해지된 toolId는 두 함수 모두 malfunction으로 처리하지 않고 각각 ToolNotFound, ToolIsDeregistered로 되돌립니다.
toolId 스코프와 CAIP 식별자
툴 ID는 (chainId, registryAddress) 튜플에 묶여 있어 서로 다른 레지스트리 배포가 같은 toolId를 중복해서 쓸 수 있습니다. 인덱서나 지갑 같은 오프체인 소비자는 반드시 체인ID와 레지스트리 주소까지 함께 명시해야 합니다. 권장 표준 표기는 CAIP-19 자산 식별자 문법을 따른 eip155:<chainId>/erc8257:<registryAddress>/<toolId> 형태이며 erc8257 네임스페이스는 아직 ChainAgnostic CAIP 저장소에 등록되지 않았지만 이 ERC가 그 등록을 제안합니다.
매니페스트 정규화(JCS)와 해시 커밋
manifestHash는 매니페스트 원문 대신 RFC 8785 JSON Canonicalization Scheme(JCS)으로 정규화한 바이트에 대한 keccak256입니다. JCS는 키 순서, 공백, 숫자 표기, 문자열 이스케이프를 정규화하지만 유니코드 정규화, 16진수 대소문자, BOM은 다루지 않으므로 이 ERC가 추가 규칙을 둡니다. 모든 문자열은 NFC여야 하고 매니페스트는 BOM 없는 UTF-8로 제공돼야 하며 creatorAddress·kind·data·enclaveHash·buildHash 등 모든 16진수 필드는 소문자여야 합니다. 세 규칙 중 하나라도 어긋나면 소비자는 조용히 고쳐 쓰지 않고 검증 실패로 처리해 해시 불일치를 드러내야 합니다.
매니페스트 필드와 오리진 바인딩
필수 필드는 type, name(1-128자, NFC, 제어문자 금지), description(1-500자), endpoint(정규화 후 반드시 https://로 시작), inputs/outputs(JSON Schema), creatorAddress(소문자 0x+40자리 16진수)입니다. creatorAddress는 온체인 creator(= registerTool 호출자)와 반드시 일치해야 해서 매니페스트 위조를 막습니다. 추가로 매니페스트는 endpoint와 같은 오리진의 <origin>/.well-known/ai-tool/<slug>.json 경로에서도 그대로 받아져야 하는 오리진 바인딩 규칙이 있어 등록된 metadataURI가 이 well-known 경로와 정확히 일치해야 합니다.
가격과 검증 가능성 등급
pricing 배열은 프로토콜에 종속되지 않는 가격 힌트로, amount(최소 단위 정수 문자열)·asset(CAIP-19)·recipient(CAIP-10)·protocol(예: x402) 네 필드가 모두 필수이며 asset과 recipient는 같은 체인을 참조해야 합니다. amount가 0이면 '무료지만 지정된 protocol로 흐름을 태우고 싶다'는 의미입니다. verifiability 객체는 tier(self-attested/hardware-attested/verifiable)와 execution(standard/tee/e2ee)을 중심으로 attestation, reproducibleBuild, dataRetention, sourceVisibility를 담아 실행 환경과 데이터 처리 보증을 선언합니다. tier가 구조적 필드와 불일치하면(예: verifiable인데 attestation이 없음) 소비자는 더 낮은 등급을 실제 신뢰 등급으로 취급해야 합니다.
표준 상태
이 ERC는 현재 Draft 상태로, 아직 커뮤니티 논의와 수정을 거치는 중인 제안입니다. 필드 구성이나 검증 규칙이 최종 확정 전에 바뀔 수 있습니다.