Metadata-Version: 2.1
Name: evmdasm
Version: 0.1.8
Summary: A lightweight ethereum evm bytecode asm instruction registry and disassembler library.
Home-page: https://github.com/tintinweb/evmdasm
Author: tintinweb
Author-email: tintinweb@oststrom.com
License: GPLv2
Download-URL: https://github.com/tintinweb/evmdasm/tarball/v0.1.8
Keywords: evmdasm,ethereum,blockchain,evm,disassembler
Platform: UNKNOWN

[![Build Status](https://api.travis-ci.org/tintinweb/evmdasm.svg?branch=master)](https://travis-ci.org/tintinweb/evmdasm/)

# 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](https://github.com/tintinweb/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](https://github.com/tintinweb/evmdasm). 


For more information visit the [Wiki](https://github.com/tintinweb/evmdasm/wiki)

### Setup

##### from pypi
```
#> python3 -m pip install evmdasm
```

##### from source
```
#> python3 setup.py install
```

### Commandline Utility

#### usage
```
#> python3 -m evmdasm --help
```

#### disassemble
```
#> echo 60406040ff | python3 -m evmdasm --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()` or `registry.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 into `registry.INSTRUCTIONS`


```python
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 takes `bytes`, `0x<hexstr>` or `hexstr`
* use `EvmBytecode.disassemble()` to transform it into a `EvmInstructions(...)` object (actually a custom `list` of `Instruction(...)` objects)
* use `EvmInstructions.assemble()` to transform it into a `EvmBytecode(...)` object. 

```python
# 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

```


