{"id":1265,"date":"2026-01-14T17:20:41","date_gmt":"2026-01-14T15:20:41","guid":{"rendered":"https:\/\/ackee.xyz\/blog\/?p=1265"},"modified":"2026-01-14T17:20:41","modified_gmt":"2026-01-14T15:20:41","slug":"wake-debugging-guide","status":"publish","type":"post","link":"https:\/\/ackee.xyz\/blog\/wake-debugging-guide\/","title":{"rendered":"Wake Debugging Guide"},"content":{"rendered":"

When a fuzz run fails or contract behavior surprises you, effective debugging turns hours of frustration into minutes of focused investigation. Wake gives you Python’s full debugging ecosystem combined with Solidity-specific visibility tools. This guide shows you the techniques Ackee’s audit team uses to isolate issues fast.<\/p>\n

Visibility Into Contract State<\/h2>\n

The first step in debugging any failing test is understanding what your contracts are actually doing. Wake provides several approaches to expose internal state.<\/p>\n

Console Logging in Solidity<\/h3>\n

Wake includes a console logging library that works directly in your Solidity code:<\/p>\n

import "wake\/console.sol";<\/code><\/pre>\n
You can log values inline during contract execution with console.log()<\/code>, console.logBytes32()<\/code>, and console.logBytes()<\/code>. The library includes variants for dynamic-length data. This gives you printf-style debugging without deploying to a live network or setting up complex tooling.<\/p>\n
When you need readable call traces, use account.label<\/code> to replace raw addresses with meaningful names. Instead of seeing 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb<\/code> in traces, you’ll see “TokenContract” or “UserWallet.”<\/p>\n
For pure functions, you’ll need a workaround since they can’t emit logs during normal execution. The quick fix is temporarily marking the function and any dependent pure functions as view<\/code>. If that’s not feasible, emit a custom event instead.<\/p>\n
Manually Guided Fuzzing (MGF) Techniques<\/h2>\n
Wake’s Python-based fuzzing gives you control that coverage-guided approaches can’t match. The key is maintaining accurate Python state that mirrors your contract state.<\/p>\n
Invariant Functions<\/h3>\n
Write more invariant functions than flow functions. Invariants verify your Python state stays synchronized with on-chain reality, which becomes essential when debugging complex failures. When a test fails, you can trust your Python state to understand what went wrong.<\/p>\n
Find the Flow That Caused a Failure<\/h3>\n
To identify which flow caused a failure, add logging at the start of each flow:<\/p>\n
def pre_flow(self, flow: Callable):\n    logger.info(f"[FLOW] {flow.__name__}")<\/code><\/pre>\n
This creates a breadcrumb trail showing exactly which sequence of operations led to the failure.<\/p>\n
Interactive Debugging with ipdb<\/h2>\n
Wake integrates seamlessly with Python’s debugger. When you need to inspect state mid-execution or step through transaction sequences, drop into ipdb.<\/p>\n
Transaction Debugging<\/a><\/h3>\n
To examine recent transactions, use chain.txs[-1].call_trace<\/code> for the most recent transaction or chain.txs[-2].call_trace<\/code> for the one before. This gives you complete visibility into what happened on-chain.<\/p>\n
> chain.txs[-1].call_trace\n> chain.txs[-2].call_trace<\/code><\/pre>\n
Systematic Debugging Setup<\/h3>\n
For systematic debugging, set up handlers that automatically print traces when problems occur:<\/p>\n
def revert_handler(e: RevertError):\n    if e.tx is not None:\n        print(e.tx.call_trace)\n\ndef tx_callback_fn(tx: TransactionAbc) -> None:\n    print(tx.call_trace)\n    # so no print(tx.call_trace) everywhere, only for debug because too slow\n\n@chain.connect()\n@on_revert(revert_handler)\ndef test_fuzz_stethpool():\n    chain.tx_callback = tx_callback_fn\n    FuzzVWStEth().run(1, 100000)<\/code><\/pre>\n
Note that printing traces for every transaction slows execution significantly, so enable tx_callback<\/code> only when actively debugging.<\/p>\n
Reproducing with Random Seeds<\/h3>\n
When you’ve found a failure, reproduce it with the exact random seed:<\/p>\n
wake test tests\/test_counter_fuzz.py -S62061e838798ad0f -d -v<\/code><\/pre>\n
The -d<\/code> flag drops you into the debugger, -v<\/code> increases verbosity, and the seed ensures you hit the same sequence every time.<\/p>\n
Shrinking Failed Sequences<\/h2>\n
Once you’ve found a failing sequence, shrinking isolates the minimal flow combination that triggers the bug. This confirms whether the issue appears earlier in the sequence or requires the full setup.<\/p>\n
Run shrinking with wake test tests\/test_something.py -SH<\/code> to shrink to a human-readable sequence or -SR<\/code> for a compact representation. The smaller sequence often reveals the core issue more clearly than the full failure.<\/p>\n
wake test tests\/test_something.py -SH\nwake test tests\/test_something.py -SR<\/code><\/pre>\n
More Tips<\/h2>\n
Handling Expected Reverts<\/a><\/h3>\n
When testing edge cases, you’ll often want to verify that operations revert under specific conditions. Wake’s may_revert<\/code> context manager lets you assert both successful execution and expected failures:<\/p>\n
with may_revert() as e:\n    tx = contract.operation()\n\nif condition_that_causes_revert:\n    assert e.value == Contract.ExpectedError()\n    return "expected_revert_reason"\n\nassert e.value is None  # Must succeed otherwise<\/code><\/pre>\n
This pattern makes tests self-documenting – it’s immediately clear which paths should revert and which should succeed.<\/p>\n
Performance Analysis<\/a><\/h3>\n
When tests run slowly, profile them to find bottlenecks:<\/p>\n
wake --profile test tests\/test_fuzz.py<\/code><\/pre>\n
This generates a profile file that you can visualize with:<\/p>\n
gprof2dot -f pstats .wake\/wake.prof | dot -Tsvg -o wake.prof.svg<\/code><\/pre>\n
The resulting SVG shows exactly where execution time goes, making optimization targets obvious.<\/p>\n
Fuzzing Coverage<\/a><\/h3>\n
For understanding test coverage, run:<\/p>\n
wake test tests\/test_fuzz.py --coverage<\/code><\/pre>\n
This generates coverage.cov<\/code> in your project root. Open VS Code’s command palette and select “Wake: Show Coverage” to visualize which contract code your tests exercised.<\/p>\n
Token Testing Patterns<\/a><\/h3>\n
Testing DeFi protocols requires minting tokens and managing approvals. Wake makes this straightforward:<\/p>\n
# Mint directly to your test user\nmint_erc20(token, user, 100 * 10**18)\ntoken.approve(contract, 100 * 10**18, from_=user)\ncontract.pullToken(from_=user)<\/code><\/pre>\n
Cross-Chain Testing<\/a><\/h3>\n
For cross-chain scenarios, Wake lets you run multiple independent chains simultaneously:<\/p>\n
from wake.testing import Chain\n\n# Create two separate blockchain instances\nethereum_chain = Chain()\npolygon_chain = Chain()\n\n@ethereum_chain.connect()\n@polygon_chain.connect()\ndef test_cross_chain_transfer():\n    # Both chains are now connected and ready\n    pass<\/code><\/pre>\n
Making Debugging Faster<\/h2>\n
Start with clear invariants that verify your assumptions about contract state. Keep call traces easily accessible through handlers and callbacks. When tests fail, shrink them to minimal reproducers before diving deep. These patterns make the difference between spending hours hunting bugs and isolating them in minutes.<\/p>\n
The techniques here leverage Python’s mature debugging ecosystem while giving you direct access to EVM internals. Wake combines the expressiveness of Python with the precision needed for smart contract security. That’s the foundation for both fast development and thorough testing.<\/p>\n","protected":false},"excerpt":{"rendered":"
When a fuzz run fails or contract behavior surprises you, effective debugging turns hours of frustration into minutes of focused investigation. Wake gives you Python’s full debugging ecosystem combined with Solidity-specific visibility tools. This guide shows you the techniques Ackee’s audit team uses to isolate issues fast. Visibility Into Contract State The first step in debugging any failing test is understanding what…<\/p>\n","protected":false},"author":24,"featured_media":852,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[61,10,80,63,1,103],"tags":[],"class_list":["post-1265","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-education","category-ethereum","category-solidity","category-tutorial","category-uncategorized","category-wake"],"aioseo_notices":[],"featured_image_src":"https:\/\/ackee.xyz\/blog\/wp-content\/uploads\/2024\/06\/Read-Only-Reentrancy-Attack-600x400.png","featured_image_src_square":"https:\/\/ackee.xyz\/blog\/wp-content\/uploads\/2024\/06\/Read-Only-Reentrancy-Attack-600x600.png","author_info":{"display_name":"Naoki Yoshida","author_link":"https:\/\/ackee.xyz\/blog\/author\/naoki-yoshida\/"},"_links":{"self":[{"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/posts\/1265","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/users\/24"}],"replies":[{"embeddable":true,"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/comments?post=1265"}],"version-history":[{"count":0,"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/posts\/1265\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/media\/852"}],"wp:attachment":[{"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/media?parent=1265"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/categories?post=1265"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/ackee.xyz\/blog\/wp-json\/wp\/v2\/tags?post=1265"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}