Welcome

1
// eth/catalyst/api.go  (inside forkchoiceUpdated)
2

3
if payloadAttributes != nil {
4
    args := &miner.BuildPayloadArgs{
5
        Parent:       update.HeadBlockHash,
6
        Timestamp:    payloadAttributes.Timestamp,
7
        FeeRecipient: payloadAttributes.SuggestedFeeRecipient,
8
        Random:       payloadAttributes.Random,
9
        Withdrawals:  payloadAttributes.Withdrawals,
10
        BeaconRoot:   payloadAttributes.BeaconRoot,
11
        Version:      payloadVersion,
12
    }
13
    id := args.Id()
14
    payload, err := api.eth.Miner().BuildPayload(args, payloadWitness)
15
    if err != nil {
16
        return valid(nil), engine.InvalidPayloadAttributes.With(err)
17
    }
18
    api.localBlocks.put(id, payload)
19
    return valid(&id), nil
20
}

1
// miner/payload_building.go  (simplified)
2

3
func (miner *Miner) buildPayload(args *BuildPayloadArgs, witness bool) (*Payload, error) {
4
    // 1. Build an empty block immediately (no transactions)
5
    emptyParams := &generateParams{
6
        timestamp:   args.Timestamp,
7
        forceTime:   true,
8
        parentHash:  args.Parent,
9
        coinbase:    args.FeeRecipient,
10
        random:      args.Random,
11
        withdrawals: args.Withdrawals,
12
        beaconRoot:  args.BeaconRoot,
13
        noTxs:       true,
14
    }
15
    empty := miner.generateWork(emptyParams, witness)
16
    if empty.err != nil {
17
        return nil, empty.err
18
    }
19
    payload := newPayload(empty.block, empty.requests, empty.witness, args.Id())
20

21
    // 2. In a background goroutine, repeatedly rebuild with transactions
22
    go func() {
23
        timer := time.NewTimer(0) // fire immediately for first build
24
        endTimer := time.NewTimer(time.Second * 12) // slot timeout
25

26
        fullParams := &generateParams{ /* same as above, but noTxs: false */ }
27

28
        for {
29
            select {
30
            case <-timer.C:
31
                r := miner.generateWork(fullParams, witness)
32
                if r.err == nil {
33
                    payload.update(r, ...)
34
                }
35
                timer.Reset(miner.config.Recommit)
36
            case <-payload.stop:
37
                return // CL called GetPayload
38
            case <-endTimer.C:
39
                return // slot expired (12s)
40
            }
41
        }
42
    }()
43
    return payload, nil
44
}

1
// miner/worker.go  (simplified)
2

3
func (miner *Miner) prepareWork(genParams *generateParams, witness bool) (*environment, error) {
4
    parent := miner.chain.CurrentBlock()
5
    if genParams.parentHash != (common.Hash{}) {
6
        block := miner.chain.GetBlockByHash(genParams.parentHash)
7
        parent = block.Header()
8
    }
9
    // Construct block header
10
    header := &types.Header{
11
        ParentHash: parent.Hash(),
12
        Number:     new(big.Int).Add(parent.Number, common.Big1),
13
        GasLimit:   core.CalcGasLimit(parent.GasLimit, miner.config.GasCeil),
14
        Time:       timestamp,
15
        Coinbase:   genParams.coinbase,
16
    }
17
    // Set EIP-1559 base fee
18
    if miner.chainConfig.IsLondon(header.Number) {
19
        header.BaseFee = eip1559.CalcBaseFee(miner.chainConfig, parent)
20
    }
21
    // Let the consensus engine set its fields (e.g., difficulty = 0 for PoS)
22
    miner.engine.Prepare(miner.chain, header)
23

24
    // Set Cancun fields (blob gas, beacon root)
25
    if miner.chainConfig.IsCancun(header.Number, header.Time) {
26
        excessBlobGas := eip4844.CalcExcessBlobGas(miner.chainConfig, parent, timestamp)
27
        header.BlobGasUsed = new(uint64)
28
        header.ExcessBlobGas = &excessBlobGas
29
        header.ParentBeaconRoot = genParams.beaconRoot
30
    }
31
    // Create execution environment: parent state + EVM instance
32
    env, err := miner.makeEnv(parent, header, genParams.coinbase, witness)
33

34
    // Run pre-block system calls
35
    if header.ParentBeaconRoot != nil {
36
        core.ProcessBeaconBlockRoot(*header.ParentBeaconRoot, env.evm) // EIP-4788
37
    }
38
    if miner.chainConfig.IsPrague(header.Number, header.Time) {
39
        core.ProcessParentBlockHash(header.ParentHash, env.evm)        // EIP-2935
40
    }
41
    return env, nil
42
}

1
// miner/worker.go  (simplified)
2

3
func (miner *Miner) fillTransactions(interrupt *atomic.Int32, env *environment) error {
4
    tip := miner.config.GasPrice
5

6
    // Build a filter for the pool query
7
    filter := txpool.PendingFilter{
8
        MinTip: uint256.MustFromBig(tip),
9
    }
10
    if env.header.BaseFee != nil {
11
        filter.BaseFee = uint256.MustFromBig(env.header.BaseFee)
12
    }
13
    if env.header.ExcessBlobGas != nil {
14
        filter.BlobFee = uint256.MustFromBig(eip4844.CalcBlobFee(miner.chainConfig, env.header))
15
    }
16
    // Osaka adds per-tx gas cap and blob version filtering
17
    if miner.chainConfig.IsOsaka(env.header.Number, env.header.Time) {
18
        filter.GasLimitCap = params.MaxTxGas
19
        filter.BlobVersion = types.BlobSidecarVersion1
20
    }
21
    // Fetch plain and blob transactions separately
22
    filter.BlobTxs = false
23
    pendingPlainTxs := miner.txpool.Pending(filter)
24

25
    filter.BlobTxs = true
26
    pendingBlobTxs := miner.txpool.Pending(filter)
27

28
    // Split priority addresses out of the normal maps
29
    prioPlainTxs := make(map[common.Address][]*txpool.LazyTransaction)
30
    prioBlobTxs  := make(map[common.Address][]*txpool.LazyTransaction)
31
    for _, account := range miner.prio {
32
        if txs := pendingPlainTxs[account]; len(txs) > 0 {
33
            delete(pendingPlainTxs, account)
34
            prioPlainTxs[account] = txs
35
        }
36
        if txs := pendingBlobTxs[account]; len(txs) > 0 {
37
            delete(pendingBlobTxs, account)
38
            prioBlobTxs[account] = txs
39
        }
40
    }
41
    // Commit prioritized transactions first, then normal ones
42
    if len(prioPlainTxs) > 0 || len(prioBlobTxs) > 0 {
43
        plainTxs := newTransactionsByPriceAndNonce(env.signer, prioPlainTxs, env.header.BaseFee)
44
        blobTxs := newTransactionsByPriceAndNonce(env.signer, prioBlobTxs, env.header.BaseFee)
45
        miner.commitTransactions(env, plainTxs, blobTxs, interrupt)
46
    }
47
    if len(pendingPlainTxs) > 0 || len(pendingBlobTxs) > 0 {
48
        plainTxs := newTransactionsByPriceAndNonce(env.signer, pendingPlainTxs, env.header.BaseFee)
49
        blobTxs := newTransactionsByPriceAndNonce(env.signer, pendingBlobTxs, env.header.BaseFee)
50
        miner.commitTransactions(env, plainTxs, blobTxs, interrupt)
51
    }
52
    return nil
53
}

1
// miner/worker.go  (simplified)
2

3
func (miner *Miner) commitTransactions(env *environment,
4
    plainTxs, blobTxs *transactionsByPriceAndNonce, interrupt *atomic.Int32) error {
5
    if env.gasPool == nil {
6
        env.gasPool = new(core.GasPool).AddGas(env.header.GasLimit)
7
    }
8
    for {
9
        // Check for interrupts (new head, timeout, recommit)
10
        if signal := interrupt.Load(); signal != commitInterruptNone {
11
            return signalToErr(signal)
12
        }
13
        // Stop if not enough gas for any transaction
14
        if env.gasPool.Gas() < params.TxGas {
15
            break
16
        }
17
        // Pick the higher-tipping transaction between plain and blob heaps
18
        pltx, ptip := plainTxs.Peek()
19
        bltx, btip := blobTxs.Peek()
20

21
        var ltx *txpool.LazyTransaction
22
        var txs *transactionsByPriceAndNonce
23
        // ... select whichever has the higher tip ...
24

25
        // Check gas budget, blob budget, block size
26
        if env.gasPool.Gas() < ltx.Gas { txs.Pop(); continue }
27
        if !env.txFitsSize(tx)          { break }
28

29
        // Execute the transaction
30
        env.state.SetTxContext(tx.Hash(), env.tcount)
31
        err := miner.commitTransaction(env, tx)
32

33
        switch {
34
        case errors.Is(err, core.ErrNonceTooLow):
35
            txs.Shift() // stale nonce, try next from same account
36
        case err == nil:
37
            txs.Shift() // success, advance to next from same account
38
        default:
39
            txs.Pop()   // fatal error, skip entire account
40
        }
41
    }
42
    return nil
43
}

1
// miner/worker.go  (inside generateWork)
2

3
if miner.chainConfig.IsPrague(work.header.Number, work.header.Time) {
4
    requests = [][]byte{}
5
    // EIP-6110: parse deposit logs from executed transactions
6
    core.ParseDepositLogs(&requests, allLogs, miner.chainConfig)
7
    // EIP-7002: process withdrawal requests from the system contract
8
    core.ProcessWithdrawalQueue(&requests, work.evm)
9
    // EIP-7251: process consolidation requests from the system contract
10
    core.ProcessConsolidationQueue(&requests, work.evm)
11
}
12
if requests != nil {
13
    reqHash := types.CalcRequestsHash(requests)
14
    work.header.RequestsHash = &reqHash
15
}

1
// miner/worker.go  (inside generateWork)
2

3
body := types.Body{Transactions: work.txs, Withdrawals: genParam.withdrawals}
4
block, err := miner.engine.FinalizeAndAssemble(miner.chain, work.header, work.state, &body, work.receipts)

1
// core/block_validator.go  (simplified)
2

3
func (v *BlockValidator) ValidateBody(block *types.Block) error {
4
    // EIP-7934: block size cap (Osaka)
5
    if v.config.IsOsaka(block.Number(), block.Time()) && block.Size() > params.MaxBlockSize {
6
        return ErrBlockOversized
7
    }
8
    // Already imported?
9
    if v.bc.HasBlockAndState(block.Hash(), block.NumberU64()) {
10
        return ErrKnownBlock
11
    }
12
    // Uncle validation (must be empty post-merge)
13
    v.bc.engine.VerifyUncles(v.bc, block)
14

15
    // Transaction root matches header
16
    if hash := types.DeriveSha(block.Transactions(), ...); hash != header.TxHash { ... }
17

18
    // Withdrawals root matches header (post-Shanghai)
19
    if header.WithdrawalsHash != nil {
20
        if hash := types.DeriveSha(block.Withdrawals(), ...); hash != *header.WithdrawalsHash { ... }
21
    }
22
    // Blob gas used matches actual blob count
23
    if header.BlobGasUsed != nil {
24
        if blobs * BlobTxBlobGasPerBlob != *header.BlobGasUsed { ... }
25
    }
26
    // Blob txs must not have sidecars attached in-block
27
    for i, tx := range block.Transactions() {
28
        if tx.BlobTxSidecar() != nil { ... }
29
    }
30
    // Parent must exist
31
    if !v.bc.HasBlockAndState(block.ParentHash(), block.NumberU64()-1) { ... }
32

33
    return nil
34
}

1
// core/block_validator.go  (simplified)
2

3
func (v *BlockValidator) ValidateState(block *types.Block, statedb *state.StateDB,
4
    res *ProcessResult, stateless bool) error {
5
    // Gas used must match header
6
    if block.GasUsed() != res.GasUsed { ... }
7

8
    // Bloom filter must match
9
    if types.MergeBloom(res.Receipts) != header.Bloom { ... }
10

11
    // Receipt root must match header
12
    if types.DeriveSha(res.Receipts, ...) != header.ReceiptHash { ... }
13

14
    // Requests hash must match header (Prague)
15
    if header.RequestsHash != nil {
16
        if types.CalcRequestsHash(res.Requests) != *header.RequestsHash { ... }
17
    }
18
    // State root must match header
19
    if statedb.IntermediateRoot(...) != header.Root { ... }
20

21
    return nil
22
}