ORE Trading Instrument Support — Complete Implementation

• swap_instrument_mapper — Swap, CrossCurrencySwap, InflationSwap, FRA, CapFloor, Swaption, CallableSwap, FlexiSwap, BalanceGuaranteedSwap
• fx_instrument_mapper — FxForward, FxSwap, FxOption
• bond_instrument_mapper — Bond, ForwardBond, CallableBond, ConvertibleBond

xml_ir_mapper_roundtrip_tests.cpp, xml_swaption_mapper_roundtrip_tests.cpp, xml_fx_mapper_roundtrip_tests.cpp, xml_bond_mapper_roundtrip_tests.cpp

All SQL tables, C++ domain types, NATS messaging protocol, service layer, and NATS handlers for: instruments/swap_legs, fx_instruments, bond_instruments, credit_instruments, equity_instruments, commodity_instruments, composite_instruments/composite_legs, scripted_instruments.

Wire the three existing mappers (swap, FX, bond) into import_portfolio_with_context() so instruments are persisted during import. No new mappers are written; this is purely an enabling change.

instrument.id must equal trade.id (same UUID) so the database can join them. Set this immediately after map_instrument() returns.

Rather than multiple std::optional fields and a growing if/else chain, the import pipeline uses a single std::variant field and a unified dispatch method.

Type alias (declared in trade_mapper.hpp, starts with three families; each subsequent phase adds one arm):

using instrument_mapping_result = std::variant<
    std::monostate,          // unmapped (exotic/scripted/unknown at this phase)
    swap_mapping_result,
    fx_mapping_result,
    bond_mapping_result
    // Phases 2–9 extend: credit_mapping_result, equity_mapping_result, ...
>;

New method on trade_mapper:

static instrument_mapping_result map_instrument(const trade& v);

Implementation delegates to the existing per-family methods — four lines:

instrument_mapping_result trade_mapper::map_instrument(const trade& v) {
    if (auto r = map_swap_instrument(v))  return *r;
    if (auto r = map_fx_instrument(v))    return *r;
    if (auto r = map_bond_instrument(v))  return *r;
    return std::monostate{};
}

projects/ores.ore/include/ores.ore/domain/trade_mapper.hpp — add the instrument_mapping_result typedef and map_instrument() declaration.

projects/ores.ore/src/domain/trade_mapper.cpp — implement map_instrument() as above (three delegating lines).

projects/ores.ore/include/ores.ore/xml/importer.hpp — replace any legacy optional instrument fields with a single field:

instrument_mapping_result instrument;  ///< monostate until resolved

projects/ores.ore/src/xml/importer.cpp — in the trade loop inside import_portfolio_with_context(), after setting item.trade, one call:

item.instrument = domain::trade_mapper::map_instrument(t);
// Patch the instrument id — visitors below need it set before any persist.
std::visit(overloaded{
    [](std::monostate) {},
    [&](auto& r) { r.instrument.id = item.trade.id; }
}, item.instrument);

Consumers (services, Qt import dialog) use std::visit with an exhaustive visitor:

std::visit(overloaded{
    [](std::monostate)          { /* not yet mapped */ },
    [&](swap_mapping_result& r) { /* persist swap instrument + legs */ },
    [&](fx_mapping_result& r)   { /* persist fx instrument */ },
    [&](bond_mapping_result& r) { /* persist bond instrument */ },
}, item.instrument);

Each subsequent phase adds exactly two changes:

1. Append the new family type to the instrument_mapping_result variant.
2. Add one line to map_instrument(): if (auto r = map_X_instrument(v)) return *r;.

The importer.hpp and importer.cpp files are not modified again after Phase 1. std::visit call-sites get a new arm for the new variant member.

Extend existing xml_trade_import_tests.cpp: load a known swap portfolio file, assert std::holds_alternative<swap_mapping_result>(item.instrument) and std::get<swap_mapping_result>(item.instrument).instrument.id = item.trade.id=.

• trade_type_code, reference_entity (CreditCurveId or IssuerId)
• currency, notional — from first LegData
• spread — FixedLegData.Rates.Rate (running premium)
• start_date, maturity_date, day_count_code, payment_frequency_code
• index_name, index_series, seniority, restructuring — IndexCDS
• option_type, option_expiry_date, option_strike — CDSOption
• linked_asset_code — CreditLinkedSwap
• tranche_attachment, tranche_detachment — SyntheticCDO

projects/ores.ore/include/ores.ore/domain/credit_instrument_mapper.hpp
projects/ores.ore/src/domain/credit_instrument_mapper.cpp
projects/ores.ore/tests/xml_credit_mapper_roundtrip_tests.cpp

• trade_mapper.hpp — add include + map_credit_instrument() declaration; append credit_mapping_result to instrument_mapping_result variant
• trade_mapper.cpp — implement map_credit_instrument() dispatch; add if (auto r = map_credit_instrument(v)) return *r; to map_instrument()

• Credit_Default_Swap.xml — assert trade_type_code = "CreditDefaultSwap", =reference_entity non-empty, spread > 0; reverse → CreditDefaultSwapData populated
• Credit_Index_Credit_Default_Swap.xml — assert index_name non-empty
• Credit_Index_CDS_Option.xml — assert option_expiry_date non-empty, option_strike.has_value()
• Credit_Synthetic_CDO_refdata.xml — assert tranche_attachment.has_value()

Extend the existing bond_instrument_mapper with two new method pairs. The bond_instrument table already has option_type, option_expiry_date, option_strike, trs_return_type, trs_funding_leg_code columns.

TRS routing rule: if TotalReturnSwapData underlying trade type = =Bond → bond_instrument_mapper::forward_bond_trs(); all other TRS → Phase 8 composite.

Base bond fields + option_type, option_expiry_date, option_strike

Base bond fields + trs_return_type, trs_funding_leg_code

• bond_instrument_mapper.hpp — add forward_bond_option, forward_bond_trs, two reverse methods
• bond_instrument_mapper.cpp — implement the four methods
• trade_mapper.cpp — add BondOption and bond-underlying TotalReturnSwap branches to map_bond_instrument()

projects/ores.ore/tests/xml_bond_option_mapper_roundtrip_tests.cpp

Tags [ore][xml][mapper][roundtrip][bond]:

• Credit_BondOption.xml — assert trade_type_code = "BondOption", =option_type = "Call", =option_strike.has_value(); reverse → BondOptionData populated
• Credit_Bond_TRS.xml — assert trade_type_code = "TotalReturnSwap", =trs_funding_leg_code non-empty

• Common: trade_type_code, underlying_code, currency, notional, quantity, start_date, maturity_date
• Options: option_type, strike_price, exercise_type
• Barriers: barrier_type, lower_barrier, upper_barrier
• Asian: average_type, averaging_start_date
• Variance: variance_strike
• Swaps: return_type, day_count_code, payment_frequency_code
• Outperformance: basket_json (two underlyings as JSON array)

projects/ores.ore/include/ores.ore/domain/equity_instrument_mapper.hpp
projects/ores.ore/src/domain/equity_instrument_mapper.cpp
projects/ores.ore/tests/xml_equity_mapper_roundtrip_tests.cpp

• trade_mapper.hpp — add include + map_equity_instrument() declaration; append equity_mapping_result to instrument_mapping_result variant
• trade_mapper.cpp — implement map_equity_instrument() dispatch; add if (auto r = map_equity_instrument(v)) return *r; to map_instrument()

• Equity_Option_European.xml — assert underlying_code non-empty, option_type = "Call", =strike_price > 0; reverse → EquityOptionData populated
• Equity_Forward.xml — assert trade_type_code = "EquityForward"=
• Equity_Swap.xml — assert return_type non-empty
• Equity_Barrier_Option.xml — assert barrier_type non-empty
• Equity_Asian_Option.xml — assert average_type non-empty
• Equity_Variance_Swap.xml — assert variance_strike > 0
• Equity_OutperformanceOption.xml — assert basket_json parses to array of size 2

Extend equity_instrument_mapper with four exotic types using accumulation_amount, cliquet_frequency_code, and basket_json.

• Accumulator/TaRF: accumulation_amount, knock_out_barrier, option_type, strike_price
• Cliquet: cliquet_frequency_code, option_type, lower_barrier, upper_barrier
• Worst-of basket: basket_json (JSON array of underlyings)

• equity_instrument_mapper.hpp — add 4 forward + 4 reverse method pairs
• equity_instrument_mapper.cpp — implement
• trade_mapper.cpp — add 4 new dispatch branches

• Exotic_EquityAccumulator_single_name.xml — assert accumulation_amount > 0, knock_out_barrier > 0
• Exotic_EquityTaRF.xml — assert accumulation_amount > 0
• Exotic_Equity_Cliquet_Option.xml — assert cliquet_frequency_code non-empty
• Exotic_EquityWorstOfBasketSwap.xml — assert basket_json parses to valid array

Extend fx_instrument_mapper with barrier/exotic FX trade types. The fx_instrument table already has barrier_type, lower_barrier, upper_barrier columns.

Note: confirm fx_instrument domain type has barrier_type, lower_barrier, upper_barrier fields before implementing; add them if missing.

• fx_instrument_mapper.hpp — add ~10 new forward/reverse method pairs
• fx_instrument_mapper.cpp — implement
• trade_mapper.cpp — extend map_fx_instrument() with all new type branches

projects/ores.ore/tests/xml_fx_exotic_mapper_roundtrip_tests.cpp

Tags [ore][xml][mapper][roundtrip][fx][exotic]:

• FX_Barrier_Option.xml — assert barrier_type non-empty, bought_currency non-empty; reverse → FxBarrierOptionData populated
• FX_Digital_Option.xml — assert trade_type_code = "FxDigitalOption"=
• FX_OneTouch_option.xml — assert trade_type_code = "FxTouchOption"=
• FX_Variance_Swap.xml — assert trade_type_code = "FxVarianceSwap"=

• Common: trade_type_code, commodity_code, currency, quantity, unit, start_date, maturity_date
• Forward: fixed_price
• Option: option_type, exercise_type, strike_price
• Option strip: strip_frequency_code
• APO: average_type, averaging_start_date, averaging_end_date
• Variance: variance_strike
• Swaption: swaption_expiry_date
• Swap: day_count_code, payment_frequency_code

projects/ores.ore/include/ores.ore/domain/commodity_instrument_mapper.hpp
projects/ores.ore/src/domain/commodity_instrument_mapper.cpp
projects/ores.ore/tests/xml_commodity_mapper_roundtrip_tests.cpp

• trade_mapper.hpp — add include + map_commodity_instrument() declaration; append commodity_mapping_result to instrument_mapping_result variant
• trade_mapper.cpp — implement map_commodity_instrument() dispatch; add if (auto r = map_commodity_instrument(v)) return *r; to map_instrument()

• Commodity_Forward.xml — assert commodity_code non-empty, fixed_price.has_value(); reverse → CommodityForwardData populated
• Commodity_Option.xml — assert option_type non-empty, strike_price.has_value()
• Commodity_APO_NYMEX_CL.xml — assert average_type non-empty, averaging_start_date non-empty
• Commodity_Variance_Swap.xml — assert variance_strike.has_value()
• Commodity_Swaption_NYMEX_NG.xml — assert swaption_expiry_date non-empty

Implement composite_instrument_mapper for CompositeTrade, TotalReturnSwap with non-bond underlyings, and ContractForDifference. Constituent trade IDs are stored in composite_leg records.

Note: Hybrid_GenericTRS_with_Bond.xml and pure bond TRS go through Phase 3 (bond_instrument_mapper::forward_bond_trs()). TRS routing in map_composite_instrument(): if underlying is a single Bond trade → delegate to map_bond_instrument(); otherwise dispatch here.

composite_instrument: trade_type_code, description (empty), audit fields.

composite_leg (one per constituent): instrument_id, leg_sequence (1-based), constituent_trade_id — component's ORE id string; if anonymous inline component, store the component TradeType string as fallback.

projects/ores.ore/include/ores.ore/domain/composite_instrument_mapper.hpp
projects/ores.ore/src/domain/composite_instrument_mapper.cpp
projects/ores.ore/tests/xml_hybrid_mapper_roundtrip_tests.cpp

• trade_mapper.hpp — add include + map_composite_instrument() declaration; append composite_mapping_result to instrument_mapping_result variant
• trade_mapper.cpp — implement map_composite_instrument() dispatch (with TRS routing logic); add if (auto r = map_composite_instrument(v)) return *r; to map_instrument()

• Hybrid_CompositeTrade.xml — assert trade_type_code = "CompositeTrade", =legs.size() = 2=, legs[0].leg_sequence = 1=; reverse → CompositeTradeData has 2 components
• Hybrid_GenericTRS_with_EquityPosition.xml — assert trade_type_code = "TotalReturnSwap", =legs.size() > 1=
• Hybrid_CFD.xml — assert trade_type_code = "ContractForDifference"=

Implement scripted_instrument_mapper for all ScriptedTrade variants and named script product types. The domain stores script_name, events_json, underlyings_json, and parameters_json as opaque JSON to avoid modelling every script's schema.

ORE scripted trades have two representations:

1. Named sugar syntax (e.g. AsianBasketOptionData) — infer script_name from the element tag (strip Data suffix).
2. Explicit ScriptedTradeData — read ScriptName directly.

Serialise events as events_json ([{"name":"Expiry","value":"2025-08-31"}]), underlyings as underlyings_json (["EQ-RIC:.SPX","EQ-RIC:.STOXX50E"]), and parameters as parameters_json ({"Strike":5000.0,"Notional":1.0}). Use nlohmann/json (already in vcpkg).

• trade_type_code, script_name, script_body (if inline; empty if library)
• events_json, underlyings_json, parameters_json
• Standard audit fields

projects/ores.ore/include/ores.ore/domain/scripted_instrument_mapper.hpp
projects/ores.ore/src/domain/scripted_instrument_mapper.cpp
projects/ores.ore/tests/xml_scripted_mapper_roundtrip_tests.cpp

• trade_mapper.hpp — add include + map_scripted_instrument() declaration; append scripted_mapping_result to instrument_mapping_result variant
• trade_mapper.cpp — implement map_scripted_instrument() (all ScriptedTrade variants → forward_scripted_trade(); DoubleDigitalOption, PerformanceOption_01 → forward_named_scripted_trade()); add if (auto r = map_scripted_instrument(v)) return *r; to map_instrument()

• Scripted_BasketOption.xml — assert script_name = "AsianBasketOption", =underlyings_json parses to array of size 2, events_json non-empty; reverse → AsianBasketOptionData or ScriptedTradeData populated
• Exotic_Double_Digital_Option.xml — assert trade_type_code = "DoubleDigitalOption", =underlyings_json non-empty
• Exotic_PerformanceOption_01_FX.xml — assert script_name = "PerformanceOption_01"=

Both ores.ore/src/CMakeLists.txt and ores.ore/tests/CMakeLists.txt use file(GLOB_RECURSE ...). New .cpp files are picked up automatically.

Every mapper .cpp should have a make_base() helper setting modified_by = "ores", performed_by = "ores", change_reason_code = "system.external_data_import", change_commentary = "Imported from ORE XML". Copy from fx_instrument_mapper.cpp.

Use nlohmann/json for basket_json, events_json, underlyings_json, parameters_json. Keep serialisation in a private helper in the .cpp only.

[ores.ore] Add <asset class> instrument mapper and Thing 3 tests