Thoughts on API refactors for Chain, VM, and State

[pipermerriam]

Architecture Refactor for Py-EVM

What is wrong?

The APIs on Chain, VM and State have all evolved organically. Now that
we have a better picture of how they are used, we should be able to make some
improvements to make things more intuitive, less stateful, and with reduced
mutation.

How can it be fixed

Terminology

Blocks

• Finalized:
  • A block which has been sealed.
    • In proof of work this means setting the mix_hash and nonce
• HEAD:
  • The highest finalized block in the chain
• TIP:
  • The unsealed block who's parent is the HEAD block

Chain

The Chain is now the only stateful object with non-pure APIs

• rename Chain.header to Chain.tip.
• add Chain.head for access to the canonical chain head.

Chain.apply_transaction(transaction) -> computation

Adds the transaction to the current TIP block.

• error if chain.tip is empty.
• executes the transaction on top of the TIP block.
• mutates chain.header with the post execution state.
• persists the transaction and resulting receipt.

Chain.import_block(*args, **kwargs) -> block

• error if chain.tip is empty.
• delegates to VM to do block import.
• validates that the imported block is equivalent to the import result.
• persists newly imported block to the database
• mutates chain.header with new tip block header.
• leaves chain.tip empty.

Chain.finalize_block(*args, **kwargs) -> block

• error if chain.tip is empty.
• delegates to VM.mine_block
• persists newly mined block to the database
• mutates chain.header with new tip block header.
• leaves chain.tip empty.

`Chain.initialize_tip(parent=None, **context)

• error if chain.tip is not empty.
• initializes chain.tip with a new fresh header on top of chain.head

VM

The VM object is now immutable, only exposing pure functions.

• remove configure_header in favor of:
  • new initialize_block which initializes the vm with a new empty header with some configured params like coinbase, difficulty, etc.

VM.execute_transaction(transaction, block) -> state_root, receipt, computation

• pure
• executes the transaction on top of the block
• returns:
  • the updated state root
  • the receipt for the transaction
  • the computation

VM.import_block(block) -> block

• pure
• TODO: figure out how to remove the configure_header call and rather start with no header and initialize a new header with the correct params from the block being imported.

VM.finalize_block(block, receipts) -> block

• pure
• computes receipt and transaction tries.
• TODO: define how mixhash and nonce get set on the header.
• returns:
  • the finalized block.

State

The State object is now immutable, only exposing pure functions.

State.execute_transaction(transaction) -> computation, state_root

• pure
• executes the transaction
• returns:
  • the resulting computation and state root.

[kclowes]

closing, some changes are tracked in the more recent issue #2079