miner: surface revoke error detail to builders

Author: flywukong

core/types/bid_block_permission.go

@@ -8,7 +8,7 @@ import (
 
 type BidBlockPermissionStatus struct {
 	Allowed   bool
-	Reason    string
+	Reason    string // err detail for auto revokes (InsertChain failure), or "manual" for admin revokes
 	BlockHash common.Hash
 	BlockNum  uint64
 	RevokedAt time.Time

miner/bid_block.go

@@ -162,15 +162,28 @@ func (w *worker) handleBidBlockResult(block *types.Block, task *task) {
 
 	w.mux.Post(core.NewSealedBlockEvent{Block: block})
 
-	// InsertChain: re-execute all transactions and verify stateRoot/receiptHash
+	// InsertChain re-executes all txs and validates fields the validator could
+	// not check at admission. Any mismatch is treated as builder dishonesty and
+	// revokes the builder for the rest of the UTC day. Categories caught here:
+	//   - Root          (post-execution state root)
+	//   - ReceiptHash   (post-execution receipts trie root)
+	//   - Bloom         (post-execution logs bloom)
+	//   - GasUsed       (cumulative gas consumed)
+	//   - Tx precheck failures (nonce, balance, signature, intrinsic gas, ...)
+	//   - System tx value / params (e.g. deposit value vs. SystemAddress balance)
+	//   - Blob sidecar checks (KZG proofs, blob hashes)
 	if _, err := w.chain.InsertChain(types.Blocks{block}); err != nil {
 		log.Error("[BID BLOCK VERIFY FAILED]",
 			"number", block.Number(),
 			"hash", hash,
+			"parentHash", block.ParentHash(),
+			"txs", len(block.Transactions()),
+			"gasUsed", block.GasUsed(),
+			"stateRoot", block.Root(),
+			"receiptHash", block.ReceiptHash(),
 			"builder", task.bidBlockInfo.builder,
-			"err", err,
-			"revokeReason", RevokeReasonInsertChainFailed)
-		w.permMgr.Revoke(task.bidBlockInfo.builder, RevokeReasonInsertChainFailed, hash, block.NumberU64())
+			"err", err)
+		w.permMgr.Revoke(task.bidBlockInfo.builder, fmt.Sprintf("InsertChain err: %v", err), hash, block.NumberU64())
 		bidBlockRevokeGauge.Inc(1)
 		return
 	}

miner/bid_block_permission.go

@@ -13,29 +13,16 @@ import (
 	"github.com/ethereum/go-ethereum/core/types"
 )
 
-// BidBlockRevokeReason classifies why a builder lost SendBidBlock permission.
-type BidBlockRevokeReason string
-
-const (
-	// RevokeReasonInsertChainFailed: the sealed BidBlock failed InsertChain.
-	// These are conditions the validator cannot check before re-execution and
-	// therefore depends on the builder to get right:
-	//   - Root          (post-execution state root)
-	//   - ReceiptHash   (post-execution receipts trie root)
-	//   - Bloom         (post-execution logs bloom)
-	//   - GasUsed       (cumulative gas consumed)
-	//   - Tx precheck failures (nonce, balance, signature, intrinsic gas, ...)
-	//   - System tx value / params (e.g. deposit value vs. SystemAddress balance)
-	//   - Blob sidecar checks (KZG proofs, blob hashes)
-	// Any mismatch is treated as builder dishonesty and revokes permission.
-	RevokeReasonInsertChainFailed BidBlockRevokeReason = "insertchain_failed"
-	RevokeReasonManual            BidBlockRevokeReason = "manual"
-)
+// RevokeReasonManual is the Reason value used when an operator manually revokes
+// a builder via SetAllowed. Automatic revokes always come from InsertChain
+// failures and carry the underlying error message as Reason directly — see the
+// auto-revoke call site in handleBidBlockResult for the conditions that trigger.
+const RevokeReasonManual = "manual"
 
 // BidBlockRevokeRecord holds one active revoke event.
 type BidBlockRevokeRecord struct {
 	RevokedAt time.Time
-	Reason    BidBlockRevokeReason
+	Reason    string // err detail for auto revokes (InsertChain failure), or RevokeReasonManual
 	BlockHash common.Hash
 	BlockNum  uint64
 }
@@ -67,9 +54,11 @@ func (m *BidBlockPermissionManager) IsAllowed(builder common.Address) bool {
 }
 
 // Revoke marks builder as denied for the remainder of the current UTC day.
+// reason is surfaced via GetBidBlockPermission RPC so builders can see specifics
+// (the InsertChain error text for auto revokes, or RevokeReasonManual for admin).
 func (m *BidBlockPermissionManager) Revoke(
 	builder common.Address,
-	reason BidBlockRevokeReason,
+	reason string,
 	blockHash common.Hash,
 	blockNum uint64,
 ) {
@@ -95,7 +84,7 @@ func (m *BidBlockPermissionManager) GetStatus(builder common.Address) types.BidB
 		return status
 	}
 	status.Allowed = false
-	status.Reason = string(rec.Reason)
+	status.Reason = rec.Reason
 	status.BlockHash = rec.BlockHash
 	status.BlockNum = rec.BlockNum
 	status.RevokedAt = rec.RevokedAt

miner/bid_block_permission_test.go

@@ -16,6 +16,11 @@ import (
 	"github.com/ethereum/go-ethereum/miner/minerconfig"
 )
 
+// testInsertChainReason is a placeholder used by tests where the specific
+// InsertChain error text doesn't matter — production passes
+// "InsertChain err: <err.Error()>" here.
+const testInsertChainReason = "InsertChain err: test"
+
 func getBidBlockPermissionRecord(m *BidBlockPermissionManager, builder common.Address) (BidBlockRevokeRecord, bool) {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
@@ -49,7 +54,7 @@ func TestBidBlockPermission_RevokeBlocks(t *testing.T) {
 	builder := common.HexToAddress("0x1")
 	hash := common.HexToHash("0xabc")
 
-	m.Revoke(builder, RevokeReasonInsertChainFailed, hash, 100)
+	m.Revoke(builder, testInsertChainReason, hash, 100)
 	if m.IsAllowed(builder) {
 		t.Fatal("revoked builder should not be allowed in same UTC day")
 	}
@@ -58,8 +63,8 @@ func TestBidBlockPermission_RevokeBlocks(t *testing.T) {
 	if !ok {
 		t.Fatal("record expected after Revoke")
 	}
-	if rec.Reason != RevokeReasonInsertChainFailed {
-		t.Fatalf("reason: got %s, want %s", rec.Reason, RevokeReasonInsertChainFailed)
+	if rec.Reason != testInsertChainReason {
+		t.Fatalf("reason: got %s, want %s", rec.Reason, testInsertChainReason)
 	}
 	if rec.BlockHash != hash {
 		t.Fatalf("blockHash: got %s, want %s", rec.BlockHash.Hex(), hash.Hex())
@@ -74,7 +79,7 @@ func TestBidBlockPermission_BuildersIndependent(t *testing.T) {
 	a := common.HexToAddress("0xa")
 	b := common.HexToAddress("0xb")
 
-	m.Revoke(a, RevokeReasonInsertChainFailed, common.Hash{}, 1)
+	m.Revoke(a, testInsertChainReason, common.Hash{}, 1)
 	if m.IsAllowed(a) {
 		t.Fatal("a should be revoked")
 	}
@@ -87,7 +92,7 @@ func TestBidBlockPermission_RevokeOverwritesSameDay(t *testing.T) {
 	m := NewBidBlockPermissionManager()
 	builder := common.HexToAddress("0x1")
 
-	m.Revoke(builder, RevokeReasonInsertChainFailed, common.HexToHash("0x1"), 1)
+	m.Revoke(builder, testInsertChainReason, common.HexToHash("0x1"), 1)
 	m.Revoke(builder, RevokeReasonManual, common.HexToHash("0x2"), 2)
 
 	rec, ok := getBidBlockPermissionRecord(m, builder)
@@ -110,7 +115,7 @@ func TestBidBlockPermission_LazyResetCrossDay(t *testing.T) {
 	day2 := day1.Add(24 * time.Hour)
 
 	setBidBlockPermissionClock(m, func() time.Time { return day1 })
-	m.Revoke(builder, RevokeReasonInsertChainFailed, common.Hash{}, 1)
+	m.Revoke(builder, testInsertChainReason, common.Hash{}, 1)
 	if m.IsAllowed(builder) {
 		t.Fatal("revoked on day1 should be blocked on day1")
 	}
@@ -130,7 +135,7 @@ func TestBidBlockPermission_SameDayBoundary(t *testing.T) {
 
 	near := time.Date(2026, 5, 8, 23, 59, 59, 0, time.UTC)
 	setBidBlockPermissionClock(m, func() time.Time { return near })
-	m.Revoke(builder, RevokeReasonInsertChainFailed, common.Hash{}, 1)
+	m.Revoke(builder, testInsertChainReason, common.Hash{}, 1)
 
 	justAfter := time.Date(2026, 5, 9, 0, 0, 1, 0, time.UTC)
 	setBidBlockPermissionClock(m, func() time.Time { return justAfter })
@@ -193,7 +198,7 @@ func TestBidBlockPermission_ConcurrentAccess(t *testing.T) {
 		wg.Add(3)
 		b := builders[i%len(builders)]
 		go func() { defer wg.Done(); m.IsAllowed(b) }()
-		go func() { defer wg.Done(); m.Revoke(b, RevokeReasonInsertChainFailed, common.Hash{}, 1) }()
+		go func() { defer wg.Done(); m.Revoke(b, testInsertChainReason, common.Hash{}, 1) }()
 		go func() { defer wg.Done(); getBidBlockPermissionRecord(m, b) }()
 	}
 	wg.Wait()
@@ -212,7 +217,7 @@ func TestBidBlockPermission_ActiveRevokeCount(t *testing.T) {
 
 	a := common.HexToAddress("0xa")
 	b := common.HexToAddress("0xb")
-	m.Revoke(a, RevokeReasonInsertChainFailed, common.Hash{}, 1)
+	m.Revoke(a, testInsertChainReason, common.Hash{}, 1)
 	m.Revoke(b, RevokeReasonManual, common.Hash{}, 2)
 
 	if got := m.ActiveRevokeCount(); got != 2 {
@@ -241,12 +246,12 @@ func TestBidBlockPermission_GetStatus(t *testing.T) {
 	}
 
 	hash := common.HexToHash("0xabc")
-	m.Revoke(builder, RevokeReasonInsertChainFailed, hash, 100)
+	m.Revoke(builder, testInsertChainReason, hash, 100)
 	status = m.GetStatus(builder)
 	if status.Allowed {
 		t.Fatal("revoked builder should not be allowed")
 	}
-	if status.Reason != string(RevokeReasonInsertChainFailed) {
+	if status.Reason != testInsertChainReason {
 		t.Fatalf("reason: got %s", status.Reason)
 	}
 	if status.BlockHash != hash || status.BlockNum != 100 || !status.RevokedAt.Equal(now) || !status.ResetAt.Equal(resetAt) {
@@ -266,7 +271,7 @@ func TestBidBlockAdmission_RevokedDoesNotConsumeQuota(t *testing.T) {
 	const blockNum uint64 = 100
 
 	b.builders[builder] = nil
-	permMgr.Revoke(builder, RevokeReasonInsertChainFailed, common.Hash{}, blockNum-1)
+	permMgr.Revoke(builder, testInsertChainReason, common.Hash{}, blockNum-1)
 
 	if !b.ExistBuilder(builder) {
 		t.Fatal("registered builder must pass ExistBuilder")
@@ -339,7 +344,7 @@ func TestMinerBidBlockPermission_UsesWorkerManager(t *testing.T) {
 	miner := &Miner{worker: &worker{permMgr: m}}
 	builder := common.HexToAddress("0x1")
 
-	m.Revoke(builder, RevokeReasonInsertChainFailed, common.Hash{}, 1)
+	m.Revoke(builder, testInsertChainReason, common.Hash{}, 1)
 	if miner.GetBidBlockPermission(builder).Allowed {
 		t.Fatal("miner should report worker revoke")
 	}
@@ -366,7 +371,7 @@ func TestBidBlockPermission_SetAllowed_Clear(t *testing.T) {
 	m := NewBidBlockPermissionManager()
 	builder := common.HexToAddress("0x1")
 
-	m.Revoke(builder, RevokeReasonInsertChainFailed, common.HexToHash("0xabc"), 100)
+	m.Revoke(builder, testInsertChainReason, common.HexToHash("0xabc"), 100)
 	m.SetAllowed(builder, true)
 	if !m.IsAllowed(builder) {
 		t.Fatal("manual SetAllowed(true) should override revoke")

miner/bid_simulator.go

@@ -654,7 +654,8 @@ func (b *bidSimulator) AddBidBlock(parentHash common.Hash, block *types.DecodedB
 	defer b.bestBidBlockMu.Unlock()
 
 	if existing := b.bestBidBlock[parentHash]; existing != nil && block.GasFee.Cmp(existing.GasFee) < 0 {
-		return fmt.Errorf("BidBlock gasFee below current best: got %v, best %v", block.GasFee, existing.GasFee)
+		return fmt.Errorf("BidBlock gasFee below current best: got %s, best %s",
+			weiToEtherStringF6(block.GasFee), weiToEtherStringF6(existing.GasFee))
 	}
 	b.bestBidBlock[parentHash] = block
 	return nil