From 50e7dfde90e82c3e966224d75c04e0734409a86e Mon Sep 17 00:00:00 2001
From: aaronbuchwald <aaron.buchwald56@gmail.com>
Date: Tue, 19 Jul 2022 09:27:42 -0400
Subject: [PATCH] Add comments to block fee handling (#856)

---
 consensus/dummy/consensus.go | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/consensus/dummy/consensus.go b/consensus/dummy/consensus.go
index 77720a0791..3cdf42217e 100644
--- a/consensus/dummy/consensus.go
+++ b/consensus/dummy/consensus.go
@@ -287,7 +287,7 @@ func (self *DummyEngine) verifyBlockFee(
 		totalBlockFee.Add(totalBlockFee, extraStateChangeContribution)
 	}
 
-	// Calculate the total excess over the base fee that was paid towards the block fee
+	// Calculate the total excess (denominated in AVAX) over the base fee that was paid towards the block fee
 	for i, receipt := range receipts {
 		// Each transaction contributes the excess over the baseFee towards the totalBlockFee
 		// This should be equivalent to the sum of the "priority fees" within EIP-1559.
@@ -295,11 +295,19 @@ func (self *DummyEngine) verifyBlockFee(
 		if err != nil {
 			return err
 		}
+		// Multiply the [txFeePremium] by the gasUsed in the transaction since this gives the total AVAX that was paid
+		// above the amount required if the transaction had simply paid the minimum base fee for the block.
+		//
+		// Ex. LegacyTx paying a gas price of 100 gwei for 1M gas in a block with a base fee of 10 gwei.
+		// Total Fee = 100 gwei * 1M gas
+		// Minimum Fee = 10 gwei * 1M gas (minimum fee that would have been accepted for this transaction)
+		// Fee Premium = 90 gwei
+		// Total Overpaid = 90 gwei * 1M gas
 		blockFeeContribution.Mul(txFeePremium, gasUsed.SetUint64(receipt.GasUsed))
 		totalBlockFee.Add(totalBlockFee, blockFeeContribution)
 	}
 	// Calculate how much gas the [totalBlockFee] would purchase at the price level
-	// set by this block.
+	// set by the base fee of this block.
 	blockGas := new(big.Int).Div(totalBlockFee, baseFee)
 
 	// Require that the amount of gas purchased by the effective tips within the block, [blockGas],
@@ -343,6 +351,8 @@ func (self *DummyEngine) Finalize(chain consensus.ChainHeaderReader, block *type
 		if chain.Config().IsApricotPhase5(new(big.Int).SetUint64(block.Time())) {
 			blockGasCostStep = ApricotPhase5BlockGasCostStep
 		}
+		// Calculate the expected blockGasCost for this block.
+		// Note: this is a deterministic transtion that defines an exact block fee for this block.
 		blockGasCost := calcBlockGasCost(
 			ApricotPhase4TargetBlockRate,
 			ApricotPhase4MinBlockGasCost,
@@ -351,9 +361,11 @@ func (self *DummyEngine) Finalize(chain consensus.ChainHeaderReader, block *type
 			parent.BlockGasCost,
 			parent.Time, block.Time(),
 		)
+		// Verify the BlockGasCost set in the header matches the calculated value.
 		if blockBlockGasCost := block.BlockGasCost(); blockBlockGasCost == nil || !blockBlockGasCost.IsUint64() || blockBlockGasCost.Cmp(blockGasCost) != 0 {
 			return fmt.Errorf("invalid blockGasCost: have %d, want %d", blockBlockGasCost, blockGasCost)
 		}
+		// Verify the block fee was paid.
 		if err := self.verifyBlockFee(
 			block.BaseFee(),
 			block.BlockGasCost(),
@@ -390,6 +402,7 @@ func (self *DummyEngine) FinalizeAndAssemble(chain consensus.ChainHeaderReader,
 		if chain.Config().IsApricotPhase5(new(big.Int).SetUint64(header.Time)) {
 			blockGasCostStep = ApricotPhase5BlockGasCostStep
 		}
+		// Calculate the required block gas cost for this block.
 		header.BlockGasCost = calcBlockGasCost(
 			ApricotPhase4TargetBlockRate,
 			ApricotPhase4MinBlockGasCost,
@@ -398,6 +411,7 @@ func (self *DummyEngine) FinalizeAndAssemble(chain consensus.ChainHeaderReader,
 			parent.BlockGasCost,
 			parent.Time, header.Time,
 		)
+		// Verify that this block covers the block fee.
 		if err := self.verifyBlockFee(
 			header.BaseFee,
 			header.BlockGasCost,