Home /Modules/advantage/trade_models.hpp

trade_models.hpp

advantage/trading/trade_models.hpp · 213 line(s) · c

// trade_models.hpp - C++ layer over the C trading models.
//
// Adds, on top of trade_models.h:
//   * Checked<T>: a result that is either a value or a human-readable error
//     (no exceptions, no sentinel numbers);
//   * the three models behind C++ signatures (std::vector for outcomes);
//   * the strategic trade-off table as data (AssetProfile);
//   * a bridge that records an evaluated trade as evidence in an
//     AdvantageStore, so `counsel` can rank trading approaches.
//
// Still pure and offline: nothing here fetches prices or places orders.
#ifndef ADVANTAGE_TRADE_MODELS_HPP
#define ADVANTAGE_TRADE_MODELS_HPP

#include <string>
#include <vector>

#include "../advantage_store.hpp"
#include "trade_models.h"

namespace advantage {
namespace trading {

// Either a value or an error message. Check ok before using value.
template <class T>
struct Checked {
    bool ok = false;
    T value{};
    std::string error;
};

namespace detail {
template <class T>
Checked<T> make(tm_status st, const T& v) {
    Checked<T> c;
    if (st == TM_OK) {
        c.ok = true;
        c.value = v;
    } else {
        c.error = tm_strerror(st);
    }
    return c;
}
}  // namespace detail

inline Checked<tm_result> arbitrage(const tm_arbitrage_in& in) {
    tm_result r{};
    return detail::make(tm_arbitrage(&in, &r), r);
}

inline Checked<double> arbitrageBreakeven(const tm_arbitrage_in& in) {
    double p = 0.0;
    return detail::make(tm_arbitrage_breakeven(&in, &p), p);
}

inline Checked<tm_result> marketMaking(const tm_marketmaking_in& in) {
    tm_result r{};
    return detail::make(tm_marketmaking(&in, &r), r);
}

struct Quote {
    double bid = 0.0;
    double ask = 0.0;
};

inline Checked<Quote> quote(double fairValue, double halfSpreadRate) {
    Quote q;
    return detail::make(tm_quote(fairValue, halfSpreadRate, &q.bid, &q.ask), q);
}

inline Checked<tm_result> refurbishment(const tm_refurb_in& in,
                                        const std::vector<tm_outcome>& outcomes) {
    tm_result r{};
    return detail::make(
        tm_refurbishment(&in, outcomes.data(), outcomes.size(), &r), r);
}

inline Checked<tm_result> regional(const tm_regional_in& in) {
    tm_result r{};
    return detail::make(tm_regional(&in, &r), r);
}

// Regional premium = sell/buy - 1 (0.05 = 5%).
inline Checked<double> regionalPremium(double buyPrice, double sellPrice) {
    double p = 0.0;
    return detail::make(tm_regional_premium(buyPrice, sellPrice, &p), p);
}

inline Checked<tm_result> aggregation(const tm_aggregation_in& in,
                                      const std::vector<double>& lotPrices) {
    tm_result r{};
    return detail::make(
        tm_aggregation(&in, lotPrices.data(), lotPrices.size(), &r), r);
}

// One candidate listing (see trade_models.h for the semantics).
inline Checked<tm_result> asymmetry(const tm_asymmetry_in& in) {
    tm_result r{};
    return detail::make(tm_asymmetry(&in, &r), r);
}

// Apparent discount = 1 - listed/estimated (0.6 = listed 60% below estimate).
inline Checked<double> mispricing(double listedPrice, double estimatedValue) {
    double d = 0.0;
    return detail::make(tm_mispricing(listedPrice, estimatedValue, &d), d);
}

inline Checked<tm_result> consignment(const tm_consignment_in& in) {
    tm_result r{};
    return detail::make(tm_consignment(&in, &r), r);
}

inline Checked<tm_result> distressed(const tm_distressed_in& in) {
    tm_result r{};
    return detail::make(tm_distressed(&in, &r), r);
}

// Sell-before-source. Assumes an honest, disclosed lead time (see the C header).
inline Checked<tm_result> virtualInventory(const tm_virtual_in& in) {
    tm_result r{};
    return detail::make(tm_virtual(&in, &r), r);
}

inline Checked<tm_result> synthetic(const tm_synthetic_in& in,
                                    const std::vector<tm_component>& outputs) {
    tm_result r{};
    return detail::make(tm_synthetic(&in, outputs.data(), outputs.size(), &r), r);
}

// exitPrices: {probability, exit price per unit} branches summing to 1.
inline Checked<tm_result> momentum(const tm_momentum_in& in,
                                   const std::vector<tm_outcome>& exitPrices) {
    tm_result r{};
    return detail::make(
        tm_momentum(&in, exitPrices.data(), exitPrices.size(), &r), r);
}

// Excess above baseline left after `days` given a half-life.
inline Checked<double> hypeDecay(double initialExcess, double halfLifeDays,
                                 double days) {
    double v = 0.0;
    return detail::make(tm_hype_decay(initialExcess, halfLifeDays, days, &v), v);
}

// Advantage of an evaluated trade after the opportunity cost of its capital.
inline Checked<double> advantageOf(const tm_result& r, double costOfCapital) {
    double a = 0.0;
    return detail::make(tm_advantage(&r, costOfCapital, &a), a);
}

// How an evaluated trade is expressed as evidence.
//   Absolute    : money units as evaluated. Fine within ONE approach, but a
//                 large trade then outweighs a small one.
//   PerUnitCost : divided by the trade's total cost, so reward and baseline
//                 are "per 1 unit of capital deployed". Use this to compare
//                 approaches of very different size (tokens vs furniture).
enum class Scale { Absolute, PerUnitCost };

// Record an evaluated trade as one <observation> on the source with `id`:
//   reward = expected proceeds, baseline = cost + opportunity cost of capital
// (both divided by total cost under Scale::PerUnitCost).
// Returns false and fills `error` if the source is absent, the rate is
// invalid, a per-unit scale is requested for a zero-cost trade, or the source
// is already at the observation limit. The store changes only on success.
bool addEvidence(AdvantageStore& store, const std::string& id,
                 const tm_result& r, double costOfCapital, std::string& error,
                 Scale scale = Scale::Absolute);

// ---- the strategic trade-offs, as data ------------------------------------

struct AssetProfile {
    const char* assetClass;      // "Crypto / Digital" or "Physical"
    const char* examples;
    const char* capitalNeeded;
    const char* liquidity;
    const char* executionSpeed;
    const char* majorRisks;
};

// The two rows of the cross-asset comparison. Descriptive, not numeric: use
// them to choose realistic inputs (hold_days, holding costs, fill odds).
const std::vector<AssetProfile>& profiles();

// ---- the comparison matrix for the four advanced models, as data -----------

struct ModelProfile {
    const char* model;
    const char* operationalLeverage;
    const char* scalability;
    const char* infrastructure;
    const char* primaryFriction;
};

// Descriptive, not numeric. The infrastructure column names what each model
// needs *conceptually*; this library supplies only the arithmetic, not the
// scrapers, OCR, inventory system or escrow platform.
const std::vector<ModelProfile>& advancedModelMatrix();

// The comparison matrix for the niche models (descriptive, not numeric).
struct NicheProfile {
    const char* model;
    const char* capitalEfficiency;
    const char* velocityOfCapital;
    const char* operationalFriction;
    const char* mainThreat;
};
const std::vector<NicheProfile>& nicheModelMatrix();

}  // namespace trading
}  // namespace advantage

#endif  // ADVANTAGE_TRADE_MODELS_HPP