code.vegaprotocol.io/vega@v0.79.0/protos/sources/vega/markets.proto

syntax = "proto3";

package vega;

import "vega/data_source.proto";

option go_package = "code.vegaprotocol.io/vega/protos/vega";

// Auction duration is used to configure 3 auction periods:
// 1. `duration > 0`, `volume == 0`:
//   The auction will last for at least N seconds
// 2. `duration == 0`, `volume > 0`:
//   The auction will end once the given volume will match at uncrossing
// 3. `duration > 0`, `volume > 0`:
//   The auction will take at least N seconds, but can end sooner if the market can trade a certain volume
message AuctionDuration {
  // Duration of the auction in seconds.
  int64 duration = 1;
  // Target uncrossing trading volume.
  uint64 volume = 2;
}

// Spot product definition
message Spot {
  // Asset ID of the underlying base asset for the spot product.
  string base_asset = 1;
  // Asset ID of the underlying quote asset for the spot product.
  string quote_asset = 2;
}

// Future product definition
message Future {
  // Underlying asset for the future.
  string settlement_asset = 1;
  // Quote name of the instrument.
  string quote_name = 2;
  // Data source specification that describes the settlement data source filter.
  vega.DataSourceSpec data_source_spec_for_settlement_data = 3;

  // Data source specification that describes the trading termination data source filter.
  vega.DataSourceSpec data_source_spec_for_trading_termination = 4;

  // Binding between the data spec and the data source.
  DataSourceSpecToFutureBinding data_source_spec_binding = 5;
  // If set, this product represents a capped future market.
  optional FutureCap cap = 6;
}

message FutureCap {
  // Set the maximum price for orders, and settlement data in market decimals.
  string max_price = 1;
  // If set to true, the settlement price must either be zero, or equal to the max price.
  optional bool binary_settlement = 2;
  // If set to true, positions must be fully collateralised so there is no default risk for any party.
  optional bool fully_collateralised = 3;
}

// Perpetual product definition
message Perpetual {
  // Underlying asset for the perpetual.
  string settlement_asset = 1;
  // Quote name of the instrument.
  string quote_name = 2;
  // Controls how much the upcoming funding payment liability contributes to party's margin, in the range [0, 1].
  string margin_funding_factor = 3;
  // Continuously compounded interest rate used in funding rate calculation, in the range [-1, 1].
  string interest_rate = 4;
  // Lower bound for the clamp function used as part of the funding rate calculation, in the range [-1, 1].
  string clamp_lower_bound = 5;
  // Upper bound for the clamp function used as part of the funding rate calculation, in the range [-1, 1].
  string clamp_upper_bound = 6;
  // Data source spec describing the data source for settlement schedule.
  vega.DataSourceSpec data_source_spec_for_settlement_schedule = 7;
  // Data source spec describing the data source for settlement.
  vega.DataSourceSpec data_source_spec_for_settlement_data = 8;
  // Binding between the data source spec and the settlement data.
  DataSourceSpecToPerpetualBinding data_source_spec_binding = 9;
  // Factor applied to funding-rates. This scales the impact that spot price deviations have on funding payments.
  optional string funding_rate_scaling_factor = 10;
  // Lower bound for the funding-rate such that the funding-rate will never be lower than this value.
  optional string funding_rate_lower_bound = 11;
  // Upper bound for the funding-rate such that the funding-rate will never be higher than this value.
  optional string funding_rate_upper_bound = 12;
  // Optional configuration for the internal composite price used in funding payment calculation.
  optional CompositePriceConfiguration internal_composite_price_config = 13;
}

// DataSourceSpecToFutureBinding describes which property of the data source data is to be
// used as settlement data and which to use as the trading terminated trigger
message DataSourceSpecToFutureBinding {
  // Name of the property in the source data that should be used as settlement data.
  // If it is set to "prices.BTC.value", then the Future will use the value of
  // this property as settlement data.
  string settlement_data_property = 1;
  // Name of the property in the data source data that signals termination of trading.
  string trading_termination_property = 2;
}

// Describes which properties of the data source data is to be
// used for settlement.
message DataSourceSpecToPerpetualBinding {
  // Name of the property in the source data that should be used for settlement data.
  // If it is set to "prices.BTC.value" for example, then the perpetual market will use the value of
  // this property to get settlement data.
  string settlement_data_property = 1;
  // Name of the property in the source data that should be used to determine the perpetual's settlement schedule.
  string settlement_schedule_property = 2;
}

// Instrument metadata definition
message InstrumentMetadata {
  // List of 0 or more tags.
  repeated string tags = 1;
}

// Instrument definition
message Instrument {
  // Unique instrument ID.
  string id = 1;
  // Code for the instrument.
  string code = 2;
  // Name of the instrument.
  string name = 3;
  // Collection of instrument meta-data.
  InstrumentMetadata metadata = 4;
  // Product the instrument is composed of.
  oneof product {
    // Future.
    Future future = 100;
    // Spot.
    Spot spot = 101;
    // Perpetual.
    Perpetual perpetual = 102;
  }
}

// Risk model for log normal
message LogNormalRiskModel {
  // Risk Aversion Parameter.
  double risk_aversion_parameter = 1;
  // Tau parameter of the risk model, projection horizon measured as a year fraction used in the expected shortfall
  // calculation to obtain the maintenance margin, must be a strictly non-negative real number.
  double tau = 2;
  // Risk model parameters for log normal.
  LogNormalModelParams params = 3;
  // And optional override for the risk factor calculated by the risk model.
  optional RiskFactorOverride risk_factor_override = 4;
}

// Risk factor override to control stable leverage
message RiskFactorOverride {
  // Short Risk factor value.
  string short = 1;
  // Long Risk factor value.
  string long = 2;
}

// Risk model parameters for log normal
message LogNormalModelParams {
  // Mu parameter, annualised growth rate of the underlying asset.
  double mu = 1;
  // R parameter, annualised growth rate of the risk-free asset, used for discounting of future cash flows, can be any real number.
  double r = 2;
  // Sigma parameter, annualised volatility of the underlying asset, must be a strictly non-negative real number.
  double sigma = 3;
}

// Risk model for simple modelling
message SimpleRiskModel {
  // Risk model params for simple modelling.
  SimpleModelParams params = 1;
}

// Risk model parameters for simple modelling
message SimpleModelParams {
  // Pre-defined risk factor value for long.
  double factor_long = 1;
  // Pre-defined risk factor value for short.
  double factor_short = 2;
  // Pre-defined maximum price move up that the model considers as valid.
  double max_move_up = 3;
  // Pre-defined minimum price move down that the model considers as valid.
  double min_move_down = 4;
  // Pre-defined constant probability of trading.
  double probability_of_trading = 5;
}

// Scaling Factors (for use in margin calculation)
message ScalingFactors {
  // Collateral search level. If collateral dips below this value,
  // the system will search for collateral to release.
  double search_level = 1;
  // Initial margin level. This is the minimum amount of collateral
  // required to open a position in a market that requires margin.
  double initial_margin = 2;
  // Collateral release level. If a trader has collateral above this level,
  // the system will release collateral to a trader's general collateral account
  // for the asset.
  double collateral_release = 3;
}

// Margin Calculator definition
message MarginCalculator {
  // Scaling factors for margin calculation.
  ScalingFactors scaling_factors = 1;
  // If set to true, positions must be fully collateralised so there is no default risk for any party (capped futures).
  optional bool fully_collateralised = 2;
}

// Tradable Instrument definition
message TradableInstrument {
  // Details for the underlying instrument.
  Instrument instrument = 1;
  // Margin calculator for the instrument.
  MarginCalculator margin_calculator = 2;
  // Risk model for use by the instrument.
  oneof risk_model {
    // Log normal.
    LogNormalRiskModel log_normal_risk_model = 100;
    // Simple.
    SimpleRiskModel simple_risk_model = 101;
  }
}

// Fee factors definition
message FeeFactors {
  // Market maker fee charged network wide.
  string maker_fee = 1;
  // Infrastructure fee charged network wide for staking and governance.
  string infrastructure_fee = 2;
  // Liquidity fee applied per market for market making.
  string liquidity_fee = 3;
  // Fees sent to network treasury for later use based on governance actions (network wide).
  string treasury_fee = 4;
  // Fees used to purchase governance tokens via regular auctions (network wide).
  string buy_back_fee = 5;
}

// Fees definition
message Fees {
  // Fee factors.
  FeeFactors factors = 1;
  // Liquidity fee settings for the market describing how the fee was calculated.
  LiquidityFeeSettings liquidity_fee_settings = 2;
}

// PriceMonitoringTrigger holds together price projection horizon τ, probability level p, and auction extension duration
message PriceMonitoringTrigger {
  // Price monitoring projection horizon τ in seconds.
  int64 horizon = 1;
  // Price monitoring probability level p.
  string probability = 2;
  // Price monitoring auction extension duration in seconds should the price
  // breach its theoretical level over the specified horizon at the specified
  // probability level.
  int64 auction_extension = 3;
}

// PriceMonitoringParameters contains a collection of triggers to be used for a given market
message PriceMonitoringParameters {
  repeated PriceMonitoringTrigger triggers = 1;
}

// PriceMonitoringSettings contains the settings for price monitoring
message PriceMonitoringSettings {
  // Specifies price monitoring parameters to be used for price monitoring purposes.
  PriceMonitoringParameters parameters = 1;
}

// LiquidityMonitoringParameters contains settings used for liquidity monitoring
message LiquidityMonitoringParameters {
  // Specifies parameters related to target stake calculation.
  TargetStakeParameters target_stake_parameters = 1;
  // Specifies the triggering ratio for entering liquidity auction.
  string triggering_ratio = 2;
  // Specifies by how many seconds an auction should be extended if leaving the auction were to trigger a liquidity auction.
  int64 auction_extension = 3;
}

message LiquiditySLAParameters {
  reserved 3; // Deprecated "providers_fee_calculation_time_step"

  string price_range = 1;
  // Specifies the minimum fraction of time LPs must spend "on the book" providing their committed liquidity.
  string commitment_min_time_fraction = 2;
  // Specifies the number of liquidity epochs over which past performance will continue to affect rewards.
  uint64 performance_hysteresis_epochs = 4;
  // Specifies the maximum fraction of their accrued fees an LP that meets the SLA implied by market.liquidity.commitmentMinTimeFraction will lose to liquidity providers
  // that achieved a higher SLA performance than them.
  string sla_competition_factor = 5;
}

// Market settings that describe how the liquidity fee is calculated.
message LiquidityFeeSettings {
  enum Method {
    METHOD_UNSPECIFIED = 0;
    // Fee is the smallest value of all bids, such that liquidity providers with nominated fees less than or equal to this value still have sufficient commitment to fulfil the market's target stake.
    METHOD_MARGINAL_COST = 1;
    // Fee is the weighted average of all liquidity providers' nominated fees, weighted by their committment.
    METHOD_WEIGHTED_AVERAGE = 2;
    // Fee is set by the market to a constant value irrespective of any liquidity provider's nominated fee.
    METHOD_CONSTANT = 3;
  }
  // Method used to calculate the market's liquidity fee.
  Method method = 1;
  // Constant liquidity fee used when using the constant fee method.
  optional string fee_constant = 2;
}

// TargetStakeParameters contains parameters used in target stake calculation
message TargetStakeParameters {
  // Specifies length of time window expressed in seconds for target stake calculation.
  int64 time_window = 1;
  // Specifies scaling factors used in target stake calculation.
  double scaling_factor = 2;
}

// Market definition
message Market {
  // Current state of the market
  enum State {
    // Default value, invalid
    STATE_UNSPECIFIED = 0;
    // Governance proposal valid and accepted
    STATE_PROPOSED = 1;
    // Outcome of governance votes is to reject the market
    STATE_REJECTED = 2;
    // Governance vote passes/wins
    STATE_PENDING = 3;
    // Market triggers cancellation condition or governance
    // votes to close before market becomes Active
    STATE_CANCELLED = 4;
    // Enactment date reached and usual auction exit checks pass
    STATE_ACTIVE = 5;
    // Price monitoring or liquidity monitoring trigger
    STATE_SUSPENDED = 6;
    // Governance vote to close (Not currently implemented)
    STATE_CLOSED = 7;
    // Defined by the product (i.e. from a product parameter,
    // specified in market definition, giving close date/time)
    STATE_TRADING_TERMINATED = 8;
    // Settlement triggered and completed as defined by product
    STATE_SETTLED = 9;
    // Market has been suspended via governance
    STATE_SUSPENDED_VIA_GOVERNANCE = 10;
  }

  // Trading mode the market is currently running, also referred to as 'market state'
  enum TradingMode {
    // Default value, this is invalid
    TRADING_MODE_UNSPECIFIED = 0;
    // Normal trading
    TRADING_MODE_CONTINUOUS = 1;
    // Auction trading (FBA)
    TRADING_MODE_BATCH_AUCTION = 2;
    // Opening auction
    TRADING_MODE_OPENING_AUCTION = 3;
    // Auction triggered by monitoring
    TRADING_MODE_MONITORING_AUCTION = 4;
    // No trading is allowed
    TRADING_MODE_NO_TRADING = 5;
    // Special auction mode triggered via governance
    TRADING_MODE_SUSPENDED_VIA_GOVERNANCE = 6;
    // Auction triggered globally by long block
    TRADING_MODE_LONG_BLOCK_AUCTION = 7;
    // Scheduled auction for automated purchase
    TRADING_MODE_PROTOCOL_AUTOMATED_PURCHASE_AUCTION = 8;

    // Note: If adding an enum value, add a matching entry in:
    //       - gateway/graphql/helpers_enum.go
    //       - gateway/graphql/schema.graphql (enum MarketTradingMode)
  }

  // Unique ID for the market.
  string id = 1;
  // Tradable instrument configuration.
  TradableInstrument tradable_instrument = 2;
  // Number of decimal places that a price must be shifted by in order to get a
  // correct price denominated in the currency of the market, for example:
  // `realPrice = price / 10^decimalPlaces`. On spot markets, also called 'size decimal places'.
  uint64 decimal_places = 3;
  // Fees configuration that apply to the market.
  Fees fees = 4;
  // Auction duration specifies how long the opening auction will run (minimum
  // duration and optionally a minimum traded volume).
  AuctionDuration opening_auction = 5;
  // PriceMonitoringSettings for the market.
  PriceMonitoringSettings price_monitoring_settings = 6;
  // LiquidityMonitoringParameters for the market.
  LiquidityMonitoringParameters liquidity_monitoring_parameters = 7;
  // Current mode of execution of the market.
  TradingMode trading_mode = 8;
  // Current state of the market.
  State state = 9;
  // Timestamps for when the market state changes.
  MarketTimestamps market_timestamps = 10;
  // The number of decimal places for a position.
  // On spot markets, used for order size, also known as 'size decimal places'.
  int64 position_decimal_places = 11;
  // Percentage move up and down from the mid price which specifies the range of
  // price levels over which automated liquidity provisions will be deployed.
  string lp_price_range = 12;
  // Linear slippage factor is used to cap the slippage component of maintenance margin - it is applied to the slippage volume.
  string linear_slippage_factor = 13;
  // Quadratic slippage factor is used to cap the slippage component of maintenance margin - it is applied to the square of the slippage volume.
  string quadratic_slippage_factor = 14;
  // ID of the market this market succeeds
  optional string parent_market_id = 15;
  // The fraction of the parent market's insurance pool that this market inherits; range 0 through 1.
  optional string insurance_pool_fraction = 16;
  // ID of the market that succeeds this market if it exists. This will be populated by the system when the successor market is enabled.
  optional string successor_market_id = 17;
  // Liquidity SLA parameters for the market.
  optional LiquiditySLAParameters liquidity_sla_params = 18;
  // Liquidation strategy used by this market.
  LiquidationStrategy liquidation_strategy = 19;
  // Mark price calculation configuration.
  CompositePriceConfiguration mark_price_configuration = 20;
  // The market tick size defines the minimum change in quote price for the market
  string tick_size = 21;
  // If enabled aggressive orders sent to the market will be delayed by the configured number of blocks
  bool enable_transaction_reordering = 22;
  // Number of allowed price levels between an AMM's fair price and its quote prices. An AMM definition that exceeds this will be rejected at submission.
  uint64 allowed_empty_amm_levels = 23;
  // Proposer of the market, to be used to restrict the sell side
  repeated string allowed_sellers = 24;
}

// Time stamps for important times about creating, enacting etc the market
message MarketTimestamps {
  // Time when the market is first proposed.
  int64 proposed = 1;
  // Time when the market has been voted in and began its opening auction.
  int64 pending = 2;
  // Time when the market has left the opening auction and is ready to accept trades.
  int64 open = 3;
  // Time when the market closed.
  int64 close = 4;
}

// Liquidation strategy used when the network holds a position resulting from position resolution.
message LiquidationStrategy {
  // Interval, in seconds, at which the network will attempt to close its position.
  int64 disposal_time_step = 1;
  // Fraction of the open position the market will try to close in a single attempt; range 0 through 1.
  string disposal_fraction = 2;
  // Size of the position that the network will try to close in a single attempt.
  uint64 full_disposal_size = 3;
  // Max fraction of the total volume of the orderbook, within liquidity bounds, that the network can use to close its position; range 0 through 1.
  string max_fraction_consumed = 4;
  // Decimal > 0 specifying the range range above and below the mid price within which the network will trade to dispose of its position.
  // The value can be > 1. For example, if set to 1.5, the minimum price will be 0, ie max(0, mid_price * (1 - 1.5)), and the maximum price will be mid_price * (1 + 1.5).
  string disposal_slippage_range = 5;
}

enum CompositePriceType {
  COMPOSITE_PRICE_TYPE_UNSPECIFIED = 0;
  // Composite price is calculated as a weighted average of the underlying mark prices.
  COMPOSITE_PRICE_TYPE_WEIGHTED = 1;
  // Composite price is calculated as a median of the underlying mark prices.
  COMPOSITE_PRICE_TYPE_MEDIAN = 2;
  // Composite price is calculated as the last trade price.
  COMPOSITE_PRICE_TYPE_LAST_TRADE = 3;
}

// Mark price configuration parameters.
message CompositePriceConfiguration {
  // Decay weight used for calculation of mark price.
  string decay_weight = 1;
  // Decay power used for the calculation of mark price.
  uint64 decay_power = 2;
  // Cash amount, in asset decimals, used for the calculation of the mark price from the order book.
  string cash_amount = 3;
  // Weights for each composite price data source.
  repeated string source_weights = 4;
  // For how long a price source is considered valid. One entry for each data source
  // such that the first is for the trade based mark price, the second is for the book based price
  // the third is for the first oracle, followed by more oracle data source staleness tolerance.
  repeated string source_staleness_tolerance = 5;
  // Which method is used for the calculation of the composite price for the market.
  CompositePriceType composite_price_type = 6;
  // Additional price sources to be used for internal composite price calculation.
  repeated vega.DataSourceDefinition data_sources_spec = 7;
  // List of each price source and its corresponding binding
  repeated vega.SpecBindingForCompositePrice data_sources_spec_binding = 8;
}

// Describes which properties of the data source data are to be
// used for automated purchase.
message DataSourceSpecToAutomatedPurchaseBinding {
  // Name of the property in the source data that should be used to determine the automated purchase schedule.
  string auction_schedule_property = 1;
  // Name of the property in the source data that should be used to determine the schedule of the automated purchase auction.
  string auction_volume_snapshot_schedule_property = 2;
}