# Core refactor

The following document will describe the necessary items that will be refactored
during the **core refactoring** phase. This eleminary document will describe the
steps required for a clean API for the core components of ethereum which
includes the following packages: core, core/vm, core/state.

## Topics

The following topics will see refactoring:

* `core`
* `core/vm`

Many of the `core` objects are used to modify **state** and many of them stack
to complete modifications. The `core/vm` lacks in documentation and suffers from
code duplication due to the new JIT-VM.

## Tasks

- [x] Filter
- [x] Execution object
- [ ] VM Database model
- [x] Cleanup byte code vm
- [x] Context => Contract
- [x] State transition changes
- [x] Remove checkpointing
- [x] ChainManager => BlockChain
- [ ] VM documentation
- [ ] Code setting from VM returned execution
- [ ] VM var cleanup

## Changes

The `core.Filter` object and methods no longer use unexported core functionality
and can therefor be moved to the `event/filter` package. Remove the
`core.Backend` dependency from the `core.Filter` objects by adding the following
`core` methods:

* `core.GetCurrentBlock(db common.Database)`

and remove the dependency on the block manager by directly using
`core.GetBlockReceipts`. These changes require the `core.NewFilter` to take a
`common.Database` argument instead of `core.Backend`.

Inside `core/vm` `vm.Transact` needs to be moved to the `core` package. From a
VM point of view "transacting" shouldn't exist. The VM shouldn't handle core
tasks.

The `core/vm` depends on the `core/state` packages for handling state changes.
An interface needs to be created that can handle this instead (`vm.Database`)
consisting of the following methods:

* AddBalance
* AddRefund
* Delete
* GetBalance
* Get/SetState
* GetCode

This will the dependency on the `core/state` packages.

Some parts of the core depends on the `vm.Environment` for retrieving the
statedb. Now that `State` has been removed from the environment we can no longer
depend on it (and shouldn't).

When a new object (e.g. account) is create - therefor creating a new instance of
the VM - upon returning the VM shouldn't be responsible for any state
modefication. Currently the VM is responsible for checking the error code and
setting the code if it's successful. This should be handled in the core instead
(i.e. `core.Execution`).

Cleanup up the VM to use the same type code as the JIT-VM this in order to
further reduce code duplication and reduce maintainability of the code and bugs
that would otherwise be required to be fixed in 2 places. By moving to the JIT
specific instructions it should optimise VM byte code execution by a small
factor.

Extend the documentation of `core/vm`

* Context method and objects
* Common functions, variables and constants
* Precompiled contracts functions
* Memory methods and object
* Stack method and object

Cleanup `core/vm/common.go` and remove unused variables/old variables.

The `vm.Context` object, while previous handling more than just contract
related tasks should be renamed to `vm.Contract`. This is much more in line with
with it actual tasks and its purpose.

`core` should reduce the amount of objects required to modify **state**. This
should make it much easier to be re-used and will remove some of the requirement
to use the full **ethereum stack**:

* `core.Execution` => `core.Create`
* `core.Execution` => `core.Call`
* `core.ApplyMessage` => `core.ApplyTransaction`

The `core.ApplyMessage` should be the initialiser of the `core.StateTransition`
object and the `core.NewStateTranstion` method should be removed. No pointer are
required and no dynamic memory allocation is required this way. No pointer will
be escaped.

With the merging of the databases we can safely remove the checkpointing from
the chain manager.

The `core.ChainManager` object should be renamed to `core.BlockChain` to better
reflect the meaning of the object itself.