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. |
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. |
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. |
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. |
MarginCalculator
Margin Calculator definition
| Name | Type | Description |
|---|
scaling_factors | ScalingFactors | Scaling factors for margin calculation. |
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`. |
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. |
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. |
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
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. |
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
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. |
name | string | Name of the instrument. |
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
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 |