Formalize API for Computation object.

What is wrong?

Currently, the Computation object houses lots of information and sub-APIs for things like maniputlating the stack, consuming gas, etc. This creates a lot of public API surface area since we are effectively support two public APIs for anything needed from a sub-property of the Computation object.

• Computation.memory is the API for getting at the Memory
• Computation.memory.read is the API for reading from memory.

How can it be fixed

I propose moving all sub-APIs to private properties and only exposing them through a single public API on the Computation object itself.

For example.

• Computation.memory -> Computation._memory
• Computation.memory.read() -> Computation.memory_read()

In the process we should organize the body of the Computation object by subject/sub-API meaning that we co-locate all of the memory APIs together, and so on for each category.

Maybe use abbreviated suffixes

Some of these accessors can be long:

• Computation.gas_meter.consume_gas

For APIs that are unambiguous like this one we can just use:

• Computation.consume_gas()

However, some APIs will need to be prefixed such as Computation.stack.pop(). In cases like this we should use a prefixed method name:

• Computation.stack_pop()
• Computation.memory_read()

Common base class

The BaseComputation class should be converted to have only STUB implementations of these methods with NotImplementedError exceptions being raised in the methods.

Then, a Computation class can be created at evm.computation.Computation which contains all of the current implementations of these methods.

Documentation

This should also include a page in the docs/ that lists all of these APIs and has a basic human readable description of what they do.

[carver]

👍 Occasionally it’s nice to be able to dir() at the repl, so dir(computation) would be much nicer this way.

Computation.gm_consume_gas()

Maybe this could even just be Computation.consume_gas(). It seems unambiguously named. The fact that it’s called gas meter seems like an unnecessary implementation detail.

The other main modules seem to work follow the memory example nicely:

• stack
• memory
• code

Like: Computation.stack_pop()

A possible argument against this is that the sharding changes may introduce new APIs which are not used pre-sharding, and in some cases, potentially removing APIs which are no longer part of the sharding EVM.

Seems like BaseComputation should just shrink, then, to the intersection of the APIs. I imagine there would still be a useful subset of methods to document.

[owocki]

@pipermerriam @murduk 👋

paid oot!