From cf50d2ad3ade8ee6bd37a835e9c29784762417fb Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Wed, 4 Jun 2025 22:35:48 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`feat/ga?= =?UTF-8?q?sless-system-clean`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @Sledro. * https://github.com/lightlink-network/ll-geth/pull/1#issuecomment-2940197358 The following files were modified: * `core/genesis.go` * `core/state_transition.go` * `core/txpool/legacypool/legacypool.go` * `core/txpool/validation.go` * `miner/ordering.go` --- core/genesis.go | 7 ++++++- core/state_transition.go | 7 +++++-- core/txpool/legacypool/legacypool.go | 3 ++- core/txpool/validation.go | 13 +++++++++++-- miner/ordering.go | 3 ++- 5 files changed, 26 insertions(+), 7 deletions(-) diff --git a/core/genesis.go b/core/genesis.go index 64b5dc1569..e27b588c23 100644 --- a/core/genesis.go +++ b/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 diff --git a/core/state_transition.go b/core/state_transition.go index c72520f92a..f2713de087 100644 --- a/core/state_transition.go +++ b/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. diff --git a/core/txpool/legacypool/legacypool.go b/core/txpool/legacypool/legacypool.go index 5027375667..b111566d0f 100644 --- a/core/txpool/legacypool/legacypool.go +++ b/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() diff --git a/core/txpool/validation.go b/core/txpool/validation.go index 0eb573c814..e95e097d85 100644 --- a/core/txpool/validation.go +++ b/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 diff --git a/miner/ordering.go b/miner/ordering.go index 38cca58f87..7d9326117a 100644 --- a/miner/ordering.go +++ b/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