A lightweight ethereum evm bytecode asm instruction registry and disassembler library.
Project description
evmdasm
A lightweight ethereum evm bytecode instruction registry and disassembler library.
This library is meant for providing a static interface and registry for EVM opcodes and instructions. The idea is to keep it as lightweight as possible especially when it comes to dependencies or high level features.
e.g. The ethereum-dasm project - a kind of high level disassembler with static/dynamic analysis features - relies on the registry and base disassembling functionality provided by evmdasm.
TBD
Setup
from pypi
#> python3 -m pip install evmdasm
from source
#> python3 setup.py install
Commandline Utility
usage
#> python3 -m evmdasm --help
disassemble
#> python3 -m evmdasm --disassemble 0x60406040ff
PUSH1 40
PUSH1 40
SELFDESTRUCT
list available instructions
#> python3 -m evmdasm --list [<filter>]
0xop | instruction category gas
============================================================
0x0 | STOP terminate 0
0x1 | ADD arithmetic 3
0x2 | MUL arithmetic 5
0x3 | SUB arithmetic 3
...
0xf0 | CREATE system 32000
0xf1 | CALL system 40
0xf2 | CALLCODE system 40
0xf3 | RETURN terminate 0
0xf4 | DELEGATECALL system 40
0xf5 | CREATE2 system 32000
0xfa | STATICCALL system 40
0xfd | REVERT terminate 0
0xff | SELFDESTRUCT terminate 0
Library
accessing the instruction registry
registry.INSTRUCTIONS
holds instruction templates. These are the initial set ob instructions available to the evm. Keep the templates static/unchanged.- To create a new instruction from a template either use
instruction.clone()
orregistry.create_instruction(name=; or opcode=)
. Feel free to do anything you want with this new instance of an evm instruction. - To add new instructions just create an
Instruction(...)
object and put it intoregistry.INSTRUCTIONS
from evm_instruction import registry
# access via named dict
jmp = registry.instruction.JUMP
# access via dict
## accessing the template objects (avoid modifying them)
jmp = registry.INSTRUCTIONS_BY_OPCODE["JUMP"] # get the template object from the instruction registry
jmp = registry.INSTRUCTIONS_BY_NAME["JUMP"] # get the template object from the instruction registry
jmp = jmp.clone() # clone a new instruction from the template object
## creating new instruction objects from the template
jmp = registry.create_instruction(name="JUMP") # create a new jump instruction object in order to keep (
# access via categories lookup
terminating_instructions = registry.INSTRUCTIONS_BY_CATEGORY["terminate"]
# access all instructions as a list (no guarantee this is sorted in the future)
list_of_all_instructions = registry.INSTRUCTIONS
# extract certain instructions
list_of_gas_heavy_instructions = [i for i in registry.INSTRUCTIONS if i.gas > 500]
disassembling bytecode
- to work with evm-bytecode create a new
EvmBytecode(...)
object. It either takesbytes
,0x<hexstr>
orhexstr
- use
EvmBytecode.disassemble()
to transform it into aEvmInstructions(...)
object (actually a customlist
ofInstruction(...)
objects) - use
EvmInstructions.assemble()
to transform it into aEvmBytecode(...)
object.
# disassemble
evm_bytecode = '606060405260043610610062576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff16806319e30bc7146100775780635bd74afe146101055780639df211541461017f578063b1d131bf146101ad575b6000366001919061007492919061042d565b50005b341561008257600080fd5b61008a610202565b6040518080602001828103825283818151815260200191508051906020019080838360005b838110156100ca5780820151818401526020810190506100af565b50505050905090810190601f1680156100f75780820380516001836020036101000a031916815260200191505b509250505060405180910390f35b61017d600480803573ffffffffffffffffffffffffffffffffffffffff1690602001909190803590602001908201803590602001908080601f016020809104026020016040519081016040528093929190818152602001838380828437820191505050505050919080359060200190919050506102a0565b005b6101ab600480803573ffffffffffffffffffffffffffffffffffffffff1690602001909190505061038d565b005b34156101b857600080fd5b6101c0610408565b604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390f35b60018054600181600116156101000203166002900480601f0160208091040260200160405190810160405280929190818152602001828054600181600116156101000203166002900480156102985780601f1061026d57610100808354040283529160200191610298565b820191906000526020600020905b81548152906001019060200180831161027b57829003601f168201915b505050505081565b3373ffffffffffffffffffffffffffffffffffffffff166000809054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff161415156102fb57600080fd5b8273ffffffffffffffffffffffffffffffffffffffff16818360405180828051906020019080838360005b83811015610341578082015181840152602081019050610326565b50505050905090810190601f16801561036e5780820380516001836020036101000a031916815260200191505b5091505060006040518083038185876187965a03f19250505050505050565b6000809054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff166108fc3073ffffffffffffffffffffffffffffffffffffffff16319081150290604051600060405180830381858888f19350505050151561040557600080fd5b50565b6000809054906101000a900473ffffffffffffffffffffffffffffffffffffffff1681565b828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f1061046e57803560ff191683800117855561049c565b8280016001018555821561049c579182015b8281111561049b578235825591602001919060010190610480565b5b5090506104a991906104ad565b5090565b6104cf91905b808211156104cb5760008160009055506001016104b3565b5090565b905600a165627a7a723058202592c848fd2bdbf19b6558815a8c0a67519b4ad552eb001c92109a188ef215950029'
evmcode = EvmBytecode(evm_bytecode) # can be hexstr, 0xhexstr or bytes
evminstructions = evmcode.disassemble() # returns an EvmInstructions object (actually a list of new instruction objects)
# print instructions
for instr in evminstructions:
print(instr.name)
# assemble instructions
print(evm_bytecode == evminstructions.assemble().as_hexstring) # assemble the instructionlist
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
evmdasm-0.1.2.tar.gz
(11.4 kB
view hashes)
Built Distribution
evmdasm-0.1.2-py3-none-any.whl
(12.8 kB
view hashes)