ERC-8100 컨트랙트 상태 XML 표현 표준 (Representable Contract State)
Draft · 이름·메타데이터 · 2025-12-01 작성
스마트 컨트랙트가 자신의 상태를 가스 비용 없이 표준화된 XML 문서로 바꿀 수 있도록 하는 인터페이스와 바인딩 규칙을 정의합니다.
왜 필요한가
스마트 파생상품이나 토큰화 채권 같은 컨트랙트는 평가 오라클에 줄 입력값, 법적 조건, 정기 보고서처럼 사람이 읽고 기계가 해석할 수 있는 문서가 필요합니다. 지금은 이런 문서를 만들기 위해 프로젝트마다 자체 뷰 함수와 오프체인 변환 규칙을 따로 만듭니다. 그래서 컨트랙트 상태를 바꾸거나 업데이트할 때마다 개발자가 오프체인 XML·JSON·PDF 표현을 손으로 맞춰 동기화해야 하고 클라이언트도 각 프로젝트에 맞춘 전용 코드를 새로 짜야 합니다. 공통 규칙이 없으니 범용 렌더링·검증 도구를 재사용하기 어렵고 독립적인 감사나 상호운용도 그만큼 힘들어집니다.
구현해야 하는 것
function stateXmlTemplate() external view returns (string memory);: 바인딩이 담긴 XML 템플릿 문자열을 반환합니다. 오프체인 렌더러가 이 템플릿의 바인딩을 실제 값으로 채워 최종 XML을 만듭니다.function stateVersion() external view returns (uint256);: 표현에 반영되는 상태가 바뀔 때마다 증가하는 버전 번호를 반환해 렌더러가 다시 그릴 필요가 있는지 싸게 판단할 수 있게 합니다.function stateHash() external view returns (bytes32);: 표현에 쓰이는 상태 값들의 해시를 반환해 외부에서 받은 XML이 실제 온체인 상태와 일치하는지 검증할 수 있게 합니다.function statePartXmlTemplate(uint256 partId) external view returns (string memory);: partId로 지정한 정산 맥락 등 상태의 특정 부분만 보여주는 XML 템플릿을 반환합니다.event SettlementRequested(address initiator, string tradeData, string lastSettlementData);: 정산을 트리거하는 이벤트의 예시로, 거래·이전 정산 데이터를 값으로 직접 담는 방식과 대조해 설명하기 위해 쓰입니다.
심층 설명
기본 인터페이스와 확장
핵심 인터페이스 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 상태로, 세부 규칙이 아직 바뀌거나 중단될 수 있습니다.
쓸 때 주의할 점
- 비결정적 뷰 함수: block.timestamp처럼 비결정적인 환경 변수나 외부 호출에 의존하는 view 함수를 바인딩하면, 같은 블록이라도 표현이 안정적이지 않을 수 있습니다. 순수하거나 실질적으로 순수한 게터만 바인딩하는 것이 권장됩니다.
- 템플릿 크기와 복잡도: 템플릿이 크거나 바인딩 수가 많으면 eth_call 비용이 커지고 공개 RPC 엔드포인트에서 타임아웃이 날 수 있습니다. 템플릿은 가능한 작게, 바인딩은 필요한 만큼만 두는 것이 권장됩니다.
- 허위 완전성 주장: 악의적인 컨트랙트가 XML-완전하다고 주장하면서 실제로는 중요한 상태를 XML 표현에서 빠뜨릴 수 있습니다. 사용자와 감사자는 XML만 믿지 말고 컨트랙트 코드와, 제공된다면 stateHash() 값을 함께 확인해야 합니다.
- 렌더러 정확성: 최종 XML 표현의 정확성은 오프체인 렌더러 구현의 정확성에 달려 있으므로, 독립적인 구현과 테스트가 권장됩니다.