ERC-8100 컨트랙트 상태 XML 표현 표준 (Representable Contract State)

Draft · 이름·메타데이터 · 2025-12-01 작성

스마트 컨트랙트가 자신의 상태를 가스 비용 없이 표준화된 XML 문서로 바꿀 수 있도록 하는 인터페이스와 바인딩 규칙을 정의합니다.

왜 필요한가

스마트 파생상품이나 토큰화 채권 같은 컨트랙트는 평가 오라클에 줄 입력값, 법적 조건, 정기 보고서처럼 사람이 읽고 기계가 해석할 수 있는 문서가 필요합니다. 지금은 이런 문서를 만들기 위해 프로젝트마다 자체 뷰 함수와 오프체인 변환 규칙을 따로 만듭니다. 그래서 컨트랙트 상태를 바꾸거나 업데이트할 때마다 개발자가 오프체인 XML·JSON·PDF 표현을 손으로 맞춰 동기화해야 하고 클라이언트도 각 프로젝트에 맞춘 전용 코드를 새로 짜야 합니다. 공통 규칙이 없으니 범용 렌더링·검증 도구를 재사용하기 어렵고 독립적인 감사나 상호운용도 그만큼 힘들어집니다.

구현해야 하는 것

심층 설명

기본 인터페이스와 확장

핵심 인터페이스 IXMLRepresentableState는 stateXmlTemplate() 하나만 요구합니다. 여기에 선택적으로 IRepresentableStateVersioned의 stateVersion()을 더하면 상태가 바뀔 때마다 증가하는 번호로 캐시 갱신 여부를 판단할 수 있고 IRepresentableStateHashed의 stateHash()를 더하면 외부에서 받은 표현의 무결성을 검증할 수 있습니다. 이 둘을 조합한 IXMLRepresentableStateVersioned, IXMLRepresentableStateHashed, IXMLRepresentableStateVersionedHashed 편의 인터페이스도 정의됩니다. 이 확장 인터페이스 중 하나라도 구현하면 IXMLRepresentableState 구현으로도 간주됩니다.

바인딩 문법: call과 selector

XML 요소에 evmstate 네임스페이스 속성을 붙이면 바인딩이 됩니다. 선호되는 방식은 evmstate:call에 notional()(uint256)처럼 함수명(입력타입)(출력타입) 형태의 서명을 적는 것으로, 렌더러가 keccak256으로 셀렉터를 계산해 호출합니다. 저수준 대안으로 evmstate:selector에 4바이트 셀렉터를 16진수로 직접 쓰고 evmstate:returns에 반환 타입을 명시할 수도 있습니다. 둘 다 있으면 call이 우선하고 selector는 오류로 취급될 수 있습니다. 핵심 프로파일에서는 반환 타입이 배열이 아닌 단일 ABI 타입이어야 하며 배열 타입은 오류로 처리됩니다.

단일/다중 바인딩과 타겟 지정

바인딩 값은 evmstate:target이 없으면 요소의 텍스트 내용에, target에 이름이 있으면 그 이름의 속성에 들어갑니다. 한 요소에 여러 값을 묶으려면 evmstate:calls, evmstate:formats, evmstate:scales, evmstate:targets처럼 복수형 속성에 세미콜론으로 구분한 목록을 씁니다. 각 목록은 위치별로 대응되며 예를 들어 targets의 첫 항목이 비어 있으면 텍스트에, 두 번째가 'currency'면 currency 속성에 값을 넣습니다. 배열 타입 반환값은 이 다중 바인딩 모드에서는 쓸 수 없습니다.

서식과 스케일 규칙

evmstate:format은 디코딩된 값을 문자열로 바꾸는 방식을 정합니다. 정수는 decimal(10진수, scale로 소수점 자리 조정), hex, iso8601-date, iso8601-datetime을 지원하고 address는 ERC-55 체크섬 16진수, bool은 true/false, bytes는 hex 또는 base64, string은 그대로의 UTF-8 텍스트로 표현합니다. scale이 S면 원시 정수값에 10의 -S승을 곱한 정확한 값을 소수점 S자리로 렌더링해야 합니다. 정의되지 않은 format을 만나면 오류로 처리하는 것이 권장됩니다.

배열 바인딩 프로파일(선택)

구현체가 선택적으로 지원할 수 있는 이 프로파일은 uint256[]나 tuple(...)[]처럼 배열을 반환하는 바인딩을 반복되는 자식 요소로 펼쳐 줍니다. evmstate:item-element로 지정한 이름을 가진 템플릿 행(row)을 배열 길이만큼 복제해 삽입하고 그 안의 각 요소에는 evmstate:item-field='k'로 튜플의 k번째 값 또는 스칼라 값(k=0)을 채웁니다. 중첩 배열은 지원하지 않으며 지원하지 않는 구현체는 item-element·item-field 사용 자체를 오류로 처리해야 합니다.

체인·블록 식별과 스냅샷 일관성

루트 요소에는 evmstate:chain-id, evmstate:contract-address, evmstate:block-number를 채워 이 표현이 어느 체인·컨트랙트·블록을 가리키는지 못박습니다. 렌더러가 각 바인딩을 'latest' 블록으로 따로 호출하면 블록 사이에 상태가 바뀌어 서로 다른 블록의 값이 섞일 수 있습니다. 이를 막기 위해 렌더러는 렌더링을 시작할 때 블록 번호 B 하나를 고정하고 템플릿 조회와 그 안의 모든 함수 호출을 전부 같은 B로 수행해야 합니다.

XML-완전성이라는 개념

어떤 컨트랙트가 XML-완전하다는 것은, 어느 블록에서 얻은 XML 표현만으로 그 컨트랙트의 이후 동작에 영향을 주는 모든 의미 있는 가변 상태를 재구성할 수 있다는 뜻입니다. 이는 EVM이 직접 강제할 수 없는 의미론적 속성이라, 작성자가 모든 영향력 있는 저장 변수를 바인딩하거나 공개된 알고리즘으로 바인딩된 값에서 유도 가능하게 해야 합니다. IXMLRepresentableStatePart로 제공하는 부분 템플릿은 완전성 주장 없이 상태의 일부 뷰만 보여줄 수 있습니다.

이벤트의 참조 URI와 현재 상태

이벤트가 상태 전체를 값으로 담아 로그에 기록하면 가스가 많이 들 수 있으므로, 이 ERC는 이벤트가 값 대신 참조를 담도록 권장합니다. 권장 형식은 evmstate://self/part/{partId}[?key=...]로, partId는 statePartXmlTemplate(partId)에 쓰는 것과 같은 uint256이고 self는 이벤트를 발생시킨 컨트랙트 자신을 가리킵니다. 이 방식으로 오프체인 소비자는 이벤트가 발생한 블록의 해당 부분 뷰를 찾아 렌더링할 수 있습니다. 이 제안은 현재 Draft 상태로, 세부 규칙이 아직 바뀌거나 중단될 수 있습니다.

쓸 때 주의할 점

ERC 원문 · ← ERCs