git clone https:\/\/github.com\/Ackee-Blockchain\/2025-workshop-fuzzing\ncd 2025-workshop-fuzzing\nnpm install<\/code><\/pre>\nBefore continuing, check that Wake compiles your project successfully by running:<\/p>\n
wake up<\/code><\/pre>\nUnderstanding Wake Printers<\/h2>\n
Wake comes with several built-in printers that showcase different kinds of analysis. You can list them with:<\/p>\n
wake print<\/code><\/pre>\nRun a specific printer by name:<\/p>\n
wake print storage-layout<\/code><\/pre>\n![\"\"](\"https:\/\/abchprod.wpengine.com\/wp-content\/uploads\/2025\/11\/Screenshot-2025-11-04-at-18.32.53.png\")
storage layout output<\/figcaption><\/figure>\nBuilt-in printers demonstrate the system’s capabilities, but the real power comes from writing custom printers tailored to your security analysis needs. Once you understand how built-in printers work, you\u2019ll see how easy it is to extend Wake with your own analysis tools. By the end of this guide, you\u2019ll know how to create printers that detect vulnerability patterns relevant to your auditing approach.<\/p>\n
Tutorial 1: Creating Your First Printer – Listing Contracts<\/h2>\n
Let’s start with a simple printer that lists all contracts in your project. This example introduces the core concepts you’ll use in more complex analysis.<\/p>\n
Creating the Printer Structure<\/h3>\n
Run this command to scaffold your first printer::<\/p>\n
wake up printer list-contracts<\/code><\/pre>\n![\"\"](\"https:\/\/abchprod.wpengine.com\/wp-content\/uploads\/2025\/11\/Screenshot-2025-11-04-at-17.40.37.png\")
<\/p>\n
Wake generates a new printer directory and a starter file with this structure:<\/p>\n
\nprinters\/<\/code> directory for all custom printers<\/li>\nlist-contracts.py<\/code> with the basic printer structure<\/li>\n<\/ul>\nUnderstanding the Template<\/h3>\n
The generated template provides this starting structure:<\/p>\n
from __future__ import annotations\n\nimport networkx as nx\nimport rich_click as click\nimport wake.ir as ir\nimport wake.ir.types as types\nfrom rich import print\nfrom wake.cli import SolidityName\nfrom wake.printers import Printer, printer\n\n\nclass ListContractsPrinter(Printer):\n def print(self) -> None:\n pass\n\n @printer.command(name="list-contracts")\n def cli(self) -> None:\n pass<\/code><\/pre>\nHere\u2019s what each part of the template does:<\/p>\n
\nprint()<\/code><\/strong>: Main execution method where analysis results are displayed<\/li>\ncli()<\/code><\/strong>: Command-line interface handler for custom arguments<\/li>\n<\/ul>\nImplementing the Visitor Pattern<\/h3>\n
Wake uses the Visitor pattern to traverse the contract’s Abstract Syntax Tree (AST). The visitor pattern allows Wake to automatically navigate through your code\u2019s structure, enabling you to react to specific elements\u2014such as contract or function definitions.<\/p>\n
To list contracts, we’ll override the visit_contract_definition<\/code> method, which gets called for each contract in the codebase.<\/p>\nAdd this method to your ListContractsPrinter<\/code> class:<\/p>\ndef visit_contract_definition(self, node: ir.ContractDefinition) -> None:\n print(node.name)<\/code><\/pre>\nTest your printer:<\/p>\n
wake print list-contracts<\/code><\/pre>\nThis command runs your printer and prints all contract names found in your project.<\/p>\n
Refining the Output<\/h3>\n
The basic implementation shows all contracts, including interfaces and inherited contracts. Let’s improve it to show only deployable contracts:<\/p>\n
from __future__ import annotations\n\nimport networkx as nx\nimport rich_click as click\nimport wake.ir as ir\nimport wake.ir.types as types\nfrom rich import print\nfrom wake.cli import SolidityName\nfrom wake.printers import Printer, printer\n\n\nclass ListContractsPrinter(Printer):\n\n def visit_contract_definition(self, node: ir.ContractDefinition) -> None:\n print(node.name)\n\n def print(self) -> None:\n pass\n\n @printer.command(name="list-contracts")\n def cli(self) -> None:\n pass<\/code><\/pre>\nRight now, the printer lists every contract, including interfaces and base classes. Let\u2019s refine it to show only deployable ones.<\/p>\n
![\"\"](\"https:\/\/abchprod.wpengine.com\/wp-content\/uploads\/2025\/11\/Screenshot-2025-11-04-at-18.32.38.png\")
<\/p>\n
Filtering for Deployable Contracts<\/h3>\n
Add conditions to filter out interfaces, libraries, and base contracts. This helps identify which contracts are actually deployable:<\/p>\n
def visit_contract_definition(self, node: ir.ContractDefinition) -> None:\n if len(node.child_contracts) != 0:\n return\n\n if node.kind != ir.enums.ContractKind.CONTRACT:\n return\n\n print(node.name)<\/code><\/pre>\nThe ContractDefinition<\/span> class includes attributes you can use to filter your results.\u00a0For complete reference, see: https:\/\/ackee.xyz\/wake\/docs\/latest\/api-reference\/ir\/declarations\/contract-definition\/<\/a><\/p>\nComplete Implementation<\/h3>\n
Here’s the final version with proper separation of concerns\u2014collecting data during traversal and displaying it in the print()<\/code> method:<\/p>\nfrom __future__ import annotations\n\nimport networkx as nx\nimport rich_click as click\nimport wake.ir as ir\nimport wake.ir.types as types\nfrom rich import print\nfrom wake.cli import SolidityName\nfrom wake.printers import Printer, printer\n\n\nclass ListContractsPrinter(Printer):\n contracts: list[ir.ContractDefinition]\n\n def __init__(self):\n self.contracts = []\n\n def visit_contract_definition(self, node: ir.ContractDefinition) -> None:\n if len(node.child_contracts) != 0:\n return\n\n if node.kind != ir.enums.ContractKind.CONTRACT:\n return\n\n self.contracts.append(node)\n\n def print(self) -> None:\n for contract in self.contracts:\n print(contract.name)\n\n @printer.command(name="list-contracts")\n def cli(self) -> None:\n pass<\/code><\/pre>\nYou\u2019ve just built your first printer. It collects and prints deployable contracts\u2014your first step toward automated contract mapping.<\/p>\n
Tutorial 2: Analyzing Contract Functions<\/h2>\n
Understanding which functions are externally callable is crucial for security: public \u2018withdraw\u2019 or \u2018transfer\u2019 functions often define a contract\u2019s attack surface. Let’s create a printer that maps out the attack surface by listing all public and external functions.<\/p>\n
Setting Up the Functions Printer<\/h3>\n
Create a new printer:<\/p>\n
wake up printer list-functions<\/code><\/pre>\nImplementation Strategy<\/h3>\n
Now we\u2019ll expand our printer to map each contract\u2019s external attack surface. Our goal: List only the final, callable public\/external functions for each deployable contract, excluding interfaces and overridden functions.<\/p>\n
While we could use visit_function_definition<\/code> to iterate all functions, grouping them by contract provides better context. We’ll use visit_contract_definition<\/code> and access the functions<\/code> attribute.<\/p>\nStart by collecting all contracts:<\/p>\n
class ListFunctionsPrinter(Printer):\n\n contracts: list[ir.ContractDefinition] = []\n\n def visit_contract_definition(self, node: ir.ContractDefinition) -> None:\n self.contracts.append(node)<\/code><\/pre>\nProcessing the Inheritance Hierarchy<\/h3>\n
In the print()<\/code> method, we traverse the inheritance hierarchy from base to derived contracts, showing callable functions at each level:<\/p>\n def print(self) -> None:\n for node in self.contracts:\n\n # Skip if not a contract (interface, library)\n if node.kind != ir.enums.ContractKind.CONTRACT:\n continue\n\n #Process leaf contracts only\n if len(node.child_contracts) !=0:\n continue\n\n # Print the inheritance hierarchy (from base to derived)\n for base_contract in reversed(node.linearized_base_contracts):\n print(f"Contract: {base_contract.name}")\n\n functions = self.get_callable_final_functions(base_contract)\n\n if len(functions) > 0:\n print("Functions:")\n for function in functions:\n print(f" {function.name}")\n print("--------------------")<\/code><\/pre>\nFiltering for Attack Surface Functions<\/h3>\n
The get_callable_final_functions<\/code> helper method identifies which functions can actually be called by external actors. It checks that a function is a final implementation (not overridden by child contracts) and has public or external visibility. These are the functions that matter for security analysis since they represent the contract’s actual attack surface.<\/p>\n def get_callable_final_functions(self, contract: ir.ContractDefinition) -> list[ir.FunctionDefinition]:\n return [\n func for func in contract.functions\n if len(func.child_functions) == 0 # Is final implementation\n and func.visibility in [ir.enums.Visibility.PUBLIC, ir.enums.Visibility.EXTERNAL]\n ]<\/code><\/pre>\nRunning the Functions Printer<\/h3>\n
Execute the printer to see the inheritance hierarchy and callable functions:<\/p>\n
wake print list-functions<\/code><\/pre>\nOutput:<\/p>\n
Contract: Context\nContract: Ownable\nFunctions:\n owner\n renounceOwnership\n transferOwnership\nContract: SingleTokenVault\nFunctions:\n constructor\n deposit\n withdraw\n emergencyWithdraw\n balanceOf\n setDepositLimits\n--------------------\nContract: EIP712Example\nFunctions:\n constructor\n DOMAIN_SEPARATOR\n castVoteBySignature\n getVoteCounts\n--------------------\nContract: Context\nContract: IERC20\nContract: IERC20Metadata\nContract: IERC20Errors\nContract: ERC20\nFunctions:\n name\n symbol\n decimals\n totalSupply\n balanceOf\n transfer\n allowance\n approve\n transferFrom\nContract: IERC20Permit\nContract: IERC5267\nContract: EIP712\nFunctions:\n eip712Domain\nContract: Nonces\nContract: ERC20Permit\nFunctions:\n permit\n nonces\n DOMAIN_SEPARATOR\nContract: PermitToken\nFunctions:\n constructor\n--------------------\nContract: Token\nFunctions:\n constructor\n mintTokens\n transfer\n transferWithBytes\n getBalance\n--------------------\nContract: Context\nContract: IERC20\nContract: IERC20Metadata\nContract: IERC20Errors\nContract: ERC20\nFunctions:\n name\n symbol\n decimals\n totalSupply\n balanceOf\n transfer\n allowance\n approve\n transferFrom\nContract: MockERC20\nFunctions:\n constructor\n--------------------<\/code><\/pre>\nThe output gives you a quick visual map of each contract\u2019s inheritance and callable entry points.<\/p>\n
Tutorial 3: Adding Command-Line Options<\/h2>\n
Real-world analysis often requires focusing on specific contracts. Let’s enhance our printer to accept command-line arguments, allowing targeted analysis of individual contracts.<\/p>\n
Understanding CLI Integration<\/h3>\n
Wake printers can accept command-line options through the @click.option<\/code> decorator. This enables dynamic analysis based on user input. We’ll add a --contract-name<\/code> option to filter results for a specific contract.<\/p>\nImplementing the Option<\/h3>\n
First, add a class member to store the contract name, then use @click.option<\/code> to capture the command-line argument:<\/p>\n@printer.command(name="list-functions")\n@click.option("--contract-name", type=str, required=False)\ndef cli(self, contract_name: str | None) -> None:\n self.contract_name = contract_name<\/code><\/pre>\nConditional Filtering Logic<\/h3>\n
The print()<\/code> method now checks if a specific contract was requested. If no contract name is provided, the printer lists all deployable contracts. If a name is specified, it drills into that contract\u2019s hierarchy only, even if it’s not a leaf contract.<\/p>\nComplete Implementation with CLI Options<\/h3>\n
Here\u2019s the final printer with optional contract filtering built in.<\/p>\n
from __future__ import annotations\n\nimport networkx as nx\nimport rich_click as click\nimport wake.ir as ir\nimport wake.ir.types as types\nfrom rich import print\nfrom wake.cli import SolidityName\nfrom wake.printers import Printer, printer\n\n\nclass ListFunctionsPrinter(Printer):\n\n contracts: list[ir.ContractDefinition] = []\n contract_name: str | None = None\n\n\n def get_callable_final_functions(self, contract: ir.ContractDefinition) -> list[ir.FunctionDefinition]:\n return [\n func for func in contract.functions\n if len(func.child_functions) == 0 # Is final implementatione\n and func.visibility in [ir.enums.Visibility.PUBLIC, ir.enums.Visibility.EXTERNAL]\n ]\n\n def visit_contract_definition(self, node: ir.ContractDefinition) -> None:\n self.contracts.append(node)\n\n\n def print(self) -> None:\n for node in self.contracts:\n # If contract name is specified, only process that contract\n if self.contract_name is not None and node.name != self.contract_name:\n continue\n\n # Skip if not a contract (e.g., interface, library)\n if node.kind != ir.enums.ContractKind.CONTRACT:\n continue\n\n # If no contract name specified, only process leaf contracts\n if self.contract_name is None and len(node.child_contracts) != 0:\n continue\n\n # Print the inheritance hierarchy (from base to derived)\n for base_contract in reversed(node.linearized_base_contracts):\n print(f"Contract: {base_contract.name}")\n\n functions = self.get_callable_final_functions(base_contract)\n\n if len(functions) > 0:\n print("Functions:")\n for function in functions:\n print(f" {function.name}")\n print("--------------------")\n\n @printer.command(name="list-functions")\n @click.option("--contract-name", type=str, required=False)\n def cli(self, contract_name: str | None) -> None:\n self.contract_name = contract_name\n pass<\/code><\/pre>\nNow your printer can analyze specific contracts on demand\u2014a feature that makes targeted auditing fast and repeatable.<\/p>\n
Using the Enhanced Printer<\/h3>\n
Now you can analyze specific contracts:<\/p>\n
# Analyze all deployable contracts\nwake print list-functions\n\n# Focus on a specific contract\nwake print list-functions --contract-name Token<\/code><\/pre>\nPractical Applications for Security Auditing<\/h2>\n
With these foundational skills, you can create printers that visualize and analyze your codebase structure. Custom printers let you visualize key code relationships quickly. They don\u2019t detect vulnerabilities directly, but they reveal patterns that guide your manual review.<\/p>\n
Useful Analysis Patterns to Visualize<\/h3>\n
Once you\u2019re comfortable building printers, try these advanced patterns to visualize complex security relationships.<\/p>\n
Access Control Mapping<\/strong>: Create printers that list all state-changing functions alongside their access modifiers. This overview helps you quickly identify which functions might need additional protection.<\/p>\nCall Flow Visualization<\/strong>: Map out which contracts call which functions. Understanding these relationships reveals potential attack paths and helps prioritize your audit focus.<\/p>\nState Variable Usage<\/strong>: Track how storage variables are accessed across functions. This analysis helps identify complex state dependencies that warrant closer inspection.<\/p>\nInheritance Hierarchies<\/strong>: Visualize the complete inheritance tree of your contracts. Complex inheritance can hide function implementations and create unexpected behaviors.<\/p>\nBuilding Your Analysis Toolkit<\/h3>\n
Start small. Build printers that solve your immediate needs. Each one adds to your personal toolkit. Over time, you\u2019ll develop reusable scripts that make every audit faster.<\/p>\n
The Wake printer system’s flexibility means you can adapt your analysis tools to different audit scenarios. Whether you’re mapping upgrade patterns, visualizing DeFi protocol interactions, or understanding storage layouts, custom printers transform hours of manual code reading into seconds of automated analysis and visualization.<\/p>\n
Next Steps<\/h2>\n
Printers give you the map; detectors find the vulnerabilities. Together, they turn Solidity auditing from a manual grind into a structured, insightful process. Every printer you write makes complex code clearer\u2014and strengthens the safety of the smart contracts you review.<\/p>\n
For vulnerability detection, Wake provides a separate detector system that goes beyond visualization to identify actual security issues. Printers give you the map; detectors find the problems.<\/p>\n
Consider contributing your printers back to the community. Analysis tools are most powerful when shared, and your custom printer might help another auditor understand complex codebases more efficiently.<\/p>\n
For more advanced topics and complete API reference, visit: Wake static analysis documents<\/a><\/p>\n