rename and document balance change reasons

cmd/evm/internal/t8ntool/execution.go

@@ -316,9 +316,9 @@ func (pre *Prestate) Apply(vmConfig vm.Config, chainConfig *params.ChainConfig,
 			reward.Sub(reward, new(big.Int).SetUint64(ommer.Delta))
 			reward.Mul(reward, blockReward)
 			reward.Div(reward, big.NewInt(8))
-			statedb.AddBalance(ommer.Address, reward, state.BalanceChangeRewardMineUncle)
+			statedb.AddBalance(ommer.Address, reward, state.BalanceIncreaseRewardMineUncle)
 		}
-		statedb.AddBalance(pre.Env.Coinbase, minerReward, state.BalanceChangeRewardMineBlock)
+		statedb.AddBalance(pre.Env.Coinbase, minerReward, state.BalanceIncreaseRewardMineBlock)
 	}
 	// Apply withdrawals
 	for _, w := range pre.Env.Withdrawals {
@@ -367,7 +367,7 @@ func MakePreState(db ethdb.Database, accounts core.GenesisAlloc) *state.StateDB
 	for addr, a := range accounts {
 		statedb.SetCode(addr, a.Code)
 		statedb.SetNonce(addr, a.Nonce)
-		statedb.SetBalance(addr, a.Balance, state.BalanceChangeGenesisBalance)
+		statedb.SetBalance(addr, a.Balance, state.BalanceIncreaseGenesisBalance)
 		for k, v := range a.Storage {
 			statedb.SetState(addr, k, v)
 		}

consensus/ethash/consensus.go

@@ -586,10 +586,10 @@ func accumulateRewards(config *params.ChainConfig, stateDB *state.StateDB, heade
 		r.Sub(r, header.Number)
 		r.Mul(r, blockReward)
 		r.Div(r, big8)
-		stateDB.AddBalance(uncle.Coinbase, r, state.BalanceChangeRewardMineUncle)
+		stateDB.AddBalance(uncle.Coinbase, r, state.BalanceIncreaseRewardMineUncle)
 
 		r.Div(blockReward, big32)
 		reward.Add(reward, r)
 	}
-	stateDB.AddBalance(header.Coinbase, reward, state.BalanceChangeRewardMineBlock)
+	stateDB.AddBalance(header.Coinbase, reward, state.BalanceIncreaseRewardMineBlock)
 }

consensus/misc/dao.go

@@ -80,7 +80,7 @@ func ApplyDAOHardFork(statedb *state.StateDB) {
 
 	// Move every DAO account and extra-balance account funds into the refund contract
 	for _, addr := range params.DAODrainList() {
-		statedb.AddBalance(params.DAORefundContract, statedb.GetBalance(addr), state.BalanceChangeDaoRefundContract)
+		statedb.AddBalance(params.DAORefundContract, statedb.GetBalance(addr), state.BalanceIncreaseDaoContract)
-		statedb.SetBalance(addr, new(big.Int), state.BalanceChangeDaoAdjustBalance)
+		statedb.SetBalance(addr, new(big.Int), state.BalanceDecreaseDaoAccount)
 	}
 }

core/genesis.go

@@ -142,7 +142,7 @@ func (ga *GenesisAlloc) hash(isVerkle bool) (common.Hash, error) {
 	}
 	for addr, account := range *ga {
 		if account.Balance != nil {
-			statedb.AddBalance(addr, account.Balance, state.BalanceChangeGenesisBalance)
+			statedb.AddBalance(addr, account.Balance, state.BalanceIncreaseGenesisBalance)
 		}
 		statedb.SetCode(addr, account.Code)
 		statedb.SetNonce(addr, account.Nonce)
@@ -165,7 +165,7 @@ func (ga *GenesisAlloc) flush(db ethdb.Database, triedb *trie.Database, blockhas
 		if account.Balance != nil {
 			// This is not actually logged via tracer because OnGenesisBlock
 			// already captures the allocations.
-			statedb.AddBalance(addr, account.Balance, state.BalanceChangeGenesisBalance)
+			statedb.AddBalance(addr, account.Balance, state.BalanceIncreaseGenesisBalance)
 		}
 		statedb.SetCode(addr, account.Code)
 		statedb.SetNonce(addr, account.Nonce)

core/state/metadata.go

@@ -21,31 +21,48 @@ package state
 type BalanceChangeReason byte
 
 const (
-	BalanceChangeUnspecified          BalanceChangeReason = 0
+	BalanceChangeUnspecified BalanceChangeReason = 0
-	BalanceChangeRewardMineUncle      BalanceChangeReason = 1
+
-	BalanceChangeRewardMineBlock      BalanceChangeReason = 2
+	// Issuance
-	BalanceChangeDaoRefundContract    BalanceChangeReason = 3
+	// BalanceIncreaseRewardMineUncle is a reward for mining an uncle block.
-	BalanceChangeDaoAdjustBalance     BalanceChangeReason = 4
+	BalanceIncreaseRewardMineUncle BalanceChangeReason = 1
-	BalanceChangeTransfer             BalanceChangeReason = 5
+	// BalanceIncreaseRewardMineBlock is a reward for mining a block.
-	BalanceChangeGenesisBalance       BalanceChangeReason = 6
+	BalanceIncreaseRewardMineBlock BalanceChangeReason = 2
-	BalanceChangeGasBuy               BalanceChangeReason = 7
+	// BalanceIncreaseWithdrawal is ether withdrawn from the beacon chain.
-	BalanceChangeRewardTransactionFee BalanceChangeReason = 8
+	BalanceChangeWithdrawal BalanceChangeReason = 3
-	BalanceChangeGasRefund            BalanceChangeReason = 9
+	// BalanceIncreaseGenesisBalance is ether allocated at the genesis block.
-	BalanceChangeTouchAccount         BalanceChangeReason = 10
+	BalanceIncreaseGenesisBalance BalanceChangeReason = 4
-	// TODO: rename (debit, credit)
+
-	// BalanceChangeSuicideRefund is added to the recipient as indicated by a selfdestructing account.
+	// Transaction fees
-	BalanceChangeSuicideRefund BalanceChangeReason = 11
+	// BalanceIncreaseRewardTransactionFee is the transaction tip increasing block builder's balance.
-	// BalanceChangeSuicideWithdraw is deducted from a contract due to self-destruct.
+	BalanceIncreaseRewardTransactionFee BalanceChangeReason = 5
+	// BalanceDecreaseGasBuy is spent to purchase gas for execution a transaction.
+	// Part of this gas will be burnt as per EIP-1559 rules.
+	BalanceDecreaseGasBuy BalanceChangeReason = 6
+	// BalanceIncreaseGasReturn is ether returned for unused gas at the end of execution.
+	BalanceIncreaseGasReturn BalanceChangeReason = 7
+
+	// DAO fork
+	// BalanceIncreaseDaoContract is ether sent to the DAO refund contract.
+	BalanceIncreaseDaoContract BalanceChangeReason = 8
+	// BalanceDecreaseDaoAccount is ether taken from a DAO account to be moved to the refund contract.
+	BalanceDecreaseDaoAccount BalanceChangeReason = 9
+
+	// BalanceChangeTransfer is ether transfered via a call.
+	// it is a decrease for the sender and an increase for the recipient.
+	BalanceChangeTransfer BalanceChangeReason = 10
+	// BalanceChangeTouchAccount is a transfer of zero value. It is only there to
+	// touch-create an account.
+	BalanceChangeTouchAccount BalanceChangeReason = 11
+
+	// BalanceIncreaseSelfdestruct is added to the recipient as indicated by a selfdestructing account.
+	BalanceIncreaseSelfdestruct BalanceChangeReason = 12
+	// BalanceDecreaseSelfdestruct is deducted from a contract due to self-destruct.
 	// This can happen either at the point of self-destruction, or at the end of the tx
 	// if ether was sent to contract post-selfdestruct.
-	BalanceChangeSuicideWithdraw BalanceChangeReason = 12
+	BalanceDecreaseSelfdestruct BalanceChangeReason = 13
-	// BalanceChangeBurn accounts for:
+	// BalanceDecreaseSelfdestructBurn is ether that is sent to an already self-destructed
-	// - EIP-1559 burnt fees
+	// account within the same tx (captured at end of tx).
-	// - ether that is sent to a self-destructed contract within the same tx (captured at end of tx)
+	// Note it doesn't account for a self-destruct which appoints itself as recipient.
-	// Note it doesn't account for a self-destruct which appoints same contract as recipient.
+	BalanceDecreaseSelfdestructBurn BalanceChangeReason = 14
-	BalanceChangeBurn BalanceChangeReason = 13
-	// BalanceChangeBurnRefund is refunded to an account at the end of transaction based on
-	// gas usage from the estimated burn amount.
-	BalanceChangeBurnRefund BalanceChangeReason = 14
-	BalanceChangeWithdrawal BalanceChangeReason = 15
 )

core/state/statedb.go

@@ -486,7 +486,7 @@ func (s *StateDB) SelfDestruct(addr common.Address) {
 		prevbalance: prev,
 	})
 	if s.logger != nil {
-		s.logger.OnBalanceChange(addr, prev, n, BalanceChangeSuicideWithdraw)
+		s.logger.OnBalanceChange(addr, prev, n, BalanceDecreaseSelfdestruct)
 	}
 	stateObject.markSelfdestructed()
 	stateObject.data.Balance = n
@@ -879,7 +879,7 @@ func (s *StateDB) Finalise(deleteEmptyObjects bool) {
 
 			// If ether was sent to account post-selfdestruct it is burnt.
 			if bal := obj.Balance(); bal.Sign() != 0 && s.logger != nil {
-				s.logger.OnBalanceChange(obj.address, bal, new(big.Int), BalanceChangeBurn)
+				s.logger.OnBalanceChange(obj.address, bal, new(big.Int), BalanceDecreaseSelfdestructBurn)
 			}
 			// We need to maintain account deletions explicitly (will remain
 			// set indefinitely). Note only the first occurred self-destruct

core/state_transition.go

@@ -270,7 +270,7 @@ func (st *StateTransition) buyGas() error {
 	st.gasRemaining += st.msg.GasLimit
 
 	st.initialGas = st.msg.GasLimit
-	st.state.SubBalance(st.msg.From, mgval, state.BalanceChangeGasBuy)
+	st.state.SubBalance(st.msg.From, mgval, state.BalanceDecreaseGasBuy)
 	return nil
 }
 
@@ -445,7 +445,7 @@ func (st *StateTransition) TransitionDb() (*ExecutionResult, error) {
 	} else {
 		fee := new(big.Int).SetUint64(st.gasUsed())
 		fee.Mul(fee, effectiveTip)
-		st.state.AddBalance(st.evm.Context.Coinbase, fee, state.BalanceChangeRewardTransactionFee)
+		st.state.AddBalance(st.evm.Context.Coinbase, fee, state.BalanceIncreaseRewardTransactionFee)
 	}
 
 	return &ExecutionResult{
@@ -471,7 +471,7 @@ func (st *StateTransition) refundGas(refundQuotient uint64) uint64 {
 
 	// Return ETH for remaining gas, exchanged at the original rate.
 	remaining := new(big.Int).Mul(new(big.Int).SetUint64(st.gasRemaining), st.msg.GasPrice)
-	st.state.AddBalance(st.msg.From, remaining, state.BalanceChangeGasRefund)
+	st.state.AddBalance(st.msg.From, remaining, state.BalanceIncreaseGasReturn)
 
 	if st.evm.Config.Tracer != nil && st.gasRemaining > 0 {
 		st.evm.Config.Tracer.OnGasChange(st.gasRemaining, 0, vm.GasChangeTxLeftOverReturned)

core/vm/instructions.go

@@ -855,7 +855,7 @@ func opSelfdestruct(pc *uint64, interpreter *EVMInterpreter, scope *ScopeContext
 	}
 	beneficiary := scope.Stack.pop()
 	balance := interpreter.evm.StateDB.GetBalance(scope.Contract.Address())
-	interpreter.evm.StateDB.AddBalance(beneficiary.Bytes20(), balance, state.BalanceChangeSuicideRefund)
+	interpreter.evm.StateDB.AddBalance(beneficiary.Bytes20(), balance, state.BalanceIncreaseSelfdestruct)
 	interpreter.evm.StateDB.SelfDestruct(scope.Contract.Address())
 	if tracer := interpreter.evm.Config.Tracer; tracer != nil {
 		tracer.CaptureEnter(SELFDESTRUCT, scope.Contract.Address(), beneficiary.Bytes20(), []byte{}, 0, balance)
@@ -870,8 +870,8 @@ func opSelfdestruct6780(pc *uint64, interpreter *EVMInterpreter, scope *ScopeCon
 	}
 	beneficiary := scope.Stack.pop()
 	balance := interpreter.evm.StateDB.GetBalance(scope.Contract.Address())
-	interpreter.evm.StateDB.SubBalance(scope.Contract.Address(), balance, state.BalanceChangeSuicideWithdraw)
+	interpreter.evm.StateDB.SubBalance(scope.Contract.Address(), balance, state.BalanceDecreaseSelfdestruct)
-	interpreter.evm.StateDB.AddBalance(beneficiary.Bytes20(), balance, state.BalanceChangeSuicideRefund)
+	interpreter.evm.StateDB.AddBalance(beneficiary.Bytes20(), balance, state.BalanceIncreaseSelfdestruct)
 	interpreter.evm.StateDB.Selfdestruct6780(scope.Contract.Address())
 	if tracer := interpreter.evm.Config.Tracer; tracer != nil {
 		tracer.CaptureEnter(SELFDESTRUCT, scope.Contract.Address(), beneficiary.Bytes20(), []byte{}, 0, balance)