Inspecting and Debugging Transactions

The TransactionReceipt object provides information about a transaction, as well as various methods to aid in debugging.

>>> tx = Token[0].transfer(accounts[1], 1e18, {'from': accounts[0]})

Transaction sent: 0xa7616a96ef571f1791586f570017b37f4db9decb1a5f7888299a035653e8b44b
Token.transfer confirmed - block: 2   gas used: 51019 (33.78%)

>>> tx
<Transaction object '0xa7616a96ef571f1791586f570017b37f4db9decb1a5f7888299a035653e8b44b'>

To view human-readable information on a transaction, call the TransactionReceipt.info method.

>>> tx.info()

Transaction was Mined
---------------------
Tx Hash: 0xa7616a96ef571f1791586f570017b37f4db9decb1a5f7888299a035653e8b44b
From: 0x4FE357AdBdB4C6C37164C54640851D6bff9296C8
To: 0xDd18d6475A7C71Ee33CEBE730a905DbBd89945a1
Value: 0
Function: Token.transfer
Block: 2
Gas Used: 51019 / 151019 (33.8%)

Events In This Transaction
--------------------------
Transfer
    from: 0x4fe357adbdb4c6c37164c54640851d6bff9296c8
    to: 0xfae9bc8a468ee0d8c84ec00c8345377710e0f0bb
    value: 1000000000000000000

Event Data

Data about events is available as TransactionReceipt.events. It is stored in an EventDict object; a hybrid container with both dict-like and list-like properties.

Hint

You can also view events that were emitted in a reverted transaction. When debugging it can be useful to create temporary events to examine local variables during the execution of a failed transaction.

>>> tx.events
{
    'CountryModified': [
        {
            'country': 1,
            'limits': (0, 0, 0, 0, 0, 0, 0, 0),
            'minrating': 1,
            'permitted': True
        },
        {
            'country': 2,
            'limits': (0, 0, 0, 0, 0, 0, 0, 0),
            'minrating': 1,
            'permitted': True
        }
    ],
    'MultiSigCallApproved': [
        {
            'callHash': "0x0013ae2e37373648c5161d81ca78d84e599f6207ad689693d6e5938c3ae4031d",
            'callSignature': "0xa513efa4",
            'caller': "0xF9c1fd2f0452FA1c60B15f29cA3250DfcB1081b9",
            'id': "0x8be1198d7f1848ebeddb3f807146ce7d26e63d3b6715f27697428ddb52db9b63"
        }
    ]
}

Use it as a dictionary for looking at specific events when the sequence they are fired in does not matter:

>>> len(tx.events)
3
>>> len(tx.events['CountryModified'])
2
>>> 'MultiSigCallApproved' in tx.events
True
>>> tx.events['MultiSigCallApproved']
{
    'callHash': "0x0013ae2e37373648c5161d81ca78d84e599f6207ad689693d6e5938c3ae4031d",
    'callSignature': "0xa513efa4",
    'caller': "0xF9c1fd2f0452FA1c60B15f29cA3250DfcB1081b9",
    'id': "0x8be1198d7f1848ebeddb3f807146ce7d26e63d3b6715f27697428ddb52db9b63"
}

Or as a list when the sequence is important, or more than one event of the same type was fired:

# name of the address
>>> tx.events[1].name
'CountryModified'

# address where the event fired
>>> tx.events[1].address
"0xDd18d6475A7C71Ee33CEBE730a905DbBd89945a1"

>>> tx.events[1]
{
    'country': 1,
    'limits': (0, 0, 0, 0, 0, 0, 0, 0),
    'minrating': 1,
    'permitted': True
}

Internal Transactions and Deployments

TransactionReceipt.internal_transfers provides a list of internal ether transfers that occurred during the transaction.

>>> tx.internal_transfers
[
    {
        "from": "0x79447c97b6543F6eFBC91613C655977806CB18b0",
        "to": "0x21b42413bA931038f35e7A5224FaDb065d297Ba3",
        "value": 100
    }
]

TransactionReceipt.new_contracts provides a list of addresses for any new contracts that were created during a transaction. This is useful when you are using a factory pattern.

>>> deployer
<Deployer Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>

>>> tx = deployer.deployNewContract()
Transaction sent: 0x6c3183e41670101c4ab5d732bfe385844815f67ae26d251c3bd175a28604da92
  Gas price: 0.0 gwei   Gas limit: 79781
  Deployer.deployNewContract confirmed - Block: 4   Gas used: 79489 (99.63%)

>>> tx.new_contracts
["0x1262567B3e2e03f918875370636dE250f01C528c"]

To generate Contract objects from this list, use ContractContainer.at:

>>> tx.new_contracts
["0x1262567B3e2e03f918875370636dE250f01C528c"]
>>> Token.at(tx.new_contracts[0])
<Token Contract object '0x1262567B3e2e03f918875370636dE250f01C528c'>

Debugging Failed Transactions

Note

Debugging functionality relies on the debug_traceTransaction RPC method. If you are using Infura this endpoint is unavailable. Attempts to access this functionality will raise an RPCRequestError.

When a transaction reverts in the console you are still returned a TransactionReceipt, but it will show as reverted. If an error string is given, it will be displayed in brackets and highlighted in red.

>>> tx = Token[0].transfer(accounts[1], 1e18, {'from': accounts[3]})

Transaction sent: 0x5ff198f3a52250856f24792889b5251c120a9ecfb8d224549cb97c465c04262a
Token.transfer confirmed (Insufficient Balance) - block: 2   gas used: 23858 (19.26%)
<Transaction object '0x5ff198f3a52250856f24792889b5251c120a9ecfb8d224549cb97c465c04262a'>

The error string is also available as TransactionReceipt.revert_msg.

>>> tx.revert_msg
'Insufficient Balance'

You can also call TransactionReceipt.traceback to view a python-like traceback for the failing transaction. It shows source highlights at each jump leading up to the revert.

>>> tx.traceback()
Traceback for '0xd31c1c8db46a5bf2d3be822778c767e1b12e0257152fcc14dcf7e4a942793cb4':
Trace step 169, program counter 3659:
    File "contracts/SecurityToken.sol", line 156, in SecurityToken.transfer:
    _transfer(msg.sender, [msg.sender, _to], _value);
Trace step 5070, program counter 5666:
    File "contracts/SecurityToken.sol", lines 230-234, in SecurityToken._transfer:
    _addr = _checkTransfer(
        _authID,
        _id,
        _addr
    );
Trace step 5197, program counter 9719:
    File "contracts/SecurityToken.sol", line 136, in SecurityToken._checkTransfer:
    require(balances[_addr[SENDER]] >= _value, "Insufficient Balance");

Inspecting the Trace

The Trace Object

The best way to understand exactly happened in a transaction is to generate and examine a transaction trace. This is available as a list of dictionaries at TransactionReceipt.trace, with several fields added to make it easier to understand.

Each step in the trace includes the following data:

{
    'address': "",  // address of the contract containing this opcode
    'contractName': "",  // contract name
    'depth': 0,  // the number of external jumps away the initially called contract (starts at 0)
    'error': "",  // occurred error
    'fn': "",  // function name
    'gas': 0,  // remaining gas
    'gasCost': 0,  // cost to execute this opcode
    'jumpDepth': 1,  // number of internal jumps within the active contract (starts at 1)
    'memory': [],  // execution memory
    'op': "",  // opcode
    'pc': 0,  // program counter
    'source': {
        'filename': "path/to/file.sol",  // path to contract source
        'offset': [0, 0]  // start:stop offset associated with this opcode
    },
    'stack': [],  // execution stack
    'storage': {}  // contract storage
}

Call Traces

When dealing with complex transactions the trace can be may thousands of steps long - it can be challenging to know where to begin examining it. Brownie provides the TransactionReceipt.call_trace method to view a complete map of every jump that occured in the transaction:

>>> tx.call_trace()
Call trace for '0x7824c6032966ca2349d6a14ec3174d48d546d0fb3020a71b08e50c7b31c1bcb1':
Initial call cost  [21228 gas]
LiquidityGauge.deposit  0:3103  [64010 / 128030 gas]
├── LiquidityGauge._checkpoint  83:1826  [-6420 / 7698 gas]
│   ├── GaugeController.get_period_timestamp  [STATICCALL]  119:384  [2511 gas]
│   ├── ERC20CRV.start_epoch_time_write  [CALL]  411:499  [1832 gas]
│   ├── GaugeController.gauge_relative_weight_write  [CALL]  529:1017  [3178 / 7190 gas]
│   │   └── GaugeController.change_epoch  697:953  [2180 / 4012 gas]
│   │       └── ERC20CRV.start_epoch_time_write  [CALL]  718:806  [1832 gas]
│   └── GaugeController.period  [STATICCALL]  1043:1336  [2585 gas]
├── LiquidityGauge._update_liquidity_limit  1929:2950  [45242 / 54376 gas]
│   ├── VotingEscrow.balanceOf  [STATICCALL]  1957:2154  [2268 gas]
│   └── VotingEscrow.totalSupply  [STATICCALL]  2180:2768  [6029 / 6866 gas]
│       └── VotingEscrow.supply_at  2493:2748  [837 gas]
└── ERC20LP.transferFrom  [CALL]  2985:3098  [1946 gas]

Each line shows the following information:

ContractName.functionName (external call opcode) start:stop [internal / total gas used]

Where start and stop are the indexes of TransactionReceipt.trace where the function was entered and exited. TransactionReceipt.call_trace provides an initial high level overview of the transaction execution path, which helps you to examine the individual trace steps in a more targetted manner and determine where things went wrong in a complex transaction.

Functions that terminated with REVERT or INVALID opcodes are highlighted in red.

For functions with no subcalls, the used gas is shown. Otherwise, the first gas number is the amount of gas used internally by this function and the second number is the total gas used by the function including all sub-calls. Gas refunds from deleting storage or contracts are shown as negative gas used. Note that overwriting an existing zero-value with another zero-value will incorrectly display a gas refund.

Calling TransactionReceipt.call_trace with True as an argument provides an expanded view:

>>> history[-1].call_trace(True)

Call trace for '0x7824c6032966ca2349d6a14ec3174d48d546d0fb3020a71b08e50c7b31c1bcb1':
Initial call cost  [21228 gas]
LiquidityGauge.deposit  0:3103  [64010 / 128030 gas]
├── LiquidityGauge._checkpoint  83:1826  [-6420 / 7698 gas]
│   │
│   ├── GaugeController.get_period_timestamp  [STATICCALL]  119:384  [2511 gas]
│   │       ├── address: 0x0C41Fc429cC21BC3c826efB3963929AEdf1DBb8e
│   │       ├── input arguments:
│   │       │   └── p: 0
│   │       └── return value: 1594574319
...

The expanded trace includes information about external subcalls, including:

  • the target address
  • the amount of ether transferred
  • input arguments
  • return values

For calls that revert, the revert reason is given in place of the return value:

>>> history[-1].call_trace(True)
...
└── ERC20LP.transferFrom  [CALL]  2985:3098  [1946 gas]
        ├── address: 0xd495633B90a237de510B4375c442C0469D3C161C
        ├── value: 0
        ├── input arguments:
        │   ├── _from: 0x9EC9431CCCCD2C73F0A2F68DC69A4A527AB5D809
        │   ├── _to: 0x5AE569698C5F986665018B6E1D92A71BE71DEF9A
        │   └── _value: 100000
        └── revert reason: Integer underflow

You can also access this information programmatically via the TransactionReceipt.subcalls attribute:

>>> history[-1].subcalls
[
    {
        'from': "0x5AE569698C5F986665018B6e1d92A71be71DEF9a",
        'function': "get_period_timestamp(int128)",
        'inputs': {
            'p': 0
        },
        'op': "STATICCALL",
        'return_value': (1594574319,),
        'to': "0x0C41Fc429cC21BC3c826efB3963929AEdf1DBb8e"
    },
...