Demo Overview

DemoICMABondTextResource deploys a smart contract that represents a bond's state and stores three associated resources in on-chain TextResource contracts: one ICMA Bond Data Taxonomy product-terms template that renders the bond's state in ICMA BDT format, and two XSLT stylesheets that transform the resulting XML into a legal document and a term sheet.

It then simulates the bond's lifecycle through three state transitions: assigning the interest rate, assigning the ISIN and WKN, and assigning a security-token address. For each checkpoint, the demo outputs six block-pinned renderer URLs: two for the XML template at different XInclude-expansion stages, one for the canonical ICMA BDT XML, one for an HTML legal document, and two for the same HTML term sheet.

The six views demonstrate:

1. the XML template with XIncludes preserved;
2. the expanded XML template with XIncludes resolved recursively and evmstate bindings still unresolved;
3. the canonical rendered XML;
4. a legal document produced by an inline XSLT selected from an XML text node;
5. a term sheet produced by an XSLT loaded directly from a web3:// URL; and
6. the same term sheet after its web3:// URL is discovered through XPath.

These views are generated from the contract state using static templates. The contract remains the source of truth for the financial product's state and controls its transitions.

The contracts, issuer, identifiers, and documents are fictional and intended solely for this technical demonstration.

If you prefer not to run the demo, scroll down to inspect screenshots of the results.

Required Installations

You need:

• Java 21 and JBang;
• Foundry (for Anvil and the default Forge compiler backend);
• curl; and
• a Bash-compatible shell such as macOS/Linux Bash or Windows Git Bash.

The alternative --compiler=solc mode additionally requires a compatible standalone solc executable on PATH; version 0.8.24 is recommended.

For installation guidance, see the setup page.

The commands below use Anvil's public development accounts. Never use those accounts or private keys on a public network or with real assets.

Open three terminals. Terminals 1 and 2 may start in any directory. Start Terminal 3 in the parent directory where you want the icma-bond-demo working directory to be created.

Prepare the Demo Sources Once

JBang downloads the Java application, XML, and XSLT resources from Maven Central. By default, the demo compiles its Solidity contracts with Forge at runtime, so download the small version-matched source set directly, as in the Try It examples:

DEMO_VERSION=2.4.1
DEMO_TAG="representable-contract-state-parent-${DEMO_VERSION}"
DEMO_WORK_DIR="$PWD/icma-bond-demo"

PROJECT_BASE_URL="https://gitlab.com/finmath/representable-contract-state/-/raw/${DEMO_TAG}/representable-contract-state-web/src/main/solidity"

PROJECT_FILES=$'IRepresentableState.sol
resources/ITextResource.sol
resources/TextResource.sol
examples/Web3Include/BondDataTaxonomyDemoTextResource.sol'

while IFS= read -r SOURCE_FILE; do
  curl --create-dirs -fsSL \
    "$PROJECT_BASE_URL/$SOURCE_FILE" \
    -o "$DEMO_WORK_DIR/src/main/solidity/$SOURCE_FILE"
done <<< "$PROJECT_FILES"

OPENZEPPELIN_BASE_URL="https://raw.githubusercontent.com/OpenZeppelin/openzeppelin-contracts/v5.1.0/contracts"

OPENZEPPELIN_FILES=$'utils/Strings.sol
utils/Panic.sol
utils/introspection/IERC165.sol
utils/math/Math.sol
utils/math/SignedMath.sol
utils/math/SafeCast.sol'

while IFS= read -r SOURCE_FILE; do
  curl --create-dirs -fsSL \
    "$OPENZEPPELIN_BASE_URL/$SOURCE_FILE" \
    -o "$DEMO_WORK_DIR/src/main/solidity/node_modules/@openzeppelin/contracts/$SOURCE_FILE"
done <<< "$OPENZEPPELIN_FILES"

curl --create-dirs -fsSL \
  "https://raw.githubusercontent.com/Vectorized/solady/v0.1.26/src/utils/SSTORE2.sol" \
  -o "$DEMO_WORK_DIR/src/main/solidity/node_modules/solady/src/utils/SSTORE2.sol"

printf 'Demo prepared in %s\n' "$DEMO_WORK_DIR"

The OpenZeppelin and Solady files are pinned to the versions used by release 2.4.1. The directory is named node_modules because that is the Solidity import layout expected by the released demo; Node.js and npm are not used. Forge downloads and caches the pinned Solidity 0.8.24 compiler on the first run, so no standalone solc installation is required for the default mode.

On later runs, you may skip the preparation block. Open Terminal 3 in the same parent directory; the run block below reconstructs the default working-directory path.

Run the Demo

Change to the directory created during preparation. The default expression also restores the path during a later run in a new Terminal 3 session:

DEMO_WORK_DIR="${DEMO_WORK_DIR:-$PWD/icma-bond-demo}"
cd "$DEMO_WORK_DIR"

Then run the demo main class through Spring Boot's PropertiesLauncher:

jbang --java 21 \
  -Dloader.main=net.finmath.smartcontracts.representablestate.demo.DemoICMABondTextResource \
  --main=org.springframework.boot.loader.launch.PropertiesLauncher \
  net.finmath:representable-contract-state-web:2.4.1

Forge is selected when no compiler option is supplied. To use the standalone Solidity compiler instead, append --compiler=solc after the Maven artifact:

jbang --java 21 \
  -Dloader.main=net.finmath.smartcontracts.representablestate.demo.DemoICMABondTextResource \
  --main=org.springframework.boot.loader.launch.PropertiesLauncher \
  net.finmath:representable-contract-state-web:2.4.1 \
  --compiler=solc

You can also select the default explicitly with --compiler=forge.

The working directory matters because the demo compiles the downloaded Solidity sources at runtime.

The demo compiles and deploys the Solidity contracts with the selected backend, uploads and finalizes the three text resources, performs three lifecycle updates, verifies every rendered checkpoint, and finally prints the browser URLs.

1. XML Template with XIncludes Preserved

The first URL uses /xml/template with resolve=none. It returns the exact XML template supplied by the bond contract. The product-terms and legal-document resources remain as two <xi:include> elements, and no evmstate bindings are evaluated. The term-sheet stylesheet remains a separate web3:// resource reference.

2. XML Template with XIncludes Resolved

The second URL uses /xml/template with resolve=xinclude. The renderer recursively expands both XIncludes, embedding the ICMA product-terms XML and the legal-document XSLT text. The product terms' evmstate:call, formatting, and scale attributes remain visible and unevaluated. The term-sheet stylesheet continues to be represented by its web3:// reference.

3. Canonical XML

The third URL uses the /xml endpoint. It shows the canonical contract-state rendering before optional post-processing:

• the resolved ICMA product-terms document;
• values read from the bond contract at the URL's block number;
• the legal-documentation XSLT included as text in <ProductDocumentationTemplate>; and
• <ProductDocumentationTermSheetTemplate> with an href referencing the term-sheet XSLT's on-chain web3:// resource.

Compare the four block-pinned canonical XML links to see the initially empty <InterestRate>, its resolution from the contract's interestRate() EVM call, the later identifiers, and finally the token address and ISSUED status.

4. Legal Document via Inline XPath

The fourth URL uses /xml/transform with an xpath: stylesheet specification. The XPath selects the XSLT text stored in <ProductDocumentationTemplate>.

The browser displays a condensed, lawyer-style HTML document with:

• a formal cover and important notices;
• contractual particulars and instrument conditions;
• DLT, settlement, and risk schedules;
• every ICMA leaf field, including fields that are not populated; and
• chain, block, and source-contract provenance.

5. Term Sheet via Direct web3:// URL

The fifth URL also uses /xml/transform, but its xslt parameter is the term-sheet resource's canonical web3:// URL. The renderer loads the stylesheet from the finalized on-chain TextResource and displays a concise indicative HTML term sheet.

6. Term Sheet via XPath URL Indirection

The sixth URL uses an xpath-uri: stylesheet specification. The renderer first selects the href attribute of <ProductDocumentationTermSheetTemplate>, obtains the web3:// URL from that attribute, and then loads the stylesheet.

The fifth and sixth URLs should display identical term sheets. They demonstrate the two supported ways to address the same external XSLT: supplying its URL directly or discovering that URL in the rendered XML.

XML Template Resolution Stages

The two template views are identical across Parts 0–3 because the resource addresses and finalized resource contents are immutable, while the evmstate bindings remain unevaluated. The screenshots therefore show one shared block-pinned pair.

Part 0 — Initial Draft

The bond has just been deployed. Its status is NOT_ISSUED; the interest rate, derived first interest payment amount, identifiers, and security-token address are not yet populated.

Part 1 — Interest Rate Assigned

The first transition sets the contract's fixed rate to 2.5000%. The derived first interest payment amount becomes EUR 12,500,000.00, while the status remains NOT_ISSUED.

Part 2 — ISIN and WKN Assigned

The second transition adds ISIN DE000A4DEMO1 and WKN A4DEMO. The coupon remains 2.5000%, and assigning identifiers alone does not change the NOT_ISSUED status.

Part 3 — Security-Token Address Assigned

The final transition assigns the security-token address. That transaction changes the contract status to ISSUED; the rate, derived first interest payment amount, ISIN, and WKN remain populated.