For contract authors

interface IXMLRepresentableState {
    function stateXmlTemplate() external view returns (string memory);
}

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

import "./IRepresentableState.sol";

contract MinimalInstrument is IXMLRepresentableState {
    address public owner;
    uint256 public notional;
    string  public currency;
    uint256 public maturityDate;
    bool    public active;

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

    function stateXmlTemplate() external pure override returns (string memory) {
        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 */
                        " evmstate:targets=';currency'/>"
                    "<MaturityDate evmstate:call='maturityDate()(uint256)'"
                                  " evmstate:format='iso8601-date'/>"
                    "<Active evmstate:call='active()(bool)' evmstate:format='boolean'/>"
            "</Instrument>";
    }
}

interface IRepresentableStateVersioned {
    function stateVersion() external view returns (uint256);
}

interface IRepresentableStateHashed {
    function stateHash() external view returns (bytes32);
}

interface IXMLRepresentableStateVersionedHashed is IXMLRepresentableState, IRepresentableStateVersioned, IRepresentableStateHashed {}

uint256 private _stateVersion;

function update(... ) external {
    // mutate storage
    _stateVersion += 1;
}

function stateVersion() external view returns (uint256) {
    return _stateVersion;
}

function stateHash() external view returns (bytes32) {
    return keccak256(abi.encode(owner, notional, currency, maturityDate, active));
}

interface IXMLRepresentableStatePart {
    function statePartXmlTemplate(uint256 partId) external view returns (string memory);
}

interface IXMLRepresentableStateWithParts is IXMLRepresentableState, IXMLRepresentableStatePart {}

Renderer Implementation (off-chain)

Although concrete implementations may differ, any conforming renderer MUST:

1. Choose a block number B (e.g. by reading eth_getBlockByNumber("latest") and taking its number).
2. Call stateXmlTemplate() (or a statePartXmlTemplate) with blockTag = B.
3. Parse the XML and discover all binding elements (those with evmstate:* attributes).
4. For each binding, execute the corresponding eth_call with blockTag = B and decode the result according to the evmstate:* attributes (including the optional array profile).
5. Fill the context bindings on the root element:
   • evmstate:chain-id
   • evmstate:contract-address
   • evmstate:block-number
6. Optionally strip all evmstate:* attributes for downstream consumers.

Renderers MAY additionally:

• Use stateVersion() for caching (e.g. only re-render when the version increases).
• Recompute stateHash() from the values they used and compare it to the on-chain value.

A Java implementation (EvmXmlRenderer) in this project follows this algorithm. Instead of implementing your own renderer, consider opening a feature request via the issue tracker if you need additional functionality.

Usage of the Renderer - e.g. by an Off-Chain Oracle

1. The off-chain oracle fixes the contract address A on chain C and the desired block B. This may be the result of a corresponding event (see below).
2. The renderer produces the desired (complete or partial) XML representation at (C, A, B).
3. If the contract implements IRepresentableStateHashed, it obtains stateHash() at block B.
4. It signs a tuple like (C, A, B, stateHash, hash(xml)) off‑chain (e.g. with ECDSA).

This yields a compact, cryptographically anchored snapshot of the contract state.

To include the provided renderer, add a dependency on:

<dependency>
    <groupId>net.finmath</groupId>
    <artifactId>representable-contract-state</artifactId>
    <version>${project.version}</version>
</dependency>

In your application create an instance evmXmlRenderer of net.finmath.smartcontracts.representablestate.xml.EvmXmlRenderer with a given chain (rpcUrl):

EvmXmlRenderer evmXmlRenderer = new EvmXmlRenderer(rpcUrl);

Then obtain an XML rendering of the XML-complete or partial state via

String xml = evmXmlRenderer.render(contractAddress, blockNumber, partId);

where

• a null value for blockNumber will result in fetching the latest block, and
• a null value for partId will result in the XML-complete state (via stateXmlTemplate()), while any non-null partId will result in the partial state XML (via statePartXmlTemplate(partId)).

The interpretation of partId can be decided by the contract.

For convenience EvmXmlRenderer provides the following methods:

String render(String contractAddress);                                         // XML-complete state of given contract at latest block
String render(String contractAddress, BigInteger blockNumber);                 // XML-complete state of given contract at given block
String renderPart(String contractAddress, BigInteger partId);                  // XML of partial state for given partId at latest block
String renderPart(String contractAddress, BigInteger blockNumber, BigInteger partId); // XML of partial state for given partId at given block

Events “by reference” instead of “by value”

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

Summary

• IXMLRepresentableState exposes a canonical XML template; renderers turn it into a concrete XML representation at a fixed block.
• IRepresentableStateVersioned and IRepresentableStateHashed help with caching and integrity checks.
• IXMLRepresentableStatePart allows specialised partial views (e.g. settlement context).
• Events SHOULD typically carry references into representable state (via URIs) rather than large by‑value payloads.
• The XML binding schema, including the optional array profile, provides a compact, generic way to bind arbitrary contract state into XML, ready to be consumed by existing XML tooling.