📝 Add docstrings to

core/genesis.go

@@ -789,7 +789,12 @@ func DefaultHoleskyGenesisBlock() *Genesis {
 	}
 }
 
-// DeveloperGenesisBlock returns the 'geth --dev' genesis block.
+// DeveloperGenesisBlock creates a genesis block specification for the developer network ("geth --dev" mode) with precompiled contracts, pre-deployed system contracts, and an optional pre-funded faucet account.
+// 
+// The returned genesis includes all standard precompiles, system contracts (such as BeaconRoots, HistoryStorage, WithdrawalQueue, ConsolidationQueue, and GasStation), and sets their initial code, nonce, and balance. If a faucet address is provided, it is pre-funded with a large balance for development purposes.
+// 
+// gasLimit specifies the block gas limit for the genesis block.
+// faucet, if non-nil, is the address to be pre-funded in the genesis allocation.
 func DeveloperGenesisBlock(gasLimit uint64, faucet *common.Address) *Genesis {
 	// Override the default period to the user requested one
 	config := *params.AllDevChainProtocolChanges

core/state_transition.go

@@ -173,7 +173,9 @@ type Message struct {
 	IsGaslessTx    bool                 // IsGaslessTx indicates the message is a gasless transaction.
 }
 
-// TransactionToMessage converts a transaction into a Message.
+// TransactionToMessage constructs a Message from a transaction, extracting all relevant fields and computing the sender address.
+// If a base fee is provided, it sets the gas price to the effective gas price based on the tip and fee cap.
+// Returns the resulting Message and any error encountered while deriving the sender address.
 func TransactionToMessage(tx *types.Transaction, s types.Signer, baseFee *big.Int) (*Message, error) {
 	msg := &Message{
 		Nonce:                 tx.Nonce(),
@@ -511,7 +513,8 @@ type GasStationStorageSlots struct {
 // calculateGasStationSlots computes the storage slot hashes for a specific
 // registered contract within the GasStation's `contracts` mapping.
 // It returns the base slot for the struct (holding packed fields), the slot for credits,
-// the slot for whitelistEnabled, and the base slot for the nested whitelist mapping.
+// CalculateGasStationSlots computes the storage slot hashes for a registered contract within the GasStation contract's mapping.
+// It returns the struct base slot, credits slot, whitelist enabled slot, and the base slot for the nested whitelist mapping for the given contract address.
 func CalculateGasStationSlots(registeredContractAddress common.Address) GasStationStorageSlots {
 	gasStationStorageSlots := GasStationStorageSlots{}
 	// The 'contracts' mapping is the first state variable, so its base slot is 0.

core/txpool/legacypool/legacypool.go

@@ -270,7 +270,8 @@ type txpoolResetRequest struct {
 }
 
 // New creates a new transaction pool to gather, sort and filter inbound
-// transactions from the network.
+// New creates and initializes a new LegacyPool for managing Ethereum transactions.
+// It sets up internal structures, applies configuration sanitization, and prepares the pool for transaction processing.
 func New(config Config, chain BlockChain) *LegacyPool {
 	// Sanitize the input to ensure no vulnerable gas prices are set
 	config = (&config).sanitize()

core/txpool/validation.go

@@ -80,7 +80,9 @@ type ValidationFunction func(tx *types.Transaction, head *types.Header, signer t
 // (balance, nonce, etc).
 //
 // This check is public to allow different transaction pools to check the basic
-// rules without duplicating code and running the risk of missed updates.
+// ValidateTransaction performs stateless validation of a transaction against consensus and pool-specific rules.
+//
+// It checks transaction type support, size limits, protocol activation status, gas and fee constraints, signature validity, and intrinsic gas requirements. Special handling is included for blob and set code transactions, as well as for gasless transactions, which bypass the minimum tip requirement. Returns a detailed error describing the first validation failure encountered.
 func ValidateTransaction(tx *types.Transaction, head *types.Header, signer types.Signer, opts *ValidationOptions) error {
 	// No unauthenticated deposits allowed in the transaction pool.
 	// This is for spam protection, not consensus,
@@ -260,6 +262,9 @@ type ValidationOptionsWithState struct {
 	PendingCreditUsage func(contractAddr common.Address) *big.Int
 }
 
+// validateGaslessTx performs stateful validation of a gasless transaction.
+// It checks that the recipient contract is registered and active in the GasStation contract, verifies sufficient available credits (including pending usage) to cover the transaction's gas, and, if whitelisting is enabled, ensures the sender is whitelisted.
+// Returns an error if any validation fails.
 func validateGaslessTx(tx *types.Transaction, from common.Address, opts *ValidationOptionsWithState) error {
 	if tx.To() == nil {
 		return fmt.Errorf("gasless txn must have a valid to address")
@@ -340,7 +345,11 @@ func validateGaslessTx(tx *types.Transaction, from common.Address, opts *Validat
 // is valid according to the pool's internal state checks (balance, nonce, gaps).
 //
 // This check is public to allow different transaction pools to check the stateful
-// rules without duplicating code and running the risk of missed updates.
+// ValidateTransactionWithState performs stateful validation of a transaction against the current account state and pool constraints.
+//
+// It checks that the transaction nonce is valid and does not create gaps, verifies sufficient account balance for transaction costs (including queued transactions and replacements), and enforces per-account transaction slot limits if configured. For gasless transactions, it delegates to gasless-specific validation and skips balance checks.
+//
+// Returns an error if the transaction fails any stateful validation rule.
 func ValidateTransactionWithState(tx *types.Transaction, signer types.Signer, opts *ValidationOptionsWithState) error {
 	// Ensure the transaction adheres to nonce ordering
 	from, err := types.Sender(signer, tx) // already validated (and cached), but cleaner to check

miner/ordering.go

@@ -35,7 +35,8 @@ type txWithMinerFee struct {
 
 // newTxWithMinerFee creates a wrapped transaction, calculating the effective
 // miner gasTipCap if a base fee is provided.
-// Returns error in case of a negative effective miner gasTipCap.
+// newTxWithMinerFee calculates the effective miner fee for a transaction, considering the base fee unless the transaction is gasless.
+// Returns a txWithMinerFee containing the transaction, sender, and computed miner fee, or an error if the gas fee cap is below the base fee or the effective tip is negative.
 func newTxWithMinerFee(tx *txpool.LazyTransaction, from common.Address, baseFee *uint256.Int) (*txWithMinerFee, error) {
 	tip := new(uint256.Int).Set(tx.GasTipCap)
 	// This func is called on all pending txns in the txpool to set the order by fees