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

Name	Type	Description
duration	int64	Duration of the auction in seconds.
volume	uint64	Target uncrossing trading volume.

CompositePriceConfiguration

Mark price configuration parameters.

Name	Type	Description
decay_weight	string	Decay weight used for calculation of mark price.
decay_power	uint64	Decay power used for the calculation of mark price.
cash_amount	string	Cash amount, in asset decimals, used for the calculation of the mark price from the order book.
source_weights	repeated string	Weights for each composite price data source.
source_staleness_tolerance	repeated string	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.
composite_price_type	CompositePriceType	Which method is used for the calculation of the composite price for the market.
data_sources_spec	repeated DataSourceDefinition	Additional price sources to be used for internal composite price calculation.
data_sources_spec_binding	repeated SpecBindingForCompositePrice	List 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

Name	Type	Description
settlement_data_property	string	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.
trading_termination_property	string	Name 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.

Name	Type	Description
settlement_data_property	string	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.
settlement_schedule_property	string	Name of the property in the source data that should be used to determine the perpetual's settlement schedule.

FeeFactors

Fee factors definition

Name	Type	Description
maker_fee	string	Market maker fee charged network wide.
infrastructure_fee	string	Infrastructure fee charged network wide for staking and governance.
liquidity_fee	string	Liquidity fee applied per market for market making.

Fees

Fees definition

Name	Type	Description
factors	FeeFactors	Fee factors.
liquidity_fee_settings	LiquidityFeeSettings	Liquidity fee settings for the market describing how the fee was calculated.

Future

Future product definition

Name	Type	Description
settlement_asset	string	Underlying asset for the future.
quote_name	string	Quote name of the instrument.
data_source_spec_for_settlement_data	DataSourceSpec	Data source specification that describes the settlement data source filter.
data_source_spec_for_trading_termination	DataSourceSpec	Data source specification that describes the trading termination data source filter.
data_source_spec_binding	DataSourceSpecToFutureBinding	Binding between the data spec and the data source.
cap	optional FutureCap	If set, this product represents a capped future market.

FutureCap

Name	Type	Description
max_price	string	Set the maximum price for orders, and settlement data in market decimals.
binary_settlement	optional bool	If set to true, the settlement price must either be zero, or equal to the max price.
fully_collateralised	optional bool	If set to true, positions must be fully collateralised so there is no default risk for any party.

Instrument

Instrument definition

Name	Type	Description
id	string	Unique instrument ID.
code	string	Code for the instrument.
name	string	Name of the instrument.
metadata	InstrumentMetadata	Collection of instrument meta-data.
future	Future	Future.
spot	Spot	Spot.
perpetual	Perpetual	Perpetual.

InstrumentMetadata

Instrument metadata definition

Name	Type	Description
tags	repeated string	List of 0 or more tags.

LiquidationStrategy

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

Name	Type	Description
disposal_time_step	int64	Interval, in seconds, at which the network will attempt to close its position.
disposal_fraction	string	Fraction of the open position the market will try to close in a single attempt; range 0 through 1.
full_disposal_size	uint64	Size of the position that the network will try to close in a single attempt.
max_fraction_consumed	string	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.
disposal_slippage_range	string	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).

LiquidityFeeSettings

Market settings that describe how the liquidity fee is calculated.

Name	Type	Description
method	LiquidityFeeSettings.Method	Method used to calculate the market's liquidity fee.
fee_constant	optional string	Constant liquidity fee used when using the constant fee method.

LiquidityMonitoringParameters

LiquidityMonitoringParameters contains settings used for liquidity monitoring

Name	Type	Description
target_stake_parameters	TargetStakeParameters	Specifies parameters related to target stake calculation.
triggering_ratio	string	Specifies the triggering ratio for entering liquidity auction.
auction_extension	int64	Specifies by how many seconds an auction should be extended if leaving the auction were to trigger a liquidity auction.

LiquiditySLAParameters

Name	Type	Description
price_range	string
commitment_min_time_fraction	string	Specifies the minimum fraction of time LPs must spend "on the book" providing their committed liquidity.
performance_hysteresis_epochs	uint64	Specifies the number of liquidity epochs over which past performance will continue to affect rewards.
sla_competition_factor	string	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.

LogNormalModelParams

Risk model parameters for log normal

Name	Type	Description
mu	double	Mu parameter, annualised growth rate of the underlying asset.
r	double	R parameter, annualised growth rate of the risk-free asset, used for discounting of future cash flows, can be any real number.
sigma	double	Sigma parameter, annualised volatility of the underlying asset, must be a strictly non-negative real number.

LogNormalRiskModel

Risk model for log normal

Name	Type	Description
risk_aversion_parameter	double	Risk Aversion Parameter.
tau	double	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.
params	LogNormalModelParams	Risk model parameters for log normal.
risk_factor_override	optional RiskFactorOverride	And optional override for the risk factor calculated by the risk model.

MarginCalculator

Margin Calculator definition

Name	Type	Description
scaling_factors	ScalingFactors	Scaling factors for margin calculation.
fully_collateralised	optional bool	If set to true, positions must be fully collateralised so there is no default risk for any party (capped futures).

Market

Market definition

Name	Type	Description
id	string	Unique ID for the market.
tradable_instrument	TradableInstrument	Tradable instrument configuration.
decimal_places	uint64	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'.
fees	Fees	Fees configuration that apply to the market.
opening_auction	AuctionDuration	Auction duration specifies how long the opening auction will run (minimum duration and optionally a minimum traded volume).
price_monitoring_settings	PriceMonitoringSettings	PriceMonitoringSettings for the market.
liquidity_monitoring_parameters	LiquidityMonitoringParameters	LiquidityMonitoringParameters for the market.
trading_mode	Market.TradingMode	Current mode of execution of the market.
state	Market.State	Current state of the market.
market_timestamps	MarketTimestamps	Timestamps for when the market state changes.
position_decimal_places	int64	The number of decimal places for a position. On spot markets, used for order size, also known as 'size decimal places'.
lp_price_range	string	Percentage 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_factor	string	Linear slippage factor is used to cap the slippage component of maintenance margin - it is applied to the slippage volume.
quadratic_slippage_factor	string	Quadratic slippage factor is used to cap the slippage component of maintenance margin - it is applied to the square of the slippage volume.
parent_market_id	optional string	ID of the market this market succeeds
insurance_pool_fraction	optional string	The fraction of the parent market's insurance pool that this market inherits; range 0 through 1.
successor_market_id	optional string	ID 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_params	optional LiquiditySLAParameters	Liquidity SLA parameters for the market.
liquidation_strategy	LiquidationStrategy	Liquidation strategy used by this market.
mark_price_configuration	CompositePriceConfiguration	Mark price calculation configuration.
tick_size	string	The market tick size defines the minimum change in quote price for the market
enable_transaction_reordering	bool	If 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

Name	Type	Description
proposed	int64	Time when the market is first proposed.
pending	int64	Time when the market has been voted in and began its opening auction.
open	int64	Time when the market has left the opening auction and is ready to accept trades.
close	int64	Time when the market closed.

Perpetual

Perpetual product definition

Name	Type	Description
settlement_asset	string	Underlying asset for the perpetual.
quote_name	string	Quote name of the instrument.
margin_funding_factor	string	Controls how much the upcoming funding payment liability contributes to party's margin, in the range [0, 1].
interest_rate	string	Continuously compounded interest rate used in funding rate calculation, in the range [-1, 1].
clamp_lower_bound	string	Lower bound for the clamp function used as part of the funding rate calculation, in the range [-1, 1].
clamp_upper_bound	string	Upper bound for the clamp function used as part of the funding rate calculation, in the range [-1, 1].
data_source_spec_for_settlement_schedule	DataSourceSpec	Data source spec describing the data source for settlement schedule.
data_source_spec_for_settlement_data	DataSourceSpec	Data source spec describing the data source for settlement.
data_source_spec_binding	DataSourceSpecToPerpetualBinding	Binding between the data source spec and the settlement data.
funding_rate_scaling_factor	optional string	Factor applied to funding-rates. This scales the impact that spot price deviations have on funding payments.
funding_rate_lower_bound	optional string	Lower bound for the funding-rate such that the funding-rate will never be lower than this value.
funding_rate_upper_bound	optional string	Upper bound for the funding-rate such that the funding-rate will never be higher than this value.
internal_composite_price_config	optional CompositePriceConfiguration	Optional 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

Name	Type	Description
triggers	repeated PriceMonitoringTrigger

PriceMonitoringSettings

PriceMonitoringSettings contains the settings for price monitoring

Name	Type	Description
parameters	PriceMonitoringParameters	Specifies price monitoring parameters to be used for price monitoring purposes.

PriceMonitoringTrigger

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

Name	Type	Description
horizon	int64	Price monitoring projection horizon τ in seconds.
probability	string	Price monitoring probability level p.
auction_extension	int64	Price 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

Name	Type	Description
short	string	Short Risk factor value.
long	string	Long Risk factor value.

ScalingFactors

Scaling Factors (for use in margin calculation)

Name	Type	Description
search_level	double	Collateral search level. If collateral dips below this value, the system will search for collateral to release.
initial_margin	double	Initial margin level. This is the minimum amount of collateral required to open a position in a market that requires margin.
collateral_release	double	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.

SimpleModelParams

Risk model parameters for simple modelling

Name	Type	Description
factor_long	double	Pre-defined risk factor value for long.
factor_short	double	Pre-defined risk factor value for short.
max_move_up	double	Pre-defined maximum price move up that the model considers as valid.
min_move_down	double	Pre-defined minimum price move down that the model considers as valid.
probability_of_trading	double	Pre-defined constant probability of trading.

SimpleRiskModel

Risk model for simple modelling

Name	Type	Description
params	SimpleModelParams	Risk model params for simple modelling.

Spot

Spot product definition

Name	Type	Description
base_asset	string	Asset ID of the underlying base asset for the spot product.
quote_asset	string	Asset ID of the underlying quote asset for the spot product.

TargetStakeParameters

TargetStakeParameters contains parameters used in target stake calculation

Name	Type	Description
time_window	int64	Specifies length of time window expressed in seconds for target stake calculation.
scaling_factor	double	Specifies scaling factors used in target stake calculation.

TradableInstrument

Tradable Instrument definition

Name	Type	Description
instrument	Instrument	Details for the underlying instrument.
margin_calculator	MarginCalculator	Margin calculator for the instrument.
log_normal_risk_model	LogNormalRiskModel	Log normal.
simple_risk_model	SimpleRiskModel	Simple.

---

Enums

CompositePriceType

Name	Number	Description
COMPOSITE_PRICE_TYPE_UNSPECIFIED	0
COMPOSITE_PRICE_TYPE_WEIGHTED	1	Composite price is calculated as a weighted average of the underlying mark prices.
COMPOSITE_PRICE_TYPE_MEDIAN	2	Composite price is calculated as a median of the underlying mark prices.
COMPOSITE_PRICE_TYPE_LAST_TRADE	3	Composite price is calculated as the last trade price.

LiquidityFeeSettings.Method

Name	Number	Description
METHOD_UNSPECIFIED	0
METHOD_MARGINAL_COST	1	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_WEIGHTED_AVERAGE	2	Fee is the weighted average of all liquidity providers' nominated fees, weighted by their committment.
METHOD_CONSTANT	3	Fee is set by the market to a constant value irrespective of any liquidity provider's nominated fee.

Market.State

Current state of the market

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

Market.TradingMode

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

Name	Number	Description
TRADING_MODE_UNSPECIFIED	0	Default value, this is invalid
TRADING_MODE_CONTINUOUS	1	Normal trading
TRADING_MODE_BATCH_AUCTION	2	Auction trading (FBA)
TRADING_MODE_OPENING_AUCTION	3	Opening auction
TRADING_MODE_MONITORING_AUCTION	4	Auction triggered by monitoring
TRADING_MODE_NO_TRADING	5	No trading is allowed
TRADING_MODE_SUSPENDED_VIA_GOVERNANCE	6	Special auction mode triggered via governance
TRADING_MODE_LONG_BLOCK_AUCTION	7	Auction triggered globally by long block

---