Versioned extension

/**
 * @title XML Representable State (versioned) interface
 * @notice Adds a monotonically increasing state version. This optional extension allows
 *         off-chain tools to cheaply detect whether the XML-relevant state has changed.
 */
interface IXMLRepresentableStateVersioned is IXMLRepresentableState {
    /**
     * @notice Monotonically increasing version of the XML-relevant state.
     * @dev Implementations SHOULD increment this whenever any mutable state that participates
     *      in the XML 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 XML Representable State (hashed) interface
 * @notice Exposes a hash of a canonical state tuple used for the XML representation.
 *         This optional extension allows off-chain tools to verify integrity of an
 *         externally provided representation against on-chain state.
 */
interface IXMLRepresentableStateHashed is IXMLRepresentableState {
    /**
     * @notice Hash of the canonical state tuple used for the XML representation.
     * @dev Implementations MAY choose their own canonical encoding of state (e.g.,
     *      abi.encode of a tuple of all fields that are represented in the XML).
     *
     *      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 + hashed) convenience interface
 * @notice Convenience interface combining versioned and hashed extensions.
 */
interface IXMLRepresentableStateVersionedHashed is IXMLRepresentableStateVersioned, IXMLRepresentableStateHashed
{}

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

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.

The output type MUST be a single ABI type (e.g. uint256, int256, address, bool, string, etc.). Support for tuples and arrays is out of scope for this minimal ERC.

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" />

Multiple bindings per element

A single XML element can have one or more bindings associated with it.

• Single-binding attributes (no semicolons, exactly one binding):

  • evmstate:call
  • evmstate:selector
  • evmstate:returns
  • evmstate:format
  • evmstate:scale
  • evmstate:target

• Multi-binding attributes (semicolon-separated lists, interpreted positionally):

  • evmstate:calls
  • evmstate:selectors
  • evmstate:returnsList
  • evmstate:formats
  • evmstate:scales
  • evmstate:targets

When any of the plural attributes (evmstate:calls, evmstate:selectors, …) are present, the element is in multi-binding mode:

• Each list is split on ';', and each part is trimmed of leading and trailing whitespace.
• The lists are interpreted positionally. For index i:
  • calls[i] is the i-th function signature (optional).
  • selectors[i] is the i-th selector (optional).
  • returnsList[i] is the i-th explicit return type (optional).
  • formats[i] is the i-th format specifier (optional).
  • scales[i] is the i-th decimal scale (optional).
  • targets[i] is the i-th target specifier (optional).

Bindings are resolved in order i = 0..N-1, where N is the length of the evmstate:calls list. If both calls[i] and selectors[i] are empty for a given index, that index MUST be ignored. If a list is shorter than N, missing entries MUST be treated as empty strings.

For each binding index i, targets[i] determines whether the value is written to the element's text content or to an attribute:

• If targets[i] is empty or missing (after trimming), the renderer MUST replace the element's text content with the rendered value for that binding. If multiple bindings for the same element write text, they MUST be applied in index order; later writes overwrite earlier ones.

• If targets[i] is a non-empty string, the renderer MUST set (create or overwrite) an attribute on the element with that local name and the rendered value as its value. It MUST NOT change the element's text content because of this binding.

When only the singular attributes are present (no evmstate:calls/formats/…), the element is in single-binding mode, and the renderer MUST treat evmstate:call/selector/returns/format/scale/target as describing exactly one binding.

Example with a single binding to the element's text:

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

might render to:

<Notional>1000000.00</Notional>

Example with two bindings: the notional as element text and the currency as an attribute, using the multi-binding attributes:

<Amount
  evmstate:calls="notional()(uint256); currency()(string)"
  evmstate:formats="decimal; string"
  evmstate:scales="2; "
  evmstate:targets="; currency" />

MUST render to something equivalent to:

<Amount currency="EUR">1000000.00</Amount>

Formatting

The optional attribute evmstate:format describes how to convert the decoded ABI value into a text string. If evmstate:format is absent or empty, a type-specific default is used.

When evmstate:formats is used, each entry formats[i] applies to the i-th binding in multi-binding mode as described above. Similarly, when evmstate:scale or evmstate:scales are present, scale/scales[i] apply to the corresponding binding; a missing or empty entry is treated as scale 0.

Implementations of this ERC MUST support at least the following combinations:

• For unsigned integers (uint*) and signed integers (int*):

  • Default → same as "decimal".
  • "decimal" → base-10 representation, optionally with scaling as described below.
  • "hex" → lower-case hex with 0x prefix.
  • "iso8601-date" → interpret the integer as a UNIX timestamp in seconds since epoch and render a UTC calendar date in ISO 8601 form YYYY-MM-DD.
  • "iso8601-datetime" → interpret the integer as a UNIX timestamp in seconds since epoch and render a UTC timestamp in ISO 8601 form (e.g. 2025-01-02T00:00:00Z).

• For address:

  • Default same as "address".
  • "address" → hex with 0x prefix and ERC-55 checksum.

• For bool:

  • Default same as "boolean".
  • "boolean" → "true" or "false".

• For bytes and bytesN:

  • Default same as "hex".
  • "hex" → hex with 0x prefix.
  • "base64" → base64 representation.

• For string:

  • Default "string".
  • "string" → UTF-8 text as returned.

Implementations MAY support additional formats. If the renderer encounters an unknown evmstate:format, it SHOULD treat this as an error.

Optionally, evmstate:scale / evmstate:scales MAY be used for decimal-like integers:

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

This means that the raw integer is scaled by 10^(-scale) before rendering, e.g. 12345 with scale="2" becomes "123.45".

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 IXMLRepresentableStateVersioned, 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.

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

/**
 * @title XML Representable State (versioned) interface
 * @notice Adds a monotonically increasing state version. This optional extension allows
 *         off-chain tools to cheaply detect whether the XML-relevant state has changed.
 */
interface IXMLRepresentableStateVersioned is IXMLRepresentableState {
    /**
     * @notice Monotonically increasing version of the XML-relevant state.
     * @dev Implementations SHOULD increment this whenever any mutable state that participates
     *      in the XML 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 XML Representable State (hashed) interface
 * @notice Exposes a hash of a canonical state tuple used for the XML representation.
 *         This optional extension allows off-chain tools to verify integrity of an
 *         externally provided representation against on-chain state.
 */
interface IXMLRepresentableStateHashed is IXMLRepresentableState {
    /**
     * @notice Hash of the canonical state tuple used for the XML representation.
     * @dev Implementations MAY choose their own canonical encoding of state (e.g.,
     *      abi.encode of a tuple of all fields that are represented in the XML).
     *
     *      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 + hashed) convenience interface
 * @notice Convenience interface combining versioned and hashed extensions.
 */
interface IXMLRepresentableStateVersionedHashed is IXMLRepresentableStateVersioned, IXMLRepresentableStateHashed
{}

Example contract

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

import "./IXMLRepresentableState.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 IXMLRepresentableStateVersioned
    function stateVersion() external view override returns (uint256) {
        return _stateVersion;
    }

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