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

syntax = "proto3";

package vega.api.v1;

import "google/api/field_behavior.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "vega/commands/v1/transaction.proto";
import "vega/events/v1/events.proto";
import "vega/vega.proto";

option go_package = "code.vegaprotocol.io/vega/protos/vega/api/v1";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "Vega core APIs";
    version: "v0.79.0";
  }
  schemes: [
    HTTP,
    HTTPS
  ]
  host: "lb.testnet.vega.xyz"
};

service CoreService {
  // Submit transaction
  //
  // Submit a signed transaction to the network containing a command to be executed such that if the submission is successful then it will be included in the chain's mempool.
  // The network will then attempt to execute the transaction in the next available block, where the results of its execution can be seen on the EventBus.
  rpc SubmitTransaction(SubmitTransactionRequest) returns (SubmitTransactionResponse);

  // Chain event
  //
  // Propagate a chain event
  rpc PropagateChainEvent(PropagateChainEventRequest) returns (PropagateChainEventResponse);

  // Statistics
  //
  // Get statistics on Vega
  rpc Statistics(StatisticsRequest) returns (StatisticsResponse);

  // Blockchain height
  //
  // Get the height of the last tendermint block
  rpc LastBlockHeight(LastBlockHeightRequest) returns (LastBlockHeightResponse);

  // Vega time
  //
  // Get current Vega time
  rpc GetVegaTime(GetVegaTimeRequest) returns (GetVegaTimeResponse);

  // Events subscription
  //
  // Subscribe to a stream of events from the core
  rpc ObserveEventBus(stream ObserveEventBusRequest) returns (stream ObserveEventBusResponse);

  // Submit raw transaction
  //
  // Submit a pre-serialised signed transaction containing a command to the network to be executed, such that if the submission is successful then it will be included in the chain's mempool.
  // The network will then attempt to execute the transaction in the next available block, where the results of its execution can be seen on the EventBus.
  rpc SubmitRawTransaction(SubmitRawTransactionRequest) returns (SubmitRawTransactionResponse);

  // Check transaction
  //
  // Send a signed transaction containing a command to the network to be checked, but not added to the chain's mempool.
  // This is useful for checking the validity of a potential transaction before submitting it.
  rpc CheckTransaction(CheckTransactionRequest) returns (CheckTransactionResponse);

  // Check raw transaction
  //
  // Send a pre-serialised transaction containing a command to the network to be checked, but then not added to the chain's mempool.
  // This is useful for checking the validity of a potential transaction before submitting it.
  rpc CheckRawTransaction(CheckRawTransactionRequest) returns (CheckRawTransactionResponse);

  // Get Spam statistics
  //
  // Get the spam statistics for a given party.
  rpc GetSpamStatistics(GetSpamStatisticsRequest) returns (GetSpamStatisticsResponse);
}

// Request for a new event sent by the blockchain queue to be propagated on Vega
message PropagateChainEventRequest {
  // Chain event to propagate.
  bytes event = 1 [(google.api.field_behavior) = REQUIRED];
  // Public key of the key pair used to sign messages.
  string pub_key = 2 [(google.api.field_behavior) = REQUIRED];
  // Signature generated by the private key associated with the public key.
  bytes signature = 3 [(google.api.field_behavior) = REQUIRED];
}

// Response for a new event sent by the blockchain queue to be propagated on Vega
message PropagateChainEventResponse {
  // Success will be true if the event was accepted by the node,
  // **Important** - success does not mean that the event is confirmed by consensus
  bool success = 1;
}

// Request for submitting a transaction v2 on Vega
message SubmitTransactionRequest {
  // Blockchain transaction type.
  enum Type {
    TYPE_UNSPECIFIED = 0;
    // Transaction will be submitted without waiting for a response.
    TYPE_ASYNC = 1;
    // Transaction will be submitted, and blocking until the mempool returns a response.
    TYPE_SYNC = 2;
    // Transaction will be submitted, and blocking until the network has committed it into a block.
    // Used only for debugging local network, not for submitting transactions.
    TYPE_COMMIT = 3;
  }
  // Transaction containing a command to execute on the network, and a signature to provide authentication.
  vega.commands.v1.Transaction tx = 1 [(google.api.field_behavior) = REQUIRED];
  // Method of submission.
  Type type = 2 [(google.api.field_behavior) = REQUIRED];
}

// Response for submitting a transaction on the network.
message SubmitTransactionResponse {
  // Whether or not the transaction was validated and submitted to the chain's mempool.
  bool success = 1;
  // Hash of the transaction, which can be used to identify the transaction in a node's event stream.
  string tx_hash = 2;
  // Error code to indicate the category of failure if the transaction was not successfully submitted.
  uint32 code = 3;
  // Further details for why the transaction was not successfully submitted.
  string data = 4;
  // Further details for the underlying consensus layer of the result of the transaction.
  string log = 5;
  // Unused.
  int64 height = 6;
}

// Request for checking a transaction v2 on Vega
message CheckTransactionRequest {
  // Transaction containing a command to be checked on the network, and not added to the chain's mempool.
  vega.commands.v1.Transaction tx = 1 [(google.api.field_behavior) = REQUIRED];
}

message CheckTransactionResponse {
  // Whether or not the transaction passed the submission checks.
  bool success = 1;
  // Error code to indicate the category of failure if the transaction was not successfully checked.
  uint32 code = 2;
  // Amount of space in a block that the transaction will fill. This does not relate to any monetary cost for submitting the transaction.
  int64 gas_wanted = 3;
  // Unused.
  int64 gas_used = 4;
  // Further details for why the transaction was not successfully submitted.
  string data = 5;
  // Further details for the underlying consensus layer of the result of the transaction.
  string log = 6;
  // Unused.
  string info = 7;
}

// Request for submitting a version agnostic transaction on Vega
message SubmitRawTransactionRequest {
  // Blockchain transaction type
  enum Type {
    TYPE_UNSPECIFIED = 0;
    // Transaction will be submitted without waiting for response
    TYPE_ASYNC = 1;
    // Transaction will be submitted, and blocking until the
    // tendermint mempool returns a response
    TYPE_SYNC = 2;
    // Transaction will be submitted, and blocking until the tendermint
    // network has committed it into a block. Used only for debugging,
    // not for submitting transactions
    TYPE_COMMIT = 3;
  }
  // Bundle of signed payload and signature marshalled into a byte array, to form a transaction that will be submitted to the Vega blockchain
  bytes tx = 1 [(google.api.field_behavior) = REQUIRED];
  // Type of transaction request, for example ASYNC, meaning the transaction will be submitted and not block on a response
  Type type = 2 [(google.api.field_behavior) = REQUIRED];
}

// Response for submitting a version agnostic transaction on Vega
message SubmitRawTransactionResponse {
  // Whether or not the transaction was validated and submitted to the chain's mempool.
  bool success = 1;
  // Hash of the transaction, which can be used to identify the transaction in a node's event stream.
  string tx_hash = 2;
  // Error code to indicate the category of failure if the transaction was not successfully submitted.
  uint32 code = 3;
  // Further details for why the transaction was not successfully submitted.
  string data = 4;
  // Further details for the underlying consensus layer of the result of the transaction.
  string log = 5;
  // Unused.
  int64 height = 6;
}

// Request for checking a version agnostic transaction on Vega
message CheckRawTransactionRequest {
  // Bundle of signed payload and signature marshalled into a byte array, to form a transaction that would be submitted to the Vega blockchain
  bytes tx = 1 [(google.api.field_behavior) = REQUIRED];
}

// Response for checking a version agnostic transaction on Vega
message CheckRawTransactionResponse {
  // Whether or not the transaction passed the submission checks.
  bool success = 1;
  // Error code to indicate the category of failure if the transaction was not successfully submitted.
  uint32 code = 2;
  // Amount of space in a block that the transaction will fill. This does not relate to any monetary cost for submitting the transaction.
  int64 gas_wanted = 3;
  // Unused.
  int64 gas_used = 4;
  // Further details for why the transaction was not successfully checked.
  string data = 5;
  // Further details for the underlying consensus layer of the result of the transaction.
  string log = 6;
  // Unused
  string info = 7;
}

// Request for the current time of the Vega network
message GetVegaTimeRequest {}

// Response for the current consensus coordinated time on the Vega network, referred to as "VegaTime"
message GetVegaTimeResponse {
  // Timestamp representation of current VegaTime as represented in
  // Unix nanoseconds, for example `1580473859111222333` corresponds to `2020-01-31T12:30:59.111222333Z`
  int64 timestamp = 1;
}

// Request to subscribe to a stream of one or more event types from the Vega event bus
message ObserveEventBusRequest {
  // One or more types of event, required field
  repeated vega.events.v1.BusEventType type = 1;
  // Market ID to filter events for, optional field. If omitted, no markets will be filtered out.
  string market_id = 2;
  // Party ID to filter events for, optional field. If omitted, no parties will be filtered out.
  string party_id = 3;
  // Batch size, optional field -
  // If not specified, any events received will be sent immediately. If the client is not ready
  // for the next data-set, data may be dropped a number of times, and eventually the stream is closed.
  // if specified, the first batch will be sent when ready. To receive the next set of events, the client
  // must write an `ObserveEventBatch` message on the stream to flush the buffer.
  // If no message is received in 5 seconds, the stream is closed.
  // Default: 0, send any and all events when they are available.
  int64 batch_size = 4;
}

// Response to a subscribed stream of events from the Vega event bus
message ObserveEventBusResponse {
  // One or more events that match the subscription request criteria.
  repeated vega.events.v1.BusEvent events = 1;
}

// Request for statistics about the Vega network
message StatisticsRequest {}

// Response containing statistics about the Vega network
message StatisticsResponse {
  Statistics statistics = 1;
}

// Vega domain specific statistics as reported by the node the caller is connected to
message Statistics {
  // Current block height as reported by the Vega blockchain
  uint64 block_height = 1;
  // Current backlog length i.e., number of transactions, that are waiting to be included in a block
  uint64 backlog_length = 2;
  // Total number of connected peers to this node
  uint64 total_peers = 3;
  // Genesis block date and time formatted in ISO-8601 datetime format with nanosecond precision
  string genesis_time = 4;
  // Current system date and time formatted in ISO-8601 datetime format with nanosecond precision
  string current_time = 5;
  // Current Vega date and time formatted in ISO-8601 datetime format with nanosecond precision
  string vega_time = 6;
  // Status of the connection to the Vega blockchain
  vega.ChainStatus status = 7;
  // Transactions per block
  uint64 tx_per_block = 8;
  // Average transaction size in bytes
  uint64 average_tx_bytes = 9;
  // Average orders per block
  uint64 average_orders_per_block = 10;
  // Trades emitted per second
  uint64 trades_per_second = 11;
  // Orders processed per second
  uint64 orders_per_second = 12;
  // Total markets on this Vega network
  uint64 total_markets = 13;
  // Total number of order amendments since genesis across all markets
  uint64 total_amend_order = 16;
  // Total number of order cancellations since genesis across all markets
  uint64 total_cancel_order = 17;
  // Total number of order submissions since genesis across all markets
  uint64 total_create_order = 18;
  // Total number of orders processed since genesis across all markets
  uint64 total_orders = 19;
  // Total number of trades emitted since genesis across all markets
  uint64 total_trades = 20;
  // Current number of stream subscribers to order data
  uint32 order_subscriptions = 21;
  // Current number of stream subscribers to trade data
  uint32 trade_subscriptions = 22;
  // Current number of stream subscribers to candlestick data
  uint32 candle_subscriptions = 23;
  // Current number of stream subscribers to market depth data
  uint32 market_depth_subscriptions = 24;
  // Current number of stream subscribers to positions data
  uint32 positions_subscriptions = 25;
  // Current number of stream subscribers to account data
  uint32 account_subscriptions = 26;
  // Current number of stream subscribers to market data
  uint32 market_data_subscriptions = 27;
  // Version hash of the Vega node software
  string app_version_hash = 28;
  // Version of the Vega node software
  string app_version = 29;
  // Version of the underlying Vega blockchain
  string chain_version = 30;
  // Current block duration, in nanoseconds
  uint64 block_duration = 31;
  // Total uptime for this node formatted in ISO-8601 datetime format with nanosecond precision
  string uptime = 32;
  // Unique ID for the underlying Vega blockchain
  string chain_id = 33;
  // Current number of stream subscribers to market depth update data
  uint32 market_depth_updates_subscriptions = 34;
  // Current block hash
  string block_hash = 35;
  // Current epoch
  uint64 epoch_seq = 36;
  // Epoch start time
  string epoch_start_time = 37;
  // Epoch expected end time
  string epoch_expiry_time = 38;
  // Number of events in the last block
  uint64 event_count = 39;
  // Rate of events per second in the last block
  uint64 events_per_second = 40;
}

// Request to get the height of the very last block processed
// by tendermint
message LastBlockHeightRequest {}

// Response with the height of the last block processed by
// tendermint
message LastBlockHeightResponse {
  // Last block height
  uint64 height = 1;
  // Last block hash
  string hash = 2;
  // Supported proof of work hash function
  string spam_pow_hash_function = 3;
  // Difficulty of the proof of work, i.e. the target number of zeros
  uint32 spam_pow_difficulty = 4;
  // Supported proof of work number of blocks behind current height allowed
  uint32 spam_pow_number_of_past_blocks = 5;
  // Allowed number of transactions per block
  uint32 spam_pow_number_of_tx_per_block = 6;
  // Boolean indicating whether increasing difficulty is allowed for using the
  // same height for more than `spam_pow_number_of_past_blocks` transactions
  bool spam_pow_increasing_difficulty = 7;
  // Network chain id from which the block comes from
  string chain_id = 8;
}

// Request to retrieve the spam statistics of a party for the given epoch
message GetSpamStatisticsRequest {
  // Party ID whose statistics are requested
  string party_id = 1 [(google.api.field_behavior) = REQUIRED];
}

// Statistics for a given spam policy
message SpamStatistic {
  // Current transaction count received from the party during this epoch for this policy
  uint64 count_for_epoch = 1;
  // Maximum number of transactions allowed for this policy in an epoch
  uint64 max_for_epoch = 2;
  // If blocked the timestamp when the party will be unblocked as RFC3339Nano
  optional string banned_until = 4;
  // Effective minimum number of tokens required to submit a transaction of this type
  string min_tokens_required = 5;
}

// Voting statistics by proposal for a given party for the current epoch
message VoteSpamStatistics {
  // List of statistics for proposals voted on by the party
  repeated VoteSpamStatistic statistics = 1;
  // Maximum number of votes per proposal allowed in an epoch
  uint64 max_for_epoch = 2;
  // If blocked the timestamp when the party will be unblocked as RFC3339Nano
  optional string banned_until = 3;
}

// Vote statistics for the voting spam policies
// which are calculated as a ratio of the total votes
// that have been rejected.
message VoteSpamStatistic {
  // Unique ID of the proposal being voted on by the party.
  string proposal = 1;
  // Current vote count received from the party for the given proposal during this epoch
  uint64 count_for_epoch = 2;
  // Effective minimum number of tokens required to vote on the proposal
  string min_tokens_required = 3;
}

// Proof of Work state for a given block
message PoWBlockState {
  // Block height for the current Proof of Work state statistics
  uint64 block_height = 1;
  // Hash of the current block
  string block_hash = 2;
  // Total number of transactions seen in the block
  uint64 transactions_seen = 3;
  // This is the minimum required difficulty for the next transaction submitted on this block
  // if it is possible to submit more transactions on this block, otherwise nil.
  optional uint64 expected_difficulty = 4;
  // Hashing function used to calculate the block hash
  string hash_function = 5;
  // Base difficulty for this block for when transactions seen < tx_per_block
  uint64 difficulty = 6;
  // Number of transactions that can have their proof-of-work calculated with this block hash before
  // either the difficulty increases, or no more transactions can use this block hash
  uint64 tx_per_block = 7;
  // Whether or not this block allows for increasing proof-of-work difficulty if the
  // tx-per-block-hash limit has been reached
  bool increasing_difficulty = 8;
}

// Proof of work statistics for a party
message PoWStatistic {
  // Block state for each block in scope for PoW calculation
  repeated PoWBlockState block_states = 1;
  // PoW banned until timestamp as RFC3339Nano
  optional string banned_until = 2;
  // Number of block behind the current block whose hash can be used for proof-of-work calculations
  uint64 number_of_past_blocks = 3;
}

// Complete spam statistics captured for a given party
message SpamStatistics {
  // Statistics for proposal transactions made by the party.
  SpamStatistic proposals = 1;
  // Statistics for delegation transactions made by the party.
  SpamStatistic delegations = 2;
  // Statistics for transfer transactions made by the party.
  SpamStatistic transfers = 3;
  // Statistics for node announcement transactions made by the party.
  SpamStatistic node_announcements = 4;
  // Statistics for proposal votes made by the party.
  VoteSpamStatistics votes = 5;
  // Statistics for proof of work difficulty observed per block for the party.
  PoWStatistic pow = 6;
  // Statistics for multisig signatures issued for the party.
  SpamStatistic issue_signatures = 7;
  // Epoch in which these statistics apply to.
  uint64 epoch_seq = 8;
  // Statistics for transactions made by the party to create referral sets.
  SpamStatistic create_referral_set = 9;
  // Statistics for transactions made by the party to update referral sets.
  SpamStatistic update_referral_set = 10;
  // Statistics for transactions made by the party to apply referral codes.
  SpamStatistic apply_referral_code = 11;
}

// Response containing all the spam statistics of a party for the current epoch
message GetSpamStatisticsResponse {
  // Chain ID for which the statistics are captured.
  string chain_id = 1;
  // Spam statistics for the party
  SpamStatistics statistics = 2;
}