Debugging OpenZeppelin SDK contracts with truffle debug

Truffle debug can be used to debug OpenZeppelin SDK contracts.

The following guide will walk through creating a project with Truffle and OpenZeppelin SDK and debugging a local testnet transaction.


Setup a project with both Truffle and OpenZeppelin SDK.
OpenZeppelin SDK will use truffle-config.js.

mkdir debugtest && cd debugtest
npm init -y
npm install truffle @openzeppelin/cli
npx truffle init
npx openzeppelin init


Add the Counter.sol contract using your favorite editor

pragma solidity ^0.5.0;

contract Counter {
  uint256 public value;

  function increase() public {

  function decrease() public {
    require(value > 0);


Uncomment the development network.

    development: {
     host: "",     // Localhost (default: none)
     port: 8545,            // Standard Ethereum port (default: none)
     network_id: "*",       // Any network (default: none)


Use ganache-cli as your local testnet

ganache-cli -d

Create the contract

Create the contract on your local testnet using openzeppelin create and interactive commands.

$ npx openzeppelin create
✓ Compiling contracts with Truffle, using settings from truffle.js file
Truffle output:

Compiling your contracts...
> Compiling ./contracts/Counter.sol
> Compiling ./contracts/Migrations.sol
> Artifacts written to build/contracts
> Compiled successfully using:
   - solc: 0.5.8+commit.23d335f2.Emscripten.clang

? Pick a contract to instantiate Counter
? Pick a network development
✓ Contract Counter deployed
All contracts have been deployed
? Do you want to call a function on the instance after creating it? No
✓ Setting everything up to create contract instances
✓ Instance created at 0xCfEB869F69431e42cdB54A4F4f105C19C080A601

Interact with the contract

Call the decrease function which will revert.

$ npx oz send-tx
? Pick a network development
? Pick an instance Counter at 0xCfEB869F69431e42cdB54A4F4f105C19C080A601
? Select which function decrease()
✖ Calling: 'decrease' with no arguments
Error while trying to send transaction to 0xCfEB869F69431e42cdB54A4F4f105C19C080A601. Error: Returned error: VM Exception while processing transaction: revert

Debug the transaction

Get the transaction hash in ganache-cli

  Transaction: 0xe8ae7851489d3136a3b819112630ab53fc29a51f946b1bdf807c841727497256
  Gas usage: 23210
  Block Number: 5
  Block Time: Tue Sep 03 2019 17:44:58 GMT+1000 (Australian Eastern Standard Time)
  Runtime Error: revert

Call truffle debug with the transaction hash and then step next (to step to the Counter contract) then step next again to get to the require

$ npx truffle debug 0xe8ae7851489d3136a3b819112630ab53fc29a51f946b1bdf807c841727497256
Starting Truffle Debugger...
✔ Compiling your contracts...
✔ Gathering information about your project and the transaction...

Addresses called: (not created)
 0xe78A0F7E598Cc8b0Bb87894B0F60dD2a88d6a8Ab - Counter

Warning: The source code for one or more contracts could not be found.

(enter) last command entered (step next)
(o) step over, (i) step into, (u) step out, (n) step next
(;) step instruction (include number to step multiple), (p) print instruction
(h) print this help, (q) quit, (r) reset
(t) load new transaction, (T) unload transaction
(b) add breakpoint, (B) remove breakpoint, (c) continue until breakpoint
(+) add watch expression (`+:<expr>`), (-) remove watch expression (-:<expr>)
(?) list existing watch expressions and breakpoints
(v) print variables and values, (:) evaluate expression - see `v`


1: // No source code found.

debug(development:0xe8ae7851...)> n


 8:   }
10:   function decrease() public {

debug(development:0xe8ae7851...)> n

10:   function decrease() public {
11:     require(value > 0);

Thanks @sht for finding this: Truffle debug