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 match 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:

{}

Note

All of the configuration options are optional.

Afterwards update your package.json build script:

{
  "scripts": {
    "build": "waffle .waffle.json"
  }
}

Next, you will learn about the configuration options:

sourcesPath

You can specify a custom path to the directory containing your smart contracts. Waffle uses ./contracts as the default value for ./sourcesPath.

Example:

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

targetPath

You can specify a custom path to the directory to which Waffle saves the compilation output. Waffle uses ./build as the default value for ./targetPath.

Example:

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

npmPath

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 ./npmPath.

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

Example:

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

compiler

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

  • solcjs (default)
  • native
  • dockerized-solc

Example:

{
  "compiler": "dockerized-solc"
}

docker-tag

Specifies the docker tag. Only use alongside "compiler": "dockerized-solc". For more information, see: Using dockerized solc.

Example:

{
  "compiler": "dockerized-solc",
  "docker-tag": "0.4.24"
}

solcVersion

solc-js allows setting the version of the solidity compiler on the fly. To change the version of the solidity compiler update the value of the solcVersion field in your config file:

{
  "solcVersion": "v0.4.24+commit.e67f0147"
}

To find an appropriate version name please consult the list of available solc versions.

Instead of specifying a version tag you can pass the path to the solc-js package.

{
  "solcVersion": "./node_modules/solc"
}

legacyOutput

Starting with Waffle 2.0, the format of contract output JSON files is the solidity standard JSON. This is not compatible with older Waffle versions and with Truffle.

You can generate files that are compatible with both current and previous versions by setting "legacyOutput": "true" in the configuration file:

{
  "legacyOutput": "true"
}

allowedPaths

The solc compiler has restrictions on paths it can access for security reasons. The value of allowedPaths 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:

{
  "allowedPaths": ["../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)"
  ]
}

ganacheOptions

Values specified here will be read by createMockProvider if passed the path to the config file.

Example:

{
  "ganacheOptions": {
    "gasLimit": 50,
    "gasPrice": 1
  }
}

Other configuration file formats

Waffle supports the following configuration file formats:

JSON:

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

JavaScript:

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

The configuration can even be a promise

module.exports = Promise.resolve({
  sourcesPath: './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, whereas 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 solcVersion.

Usage with Truffle

See legacyOutput.

Usage with old Waffle versions

See legacyOutput.

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 single file for each contract and second (KLAB friendly) generates one file (Combined-Json.json) combining all contracts. The second type does not meet (in contrary to the first one) all official solidity standards since KLAB requirements are slightly modified. To choice of the output is set in config file, i.e.:

outputType: 'combined'

Possible options are: - ‘multiple’: single file for each contract; - ‘combined’: one KLAB friendly file; - ‘all’: generates both above outputs.

An example of full KLAB friendly config file:

module.exports = {
  compiler: process.env.WAFFLE_COMPILER,
  legacyOutput: true,
  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 common npmPath 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 require additional configuration. When lerna cross-links npm packages in monorepo, it creates symbolic links to original catalog. That leads to sources files located beyond allowed paths. This process breaks compilation with native solc.

If you see a message like below 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:

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

That should solve a problem.

Currently Waffle does not support similar feature for dockerized solc.