Skip to main content
Version: release (v0.77)

core.proto

path vega/api/v1/core.proto

package vega.api.v1


Messages

CheckRawTransactionRequest

Request for checking a version agnostic transaction on Vega

NameTypeDescription
txbytesBundle of signed payload and signature marshalled into a byte array, to form a transaction that would be submitted to the Vega blockchain

CheckRawTransactionResponse

Response for checking a version agnostic transaction on Vega

NameTypeDescription
successboolWhether or not the transaction passed the submission checks.
codeuint32Error code to indicate the category of failure if the transaction was not successfully submitted.
gas_wantedint64Amount of space in a block that the transaction will fill. This does not relate to any monetary cost for submitting the transaction.
gas_usedint64Unused.
datastringFurther details for why the transaction was not successfully checked.
logstringFurther details for the underlying consensus layer of the result of the transaction.
infostringUnused

CheckTransactionRequest

Request for checking a transaction v2 on Vega

NameTypeDescription
txvega.commands.v1.TransactionTransaction containing a command to be checked on the network, and not added to the chain's mempool.

CheckTransactionResponse

NameTypeDescription
successboolWhether or not the transaction passed the submission checks.
codeuint32Error code to indicate the category of failure if the transaction was not successfully checked.
gas_wantedint64Amount of space in a block that the transaction will fill. This does not relate to any monetary cost for submitting the transaction.
gas_usedint64Unused.
datastringFurther details for why the transaction was not successfully submitted.
logstringFurther details for the underlying consensus layer of the result of the transaction.
infostringUnused.

GetSpamStatisticsRequest

Request to retrieve the spam statistics of a party for the given epoch

NameTypeDescription
party_idstringParty ID whose statistics are requested

GetSpamStatisticsResponse

Response containing all the spam statistics of a party for the current epoch

NameTypeDescription
chain_idstringChain ID for which the statistics are captured.
statisticsSpamStatisticsSpam statistics for the party

GetVegaTimeRequest

Request for the current time of the Vega network

NameTypeDescription

GetVegaTimeResponse

Response for the current consensus coordinated time on the Vega network, referred to as "VegaTime"

NameTypeDescription
timestampint64Timestamp representation of current VegaTime as represented in Unix nanoseconds, for example `1580473859111222333` corresponds to `2020-01-31T12:30:59.111222333Z`

LastBlockHeightRequest

Request to get the height of the very last block processed by tendermint

NameTypeDescription

LastBlockHeightResponse

Response with the height of the last block processed by tendermint

NameTypeDescription
heightuint64Last block height
hashstringLast block hash
spam_pow_hash_functionstringSupported proof of work hash function
spam_pow_difficultyuint32Difficulty of the proof of work, i.e. the target number of zeros
spam_pow_number_of_past_blocksuint32Supported proof of work number of blocks behind current height allowed
spam_pow_number_of_tx_per_blockuint32Allowed number of transactions per block
spam_pow_increasing_difficultyboolBoolean indicating whether increasing difficulty is allowed for using the same height for more than `spam_pow_number_of_past_blocks` transactions
chain_idstringNetwork chain id from which the block comes from

ObserveEventBusRequest

Request to subscribe to a stream of one or more event types from the Vega event bus

NameTypeDescription
typerepeated vega.events.v1.BusEventTypeOne or more types of event, required field
market_idstringMarket ID to filter events for, optional field. If omitted, no markets will be filtered out.
party_idstringParty ID to filter events for, optional field. If omitted, no parties will be filtered out.
batch_sizeint64Batch 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.

ObserveEventBusResponse

Response to a subscribed stream of events from the Vega event bus

NameTypeDescription
eventsrepeated vega.events.v1.BusEventOne or more events that match the subscription request criteria.

PoWBlockState

Proof of Work state for a given block

NameTypeDescription
block_heightuint64Block height for the current Proof of Work state statistics
block_hashstringHash of the current block
transactions_seenuint64Total number of transactions seen in the block
expected_difficultyoptional uint64This 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.
hash_functionstringHashing function used to calculate the block hash
difficultyuint64Base difficulty for this block for when transactions seen < tx_per_block
tx_per_blockuint64Number 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
increasing_difficultyboolWhether or not this block allows for increasing proof-of-work difficulty if the tx-per-block-hash limit has been reached

PoWStatistic

Proof of work statistics for a party

NameTypeDescription
block_statesrepeated PoWBlockStateBlock state for each block in scope for PoW calculation
banned_untiloptional stringPoW banned until timestamp as RFC3339Nano
number_of_past_blocksuint64Number of block behind the current block whose hash can be used for proof-of-work calculations

PropagateChainEventRequest

Request for a new event sent by the blockchain queue to be propagated on Vega

NameTypeDescription
eventbytesChain event to propagate.
pub_keystringPublic key of the key pair used to sign messages.
signaturebytesSignature generated by the private key associated with the public key.

PropagateChainEventResponse

Response for a new event sent by the blockchain queue to be propagated on Vega

NameTypeDescription
successboolSuccess will be true if the event was accepted by the node, **Important** - success does not mean that the event is confirmed by consensus

SpamStatistic

Statistics for a given spam policy

NameTypeDescription
count_for_epochuint64Current transaction count received from the party during this epoch for this policy
max_for_epochuint64Maximum number of transactions allowed for this policy in an epoch
banned_untiloptional stringIf blocked the timestamp when the party will be unblocked as RFC3339Nano
min_tokens_requiredstringEffective minimum number of tokens required to submit a transaction of this type

SpamStatistics

Complete spam statistics captured for a given party

NameTypeDescription
proposalsSpamStatisticStatistics for proposal transactions made by the party.
delegationsSpamStatisticStatistics for delegation transactions made by the party.
transfersSpamStatisticStatistics for transfer transactions made by the party.
node_announcementsSpamStatisticStatistics for node announcement transactions made by the party.
votesVoteSpamStatisticsStatistics for proposal votes made by the party.
powPoWStatisticStatistics for proof of work difficulty observed per block for the party.
issue_signaturesSpamStatisticStatistics for multisig signatures issued for the party.
epoch_sequint64Epoch in which these statistics apply to.
create_referral_setSpamStatisticStatistics for transactions made by the party to create referral sets.
update_referral_setSpamStatisticStatistics for transactions made by the party to update referral sets.
apply_referral_codeSpamStatisticStatistics for transactions made by the party to apply referral codes.

Statistics

Vega domain specific statistics as reported by the node the caller is connected to

NameTypeDescription
block_heightuint64Current block height as reported by the Vega blockchain
backlog_lengthuint64Current backlog length i.e., number of transactions, that are waiting to be included in a block
total_peersuint64Total number of connected peers to this node
genesis_timestringGenesis block date and time formatted in ISO-8601 datetime format with nanosecond precision
current_timestringCurrent system date and time formatted in ISO-8601 datetime format with nanosecond precision
vega_timestringCurrent Vega date and time formatted in ISO-8601 datetime format with nanosecond precision
statusvega.ChainStatusStatus of the connection to the Vega blockchain
tx_per_blockuint64Transactions per block
average_tx_bytesuint64Average transaction size in bytes
average_orders_per_blockuint64Average orders per block
trades_per_seconduint64Trades emitted per second
orders_per_seconduint64Orders processed per second
total_marketsuint64Total markets on this Vega network
total_amend_orderuint64Total number of order amendments since genesis across all markets
total_cancel_orderuint64Total number of order cancellations since genesis across all markets
total_create_orderuint64Total number of order submissions since genesis across all markets
total_ordersuint64Total number of orders processed since genesis across all markets
total_tradesuint64Total number of trades emitted since genesis across all markets
order_subscriptionsuint32Current number of stream subscribers to order data
trade_subscriptionsuint32Current number of stream subscribers to trade data
candle_subscriptionsuint32Current number of stream subscribers to candlestick data
market_depth_subscriptionsuint32Current number of stream subscribers to market depth data
positions_subscriptionsuint32Current number of stream subscribers to positions data
account_subscriptionsuint32Current number of stream subscribers to account data
market_data_subscriptionsuint32Current number of stream subscribers to market data
app_version_hashstringVersion hash of the Vega node software
app_versionstringVersion of the Vega node software
chain_versionstringVersion of the underlying Vega blockchain
block_durationuint64Current block duration, in nanoseconds
uptimestringTotal uptime for this node formatted in ISO-8601 datetime format with nanosecond precision
chain_idstringUnique ID for the underlying Vega blockchain
market_depth_updates_subscriptionsuint32Current number of stream subscribers to market depth update data
block_hashstringCurrent block hash
epoch_sequint64Current epoch
epoch_start_timestringEpoch start time
epoch_expiry_timestringEpoch expected end time
event_countuint64Number of events in the last block
events_per_seconduint64Rate of events per second in the last block

StatisticsRequest

Request for statistics about the Vega network

NameTypeDescription

StatisticsResponse

Response containing statistics about the Vega network

NameTypeDescription
statisticsStatistics

SubmitRawTransactionRequest

Request for submitting a version agnostic transaction on Vega

NameTypeDescription
txbytesBundle of signed payload and signature marshalled into a byte array, to form a transaction that will be submitted to the Vega blockchain
typeSubmitRawTransactionRequest.TypeType of transaction request, for example ASYNC, meaning the transaction will be submitted and not block on a response

SubmitRawTransactionResponse

Response for submitting a version agnostic transaction on Vega

NameTypeDescription
successboolWhether or not the transaction was validated and submitted to the chain's mempool.
tx_hashstringHash of the transaction, which can be used to identify the transaction in a node's event stream.
codeuint32Error code to indicate the category of failure if the transaction was not successfully submitted.
datastringFurther details for why the transaction was not successfully submitted.
logstringFurther details for the underlying consensus layer of the result of the transaction.
heightint64Unused.

SubmitTransactionRequest

Request for submitting a transaction v2 on Vega

NameTypeDescription
txvega.commands.v1.TransactionTransaction containing a command to execute on the network, and a signature to provide authentication.
typeSubmitTransactionRequest.TypeMethod of submission.

SubmitTransactionResponse

Response for submitting a transaction on the network.

NameTypeDescription
successboolWhether or not the transaction was validated and submitted to the chain's mempool.
tx_hashstringHash of the transaction, which can be used to identify the transaction in a node's event stream.
codeuint32Error code to indicate the category of failure if the transaction was not successfully submitted.
datastringFurther details for why the transaction was not successfully submitted.
logstringFurther details for the underlying consensus layer of the result of the transaction.
heightint64Unused.

VoteSpamStatistic

Vote statistics for the voting spam policies which are calculated as a ratio of the total votes that have been rejected.

NameTypeDescription
proposalstringUnique ID of the proposal being voted on by the party.
count_for_epochuint64Current vote count received from the party for the given proposal during this epoch
min_tokens_requiredstringEffective minimum number of tokens required to vote on the proposal

VoteSpamStatistics

Voting statistics by proposal for a given party for the current epoch

NameTypeDescription
statisticsrepeated VoteSpamStatisticList of statistics for proposals voted on by the party
max_for_epochuint64Maximum number of votes per proposal allowed in an epoch
banned_untiloptional stringIf blocked the timestamp when the party will be unblocked as RFC3339Nano

Enums

SubmitRawTransactionRequest.Type

Blockchain transaction type

NameNumberDescription
TYPE_UNSPECIFIED0
TYPE_ASYNC1Transaction will be submitted without waiting for response
TYPE_SYNC2Transaction will be submitted, and blocking until the tendermint mempool returns a response
TYPE_COMMIT3Transaction will be submitted, and blocking until the tendermint network has committed it into a block. Used only for debugging, not for submitting transactions

SubmitTransactionRequest.Type

Blockchain transaction type.

NameNumberDescription
TYPE_UNSPECIFIED0
TYPE_ASYNC1Transaction will be submitted without waiting for a response.
TYPE_SYNC2Transaction will be submitted, and blocking until the mempool returns a response.
TYPE_COMMIT3Transaction will be submitted, and blocking until the network has committed it into a block. Used only for debugging local network, not for submitting transactions.

Services

CoreService

SubmitTransaction

MethodSubmitTransaction
RequestSubmitTransactionRequest
ResponseSubmitTransactionResponse
DescriptionSubmit 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.

PropagateChainEvent

MethodPropagateChainEvent
RequestPropagateChainEventRequest
ResponsePropagateChainEventResponse
DescriptionChain event Propagate a chain event

Statistics

MethodStatistics
RequestStatisticsRequest
ResponseStatisticsResponse
DescriptionStatistics Get statistics on Vega

LastBlockHeight

MethodLastBlockHeight
RequestLastBlockHeightRequest
ResponseLastBlockHeightResponse
DescriptionBlockchain height Get the height of the last tendermint block

GetVegaTime

MethodGetVegaTime
RequestGetVegaTimeRequest
ResponseGetVegaTimeResponse
DescriptionVega time Get current Vega time

ObserveEventBus

MethodObserveEventBus
RequestObserveEventBusRequest stream
ResponseObserveEventBusResponse stream
DescriptionEvents subscription Subscribe to a stream of events from the core

SubmitRawTransaction

MethodSubmitRawTransaction
RequestSubmitRawTransactionRequest
ResponseSubmitRawTransactionResponse
DescriptionSubmit 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.

CheckTransaction

MethodCheckTransaction
RequestCheckTransactionRequest
ResponseCheckTransactionResponse
DescriptionCheck 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.

CheckRawTransaction

MethodCheckRawTransaction
RequestCheckRawTransactionRequest
ResponseCheckRawTransactionResponse
DescriptionCheck 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.

GetSpamStatistics

MethodGetSpamStatistics
RequestGetSpamStatisticsRequest
ResponseGetSpamStatisticsResponse
DescriptionGet Spam statistics Get the spam statistics for a given party.