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

commands.proto

path vega/commands/v1/commands.proto

package vega.commands.v1


Messages

AmendAMM

Command to amend an existing automated market maker on a market.

NameTypeDescription
market_idstringMarket ID for the AMM to be amended.
commitment_amountoptional stringAmount to be committed to the AMM. If not supplied the commitment will remain unchanged.
slippage_tolerancestringSlippage tolerance for rebasing position when updating the AMM.
concentrated_liquidity_parametersoptional AmendAMM.ConcentratedLiquidityParametersConcentrated liquidity parameters defining the shape of the AMM's volume curves. If not supplied the parameters will remain unchanged.
proposed_feeoptional stringNominated liquidity fee factor, which is an input to the calculation of taker fees on the market. If not supplied the proposed fee will remain unchanged.

AmendAMM.ConcentratedLiquidityParameters

Liquidity parameters that define the size and range of the AMM's tradeable volume.

NameTypeDescription
upper_boundoptional stringPrice at which the AMM will stop quoting sell volume. If not supplied the AMM will never hold a short position.
lower_boundoptional stringPrice at which the AMM will stop quoting buy volume. If not supplied the AMM will never hold a long position.
basestringPrice that the AMM will quote as its "fair price" when its position is zero.
leverage_at_upper_boundoptional stringLeverage at upper bound. If not set the markets risk-factors will be used to calculate leverage.
leverage_at_lower_boundoptional stringLeverage at lower bound. If not set the markets risk-factors will be used to calculate leverage.

ApplyReferralCode

Command that allows the submitter to join a referral set and earn a collective reduction in fees based on the activity of all members of that set. A party that joins a referral set is called a referee. A referee can only be a member of one referral set and cannot themselves be or become a referrer. To switch to another referral set, a subsequent command can be sent and the switch will take effect at the end of the epoch.

NameTypeDescription
idstringReferral code, normally the referral set ID, for the party to join.
do_not_join_teamboolShould the key applying the referral code also join the team. the default is false so the existing behaviour is kept if older versions of the protobufs are used.

BatchMarketInstructions

A command that allows the submission of a batch market instruction which wraps up multiple market instructions into a single transaction. These instructions are then processed sequentially in the following order: - OrderCancellation - OrderAmendment - OrderSubmission - StopOrderSubmission where the maximum allow of instructions in a batch is controlled by the network parameter "spam.protection.max.batchSize".

NameTypeDescription
cancellationsrepeated OrderCancellationList of order cancellations to be processed sequentially.
amendmentsrepeated OrderAmendmentList of order amendments to be processed sequentially.
submissionsrepeated OrderSubmissionList of order submissions to be processed sequentially.
stop_orders_cancellationrepeated StopOrdersCancellationList of stop order cancellations to be processed sequentially.
stop_orders_submissionrepeated StopOrdersSubmissionList of stop order submissions to be processed sequentially.
update_margin_moderepeated UpdateMarginModeUpdate margin mode instruction

BatchProposalSubmission

Command that allows a token holder to submit a batch governance proposal that can be voted on by any other token holders, and eventually enacted on the Vega network. For example this command can be used to propose a new market and a network parameter change with it.

NameTypeDescription
referencestringArbitrary human-readable reference identifying the proposal.
termsBatchProposalSubmissionTermsProposal terms containing the type and details of the proposal, as well as time spans for voting and enactment.
rationalevega.ProposalRationaleRationale behind a proposal.

BatchProposalSubmissionTerms

Terms for a batch governance proposal submission

NameTypeDescription
closing_timestampint64Closing timestamp in Unix time; adheres to `minClose` and `maxClose` limits.
changesrepeated vega.BatchProposalTermsChangeList of individual changes included in the batch proposal.

CancelAMM

Command to cancel an automated market maker for a given market.

NameTypeDescription
market_idstringMarket ID to cancel an AMM for.
methodCancelAMM.MethodMethod to use to cancel the AMM.

CancelTransfer

Command that can be used by the party that initiated a transfer to instruct the network to stop an active recurring transaction.

NameTypeDescription
transfer_idstringTransfer ID of the transfer to cancel.

CreateReferralSet

Command that a party can use to instruct the network to create a new referral set on the network. The submitter of this command will become the referrer of the new set and cannot be the referrer or a referee of another set. A referrer can use the referral set ID as a referral code to attract others to the Vega network and have fees reduced for the referral set.

NameTypeDescription
is_teamboolWhether or not the referral set should be considered a team that can participate in team games on the network.
teamoptional CreateReferralSet.TeamTeam details, if the referral set is to be considered a team.
do_not_create_referral_setboolShould a referral set be created as well or only a team. the default is false so the existing behaviour is kept if older versions of the protobufs are used.

CreateReferralSet.Team

NameTypeDescription
namestringName of the team.
team_urloptional stringExternal link to the team's homepage.
avatar_urloptional stringExternal link to an avatar for the team.
closedboolWhether or not the team is closed to new party members.
allow_listrepeated stringList of public keys that are allowed to join the team. Only applicable to closed teams. Removing a party from the allow list does not remove the party from the team.

DelayedTransactionsWrapper

Internal transactions used to convey delayed transactions to be included in the next block.

NameTypeDescription
transactionsrepeated bytes
heightuint64

DelegateSubmission

Command to allow a token holder to delegate their tokens to a validator to help secure the network. A token holder delegating to a validator will earn rewards based on the amount they have delegated, and the performance of the chosen validator.

NameTypeDescription
node_idstringNode ID to delegate stake to.
amountstringAmount of stake to delegate, as an unsigned integer scaled to the governance asset's decimal places.

IcebergOpts

Iceberg order options

NameTypeDescription
peak_sizeuint64Size of the order that is made visible and can be traded with during the execution of a single order.
minimum_visible_sizeuint64Minimum allowed remaining size of the order before it is replenished back to its peak size.

IssueSignatures

Command that can be used by a validator to instruct the network to generate signatures to add or remove validators from the multisig-control contract. Signatures can only be generated for validator nodes that have been promoted or demoted from the consensus validator set, and any attempt to generate signatures for another node will be rejected. The generated signatures can only be submitted to the contract by the Ethereum addresses included in the command.

NameTypeDescription
submitterstringEthereum address which will submit the signatures to the smart contract.
kindNodeSignatureKindWhat kind of signatures to generate, namely for whether a signer is being added or removed.
validator_node_idstringNode ID of the validator node that will be signed in or out of the smart contract.
chain_idstringChain ID of the bridge to generate signatures for.

JoinTeam

Command that allows the submitter to join a team or change teams if they are already a member of a team.

NameTypeDescription
idstringID of the team to join, this is the same as the referral code used to generate the team.

LiquidityProvisionAmendment

Command that allows a liquidity provider to update the details of their existing liquidity commitment. Any field that is left unset or as a default value indicates that this field on the original submission will be left unchanged.

NameTypeDescription
market_idstringMarket that the submitter wants to amend the liquidity commitment for.
commitment_amountstringNew commitment amount.
feestringNew nominated liquidity fee factor.
referencestringNew arbitrary reference to be added to every order created out of this liquidity provision submission.

LiquidityProvisionCancellation

Command that allows a liquidity provider to inform the network that they will stop providing liquidity for a market.

NameTypeDescription
market_idstringMarket that the submitter will stop providing liquidity for.

LiquidityProvisionSubmission

A command that indicates to the network the party's intention to supply liquidity to the given market and become a liquidity provider. An active liquidity provider for a market will earn fees based on the trades that occur in the market.

NameTypeDescription
market_idstringMarket that the submitter wishes to provide liquidity for.
commitment_amountstringAmount that the submitter will commit as liquidity to the market, specified as a unitless number in the settlement asset of the market. This field is an unsigned integer scaled using the asset's decimal places.
feestringNominated liquidity fee factor, which is an input to the calculation of taker fees on the market, as per setting fees and rewarding liquidity providers.
referencestringArbitrary reference to be added to every order created out of this liquidity provision submission.

OneOffTransfer

Details for a one-off transfer.

NameTypeDescription
deliver_onint64Timestamp, in Unix nanoseconds, for when the transfer should be executed, i.e., assets transferred into the receiver's account.

OrderAmendment

A command that allows a party to update the details of an existing order. Any field that is left unset or as a default value indicates that this field on the original order will be left unchanged. It is not possible to change an order's type through this command.

NameTypeDescription
order_idstringID of the order to amend.
market_idstringMarket ID that the order was originally submitted to.
priceoptional stringNew price for the order. This field is an unsigned integer scaled to the market's decimal places.
size_deltaint64Amend the size for the order by the delta specified: - To reduce the size from the current value set a negative integer value - To increase the size from the current value, set a positive integer value - To leave the size unchanged set a value of zero This field needs to be scaled using the market's position decimal places. If specified, size must not be set.
expires_atoptional int64Timestamp, in Unix nanoseconds, for the new expiry time for the order.
time_in_forcevega.Order.TimeInForceNew time in force for the order.
pegged_offsetstringNew pegged offset for the order. This field is an unsigned integer scaled to the market's decimal places.
pegged_referencevega.PeggedReferenceNew pegged reference for the order.
sizeoptional uint64New size for the order. Amending the size causes the size and remaining part of the order to be changed by the difference between the original and amended size. - Specifying a size smaller than the current size leaves the order at its current order book position. - Specifying a size larger than the current size removes and reinserts the order at the back of the price level. - Specifying a size that results in the remaining part of the order being reduced to zero cancels the order. This field is an unsigned integer scaled to the market's decimal places. If specified, size_delta must be set to 0.

OrderCancellation

A command that instructs the network to cancel orders, active or partially filled, that were previously submitted by the sender of this transaction. It is not possible to cancel another party's order with this command.

NameTypeDescription
order_idstringRestrict cancellations to an order with the given ID. If set, then a market ID must also be provided.
market_idstringRestrict cancellations to those submitted to the given market. If not set, all stop orders across all markets will be cancelled.

OrderSubmission

A command that submits an order to the Vega network for a given market.

NameTypeDescription
market_idstringMarket ID to submit the order to.
pricestringPrice for the order, the price is an integer, for example `123456` is a correctly formatted price of `1.23456` assuming market configured to 5 decimal places, required field for limit orders, however it is not required for market orders. This field is an unsigned integer scaled to the market's decimal places.
sizeuint64Size for the order, for example, in a futures market the size equals the number of units.
sidevega.SideWhich side of the order book the order is for, e.g. buy or sell.
time_in_forcevega.Order.TimeInForceTime in force indicates how long an order will remain active before it is executed or expires..
expires_atint64Timestamp, in Unix nanoseconds, for when the order will expire. Can only be set when the order's time-in-force is GTT.
typevega.Order.TypeType of the order.
referencestringArbitrary optional reference for the order, to be used as a human-readable non-unique identifier for the order.
pegged_ordervega.PeggedOrderPegged order details. If set, the order's price will be offset from a particular reference price of the order book at all times.
post_onlyboolIf set, the order will only be executed if it would not trade on entry to the order book. Only valid for limit orders.
reduce_onlyboolIf set, the order will only be executed if the outcome of the trade moves the trader's position closer to 0. Only valid for non-persistent orders.
iceberg_optsoptional IcebergOptsIceberg order details. If set, the order will exist on the order book in chunks.

ProposalSubmission

Command that allows a token holder to submit a governance proposal that can be voted on by any other token holders, and eventually enacted on the Vega network. For example this command can be used to propose a new market.

NameTypeDescription
referencestringArbitrary human-readable reference identifying the proposal.
termsvega.ProposalTermsProposal terms containing the type and details of the proposal, as well as time spans for voting and enactment.
rationalevega.ProposalRationaleRationale behind a proposal.

RecurringTransfer

Details for a recurring transfer

NameTypeDescription
start_epochuint64First epoch from which this transfer shall be executed.
end_epochoptional uint64Last epoch at which this transfer shall be executed.
factorstringFactor that the initial transfer amount is multiplied by for each epoch that it is executed. For example if the initial transfer amount is 1000 and the factor is 0.5, then the amounts transferred per epoch will be 1000, 500, 250, 125, etc.
dispatch_strategyvega.DispatchStrategyOptional parameter defining how a transfer is dispatched.

StopOrderSetup

Price and expiry configuration for a stop order.

NameTypeDescription
order_submissionOrderSubmissionOrder to be submitted once the trigger is breached.
expires_atoptional int64Timestamp, in Unix nanoseconds, for when the stop order should expire. If not set the stop order will not expire.
expiry_strategyoptional vega.StopOrder.ExpiryStrategyStrategy to adopt if the expiry time is reached.
size_override_settingoptional vega.StopOrder.SizeOverrideSettingIndicates if this order is linked to an order or position to derive the order size
size_override_valueoptional vega.StopOrder.SizeOverrideValueIf this order is linked to a position, provide an optional scaling factor
pricestringOrder will be submitted if the last traded price on the market breaches the given price.
trailing_percent_offsetstringOrder will be submitted if the last traded price has moved the given percent from the highest/lowest mark price since the stop order was submitted.

StopOrdersCancellation

A command that instructs the network to cancel untriggered stop orders that were submitted by the sender of this transaction. If any cancelled stop order is part of an OCO, both stop orders will be cancelled. It is not possible to cancel another party's stop orders with this command.

NameTypeDescription
market_idoptional stringRestrict cancellations to those submitted to the given market. If not set, all stop orders across all markets will be cancelled.
stop_order_idoptional stringRestrict cancellations to a stop order with the given ID. If set, then a market ID must also be provided.

StopOrdersSubmission

A command that allows a party to submit a stop order for a given market. A stop order is a normal order that remains off the order book and is only submitted if a given trigger is breached from a particular direction. If both rises-above and falls-below are configured, then if one is triggered the other will be cancelled (OCO).

NameTypeDescription
rises_aboveoptional StopOrderSetupStop order that will be triggered if the price rises above a given trigger price.
falls_belowoptional StopOrderSetupStop order that will be triggered if the price falls below a given trigger price.

SubmitAMM

Command to create an automated market maker for a given market.

NameTypeDescription
market_idstringMarket ID for which to create an AMM.
commitment_amountstringAmount to be committed to the AMM.
slippage_tolerancestringSlippage tolerance used for rebasing the AMM if its base price crosses with existing order
concentrated_liquidity_parametersSubmitAMM.ConcentratedLiquidityParametersConcentrated liquidity parameters defining the shape of the AMM's volume curves.
proposed_feestringNominated liquidity fee factor, which is an input to the calculation of taker fees on the market.

SubmitAMM.ConcentratedLiquidityParameters

Liquidity parameters that define the size and range of the AMM's tradeable volume.

NameTypeDescription
upper_boundoptional stringPrice at which the AMM will stop quoting sell volume. If not supplied the AMM will never hold a short position.
lower_boundoptional stringPrice at which the AMM will stop quoting buy volume. If not supplied the AMM will never hold a long position.
basestringPrice that the AMM will quote as its "fair price" when its position is zero.
leverage_at_upper_boundoptional stringLeverage at upper bound. If not set the markets risk-factors will be used to calculate leverage.
leverage_at_lower_boundoptional stringLeverage at lower bound. If not set the markets risk-factors will be used to calculate leverage.

Transfer

Command that allows a party to move assets from one account to another. A transfer can be set up as a single one-off transfer, or a recurring transfer that occurs once at the start of each epoch. Each transfer incurs a fee as specified by the network parameter `transfer.fee.factor`

NameTypeDescription
from_account_typevega.AccountTypeAccount type from which the funds of the party should be taken.
tostringPublic key of the destination account.
to_account_typevega.AccountTypeType of the destination account.
assetstringAsset ID of the asset to be transferred.
amountstringAmount to be taken from the source account, as an unsigned integer scaled to the asset's decimal places.
referencestringReference to be attached to the transfer.
fromoptional stringAMM key from which assets are to be transferred, if applicable. The submitter of the transaction must be the owner of this AMM key. If provided, the 'from_account_type' must be REWARDS_VESTED, and the asset in this account must match the asset specified in the transfer.
one_offOneOffTransferDetails of a one-off transfer that is executed once at a specified time.
recurringRecurringTransferDetails of a transfer that is executed once every epoch until stopped.

UndelegateSubmission

Command to allow a token holder to instruct the network to remove their delegated stake from a given validator node.

NameTypeDescription
node_idstringNode ID to undelegate stake from.
amountstringAmount to undelegate, as an unsigned integer scaled to the governance asset's decimal places. If not set, then all delegations to the given validator node will be removed.
methodUndelegateSubmission.MethodMethod of delegation.

UpdateMarginMode

NameTypeDescription
market_idstringMarket to change margin mode for.
modeUpdateMarginMode.ModeMargin mode to use.
margin_factoroptional stringMargin factor to use for margin in isolated mode. It is a multiplier that defines how much margin needs to be set aside

UpdatePartyProfile

Command to associate metadata to a public key, known as a party ID. Partial update is not supported, meaning previous values must be included in the update, otherwise they are removed.

NameTypeDescription
aliasstringAlias given to the party. It must be unique network-wide.
metadatarepeated vega.MetadataFreeform data to associate to the party. Support a maximum of 10 entries.

UpdateReferralSet

A command that allows the referrer of a referral set to update team details for a referral set. Any field that is left unset or has a default value indicates that this field on the original referral set will be left unchanged.

NameTypeDescription
idstringID of the referral set to update.
is_teamboolWhether or not the referral set should be considered a team that can participate in team games on the network.
teamoptional UpdateReferralSet.TeamTeam details, if the referral set is to be considered a team.

UpdateReferralSet.Team

NameTypeDescription
nameoptional stringNew name of the team.
team_urloptional stringNew link to the team's homepage.
avatar_urloptional stringNew link to an avatar for the team.
closedoptional boolWhether or not the team is closed to new party members. When closed, only parties specified in the allow list can join the team.
allow_listrepeated stringList of public keys that are allowed to join the team. Only applicable to closed teams. Removing a party from the allow list does not remove the party from the team.

VoteSubmission

Command that allows a token holder to vote for or against an active governance proposal.

NameTypeDescription
proposal_idstringSubmit vote for the specified proposal ID.
valuevega.Vote.ValueActual value of the vote.

WithdrawSubmission

Command to instruct the network to process an asset withdrawal from the Vega network. The process is specific to the destination foreign chain, for example, a withdrawal to Ethereum will generate signatures that allow funds to be taken across the bridge.

NameTypeDescription
amountstringAmount to be withdrawn, as an unsigned integer scaled to the asset's decimal places.
assetstringAsset to be withdrawn.
extvega.WithdrawExtDetails specific to the foreign chain, such as the receiver address.

Enums

CancelAMM.Method

NameNumberDescription
METHOD_UNSPECIFIED0
METHOD_IMMEDIATE1Cancellation will be immediate and any open positions will be transferred to the network for liquidation.
METHOD_REDUCE_ONLY2AMM will only trade to reduce its position, and will be cancelled once its position reaches zero.

UndelegateSubmission.Method

NameNumberDescription
METHOD_UNSPECIFIED0
METHOD_NOW1Undelegate straight away, losing all rewards for the current epoch.
METHOD_AT_END_OF_EPOCH2Undelegate at the end of an epoch, retaining all rewards for the current epoch.

UpdateMarginMode.Mode

NameNumberDescription
MODE_UNSPECIFIED0Never valid.
MODE_CROSS_MARGIN1Cross margin mode - margin is dynamically acquired and released as a position is marked to market
MODE_ISOLATED_MARGIN2Isolated margin mode - margin for any newly opened position volume is transferred to the margin account when the trade is executed