code.vegaprotocol.io/vega@v0.79.0/protos/sources/vega/commands/v1/commands.proto

syntax = "proto3";

package vega.commands.v1;

import "vega/commands/v1/validator_commands.proto";
import "vega/governance.proto";
import "vega/vega.proto";

option go_package = "code.vegaprotocol.io/vega/protos/vega/commands/v1";

// 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".
message BatchMarketInstructions {
  // List of order cancellations to be processed sequentially.
  repeated OrderCancellation cancellations = 1;
  // List of order amendments to be processed sequentially.
  repeated OrderAmendment amendments = 2;
  // List of order submissions to be processed sequentially.
  repeated OrderSubmission submissions = 3;
  // List of stop order cancellations to be processed sequentially.
  repeated StopOrdersCancellation stop_orders_cancellation = 4;
  // List of stop order submissions to be processed sequentially.
  repeated StopOrdersSubmission stop_orders_submission = 5;
  // Update margin mode instruction
  repeated UpdateMarginMode update_margin_mode = 6;
}

// 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).
message StopOrdersSubmission {
  // Stop order that will be triggered if the price rises above a given trigger price.
  optional StopOrderSetup rises_above = 1;
  // Stop order that will be triggered if the price falls below a given trigger price.
  optional StopOrderSetup falls_below = 2;
}

// Price and expiry configuration for a stop order.
message StopOrderSetup {
  // Order to be submitted once the trigger is breached.
  OrderSubmission order_submission = 1;
  // Timestamp, in Unix nanoseconds, for when the stop order should expire. If not set the stop order will not expire.
  optional int64 expires_at = 2;
  // Strategy to adopt if the expiry time is reached.
  optional vega.StopOrder.ExpiryStrategy expiry_strategy = 3;
  // Indicates if this order is linked to an order or position to derive the order size
  optional vega.StopOrder.SizeOverrideSetting size_override_setting = 4;
  // If this order is linked to a position, provide an optional scaling factor
  optional vega.StopOrder.SizeOverrideValue size_override_value = 5;

  // Trigger that will need to be breached for the order to be submitted to the book.
  oneof trigger {
    // Order will be submitted if the last traded price on the market breaches the given price.
    string price = 100;
    // 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.
    string trailing_percent_offset = 101;
  }
}

// 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.
message StopOrdersCancellation {
  // Restrict cancellations to those submitted to the given market. If not set, all stop orders across all markets will be cancelled.
  optional string market_id = 1;
  // Restrict cancellations to a stop order with the given ID. If set, then a market ID must also be provided.
  optional string stop_order_id = 2;
}

// A command that submits an order to the Vega network for a given market.
message OrderSubmission {
  // Market ID to submit the order to.
  string market_id = 1;
  // 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.
  string price = 2;
  // Size for the order, for example, in a futures market the size equals the number of units.
  uint64 size = 3;
  // Which side of the order book the order is for, e.g. buy or sell.
  vega.Side side = 4;
  // Time in force indicates how long an order will remain active before it is executed or expires..
  vega.Order.TimeInForce time_in_force = 5;
  // Timestamp, in Unix nanoseconds, for when the order will expire. Can only be set when the order's time-in-force is GTT.
  int64 expires_at = 6;
  // Type of the order.
  vega.Order.Type type = 7;
  // Arbitrary optional reference for the order, to be used as a human-readable non-unique identifier for the order.
  string reference = 8;
  // Pegged order details. If set, the order's price will be offset from a particular reference price of the order book at all times.
  vega.PeggedOrder pegged_order = 9;
  // If set, the order will only be executed if it would not trade on entry to the order book. Only valid for limit orders.
  bool post_only = 10;
  // 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.
  bool reduce_only = 11;
  // Iceberg order details. If set, the order will exist on the order book in chunks.
  optional IcebergOpts iceberg_opts = 12;
}

// Iceberg order options
message IcebergOpts {
  // Size of the order that is made visible and can be traded with during the execution of a single order.
  uint64 peak_size = 1;
  // Minimum allowed remaining size of the order before it is replenished back to its peak size.
  uint64 minimum_visible_size = 2;
}

message UpdateMarginMode {
  enum Mode {
    // Never valid.
    MODE_UNSPECIFIED = 0;
    // Cross margin mode - margin is dynamically acquired and released as a position is marked to market
    MODE_CROSS_MARGIN = 1;
    // Isolated margin mode - margin for any newly opened position volume is transferred to the margin account when the trade is executed
    MODE_ISOLATED_MARGIN = 2;
  }
  // Market to change margin mode for.
  string market_id = 1;
  // Margin mode to use.
  Mode mode = 2;
  // Margin factor to use for margin in isolated mode. It is a multiplier that defines how much margin needs to be set aside
  optional string margin_factor = 3;
}

// 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.
message OrderCancellation {
  // Restrict cancellations to an order with the given ID. If set, then a market ID must also be provided.
  string order_id = 1;
  // Restrict cancellations to those submitted to the given market. If not set, all stop orders across all markets will be cancelled.
  string market_id = 2;
}

// 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.
message OrderAmendment {
  // ID of the order to amend.
  string order_id = 1;
  // Market ID that the order was originally submitted to.
  string market_id = 2;
  // New price for the order. This field is an unsigned integer scaled to the market's decimal places.
  optional string price = 3;
  // 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.
  int64 size_delta = 4;
  // Timestamp, in Unix nanoseconds, for the new expiry time for the order.
  optional int64 expires_at = 5;
  // New time in force for the order.
  vega.Order.TimeInForce time_in_force = 6;
  // New pegged offset for the order.
  // This field is an unsigned integer scaled to the market's decimal places.
  string pegged_offset = 7;
  // New pegged reference for the order.
  vega.PeggedReference pegged_reference = 8;
  // 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.
  optional uint64 size = 9;
}

// 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.
message LiquidityProvisionSubmission {
  reserved 4, 5;
  // Market that the submitter wishes to provide liquidity for.
  string market_id = 1;
  // 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.
  string commitment_amount = 2;
  // 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.
  string fee = 3;
  // Arbitrary reference to be added to every order created out of this liquidity provision submission.
  string reference = 6;
}

// Command that allows a liquidity provider to inform the network that they will stop providing liquidity for a market.
message LiquidityProvisionCancellation {
  // Market that the submitter will stop providing liquidity for.
  string market_id = 1;
}

// 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.
message LiquidityProvisionAmendment {
  reserved 4, 5;
  // Market that the submitter wants to amend the liquidity commitment for.
  string market_id = 1;
  // New commitment amount.
  string commitment_amount = 2;
  // New nominated liquidity fee factor.
  string fee = 3;
  // New arbitrary reference to be added to every order created out of this liquidity provision submission.
  string reference = 6;
}

// 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.
message WithdrawSubmission {
  // Amount to be withdrawn, as an unsigned integer scaled to the asset's decimal places.
  string amount = 1;
  // Asset to be withdrawn.
  string asset = 2;
  // Details specific to the foreign chain, such as the receiver address.
  vega.WithdrawExt ext = 3;
}

// 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.
message ProposalSubmission {
  // Arbitrary human-readable reference identifying the proposal.
  string reference = 1;
  // Proposal terms containing the type and details of the proposal, as well as time spans for voting and enactment.
  vega.ProposalTerms terms = 2;
  // Rationale behind a proposal.
  vega.ProposalRationale rationale = 3;
}

// Terms for a batch governance proposal submission
message BatchProposalSubmissionTerms {
  // Closing timestamp in Unix time; adheres to `minClose` and `maxClose` limits.
  int64 closing_timestamp = 1;
  // List of individual changes included in the batch proposal.
  repeated vega.BatchProposalTermsChange changes = 2;
}

// 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.
message BatchProposalSubmission {
  // Arbitrary human-readable reference identifying the proposal.
  string reference = 1;
  // Proposal terms containing the type and details of the proposal, as well as time spans for voting and enactment.
  BatchProposalSubmissionTerms terms = 2;
  // Rationale behind a proposal.
  vega.ProposalRationale rationale = 3;
}

// Command that allows a token holder to vote for or against an active governance proposal.
message VoteSubmission {
  // Submit vote for the specified proposal ID.
  string proposal_id = 1;
  // Actual value of the vote.
  vega.Vote.Value value = 2;
}

// 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.
message DelegateSubmission {
  // Node ID to delegate stake to.
  string node_id = 1;
  // Amount of stake to delegate, as an unsigned integer scaled to the governance asset's decimal places.
  string amount = 2;
}

// Command to allow a token holder to instruct the network to remove their delegated stake from a given validator node.
message UndelegateSubmission {
  enum Method {
    reserved 3;

    METHOD_UNSPECIFIED = 0;
    // Undelegate straight away, losing all rewards for the current epoch.
    METHOD_NOW = 1;
    // Undelegate at the end of an epoch, retaining all rewards for the current epoch.
    METHOD_AT_END_OF_EPOCH = 2;
  }
  // Node ID to undelegate stake from.
  string node_id = 1;
  // 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.
  string amount = 2;
  // Method of delegation.
  Method method = 3;
}

// 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`
message Transfer {
  // Account type from which the funds of the party should be taken.
  vega.AccountType from_account_type = 1;
  // Public key of the destination account.
  string to = 2;
  // Type of the destination account.
  vega.AccountType to_account_type = 3;
  // Asset ID of the asset to be transferred.
  string asset = 4;
  // Amount to be taken from the source account, as an unsigned integer scaled to the asset's decimal places.
  string amount = 5;
  // Reference to be attached to the transfer.
  string reference = 6;
  // AMM 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.
  optional string from = 7;

  // Specific details of the transfer.
  oneof kind {
    // Details of a one-off transfer that is executed once at a specified time.
    OneOffTransfer one_off = 101;
    // Details of a transfer that is executed once every epoch until stopped.
    RecurringTransfer recurring = 102;
  }
}

// Details for a one-off transfer.
message OneOffTransfer {
  // Timestamp, in Unix nanoseconds, for when the transfer should be executed, i.e., assets transferred into the receiver's account.
  int64 deliver_on = 1;
}

// Details for a recurring transfer
message RecurringTransfer {
  // First epoch from which this transfer shall be executed.
  uint64 start_epoch = 1;
  // Last epoch at which this transfer shall be executed.
  optional uint64 end_epoch = 2;
  // 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.
  string factor = 3;
  // Optional parameter defining how a transfer is dispatched.
  vega.DispatchStrategy dispatch_strategy = 4;
}

// Command that can be used by the party that initiated a transfer to instruct the network to stop an active recurring transaction.
message CancelTransfer {
  // Transfer ID of the transfer to cancel.
  string transfer_id = 1;
}

// 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.
message IssueSignatures {
  // Ethereum address which will submit the signatures to the smart contract.
  string submitter = 1;
  // What kind of signatures to generate, namely for whether a signer is being added or removed.
  NodeSignatureKind kind = 2;
  // Node ID of the validator node that will be signed in or out of the smart contract.
  string validator_node_id = 3;
  // Chain ID of the bridge to generate signatures for.
  string chain_id = 4;
}

// 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.
message CreateReferralSet {
  // Whether or not the referral set should be considered a team that can participate in team games on the network.
  bool is_team = 1;
  // Team details, if the referral set is to be considered a team.
  optional Team team = 2;
  // Should 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.
  bool do_not_create_referral_set = 3;

  message Team {
    // Name of the team.
    string name = 10;
    // External link to the team's homepage.
    optional string team_url = 11;
    // External link to an avatar for the team.
    optional string avatar_url = 12;
    // Whether or not the team is closed to new party members.
    bool closed = 13;
    // 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.
    repeated string allow_list = 14;
  }
}

// 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.
message UpdateReferralSet {
  // ID of the referral set to update.
  string id = 1;
  // Whether or not the referral set should be considered a team that can participate in team games on the network.
  bool is_team = 2;
  // Team details, if the referral set is to be considered a team.
  optional Team team = 3;

  message Team {
    // New name of the team.
    optional string name = 10;
    // New link to the team's homepage.
    optional string team_url = 11;
    // New link to an avatar for the team.
    optional string avatar_url = 12;
    // Whether or not the team is closed to new party members. When closed, only parties specified in the allow list can
    // join the team.
    optional bool closed = 13;
    // 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.
    repeated string allow_list = 14;
  }
}

// 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.
message ApplyReferralCode {
  // Referral code, normally the referral set ID, for the party to join.
  string id = 1;
  // Should 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.
  bool do_not_join_team = 2;
}

// Command that allows the submitter to join a team or change teams if they are already a member of a team.
message JoinTeam {
  // ID of the team to join, this is the same as the referral code used to generate the team.
  string id = 1;
}

// 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.
message UpdatePartyProfile {
  // Alias given to the party. It must be unique network-wide.
  string alias = 1;
  // Freeform data to associate to the party.
  // Support a maximum of 10 entries.
  repeated vega.Metadata metadata = 2;
}

// Command to create an automated market maker for a given market.
message SubmitAMM {
  // Market ID for which to create an AMM.
  string market_id = 1;
  // Amount to be committed to the AMM.
  string commitment_amount = 2;
  // Slippage tolerance used for rebasing the AMM if its base price crosses with existing order
  string slippage_tolerance = 3;
  // Concentrated liquidity parameters defining the shape of the AMM's volume curves.
  ConcentratedLiquidityParameters concentrated_liquidity_parameters = 4;
  // Nominated liquidity fee factor, which is an input to the calculation of taker fees on the market.
  string proposed_fee = 5;
  // Liquidity parameters that define the size and range of the AMM's tradeable volume.
  message ConcentratedLiquidityParameters {
    // Price at which the AMM will stop quoting sell volume. If not supplied the AMM will never hold a short position.
    optional string upper_bound = 1;
    // Price at which the AMM will stop quoting buy volume. If not supplied the AMM will never hold a long position.
    optional string lower_bound = 2;
    // Price that the AMM will quote as its "fair price" when its position is zero.
    string base = 3;
    // Leverage at upper bound. If not set the markets risk-factors will be used to calculate leverage.
    optional string leverage_at_upper_bound = 4;
    // Leverage at lower bound. If not set the markets risk-factors will be used to calculate leverage.
    optional string leverage_at_lower_bound = 5;
    // ID of a data source already used by the market which will be used as the base price for the AMM.
    optional string data_source_id = 6;
  }
  // An AMM with an oracle driven base price will only be updated if abs(new-base-price / old-base-price - 1) >= minimum_price_change_trigger.
  optional string minimum_price_change_trigger = 7;
}

// Command to amend an existing automated market maker on a market.
message AmendAMM {
  // Market ID for the AMM to be amended.
  string market_id = 1;
  // Amount to be committed to the AMM. If not supplied the commitment will remain unchanged.
  optional string commitment_amount = 2;
  // Slippage tolerance for rebasing position when updating the AMM.
  string slippage_tolerance = 3;
  // Concentrated liquidity parameters defining the shape of the AMM's volume curves. If not supplied the parameters will remain unchanged.
  optional ConcentratedLiquidityParameters concentrated_liquidity_parameters = 4;
  // Nominated 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.
  optional string proposed_fee = 5;
  // Liquidity parameters that define the size and range of the AMM's tradeable volume.
  message ConcentratedLiquidityParameters {
    // Price at which the AMM will stop quoting sell volume. If not supplied the AMM will never hold a short position.
    optional string upper_bound = 1;
    // Price at which the AMM will stop quoting buy volume. If not supplied the AMM will never hold a long position.
    optional string lower_bound = 2;
    // Price that the AMM will quote as its "fair price" when its position is zero.
    string base = 3;
    // Leverage at upper bound. If not set the markets risk-factors will be used to calculate leverage.
    optional string leverage_at_upper_bound = 4;
    // Leverage at lower bound. If not set the markets risk-factors will be used to calculate leverage.
    optional string leverage_at_lower_bound = 5;
    // ID of a data source already used by the market which will be used as the base price for the AMM.
    optional string data_source_id = 6;
  }
  // An AMM with an oracle driven base price will only be updated if abs(new-base-price / old-base-price - 1) >= minimum_price_change_trigger.
  optional string minimum_price_change_trigger = 7;
}

// Command to cancel an automated market maker for a given market.
message CancelAMM {
  enum Method {
    METHOD_UNSPECIFIED = 0;
    // Cancellation will be immediate and any open positions will be transferred to the network for liquidation.
    METHOD_IMMEDIATE = 1;
    // AMM will only trade to reduce its position, and will be cancelled once its position reaches zero.
    METHOD_REDUCE_ONLY = 2;
  }
  // Market ID to cancel an AMM for.
  string market_id = 1;
  // Method to use to cancel the AMM.
  Method method = 2;
}

// Internal transactions used to convey delayed transactions to be included in the next block.
message DelayedTransactionsWrapper {
  repeated bytes transactions = 1;
  uint64 height = 2;
}