Skip to main content
Version: pre-release (v0.78)

Propose a new asset

This page provides a tutorial for submitting a proposal for a new ERC-20 asset to be used as collateral. It describes what can be proposed, what you need to propose a new asset, and provides proposal templates that you will need to edit before submitting.

Requirements​

You will need:

  • A connected Vega wallet, with your wallet name and public key to hand
  • A minimum of whichever is larger, associated with that public key, based on the network parameter values for governance.proposal.asset.minProposerBalance or spam.protection.proposal.min.tokens
  • Familiarity with governance on Vega.

After a new asset vote passes, the change has to be submitted to the asset bridge on Ethereum. Until it has been submitted, no one can start depositing that asset. See the tutorial for how to do that.

Overview​

The Vega software has support for using ERC-20 assets ↗. ERC-20 assets that pass a governance vote can be enabled via a given network's bridge - which is to say that they are deposited from and withdrawn to Ethereum.

Query for data

You can see all of the currently supported assets using the REST endpoint.

If an asset that you would like to see on a network is not already available, a governance proposal can be made to list the asset.

If the vote passes, the network's validators will then enable the asset on the bridge contract which will enable deposits and withdrawals for that token.

Anatomy of a new asset proposal​

The key inputs on a new asset proposal are as follows.

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.

Rationale requires a title and a description. They are free-text fields that describe the purpose of the proposal.

FieldDescriptionExample
nameName of the asset (string)Testnet DAI
symbolSymbol of the asset (string)tDAI
decimalsNumber of decimal / precision handled by this asset (string)18
chainIDID of the asset's originating chain (string)
quantumThe minimum economically meaningful amount of the asset (string). This should be the amount of the asset roughly equal to 1 USD. It is used in a number of ways by the protocol but only requires precision to an order of magnitude level. For example, if one BTC = 26,583 USD, then in this case a quantum of 1 / 25,000 or 0.00004 is sufficient. Converted to asset decimals it would be 40000000000000.1000000000000000000
withdrawThresholdThe maximum you can withdraw instantly. All withdrawals over the threshold will be delayed by the withdrawal delay, which can be seen on the ERC-20 bridge per asset. Setting this to 1 means all withdrawals will be subject to the delay. It's measured in asset decimals, so 1 is the smallest increment of the market's asset.1
lifetimeLimitThe lifetime deposit limit per public key, in asset decimals. Users are able to opt out of this functionality using the exempt_depositor write function on the ERC20 contract if they wish to. Suggested value: equivalent of 10,000 USD10000000000000000000000

ERC-20 asset validation​

When adding an ERC-20 asset to a bridge, the key details are compared to the smart contract on Ethereum. Specifically:

  • The name and symbol must match
  • The contract must be an ERC-20 asset
  • There cannot be multiple assets for the same ERC-20 asset

Validation happens according to the validationTimestamp parameter. The validation timestamp must be within the range between 1 second and 2 days from the time of submission. In most situations, this should be early on in the voting period so that any validation errors are caught before token holders start voting. However you could push the validation later in that range if the contract is not yet deployed.

Submitting proposals in a batch​

When including a new asset proposal in a batch, the entire proposal will not be enacted until the asset's validation has succeeded. If the asset validation fails, the entire proposal fails.

At top level, one closing timestamp. Inside batch each proposal has own enactment. Now a new asset has a validation stamp, only if new asset. If it’s there, there’s a new validation flow, and then once that passes, the whole batch goes through. So the whole batch is on standby.

If you want to submit this proposal as part of a larger batch of proposals, follow this sample structure:

{
  "batchProposalSubmission": {
    "rationale": {
      "title": "High level title",
      "description": "Description of all parts of this batch of proposals"
    },
    "terms": {
      "closingTimestamp": "123",
      "changes": [
        {
          "enactmentTimestamp": "123",
          "validationTimestamp": "654",
          "newAsset": {
            "changes": {
              "name": "asset",
              "symbol": "tSYM",
              "decimals": "18",
              "quantum": "1",
              "erc20": {
                "chainId": "1",
                "contractAddress": "0xaddress",
                "withdrawThreshold": "10",
                "lifetimeLimit": "10"
              }
            }
          }
        },
        {
          "enactmentTimestamp": "123",
          "cancelTransfer": {
            "changes": {
              "transferId": "789"
            }
          }
        }
      ]
    }
  }
}

Templates and submitting​

In the tabs below you'll see:

  • Annotated example describing what each field is for
  • JSON example
  • Command line examples for different operating systems

Replace the example data with the relevant details before submitting.

{
 proposalSubmission: {
  rationale: {
   title: "Add tDAI TEST (tDAI)",
   description: "Proposal to add tDAI TEST (tDAI) as an asset"
  },
  terms: {
   newAsset: {
    changes: {
     // Name of the asset (e.g: Great British Pound). (string) 
     name: "tDAI TEST",

     // Symbol of the asset (e.g: GBP). (string) 
     symbol: "tDAI",

     // Number of decimal / precision handled by this asset. (string) 
     decimals: "18",

     // Minimum economically meaningful amount in the asset. (string) 
     quantum: "1",

     // ERC20 token based asset, living on the ethereum network
     erc20: {
      // Chain ID the asset originated from. (string)
      chainId: "1",

      // Address of the contract for the token, on the ethereum network. (string)
      contractAddress: "0x26223f9C67871CFcEa329975f7BC0C9cB8FBDb9b",

      // Maximum you can withdraw instantly. All withdrawals over the threshold will be delayed by the withdrawal delay.
      // There’s no limit on the size of a withdrawal (string)
      withdrawThreshold: "10",

      // Lifetime limits deposit per address
      // note: this is a temporary measure that can be changed by governance. (string)
      lifetimeLimit: "10",
     }
    }
   },

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

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

   // Validation timestamp as Unix time in seconds. (int64 as string)
   validationTimestamp: 1728476138
  }
 }
}

Voting​

All proposals are voted on by the community.

To vote, community members need, at a minimum, the larger of the values of the following network parameters: governance.proposal.asset.minVoterBalance or spam.protection.voting.min.tokens associated with their Vega key.

Your proposal will need participation at a minimum of the value of the network parameter governance.proposal.asset.requiredParticipation and a majority that meets or exceeds the value of the network parameter <NetworkParameter frontMatter={frontMatter} param="governance.proposal.asset.requiredMajority".

Enactment​

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