Home /Modules/advantage/trade_models.h

trade_models.h

advantage/trading/trade_models.h · 375 line(s) · c

/*
 * trade_models.h - Three cross-asset trading models, as pure C math.
 *
 *   1. Arbitrage      : same asset, two venues, price gap (DEX->CEX, or
 *                       regional listing -> premium relist).
 *   2. Market making  : be the instant buyer and seller; earn the spread,
 *                       bear the risk of inventory that does not turn over.
 *   3. Refurbishment  : buy raw/distressed, improve, sell into a higher tier;
 *                       the result is a distribution of outcomes, not one.
 *
 * The models are asset-agnostic: a token and a mid-century dresser differ only
 * in the numbers (fees, holding cost, days held, fill probability).
 *
 * Every function is PURE: no I/O, no network, no clock, no global state. It
 * does not fetch prices and it does not place orders. Callers supply quotes
 * (from wherever they legitimately obtain them) and receive an evaluation.
 *
 * Care taken (fail closed):
 *   - every input must be finite and inside a stated range, else an error
 *     status is returned and the output struct is left untouched;
 *   - amounts are capped at TM_MAX_AMOUNT so products cannot overflow;
 *   - results are re-checked for finiteness before being returned.
 *
 * Models that involve chance (loss, completion, winning a race, a sale
 * happening) report EXPECTED values: total_cost and expected_proceeds are
 * probability-weighted, so a single real trade will land above or below them.
 *
 * Costs are modelled explicitly so a "profitable-looking" spread that fees,
 * slippage, storage and time would consume is reported honestly as a loss.
 *
 * This is arithmetic, not financial advice. Outputs are only as good as the
 * inputs.
 */
#ifndef ADVANTAGE_TRADE_MODELS_H
#define ADVANTAGE_TRADE_MODELS_H

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

#define TM_MAX_AMOUNT 1e12     /* cap on prices, quantities and cost totals */
#define TM_MAX_OUTCOMES 16     /* cap on refurbishment outcome branches     */
#define TM_MAX_LOTS 256        /* cap on items in one aggregation           */
#define TM_MAX_COMPONENTS 64   /* cap on parts in one synthetic bundle      */
#define TM_PROB_TOLERANCE 1e-6 /* outcome probabilities must sum to 1 +/- this */
#define TM_MAX_HOLD_DAYS 36500.0

typedef enum {
    TM_OK = 0,
    TM_ERR_ARG = -1,   /* NULL pointer or count out of range              */
    TM_ERR_RANGE = -2, /* a value is non-finite or outside its valid range */
    TM_ERR_PROB = -3,  /* outcome probabilities do not form a distribution */
    TM_ERR_OVERFLOW = -4 /* a computed result was not finite              */
} tm_status;

/* Common evaluation result (all three models). Money units are the caller's. */
typedef struct {
    double total_cost;        /* everything paid: purchase, fees, slippage,
                                 fixed and holding costs                     */
    double expected_proceeds; /* what is expected back, net of selling costs */
    double expected_profit;   /* expected_proceeds - total_cost              */
    double return_on_cost;    /* expected_profit / total_cost (0 if no cost) */
    double hold_days;         /* time capital is tied up                     */
} tm_result;

/* ---- 1. Arbitrage ------------------------------------------------------ */
typedef struct {
    double buy_price;           /* per unit, venue A                     (> 0) */
    double sell_price;          /* per unit, venue B                     (> 0) */
    double quantity;            /* units                                 (> 0) */
    double buy_fee_rate;        /* fraction of buy notional          [0, 1)    */
    double sell_fee_rate;       /* fraction of sell notional         [0, 1)    */
    double slippage_rate;       /* adverse fraction, applied per leg [0, 1)    */
    double fixed_costs;         /* gas / shipping / transfer, total      (>= 0) */
    double holding_cost_per_day;/* storage etc., total per day           (>= 0) */
    double hold_days;           /* days capital is tied up      [0, MAX_HOLD]  */
} tm_arbitrage_in;

tm_status tm_arbitrage(const tm_arbitrage_in *in, tm_result *out);

/* Lowest sell price per unit at which the arbitrage breaks even. */
tm_status tm_arbitrage_breakeven(const tm_arbitrage_in *in, double *out_price);

/* ---- 2. Market making / liquidity provision ---------------------------- */
typedef struct {
    double bid;                 /* price paid per unit                   (> 0) */
    double ask;                 /* price received per unit        (>= bid)     */
    double quantity;            /* units per round trip                  (> 0) */
    double fee_rate;            /* per side; negative = rebate     (-1, 1)     */
    double fill_probability;    /* P(round trip completes at the ask)  [0, 1]  */
    double unwind_loss_rate;    /* if NOT filled, fraction of bid lost
                                   when stuck inventory is dumped      [0, 1]  */
    double fixed_costs;         /* total                                 (>= 0) */
    double holding_cost_per_day;/* total per day                         (>= 0) */
    double hold_days;           /* expected days inventory is carried          */
} tm_marketmaking_in;

/* Symmetric quote around a fair value: bid = fair*(1-h), ask = fair*(1+h). */
tm_status tm_quote(double fair_value, double half_spread_rate,
                   double *out_bid, double *out_ask);

tm_status tm_marketmaking(const tm_marketmaking_in *in, tm_result *out);

/* ---- 3. Value-add refurbishment ---------------------------------------- */
typedef struct {
    double probability;         /* chance of this outcome            [0, 1]    */
    double unit_value;          /* sale value per unit in this case  (>= 0)    */
} tm_outcome;

typedef struct {
    double acquire_price;       /* per unit, raw / distressed            (> 0) */
    double quantity;            /* units                                 (> 0) */
    double per_unit_cost;       /* grading fee, parts, labour, per unit  (>= 0) */
    double fixed_costs;         /* total                                 (>= 0) */
    double sell_fee_rate;       /* fraction of sale value            [0, 1)    */
    double holding_cost_per_day;/* total per day                         (>= 0) */
    double hold_days;           /* days capital is tied up                      */
} tm_refurb_in;

/*
 * `outcomes` lists every branch (e.g. grade results, or restored / not
 * restorable). Probabilities must each be in [0,1] and sum to 1 within
 * TM_PROB_TOLERANCE, otherwise TM_ERR_PROB.
 */
tm_status tm_refurbishment(const tm_refurb_in *in,
                           const tm_outcome *outcomes, size_t n_outcomes,
                           tm_result *out);

/* ---- 4. Regional / geofenced arbitrage --------------------------------- */
/*
 * Buy where an asset is cheap, move it, sell where it is dear. The edge is
 * spatial; the friction is logistics. For tokens the "move" may be a capital-
 * control or conversion barrier (a regional premium); for furniture it is a
 * truck. Either way the move can fail or damage the goods.
 */
typedef struct {
    double buy_price;            /* per unit, origin region               (> 0) */
    double sell_price;           /* per unit, destination region          (> 0) */
    double quantity;             /* units                                 (> 0) */
    double buy_fee_rate;         /* fraction of buy notional          [0, 1)    */
    double sell_fee_rate;        /* fraction of sell notional         [0, 1)    */
    double transport_cost_per_unit; /* freight / conversion per unit      (>= 0) */
    double fixed_costs;          /* total                                 (>= 0) */
    double holding_cost_per_day; /* total per day in transit              (>= 0) */
    double transit_days;         /* days capital is tied up      [0, MAX_HOLD]  */
    double loss_probability;     /* P(damaged / blocked / not completed) [0, 1] */
    double salvage_rate;         /* if lost: fraction of buy value
                                    recovered                           [0, 1] */
} tm_regional_in;

tm_status tm_regional(const tm_regional_in *in, tm_result *out);

/* Regional premium = sell_price / buy_price - 1 (e.g. 0.05 = 5% premium). */
tm_status tm_regional_premium(double buy_price, double sell_price,
                              double *out_premium);

/* ---- 5. Fragmented supply aggregation ----------------------------------- */
/*
 * Buy many small items from many sellers, assemble a cohesive set, sell the
 * set at a premium. The risk is that the set never completes; unsold pieces
 * then fetch only their piecemeal value.
 */
typedef struct {
    double set_value;            /* sale value of the COMPLETE set        (>= 0) */
    double piecemeal_value_per_item; /* value of one item sold alone      (>= 0) */
    double completion_probability;   /* P(the set is completed)          [0, 1] */
    double per_item_cost;        /* sorting, cleaning, travel, per item   (>= 0) */
    double fixed_costs;          /* total                                 (>= 0) */
    double sell_fee_rate;        /* fraction of sale value            [0, 1)    */
    double holding_cost_per_day; /* storage, total per day                (>= 0) */
    double hold_days;            /* the "patience" time          [0, MAX_HOLD]  */
} tm_aggregation_in;

/* lot_prices: acquisition price of each item, 1..TM_MAX_LOTS entries (> 0). */
tm_status tm_aggregation(const tm_aggregation_in *in,
                         const double *lot_prices, size_t n_lots,
                         tm_result *out);

/* ---- 6. Informational asymmetry ----------------------------------------- */
/*
 * A listing is mislabeled, mispriced or misunderstood. One evaluation is one
 * CANDIDATE listing: you pay to look at it (attempt_cost) every time, you only
 * buy it if you win the race against other buyers (win_probability), and what
 * you bought is only valuable if your read of it was right
 * (genuine_probability).
 */
typedef struct {
    double listed_price;         /* what the seller asks                  (> 0) */
    double genuine_value;        /* sale value if your read is right      (>= 0) */
    double fallback_value;       /* sale value if your read is wrong      (>= 0) */
    double genuine_probability;  /* P(your read is right)             [0, 1]    */
    double win_probability;      /* P(you get it before competitors)  [0, 1]    */
    double buy_fee_rate;         /* fraction of listed price          [0, 1)    */
    double sell_fee_rate;        /* fraction of sale value            [0, 1)    */
    double verification_cost;    /* authentication / inspection, if won   (>= 0) */
    double attempt_cost;         /* scanning / OCR / tooling per candidate (>= 0) */
    double holding_cost_per_day; /* total per day                         (>= 0) */
    double hold_days;            /* days capital is tied up      [0, MAX_HOLD]  */
} tm_asymmetry_in;

tm_status tm_asymmetry(const tm_asymmetry_in *in, tm_result *out);

/* Apparent discount = 1 - listed_price / estimated_value (needs both > 0). */
tm_status tm_mispricing(double listed_price, double estimated_value,
                        double *out_discount);

/* ---- 7. Consignment / zero inventory ------------------------------------ */
/*
 * Match buyers and sellers without buying or storing anything: earn a
 * commission when it sells. Almost no capital is tied up, so "return on cost"
 * can look enormous -- the real inputs are your TIME (labor_cost) and the
 * counterparty risk (chargeback / fraud), which are modelled explicitly.
 */
typedef struct {
    double sale_price;           /* expected sale price of the item       (> 0) */
    double commission_rate;      /* your share of the sale price      [0, 1)    */
    double sale_probability;     /* P(it sells)                       [0, 1]    */
    double platform_fee_rate;    /* fees YOU bear, fraction of sale   [0, 1)    */
    double labor_cost;           /* staging, photos, listing, messaging;
                                    value your time                     (>= 0) */
    double fixed_costs;          /* total                                 (>= 0) */
    double chargeback_probability;/* P(sale reversed / defrauded | sold) [0, 1] */
    double chargeback_loss;      /* amount you lose if it is              (>= 0) */
    double days_to_sell;         /* days until it sells          [0, MAX_HOLD]  */
} tm_consignment_in;

tm_status tm_consignment(const tm_consignment_in *in, tm_result *out);

/* ---- 8. Distressed inventory & liquidation ------------------------------ */
/*
 * Buy from a seller who values speed and certainty over price (forced
 * liquidation, eviction clean-out, storage auction, flash crash), then sell
 * the contents on. Institutional liquidators compete for the best lots, so
 * the model carries a win probability and a cost to pursue every lot.
 */
typedef struct {
    double lot_price;            /* total price of the whole lot          (> 0) */
    double units;                /* items in the lot                      (> 0) */
    double expected_unit_value;  /* resale value per unit that sells      (>= 0) */
    double sell_through_rate;    /* fraction of units that sell at that
                                    value                               [0, 1] */
    double salvage_unit_value;   /* per unit for the rest (scrap / dump)  (>= 0) */
    double sell_fee_rate;        /* fraction of sale value            [0, 1)    */
    double per_unit_handling_cost;/* sorting, cleaning, listing, per unit (>= 0) */
    double disposal_cost_per_unsold_unit; /* hauling away what will not sell (>= 0) */
    double fixed_costs;          /* truck, crew, total                    (>= 0) */
    double holding_cost_per_day; /* storage, total per day                (>= 0) */
    double hold_days;            /* days to clear the lot        [0, MAX_HOLD]  */
    double win_probability;      /* P(you get the lot)                [0, 1]    */
    double pursuit_cost;         /* cost of chasing the lot, paid either way (>= 0) */
} tm_distressed_in;

tm_status tm_distressed(const tm_distressed_in *in, tm_result *out);

/* ---- 9. Virtual inventory / sell-before-source -------------------------- */
/*
 * Take the customer's payment first and source the item afterwards. The edge
 * is that the customer's money funds the purchase; the risk is that you cannot
 * fulfil (item gone, price jumped, source refuses you) after being paid.
 *
 * Because the sale funds the purchase, "return on cost" here is measured on
 * total outlay, NOT on your own capital. Your capital at risk is mainly
 * fixed_costs plus the failure branch (failure_loss), which is why the
 * failure probability is the most important number in this model.
 *
 * This model assumes an HONEST sale: the buyer is told it is fulfilled to
 * order with a stated lead time. It makes no allowance for misrepresentation.
 */
typedef struct {
    double sale_price;           /* per unit, charged to your customer    (> 0) */
    double source_price;         /* per unit, quoted by the source now    (> 0) */
    double quantity;             /* units                                 (> 0) */
    double sale_fee_rate;        /* your sales channel's fee          [0, 1)    */
    double source_fee_rate;      /* fee on the purchase               [0, 1)    */
    double shipping_cost;        /* total per order                       (>= 0) */
    double price_drift_rate;     /* adverse move in source price between
                                    sale and purchase                   [0, 1)    */
    double fulfillment_failure_probability; /* P(cannot fulfil)       [0, 1]    */
    double failure_loss;         /* what you lose if you cannot: non-refundable
                                    fees, penalties, goodwill, total    (>= 0) */
    double fixed_costs;          /* total                                 (>= 0) */
    double days_to_fulfil;       /* sale -> delivery             [0, MAX_HOLD]  */
} tm_virtual_in;

tm_status tm_virtual(const tm_virtual_in *in, tm_result *out);

/* ---- 10. Synthetic bundling (assemble / disassemble) -------------------- */
/*
 * Turn one thing into many (break up a collection: sell the rare parts to
 * specialists, melt the rest) or many into one (assemble mismatched parts into
 * a finished piece). Both are "pay for inputs, transform at a cost, sell
 * outputs", so one structure covers them. Wrap/unwrap of a token is the
 * degenerate case: one output, tiny transform cost, small spread.
 */
typedef struct {
    double sale_value;           /* value of this output if it sells      (>= 0) */
    double sale_probability;     /* P(it sells at that value)         [0, 1]    */
    double fallback_value;       /* value if it does not (e.g. melt)      (>= 0) */
} tm_component;

typedef struct {
    double input_cost;           /* total paid for the inputs             (> 0) */
    double fixed_costs;          /* tools, setup, total                   (>= 0) */
    double per_output_cost;      /* labor / hardware / grading, per output (>= 0) */
    double waste_rate;           /* fraction of output value lost to
                                    material waste or defects           [0, 1)    */
    double sell_fee_rate;        /* fraction of sale value            [0, 1)    */
    double holding_cost_per_day; /* total per day                         (>= 0) */
    double hold_days;            /* days including assembly      [0, MAX_HOLD]  */
} tm_synthetic_in;

/* outputs: 1..TM_MAX_COMPONENTS entries. */
tm_status tm_synthetic(const tm_synthetic_in *in,
                       const tm_component *outputs, size_t n_outputs,
                       tm_result *out);

/* ---- 11. Event-driven momentum / hype cycle ------------------------------ */
/*
 * Enter on a news or trend shock and exit while demand is still elevated. The
 * profit is entirely in the exit-price distribution and in whether you can exit
 * at all; both are the caller's honest estimates. Hype decays, so time held is
 * a cost, not a neutral input. High failure rates are normal in this model:
 * thin or manipulated markets can leave you holding something you cannot sell
 * (exit_failure_probability), often at near-zero recovery.
 */
typedef struct {
    double entry_price;          /* per unit                              (> 0) */
    double quantity;             /* units                                 (> 0) */
    double buy_fee_rate;         /* fraction of entry notional        [0, 1)    */
    double sell_fee_rate;        /* fraction of exit notional         [0, 1)    */
    double entry_slippage_rate;  /* adverse fill on the way in        [0, 1)    */
    double exit_slippage_rate;   /* adverse fill on the way out       [0, 1)    */
    double fixed_costs;          /* total                                 (>= 0) */
    double holding_cost_per_day; /* total per day                         (>= 0) */
    double hold_days;            /* planned holding time         [0, MAX_HOLD]  */
    double exit_failure_probability; /* P(cannot exit at all)         [0, 1]    */
    double stuck_recovery_rate;  /* if stuck: fraction of entry value
                                    recovered                           [0, 1]    */
} tm_momentum_in;

/* exit_prices: branches that start with tm_outcome{probability, exit price per
 * unit}; probabilities must sum to 1 (they describe the exits that WERE
 * possible; the failure to exit is separate). */
tm_status tm_momentum(const tm_momentum_in *in,
                      const tm_outcome *exit_prices, size_t n_exit_prices,
                      tm_result *out);

/* Excess price above baseline remaining after `days`, given a half-life:
 * remaining = initial_excess * 0.5^(days / half_life_days). */
tm_status tm_hype_decay(double initial_excess, double half_life_days,
                        double days, double *out_remaining);

/* ---- Bridge to the advantage core -------------------------------------- */
/*
 * Express an evaluated trade as an advantage: reward = expected proceeds,
 * baseline = total cost plus the opportunity cost of tying that capital up
 * for hold_days at `cost_of_capital_annual` (a fraction, e.g. 0.05, in
 * [0, 10]). The advantage is what the trade earns beyond simply having paid
 * its costs AND beyond what the capital could have earned elsewhere.
 */
tm_status tm_baseline(const tm_result *r, double cost_of_capital_annual,
                      double *out_baseline);
tm_status tm_advantage(const tm_result *r, double cost_of_capital_annual,
                       double *out_advantage);

const char *tm_strerror(tm_status st);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* ADVANTAGE_TRADE_MODELS_H */