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

Propose a new market

Propose a cash-settled futures market on any underlying with a settlement data source.

Requirements​

You will need:

Anatomy of a market proposal​

In this section, the full proposal template has been divided into sections to provide more details on what you need to submit.

There are a number of fields required for proposing a market to ensure that it has all the necessary details and research behind it to be a well-functioning market.

The general shape is as follows:

{
 rationale: {
  title: "Add Lorem Ipsum market",
  description: "An example proposal to add Lorem Ipsum market"
 },
 terms: {
  newMarket: {
   changes: {
    // Percentage move up and down from the mid price which specifies the range of 
    // price levels over which automated liquidity provision orders will be deployed
    lpPriceRange: "10",
    // Linear slippage factor is used to cap the slippage component of maintainence margin - it is applied to the slippage volume
    linearSlippageFactor: 0.001,
    // Quadratic slippage factor is used to cap the slippage component of maintainence margin - it is applied to the square of the slippage volume
    quadraticSlippageFactor: 0,
    // Decimal places used for the new 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 market can be (int64 as string)
    positionDecimalPlaces: "5",
    // New market instrument configuration
    instrument: {},
    // Optional new market metadata, tags
    metadata: [],
    // Price monitoring parameters
    priceMonitoringParameters: [],
    // Liquidity monitoring parameters
    liquidityMonitoringParameters: {},
    // Log normal risk model parameters, valid only if MODEL_LOG_NORMAL is selected
    logNormal: {},
   }
  },
  // Timestamp (Unix time in seconds) when voting closes for this proposal,
  // constrained by `minClose` and `maxClose` network parameters (int64 as string)
  closingTimestamp: 1680534013000,
  // Timestamp (Unix time in seconds) when proposal gets enacted (if passed),
  // constrained by `minEnact` and `maxEnact` network parameters (int64 as string)
  enactmentTimestamp: 1680620413000,
 }
}

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, data sources, and liquidity commitment are all described in more detail below.

Rationale requires a description, which is a free-text field that describes the purpose of the proposal. 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.

LP price range is a number that, when multiplied by 100, determines the percentage move up and down from the mid price, which determines the range of price levels over which automated liquidity commitment orders will be deployed. An accepted value is > 0 and <= 100.

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.

FieldDescriptionExample
decimalPlacesSets the smallest price increment on the book.18
positionDecimalPlacesSets how big the smallest order / position on the market can be.5

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. The chosen time must be between 👀1m0s and 👀720h after the proposal submission time. (int64 as string)1663517914
enactmentTimestamp Timestamp (Unix time in seconds) when the market will be enacted, ready for trading. The chosen time must be between 👀2m0s 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​

The instrument shape is as follows, see below for a description of each property:

{
 // Instrument name
 name: "Oranges Daily",
 // Instrument code, human-readable shortcode used to describe the instrument
 code: "ORANGES.24h",
 // Future
 future: {
  // Asset ID for the product's settlement asset (string)
  settlementAsset: "8b52d4a3a4b0ffe733cddbc2b67be273816cfeb6ca4c8b339bac03ffba08e4e4",
  // Product quote name (string)
  quoteName: "tEuro",
  // The data source spec describing the data source for settlement (object)
  dataSourceSpecForSettlementData: {
   external: {
    oracle: {
     // signers is the list of authorized signatures that signed the data for this
     // source. All the signatures in the data source data should be contained in this (array of objects)
     signers: [
      {
       ethAddress: {
        address: "0xfCEAdAFab14d46e20144F48824d0C09B1a03F2BC"
       }
      }
     ],
     // filters describes which source data are considered of interest or not for
     // the product (or the risk model).
     filters: [
      key: {
       // name is the name of the property. (string)
       name: "prices.BTC.value",
       // type is the type of the property. (string)
       type: "TYPE_INTEGER",
       // An optional decimal place to be be applied on the provided value
       // valid only for PropertyType of type DECIMAL and INTEGER
       numberDecimalPlaces: "5",
      },
      // conditions are the conditions that should be matched by the data to be
      // considered of interest.
      conditions: [
       {
        // comparator is the type of comparison to make on the value. (string)
        operator: "OPERATOR_GREATER_THAN",
        // value is used by the comparator. (string)
        value: "0",
       }
      ]
     },
     {
      key: {
       name: "prices.BTC.timestamp",
       type: "TYPE_TIMESTAMP",
      },
      conditions: [
       {
        operator: "OPERATOR_GREATER_THAN",
        value: "1648684800000000000",
       }
      ]
     }
    ]
   }
  },
  // The external data source spec describing the data source of trading termination (object)
  dataSourceSpecForTradingTermination: {},
  // The binding between the data source spec and the settlement data (object)
  dataSourceSpecBinding: {
   // settlement_data_property holds the 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)
   settlementDataProperty: "prices.BTC.value",
   // the name of the property in the data source data that signals termination of trading (string)
   tradingTerminationProperty: "vega.builtin.timestamp"
  }
 }

An instrument contains the following properties:

FieldDescriptionExample
nameA string for the market name. Best practice is to include a full and fairly descriptive name for the instrument.BTC/USD 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
futureAn object that provides details about the futures 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
dataSourceSpecForSettlementDataThis defines the data source that will be used to identify the settlement price when the market expires.prices.BTC.value
dataSourceSpecForTradingTerminationThe fields that define the data source used for terminating trading on the market.vegaprotocol.builtin.timestamp
dataSourceSpecBindingThe fields describe how specific information provided by the data source is used. For example, they can identify the specific name of the settlement price output, or the specific name of the trading termination property.

For easy reading, the data source filters are separated out - see Data source bindings below to see the fields for specifying data.

Data source bindings​

Data feeds from an oracle can be used to terminate trading and settle markets. See below for a full description of each field. A data source spec binding looks like this:

{
 // DataSourceDefinition represents the top level object that deals with data sources.
 // DataSourceDefinition can be external or internal, with whatever number of data sources are defined
 internal {
  // DataSourceSpecConfigurationTime is the internal data source used for emitting timestamps.
  time: {
   // Conditions that the timestamps should meet in order to be considered.
   conditions: [
    {
     // comparator is the type of comparison to make on the value. (string)
     operator: "OPERATOR_GREATER_THAN_OR_EQUAL",
     // value is used by the comparator. (string)
     value: "1648684800000000000",
    }
   ]
  }
 }

Data source bindings include the following properties:

FieldDescriptionExample
pubKeysPublic key(s) that can sign and submit values for this data source0xfCEAdAFab14d46e20144F48824d0C09B1a03F2BC
filtersFilters define what data is of importance for the purposes of the type of governance proposal
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
nameSpecific name of the information that the filter provides.prices.ETH.value
typeSpecifies the data type that is emitted. For example, for the prices.ETH.value, the type is an integer, as it is output as a non-fractional numberTYPE_TIMESTAMP
numberDecimalPlacesOptional field to specify the precision in which numerical data is emitted. Use when data is numerical18
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 operator0
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.

 {
  // Specifies parameters related to target stake calculation
  targetStakeParameters: {
   // Specifies length of time window expressed in seconds for target stake calculation (string)
   timeWindow: "3600",
   // Specifies scaling factors used in target stake calculation (number)
   scalingFactor: 10
  },
  // Specifies the triggering ratio for entering liquidity auction (undefined as string)
  triggeringRatio: "0.7",
  // Specifies by how many seconds an auction should be extended if leaving the auction were to trigger a liquidity auction (int64 as string)
  auctionExtension: "1",
 }
}

Liquidity monitoring uses the following properties:

FieldDescriptionExample
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
scalingFactorThis must be set within the range defined by the network parameter 👀market.stake.target.scalingFactor, and defines the scaling between the liquidity demand estimate, based on open interest and target stake. 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.70.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. 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:

FieldDescriptionExample
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

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:
FieldDescriptionSuggested 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.

Accepted values: any real number		0
param: sigmaAnnualised 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%)

Templates and submitting​

In the tabs below you'll see an annotated example, which describes what each field is for, a JSON example that can be used as the basis to submit on the governance dApp ↗, and command line examples for different operating systems. You'll need to replace the example data with the relevant details before submitting.

{
 rationale: {
  title: "Add Lorem Ipsum market",
  description: "An example proposal to add Lorem Ipsum market"
 },
 terms: {
  newMarket: {
   changes: {
    // Percentage move up and down from the mid price which specifies the range of 
    // price levels over which automated liquidity provision orders will be deployed
    lpPriceRange: "10",

    // Linear slippage factor is used to cap the slippage component of maintainence margin - it is applied to the slippage volume
    linearSlippageFactor: 0.001,

    // Quadratic slippage factor is used to cap the slippage component of maintainence margin - it is applied to the square of the slippage volume
    quadraticSlippageFactor: 0,

    // Decimal places used for the new 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 market can be (int64 as string)
    positionDecimalPlaces: "5",

    // New market instrument configuration
    instrument: {
     // Instrument name
     name: "Oranges Daily",

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

     // Future
     future: {
      // Asset ID for the product's settlement asset (string)
      settlementAsset: "8b52d4a3a4b0ffe733cddbc2b67be273816cfeb6ca4c8b339bac03ffba08e4e4",

      // Product quote name (string)
      quoteName: "tEuro",

      // The data source spec describing the data source for settlement (object)
      dataSourceSpecForSettlementData: {
       external: {
        oracle: {
         // signers is the list of authorized signatures that signed the data for this
         // source. All the signatures in the data source data should be contained in this (array of objects)
         signers: [
          {
           ethAddress: {
            address: "0xfCEAdAFab14d46e20144F48824d0C09B1a03F2BC"
           }
          }
         ],

         // filters describes which source data are considered of interest or not for
         // the product (or the risk model).
         filters: [
          key: {
           // name is the name of the property. (string)
           name: "prices.BTC.value",

           // type is the type of the property. (string)
           type: "TYPE_INTEGER",

           // An optional decimal place to be be applied on the provided value
           // valid only for PropertyType of type DECIMAL and INTEGER
           numberDecimalPlaces: "5",
          },

          // conditions are the conditions that should be matched by the data to be
          // considered of interest.
          conditions: [
           {
            // comparator is the type of comparison to make on the value. (string)
            operator: "OPERATOR_GREATER_THAN",

            // value is used by the comparator. (string)
            value: "0",
           }
          ]
         },
         {
          key: {
           name: "prices.BTC.timestamp",
           type: "TYPE_TIMESTAMP",
          },
          conditions: [
           {
            operator: "OPERATOR_GREATER_THAN",
            value: "1648684800000000000",
           }
          ]
         }
        ]
       }
      },

      // The external data source spec describing the data source of trading termination (object)
      dataSourceSpecForTradingTermination: {
       // DataSourceDefinition represents the top level object that deals with data sources.
       // DataSourceDefinition can be external or internal, with whatever number of data sources are defined
       internal {
        // DataSourceSpecConfigurationTime is the internal data source used for emitting timestamps.
        time: {
         // Conditions that the timestamps should meet in order to be considered.
         conditions: [
          {
           // comparator is the type of comparison to make on the value. (string)
           operator: "OPERATOR_GREATER_THAN_OR_EQUAL",

           // value is used by the comparator. (string)
           value: "1648684800000000000",
          }
         ]
        }
       },

       // The binding between the data source spec and the settlement data (object)
       dataSourceSpecBinding: {
        // settlement_data_property holds the 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)
        settlementDataProperty: "prices.BTC.value",

        // the name of the property in the data source data that signals termination of trading (string)
        tradingTerminationProperty: "vega.builtin.timestamp"
       }
      },

      // Optional new market metadata, tags
      metadata: [
       "enactment:2023-04-04T17:00:13Z",
       "settlement:2023-04-03T17:00:13Z",
       "source:docs.vega.xyz"
      ],

      // Price monitoring parameters
      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",
        }
       ]
      },

      // Liquidity monitoring parameters
      liquidityMonitoringParameters: {
       // Specifies parameters related to target stake calculation
       targetStakeParameters: {
        // Specifies length of time window expressed in seconds for target stake calculation (string)
        timeWindow: "3600",

        // Specifies scaling factors used in target stake calculation (number)
        scalingFactor: 10
       },

       // Specifies the triggering ratio for entering liquidity auction (undefined as string)
       triggeringRatio: "0.7",

       // Specifies by how many seconds an auction should be extended if leaving the auction were to trigger a liquidity auction (int64 as string)
       auctionExtension: "1",
      }
     },

     // Log normal risk model parameters, valid only if MODEL_LOG_NORMAL is selected
     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.5,
      }
     },
    }
   },

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

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

Voting and enactment​

All proposals are voted on by the community. To vote, community members need, at a minimum, the larger of 👀more than 0 tokens, or 👀1 token associated with their Vega key.

Your proposal will need participation of 👀10% and a majority of 👀66%, so having community support is essential. If successful, the proposal will be enacted at the time you specify in the enactmentTimestamp field.

Building support is down to you. Share your proposal in the New Market Proposals forum ↗ on Vega community, being sure to follow the post guide ↗. You may also wish to share on Discord ↗.

Proposers who invite feedback, engage with comments, and make revisions to meet the needs of the community are more likely to be successful.