Market creation using governance

Introduction

A powerful feature of Vega is the ability to create markets using governance. In summary, users in the Vega community can propose and vote for markets using the governance asset of the network. For further background and explanation, please see the section on Market proposals and governance.

How do I propose a market?

To propose a market via the Vega APIs, a user must define a set of specific inputs as parameters. If all of the inputs pass validation, the market proposal will enter into a voting period, the length of which is set in the governance proposal, subject to minimums set as network parameters.

Once voted in, a market will be enacted and available on a Vega network.

At present the Vega testnet uses the tVOTE token for governance, which you will need to obtain and hold in your wallet to propose a market. Also, when a Vega testnet network reset occurs, any user proposed and enacted markets will also be reset. Markets will need to be recreated once the network has restarted.

1. Log in to wallet and get public key

See the section on the Wallet service to learn how to log in, list keys and select a public key.

For a working wallet example used by this how-to guide, please visit the API Samples GitHub repo.

2. Find a settlement asset

Pick from an existing settlement asset on Vega. Note: it is also possible to propose assets via governance.
In this example we’ve chosen an example asset named tDAI (other assets are available).

Gitpod ready-to-code What’s Gitpod?

See also REST API reference for further query detail.

If successful, the response will include:

Field Description
assets A list of zero or more assets available on the Vega network. Search the assets returned to find the unique identifier for the underlying asset needed in step 3. If this is already known, you may omit this step. Note: Asset identifiers are currently generated by the network and can change when networks are reset or upgraded.

3. Propose a new market

Create your proposal for a new market, taking care to craft it to your requirements. Please refer to the field descriptions found in the Market proposals and governance section. The current configuration of network parameters can also be loaded programmatically.

The current time on the Vega blockchain is required to accurately set validation, closing and enactment times (specified in seconds from the Unix epoch). Please see the how-to guide for Vega Time to learn more about blockchain time. For further guidance on timestamp ranges, please see the following points:

  • VALIDATION TIMESTAMP
    Defines a time period for which the Vega nodes perform validation on the proposal. Currently this is ignored for market creation but it must be set to a valid timestamp. In the example below we set it to 1 second past the current time on the blockchain. If valid, the proposal is considered active for a proposal period.

  • CLOSING TIMESTAMP
    A proposal will have a closing time specified as a timestamp. As mentioned above, once the proposal is active it is open for voting and will remain open until the specified closing time. The closing time has a minimum and maximum offset period as defined by the network parameters; governance.proposal.market.minClose and governance.proposal.market.maxClose.

  • ENACTMENT TIMESTAMP
    Once the proposal voting period has closed, all votes are counted and if successfully passed the proposal will enter a period of waiting before enactment. This is when the market goes live, it is said to be enacted. Enactment timestamp must be after the closing timestamp. The enactment time has a minimum and maximum offset period as defined by the network parameters; governance.proposal.market.minEnact and governance.proposal.market.maxEnact.

The following script snippets show an example BTC/DAI futures market proposal with calculated offsets using current blockchain time.
It is settled in the tDAI asset located in step 2.

If successful, the response will include:

Field Description
signature A signed transaction message containing the proposal data. If propagate is set to true, the signed data will be automatically forwarded by the wallet server to a node. If you wish to manually submit the transaction you can do so with the data in signature (tx) and set propagate to false.

Once the proposal has been signed and forwarded to a Vega node, the caller must wait for the proposal to be accepted by the Vega blockchain. The recommended wait time is at least 1 second. Please visit the API Samples GitHub repo for an example of waiting on a market proposal.

4. Vote for a market proposal

Participants will need to vote Yes on the new market proposal so that after the proposal period it can be successfully marked as passed. This will be the case as long as no other parties vote against the new market proposal and there are enough votes (see below). Once passed it will be scheduled to launch into an opening auction.

One participant’s Yes vote is typically not enough to pass a market, the voting majority required for a market to pass is defined by the network parameter; governance.proposal.market.requiredMajority and for reference the weighting calculation is as follows:

participation_rate
  = SUM (weightings of ALL valid votes cast)
     / max total weighting possible
     #  e.g. sum of token balances of all votes cast / total supply of governance asset

Votes are weighted by the total tVOTE asset held by the voter, with a minimum balance required to vote set by the network parameter; governance.proposal.market.minVoterBalance.

The total supply of governance asset on the Vega testnet is currently 6.4 million tVOTE and the minVoterBalance is set to the value 1 token. Due to tVOTE assets having a precision of 5 decimal places, this means that a participant must hold at least 0.00001 tVOTE.

Gitpod ready-to-code What’s Gitpod?

See also REST API reference for further query detail.

If successful, the response will include:

Field Description
signedTx A signed transaction message containing the vote data. In the same way as the market proposal message, if propagate is set to true, the signed data will be automatically forwarded by the wallet server to a node.

5. Wait for enactment of the market

After the voting period has elapsed, and if the majority of participants voted Yes, then you need to wait for the new market to be enacted. A simple way to do this is to wait for the new market to appear in the list of available Vega markets.

Gitpod ready-to-code What’s Gitpod?

See also REST API reference for further query detail.

If successful, the response will include:

Field Description
markets A list of zero or more markets including the newly enacted market. Note: there is a wait loop with a condition to find a market matching the proposal identifier. The loop will continue until the proposed market is found.

On Vega, newly proposed markets always start in auction mode as a way of ensuring a new market has a fair price at the start of trading. The auction duration is specified in the proposal (in this example it is 120 seconds), after which it will switch to continuous trading. The auction duration is subject to the network minimum which is found by requesting the network parameters.

Where do I find the current network parameters?

The current configuration of all network parameters can be requested from the APIs. Connect to a Vega API server, and request a list of network parameters:

Gitpod ready-to-code What’s Gitpod?

See also REST API reference for further query detail.

See also REST API reference for further query detail.

Make sure vegaapiclient is installed (from PyPI):

pip install --upgrade Vega-API-client

This Python snippet code shows how to query for network parameters:

See also gRPC API reference for further query detail.

If successful, the response will include:

Field Description
networkParameters A list of key/value pairs containing the current network parameters for a Vega network. Please refer to the field descriptions found in the Market proposals and governance section.

What’s next?