Configuration

Configuration file

While Waffle works well enough without any configurations, advanced users might want to excert more control over what happens when they use Waffle in their projects.

This is why we made it very easy to configure Waffle to meet your needs. All you need to do is create a waffle.json file inside your project and point waffle to it.

First create your waffle.json configuration file:

{
  "compilerType": "solcjs",
  "compilerVersion": "0.6.2",
  "sourceDirectory": "./src",
  "outputDirectory": "./build"
}

Note

Each configuration is optional.

Afterwards update your package.json build script:

Note

Since Waffle 3.0.0 it recognises waffle.json as the default configuration file. If your configuration file is called waffle.json, it’s possible to use just waffle to build contracts.

{
  "scripts": {
    "build": "waffle"
  }
}
{
“scripts”: {

“build”: “waffle waffle.json”

}

}

Configuration options:

sourceDirectory

You can specify a custom path to the directory containing your smart contracts. Waffle uses ./contracts as the default value for sourceDirectory. The path you provide will be resolved relative to the current working directory.

Example:

{
  "sourceDirectory": "./custom/path/to/contracts"
}

outputDirectory

You can specify a custom path to the directory to which Waffle saves the compilation output. Waffle uses ./build as the default value for outputDirectory. The path you provide will be resolved relative to the current working directory.

Example:

{
  "outputDirectory": "./custom/path/to/output"
}

nodeModulesDirectory

You can specify a custom path to the node_modules folder which Waffle will use to resolve third party dependencies. Waffle uses ./node_modules as the default value for nodeModulesDirectory. The path you provide will be resolved relative to the current working directory.

For more information about third party libraries, see Using third party libraries.

Example:

{
  "nodeModulesDirectory": "./custom/path/to/node_modules"
}

cacheDirectory

When compiling using solcjs and using a non-default compilerVersion Waffle downloads the necessary solcjs binary from a remote server. This file is cached to speed up subsequent runs. You can specify a custom path to the directory in which caches are saved. Waffle uses ./cache as the default value for cacheDirectory. The path you provide will be resolved relative to the current working directory.

Example:

{
  "cacheDirectory": "./custom/path/to/cache"
}

compilerType

Specifies the compiler to use. For more information see: Reducing compile times. Allowed values:

  • solcjs

  • native

  • dockerized-solc

  • dockerized-vyper

Waffle uses solcjs as the default value for compilerType.

Example:

{
  "compilerType": "dockerized-solc"
}

compilerVersion

Specifies the version of the compiler. Should be a semver string like 0.5.9. You can use it with "compilerType": "solcjs" or "compilerType": "dockerized-solc".

When using "compilerType": "solcjs" you can also specify the exact commit that will be used or a path to a specific solc module dependency.

To find a specific commit please consult the list of available solc versions.

Examples:

{
  "compilerType": "dockerized-solc",
  "compilerVersion": "0.4.24"
}
{
  "compilerType": "solcjs",
  "compilerVersion": "v0.4.24+commit.e67f0147"
}
{
  "compilerType": "solcjs",
  "compilerVersion": "./node_modules/solc"
}

compilerAllowedPaths

The solc compiler has restrictions on paths it can access for security reasons. The value of compilerAllowedPaths will be passed as a command line argument: solc --allow-paths <VALUE>.

This is especially useful if you are doing a monorepo setup with Lerna, see: Usage with Lernajs.

Example:

{
  "compilerAllowedPaths": ["../contracts"]
}

compilerOptions

You can customize the behaviour of solc by providing custom settings for it. All of the information is provided in the Solidity documentation. Value of the compilerOptions configuration setting will be passed to solc as settings.

For detailed list of options go to solidity documentation (sections: ‘Setting the EVM version to target’, ‘Target options’ and ‘Compiler Input and Output JSON Description’).

Example:

{
  "compilerOptions": {
    "evmVersion": "constantinople"
  }
}

outputType

See: KLAB compatibility.

outputHumanReadableAbi

Waffle supports Human Readable Abi.

In order to enable its output, you need to set outputHumanReadableAbi to true in your config file:

{
  "outputHumanReadableAbi": true
}

For the compiled contracts you will now see the following in the output:

{
  "humanReadableAbi": [
    "constructor(uint256 argOne)",
    "event Bar(bool argOne, uint256 indexed argTwo)",
    "event FooEvent()",
    "function noArgs() view returns(uint200)",
    "function oneArg(bool argOne)",
    "function threeArgs(string argOne, bool argTwo, uint256[] argThree) view returns(bool, uint256)",
    "function twoReturns(bool argOne) view returns(bool, uint256)"
  ]
}

Other configuration file formats

Waffle supports the following configuration file formats:

JSON:

{
  "sourceDirectory": "./src/contracts",
}

JavaScript:

module.exports = {
  sourceDirectory: './src/contracts'
}

The configuration can even be a promise

module.exports = Promise.resolve({
  sourceDirectory: './src/contracts'
})

Hint

This is a powerful feature if you want to asynchronously load different compliation configurations in different environments. For example, you can use native solc in CI for faster compilation, while deciding the exact solc-js version locally based on the contract versions being used. Since many of those operations are asynchronous, you’ll most likely be returning a Promise to waffle to handle.

Setting Solidity compiler version

See compilerVersion.

Usage with Truffle

Waffle output should be compatible with Truffle by default.

Custom compiler options

See compilerOptions.

KLAB compatibility

The default compilation process is not compatible with KLAB (a formal verification tool, see: https://github.com/dapphub/klab). To compile contracts to work with KLAB one must:

  1. Set appropriate compiler options, i.e.:

compilerOptions: {
  outputSelection: {
    "*": {
      "*": [ "evm.bytecode.object", "evm.deployedBytecode.object",
             "abi" ,
             "evm.bytecode.sourceMap", "evm.deployedBytecode.sourceMap" ],

      "": [ "ast" ]
    },
  }
}

2. Set appropriate output type. We support two types: one (default) generates a single file for each contract and the other (KLAB friendly) generates one file (Combined-Json.json) combining all contracts. The latter type does not meet (in contrary to the first one) all official solidity standards since KLAB requirements are slightly modified. Set the output in the config file:

Possible options are:

  • ‘multiple’: a single file for each contract;

  • ‘combined’: one KLAB friendly file;

  • ‘all’: generates both above outputs;

  • ‘minimal’: a single file for each contract with minimal information (just abi and bytecode).

Note

‘minimal’ option was introduced in Waffle 3.0.0.

{
  "outputType": "combined"
}

An example of full KLAB friendly config file:

module.exports = {
  compilerType: process.env.WAFFLE_COMPILER,
  outputType: 'all',
  compilerOptions: {
    outputSelection: {
      "*": {
        "*": [ "evm.bytecode.object", "evm.deployedBytecode.object",
               "abi" ,
               "evm.bytecode.sourceMap", "evm.deployedBytecode.sourceMap" ],

        "": [ "ast" ]
      },
   }
 }
};

Monorepo

Waffle works well with mono-repositories. It is enough to set up a common nodeModulesDirectory in the configuration file to make it work. We recommend using yarn workspaces and wsrun for monorepo management.

Usage with Lernajs

Waffle works with lerna, but requires additional configuration. When lerna cross-links npm packages in monorepo, it creates symbolic links to the original catalog. They lead to sources files located beyond allowed paths. This process breaks compilation with native solc.

If you see the following message in your monorepo setup:

contracts/Contract.sol:4:1: ParserError: Source ".../monorepo/node_modules/YourProjectContracts/contracts/Contract.sol" not found: File outside of allowed directories.
import "YourProjectContracts/contracts/Contract.sol";

you probably need to add allowedPath to your waffle configuration.

Assuming you have the following setup:

/monorepo
  /YourProjectContracts
    /contracts
  /YourProjectDapp
    /contracts

Add to waffle configuration in YourProjectDapp:

{
  "compilerAllowedPaths": ["../YourProjectContracts"]
}

That should solve a problem.

Currently Waffle does not support a similar feature for dockerized solc.