# EVMole Python EVMole Python is built with [PyO3](https://pyo3.rs/) for different operating systems and Python versions. In most cases, pip will install a pre-built wheel. However, the source distribution (sdist) is also published, allowing installation on other architectures and Python versions (this is automatically tested). ## Installation To install or upgrade EVMole, use pip: ```bash $ pip install evmole --upgrade ``` ## API ### contract\_info ```python def contract_info(code: Union[bytes, str], *, selectors: bool = False, arguments: bool = False, state_mutability: bool = False, storage: bool = False, disassemble: bool = False, basic_blocks: bool = False, control_flow_graph: bool = False, metadata: bool = False) -> Contract ``` Extracts information about a smart contract from its EVM bytecode. **Arguments**: - `code` - Runtime bytecode as a hex string (with or without '0x' prefix) or raw bytes. - `selectors` - When True, extracts function selectors. - `arguments` - When True, extracts function arguments. - `state_mutability` - When True, extracts function state mutability. - `storage` - When True, extracts persistent and transient storage layouts. - `disassemble` - When True, includes disassembled bytecode. - `basic_blocks` - When True, extracts basic block ranges. - `control_flow_graph` - When True, builds control flow graph. - `metadata` - When True, extracts terminal CBOR metadata. **Returns**: - `Contract` - Object containing the requested smart contract information. Fields that weren't requested to be extracted will be None. ### Contract ```python class Contract(): functions: Optional[List[Function]] storage: Optional[List[StorageRecord]] transient_storage: Optional[List[StorageRecord]] disassembled: Optional[List[Tuple[int, str]]] basic_blocks: Optional[List[Tuple[int, int]]] control_flow_graph: Optional[ControlFlowGraph] metadata: Optional[CborMetadata] ``` Contains analyzed information about a smart contract. **Attributes**: - `functions` - List of detected contract functions. None if no functions were extracted - `storage` - List of persistent contract storage records. None if storage layout was not extracted - `transient_storage` - List of transient contract storage records. None if storage layout was not extracted - `disassembled` - List of bytecode instructions, where each element is [offset, instruction]. None if disassembly was not requested - `basic_blocks` - List of basic block ranges as (first_op, last_op) offsets. None if basic blocks were not requested - `control_flow_graph` - Control flow graph of the contract. None if control flow analysis was not requested - `metadata` - Terminal CBOR metadata. None if extraction was not requested or no valid trailer exists ### Function ```python class Function(): selector: str bytecode_offset: int dispatch: str arguments: Optional[str] state_mutability: Optional[str] ``` Represents a public smart contract function. **Attributes**: - `selector` - Function selector as a 4-byte hex string without '0x' prefix (e.g., 'aabbccdd'). - `bytecode_offset` - Starting byte offset within the EVM bytecode for the function body. - `dispatch` - `"abi"` when the selector appears in the normal external-function dispatcher, or `"fallback"` when it appears in fallback dispatch logic. - `arguments` - Function argument types in canonical format (e.g., 'uint256,address[]'). None if arguments were not extracted - `state_mutability` - Function's state mutability ('pure', 'view', 'payable', or 'nonpayable'). None if state mutability was not extracted ### StorageRecord ```python class StorageRecord(): slot: str offset: int type: str reads: List[str] writes: List[str] ``` Represents an inferred persistent or transient storage record. The containing `Contract` field identifies the storage domain. **Attributes**: - `slot` - Storage slot number as a hex string (e.g., '0', '1b'). - `offset` - Byte offset within the storage slot (0-31). - `type` - Variable type (e.g., 'uint256', 'mapping(address => uint256)', 'bytes32'). - `reads` - List of function selectors that read from this storage location. - `writes` - List of function selectors that write to this storage location. ### ControlFlowGraph ```python class ControlFlowGraph(): blocks: List[Block] ``` Represents the control flow graph of the contract bytecode. **Attributes**: - `blocks` - List of basic blocks in the control flow graph ### Block ```python class Block(): id: int start: int end: int btype: BlockType ``` Represents a basic block in the control flow graph. **Attributes**: - `id` - Unique block identifier (CFG key) - `start` - Byte offset where the block's first opcode begins - `end` - Byte offset where the block's last opcode begins - `btype` - Type of the block and its control flow ### BlockType ```python class BlockType(): class Terminate: success: bool class Jump: to: int class Jumpi: true_to: int false_to: int class DynamicJump: to: List[DynamicJump] class DynamicJumpi: true_to: List[DynamicJump] false_to: int ``` Represents the type of a basic block and its control flow. This is an enum-like class, all child classes are derived from `BlockType` class #### Terminate Block terminates execution - `success` - True for normal termination (STOP/RETURN), False for REVERT/INVALID #### Jump Block ends with unconditional jump - `to` - Destination block ID; use `Block.start` to get the bytecode offset #### Jumpi Block ends with conditional jump - `true_to` - Destination block ID if condition is true; use `Block.start` to get the bytecode offset - `false_to` - Destination block ID if condition is false; use `Block.start` to get the bytecode offset #### DynamicJump Block ends with jump to computed destination - `to` - Possible computed jump destinations #### DynamicJumpi Block ends with conditional jump to computed destination - `true_to` - Possible computed jump destinations if true - `false_to` - Destination block ID if condition is false; use `Block.start` to get the bytecode offset ### DynamicJump ```python class DynamicJump(): path: List[int] to: Optional[int] ``` Represents a dynamic jump destination in the control flow. **Attributes**: - `path` - Path of block IDs leading to this jump - `to` - Destination block ID if known, None otherwise; use `Block.start` to get the bytecode offset ### CborValue ```python class CborValue(): type: Literal["string", "integer", "bytes", "bool", "undecoded"] value: Union[str, int, bytes, bool] ``` Represents a decoded CBOR scalar or an unsupported value kept in encoded form. **Attributes**: - `type` - Value kind: string, integer, bytes, bool, or undecoded. - `value` - Decoded scalar. Bytes and undecoded values are returned as bytes. ### CborEntry ```python class CborEntry(): key: str value: CborValue ``` Represents a CBOR map entry having a text-string key. **Attributes**: - `key` - Text-string map key. - `value` - Decoded or preserved CBOR value. ### CborMetadata ```python class CborMetadata(): bytecode_offset: int cbor_length: int entries: List[CborEntry] ``` Represents terminal length-suffixed CBOR metadata. **Attributes**: - `bytecode_offset` - Absolute byte offset of the CBOR payload. - `cbor_length` - CBOR payload length, excluding the two-byte suffix. - `entries` - Entries having text-string keys; other keys are skipped.