core.proto

path vega/api/v1/core.proto

package vega.api.v1

---

Messages

CheckRawTransactionRequest

Request for checking a version agnostic transaction on Vega

Name	Type	Description
tx	bytes	Bundle 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

Name	Type	Description
success	bool	Whether or not the transaction passed the submission checks.
code	uint32	Error code to indicate the category of failure if the transaction was not successfully submitted.
gas_wanted	int64	Amount of space in a block that the transaction will fill. This does not relate to any monetary cost for submitting the transaction.
gas_used	int64	Unused.
data	string	Further details for why the transaction was not successfully checked.
log	string	Further details for the underlying consensus layer of the result of the transaction.
info	string	Unused

CheckTransactionRequest

Request for checking a transaction v2 on Vega

Name	Type	Description
tx	vega.commands.v1.Transaction	Transaction containing a command to be checked on the network, and not added to the chain's mempool.

CheckTransactionResponse

Name	Type	Description
success	bool	Whether or not the transaction passed the submission checks.
code	uint32	Error code to indicate the category of failure if the transaction was not successfully checked.
gas_wanted	int64	Amount of space in a block that the transaction will fill. This does not relate to any monetary cost for submitting the transaction.
gas_used	int64	Unused.
data	string	Further details for why the transaction was not successfully submitted.
log	string	Further details for the underlying consensus layer of the result of the transaction.
info	string	Unused.

GetSpamStatisticsRequest

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

Name	Type	Description
party_id	string	Party ID whose statistics are requested

GetSpamStatisticsResponse

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

Name	Type	Description
chain_id	string	Chain ID for which the statistics are captured.
statistics	SpamStatistics	Spam statistics for the party

GetVegaTimeRequest

Request for the current time of the Vega network

Name	Type	Description

GetVegaTimeResponse

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

Name	Type	Description
timestamp	int64	Timestamp 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

Name	Type	Description

LastBlockHeightResponse

Response with the height of the last block processed by tendermint

Name	Type	Description
height	uint64	Last block height
hash	string	Last block hash
spam_pow_hash_function	string	Supported proof of work hash function
spam_pow_difficulty	uint32	Difficulty of the proof of work, i.e. the target number of zeros
spam_pow_number_of_past_blocks	uint32	Supported proof of work number of blocks behind current height allowed
spam_pow_number_of_tx_per_block	uint32	Allowed number of transactions per block
spam_pow_increasing_difficulty	bool	Boolean indicating whether increasing difficulty is allowed for using the same height for more than `spam_pow_number_of_past_blocks` transactions
chain_id	string	Network 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

Name	Type	Description
type	repeated vega.events.v1.BusEventType	One or more types of event, required field
market_id	string	Market ID to filter events for, optional field. If omitted, no markets will be filtered out.
party_id	string	Party ID to filter events for, optional field. If omitted, no parties will be filtered out.
batch_size	int64	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.

ObserveEventBusResponse

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

Name	Type	Description
events	repeated vega.events.v1.BusEvent	One or more events that match the subscription request criteria.

PoWBlockState

Proof of Work state for a given block

Name	Type	Description
block_height	uint64	Block height for the current Proof of Work state statistics
block_hash	string	Hash of the current block
transactions_seen	uint64	Total number of transactions seen in the block
expected_difficulty	optional uint64	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.
hash_function	string	Hashing function used to calculate the block hash
difficulty	uint64	Base difficulty for this block for when transactions seen < tx_per_block
tx_per_block	uint64	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
increasing_difficulty	bool	Whether 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

Name	Type	Description
block_states	repeated PoWBlockState	Block state for each block in scope for PoW calculation
banned_until	optional string	PoW banned until timestamp as RFC3339Nano
number_of_past_blocks	uint64	Number 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

Name	Type	Description
event	bytes	Chain event to propagate.
pub_key	string	Public key of the key pair used to sign messages.
signature	bytes	Signature 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

Name	Type	Description
success	bool	Success 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

Name	Type	Description
count_for_epoch	uint64	Current transaction count received from the party during this epoch for this policy
max_for_epoch	uint64	Maximum number of transactions allowed for this policy in an epoch
banned_until	optional string	If blocked the timestamp when the party will be unblocked as RFC3339Nano
min_tokens_required	string	Effective minimum number of tokens required to submit a transaction of this type

SpamStatistics

Complete spam statistics captured for a given party

Name	Type	Description
proposals	SpamStatistic	Statistics for proposal transactions made by the party.
delegations	SpamStatistic	Statistics for delegation transactions made by the party.
transfers	SpamStatistic	Statistics for transfer transactions made by the party.
node_announcements	SpamStatistic	Statistics for node announcement transactions made by the party.
votes	VoteSpamStatistics	Statistics for proposal votes made by the party.
pow	PoWStatistic	Statistics for proof of work difficulty observed per block for the party.
issue_signatures	SpamStatistic	Statistics for multisig signatures issued for the party.
epoch_seq	uint64	Epoch in which these statistics apply to.
create_referral_set	SpamStatistic	Statistics for transactions made by the party to create referral sets.
update_referral_set	SpamStatistic	Statistics for transactions made by the party to update referral sets.
apply_referral_code	SpamStatistic	Statistics 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

Name	Type	Description
block_height	uint64	Current block height as reported by the Vega blockchain
backlog_length	uint64	Current backlog length i.e., number of transactions, that are waiting to be included in a block
total_peers	uint64	Total number of connected peers to this node
genesis_time	string	Genesis block date and time formatted in ISO-8601 datetime format with nanosecond precision
current_time	string	Current system date and time formatted in ISO-8601 datetime format with nanosecond precision
vega_time	string	Current Vega date and time formatted in ISO-8601 datetime format with nanosecond precision
status	vega.ChainStatus	Status of the connection to the Vega blockchain
tx_per_block	uint64	Transactions per block
average_tx_bytes	uint64	Average transaction size in bytes
average_orders_per_block	uint64	Average orders per block
trades_per_second	uint64	Trades emitted per second
orders_per_second	uint64	Orders processed per second
total_markets	uint64	Total markets on this Vega network
total_amend_order	uint64	Total number of order amendments since genesis across all markets
total_cancel_order	uint64	Total number of order cancellations since genesis across all markets
total_create_order	uint64	Total number of order submissions since genesis across all markets
total_orders	uint64	Total number of orders processed since genesis across all markets
total_trades	uint64	Total number of trades emitted since genesis across all markets
order_subscriptions	uint32	Current number of stream subscribers to order data
trade_subscriptions	uint32	Current number of stream subscribers to trade data
candle_subscriptions	uint32	Current number of stream subscribers to candlestick data
market_depth_subscriptions	uint32	Current number of stream subscribers to market depth data
positions_subscriptions	uint32	Current number of stream subscribers to positions data
account_subscriptions	uint32	Current number of stream subscribers to account data
market_data_subscriptions	uint32	Current number of stream subscribers to market data
app_version_hash	string	Version hash of the Vega node software
app_version	string	Version of the Vega node software
chain_version	string	Version of the underlying Vega blockchain
block_duration	uint64	Current block duration, in nanoseconds
uptime	string	Total uptime for this node formatted in ISO-8601 datetime format with nanosecond precision
chain_id	string	Unique ID for the underlying Vega blockchain
market_depth_updates_subscriptions	uint32	Current number of stream subscribers to market depth update data
block_hash	string	Current block hash
epoch_seq	uint64	Current epoch
epoch_start_time	string	Epoch start time
epoch_expiry_time	string	Epoch expected end time
event_count	uint64	Number of events in the last block
events_per_second	uint64	Rate of events per second in the last block

StatisticsRequest

Request for statistics about the Vega network

Name	Type	Description

StatisticsResponse

Response containing statistics about the Vega network

Name	Type	Description
statistics	Statistics

SubmitRawTransactionRequest

Request for submitting a version agnostic transaction on Vega

Name	Type	Description
tx	bytes	Bundle of signed payload and signature marshalled into a byte array, to form a transaction that will be submitted to the Vega blockchain
type	SubmitRawTransactionRequest.Type	Type 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

Name	Type	Description
success	bool	Whether or not the transaction was validated and submitted to the chain's mempool.
tx_hash	string	Hash of the transaction, which can be used to identify the transaction in a node's event stream.
code	uint32	Error code to indicate the category of failure if the transaction was not successfully submitted.
data	string	Further details for why the transaction was not successfully submitted.
log	string	Further details for the underlying consensus layer of the result of the transaction.
height	int64	Unused.

SubmitTransactionRequest

Request for submitting a transaction v2 on Vega

Name	Type	Description
tx	vega.commands.v1.Transaction	Transaction containing a command to execute on the network, and a signature to provide authentication.
type	SubmitTransactionRequest.Type	Method of submission.

SubmitTransactionResponse

Response for submitting a transaction on the network.

Name	Type	Description
success	bool	Whether or not the transaction was validated and submitted to the chain's mempool.
tx_hash	string	Hash of the transaction, which can be used to identify the transaction in a node's event stream.
code	uint32	Error code to indicate the category of failure if the transaction was not successfully submitted.
data	string	Further details for why the transaction was not successfully submitted.
log	string	Further details for the underlying consensus layer of the result of the transaction.
height	int64	Unused.

VoteSpamStatistic

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

Name	Type	Description
proposal	string	Unique ID of the proposal being voted on by the party.
count_for_epoch	uint64	Current vote count received from the party for the given proposal during this epoch
min_tokens_required	string	Effective minimum number of tokens required to vote on the proposal

VoteSpamStatistics

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

Name	Type	Description
statistics	repeated VoteSpamStatistic	List of statistics for proposals voted on by the party
max_for_epoch	uint64	Maximum number of votes per proposal allowed in an epoch
banned_until	optional string	If blocked the timestamp when the party will be unblocked as RFC3339Nano

---

Enums

SubmitRawTransactionRequest.Type

Blockchain transaction type

Name	Number	Description
TYPE_UNSPECIFIED	0
TYPE_ASYNC	1	Transaction will be submitted without waiting for response
TYPE_SYNC	2	Transaction will be submitted, and blocking until the tendermint mempool returns a response
TYPE_COMMIT	3	Transaction 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.

Name	Number	Description
TYPE_UNSPECIFIED	0
TYPE_ASYNC	1	Transaction will be submitted without waiting for a response.
TYPE_SYNC	2	Transaction will be submitted, and blocking until the mempool returns a response.
TYPE_COMMIT	3	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.

---

Services

CoreService

SubmitTransaction

Method	SubmitTransaction
Request	SubmitTransactionRequest
Response	SubmitTransactionResponse
Description	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.

PropagateChainEvent

Method	PropagateChainEvent
Request	PropagateChainEventRequest
Response	PropagateChainEventResponse
Description	Chain event Propagate a chain event

Statistics

Method	Statistics
Request	StatisticsRequest
Response	StatisticsResponse
Description	Statistics Get statistics on Vega

LastBlockHeight

Method	LastBlockHeight
Request	LastBlockHeightRequest
Response	LastBlockHeightResponse
Description	Blockchain height Get the height of the last tendermint block

GetVegaTime

Method	GetVegaTime
Request	GetVegaTimeRequest
Response	GetVegaTimeResponse
Description	Vega time Get current Vega time

ObserveEventBus

Method	ObserveEventBus
Request	ObserveEventBusRequest stream
Response	ObserveEventBusResponse stream
Description	Events subscription Subscribe to a stream of events from the core

SubmitRawTransaction

Method	SubmitRawTransaction
Request	SubmitRawTransactionRequest
Response	SubmitRawTransactionResponse
Description	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.

CheckTransaction

Method	CheckTransaction
Request	CheckTransactionRequest
Response	CheckTransactionResponse
Description	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.

CheckRawTransaction

Method	CheckRawTransaction
Request	CheckRawTransactionRequest
Response	CheckRawTransactionResponse
Description	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.

GetSpamStatistics

Method	GetSpamStatistics
Request	GetSpamStatisticsRequest
Response	GetSpamStatisticsResponse
Description	Get Spam statistics Get the spam statistics for a given party.

---