Setup the development environment using Truffle

This guide will cover the process of setting up your local environment for developing on the VeChainThor blockchain using the standard web3 stack.

Getting Started

This guide assumes you are using MacOS with homebrew and pip3 installed. We welcome any pull requests to expand this guide to other platforms.


Development Stack

VeChain Development Stack


Running the VeChainThor Local Node

We recommend developer to set up a VeChainThor node running locally for development. This will be your own local testnet that you can easiliy spin up or down without having to worry about affecting the rest of the network.


  • Thor requires Go 1.10+ and C compiler to build. To install Go, follow this link.
  • Install dep dependency manager for Go.

Getting the source

Clone the Thor repo:

git clone

Install dependencies

Simply run:

make dep


To build the thor node application run


Running node

Once built you will want to run the node in solo mode. This instructs the node to run locally as its own network instead of connecting to testnet or mainnet.

./bin/thor solo --api-cors "*"

The --api-cors flag enables secure websocket connections from web3 and the Comet extension.


Web3-Gear is a proxy server that converts Eth JSON-RPC to VeChainThor’s RESTful API. You will need to run web3-gear so that truffle can talk to your local VeChainThor node.


  • Python 3.6+ support
  • OpenSSL


Install the system-dependecies:

brew install openssl

Installation of Web3-Gear and it’s dependent Python packages via PyPI:

pip3 install web3-gear



Other useful options

These options will be useful in later sections for deploying your contracts to testnet or mainnet.

| Flag | Description | | ———- | ————————————————————- | | –host | rpc service host, eg: --host | | –port | rpc service port, eg: --port 8545 | | –keystore | custom keystore filepath, eg: --keystore /path/to/keystore) | | –passcode | passcode of custom keystore, eg: --passcode xxxxxxxx |


Truffle is your development environment for building and deploying contract code. Truffle is an Ethereum project however using web3-gear, can work with VeChainThor.

If you do not already have a truffle project started please start by reading through their documentation


Once you have a truffle project setup you may configure your project to talk to web3-gear by updating your truffle.js file

module.exports = {
    networks: {
        development: {
            host: "localhost",
            port: 8545,        // Default web3-gear port
            network_id: "*"    // Match any network id


To deploy your project’s contracts to your local VeChainThor node run

truffle migrate

Deploying to full network

  • Deploying to testnet or mainnet can be accomplish by pointing your web3-gear at a testnet or mainnet node using the --host and --port flags
  • When deploying to testnet or mainnet you’ll need to load your own wallet into web3-gear using the --keystore and --passcode flags. Make sure to also use this address in your truffle migration scripts


To debug a transaction run

truffle debug <TxID>

Note that this only works in the latest master of thor. You must run your local node in solo mode and not use the --persist or --on-demand flags. This feature is a work in progress so you may experience bugs while using.