Tezos support in Truffle is experimental. Give it a spin, and help us out by filing issues on Github.

Tezos Quickstart

Wanna build apps on Tezos using Truffle? You're in the right place.

  1. Getting set up
  2. Installing Truffle
  3. Using the Tezos Truffle Box
  4. Writing Contracts
  5. Deploying Contracts
  6. Testing Contracts
  7. Further Resources

Before you can start developing Tezos applications with Truffle, you'll first need to ensure you have Docker installed on your machine. Installing docker let's Truffle easily use the latest LIGO compiler on any platform.

See Docker install instructions for your platform.

Docker on Windows: If you're developing on Windows, you need to install the Docker edge release instead of the mainline docker version. Trust us: This is a better experience.

  • NodeJS v8.9.4 or later
  • Windows, Linux or Mac OS X

You'll need to download a special version of Truffle to use Tezos.

$ npm install -g [email protected]

If you already have Truffle installed, we recommend uninstalling truffle before running the above command.

This quick start uses an already-created project to provide the base Truffle project structure and example contracts.

In your workspace directory, run the following commands:

$ mkdir tezos-example
$ cd tezos-example
$ truffle unbox tezos-example

The example box comes with two contracts, which you can find in the ./contracts folder:

  • Counter.ligo
  • Migrations.ligo
  • SimpleStorage.ligo

You can see that these contracts end in the .ligo file extension. This refers to the LIGO programming language. See the Writing Tezos contracts section for more info.

For this quick start, we're going to configure your project to deploy to the Carthagenet test network for Tezos. This is the quickest way to get started, though as you get familiar with Tezos, you'll want to set up a local development environment. See the example box documentation for an example on using a local flextesa sandbox.

First, navigate to https://faucet.tzalpha.net/ to get a faucet account. This will create a new account for you on the testnet and fill it with some testnet XTZ. Download the file and save it as faucet.json in the root of your project.

Next, replace the box's truffle-config.js with the following:

const { mnemonic, secret, password, email } = require("./faucet.json");

module.exports = {
  // see <http://truffleframework.com/docs/advanced/configuration>
  // for more details on how to specify configuration options!
  networks: {
    development: {
      host: "https://carthagenet.smartpy.io",
      port: 443,
      network_id: "*",
      type: "tezos"

That's it! You're all set to run the box's deployment scripts against a testnet.

Note: The default tezos box is configured to deploy to multiple networks, including mainnet. If you'd like to deploy to those networks, you'll need to first configure the `secret`, `mnemonic`, `password`, and `email` like the above to represent an account you own that's funded with XTZ. See the Configuring Tezos Projects section for more info.

Caution! Keep your `secret`, `mnemonic` and `password` safe! When not on a testnet, you can quickly lose all your tez if someone else gets ahold of them.

The example box comes default with pre-written deployment scripts, found within the ./migrations directory:

  • 1_initial_migration.js
  • 2_deploy_simple_storage.js
  • 3_deploy_counter.js

Truffle will handle running these scripts when you run the following command:

$ truffle migrate

See the Deploying Tezos contracts section for more information on how to write and use Truffle's deployment scripts.

The box also comes equipped with tests, showing you how to write automated tests for your Tezos contracts. You can find these tests in the ./test directory:

  • counter.test.js
  • simpleStorage.test.js

See the Testing Tezos contracts section for more information on how to write tests for your LIGO congrats.

Running your tests is easy, by running following command:

$ truffle test

If you've reached this point, you now have a Truffle project that lets you compile, test, and deploy LIGO contracts to the Carthage Tezos test network. Congrats! This is a great start, but there's still much to learn. We suggest you check out the following resources to learn more about Tezos, LIGO, and Truffle: