Terminology

• XML template: A well-formed XML document, returned as a UTF-8 string by the contract, that contains placeholder bindings in the evmstate namespace.
• Binding: An evmstate:* attribute on an XML element that instructs a renderer to fetch a value from the contract (or from chain context) and insert it into the document.
• XML representation: The final XML document obtained by evaluating all bindings of the XML template against the contract at a specific (chain-id, address, block-number) and then removing all evmstate:* attributes.
• XML-complete contract: A contract that implements IXMLRepresentableState and whose XML representation encodes all semantically relevant mutable state. Informally, if two contracts are bytecode-identical and their XML representations agree at some block, their externally observable behaviour MUST be the same from that block onward.
• Partial XML template: A well-formed XML document returned by statePartXmlTemplate(partId) on a contract implementing IXMLRepresentableStatePart. It uses the same evmstate bindings as the full template but is intended to represent only a selected view or projection of the contract state.
• Partial XML view: The XML document obtained by rendering a partial XML template against a contract at a specific (chain-id, address, block-number). Partial XML views are not required to be XML-complete and MAY omit state that is present in the full XML representation.

Interface

The base interface is:

// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.23;

/**
 * @title XML Representable State interface
 * @notice Contracts implementing this interface expose an XML template that can be rendered
 *         into a canonical XML representation of the contract state at a given block.
 * @dev The XML binding schema and version are defined inside the XML itself (e.g. via
 *      namespaces or attributes). Snapshot consistency is achieved off-chain by evaluating
 *      all view calls against a single fixed block.
 */
interface IXMLRepresentableState {
    /**
     * @notice Returns the XML template string, using a dedicated namespace for bindings.
     * @dev MUST return a well-formed XML 1.0 (or 1.1) document in UTF-8 encoding.
     *      Implementations SHOULD make this string independent of mutable contract state
     *      and environment variables, i.e., effectively constant.
     */
    function stateXmlTemplate() external view returns (string memory);
}

For contracts that want stronger off-chain tooling support (caching and integrity checks), optional extended interfaces are defined.

/**
 * @title Representable State (versioned) interface
 * @notice Adds a monotonically increasing version of the representable state. This optional
 *         extension allows off-chain tools to cheaply detect whether the representation-relevant
 *         state has changed.
 */
interface IRepresentableStateVersioned {
    /**
     * @notice Monotonically increasing version of the representable state.
     * @dev Implementations SHOULD increment this whenever any mutable state that participates
     *      in the representation changes. It MAY start at 0.
     *
     *      Off-chain tools MAY use this to:
     *        - cache rendered XML and skip recomputation if the version is unchanged;
     *        - provide a simple ordering of state changes.
     */
    function stateVersion() external view returns (uint256);
}

/**
 * @title Representable State (hashed) interface
 * @notice Exposes a hash of a canonical state tuple used for the representation.
 *         This optional extension allows off-chain tools to verify integrity of an
 *         externally provided representation against on-chain state.
 */
interface IRepresentableStateHashed {
    /**
     * @notice Hash of the canonical state tuple used for the representation.
     * @dev Implementations MAY choose their own canonical encoding of state (e.g.,
     *      abi.encode of a tuple of all fields that are represented).
     *
     *      This function is intended for off-chain integrity checks, for example:
     *        - parties can sign (chainId, contract, blockNumber, stateHash);
     *        - renderers can recompute the same hash from the values they used.
     *
     *      It is RECOMMENDED that stateHash() is implemented as a pure/view
     *      function that computes the hash on the fly, instead of storing it in
     *      contract storage and updating it on every change.
     */
    function stateHash() external view returns (bytes32);
}

/**
 * @title XML Representable State (versioned) interface
 * @notice Convenience interface combining XML template and versioned state.
 */
interface IXMLRepresentableStateVersioned is IXMLRepresentableState, IRepresentableStateVersioned {}

/**
 * @title XML Representable State (hashed) interface
 * @notice Convenience interface combining XML template and hashed state.
 */
interface IXMLRepresentableStateHashed is IXMLRepresentableState, IRepresentableStateHashed {}

/**
 * @title XML Representable State (versioned + hashed) convenience interface
 * @notice Convenience interface combining XML template and versioned/hashed state.
 */
interface IXMLRepresentableStateVersionedHashed is IXMLRepresentableState, IRepresentableStateVersioned, IRepresentableStateHashed {}

/**
 * @title XML Representable State (partial) interface
 * @notice Optional extension exposing partial XML templates for selected views of the state.
 * @dev The meaning of partId is contract-specific or defined by higher-level standards
 *      (e.g. "settlement context" for an ERC-6123 implementation). Implementations of this
 *      interface alone are NOT required to be XML-complete.
 */
interface IXMLRepresentableStatePart {
    /**
     * @notice Returns the XML template string for a particular partial state view.
     * @param partId Contract-specific identifier of the partial view.
     * @dev MUST return a well-formed XML 1.0 (or 1.1) document in UTF-8 encoding and MUST
     *      follow the same binding rules as `stateXmlTemplate()`.
     */
    function statePartXmlTemplate(uint256 partId) external view returns (string memory);
}

/**
 * @title XML Representable State (full + parts) interface
 * @notice Convenience interface for contracts that provide a canonical full representation
 *         and one or more partial views.
 */
interface IXMLRepresentableStateWithParts is IXMLRepresentableState, IXMLRepresentableStatePart {}

XML Namespace and Bindings (overview)

This ERC defines the XML namespace URI

• Namespace URI: urn:evm:state:1.0
• Recommended prefix: evmstate

The XML template MUST declare this namespace, for example:

<Contract xmlns="urn:example:instrument"
          xmlns:evmstate="urn:evm:state:1.0">
    ...
</Contract>

Bindings are expressed as attributes in the evmstate namespace on XML elements. A binding element is any XML element that has one or more attributes in that namespace.

At a high level:

• evmstate:call and evmstate:selector bind an element to a contract view function (signature form or raw selector).
• evmstate:target (or the pluralised evmstate:targets in multi-binding mode) routes a value either into the element’s text content or into a named attribute.
• evmstate:format / evmstate:scale (and their plural forms) control string formatting and decimal scaling.
• The optional array binding profile uses
  • evmstate:item-element on an array container, and
  • evmstate:item-field on nodes inside the template row, to render arrays (and arrays of tuples) as repeated child elements.

The detailed rules for function binding, single vs. multi-binding mode, formatting, the array binding profile, and chain/contract identification are specified on the separate “XML Namespace and Bindings” page.

Chain and contract identification

The XML representation MUST identify the chain, contract, and block that it represents.

This ERC reserves the following attributes in the evmstate namespace on the root element:

• evmstate:chain-id
• evmstate:contract-address
• evmstate:block-number

Example root element in the template:

<Contract xmlns="urn:example:instrument"
          xmlns:evmstate="urn:evm:state:1.0"
          evmstate:chain-id=""
          evmstate:contract-address=""
          evmstate:block-number="">
    ...
</Contract>

These attributes are context bindings:

• The renderer MUST set evmstate:chain-id to the chain ID (e.g. [EIP-155] chain IDs), as a base-10 string.
• The renderer MUST set evmstate:contract-address to the contract address, as a checksummed hex address.
• The renderer MUST set evmstate:block-number to the block number at which the representation was evaluated, as a base-10 string.

These fields are filled based on the RPC context (chain id, contract address, and block tag) and do not correspond to actual contract calls.

XML representation and XML-complete contracts

For a given chain-id C, contract address A, and block-number B, and for a contract that implements IXMLRepresentableState, the XML representation at (C, A, B) is defined as follows:

1. Choose a JSON-RPC provider for chain C.
2. Call eth_getBlockByNumber (or equivalent) to obtain block B and its number, or use an externally provided B.
3. Perform all eth_call invocations (for stateXmlTemplate() and for all bound functions) with blockTag = B.
4. Start from the XML template returned by stateXmlTemplate().
5. Resolve all bindings as specified (including the optional array profile, if supported by the renderer) and insert the resolved values.
6. Fill evmstate:chain-id, evmstate:contract-address, and evmstate:block-number on the root element.
7. Optionally remove all evmstate:* attributes from the document.

A contract is XML-complete if, for every block B at which its code matches this ERC’s interface, the following holds:

Given the XML representation at (C, A, B), one can reconstruct all semantically relevant mutable state that influences the contract’s future behaviour (up to isomorphism).

This is a semantic property that cannot be enforced by the EVM itself, but it can be audited and tested. Authors of contracts that claim to implement IXMLRepresentableState MUST ensure that:

• Every mutable storage variable that influences behaviour is either:
  • directly bound via an evmstate:call / evmstate:selector, or
  • deterministically derivable from bound values via a public algorithm.
• Adding new mutable state requires adding corresponding bindings to the template.

Contracts that implement IXMLRepresentableStatePart MAY define additional partial XML templates via statePartXmlTemplate(partId). Rendering of such partial templates follows the same binding rules and snapshot semantics as stateXmlTemplate(), but no XML-completeness claim is made for any individual partId. When a contract also implements IXMLRepresentableState and claims to be XML-complete, the XML representation defined above remains the canonical representation; partial views SHOULD be consistent with it and MUST NOT contradict the state that would be observed via the full representation.

Race conditions and consistent snapshots

If a renderer naively uses eth_call with blockTag = "latest" for each binding, state may change between calls when new blocks are mined. In that case, different bindings might see different blocks, and the resulting XML would not correspond to a single consistent contract state.

To avoid this race condition, renderers MUST:

1. Determine a single block-number B at the start of rendering, e.g. by calling eth_getBlockByNumber("latest").
2. Use blockTag = B for:
   • the call to stateXmlTemplate(), and
   • all subsequent function calls required by the bindings inside the template.

Under normal node behaviour, this guarantees that all view calls see the same state snapshot.

If the contract implements IRepresentableStateVersioned, the renderer MAY additionally use stateVersion() for caching or sanity checks, but the basic snapshot algorithm using a fixed blockTag is mandatory for all conforming renderers.

Representable Contract State referenced in Events

Emitting events is an on-chain operation that MUST be paid for by the transaction sender. If an event is intended to trigger external processing of a contract’s state, it is tempting to publish all required information as event arguments. However, logging large portions of static or slowly changing data can be expensive.

When a contract also exposes a representable contract state (e.g. via IXMLRepresentableState and/or IXMLRepresentableStatePart), it is natural to treat events primarily as triggers and to use them to carry compact references into that representable state instead of full by-value snapshots.

In other words, the event transports state by reference rather than by value: the event payload contains just enough information for an off-chain consumer to locate and render the relevant view of the contract state at the block in which the event was emitted.

event SettlementRequested(address initiator, string tradeData, string lastSettlementData);

evmstate://self/part/<partId>[?key=<application-specific-key>]

lastSettlementData = "evmstate://self/part/1?key=2026-01-02";

uint256 constant XML_PART_SETTLEMENT_CTX =
    uint256(keccak256("ERC-6123:XML:SETTLEMENT-CONTEXT:v1"));

evmstate://self/part/8224939103947...

Illustration: Contract event state by reference

The following sequence diagram illustrates the concept of fetching contract event state by reference.

IRepresentableState.sol

// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.23;

/**
 * @title XML Representable State interface
 * @notice Contracts implementing this interface expose an XML template that can be rendered
 *         into a canonical XML representation of the contract state at a given block.
 * @dev The XML binding schema and version are defined inside the XML itself (e.g., via
 *      namespaces or attributes). Snapshot consistency is achieved off-chain by evaluating
 *      all view calls against a single fixed block.
 */
interface IXMLRepresentableState {
    function stateXmlTemplate() external view returns (string memory);
}

/**
 * @title Representable State (versioned) interface
 * @notice Adds a monotonically increasing version of the representable state.
 */
interface IRepresentableStateVersioned {
    function stateVersion() external view returns (uint256);
}

/**
 * @title Representable State (hashed) interface
 * @notice Exposes a hash of a canonical state tuple used for the representation.
 */
interface IRepresentableStateHashed {
    function stateHash() external view returns (bytes32);
}

/**
 * @title XML Representable State (versioned) interface
 * @notice Convenience interface combining XML template and versioned state.
 */
interface IXMLRepresentableStateVersioned is IXMLRepresentableState, IRepresentableStateVersioned {}

/**
 * @title XML Representable State (hashed) interface
 * @notice Convenience interface combining XML template and hashed state.
 */
interface IXMLRepresentableStateHashed is IXMLRepresentableState, IRepresentableStateHashed {}

/**
 * @title XML Representable State (versioned + hashed) convenience interface
 * @notice Convenience interface combining XML template and versioned/hashed state.
 */
interface IXMLRepresentableStateVersionedHashed is
    IXMLRepresentableState,
    IRepresentableStateVersioned,
    IRepresentableStateHashed
{}

Example contract

// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.23;

import "./IRepresentableState.sol";

/**
 * @title Example XML-representable contract
 * @notice Simple "instrument" with state fields owner, notional, currency, maturity, and active flag and
 *         an XML representation of its internal state using the generic IXMLRepresentableState
 *         schema.
 */
contract MinimalInstrument is IXMLRepresentableStateVersionedHashed {
    address public owner;

    uint256 public notional;
    string  public currency;
    uint256 public maturityDate;
    bool    public active;

    uint256 private _stateVersion;

    event Updated(address indexed updater, uint256 newNotional, uint256 newMaturity, bool newActive);

    constructor(address _owner, uint256 _notional, uint256 _maturityDate) {
        owner = _owner;
        notional = _notional;
        currency = "EUR";
        maturityDate = _maturityDate;
        active = true;
        _stateVersion = 1;
    }

    function update(uint256 _notional, uint256 _maturityDate, bool _active) external {
        require(msg.sender == owner, "not owner");
        notional = _notional;
        maturityDate = _maturityDate;
        active = _active;
        _stateVersion += 1;
        emit Updated(msg.sender, _notional, _maturityDate, _active);
    }

    /// @inheritdoc IXMLRepresentableState
    function stateXmlTemplate() external pure override returns (string memory) {
        // Notional as text, currency as attribute via multi-binding attributes.
        return
            "<Instrument xmlns='urn:example:instrument'"
                " xmlns:evmstate='urn:evm:state:1.0'"
                " evmstate:chain-id=''"
                " evmstate:contract-address=''"
                " evmstate:block-number=''>"
                    "<Owner evmstate:call='owner()(address)' evmstate:format='address'/>"
                    "<Notional"
                        " evmstate:calls='notional()(uint256);currency()(string)'"
                        " evmstate:formats='decimal;string'"
                        " evmstate:scales='2;'"       // 2 decimals for notional, no scaling for currency
                        " evmstate:targets=';currency'/>"
                    "<MaturityDate evmstate:call='maturityDate()(uint256)' evmstate:format='iso8601-date'/>"
                    "<Active evmstate:call='active()(bool)' evmstate:format='boolean'/>"
            "</Instrument>";
    }

    /// @inheritdoc IRepresentableStateVersioned
    function stateVersion() external view override returns (uint256) {
        return _stateVersion;
    }

    /// @inheritdoc IRepresentableStateHashed
    function stateHash() external view override returns (bytes32) {
        // Canonical encoding of the state relevant to the XML representation.
        return keccak256(abi.encode(owner, notional, currency, maturityDate, active));
    }
}