Add ERC: Representable Contract State

[cfries]

This proposal specifies a minimal interface IXMLRepresentableState that lets an EVM contract expose a canonical
representation of its state via an XML (or JSON) template with machine-readable bindings to its state and view functions.
Off-chain renderers use only eth_call at a specific block to materialize that representation.

Note: The corresponding interface IJSONRepresentableState ist part of the ERC, however the binding scheme is currently focussing on XML bindings.

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 document representing the contract's state at a specific block, without incurring any on-chain gas cost.

A contract that claims to implement IXMLRepresentableState MUST be XML-complete: every piece of mutable state that the author considers semantically relevant MUST be represented in the XML via bindings, so that the rendered XML is a complete representation of the contract at a given (chain-id, address, block-number).

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

• Smart derivative contracts that must present their current state to a valuation oracle or settlement engine.
• Smart bonds and other tokenized financial instruments that must generate legal terms, term sheets, or regulatory and supervisory reports.
• On-chain registries, governance modules, and vaults that want a reproducible, auditable document-style snapshot of their state.

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 sketch (informal)

Very briefly, beyond the header/abstract/motivation above, the ERC specifies:

• A minimal interface IXMLRepresentableState with xmlTemplate() returning a UTF‑8 XML document.
• Optional extensions:
  • IRepresentableStateVersioned with stateVersion() (monotonically increasing version of the representable state).
  • IRepresentableStateHashed with stateHash() (hash of a canonical state tuple for the representation).
  • Convenience combinations for XML: IXMLRepresentableStateVersioned, IXMLRepresentableStateHashed, IXMLRepresentableStateVersionedHashed.
• A binding schema in the evmstate namespace, with attributes like:
  • single-binding attributes (no semicolons, exactly one binding):
    • evmstate:call / evmstate:selector / evmstate:returns
    • evmstate:format / evmstate:scale
    • evmstate:target (element text vs. attribute target)
  • multi-binding attributes (semicolon-separated lists, interpreted positionally):
    • evmstate:calls / evmstate:selectors / evmstate:returnsList
    • evmstate:formats / evmstate:scales / evmstate:targets

A renderer:

• fetches xmlTemplate() at a fixed block tag B,
• walks the XML, resolves each evmstate:* binding via eth_call at blockTag=B,
• writes values into element text or attributes (single- or multi-binding mode),
• and fills the context attributes (evmstate:chain-id, evmstate:contract-address, evmstate:block-number).

Snapshot consistency is guaranteed by always using the same block B for all calls.

---

Reference implementation / demos

We have a small set of demo contracts and a Java-based reference renderer (Web3j + DOM XML), including:

• MinimalInstrument – owner, notional, currency, maturity, active flag.
• TestContract – exercises many type/format combinations (uint/int, hex, decimal+scale, iso8601 date/datetime, bytes as hex/base64, etc.) including a multi-binding example.
• InterestRateSwapSettleToMarket – IRS with settle-to-market semantics and lastSettlement{time,value}.
• BondDataTaxonomyDemo – ICMA BDT-inspired bond (issuer, ISIN, coupon, dates, etc.) rendered via evmstate bindings.

Project Homepage: http://finmath.gitlab.io/representable-contract-state

[eip-review-bot]

✅ All reviewers have approved.

[cfries]

Hi @SamWilsn — sorry for the ping. I believe I’ve addressed all of your comments.
The only open question is whether to keep package.json; I left it in for now, as in ERC-7573 and ERC-6123, because it helps with interface versioning while the ERC is in draft.

[cfries]

Hi @SamWilsn — just gently following up here.
I believe the review comments have been addressed. Is there anything else needed from my side before this can be merged / moved to Draft? I’d like to reference ERC-8100 from another ERC, so a merge to draft would be very helpful. Thanks!

[SamWilsn]

These are pretty minor, please fix them at your leisure.

[SamWilsn]

These may be common abbreviations in a specific domain, but not to general Ethereum developers.

[SamWilsn]

Small aside, but might be worth reserving this scheme if it's important.

[SamWilsn]

Suggested change

	#### Example with a Single Binding to the Element's Text:
	#### Example with a Single Binding to the Element's Text

[eip-review-bot]

All Reviewers Have Approved; Performing Automatic Merge...