Skip to main content
Version: testnet (v0.74)

Propose new perpetuals market

Requirements​

You will need:

Anatomy of a proposal​

The contents of a changes object specifies what will be different after the proposal. In this case, these are the changes that will occur on the network, in the form of a new market.

Instrument, liquidity monitoring parameters, price monitoring parameters, and data sources are all described in more detail below.

Rationale requires a title and description, which is are free-text fields that describe the purpose of the proposal. Within the description, include links with more information about your proposal (such as to the IPFS content or forum post) that voters can reference to learn more about the market proposal. Formatting your rationale with markdown makes it easier to read when it's displayed.

Decimal places need to be defined for both order sizes and the market. A market cannot specify more decimal places than its settlement asset supports. The values for these fields cannot be changed, even through governance.

FieldDescriptionExample
decimalPlacesSets the smallest price increment on the book.18
positionDecimalPlacesSets the size that the smallest order / position on the market can be. Set the position decimal places such that the margin on the smallest order ends up being about 1 USD. This ensures that the market will not accept orders with very small margin minimums, protecting the network from being spammed with lots of financially insignificant orders. To figure out the ideal decimal place: Calculate the risk factor. Find the current price the asset is trading for, such as from the oracle you're using. The smallest order margin is price x 10^{-pdp} x (risk factor). Convert to USD. If this is less than 0.5, then decrease the position decimal places (pdp) accordingly. Position decimal places (pdp) can also be negative integers.3

Timestamps are required for ending the voting period, as well as enacting the market. The time between closing and enactment also defines how long an opening auction will be, which must be smaller than/equal to the difference between πŸ”—governance.proposal.market.maxClose: 720h and πŸ”—governance.proposal.market.maxEnact: 720h.

FieldDescriptionExample
closingTimestampTimestamp (Unix time in seconds) when voting closes for this proposal. If it passes the vote, liquidity can be committed from this time. The chosen time must be between πŸ”—1m and πŸ”—720h after the proposal submission time. (int64 as string)1663517914
enactmentTimestampTimestamp (Unix time in seconds) when the market will be enacted, ready for trading. The chosen time must be between πŸ”—1m and πŸ”—720h after closingTimestamp. (int64 as string)1663604314

Slippage factors are parameters that determine by how much the margin slippage is affected by the liquidity component of margin in a low-volume scenario. If there is enough volume on the book, the slippage comes directly from the book and the liquidity component is not used. The suggested values are in the example column below. Margin slippage in a low-volume scenario is calculated as slippageFromFactors = linear x position + quadratic x position^2) x price. I

FieldDescriptionExample
linearSlippageFactorThe linear slippage factor captures that for a bigger position there is proportionally bigger liquidity risk.0.001
quadraticSlippageFactorThe quadratic slippage factor determines by what factor especially large positions can be penalised. When closing those out, the system will 'walk the book' and potentially end up with an execution price notably worse that the last mark price.0.0

Instrument​

An instrument contains the following properties:

FieldDescriptionSample value
nameA string for the market name. Best practice is to include a full and fairly descriptive name for the instrument.Oranges DEC18.
code (instrument)This is a shortcode used to easily describe the instrument. The more information you add, the easier it is for people to know what the market offers.FX:BTCUSD/DEC18
perpetualAn object that provides details about the perpetual market to be proposed.
settlementAssetSettlement asset requires the ID of the asset that the market will be margined in and settle in. You can get a list of supported assets by querying REST, GraphQL, or gRPC, and then selecting the asset ID.
quoteNameThe quote name is the human-readable name/abbreviation of the settlement asset. Example: In BTCUSD, USD is the quote.tEuro
marginFundingFactorDetermines how much a funding payment liability contributes to a trader's margin. Must be in the range [0, 1].0.9
interestRateSets the continuously compounded interest rate used in funding rate calculation. Must be in the range [-1, 1].0.1
clampLowerBoundLower bound for the clamp function used as part of the funding rate calculation. Must be in the range [-1, 1].0
clampUpperBoundUpper bound for the clamp function used as part of the funding rate calculation. Must be in the range [-1, 1].0
dataSourceSpecForSettlementDataThis defines the Ethereum data source, the method, normalisers, required confirmations, etc, that will be used to identify the settlement price when the market expires.
dataSourceSpecForSettlementScheduleThis defines how the market will source data for funding, and how often to source it.
dataSourceSpecBindingThe fields describe how specific information provided by the data source is used. For example, they are used to set the settlement data property and the settlement schedule property.

Data source for settlement schedule​

The periodic settlements scheduled with the fields below determine how often the market's funding payments occur. It's recommended that funding payments are be less frequent than auction extensions for price monitoring. Very frequent funding payments may lead to quick price changes in the market that participants may not have time to react to. Setting longer funding payment triggers allow for more time.

The settlement schedule property contains the following fields:

FieldDescriptionSample value
internal: timeTriggerDetermines when the call should be repeated after the first call, in seconds.3300
conditionsA filter for the data. The conditions that should to be matched by the data to be considered. This is an optional set of fields. For example you could use an operator and a value to denote that a price should be greater than zero
operatorThis adds a constraint to the value, such as LESS_THAN, GREATER_THAN. For example if you wanted to ensure that the price would always be above zero, you would set the operator to β€˜GREATER_THAN’ and the Value to be β€˜0’GREATER_THAN_OR_EQUAL
valueA number that is constrained by the operator. If providing a timestamp, use the Unix time in seconds0
triggers: initial; everyThese fields set how often the call should be repeated after the initial call, in seconds.1699033027; 28800

Data source for settlement data​

Data feeds from an oracle can be used to determine when to read price data from an Ethereum contract.

Data source specs include the following properties under ethOracle:

FieldDescriptionSample value
addressEthereum address that can sign and submit values for this data sourceValid Ethereum address
abiThe abi tells the settlement spec how to interact with the oracle.
methodMethod is one field that describes what information to take from the oracle.latestAnswer
argsAny extra information that is required from the contract. Can be left as an empty array if there is none.
normalisers: name, expressionNormalisers are used to convert the data returned from the contract method into a standard format. The name identifies the specific piece of data. The value is where in the contract call result the required data is located. For example $[0] is the first result.
requiredConfirmationsNumber of network confirmations before data can be considered verified3
timeTrigger: initial; everyDetermines the first call, and how often the call should be repeated, in seconds.1701193129, 3000
filtersFilters define what data is of importance for the purposes of this market
keyDefines the specific type of information the data source provides that is relevant to the proposed market. Example: If a data source provides a list of prices for various markets, focus only on the specific relevant price for the market, and specifics on the data format.
nameSpecific name of the information that the filter provides.btc.price
typeSpecifies the data type that is emitted. For example, for btc.price, the type is an integer, as it is output as a non-fractional numberTYPE_INTEGER
numberDecimalPlacesNumber of decimal places specifies the precision in which numerical data is emitted. Use when data is numerical8
conditionsA filter for the data. The conditions that should to be matched by the data to be considered. This is an optional set of fields. For example you could use an operator and a value to denote that a price should be greater than zero
operatorThis adds a constraint to the value, such as LESS_THAN, GREATER_THAN. For example if you wanted to ensure that the price would always be above zero, you would set the operator to β€˜GREATER_THAN’ and the Value to be β€˜0’GREATER_THAN
valueA number that is constrained by the operator. If providing a timestamp, use the Unix time in seconds0
dataSourceSpecBindingDescribes which property of the data source data is to be used as settlement data and when.
settlementDataPropertyName of the property in the source data to be used as settlement data.btc.price
settlementSchedulePropertyDescribes what to use to determine when to run a settlement.vegaprotocol.builtin.timetrigger
Submitting data

Learn how to find and submit data in the submitting data sources tutorial.

Liquidity monitoring​

The liquidity monitoring settings detect when the market's liquidity drops below the safe level, and as such when to launch a 'liquidity seeking' auction. See below for more details on each field.

undefined

Liquidity monitoring uses the following properties:

FieldDescriptionSample value
targetStakeParametersTarget stake parameters are derived from open interest history over a time window to calculate the maximum open interest.
timeWindowDefines the length of time (in seconds) over which open interest is measured. If empty, this field defaults to πŸ”—1h0m0s.3600
scalingFactorThe target stake scaling factor scales the estimated required liquidity (based on the market's risk model and current market data) to yield the market's target stake. If not included, it defaults to the value of the network parameter πŸ”—market.stake.target.scalingFactor. The scaling factor must be a number greater than zero and finite10
triggeringRatioSpecifies the triggering ratio for entering liquidity auction. If empty, the network will default to πŸ”—0.250.7
auctionExtensionSpecifies by how many seconds an auction should be extended if leaving the auction were to trigger a liquidity auction. If empty, the network will default to the network parameter πŸ”—market.monitor.price.defaultParameters1

Price monitoring​

Price monitoring parameters are optional, and configure the acceptable price movement bounds for price monitoring. If you leave these blank, they will default to the value of the network parameter πŸ”—market.monitor.price.defaultParameters). See below for more details on each field.

{
 // PriceMonitoringTrigger holds together price projection horizon Ο„, probability level p, and auction extension duration
 triggers: [
  {
   // Price monitoring projection horizon Ο„ in seconds. (int64 as string)
   horizon: "43200",
   // Price monitoring probability level p. (string)
   probability: "0.9999999",
   // Price monitoring auction extension duration in seconds should the price
   // breach its theoretical level over the specified horizon at the specified
   // probability level. (int64 as string)
   auctionExtension: "600",
  }
 ]
}

Price monitoring uses the following properties:

FieldDescriptionSample value
horizonPrice monitoring projection horizon Ο„ in seconds (set as >0)43200
probabilityPrice monitoring probability level p (set as >0 and <1)0.9999999
auctionExtensionPrice monitoring auction extension duration (in seconds) should the price breach its theoretical level over the specified horizon at the specified probability level (set as >0)600

You can use a maximum of 5 sets of price monitoring parameters for a market.

Risk model​

Choose the individual parameters for the log-normal risk model. You should ensure the risk model parameters represent the dynamics of the underlying instrument, and that the resulting margins strike the right balance between prudence and capital efficiency.

While you cannot define exactly how much margin (or leverage) is possible, you can influence the acceptable levels of market volatility.

Read about the risk models and parameters before choosing your values.

{
 // Tau (number) 
 tau: 0.0001140771161,
 // Risk Aversion Parameter (double as number) 
 riskAversionParameter: "0.001",
 // Risk model parameters for log normal
 params: {
  // Mu param (double as number) 
  mu: 0,
  // R param (double as number) 
  r: 0.016,
  // Sigma param (double as number) 
  sigma: 0.8,
 }
}
The risk model uses the following properties:
FieldDescriptionSample value
tauProjection horizon measured as a year fraction used in the expected shortfall calculation to obtain the maintenance margin.

Accepted values: any strictly non-negative real number; suggested value: 0.000114077116130504 - corresponds to one hour expressed as year fraction		0.000114077116130504
riskAversionParameterProbability confidence level used in expected shortfall calculation when obtaining the maintenance margin level. First, the value at risk, defined by confidence lambda is calculated. This is the cash amount that one would need to add to the position to make the probability of the value of the position and cash going negative after time tau to be less than lambda. The margin is then the expected loss of the position given that it incurred a loss bigger than the value at risk.

Accepted values: strictly greater than 0 and strictly smaller than 1		0.00001
param: muAnnualised growth rate of the underlying asset.

Accepted values: any real number		0
param: rAnnualised growth rate of the risk-free asset, it's used for discounting of future cash flows. Use 0.0 unless otherwise required.

Accepted values: any real number		0.0
param: sigmaAnnualised historic volatility of the underlying asset.

Accepted values: any strictly non-negative real number; suggested value: asset dependent, should be derived from the historical time-series of prices.		0.8 (converts to 80%)

Liquidity SLA parameters​

The liquidity parameters set the requirements that liquidity providers on the market must meet in order to avoid being penalised and to earn fee revenue.

FieldDescriptionSample value
liquiditySlaParametersParameters for minimum requirements and measurements
priceRangeSets the percentage move up and down from the mid price that LPs must be within to count towards their commitment0.1
commitmentMinTimeFractionThe minimum fraction of time that LPs must spend on the book and within the price range0.1
performanceHysteresisEpochsSets the number of epochs over which past performance will continue to affect rewards.10
slaCompetitionFactorSets the maximum fraction of their accrued fees an LP that meets the SLA will lose to liquidity providers that achieved a higher SLA performance than them.0.2

Templates and submitting​

In the tabs below you'll see:

  • Annotated example describing what each field is for
  • JSON example that can be submitted with the governance dApp β†—
  • Command line examples for different operating systems

Replace the example data with the relevant details before submitting.

{
 rationale: {
  title: "Lorem Ipsum perpetual",
  description: "An orange perpetual market"
 },
 terms: {
  newMarket: {
   changes: {
    // Linear slippage factor is used to cap the slippage component of maintenance margin - it is applied to the slippage volume.
    linearSlippageFactor: 0.001,

    // Decimal places used for the new futures market, sets the smallest price increment on the book. (uint64 as string)
    decimalPlaces: "5",

    // Decimal places for order sizes, sets what size the smallest order / position on the futures market can be. (int64 as string)
    positionDecimalPlaces: "5",

    // Instrument configuration
    instrument: {
     // Instrument name.
     name: "Oranges Perpetual",

     // Instrument code, human-readable shortcode used to describe the instrument.
     code: "ORANGES.PERP",

     // Perpetual product configuration
     perpetual: {
      // Asset ID for the product's settlement asset.
      settlementAsset: "c9fe6fc24fce121b2cc72680543a886055abb560043fda394ba5376203b7527d",

      // Product quote name.
      quoteName: "USD",

      // Controls how much the upcoming funding payment liability contributes to party's margin, in the range [0, 1].
      marginFundingFactor: "0.9",

      // Continuously compounded interest rate used in funding rate calculation, in the range [-1, 1].
      interestRate: "0",

      // Lower bound for the clamp function used as part of the funding rate calculation, in the range [-1, 1].
      clampLowerBound: "0",

      // Upper bound for the clamp function used as part of the funding rate calculation, in the range [-1, 1].
      clampUpperBound: "0",
      dataSourceSpecForSettlementData: {
       // DataSourceDefinitionExternal is the top level object used for all external 
       // data sources. It contains one of any of the defined `SourceType` variants. 
       external: {
        // Contains the data specification that is received from Ethereum sources.
        ethOracle: {
         // The ID of the EVM based chain which is to be used to source the oracle data. (uint64 as string)
         // The ID of the EVM based chain which is to be used to source the oracle data. 
         sourceChainId: "1",

         // Ethereum address of the contract to call.
         address: "0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43",

         // The ABI of that contract.
         abi: "[{" inputs ":[]," name ":" latestAnswer "," outputs ":[{" internalType ":" int256 "," name ":" "," type ":" int256 "}]," stateMutability ":" view "," type ":" function "}]",

         // Name of the method on the contract to call.
         method: "latestAnswer",


         /* Normalisers are used to convert the data returned from the contract method
          * into a standard format. The key of the map is the name of the property,
          * which identifies the specific piece of data to other parts of the data
          * sourcing framework, for example filters. The value is a JSONPath expression
          * for expressing where in the contract call result the required data is
          * located, for example $[0] indicates the first result. $[1].price would look
          * in the second result returned from the contract for a structure with a key
          * called 'price' and use that if it exists. */
         normalisers: [
          {
           name: "prices.ORANGES.value",
           expression: "$[0]"
          }
         ],

         // Number of confirmations required before the query is considered verified
         requiredConfirmations: 3,

         // Conditions for determining when to call the contract method.
         trigger: {
          /* Trigger for an Ethereum call based on the Ethereum block timestamp. Can be
           * one-off or repeating. */
          timeTrigger: {
           /* Repeat the call every n seconds after the initial call. If no time for
            * initial call was specified, begin repeating immediately. */
           every: 30
          }
         },

         // Filters the data returned from the contract method
         filters: [
          {
           key: {
            name: "prices.ORANGES.value",
            type: "TYPE_INTEGER",
            numberDecimalPlaces: 8
           },
           conditions: [
            {
             operator: "OPERATOR_GREATER_THAN_OR_EQUAL",
             value: "0"
            }
           ]
          }
         ]
        }
       }
      },
      dataSourceSpecForSettlementSchedule: {
       internal: {
        timeTrigger: {
         conditions: [
          {
           operator: "OPERATOR_GREATER_THAN_OR_EQUAL",
           value: "0"
          }
         ],
         triggers: [
          {
           every: 28800
          }
         ]
        }
       }
      },


      /* undefined */
      dataSourceSpecBinding: {
       /* 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. */
       settlementDataProperty: "prices.ORANGES.value",
       settlementScheduleProperty: "vegaprotocol.builtin.timetrigger"
      }
     },

     // Optional new futures market metadata, tags.
     metadata: [
      "enactment:2024-02-18T17:18:38Z",
      "settlement:2024-02-17T17:18:38Z",
      "source:docs.vega.xyz"
     ],

     // PriceMonitoringParameters contains a collection of triggers to be used for a given market
     priceMonitoringParameters: {
      // PriceMonitoringTrigger holds together price projection horizon Ο„, probability level p, and auction extension duration
      triggers: [
       {
        // Price monitoring projection horizon Ο„ in seconds. (int64 as string)
        horizon: "43200",

        // Price monitoring probability level p. (string)
        probability: "0.9999999",

        // Price monitoring auction extension duration in seconds should the price
        // breach its theoretical level over the specified horizon at the specified
        // probability level. (int64 as string)
        auctionExtension: "600",
       }
      ]
     },

     // Risk model for log normal
     logNormal: {
      // 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.(number) tau: 0.0001140771161,

      // Risk Aversion Parameter. (double as number)
      riskAversionParameter: "0.01",

      // Risk model parameters for log normal
      params: {
       // Mu parameter, annualised growth rate of the underlying asset. (double as number)
       mu: 0,

       // R parameter, annualised growth rate of the risk-free asset, used for discounting of future cash flows, can be any real number. (double as number)
       r: 0.016,

       // Sigma parameter, annualised volatility of the underlying asset, must be a strictly non-negative real number. (double as number)
       sigma: 0.15,
      }
     },

     // Liquidity SLA parameters
     liquiditySlaParameters: {
      // (string)
      priceRange: 0.1,

      // Specifies the minimum fraction of time LPs must spend "on the book" providing their committed liquidity. (string)
      commitmentMinTimeFraction: "0.1",

      // Specifies the number of liquidity epochs over which past performance will continue to affect rewards. (uint64 as string)
      performanceHysteresisEpochs: "10",

      // 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)
      slaCompetitionFactor: "0.2",
     },
    }
   },

   // Timestamp as Unix time in seconds when voting closes for this proposal,
   // constrained by `minClose` and `maxClose` network parameters. (int64 as string)
   closingTimestamp: 1708190318,

   // Timestamp as Unix time in seconds when proposal gets enacted if passed,
   // constrained by `minEnact` and `maxEnact` network parameters. (int64 as string)
   enactmentTimestamp: 1708276718,
  }
 }

Voting​

All proposals are voted on by the community.

To vote, community members need, at a minimum, the larger of πŸ”—1 token or πŸ”—1 token associated to their Vega key. Proposers who invite feedback, engage with comments, and make revisions to meet the needs of the community are more likely to be successful.

Enactment​

If successful, the proposal will be enacted at the time you specify in the enactmentTimestamp field.