DOCSEARCHbyAlgolia
Submit Docs

pyevmasm Documentation

repository·master·Indexed 18 days ago

https://github.com/crytic/pyevmasm

An Ethereum Virtual Machine (EVM) assembler and disassembler library providing a Python API and a command-line utility. It supports converting between EVM assembly and bytecode, mapping block numbers to hard forks, and accessing detailed instruction metadata. Supported forks include frontier, homestead, byzantium, constantinople, london, shanghai, cancun, and others.

Tokens
3.6K
Snippets
16
Records
22
Agent score
56%

What's inside pyevmasm

  2. Use the pyevmasm Python API

    master

    The Python API provides low-level control over EVM assembly and disassembly.

    Key Functions:

    • disassemble_hex(hex_string): Disassembles a hex string into human-readable instructions.
    • disassemble_all(bytes): Disassembles a byte sequence into a list of instruction objects.
    • assemble_hex(instructions): Assembles a list of instruction objects into a hex string.
    • assemble_hex(hex_string): Assembles a string of human-readable instructions into a hex string.

    Instruction Tables: Access fork-specific instruction sets via instruction_tables. You can look up instructions by their opcode (integer) or their mnemonic (string).

    from pyevmasm import instruction_tables, disassemble_hex, disassemble_all, assemble_hex
import binascii

# Accessing instruction tables
instruction_table = instruction_tables['byzantium']

# Disassembling bytes
bin_data = binascii.unhexlify('608060405260043610603f57600035')
instrs = list(disassemble_all(bin_data))

# Assembling instructions back to hex
a = assemble_hex(instrs)
print(a)  # '0x60805760405260043610603f57600035'

# Assembling from mnemonic strings
print(assemble_hex('PUSH1 0x40\nMSTORE\n'))  # '0x604052'

  4. Use the evmasm CLI

    master

    The evmasm command-line utility allows you to assemble, disassemble, or list EVM opcodes.

    Core Commands:

    • -a, --assemble: Assemble EVM instructions to opcodes.
    • -d, --disassemble: Disassemble EVM to opcodes.
    • -t, --print-opcode-table: List supported EVM opcodes.

    Input/Output Options:

    • -bi, --binary-input: Use binary input mode (disassembly only).
    • -bo, --binary-output: Use binary output mode (assembly only).
    • -i [INPUT], --input [INPUT]: Specify input file (defaults to stdin).
    • -o [OUTPUT], --output [OUTPUT]: Specify output file (defaults to stdout).

    Fork Selection: Use -f FORK, --fork FORK to select the EVM fork. Supported forks include:

    • frontier
    • homestead
    • tangerine_whistle
    • spurious_dragon
    • byzantium (default)
    • constantinople
    • serenity
    • An unsigned block number can also be used to select the fork.
    # Example: Disassembling a hex string via stdin
$ echo -n "608060405260043610603f57600035" | evmasm -d

  5. Assemble a single EVM instruction

    master

    Use assemble_one to convert a single line of assembly text into an Instruction object. This is useful for testing specific opcodes or building instruction sequences manually.

    from pyevmasm import assemble_one

# Creates an Instruction object for PUSH1 0x10
instruction = assemble_one('PUSH1 0x10')
print(instruction.name)  # PUSH1
print(instruction.operand) # 16

  6. Disassemble hex-encoded EVM bytecode

    master

    Use disassemble_hex to convert a hexadecimal string (optionally prefixed with 0x) into a human-readable string of assembly mnemonics. This is useful when working with hex strings commonly found in blockchain explorers or transaction data.

    from pyevmasm import disassemble_hex

# Disassemble a hex string
asm_text = disassemble_hex('0x6060604052600261010')
print(asm_text)

  7. Disassemble a single EVM instruction

    master

    Use disassemble_one to extract a single Instruction object from a bytecode stream. It consumes the bytes required for the instruction (including its operand) from the provided iterator.

    from pyevmasm import disassemble_one

# Disassemble one instruction from bytes
instruction = disassemble_one(b'\x60\x10')
print(instruction.name) # PUSH1

  8. Disassemble EVM bytecode with pyevmasm

    master

    Use the disassembly functions to convert EVM bytecode back into human-readable assembly. The available functions are:

    • disassemble(bytecode: bytes): Disassembles a single chunk of bytecode.
    • disassemble_one(bytecode: bytes): Disassembles a single chunk of bytecode (alias).
    • disassemble_hex(hex_code: str): Disassembles a hex-encoded string of bytecode.
    • disassemble_all(bytecodes: List[bytes]): Disassembles a list of bytecode chunks.
    • disassemble_all(hex_codes: List[str]): Disassembles a list of hex-encoded bytecode strings.
    from pyevmasm import disassemble, disassemble_hex

# Disassemble raw bytes
assembly = disassemble(b"\x60\x00\x50")

# Disassemble hex string
assembly_from_hex = disassemble_hex("600050")

  9. Disassemble EVM bytecode to text

    master

    Use disassemble to convert raw EVM bytecode into a human-readable string of assembly mnemonics. You can specify the starting program counter (pc) and the Ethereum hardfork (fork) to ensure correct opcode mapping.

    Supported input types for bytecode include str, bytes, bytearray, or an Iterator of bytes.

    from pyevmasm import disassemble

# Disassemble raw bytes
asm_text = disassemble(b'\x60\x60\x60\x40\x52\x60\x02\x61\x01\x00')
print(asm_text)

  10. Map a block number to an EVM fork name

    master

    Use the block_to_fork function to determine which Ethereum hard fork applies to a specific block number. This is useful for selecting the correct InstructionTable when disassembling or assembling EVM bytecode for a specific point in Ethereum's history.

    from pyevmasm.evmasm import block_to_fork

fork = block_to_fork(4370000)  # Returns 'byzantium'
fork = block_to_fork(0)      # Returns 'frontier'

  11. Inspect EVM instructions and tables

    master

    The library provides access to the underlying instruction definitions and data structures:

    • Instruction: A class representing a single EVM instruction.
    • instruction_tables: A collection of tables containing the definitions and metadata for EVM instructions.