Wallets and Signing

Wallets and Signing on Vega

What is a wallet?

A wallet is a file on your computer that stores your key pairs. This file can contain any number of key pairs, possibly along with extra data, such as a nickname for a key.

A wallet service is a program on your computer that reads and writes wallet files, by creating or removing key pairs. Wallet services are encrypted, and you’ll need to choose a password/passphrase to decrypt it, to access its contents.

Every person / participant needs at least one wallet to use Vega. One wallet can have many key pairs, and each public key acts as a completely different party on Vega, even if the keys are derived from the same wallet. Read more about key pairs below.

Note: When you deposit assets using the bridge, you deposit to a public key (not to a wallet), so each public key that you want to use for trading will need its own pool of assets. Each public key is the party ID used for trading, and one public key cannot share collateral with other public keys in the same wallet.

What wallets can you use with Vega?

Vega has a self-hosted, local wallet. To use it, download the zip file and follow the instructions in the Vega Go Wallet GitHub repository. Using this wallet, your keys will be completely disassociated from your personal identity, and we will have no way to connect them, unless you share your public key for any reason.

For testnet, Vega has also hosted a version of the wallet server, to make it easier to quickly start trading. A hosted wallet service is a website that manages wallet access for multiple users. Each user only has access to their own wallets. Wallet files are stored remotely, not on your computer, and access is only possible via the website. You can request wallet credentials from Vega on Discord.

Note: Even though this is a testnet, you should never share your private keys, or your wallet passphrase.

Whether you use the Vega-hosted wallet server, or the self-hosted wallet, the Vega network doesn’t know about the Vega wallet server, or anything about your login information locally, or your personal information. All it sees is the public key and cryptographic signature that comes along with the transaction. That’s enough for it to know that the correct person has the authority to manage collateral, place orders, request withdrawal, or vote on governance actions.

Learn more about depositing collateral with your public key on the deposits page.

Should I be setting up my own wallet to use the Vega testnet?

It’s recommended that you set up your own wallet and stop using the Vega-hosted wallet credentials, but you’re welcome to keep using them if you find them much easier to interact with.

Right now, if you attempt to connect your self-hosted, local wallet (on http://localhost/) directly to the hosted Console on https://testnet.vega.xyz, you’ll run into cross-site security issues, and won’t be able to connect. We’ve added a feature to the Wallet that allows you to get around this. If you’re using the Vega-hosted wallet, then you can still successfully use https://testnet.vega.trading.

Building a web-based wallet is in progress, and that will make the process smoother.

Is there an API reference for the Vega Wallet service?

We have a full REST API reference for interacting with both Vega-hosted and self-hosted, local Vega wallets.

What is a key pair?

A key pair is two keys, created together. One is public (shared with everyone), and one is private (only you know it). If data is encrypted with the public key, only the private key can decrypt it, and vice versa. This means that it is possible to do two things:

  • Share secret data: If someone encrypts data with your public key, then only you can decrypt it with your private key
  • Authenticate data, also known as sign data: If Pat encrypts data with their private key, then anyone can decrypt it with their public key, and they know that only Pat could have encrypted this data

How does the Vega network use public and private keys?

To trade or take other actions on Vega, the requests you make to the network need to be signed with a set of keys, one public and one private. The public key provides enough information to verify that a transaction was signed and is valid, and that only the holder of the private key could have signed the transaction. This allows the network to authenticate you as the holder of any collateral balances and open positions, and identifies you when you vote on any governance actions.

When you want to do something on the Vega testnet, for example place an order, Console creates a representation of the order, uses the wallet server to sign it with the private key to prove that only you could have done it, and then submits it to the network. The public key is included in this, meaning anyone can verify that it’s signed by you. The public key doesn’t reveal your name, or who it’s owned by, it only shows your interactions with the Vega network.

How does Vega Console use my keys?

Console itself never directly uses your public and private key.

  • Console accesses your wallets through a wallet service, which is either the testnet’s demonstration key service, or another Vega wallet running the wallet server, such as one installed on your computer or that you or your employer hosts
  • Console knows your public key but will never have access to your private key, which is seen only by the wallet software
  • You select a set of keys, held by the wallet, in order to authenticate your transaction
  • Console then forwards this transaction, signed and bundled by the wallet service using a set of keys from your wallet, to the Vega network

When real money is at stake you should ensure that the system running the wallet is secure, and that you trust whoever is running it, as they can potentially access all of your funds and act as you on the Vega network.

How are transactions signed on Vega?

In order to submit signed transactions to a Vega node, you need to connect to a Vega Wallet server, which handles your key pairs for you and signs transactions using a specified key pair.

Alongside a self-hosted, local wallet for testnet demonstration purposes, Vega offers a centralised wallet server. The URL for this is https://wallet.testnet.vega.xyz/api/v1. (If you’re using the self-hosted, local wallet, you can get the URL by running your wallet.) To verify if the Vega hosted wallet service is online use https://wallet.testnet.vega.xyz/api/v1/status.

To check connectivity, use its status endpoint.

On mainnet, everyone will need to run their own private wallet server: Your private keys, under your control, your responsibility. Each wallet file stored on disk is encrypted with that wallet’s passphrase. Security and backups will be the responsibility of each individual.

Since neither Vega nodes nor the Vega team have access to anyone’s private keys, they are not able to backup or restore lost keys, and not able to modify signed transactions.

For a full examples of Wallet server usage, see how to submit an order or the REST API information for Vega Wallet.

What happens to a transaction when it is submitted to a node?

When transactions (e.g. SubmitOrder, AmendOrder) are submitted to a node, they are first shared among all other nodes. Invalid transactions are discarded, and valid transactions are sequenced deterministically. Nodes propose a block, then reach agreement by voting. Once the block is agreed, the transactions are finally on the blockchain.

What is the difference between a transaction ID and a transaction reference?

When a transaction is submitted, it is assigned a reference before it is included in a block, i.e. when it is pre-consensus. The reference can be used to check on the progress of a transaction.

A valid transaction has an ID assigned as it is included in a block, i.e. when it is post-consensus.

What is the difference between a pre-consensus transaction and a post-consensus one?

A pre-consensus transaction, having not yet been included in a block, has not yet “happened”. Conversely, a post-consensus transaction has been included in a block, and has “happened”.

For example, a pre-consensus SubmitOrder has not yet been executed, so it hasn’t yet been added to the order book, it hasn’t yet been filled-or-killed, etc.