Skip to main content
Version: release (v0.77)

markets.proto

path vega/markets.proto

package vega


Messages

AuctionDuration

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

NameTypeDescription
durationint64Duration of the auction in seconds.
volumeuint64Target uncrossing trading volume.

CompositePriceConfiguration

Mark price configuration parameters.

NameTypeDescription
decay_weightstringDecay weight used for calculation of mark price.
decay_poweruint64Decay power used for the calculation of mark price.
cash_amountstringCash amount, in asset decimals, used for the calculation of the mark price from the order book.
source_weightsrepeated stringWeights for each composite price data source.
source_staleness_tolerancerepeated stringFor 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.
composite_price_typeCompositePriceTypeWhich method is used for the calculation of the composite price for the market.
data_sources_specrepeated DataSourceDefinitionAdditional price sources to be used for internal composite price calculation.
data_sources_spec_bindingrepeated SpecBindingForCompositePriceList of each price source and its corresponding binding

DataSourceSpecToFutureBinding

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

NameTypeDescription
settlement_data_propertystringName 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.
trading_termination_propertystringName of the property in the data source data that signals termination of trading.

DataSourceSpecToPerpetualBinding

Describes which properties of the data source data is to be used for settlement.

NameTypeDescription
settlement_data_propertystringName 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.
settlement_schedule_propertystringName of the property in the source data that should be used to determine the perpetual's settlement schedule.

FeeFactors

Fee factors definition

NameTypeDescription
maker_feestringMarket maker fee charged network wide.
infrastructure_feestringInfrastructure fee charged network wide for staking and governance.
liquidity_feestringLiquidity fee applied per market for market making.

Fees

Fees definition

NameTypeDescription
factorsFeeFactorsFee factors.
liquidity_fee_settingsLiquidityFeeSettingsLiquidity fee settings for the market describing how the fee was calculated.

Future

Future product definition

NameTypeDescription
settlement_assetstringUnderlying asset for the future.
quote_namestringQuote name of the instrument.
data_source_spec_for_settlement_dataDataSourceSpecData source specification that describes the settlement data source filter.
data_source_spec_for_trading_terminationDataSourceSpecData source specification that describes the trading termination data source filter.
data_source_spec_bindingDataSourceSpecToFutureBindingBinding between the data spec and the data source.
capoptional FutureCapIf set, this product represents a capped future market.

FutureCap

NameTypeDescription
max_pricestringSet the maximum price for orders, and settlement data in market decimals.
binary_settlementoptional boolIf set to true, the settlement price must either be zero, or equal to the max price.
fully_collateralisedoptional boolIf set to true, positions must be fully collateralised so there is no default risk for any party.

Instrument

Instrument definition

NameTypeDescription
idstringUnique instrument ID.
codestringCode for the instrument.
namestringName of the instrument.
metadataInstrumentMetadataCollection of instrument meta-data.
futureFutureFuture.
spotSpotSpot.
perpetualPerpetualPerpetual.

InstrumentMetadata

Instrument metadata definition

NameTypeDescription
tagsrepeated stringList of 0 or more tags.

LiquidationStrategy

Liquidation strategy used when the network holds a position resulting from position resolution.

NameTypeDescription
disposal_time_stepint64Interval, in seconds, at which the network will attempt to close its position.
disposal_fractionstringFraction of the open position the market will try to close in a single attempt; range 0 through 1.
full_disposal_sizeuint64Size of the position that the network will try to close in a single attempt.
max_fraction_consumedstringMax fraction of the total volume of the orderbook, within liquidity bounds, that the network can use to close its position; range 0 through 1.
disposal_slippage_rangestringDecimal > 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).

LiquidityFeeSettings

Market settings that describe how the liquidity fee is calculated.

NameTypeDescription
methodLiquidityFeeSettings.MethodMethod used to calculate the market's liquidity fee.
fee_constantoptional stringConstant liquidity fee used when using the constant fee method.

LiquidityMonitoringParameters

LiquidityMonitoringParameters contains settings used for liquidity monitoring

NameTypeDescription
target_stake_parametersTargetStakeParametersSpecifies parameters related to target stake calculation.
triggering_ratiostringSpecifies the triggering ratio for entering liquidity auction.
auction_extensionint64Specifies by how many seconds an auction should be extended if leaving the auction were to trigger a liquidity auction.

LiquiditySLAParameters

NameTypeDescription
price_rangestring
commitment_min_time_fractionstringSpecifies the minimum fraction of time LPs must spend "on the book" providing their committed liquidity.
performance_hysteresis_epochsuint64Specifies the number of liquidity epochs over which past performance will continue to affect rewards.
sla_competition_factorstringSpecifies 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.

LogNormalModelParams

Risk model parameters for log normal

NameTypeDescription
mudoubleMu parameter, annualised growth rate of the underlying asset.
rdoubleR parameter, annualised growth rate of the risk-free asset, used for discounting of future cash flows, can be any real number.
sigmadoubleSigma parameter, annualised volatility of the underlying asset, must be a strictly non-negative real number.

LogNormalRiskModel

Risk model for log normal

NameTypeDescription
risk_aversion_parameterdoubleRisk Aversion Parameter.
taudoubleTau 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.
paramsLogNormalModelParamsRisk model parameters for log normal.
risk_factor_overrideoptional RiskFactorOverrideAnd optional override for the risk factor calculated by the risk model.

MarginCalculator

Margin Calculator definition

NameTypeDescription
scaling_factorsScalingFactorsScaling factors for margin calculation.
fully_collateralisedoptional boolIf set to true, positions must be fully collateralised so there is no default risk for any party (capped futures).

Market

Market definition

NameTypeDescription
idstringUnique ID for the market.
tradable_instrumentTradableInstrumentTradable instrument configuration.
decimal_placesuint64Number 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'.
feesFeesFees configuration that apply to the market.
opening_auctionAuctionDurationAuction duration specifies how long the opening auction will run (minimum duration and optionally a minimum traded volume).
price_monitoring_settingsPriceMonitoringSettingsPriceMonitoringSettings for the market.
liquidity_monitoring_parametersLiquidityMonitoringParametersLiquidityMonitoringParameters for the market.
trading_modeMarket.TradingModeCurrent mode of execution of the market.
stateMarket.StateCurrent state of the market.
market_timestampsMarketTimestampsTimestamps for when the market state changes.
position_decimal_placesint64The number of decimal places for a position. On spot markets, used for order size, also known as 'size decimal places'.
lp_price_rangestringPercentage move up and down from the mid price which specifies the range of price levels over which automated liquidity provisions will be deployed.
linear_slippage_factorstringLinear slippage factor is used to cap the slippage component of maintenance margin - it is applied to the slippage volume.
quadratic_slippage_factorstringQuadratic slippage factor is used to cap the slippage component of maintenance margin - it is applied to the square of the slippage volume.
parent_market_idoptional stringID of the market this market succeeds
insurance_pool_fractionoptional stringThe fraction of the parent market's insurance pool that this market inherits; range 0 through 1.
successor_market_idoptional stringID of the market that succeeds this market if it exists. This will be populated by the system when the successor market is enabled.
liquidity_sla_paramsoptional LiquiditySLAParametersLiquidity SLA parameters for the market.
liquidation_strategyLiquidationStrategyLiquidation strategy used by this market.
mark_price_configurationCompositePriceConfigurationMark price calculation configuration.
tick_sizestringThe market tick size defines the minimum change in quote price for the market
enable_transaction_reorderingboolIf enabled aggressive orders sent to the market will be delayed by the configured number of blocks

MarketTimestamps

Time stamps for important times about creating, enacting etc the market

NameTypeDescription
proposedint64Time when the market is first proposed.
pendingint64Time when the market has been voted in and began its opening auction.
openint64Time when the market has left the opening auction and is ready to accept trades.
closeint64Time when the market closed.

Perpetual

Perpetual product definition

NameTypeDescription
settlement_assetstringUnderlying asset for the perpetual.
quote_namestringQuote name of the instrument.
margin_funding_factorstringControls how much the upcoming funding payment liability contributes to party's margin, in the range [0, 1].
interest_ratestringContinuously compounded interest rate used in funding rate calculation, in the range [-1, 1].
clamp_lower_boundstringLower bound for the clamp function used as part of the funding rate calculation, in the range [-1, 1].
clamp_upper_boundstringUpper bound for the clamp function used as part of the funding rate calculation, in the range [-1, 1].
data_source_spec_for_settlement_scheduleDataSourceSpecData source spec describing the data source for settlement schedule.
data_source_spec_for_settlement_dataDataSourceSpecData source spec describing the data source for settlement.
data_source_spec_bindingDataSourceSpecToPerpetualBindingBinding between the data source spec and the settlement data.
funding_rate_scaling_factoroptional stringFactor applied to funding-rates. This scales the impact that spot price deviations have on funding payments.
funding_rate_lower_boundoptional stringLower bound for the funding-rate such that the funding-rate will never be lower than this value.
funding_rate_upper_boundoptional stringUpper bound for the funding-rate such that the funding-rate will never be higher than this value.
internal_composite_price_configoptional CompositePriceConfigurationOptional configuration for the internal composite price used in funding payment calculation.

PriceMonitoringParameters

PriceMonitoringParameters contains a collection of triggers to be used for a given market

NameTypeDescription
triggersrepeated PriceMonitoringTrigger

PriceMonitoringSettings

PriceMonitoringSettings contains the settings for price monitoring

NameTypeDescription
parametersPriceMonitoringParametersSpecifies price monitoring parameters to be used for price monitoring purposes.

PriceMonitoringTrigger

PriceMonitoringTrigger holds together price projection horizon τ, probability level p, and auction extension duration

NameTypeDescription
horizonint64Price monitoring projection horizon τ in seconds.
probabilitystringPrice monitoring probability level p.
auction_extensionint64Price monitoring auction extension duration in seconds should the price breach its theoretical level over the specified horizon at the specified probability level.

RiskFactorOverride

Risk factor override to control stable leverage

NameTypeDescription
shortstringShort Risk factor value.
longstringLong Risk factor value.

ScalingFactors

Scaling Factors (for use in margin calculation)

NameTypeDescription
search_leveldoubleCollateral search level. If collateral dips below this value, the system will search for collateral to release.
initial_margindoubleInitial margin level. This is the minimum amount of collateral required to open a position in a market that requires margin.
collateral_releasedoubleCollateral 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.

SimpleModelParams

Risk model parameters for simple modelling

NameTypeDescription
factor_longdoublePre-defined risk factor value for long.
factor_shortdoublePre-defined risk factor value for short.
max_move_updoublePre-defined maximum price move up that the model considers as valid.
min_move_downdoublePre-defined minimum price move down that the model considers as valid.
probability_of_tradingdoublePre-defined constant probability of trading.

SimpleRiskModel

Risk model for simple modelling

NameTypeDescription
paramsSimpleModelParamsRisk model params for simple modelling.

Spot

Spot product definition

NameTypeDescription
base_assetstringAsset ID of the underlying base asset for the spot product.
quote_assetstringAsset ID of the underlying quote asset for the spot product.

TargetStakeParameters

TargetStakeParameters contains parameters used in target stake calculation

NameTypeDescription
time_windowint64Specifies length of time window expressed in seconds for target stake calculation.
scaling_factordoubleSpecifies scaling factors used in target stake calculation.

TradableInstrument

Tradable Instrument definition

NameTypeDescription
instrumentInstrumentDetails for the underlying instrument.
margin_calculatorMarginCalculatorMargin calculator for the instrument.
log_normal_risk_modelLogNormalRiskModelLog normal.
simple_risk_modelSimpleRiskModelSimple.

Enums

CompositePriceType

NameNumberDescription
COMPOSITE_PRICE_TYPE_UNSPECIFIED0
COMPOSITE_PRICE_TYPE_WEIGHTED1Composite price is calculated as a weighted average of the underlying mark prices.
COMPOSITE_PRICE_TYPE_MEDIAN2Composite price is calculated as a median of the underlying mark prices.
COMPOSITE_PRICE_TYPE_LAST_TRADE3Composite price is calculated as the last trade price.

LiquidityFeeSettings.Method

NameNumberDescription
METHOD_UNSPECIFIED0
METHOD_MARGINAL_COST1Fee 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_WEIGHTED_AVERAGE2Fee is the weighted average of all liquidity providers' nominated fees, weighted by their committment.
METHOD_CONSTANT3Fee is set by the market to a constant value irrespective of any liquidity provider's nominated fee.

Market.State

Current state of the market

NameNumberDescription
STATE_UNSPECIFIED0Default value, invalid
STATE_PROPOSED1Governance proposal valid and accepted
STATE_REJECTED2Outcome of governance votes is to reject the market
STATE_PENDING3Governance vote passes/wins
STATE_CANCELLED4Market triggers cancellation condition or governance votes to close before market becomes Active
STATE_ACTIVE5Enactment date reached and usual auction exit checks pass
STATE_SUSPENDED6Price monitoring or liquidity monitoring trigger
STATE_CLOSED7Governance vote to close (Not currently implemented)
STATE_TRADING_TERMINATED8Defined by the product (i.e. from a product parameter, specified in market definition, giving close date/time)
STATE_SETTLED9Settlement triggered and completed as defined by product
STATE_SUSPENDED_VIA_GOVERNANCE10Market has been suspended via governance

Market.TradingMode

Trading mode the market is currently running, also referred to as 'market state'

NameNumberDescription
TRADING_MODE_UNSPECIFIED0Default value, this is invalid
TRADING_MODE_CONTINUOUS1Normal trading
TRADING_MODE_BATCH_AUCTION2Auction trading (FBA)
TRADING_MODE_OPENING_AUCTION3Opening auction
TRADING_MODE_MONITORING_AUCTION4Auction triggered by monitoring
TRADING_MODE_NO_TRADING5No trading is allowed
TRADING_MODE_SUSPENDED_VIA_GOVERNANCE6Special auction mode triggered via governance
TRADING_MODE_LONG_BLOCK_AUCTION7Auction triggered globally by long block