Support Zircuit fraud transactions and zk overflow detection (#14629)

* Support Zircuit fraud transactions detection and zk overflow detection, need dedup and unit test

* add dedup

* fix test

* add unit tests

* rm

* update chaintype

* update for testnet chainType

* address comments

* update log level

Author: huangzhen1997

.changeset/orange-humans-laugh.md

@@ -0,0 +1,5 @@
+---
+"chainlink": minor
+---
+
+Support Zircuit fraud transactions detection and zk overflow detection #added

core/chains/evm/config/chaintype/chaintype.go

@@ -23,6 +23,7 @@ const (
 	ChainXLayer          ChainType = "xlayer"
 	ChainZkEvm           ChainType = "zkevm"
 	ChainZkSync          ChainType = "zksync"
+	ChainZircuit         ChainType = "zircuit"
 )
 
 // IsL2 returns true if this chain is a Layer 2 chain. Notably:
@@ -39,7 +40,7 @@ func (c ChainType) IsL2() bool {
 
 func (c ChainType) IsValid() bool {
 	switch c {
-	case "", ChainArbitrum, ChainAstar, ChainCelo, ChainGnosis, ChainHedera, ChainKroma, ChainMantle, ChainMetis, ChainOptimismBedrock, ChainSei, ChainScroll, ChainWeMix, ChainXLayer, ChainZkEvm, ChainZkSync:
+	case "", ChainArbitrum, ChainAstar, ChainCelo, ChainGnosis, ChainHedera, ChainKroma, ChainMantle, ChainMetis, ChainOptimismBedrock, ChainSei, ChainScroll, ChainWeMix, ChainXLayer, ChainZkEvm, ChainZkSync, ChainZircuit:
 		return true
 	}
 	return false
@@ -77,6 +78,8 @@ func FromSlug(slug string) ChainType {
 		return ChainZkEvm
 	case "zksync":
 		return ChainZkSync
+	case "zircuit":
+		return ChainZircuit
 	default:
 		return ChainType(slug)
 	}
@@ -144,4 +147,5 @@ var ErrInvalid = fmt.Errorf("must be one of %s or omitted", strings.Join([]strin
 	string(ChainXLayer),
 	string(ChainZkEvm),
 	string(ChainZkSync),
+	string(ChainZircuit),
 }, ", "))

core/chains/evm/config/toml/defaults/Zircuit_Mainnet.toml

@@ -1,5 +1,5 @@
 ChainID = '48900'
-ChainType = 'optimismBedrock'
+ChainType = 'zircuit'
 FinalityTagEnabled = true
 FinalityDepth = 1000
 LinkContractAddress = '0x5D6d033B4FbD2190D99D930719fAbAcB64d2439a'

core/chains/evm/config/toml/defaults/Zircuit_Sepolia.toml

@@ -1,5 +1,5 @@
 ChainID = '48899'
-ChainType = 'optimismBedrock'
+ChainType = 'zircuit'
 FinalityTagEnabled = true
 FinalityDepth = 1000
 LinkContractAddress = '0xDEE94506570cA186BC1e3516fCf4fd719C312cCD'

core/chains/evm/gas/chain_specific.go

@@ -19,7 +19,7 @@ func chainSpecificIsUsable(tx evmtypes.Transaction, baseFee *assets.Wei, chainTy
 			return false
 		}
 	}
-	if chainType == chaintype.ChainOptimismBedrock || chainType == chaintype.ChainKroma || chainType == chaintype.ChainScroll {
+	if chainType == chaintype.ChainOptimismBedrock || chainType == chaintype.ChainKroma || chainType == chaintype.ChainScroll || chainType == chaintype.ChainZircuit {
 		// This is a special deposit transaction type introduced in Bedrock upgrade.
 		// This is a system transaction that it will occur at least one time per block.
 		// We should discard this type before even processing it to avoid flooding the

core/chains/evm/gas/rollups/l1_oracle.go

@@ -57,7 +57,7 @@ func NewL1GasOracle(lggr logger.Logger, ethClient l1OracleClient, chainType chai
 	var l1Oracle L1Oracle
 	var err error
 	switch chainType {
-	case chaintype.ChainOptimismBedrock, chaintype.ChainKroma, chaintype.ChainScroll, chaintype.ChainMantle:
+	case chaintype.ChainOptimismBedrock, chaintype.ChainKroma, chaintype.ChainScroll, chaintype.ChainMantle, chaintype.ChainZircuit:
 		l1Oracle, err = NewOpStackL1GasOracle(lggr, ethClient, chainType)
 	case chaintype.ChainArbitrum:
 		l1Oracle, err = NewArbitrumL1GasOracle(lggr, ethClient)

core/chains/evm/gas/rollups/op_l1_oracle.go

@@ -101,7 +101,7 @@ const (
 func NewOpStackL1GasOracle(lggr logger.Logger, ethClient l1OracleClient, chainType chaintype.ChainType) (*optimismL1Oracle, error) {
 	var precompileAddress string
 	switch chainType {
-	case chaintype.ChainOptimismBedrock, chaintype.ChainMantle:
+	case chaintype.ChainOptimismBedrock, chaintype.ChainMantle, chaintype.ChainZircuit:
 		precompileAddress = OPGasOracleAddress
 	case chaintype.ChainKroma:
 		precompileAddress = KromaGasOracleAddress

core/chains/evm/txmgr/stuck_tx_detector.go

@@ -130,6 +130,8 @@ func (d *stuckTxDetector) DetectStuckTransactions(ctx context.Context, enabledAd
 		return d.detectStuckTransactionsScroll(ctx, txs)
 	case chaintype.ChainZkEvm, chaintype.ChainXLayer:
 		return d.detectStuckTransactionsZkEVM(ctx, txs)
+	case chaintype.ChainZircuit:
+		return d.detectStuckTransactionsZircuit(ctx, txs, blockNum)
 	default:
 		return d.detectStuckTransactionsHeuristic(ctx, txs, blockNum)
 	}
@@ -270,6 +272,10 @@ type scrollResponse struct {
 	Data    map[string]int `json:"data"`
 }
 
+type zircuitResponse struct {
+	IsQuarantined bool `json:"isQuarantined"`
+}
+
 // Uses the custom Scroll skipped endpoint to determine an overflow transaction
 func (d *stuckTxDetector) detectStuckTransactionsScroll(ctx context.Context, txs []Tx) ([]Tx, error) {
 	if d.cfg.DetectionApiUrl() == nil {
@@ -336,6 +342,84 @@ func (d *stuckTxDetector) detectStuckTransactionsScroll(ctx context.Context, txs
 	return stuckTx, nil
 }
 
+// return fraud and overflow transactions
+func (d *stuckTxDetector) detectStuckTransactionsZircuit(ctx context.Context, txs []Tx, blockNum int64) ([]Tx, error) {
+	var err error
+	var fraudTxs, stuckTxs []Tx
+	fraudTxs, err = d.detectFraudTransactionsZircuit(ctx, txs)
+	if err != nil {
+		d.lggr.Errorf("Failed to detect zircuit fraud transactions: %v", err)
+	}
+
+	stuckTxs, err = d.detectStuckTransactionsHeuristic(ctx, txs, blockNum)
+	if err != nil {
+		return txs, err
+	}
+
+	// prevent duplicate transactions from the fraudTxs and stuckTxs with a map
+	uniqueTxs := make(map[int64]Tx)
+	for _, tx := range fraudTxs {
+		uniqueTxs[tx.ID] = tx
+	}
+
+	for _, tx := range stuckTxs {
+		uniqueTxs[tx.ID] = tx
+	}
+
+	var combinedStuckTxs []Tx
+	for _, tx := range uniqueTxs {
+		combinedStuckTxs = append(combinedStuckTxs, tx)
+	}
+
+	return combinedStuckTxs, nil
+}
+
+// Uses zirc_isQuarantined to check whether the transactions are considered as malicious by the sequencer and
+// preventing their inclusion into a block
+func (d *stuckTxDetector) detectFraudTransactionsZircuit(ctx context.Context, txs []Tx) ([]Tx, error) {
+	txReqs := make([]rpc.BatchElem, len(txs))
+	txHashMap := make(map[common.Hash]Tx)
+	txRes := make([]*zircuitResponse, len(txs))
+
+	// Build batch request elems to perform
+	for i, tx := range txs {
+		latestAttemptHash := tx.TxAttempts[0].Hash
+		var result zircuitResponse
+		txReqs[i] = rpc.BatchElem{
+			Method: "zirc_isQuarantined",
+			Args: []interface{}{
+				latestAttemptHash,
+			},
+			Result: &result,
+		}
+		txHashMap[latestAttemptHash] = tx
+		txRes[i] = &result
+	}
+
+	// Send batch request
+	err := d.chainClient.BatchCallContext(ctx, txReqs)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check Quarantine transactions in batch: %w", err)
+	}
+
+	// If the result is not nil, the fraud transaction is flagged as quarantined
+	var fraudTxs []Tx
+	for i, req := range txReqs {
+		txHash := req.Args[0].(common.Hash)
+		if req.Error != nil {
+			d.lggr.Errorf("failed to check fraud transaction by hash (%s): %v", txHash.String(), req.Error)
+			continue
+		}
+
+		result := txRes[i]
+		if result != nil && result.IsQuarantined {
+			tx := txHashMap[txHash]
+			fraudTxs = append(fraudTxs, tx)
+		}
+	}
+	return fraudTxs, nil
+}
+
 // Uses eth_getTransactionByHash to detect that a transaction has been discarded due to overflow
 // Currently only used by zkEVM but if other chains follow the same behavior in the future
 func (d *stuckTxDetector) detectStuckTransactionsZkEVM(ctx context.Context, txs []Tx) ([]Tx, error) {
@@ -390,7 +474,7 @@ func (d *stuckTxDetector) detectStuckTransactionsZkEVM(ctx context.Context, txs
 	for i, req := range txReqs {
 		txHash := req.Args[0].(common.Hash)
 		if req.Error != nil {
-			d.lggr.Debugf("failed to get transaction by hash (%s): %v", txHash.String(), req.Error)
+			d.lggr.Errorf("failed to get transaction by hash (%s): %v", txHash.String(), req.Error)
 			continue
 		}
 		result := *txRes[i]

core/chains/evm/txmgr/stuck_tx_detector_test.go

@@ -280,6 +280,108 @@ func TestStuckTxDetector_DetectStuckTransactionsHeuristic(t *testing.T) {
 	})
 }
 
+func TestStuckTxDetector_DetectStuckTransactionsZircuit(t *testing.T) {
+	t.Parallel()
+
+	db := pgtest.NewSqlxDB(t)
+	txStore := cltest.NewTestTxStore(t, db)
+	ethKeyStore := cltest.NewKeyStore(t, db).Eth()
+	ctx := tests.Context(t)
+
+	lggr := logger.Test(t)
+	feeEstimator := gasmocks.NewEvmFeeEstimator(t)
+	// Return 10 gwei as market gas price
+	marketGasPrice := tenGwei
+	fee := gas.EvmFee{Legacy: marketGasPrice}
+	feeEstimator.On("GetFee", mock.Anything, []byte{}, uint64(0), mock.Anything, mock.Anything, mock.Anything).Return(fee, uint64(0), nil)
+	ethClient := testutils.NewEthClientMockWithDefaultChain(t)
+	autoPurgeThreshold := uint32(5)
+	autoPurgeMinAttempts := uint32(3)
+	autoPurgeCfg := testAutoPurgeConfig{
+		enabled:     true, // Enable auto-purge feature for testing
+		threshold:   &autoPurgeThreshold,
+		minAttempts: &autoPurgeMinAttempts,
+	}
+	blockNum := int64(100)
+	stuckTxDetector := txmgr.NewStuckTxDetector(lggr, testutils.FixtureChainID, chaintype.ChainZircuit, assets.NewWei(assets.NewEth(100).ToInt()), autoPurgeCfg, feeEstimator, txStore, ethClient)
+
+	t.Run("returns empty list if no fraud or stuck transactions identified", func(t *testing.T) {
+		_, fromAddress := cltest.MustInsertRandomKey(t, ethKeyStore)
+		tx := mustInsertUnconfirmedTxWithBroadcastAttempts(t, txStore, 0, fromAddress, 1, blockNum, tenGwei)
+		attempts := tx.TxAttempts[0]
+		// Request still returns transaction by hash, transaction not discarded by network and not considered stuck
+		ethClient.On("BatchCallContext", mock.Anything, mock.MatchedBy(func(b []rpc.BatchElem) bool {
+			return len(b) == 1 && cltest.BatchElemMatchesParams(b[0], attempts.Hash, "zirc_isQuarantined")
+		})).Return(nil).Run(func(args mock.Arguments) {
+			elems := args.Get(1).([]rpc.BatchElem)
+			resp, err := json.Marshal(struct {
+				IsQuarantined bool `json:"isQuarantined"`
+			}{IsQuarantined: false})
+			require.NoError(t, err)
+			elems[0].Error = json.Unmarshal(resp, elems[0].Result)
+		}).Once()
+
+		txs, err := stuckTxDetector.DetectStuckTransactions(ctx, []common.Address{fromAddress}, blockNum)
+		require.NoError(t, err)
+		require.Len(t, txs, 0)
+	})
+
+	t.Run("returns fraud transactions identified", func(t *testing.T) {
+		_, fromAddress := cltest.MustInsertRandomKey(t, ethKeyStore)
+		tx := mustInsertUnconfirmedTxWithBroadcastAttempts(t, txStore, 0, fromAddress, 1, blockNum, tenGwei)
+		attempts := tx.TxAttempts[0]
+		// Request still returns transaction by hash, transaction not discarded by network and not considered stuck
+		ethClient.On("BatchCallContext", mock.Anything, mock.MatchedBy(func(b []rpc.BatchElem) bool {
+			return len(b) == 1 && cltest.BatchElemMatchesParams(b[0], attempts.Hash, "zirc_isQuarantined")
+		})).Return(nil).Run(func(args mock.Arguments) {
+			elems := args.Get(1).([]rpc.BatchElem)
+			resp, err := json.Marshal(struct {
+				IsQuarantined bool `json:"isQuarantined"`
+			}{IsQuarantined: true})
+			require.NoError(t, err)
+			elems[0].Error = json.Unmarshal(resp, elems[0].Result)
+		}).Once()
+
+		txs, err := stuckTxDetector.DetectStuckTransactions(ctx, []common.Address{fromAddress}, blockNum)
+		require.NoError(t, err)
+		require.Len(t, txs, 1)
+	})
+
+	t.Run("returns the transaction only once if it's identified as both fraud and stuck", func(t *testing.T) {
+		_, fromAddress := cltest.MustInsertRandomKey(t, ethKeyStore)
+		tx := mustInsertUnconfirmedTxWithBroadcastAttempts(t, txStore, 0, fromAddress, autoPurgeMinAttempts, blockNum-int64(autoPurgeThreshold)+int64(autoPurgeMinAttempts-1), marketGasPrice.Add(oneGwei))
+		attempts := tx.TxAttempts[0]
+
+		ethClient.On("BatchCallContext", mock.Anything, mock.MatchedBy(func(b []rpc.BatchElem) bool {
+			return len(b) == 1 && cltest.BatchElemMatchesParams(b[0], attempts.Hash, "zirc_isQuarantined")
+		})).Return(nil).Run(func(args mock.Arguments) {
+			elems := args.Get(1).([]rpc.BatchElem)
+			resp, err := json.Marshal(struct {
+				IsQuarantined bool `json:"isQuarantined"`
+			}{IsQuarantined: true})
+			require.NoError(t, err)
+			elems[0].Error = json.Unmarshal(resp, elems[0].Result)
+		}).Once()
+
+		txs, err := stuckTxDetector.DetectStuckTransactions(ctx, []common.Address{fromAddress}, blockNum)
+		require.NoError(t, err)
+		require.Len(t, txs, 1)
+	})
+	t.Run("returns the stuck tx even if failed to detect fraud tx", func(t *testing.T) {
+		_, fromAddress := cltest.MustInsertRandomKey(t, ethKeyStore)
+		tx := mustInsertUnconfirmedTxWithBroadcastAttempts(t, txStore, 0, fromAddress, autoPurgeMinAttempts, blockNum-int64(autoPurgeThreshold)+int64(autoPurgeMinAttempts-1), marketGasPrice.Add(oneGwei))
+		attempts := tx.TxAttempts[0]
+
+		ethClient.On("BatchCallContext", mock.Anything, mock.MatchedBy(func(b []rpc.BatchElem) bool {
+			return len(b) == 1 && cltest.BatchElemMatchesParams(b[0], attempts.Hash, "zirc_isQuarantined")
+		})).Return(fmt.Errorf("failed to fetch rpc"))
+
+		txs, err := stuckTxDetector.DetectStuckTransactions(ctx, []common.Address{fromAddress}, blockNum)
+		require.NoError(t, err)
+		require.Len(t, txs, 1)
+	})
+}
+
 func TestStuckTxDetector_DetectStuckTransactionsZkEVM(t *testing.T) {
 	t.Parallel()
 

core/services/chainlink/config_test.go

@@ -1357,7 +1357,7 @@ func TestConfig_Validate(t *testing.T) {
 		- 1: 10 errors:
 			- ChainType: invalid value (Foo): must not be set with this chain id
 			- Nodes: missing: must have at least one node
-			- ChainType: invalid value (Foo): must be one of arbitrum, astar, celo, gnosis, hedera, kroma, mantle, metis, optimismBedrock, sei, scroll, wemix, xlayer, zkevm, zksync or omitted
+			- ChainType: invalid value (Foo): must be one of arbitrum, astar, celo, gnosis, hedera, kroma, mantle, metis, optimismBedrock, sei, scroll, wemix, xlayer, zkevm, zksync, zircuit or omitted
 			- HeadTracker.HistoryDepth: invalid value (30): must be greater than or equal to FinalizedBlockOffset
 			- GasEstimator.BumpThreshold: invalid value (0): cannot be 0 if auto-purge feature is enabled for Foo
 			- Transactions.AutoPurge.Threshold: missing: needs to be set if auto-purge feature is enabled for Foo
@@ -1370,7 +1370,7 @@ func TestConfig_Validate(t *testing.T) {
 		- 2: 5 errors:
 			- ChainType: invalid value (Arbitrum): only "optimismBedrock" can be used with this chain id
 			- Nodes: missing: must have at least one node
-			- ChainType: invalid value (Arbitrum): must be one of arbitrum, astar, celo, gnosis, hedera, kroma, mantle, metis, optimismBedrock, sei, scroll, wemix, xlayer, zkevm, zksync or omitted
+			- ChainType: invalid value (Arbitrum): must be one of arbitrum, astar, celo, gnosis, hedera, kroma, mantle, metis, optimismBedrock, sei, scroll, wemix, xlayer, zkevm, zksync, zircuit or omitted
 			- FinalityDepth: invalid value (0): must be greater than or equal to 1
 			- MinIncomingConfirmations: invalid value (0): must be greater than or equal to 1
 		- 3: 3 errors: