Search documentation of Cartouche

# Cartouche.Assembly (Cartouche v0.1.3)

Copy Markdown View Source

A for-fun assembler of EVM assembly code from a simple lisp-like language used to construct Quark scripts.

This is really for fun and testing, so mostly feel free to ignore.

## Usage

You can build EVM assembly, via:

    Cartouche.Assembly.build([
      {:log1, 0, 0, 55}
    ])

That results in the EVM compiled script `0x603760006000a1`.

If you view that here https://ethervm.io/decompile you see that it decompiles to:

    log(memory[0x00:0x00], [0x37]);

via the assembly:

    0000    60  PUSH1 0x37
    0002    60  PUSH1 0x00
    0004    60  PUSH1 0x00
    0006    A1  LOG1

Overall, scripts can get more complex, e.g. we use a script to revert if `tx.origin` is zero (e.g. during an `eth_estimateGas`).

    Cartouche.Assembly.build([
      {:mstore, 0, 0x01020304},
      {:if, :origin, {:revert, 28, 4}, {:return, 0, 0}}
    ])

There's no real goal for this assembler. Just a fun experiment and useful in testing.

## Summary

### Types

opcode()

### Functions

assemble(opcodes)

Assmbles opcodes into raw evm bytecode

build(operations)

Compiles and assembles assembly operations.

compile(b)

Compiles operations into assembly, which can then be compiled.

constructor(code)

Returns a simple EVM program that returns the input code as the output of an Ethereum "initCode" constructor.

disassemble(bytes)

Disassembles opcodes from raw evm bytecode to opcodes.

show_opcode(op)

Returns a textual representation of the given operation.

## Types

# opcode()

    @type opcode() ::
      atom()
      | {:push, non_neg_integer(), binary()}
      | {:dup, non_neg_integer()}
      | {:swap, non_neg_integer()}
      | {:invalid, binary()}
      | {:jump_ptr, integer()}
      | {:jump_dest, integer()}

## Functions

# assemble(opcodes)

    @spec assemble([term()]) :: binary()

Assmbles opcodes into raw evm bytecode

## Examples

    iex> [{:push, 0, ""}, {:push, 4, <<0x11, 0x22, 0x33, 0x44>>}, :mstore, {:push, 1, <<4>>}, {:push, 1, <<28>>}, :revert]
    ...> |> Cartouche.Assembly.assemble()
    <<95, 99, 17, 34, 51, 68, 82, 96, 4, 96, 28, 253>>

    iex> [
    ...>   {:push, 2, <<0x01, 0x02>>},
    ...>   {:push, 1, <<0>>},
    ...>   :mstore,
    ...>   :callvalue,
    ...>   {:push, 1, <<0>>},
    ...>   :sub,
    ...>   {:jump_ptr, 0},
    ...>   :jumpi,
    ...>   {:push, 1, <<2>>},
    ...>   {:push, 1, <<30>>},
    ...>   :revert,
    ...>   {:jump_dest, 0},
    ...>   {:push, 1, <<2>>},
    ...>   {:push, 1, <<31>>},
    ...>   :revert
    ...> ]
    ...> |> Cartouche.Assembly.assemble()
    ...> |> Cartouche.Hex.to_hex()
    "0x6101026000523460000362000014576002601efd5b6002601ffd"

    iex> [
    ...>   {:dup, 2},
    ...>   {:swap, 3},
    ...>   {:invalid, ~h[0x010203]}
    ...> ]
    ...> |> Cartouche.Assembly.assemble()
    ...> |> Cartouche.Hex.to_hex()
    "0x8192fe010203"

# build(operations)

    @spec build([term()]) :: binary()

Compiles and assembles assembly operations.

## Examples

    iex> use Cartouche.Hex
    ...> [
    ...>   {:mstore, 0, ~h[0x11223344]},
    ...>   {:revert, 28, 4}
    ...> ]
    ...> |> Cartouche.Assembly.build()
    ...> |> to_hex()
    "0x63112233446000526004601cfd"

# compile(b)

    @spec compile(term()) :: [term()] | atom()

Compiles operations into assembly, which can then be compiled.

## Examples

    iex> use Cartouche.Hex
    ...> [
    ...>   {:mstore, 0, ~h[0x11223344]},
    ...>   {:revert, 4, 28}
    ...> ]
    ...> |> Cartouche.Assembly.compile()
    [{:push, 4, ~h[0x11223344]}, {:push, 1, <<0>>}, :mstore, {:push, 1, <<28>>}, {:push, 1, <<0x04>>}, :revert]

# constructor(code)

    @spec constructor(binary()) :: binary()

Returns a simple EVM program that returns the input code as the output of an Ethereum "initCode" constructor.

## Examples

    iex> use Cartouche.Hex
    ...> Cartouche.Assembly.constructor(~h[0xaabbcc])
    ...> |> to_hex()
    "0x60036200000e60003960036000f3aabbcc"

# disassemble(bytes)

    @spec disassemble(binary()) :: [term()]

Disassembles opcodes from raw evm bytecode to opcodes.

## Examples

    iex> Cartouche.Assembly.disassemble(~h[0x6101026000523460000362000014576002601efd5b6002601ffd])
    [
      {:push, 2, <<0x01, 0x02>>},
      {:push, 1, <<0>>},
      :mstore,
      :callvalue,
      {:push, 1, <<0>>},
      :sub,
      {:push, 3, <<0, 0, 20>>},
      :jumpi,
      {:push, 1, <<2>>},
      {:push, 1, <<30>>},
      :revert,
      :jumpdest,
      {:push, 1, <<2>>},
      {:push, 1, <<31>>},
      :revert
    ]

    iex> Cartouche.Assembly.disassemble(~h[0x8192fe010203])
    [
      {:dup, 2},
      {:swap, 3},
      {:invalid, ~h[0x010203]}
    ]

# show_opcode(op)

    @spec show_opcode(term()) :: String.t()

Returns a textual representation of the given operation.

## Examples

    iex> Cartouche.Assembly.show_opcode(:add)
    "ADD"

    iex> Cartouche.Assembly.show_opcode({:push, 5, <<1,2,3,4,5>>})
    "PUSH5 0x0102030405"