Skip to content

Developing with Truffle


Truffle is the suggested framework for developing and testing smart contracts on Oasis. Here we'll cover the basics of how to create a new project with Truffle, how to develop confidential smart contracts, and how to migrate an existing Truffle projects to Oasis.


This guide assumes you are running the Oasis Contract Kit. See the instructions for installing and launching Contract Kit.


The commands in this guide should all be run inside the Contract Kit environment.

Creating a new project

To create new an empty project:

$ truffle unbox oasislabs/oasis-box

This will set up all the boilerplate needed to develop on Oasis. Along with initializing your Truffle project, it installs the required npm packages and modifies your truffle-config.js so that you have everything needed to start your project.

It's suggested to start new Truffle projects using this command (not truffle init) to ensure compatibility with the Oasis Devnet.

Configuring your project

Before you can deploy your contracts to Oasis Devnet you need to tell Truffle how to access your wallet. Modify the truffle-config.js file to add your account's mnemonic:

// add your Oasis Devnet mnemonic here. Be sure to keep it secret!
const MNEMONIC = '';

Consult your wallet software to identify the mnemonic used to generate your key. The mnemonic is sometimes referred to as the “seed phrase” and is typically a series of 12 words (in MetaMask you were asked to save this phrase when generating your wallet).


Keep this phrase secret! Someone who knows this phrase can access your wallet and all your funds. For this reason, do not use the same phrase here that you use for other networks.

Lastly, ensure the address associated with your mnemonic has tokens. You can visit the Oasis dashboard to auto-fund your wallet.

Developing with Truffle

With these changes, you have everything you need to start developing on Oasis with Truffle.

To create new contracts:

$ truffle create contract MySolidityContract

$ truffle create rust-contract MyRustContract

To compile contracts:

$ truffle compile

To deploy and test both confidential and non-confidential smart contracts against the Oasis Devnet:

$ truffle migrate --network oasis
$ truffle test --network oasis

To deploy and test regular (non-confidential) smart contracts against the local blockchain:

$ truffle migrate --network development
$ truffle test --network development

See the Contract Kit docs for instructions on launching the local chain.

Confidential Smart Contracts

Truffle will accept a configuration at deploy time for how the contract should be managed by the Oasis runtime. Just specify an Oasis deploy configuation to the deployer to set whether the contract should be deployed as a confidential smart contract. For a complete list of settings, see Contract Settings.

For example, you can add a migration script with the following to deploy a confidential smart contract that expires in 24 hours:

// 2_counter_migration.js
const Counter = artifacts.require("Counter");
module.exports = function(deployer) {
  deployer.deploy(Counter, args, {
    oasis: {
        confidential: true,
        expiry: Math.floor( + 24*60*60, // expire in 24 hours

Since each contract is deployed independently, you can mix confidential and non-confidential contracts in your project.

Migrating an existing Truffle project


This section is only relevant if you want to manually migrate an existing Truffle project to Oasis. For new projects we strongly recommend using the workflow described above.

Existing DApps developed with Truffle can be easily migrated to Oasis.

If you haven't already, install the following packages:

$ npm install --save-dev truffle-hdwallet-provider@1.0.0-web3one.0
$ npm install --save-dev oasis-compile
$ npm install --save web3c

Next, ensure your Truffle config (truffle-config.js) has the following settings (from the Oasis Truffle box):

const HDWalletProvider = require("truffle-hdwallet-provider");

// add your Oasis Devnet mnemonic here. Be sure to keep it secret!
const MNEMONIC = '';

// mnemonic for Contract Kit local blockchain
const CONTRACT_KIT_MNEMONIC = 'range drive remove bleak mule satisfy mandate east lion minimum unfold ready';

module.exports = {
  networks: {
    // Oasis Devnet
    oasis: {
      provider: function () {
        return new HDWalletProvider(MNEMONIC, "");
      network_id: "42261"

    // Contract Kit local chain
    development: {
      provider: function () {
        return new HDWalletProvider(CONTRACT_KIT_MNEMONIC, "http://localhost:8545", 0, 10);
      network_id: "*"
  compilers: {
    external: {
      command: "./node_modules/.bin/oasis-compile",
      targets: [{
        path: "./.oasis-build/*.json"

Be sure to add your mnemonic to this file as described in the Configuring your project section above.

You can now deploy your contract as usual. The oasis network will deploy to the Oasis Devnet. The development network is preconfigured to work with the local blockchain from the Contract Kit. For more information on how to use the local chain, see the Contract Kit docs.