This guide describes how to add Velas native token VLX to your cryptocurrency exchange.
We highly recommend setting up at least two of your own Velas api nodes to give you a trusted entrypoint to the network, allow you full control over how much data is retained, and ensure you do not miss any data if one node fails.
To run an api node:
- Install the Velas command-line tool suite
- Boot the node with at least the following parameters:
--ledger to your desired ledger storage location, and
--rpc-port to the port you want to expose.
--expected-genesis-hash parameters are all specific to the cluster you are joining.
Current parameters for Mainnet Beta
--limit-ledger-size parameter allows you to specify how many ledger shreds your node retains on disk. If you do not include this parameter, the validator will keep the entire ledger until it runs out of disk space. The default value attempts to keep the ledger disk usage under 500GB. More or less disk usage may be requested by adding an argument to
--limit-ledger-size if desired. Check
velas-validator --help for the default limit value used by
--limit-ledger-size. More information about selecting a custom limit value is available here.
Specifying one or more
--trusted-validator parameters can protect you from booting from a malicious snapshot. More on the value of booting with trusted validators
Optional parameters to consider:
--private-rpcprevents your RPC port from being published for use by other nodes
--rpc-bind-addressallows you to specify a different IP address to bind the RPC port
We recommend configuring each of your nodes to restart automatically on exit, to ensure you miss as little data as possible. Running the velas software as a systemd service is one great option.
By default, each of your nodes will boot from a snapshot provided by one of your
trusted validators. This snapshot reflects the current state of the chain, but
does not contain the complete historical ledger. If one of your node exits and
boots from a new snapshot, there may be a gap in the ledger on that node. In
order to prevent this issue, add the
--no-snapshot-fetch parameter to your
velas-validator command to receive historical ledger data instead of a
If you pass the
--no-snapshot-fetch parameter on your initial boot, it will
take your node a very long time to catch up. We recommend booting from a
snapshot first, and then using the
--no-snapshot-fetch parameter for reboots.
It is important to note that the amount of historical ledger available to your nodes is limited to what your trusted validators retain. You will need to ensure your nodes do not experience downtimes longer than this span, if ledger continuity is crucial for you.
Setting up Deposit Accounts
Velas accounts do not require any on-chain initialization; once they contain some VLX, they exist. To set up a deposit account for your exchange, simply generate a Velas keypair using any of our wallet tools.
We recommend using a unique deposit account for each of your users.
Velas accounts are charged rent on creation and once per
epoch, but they can be made rent-exempt if they contain 2-years worth of rent in
VLX. In order to find the minimum rent-exempt balance for your deposit accounts,
You may wish to keep the keys for one or more collection accounts offline for greater security. If so, you will need to move VLX to hot accounts using our offline methods.
Listening for Deposits
When a user wants to deposit VLX into your exchange, instruct them to send a transfer to the appropriate deposit address.
Validating User-supplied Account Addresses for Withdrawals in VLX
As withdrawals are irreversible, it may be a good practice to validate the account address before authorizing withdrawals into user-supplied accounts to prevent accidental user's fund loss.
For a normal account in Velas, its address is simply a Base58-encoded actual 256-bit public key of ed25519. Because not all bit pattern is a valid public key for the ed25519, it's possible to make sure user-supplied account addresses are at least something that may be a correct ed25519 public key.
You can check Velas normal account address validity by first decoding Base58 string and ensuring the decoded bytes are valid ed25519 public keys like this:
The following code sample assumes you're using the Maven.
Poll for Blocks
The easiest way to track all the deposit accounts for your exchange is to poll for each confirmed block and inspect for addresses of interest, using the JSON-RPC service of your Velas api node.
- To identify which blocks are available, send a
getConfirmedBlocksrequest, passing the last block you have already processed as the start-slot parameter:
Not every slot produces a block, so there may be gaps in the sequence of integers.
- For each block, request its contents with a
postBalances fields allow you to track the balance
changes in every account without having to parse the entire transaction. They
list the starting and ending balances of each account in
lamport, indexed to the
accountKeys list. For
example, if the deposit address if interest is
47Sbuv6jL7CViK9F2NMW51aQGhfdpUu7WNvKyH645Rfi, this transaction represents a
transfer of 218099990000 - 207099990000 = 11000000000 lamports = 11 VLX
You can also query the transaction history of a specific address.
- Send a
getConfirmedSignaturesForAddressrequest to the api node, specifying a range of recent slots:
- For each signature returned, get the transaction details by sending a
To accommodate a user's request to withdraw VLX, you must generate a Velas transfer transaction, and send it to the api node to be forwarded to your cluster.
Sending a synchronous transfer to the Velas cluster allows you to easily ensure that a transfer is successful and finalized by the cluster.
Velas command-line tool offers a simple command,
velas transfer, to
generate, submit, and confirm transfer transactions. By default, this method
will wait and track progress on stderr until the transaction has been finalized
by the cluster. If the transaction fails, it will report any transaction errors.
offers a similar approach for the JS ecosystem. Use the
SystemProgram to build
a transfer transaction, and submit it using the
For greater flexibility, you can submit withdrawal transfers asynchronously. In these cases, it is your responsibility to verify that the transaction succeeded and was finalized by the cluster.
Note: Each transaction contains a recent blockhash to indicate its liveness. It is critical to wait until this blockhash expires before retrying a withdrawal transfer that does not appear to have been confirmed or finalized by the cluster. Otherwise, you risk a double spend. See more on blockhash expiration below.
First, get a recent blockhash using the
or the CLI command:
In the command-line tool, pass the
--no-wait argument to send a transfer
asynchronously, and include your recent blockhash with the
You can also build, sign, and serialize the transaction manually, and fire it off to
the cluster using the JSON-RPC
Transaction Confirmations & Finality
Get the status of a batch of transactions using the
getSignatureStatuses JSON-RPC endpoint.
confirmations field reports how many
confirmed blocks have elapsed since the
transaction was processed. If
confirmations: null, it is finalized.
When you request a recent blockhash for your withdrawal transaction using the
getFees endpoint or
velas fees, the
response will include the
lastValidSlot, the last slot in which the blockhash
will be valid. You can check the cluster slot with a
getSlot query; once the cluster slot is
lastValidSlot, the withdrawal transaction using that blockhash
should never succeed.
You can also doublecheck whether a particular blockhash is still valid by sending a
request with the blockhash as a parameter. If the response value is null, the
blockhash is expired, and the withdrawal transaction should never succeed.
Testing the Integration
Be sure to test your complete workflow on Velas devnet and testnet clusters before moving to production on mainnet-beta. Devnet is the most open and flexible, and ideal for initial development, while testnet offers more realistic cluster configuration. Devnet features a token faucet, but you will need to request some testnet VLX to get going on testnet.