ERC-8100 Contract state XML representation standard (Representable Contract State)
Draft · Names & metadata · created 2025-12-01
Defines an interface and binding rules that let a smart contract convert its state into a standardized XML document without incurring gas costs.
Why it is needed
Contracts like smart derivatives or tokenized bonds need documents that are both human-readable and machine-interpretable, such as inputs for valuation oracles, legal terms, and periodic reports. Currently, each project builds its own view functions and off-chain conversion rules separately to produce such documents. This means that every time a contract's state changes or is updated, developers must manually synchronize the off-chain XML, JSON, or PDF representations, and clients must write new project-specific code each time. Without a common set of rules, it is difficult to reuse general-purpose rendering and validation tools, which in turn makes independent audits and interoperability that much harder.
What to implement
function stateXmlTemplate() external view returns (string memory);: Returns an XML template string containing bindings. An off-chain renderer fills the bindings in this template with actual values to produce the final XML.function stateVersion() external view returns (uint256);: Returns a version number that increments whenever state reflected in the representation changes, so a renderer can cheaply determine whether it needs to re-render.function stateHash() external view returns (bytes32);: Returns a hash of the state values used in the representation, so that XML received from outside can be verified against the actual on-chain state.function statePartXmlTemplate(uint256 partId) external view returns (string memory);: Returns an XML template that shows only a specific part of the state, such as a settlement context designated by partId.event SettlementRequested(address initiator, string tradeData, string lastSettlementData);: An example event that triggers settlement, used to contrast with an approach that embeds transaction and prior settlement data directly as values.
In depth
Core interface and extensions
The core interface IXMLRepresentableState requires only stateXmlTemplate(). Optionally adding stateVersion() from IRepresentableStateVersioned lets you determine whether a cache needs refreshing using a number that increments whenever state changes, and adding stateHash() from IRepresentableStateHashed lets you verify the integrity of a representation received from outside. Convenience interfaces combining the two are also defined: IXMLRepresentableStateVersioned, IXMLRepresentableStateHashed, and IXMLRepresentableStateVersionedHashed. Implementing any of these extension interfaces also counts as implementing IXMLRepresentableState.
Binding syntax: call and selector
Attaching an evmstate namespace attribute to an XML element makes it a binding. The preferred approach is to write a signature in the form functionName(inputTypes)(outputType), such as notional()(uint256), in evmstate:call; the renderer computes the selector with keccak256 and calls it. As a low-level alternative, you can write the 4-byte selector directly in hex in evmstate:selector and specify the return type in evmstate:returns. If both are present, call takes precedence and selector may be treated as an error. In the core profile, the return type must be a single ABI type, not an array; array types are treated as an error.
Single/multiple bindings and target specification
A binding value goes into the element's text content if evmstate:target is absent, or into the attribute named by target if target has a name. To bind multiple values to a single element, use the plural attributes evmstate:calls, evmstate:formats, evmstate:scales, and evmstate:targets with semicolon-separated lists. Each list corresponds positionally; for example, if the first entry in targets is empty, the value goes into the text, and if the second is 'currency', the value goes into the currency attribute. Array-typed return values cannot be used in this multiple-binding mode.
Formatting and scale rules
evmstate:format determines how a decoded value is converted to a string. For integers, decimal (base-10, with scale adjusting the decimal point), hex, iso8601-date, and iso8601-datetime are supported; address is represented as ERC-55 checksummed hex, bool as true/false, bytes as hex or base64, and string as plain UTF-8 text as-is. If scale is S, the raw integer value must be multiplied by 10 to the power of -S and the exact result rendered with S decimal places. It is recommended to treat an undefined format as an error.
Array binding profile (optional)
This optionally supportable profile expands bindings that return arrays, such as uint256[] or tuple(...)[], into repeated child elements. It duplicates and inserts a template row named by evmstate:item-element as many times as the array length, and fills each element within it using evmstate:item-field='k' with the k-th value of the tuple, or the scalar value itself when k=0. Nested arrays are not supported, and implementations that do not support this must treat any use of item-element or item-field as an error.
Chain and block identification and snapshot consistency
The root element fills in evmstate:chain-id, evmstate:contract-address, and evmstate:block-number to pin down which chain, contract, and block this representation refers to. If a renderer calls each binding separately against the 'latest' block, state can change between blocks and values from different blocks can end up mixed together. To prevent this, the renderer must fix a single block number B at the start of rendering and perform the template lookup and all function calls within it against that same B.
The concept of XML-completeness
A contract being XML-complete means that the XML representation obtained at a given block alone can reconstruct all meaningful mutable state that affects the contract's subsequent behavior. This is a semantic property that the EVM cannot enforce directly, so authors must bind every influential storage variable, or make it derivable from bound values via a published algorithm. A partial template provided via IXMLRepresentableStatePart may show only a partial view of state, without making a completeness claim.
Reference URIs for events and current state
Recording an event with the entire state embedded as values can be gas-expensive, so this ERC recommends that events carry a reference instead of values. The recommended format is evmstate://self/part/{partId}[?key=...], where partId is the same uint256 used in statePartXmlTemplate(partId), and self refers to the contract that emitted the event itself. This lets off-chain consumers locate and render the corresponding partial view at the block in which the event occurred. This proposal is currently in Draft status, and its details may still change or be discontinued.
Things to watch out for
- Non-deterministic view functions: Binding a view function that depends on non-deterministic environment variables like block.timestamp or on external calls can make the representation unstable even within the same block. It is recommended to bind only pure or effectively pure getters.
- Template size and complexity: If a template is large or has many bindings, eth_call costs grow and public RPC endpoints may time out. It is recommended to keep templates as small as possible and bindings to only what is necessary.
- False completeness claims: A malicious contract may claim to be XML-complete while actually omitting important state from its XML representation. Users and auditors should not trust the XML alone; they should also check the contract code and, if provided, the stateHash() value.
- Renderer correctness: The correctness of the final XML representation depends on the correctness of the off-chain renderer implementation, so independent implementations and testing are recommended.