Versioned Extension

/**
 * @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);
}

Hashed Extension

/**
 * @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);
}

Combined Convenience Extension

/**
 * @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 {}

A contract that implements any of these extended interfaces is also considered an implementation of IXMLRepresentableState.

Partial XML State Views (optional)

Some applications benefit from specialised views of the contract state (for example, a settlement context for a smart derivative contract) without needing to process the full XML representation.

To support such use cases, this ERC defines an optional interface that allows contracts to expose one or more partial XML templates keyed by an application-defined identifier:

/**
 * @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.
 *
 *      Implementations of this interface alone are NOT required to be XML-complete:
 *      a contract may expose only partial views of its state without providing a
 *      canonical full XML representation via IXMLRepresentableState.
 */
interface IXMLRepresentableStatePart {
    /**
     * @notice Returns the XML template string for a particular partial state view.
     * @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.
     *
     * @param partId Contract-specific identifier of the partial view.
     */
    function statePartXmlTemplate(uint256 partId) external view returns (string memory);
}

Contracts that implement both IXMLRepresentableState and IXMLRepresentableStatePart may optionally declare a convenience interface:

/**
 * @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 {}

Higher-level standards MAY reserve specific partId values for well-known views. Implementations that define their own partId mapping SHOULD document it in their contract documentation or off-chain specification.

Representable Contract State referenced in Events

Events MAY carry compact references into a contract’s representable state. When they do, references SHOULD be expressed in a machine-readable URI format (see “Reference URI Scheme” below).

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

evmstate://self/part/{partId}[?key={application-specific-key}]

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

evmstate://self/part/281092189917326349...

Informative Sequence Diagram

The following figure illustrates a typical event-triggered rendering flow. This figure is informative and does not introduce additional requirements beyond this specification.

XInclude namespace

Templates that use this profile MUST declare the XInclude namespace:

• Namespace URI: http://www.w3.org/2001/XInclude
• Recommended prefix: xi

Example:

<Contract xmlns="urn:example:instrument"
          xmlns:evmstate="urn:evm:state:1.0"
          xmlns:xi="http://www.w3.org/2001/XInclude">
  ...
</Contract>

Include element and required attributes

A template MAY contain one or more xi:include elements.

For this profile, each xi:include element MUST satisfy all of the following:

• It MUST have an href attribute whose value is an absolute URI.
• It MUST have an evmstate:integrity attribute.
• It MUST NOT have an xpointer attribute (fragment selection is out of scope for this profile).
• If a parse attribute is present, its value MUST be xml or application/xml. Text inclusion is out of scope.

The evmstate:integrity attribute is reserved by this ERC for use on xi:include elements only, and MUST NOT be interpreted as an evmstate binding.

Integrity format

For this profile, renderers MUST support integrity values of the form:

keccak256-0x{64hex}

where {64hex} is exactly 64 hexadecimal digits (case-insensitive), representing a 32-byte digest.

The digest is the EVM/Solidity keccak256 of the fetched resource content bytes (the octet sequence obtained from dereferencing href).

Renderers MAY support additional algorithms in the future, but MUST treat unknown algorithms as an error.

Processing model

Template includes MUST be resolved before evaluating any evmstate bindings.

Given a template document T, the renderer MUST produce an expanded template T' by processing includes as follows:

1. Locate xi:include elements in document order.
2. For each xi:include element I:
   1. Dereference the URI in I/@href and obtain an octet sequence content.
   2. Compute keccak256(content) and compare it to the digest in I/@evmstate:integrity. If the digest does not match, the renderer MUST treat this as an error.
   3. Parse content as XML and obtain its document element E. The included resource MUST be a well-formed XML document with exactly one document element. If parsing fails, the renderer MUST treat this as an error.
   4. Replace the xi:include element I in the template with a deep clone of E (including attributes and descendants).
3. If any included document contains further xi:include elements, the renderer MUST process them recursively using the same rules until no xi:include elements remain.
4. The renderer MUST detect inclusion loops (direct or indirect) and MUST treat them as an error.

After all xi:include elements have been replaced successfully, the renderer proceeds with normal evaluation of evmstate bindings on the expanded template.

Example

<Instrument xmlns="urn:example:instrument"
            xmlns:evmstate="urn:evm:state:1.0"
            xmlns:xi="http://www.w3.org/2001/XInclude"
            evmstate:chain-id=""
            evmstate:contract-address=""
            evmstate:block-number="">

  <xi:include href="ipfs://bafy.../instrument-template.xml"
              evmstate:integrity="keccak256-0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" />

</Instrument>

Function Binding

To bind an element or attribute to a contract view function, the template MUST use either:

1. Signature form (preferred)

<Notional
        evmstate:call="notional()(uint256)"
        evmstate:format="decimal" />

• evmstate:call is a Solidity function signature string of the form functionName(inputTypes...)(outputTypes...), with no spaces.
• The renderer MUST:
  • Compute the function selector as keccak256("notional()")[0:4].
  • Use the declared output type (uint256) to decode the return data.

1. Selector form (low-level)

<Notional
        evmstate:selector="0x70a08231"
        evmstate:returns="uint256"
        evmstate:format="decimal" />

• evmstate:selector is a 4-byte hex selector as a string with a 0x prefix.
• evmstate:returns is an ABI type string describing the return type.
• The renderer MUST call the contract using the provided selector and decode using the given type.

If both evmstate:call and evmstate:selector are present, the renderer MUST prefer evmstate:call and MAY treat evmstate:selector as an error.

For the core profile of this ERC, the output type of a binding MUST be a single, non-array ABI type (e.g. uint256, int256, address, bool, string, etc.). Implementations MAY additionally support the optional array binding profile defined in this specification, which allows array and array-of-tuple return types to be used as inputs for repeated XML elements. An implementation that does not support the array binding profile MUST treat any binding whose declared output type is an array (e.g. uint256[], tuple(uint256,uint256)[]) as an error.

Target Location (single binding)

A single binding can either target the element's text content or one of its attributes:

• If evmstate:target is absent or empty, the renderer MUST replace the element's text content with the rendered value.

<Notional evmstate:call="notional()(uint256)"
          evmstate:format="decimal"
          evmstate:scale="2" />

<Notional>1000000.00</Notional>

<Party evmstate:call="partyALEI()(string)"
       evmstate:target="id" />

<Party id="LEI-of-Party-A" />

Problem

If a renderer naively uses eth_call with blockTag = "latest" for each individual 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.

Required Behaviour for Renderers

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.

Race Conditions

There would be a race condition if bindings were evaluated against moving "latest" state. This specification resolves it by requiring all calls to be evaluated against a single fixed block-number B. Optional on-chain state version counters can be used for additional checks, but are not required for snapshot consistency.

IRepresentableState.sol

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

/**
 * @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.19;

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));
    }
}