Original source: 0003-renaming-refactor.md

Summary

Refactor our codebase with consistent, correct, and descriptive names.

Motivation

There are a multitude of naming issues which plague our codebase. Some names are not consistent (Statement vs. Work), others are not correct (Ledger is not a ledger; there is no log of transactions). We also have some names that are not very descriptive (Statement, Work, Super_transaction, Ledger_builder, Ledger_builder_controller). Having a standardized and descriptive set of names in our codebase will increase the initial readability, reduce potential areas of confusion, and increase our ability to communicate concept consistently (in person, in code, and in documentation).

Detailed design

Merkle trees

Current Name	Description	New Name
Ledger	Interface into merkle tree of account states	Account_db
Ledger_hash	Root hash of a Account_db	Account_db_root
Merkle_ledger	In memory implementation of Account_db	Volatile_account_db
Merkle_database	On disk implementation of Account_db	Persistent_account_db
Syncable_ledger	Wrapper of Account_db to sync over network	Sync_account_db
Genesis_ledger	The initial Account_db for the protocol	Genesis_account_db

States

Current Name	Description	New Name
Parallel_scan_state	State of a series of parallel scan trees	"
Ledger_builder	State of Parallel_scan_state + Transaction_work	Pending_account_db
Ledger_builder_aux	Auxillary datastructure of Pending_account_db	Work_queue
Blockchain_state	State of Account_db root and Pending_account_db root at a block	Account_db_state
Consensus_state	Consensus mechanism specific state at a block	"
Protocol_state	The Account_db_state and Consensus_state at a block	"
Tip	The Protocol_state and Pending_account_db at a block	Full_state

Transitions

Current Name	Description	New Name
Snark_transition	Subset of Full_state_transition that is snarked	Provable_full_state_transition
Internal_transition	State transition on full states	Full_state_transition
External_transition	State transition on lite states; sent to other nodes	Protocol_state_transition

Transactions

Current Name	Description	New Name
Super_transaction	ADT for all types of account state transitions	Transaction
Transaction	Transaction for payment between accounts	Payment
Fee_transfer	Transaction for distributing work fees	Fee
Coinbase	Transaction for new currency added each Block_trans	Coinbase

Snarks

Current Name	Description	New Name
Statement	A snark proving the application of a single Txn to an Acc_db	Transaction_statement
Work	A collection of one or two Txn_statements	Transcation_work
Transaction_snark	The snark which proves Txn_statements	Transaction_snark
Blockchain_snark	The snark which proves Full_state_transs on Full_states	Full_state_transition_snark

Primary components

Current Name	Description	New Name
Ledger_builder_controller	Maintains locked Full_state and forks of potential future Full_states	Full_state_frontier
Proposer	Proposes new blocks	"
Snark_worker	Generates Transaction_works	Snarker
Prover	Proves Full_state_transitions	"
Verifier	Verifies Full_state_transition_snarks	"
Micro_client	A node which only tracks State_summary a limited number of account balances	"

Drawbacks

This may cause some initial headache while the development team gets used to the new vocabulary.

Rationale and alternatives

There are many alternative naming patterns that we could choose. The important thing is that we all come to consensus as a team with something we all like (or, if that's impossible, at least something the majority like and the remaining don't hate).