ERC-8100 - Representable Contract State

Created 2025-12-01
Status Draft
Category ERC
Type Standards Track
Authors
Requires

Interface and XML binding schema for contracts that expose a canonical representation of their state.

Abstract

This ERC introduces IXMLRepresentableState, a standard interface and XML binding schema that allows an EVM smart contract to define a static XML template with machine-readable bindings to its state and view functions. Off-chain renderers use this template to build a canonical XML representation of the contract's state at a specific block, without incurring any on-chain gas cost. In this ERC, "canonical" refers to the semantic content defined by the rendering rules; byte-for-byte identical XML output across renderers is not required.

This ERC defines the notion of an XML-complete contract (see Specification). Informally, an XML-complete contract exposes, via bindings in its XML template, all mutable state that the author considers semantically relevant for future behaviour at a given (chain-id, address, block-number).

Additionally, this ERC defines an optional interface IXMLRepresentableStatePart for contracts that expose one or more partial XML templates representing selected views of their state (for example, a settlement context), without changing the semantics of the canonical full representation.

Motivation

Smart contracts can efficiently orchestrate and process the life-cycle of a financial (derivative) product to an extent that they finally represent the financial product itself.

At the same time, many applications require a human-readable, machine-parseable representation of that product and its state: valuation oracles need inputs for settlements, smart bonds and other tokenized instruments need legal terms, term sheets or regulatory reports, and on-chain registries, governance modules or vaults benefit from a stable "document view" of their state.

In the traditional off-chain world, such needs are addressed by standards like FpML, the ISDA Common Domain Model, or the ICMA Bond Data Taxonomy. A common pattern is to treat an XML (or similar) document as the definitive source defining the financial product and then generate code to interact with the corresponding data. When a process modifies or updates properties of the product, developers must synchronize the smart contract's internal state with the off-chain XML representation. Today, each project typically invents its own set of view functions and off-chain conventions, so clients need bespoke code to map contract state into XML, JSON, or PDF. This makes interoperability, independent auditing, and reuse of tooling harder.

This ERC inverts that pattern by putting the smart contract at the centre. A contract declares that it implements IXMLRepresentableState and defines an interface of representable state. Off-chain renderers can then derive a canonical XML representation that reflects the semantically relevant state of the contract at a given (chain-id, address, block-number), using only eth_call and a standardized XML binding schema. Rendering happens entirely off-chain and does not change state, so there is no gas cost, yet the resulting XML remains cryptographically anchored to the chain.

Typical use cases include:

By standardizing the Solidity interface and the XML attribute schema, this ERC allows generic tools to consume any compliant contract without project-specific adapters, and to plug directly into existing XML-based workflows in finance and beyond.

Specification

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Terminology

Interface

The base interface is:

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

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).

Example: Settlement Data by Reference

Consider an external settlement process is triggered by the SettlementRequested event:

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

A straightforward interpretation of this event signature is that the full set of data required to perform a settlement is passed as part of the event parameters:

In many realistic deployments, large parts of tradeData and lastSettlementData are static or slowly changing. Logging such data in every settlement request can therefore lead to unnecessary gas consumption.

Contracts that implement both, the above event and a representable contract state interface (for example, an XML-based representation exposed via read-only functions) should treat settlement events as compact references to the on-chain state rather than as self-contained data blobs.

Reference URI Scheme

When events carry references into a representable contract state, those references SHOULD be expressed in a machine-readable URI format. This ERC does not mandate a single URI scheme, but defines a simple RECOMMENDED pattern that is sufficient for most use cases.

For events that refer to the same contract that emitted the event (the most common case), the chain, contract address, and block number are already known from the log context. A reference into the representable state only needs to identify:

This ERC RECOMMENDS the following minimal scheme for references to partial XML views:

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

where

Higher-level standards MAY define additional URI forms if they need to reference views on different contracts or chains (for example, evmstate://{chain-id}/{contract-address}/part/{partId}), but cross-contract references are intentionally out of scope for this ERC.

The partId used in the URI is always a uint256 and corresponds directly to the partId parameter of statePartXmlTemplate(uint256 partId). Standards that wish to define globally unique part identifiers MAY define their partId constants as uint256 values derived from a namespaced string, for example:

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

In that case the URI would still carry the numeric identifier, e.g.

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.

Event life cycle

XML Namespace

This ERC defines the XML namespace URI:

The XML template MUST declare this namespace, for example:

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

Bindings

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 the evmstate namespace.

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

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

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:

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

might render to:

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

might render to:

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

The renderer MUST create or overwrite the attribute with that name on the element. It MUST NOT change the element's text content in this case.

Bindings MUST NOT be attached directly to attributes (XML does not allow attributes on attributes); all evmstate:* attributes are always attached to elements.

Multiple Bindings per Element

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

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

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:

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.

For the array binding profile defined below, array-valued return types MUST NOT be used in multi-binding mode. Implementations that support the array binding profile MUST treat a binding in multi-binding mode whose declared output type is an array as an error. Array handling in this ERC is restricted to single-binding mode on the array container and to single-binding nodes inside the template row.

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

After rendering, the renderer MUST:

Example rendered output (illustrative):

<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:

Decimal Lexical Form and Numeric Equivalence

When rendering integer types with default / "decimal" formatting, the renderer MUST output a base-10 decimal string using:

If a binding specifies scale = S (where S is a non-negative integer), the rendered string MUST represent the exact numeric value raw * 10^(-S), where raw is the decoded ABI integer value.

The renderer MAY include any number of trailing zeros in the fractional part. Consuming tools MUST treat trailing zeros in the fractional part as insignificant. For example, 10, 10.0, and 10.00 all represent the same numeric value.

Renderers SHOULD emit exactly S digits after the decimal point when scale is present, to maximize compatibility with downstream XML schemas and tooling.

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

Optionally, an evmstate:scale / evmstate:scales attribute 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".

Array Binding Profile (optional, Mode B)

This section defines an optional array binding profile that implementations MAY support. It allows a binding whose output type is an array or array-of-tuples to be rendered as a sequence of repeated child elements. Other array-shaped representations (e.g., inline lists) are intentionally left to off-chain post-processing such as XSLT.

An implementation that supports this profile MUST implement the rules in this section. An implementation that does not support this profile MUST treat any use of evmstate:item-element or evmstate:item-field as an error.

Supported Array Output Types

The array binding profile supports bindings whose declared output type is one of:

Nested arrays (e.g. uint256[][], tuple(uint256[],uint256)[]) are out of scope for this profile. A renderer that implements this profile MUST treat such types as an error.

Array Containers and Template Rows

An XML element E is an array container if all of the following hold:

Within an array container E, the renderer MUST locate the template row as follows:

Before inserting any rendered rows, the renderer MUST remove the template row T* from the document. If rendering produces zero rows, E will have no child corresponding to the template.

The evmstate:item-element attribute is only meaningful on array containers and MUST NOT be used elsewhere.

Evaluation Semantics

Given chain-id C, contract address A, block-number B, and an array container E:

  1. Evaluate the array-valued binding of E at block B, using the normal function-binding rules, yielding a sequence items[0..N-1].

    • If the element type is scalar T, each items[i] is a scalar value.
    • If the element type is tuple(T0,...,Tn-1), each items[i] is decoded as a tuple (v0,...,v{n-1}).

  2. For each index i from 0 to N-1:

    • Deep-clone the template row T* (including its descendants and attributes) to a new element R.
    • Within R and its descendants, process any evmstate:item-field attributes as described below, using items[i] as the current row value.
    • Insert R as a child of E, after any previously inserted rows, preserving the original document order of other children of E.

  3. If N = 0, the renderer MUST remove T* and MUST NOT insert any rows derived from it.

Array-valued bindings MUST NOT be used in multi-binding mode (evmstate:calls, evmstate:selectors, etc.) in this profile.

Item-Field Bindings

Inside the subtree rooted at the template row T*, elements MAY carry an attribute:

evmstate:item-field="k"

where k is a non-negative integer index into the array element.

Let the ABI array element type be:

For a given row index i and a node X inside the cloned row R that has evmstate:item-field="k":

  1. Determine value = items[i].

  2. Determine the selected component v:

    • If the element type is scalar T, value is a single scalar. For this profile, it is treated as a tuple (v0) of length 1. The only valid index is k = 0. If k != 0, this is an error.

    • If the element type is a tuple tuple(T0,...,Tn-1), then value = (v0,...,v{n-1}). The index k MUST satisfy 0 <= k < n, and v = vk. Otherwise this is an error.

  3. Render v to a string using the existing scalar formatting rules on X (evmstate:format, evmstate:scale). If evmstate:format is absent on X, the default for the ABI type of v is used.

  4. Place the rendered string:

    • If X has an attribute evmstate:target="attrName", the renderer MUST set (create or overwrite) an attribute attrName on X with the rendered string as its value and MUST NOT change X’s text content because of this binding.

    • If X has no evmstate:target attribute, the renderer MUST replace the text content of X with the rendered string.

The evmstate:item-field attribute is only meaningful inside the subtree of a template row in an array container. Implementations SHOULD treat its use elsewhere as an error.

Within a node that carries evmstate:item-field, only single-binding mode is allowed. It MUST NOT be combined with the multi-binding attributes (evmstate:calls, evmstate:selectors, etc.) in this profile.

Example: Scalar Array

Consider a contract function:

function couponAmounts() external view returns (int256[] memory);

A template that renders each coupon amount as a separate element can be written as:

<Coupons
    xmlns:evmstate="urn:evm:state:1.0"
    evmstate:call="couponAmounts()(int256[])"
    evmstate:item-element="Coupon">

  <!-- Template row, cloned once per array element -->
  <Coupon
      evmstate:item-field="0"
      evmstate:format="decimal"
      evmstate:scale="2" />
</Coupons>

If the function returns three amounts, the rendered XML might be:

<Coupons>
  <Coupon>1000000.00</Coupon>
  <Coupon>1000000.00</Coupon>
  <Coupon>1000000.00</Coupon>
</Coupons>
Example: Array of Tuples (payment schedule)

Consider a contract function:

struct Cashflow {
    int256 amount;      // 18-decimal
    uint256 payDate;    // unix timestamp
}

function cashflows() external view returns (Cashflow[] memory);

ABI return type is tuple(int256,uint256)[]. A template that renders a payment schedule can be written as:

<PaymentSchedule
    xmlns:evmstate="urn:evm:state:1.0"
    evmstate:call="cashflows()(tuple(int256,uint256)[])"
    evmstate:item-element="Payment">

  <!-- Template row, cloned once per cashflow -->
  <Payment>
    <PaymentDate
        evmstate:item-field="1"
        evmstate:format="iso8601-date" />
    <Amount
        evmstate:item-field="0"
        evmstate:format="decimal"
        evmstate:scale="2" />
  </Payment>

</PaymentSchedule>

The rendered XML might be:

<PaymentSchedule>
  <Payment>
    <PaymentDate>2026-01-02</PaymentDate>
    <Amount>1000000.00</Amount>
  </Payment>
  <Payment>
    <PaymentDate>2026-04-02</PaymentDate>
    <Amount>1000000.00</Amount>
  </Payment>
  <!-- ... -->
</PaymentSchedule>

More complex document shapes (e.g. inline lists, grouped summaries) can be derived from this repeated-element representation using standard XML transformation tools such as XSLT, and are intentionally out of scope for this array profile.

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:

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:

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

After rendering, the root element in the final XML might look like:

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

The renderer SHOULD set these attributes in the evmstate namespace (e.g. evmstate:chain-id, evmstate:contract-address, evmstate:block-number) to avoid collisions with existing attributes defined by the business XML schema. Implementations MAY additionally provide non-namespaced duplicates if required by downstream tooling.

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 above 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:

In practice, contracts MAY also expose a separate "state descriptor" view function that lists all bound fields, but this is out of scope for this minimal ERC.

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

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.

Rationale

When a contract also exposes a representable contract state (e.g. via IXMLRepresentableState and/or IXMLRepresentableStatePart), events can be treated primarily as triggers and can 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.

Backwards Compatibility

This ERC is purely additive:

Contracts and renderers that do not implement the array binding profile remain fully compliant with the core profile of this ERC; they simply treat array-valued bindings and the corresponding attributes as errors.

Contracts and tools that do not support IXMLRepresentableStatePart remain fully compliant with this ERC; they simply ignore the optional partial state extension.

Reference Implementation

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

Security Considerations

Copyright

Copyright and related rights waived via CC0.