commands.proto

path vega/commands/v1/commands.proto

package vega.commands.v1

---

Messages

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.

Name	Type	Description
id	string	Referral code, normally the referral set ID, for the party to join.

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".

Name	Type	Description
cancellations	repeated OrderCancellation	List of order cancellations to be processed sequentially.
amendments	repeated OrderAmendment	List of order amendments to be processed sequentially.
submissions	repeated OrderSubmission	List of order submissions to be processed sequentially.
stop_orders_cancellation	repeated StopOrdersCancellation	List of stop order cancellations to be processed sequentially.
stop_orders_submission	repeated StopOrdersSubmission	List of stop order submissions to be processed sequentially.
update_margin_mode	repeated UpdateMarginMode	Update 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.

Name	Type	Description
reference	string	Arbitrary human-readable reference identifying the proposal.
terms	BatchProposalSubmissionTerms	Proposal terms containing the type and details of the proposal, as well as time spans for voting and enactment.
rationale	vega.ProposalRationale	Rationale behind a proposal.

BatchProposalSubmissionTerms

Terms for a batch governance proposal submission

Name	Type	Description
closing_timestamp	int64	Closing timestamp in Unix time; adheres to `minClose` and `maxClose` limits.
changes	repeated vega.BatchProposalTermsChange	List of individual changes included in the batch proposal.

CancelTransfer

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

Name	Type	Description
transfer_id	string	Transfer 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.

Name	Type	Description
is_team	bool	Whether or not the referral set should be considered a team that can participate in team games on the network.
team	optional CreateReferralSet.Team	Team details, if the referral set is to be considered a team.

CreateReferralSet.Team

Name	Type	Description
name	string	Name of the team.
team_url	optional string	External link to the team's homepage.
avatar_url	optional string	External link to an avatar for the team.
closed	bool	Whether or not the team is closed to new party members.
allow_list	repeated string	List 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.

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.

Name	Type	Description
node_id	string	Node ID to delegate stake to.
amount	string	Amount of stake to delegate, as an unsigned integer scaled to the governance asset's decimal places.

IcebergOpts

Iceberg order options

Name	Type	Description
peak_size	uint64	Size of the order that is made visible and can be traded with during the execution of a single order.
minimum_visible_size	uint64	Minimum 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.

Name	Type	Description
submitter	string	Ethereum address which will submit the signatures to the smart contract.
kind	NodeSignatureKind	What kind of signatures to generate, namely for whether a signer is being added or removed.
validator_node_id	string	Node ID of the validator node that will be signed in or out of the smart contract.
chain_id	string	Chain 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.

Name	Type	Description
id	string	ID 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.

Name	Type	Description
market_id	string	Market that the submitter wants to amend the liquidity commitment for.
commitment_amount	string	New commitment amount.
fee	string	New nominated liquidity fee factor.
reference	string	New 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.

Name	Type	Description
market_id	string	Market 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.

Name	Type	Description
market_id	string	Market that the submitter wishes to provide liquidity for.
commitment_amount	string	Amount 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.
fee	string	Nominated liquidity fee factor, which is an input to the calculation of taker fees on the market, as per setting fees and rewarding liquidity providers.
reference	string	Arbitrary reference to be added to every order created out of this liquidity provision submission.

OneOffTransfer

Details for a one-off transfer.

Name	Type	Description
deliver_on	int64	Timestamp, 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.

Name	Type	Description
order_id	string	ID of the order to amend.
market_id	string	Market ID that the order was originally submitted to.
price	optional string	New price for the order. This field is an unsigned integer scaled to the market's decimal places.
size_delta	int64	Amend 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_at	optional int64	Timestamp, in Unix nanoseconds, for the new expiry time for the order.
time_in_force	vega.Order.TimeInForce	New time in force for the order.
pegged_offset	string	New pegged offset for the order. This field is an unsigned integer scaled to the market's decimal places.
pegged_reference	vega.PeggedReference	New pegged reference for the order.
size	optional uint64	New 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.

Name	Type	Description
order_id	string	Restrict cancellations to an order with the given ID. If set, then a market ID must also be provided.
market_id	string	Restrict 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.

Name	Type	Description
market_id	string	Market ID to submit the order to.
price	string	Price 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.
size	uint64	Size for the order, for example, in a futures market the size equals the number of units.
side	vega.Side	Which side of the order book the order is for, e.g. buy or sell.
time_in_force	vega.Order.TimeInForce	Time in force indicates how long an order will remain active before it is executed or expires..
expires_at	int64	Timestamp, in Unix nanoseconds, for when the order will expire. Can only be set when the order's time-in-force is GTT.
type	vega.Order.Type	Type of the order.
reference	string	Arbitrary optional reference for the order, to be used as a human-readable non-unique identifier for the order.
pegged_order	vega.PeggedOrder	Pegged order details. If set, the order's price will be offset from a particular reference price of the order book at all times.
post_only	bool	If set, the order will only be executed if it would not trade on entry to the order book. Only valid for limit orders.
reduce_only	bool	If 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_opts	optional IcebergOpts	Iceberg 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.

Name	Type	Description
reference	string	Arbitrary human-readable reference identifying the proposal.
terms	vega.ProposalTerms	Proposal terms containing the type and details of the proposal, as well as time spans for voting and enactment.
rationale	vega.ProposalRationale	Rationale behind a proposal.

RecurringTransfer

Details for a recurring transfer

Name	Type	Description
start_epoch	uint64	First epoch from which this transfer shall be executed.
end_epoch	optional uint64	Last epoch at which this transfer shall be executed.
factor	string	Factor 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_strategy	vega.DispatchStrategy	Optional parameter defining how a transfer is dispatched.

StopOrderSetup

Price and expiry configuration for a stop order.

Name	Type	Description
order_submission	OrderSubmission	Order to be submitted once the trigger is breached.
expires_at	optional int64	Timestamp, in Unix nanoseconds, for when the stop order should expire. If not set the stop order will not expire.
expiry_strategy	optional vega.StopOrder.ExpiryStrategy	Strategy to adopt if the expiry time is reached.
size_override_setting	optional vega.StopOrder.SizeOverrideSetting	Indicates if this order is linked to an order or position to derive the order size
size_override_value	optional vega.StopOrder.SizeOverrideValue	If this order is linked to a position, provide an optional scaling factor
price	string	Order will be submitted if the last traded price on the market breaches the given price.
trailing_percent_offset	string	Order 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.

Name	Type	Description
market_id	optional string	Restrict cancellations to those submitted to the given market. If not set, all stop orders across all markets will be cancelled.
stop_order_id	optional string	Restrict 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).

Name	Type	Description
rises_above	optional StopOrderSetup	Stop order that will be triggered if the price rises above a given trigger price.
falls_below	optional StopOrderSetup	Stop order that will be triggered if the price falls below a given trigger price.

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`

Name	Type	Description
from_account_type	vega.AccountType	Account type from which the funds of the party should be taken.
to	string	Public key of the destination account.
to_account_type	vega.AccountType	Type of the destination account.
asset	string	Asset ID of the asset to be transferred.
amount	string	Amount to be taken from the source account, as an unsigned integer scaled to the asset's decimal places.
reference	string	Reference to be attached to the transfer.
one_off	OneOffTransfer	Details of a one-off transfer that is executed once at a specified time.
recurring	RecurringTransfer	Details 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.

Name	Type	Description
node_id	string	Node ID to undelegate stake from.
amount	string	Amount 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.
method	UndelegateSubmission.Method	Method of delegation.

UpdateMarginMode

Name	Type	Description
market_id	string	Market to change margin mode for.
mode	UpdateMarginMode.Mode	Margin mode to use.
margin_factor	optional string	Margin 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.

Name	Type	Description
alias	string	Alias given to the party. It must be unique network-wide.
metadata	repeated vega.Metadata	Freeform 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.

Name	Type	Description
id	string	ID of the referral set to update.
is_team	bool	Whether or not the referral set should be considered a team that can participate in team games on the network.
team	optional UpdateReferralSet.Team	Team details, if the referral set is to be considered a team.

UpdateReferralSet.Team

Name	Type	Description
name	optional string	New name of the team.
team_url	optional string	New link to the team's homepage.
avatar_url	optional string	New link to an avatar for the team.
closed	optional bool	Whether or not the team is closed to new party members. When closed, only parties specified in the allow list can join the team.
allow_list	repeated string	List 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.

Name	Type	Description
proposal_id	string	Submit vote for the specified proposal ID.
value	vega.Vote.Value	Actual 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.

Name	Type	Description
amount	string	Amount to be withdrawn, as an unsigned integer scaled to the asset's decimal places.
asset	string	Asset to be withdrawn.
ext	vega.WithdrawExt	Details specific to the foreign chain, such as the receiver address.

---

Enums

UndelegateSubmission.Method

Name	Number	Description
METHOD_UNSPECIFIED	0
METHOD_NOW	1	Undelegate straight away, losing all rewards for the current epoch.
METHOD_AT_END_OF_EPOCH	2	Undelegate at the end of an epoch, retaining all rewards for the current epoch.

UpdateMarginMode.Mode

Name	Number	Description
MODE_UNSPECIFIED	0	Never valid.
MODE_CROSS_MARGIN	1	Cross margin mode - margin is dynamically acquired and released as a position is marked to market
MODE_ISOLATED_MARGIN	2	Isolated margin mode - margin for any newly opened position volume is transferred to the margin account when the trade is executed

---