Skip to main content
Version: mainnet (v0.53)

Build and send commands

This guide will teach you how to build a Vega command to include in a transaction. Once you create a command, to create a transaction you will need to sign it, and include your public key and the block height you are targeting.

Build commands​

A command is an action you want to issue to the network. To submit that command to the network, you will need to sign it to verify it, and add in other data.

Vega Wallet allows you to send and sign commands to the Vega network by using the following wallet commands:

  • vegawallet command send: turns a command into a transaction and send it
  • vegawallet command sign: turns a command into a transaction (base64-encoded) without sending it
Commands and transactions are different

A Vega transaction is a bundle containing a Vega command, a signature, a public key and target block height.

There are other Vega Wallet commands that allow you to work with Vega transactions (base64-encoded), such as vegawallet tx send.

Inserting a Vega command in vegawallet tx send will fail, as it requires a transaction, hence a bundled Vega command with its signature. Inserting a Vega transaction in vegawallet command sign will fail, as it requires a Vega command only, without signature or any other data.

danger

Only gRPC commands are supported.

HTTP REST and GraphQL commands are not supported.

gRPC reference documentation for commands​

The supported commands can be found here:

Command format​

The gRPC command needs to be formatted as a JSON payload, as follows:

{"commandName": {"someProperty": "someValue", "anObject": {"nestedProperty":42}}}
  • commandName is the name of the command you want to submit, such as "voteSubmission", or "orderCancellation". It should be camel or snake case.
  • someProperty is the name of the property or properties that are required by the command, such as "proposalId" on "voteSubmission", or "price" on "orderSubmission". It should be camel or snake case.
  • If the command you want to send has nested fields, anObject is the name of the object that wraps them, such as "peggedOrder" on "orderSubmission", or "terms" on "proposalSubmission".

Example commands​

Submit vote for governance proposal​

{
  "voteSubmission": {
    "proposalId": "some-id",
    "value": "VALUE_YES"
  }
}

Submit order on a market​

This is a partial example for order submission

{
  "orderSubmission": {
    "marketId": "1234", 
    "price": "42", 
    "size":10, 
    "side": "SIDE_BUY", 
    "timeInForce": "TIME_IN_FORCE_FOK",
    "type": "TYPE_LIMIT"
  }
}

Send commands​

Tips for sending commands

  1. Write the command on a single line to prevent problems with the CLI not properly handling multiple arguments.
  2. Wrap the JSON payload with single quotes in the command line to prevent the CLI from interpreting the JSON command as a special command.

Command structure

vegawallet command-name '{"commandName": {"someProperty": "someValue", "anObject": {"nestedProperty":42}}}'

Send the command to the first node configured in the network configuration, via its gRPC API using:

vegawallet command send --network "NETWORK" --wallet "MY_WALLET_NAME" --pubkey "MY_PUBLIC_KEY"

Customise the number of retries (default to 5) using:

vegawallet command send --retries 10

If you don't want to rely on the nodes defined in the network configuration, you can specify a node address:

vegawallet command send --node-address "ADDRESS"

See more options by using the help flag:

vegawallet command send --help

Create transactions with air-gapped wallets​

This is useful for validators that are signing validator commands using their root keys.

The workflow is:

  1. Build and sign a Vega command on an air-gapped computer to get a base64 encoded transaction
  2. Send that transaction using an online computer

1. Build transaction on an air-gapped computer​

This will build a transaction containing the specified command, its signature and additional protocol related data:

vegawallet command sign --wallet "MY_WALLET_NAME" --pubkey "MY_PUBLIC_KEY" --tx-height "TRANSACTION_BLOCK_HEIGHT" "COMMAND"

TRANSACTION_BLOCK_HEIGHT must be close to the current block height when the transaction is applied, with a threshold of approximately 150 blocks. Note: If it is higher than the blockchain's block height, it will be rejected.

The resulting transaction is encoded using base64.

You can decode it using base64 command line utility. First save the transaction in a file result.txt, then use:

base64 --decode --input result.txt

The transaction will be decoded and displayed on screen.

2. Send transaction with an online computer​

Use any way to transfer the transaction from your air-grapped computer to the online one.

Then, send the transaction using:

vegawallet tx send --network "NETWORK" "BASE64_TRANSACTION"
Block height

You will need to respect the block height that you set in you transaction with the command vegawallet command sign.

You must wait if the block height you define is higher than the blockchain's block height. Transactions set with a future block height will be rejected.

If the block height you set is smaller than the blockchain's block height, you should send your transaction ASAP. If it's too small (~ > 150), it will be rejected by the replay protection mechanism.

If the current height is 200:

  • a transaction with block height 10 is rejected because 200 - 10 = 190 and 190 > 150
  • a transaction with block height 60 is accepted because 200 - 60 = 140 and 140 < 150
  • a transaction with block height 201 is rejected because 200 - 201 = -1 and -1 is in the future