0
# PyEVMAsm
1

2
A comprehensive Ethereum Virtual Machine (EVM) assembler and disassembler library that enables developers to work with EVM bytecode and assembly instructions. PyEVMAsm supports multiple Ethereum hard forks, provides detailed instruction metadata including gas costs and stack effects, and offers both a Python API and command-line interface for converting between EVM assembly language and bytecode.
3

4
## Package Information
5

6
- **Package Name**: pyevmasm
7
- **Language**: Python
8
- **Installation**: `pip install pyevmasm`
9
- **Requirements**: Python >= 2.7 or Python >= 3.3
10

11
## Core Imports
12

13
```python
14
import pyevmasm
15
```
16

17
Common usage imports:
18

19
```python
20
from pyevmasm import (
21
    assemble_hex, disassemble_hex,
22
    assemble_one, disassemble_one,
23
    assemble_all, disassemble_all,
24
    Instruction, instruction_tables,
25
    DEFAULT_FORK
26
)
27
```
28

29
## Basic Usage
30

31
```python
32
from pyevmasm import assemble_hex, disassemble_hex, disassemble_one
33

34
# Assemble EVM assembly to bytecode
35
bytecode = assemble_hex('''
36
    PUSH1 0x80
37
    PUSH1 0x40
38
    MSTORE
39
    PUSH1 0x4
40
    CALLDATASIZE
41
    LT
42
''')
43
print(bytecode)  # "0x608060405260043610"
44

45
# Disassemble bytecode to assembly
46
assembly = disassemble_hex("0x608060405260043610")
47
print(assembly)
48
# PUSH1 0x80
49
# PUSH1 0x40
50
# MSTORE
51
# PUSH1 0x4
52
# CALLDATASIZE
53
# LT
54

55
# Analyze individual instructions
56
instruction = disassemble_one(b'\x60\x80')
57
print(f"Opcode: 0x{instruction.opcode:02x}")  # 0x60
58
print(f"Name: {instruction.name}")            # PUSH1
59
print(f"Gas cost: {instruction.fee}")         # 3
60
print(f"Operand: 0x{instruction.operand:x}") # 0x80
61
```
62

63
## Architecture
64

65
PyEVMAsm is built around several key components:
66

67
- **Instruction Class**: Core representation of EVM instructions with complete metadata (opcode, operands, gas costs, stack effects, semantic analysis)
68
- **InstructionTable**: Fork-specific lookup tables mapping opcodes/mnemonics to instruction definitions
69
- **Fork Support**: Comprehensive support for all Ethereum hard forks from Frontier to Istanbul with proper opcode evolution
70
- **Assembly/Disassembly Engine**: Bidirectional conversion between textual assembly and binary bytecode representations
71

72
The library provides both high-level convenience functions for common use cases and low-level access to instruction metadata for detailed EVM analysis and tooling development.
73

74
## Capabilities
75

76
### Assembly Operations
77

78
Convert EVM assembly language to bytecode with support for individual instructions, multiple instructions, and complete programs. Includes both binary and hexadecimal output formats.
79

80
```python { .api }
81
def assemble_one(asmcode: str, pc: int = 0, fork: str = DEFAULT_FORK) -> Instruction: ...
82
def assemble_all(asmcode: str, pc: int = 0, fork: str = DEFAULT_FORK): ...  # generator
83
def assemble_hex(asmcode: str, pc: int = 0, fork: str = DEFAULT_FORK) -> str: ...
84
```
85

86
[Assembly Operations](./assembly.md)
87

88
### Disassembly Operations
89

90
Convert EVM bytecode to assembly language with support for various input formats (bytes, hex strings, iterators) and detailed instruction analysis.
91

92
```python { .api }
93
def disassemble_one(bytecode, pc: int = 0, fork: str = DEFAULT_FORK) -> Instruction: ...
94
def disassemble_all(bytecode, pc: int = 0, fork: str = DEFAULT_FORK): ...  # generator
95
def disassemble_hex(bytecode: str, pc: int = 0, fork: str = DEFAULT_FORK) -> str: ...
96
```
97

98
[Disassembly Operations](./disassembly.md)
99

100
### Instruction Analysis
101

102
Rich instruction metadata and semantic analysis capabilities for EVM instruction inspection, including stack effects, memory/storage access patterns, and control flow analysis.
103

104
```python { .api }
105
class Instruction:
106
    opcode: int
107
    name: str
108
    operand: int
109
    pops: int
110
    pushes: int
111
    fee: int
112
    # ... 20+ additional properties
113
```
114

115
[Instruction Analysis](./instruction-analysis.md)
116

117
### Fork Management
118

119
Support for all Ethereum hard forks with proper opcode evolution, gas cost updates, and block number to fork conversion utilities.
120

121
```python { .api }
122
instruction_tables: dict  # Fork name -> InstructionTable mappings
123
def block_to_fork(block_number: int) -> str: ...
124
```
125

126
[Fork Management](./fork-management.md)
127

128
## Types
129

130
```python { .api }
131
# Core instruction representation
132
class Instruction:
133
    def __init__(self, opcode: int, name: str, operand_size: int, 
134
                 pops: int, pushes: int, fee: int, description: str,
135
                 operand: int = None, pc: int = 0): ...
136

137
# Fork-specific instruction lookup
138
class InstructionTable:
139
    def __getitem__(self, key) -> Instruction: ...  # key: int (opcode) or str (mnemonic)
140
    def get(self, key, default=None) -> Instruction: ...
141
    def __contains__(self, key) -> bool: ...
142
    def __iter__(self): ...
143

144
# Exception types
145
class UnknownMnemonicError(Exception): ...
146
class UnknownOpcodeError(Exception): ...
147
class AssembleError(Exception): ...
148
class ParseError(Exception): ...
149
```