refactor: switch zetaclient to confirmation params; unify inbound observation as block range based (#3496)

* switch zetaclient to confirmation params; refactor evm, btc inbound observation using block range; add confirmation related helper functions to base observer

* add changelog entry

* clean unused code and revert unneeded change

* always use wrapper function InboundConfirmationFast() to ensure fallback to safe confirmation

* fix unit test failures

* add InboundConfirmationSafe and OutboundConfirmationSafe to make API consistent

* remove redundant log prints which can be printed by caller

* change ObserverTSSReceive -> ObserveTSSReceive

* correct misspelling in changelog

* simplify function signature

Co-authored-by: Dmitry S <[email protected]>

* function, variable remanings; using log fields, etc.

* fix CI unit test failure

---------

Co-authored-by: Dmitry S <[email protected]>

Author: ws4charlie

changelog.md

@@ -11,6 +11,7 @@
 ### Refactor
 
 * [3381](https://github.com/zeta-chain/node/pull/3381) - split Bitcoin observer and signer into small files and organize outbound logic into reusable/testable functions; renaming, type unification, etc.
+* [3496](https://github.com/zeta-chain/node/pull/3496) - zetaclient uses `ConfirmationParams` instead of old `ConfirmationCount`; use block ranged based observation for btc and evm chain.
 
 ### Fixes
 

cmd/zetatool/cctx/inbound.go

@@ -128,6 +128,7 @@ func (c *TrackingDetails) btcInboundBallotIdentifier(ctx *context.Context) error
 	if err != nil {
 		return fmt.Errorf("failed to get chain params: %w", err)
 	}
+	createConfirmationParamsIfAbsent(chainParams)
 
 	cctxIdentifier, isConfirmed, err := zetatoolchains.BitcoinBallotIdentifier(
 		ctx,
@@ -137,7 +138,7 @@ func (c *TrackingDetails) btcInboundBallotIdentifier(ctx *context.Context) error
 		inboundHash,
 		inboundChain.ChainId,
 		zetaChainID,
-		chainParams.ConfirmationCount,
+		chainParams.InboundConfirmationSafe(),
 	)
 	if err != nil {
 		return fmt.Errorf("failed to get bitcoin ballot identifier: %w", err)
@@ -161,6 +162,7 @@ func (c *TrackingDetails) evmInboundBallotIdentifier(ctx *context.Context) error
 	if err != nil {
 		return fmt.Errorf("failed to get chain params: %w", err)
 	}
+	createConfirmationParamsIfAbsent(chainParams)
 
 	evmClient, err := zetatoolchains.GetEvmClient(ctx, inboundChain)
 	if err != nil {
@@ -173,7 +175,7 @@ func (c *TrackingDetails) evmInboundBallotIdentifier(ctx *context.Context) error
 	}
 	// Signer is unused
 	zetaEvmClient := zetaevmclient.New(evmClient, ethtypes.NewLondonSigner(tx.ChainId()))
-	isConfirmed, err := zetaEvmClient.IsTxConfirmed(goCtx, inboundHash, chainParams.ConfirmationCount)
+	isConfirmed, err := zetaEvmClient.IsTxConfirmed(goCtx, inboundHash, chainParams.InboundConfirmationSafe())
 	if err != nil {
 		return fmt.Errorf("unable to confirm tx: %w", err)
 	}
@@ -310,6 +312,7 @@ func (c *TrackingDetails) solanaInboundBallotIdentifier(ctx *context.Context) er
 	if err != nil {
 		return fmt.Errorf("failed to get chain params: %w", err)
 	}
+	createConfirmationParamsIfAbsent(chainParams)
 
 	gatewayID, _, err := solanacontracts.ParseGatewayWithPDA(chainParams.GatewayAddress)
 	if err != nil {
@@ -371,3 +374,15 @@ func compareAddress(a string, b string) bool {
 	lowerB := strings.ToLower(b)
 	return strings.EqualFold(lowerA, lowerB)
 }
+
+// createConfirmationParamsIfAbsent sets the confirmation params if they are not already set
+// TODO: Remove this once the confirmation migration is done
+// https://github.com/zeta-chain/node/issues/3466
+func createConfirmationParamsIfAbsent(chainParams *types.ChainParams) {
+	if chainParams != nil && chainParams.ConfirmationParams == nil {
+		chainParams.ConfirmationParams = &types.ConfirmationParams{
+			SafeInboundCount:  chainParams.ConfirmationCount,
+			SafeOutboundCount: chainParams.ConfirmationCount,
+		}
+	}
+}

cmd/zetatool/cctx/outbound.go

@@ -69,7 +69,7 @@ func (c *TrackingDetails) checkEvmOutboundTx(ctx *context.Context) error {
 		}
 		// Signer is unused
 		c := zetaevmclient.New(evmClient, ethtypes.NewLondonSigner(tx.ChainId()))
-		confirmed, err := c.IsTxConfirmed(goCtx, hash, chainParams.ConfirmationCount)
+		confirmed, err := c.IsTxConfirmed(goCtx, hash, chainParams.OutboundConfirmationSafe())
 		if err != nil {
 			continue
 		}
@@ -125,7 +125,7 @@ func (c *TrackingDetails) checkBitcoinOutboundTx(ctx *context.Context) error {
 	if err != nil {
 		return fmt.Errorf("failed to get chain params: %w", err)
 	}
-	confirmationCount := chainParams.ConfirmationCount
+	confirmationCount := chainParams.OutboundConfirmationSafe()
 
 	params, err := chains.BitcoinNetParamsFromChainID(outboundChain.ChainId)
 	if err != nil {

x/observer/types/chain_params.go

@@ -155,6 +155,34 @@ func ValidateChainParams(params *ChainParams) error {
 	return nil
 }
 
+// InboundConfirmationSafe returns the safe number of confirmation for inbound observation.
+func (cp ChainParams) InboundConfirmationSafe() uint64 {
+	return cp.ConfirmationParams.SafeInboundCount
+}
+
+// InboundConfirmationFast returns the fast number of confirmation for inbound observation.
+// It falls back to safe confirmation count if fast mode is disabled.
+func (cp ChainParams) InboundConfirmationFast() uint64 {
+	if cp.ConfirmationParams.FastInboundCount > 0 {
+		return cp.ConfirmationParams.FastInboundCount
+	}
+	return cp.ConfirmationParams.SafeInboundCount
+}
+
+// OutboundConfirmationSafe returns the safe number of confirmation for outbound observation.
+func (cp ChainParams) OutboundConfirmationSafe() uint64 {
+	return cp.ConfirmationParams.SafeOutboundCount
+}
+
+// OutboundConfirmationFast returns the fast number of confirmation for outbound observation.
+// It falls back to safe confirmation count if fast mode is disabled.
+func (cp ChainParams) OutboundConfirmationFast() uint64 {
+	if cp.ConfirmationParams.FastOutboundCount > 0 {
+		return cp.ConfirmationParams.FastOutboundCount
+	}
+	return cp.ConfirmationParams.SafeOutboundCount
+}
+
 func validChainContractAddress(address string) bool {
 	if !strings.HasPrefix(address, "0x") {
 		return false
@@ -435,5 +463,17 @@ func ChainParamsEqual(params1, params2 ChainParams) bool {
 		params1.MinObserverDelegation.Equal(params2.MinObserverDelegation) &&
 		params1.IsSupported == params2.IsSupported &&
 		params1.GatewayAddress == params2.GatewayAddress &&
-		params1.ConfirmationParams == params2.ConfirmationParams
+		confirmationParamsEqual(params1.ConfirmationParams, params2.ConfirmationParams)
+}
+
+// confirmationParamsEqual returns true if two confirmation params are equal
+func confirmationParamsEqual(a, b *ConfirmationParams) bool {
+	if a == b {
+		return true
+	}
+	if (a == nil) || (b == nil) {
+		return false
+	}
+
+	return *a == *b
 }

x/observer/types/chain_params_test.go

@@ -8,6 +8,7 @@ import (
 	"github.com/stretchr/testify/suite"
 	. "gopkg.in/check.v1"
 
+	"github.com/zeta-chain/node/testutil/sample"
 	"github.com/zeta-chain/node/x/observer/types"
 )
 
@@ -48,9 +49,105 @@ func TestUpdateChainParamsSuiteSuite(t *testing.T) {
 }
 
 func TestChainParamsEqual(t *testing.T) {
-	params := types.GetDefaultChainParams()
-	require.True(t, types.ChainParamsEqual(*params.ChainParams[0], *params.ChainParams[0]))
-	require.False(t, types.ChainParamsEqual(*params.ChainParams[0], *params.ChainParams[1]))
+	params := sample.ChainParams(1)
+
+	require.True(t, types.ChainParamsEqual(*params, *params))
+
+	// ChainId matters
+	copy := copyParams(params)
+	copy.ChainId = 2
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// ConfirmationCount matters
+	copy = copyParams(params)
+	copy.ConfirmationCount = params.ConfirmationCount + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// GasPriceTicker matters
+	copy = copyParams(params)
+	copy.GasPriceTicker = params.GasPriceTicker + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// InboundTicker matters
+	copy = copyParams(params)
+	copy.InboundTicker = params.InboundTicker + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// OutboundTicker matters
+	copy = copyParams(params)
+	copy.OutboundTicker = params.OutboundTicker + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// WatchUtxoTicker matters
+	copy = copyParams(params)
+	copy.WatchUtxoTicker = params.WatchUtxoTicker + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// ZetaTokenContractAddress matters
+	copy = copyParams(params)
+	copy.ZetaTokenContractAddress = "0x_something_else"
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// ConnectorContractAddress matters
+	copy = copyParams(params)
+	copy.ConnectorContractAddress = "0x_something_else"
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// Erc20CustodyContractAddress matters
+	copy = copyParams(params)
+	copy.Erc20CustodyContractAddress = "0x_something_else"
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// OutboundScheduleInterval matters
+	copy = copyParams(params)
+	copy.OutboundScheduleInterval = params.OutboundScheduleInterval + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// OutboundScheduleLookahead matters
+	copy = copyParams(params)
+	copy.OutboundScheduleLookahead = params.OutboundScheduleLookahead + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// BallotThreshold matters
+	copy = copyParams(params)
+	copy.BallotThreshold = params.BallotThreshold.Add(sdkmath.LegacySmallestDec())
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// MinObserverDelegation matters
+	copy = copyParams(params)
+	copy.MinObserverDelegation = params.MinObserverDelegation.Add(sdkmath.LegacySmallestDec())
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// IsSupported matters
+	copy = copyParams(params)
+	copy.IsSupported = !params.IsSupported
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// GatewayAddress matters
+	copy = copyParams(params)
+	copy.GatewayAddress = "0x_something_else"
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	// ConfirmationParams matters
+	copy = copyParams(params)
+	copy.ConfirmationParams = nil
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	copy = copyParams(params)
+	copy.ConfirmationParams.SafeInboundCount = params.ConfirmationParams.SafeInboundCount + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	copy = copyParams(params)
+	copy.ConfirmationParams.FastInboundCount = params.ConfirmationParams.FastInboundCount + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	copy = copyParams(params)
+	copy.ConfirmationParams.SafeOutboundCount = params.ConfirmationParams.SafeOutboundCount + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
+
+	copy = copyParams(params)
+	copy.ConfirmationParams.FastOutboundCount = params.ConfirmationParams.FastOutboundCount + 1
+	require.False(t, types.ChainParamsEqual(*params, *copy))
 }
 
 func (s *UpdateChainParamsSuite) SetupTest() {
@@ -171,6 +268,58 @@ func (s *UpdateChainParamsSuite) TestCoreContractAddresses() {
 	require.NotNil(s.T(), err)
 }
 
+func Test_InboundConfirmationSafe(t *testing.T) {
+	cp := sample.ChainParams(1)
+
+	// set and check safe inbound count
+	cp.ConfirmationParams.SafeInboundCount = 10
+	require.Equal(t, uint64(10), cp.InboundConfirmationSafe())
+}
+
+func Test_OutboundConfirmationSafe(t *testing.T) {
+	cp := sample.ChainParams(1)
+
+	// set and check safe outbound count
+	cp.ConfirmationParams.SafeOutboundCount = 10
+	require.Equal(t, uint64(10), cp.OutboundConfirmationSafe())
+}
+
+func Test_InboundConfirmationFast(t *testing.T) {
+	t.Run("should return fast inbound confirmation count if enabled", func(t *testing.T) {
+		cp := sample.ChainParams(1)
+		cp.ConfirmationParams.SafeInboundCount = 2
+		cp.ConfirmationParams.FastInboundCount = 1
+		confirmation := cp.InboundConfirmationFast()
+		require.Equal(t, uint64(1), confirmation)
+	})
+
+	t.Run("should fallback to safe inbound confirmation count if fast confirmation is disabled", func(t *testing.T) {
+		cp := sample.ChainParams(1)
+		cp.ConfirmationParams.SafeInboundCount = 2
+		cp.ConfirmationParams.FastInboundCount = 0
+		confirmation := cp.InboundConfirmationFast()
+		require.Equal(t, uint64(2), confirmation)
+	})
+}
+
+func Test_OutboundConfirmationFast(t *testing.T) {
+	t.Run("should return fast outbound confirmation count if enabled", func(t *testing.T) {
+		cp := sample.ChainParams(1)
+		cp.ConfirmationParams.SafeOutboundCount = 2
+		cp.ConfirmationParams.FastOutboundCount = 1
+		confirmation := cp.OutboundConfirmationFast()
+		require.Equal(t, uint64(1), confirmation)
+	})
+
+	t.Run("should fallback to safe outbound confirmation count if fast confirmation is disabled", func(t *testing.T) {
+		cp := sample.ChainParams(1)
+		cp.ConfirmationParams.SafeOutboundCount = 2
+		cp.ConfirmationParams.FastOutboundCount = 0
+		confirmation := cp.OutboundConfirmationFast()
+		require.Equal(t, uint64(2), confirmation)
+	})
+}
+
 func (s *UpdateChainParamsSuite) Validate(params *types.ChainParams) {
 	copy := copyParams(params)
 	copy.ConfirmationCount = 0

zetaclient/chains/base/confirmation.go

@@ -0,0 +1,85 @@
+package base
+
+// GetScanRangeInboundSafe calculates the block range to scan using inbound safe confirmation count.
+// It returns a range of blocks [from, end (exclusive)) that need to be scanned.
+func (ob *Observer) GetScanRangeInboundSafe(blockLimit uint64) (from uint64, end uint64) {
+	lastBlock := ob.LastBlock()
+	lastScanned := ob.LastBlockScanned()
+	confirmation := ob.ChainParams().InboundConfirmationSafe()
+
+	return calcUnscannedBlockRange(lastBlock, lastScanned, confirmation, blockLimit)
+}
+
+// GetScanRangeInboundFast calculates the block range to scan using inbound fast confirmation count.
+// It returns a range of blocks [from, end (exclusive)) that need to be scanned.
+func (ob *Observer) GetScanRangeInboundFast(blockLimit uint64) (from uint64, end uint64) {
+	lastBlock := ob.LastBlock()
+	lastScanned := ob.LastBlockScanned()
+	confirmation := ob.ChainParams().InboundConfirmationFast()
+
+	return calcUnscannedBlockRange(lastBlock, lastScanned, confirmation, blockLimit)
+}
+
+// IsBlockConfirmedForInboundSafe checks if the block number is confirmed using inbound safe confirmation count.
+func (ob *Observer) IsBlockConfirmedForInboundSafe(blockNumber uint64) bool {
+	lastBlock := ob.LastBlock()
+	confirmation := ob.ChainParams().InboundConfirmationSafe()
+	return isBlockConfirmed(blockNumber, confirmation, lastBlock)
+}
+
+// IsBlockConfirmedForInboundFast checks if the block number is confirmed using inbound fast confirmation count.
+// It falls back to safe confirmation count if fast confirmation is disabled.
+func (ob *Observer) IsBlockConfirmedForInboundFast(blockNumber uint64) bool {
+	lastBlock := ob.LastBlock()
+	confirmation := ob.ChainParams().InboundConfirmationFast()
+	return isBlockConfirmed(blockNumber, confirmation, lastBlock)
+}
+
+// IsBlockConfirmedForOutboundSafe checks if the block number is confirmed using outbound safe confirmation count.
+func (ob *Observer) IsBlockConfirmedForOutboundSafe(blockNumber uint64) bool {
+	lastBlock := ob.LastBlock()
+	confirmation := ob.ChainParams().OutboundConfirmationSafe()
+	return isBlockConfirmed(blockNumber, confirmation, lastBlock)
+}
+
+// IsBlockConfirmedForOutboundFast checks if the block number is confirmed using outbound fast confirmation count.
+// It falls back to safe confirmation count if fast confirmation is disabled.
+func (ob *Observer) IsBlockConfirmedForOutboundFast(blockNumber uint64) bool {
+	lastBlock := ob.LastBlock()
+	confirmation := ob.ChainParams().OutboundConfirmationFast()
+	return isBlockConfirmed(blockNumber, confirmation, lastBlock)
+}
+
+// calcUnscannedBlockRange calculates the unscanned block range [from, end (exclusive)) within given block limit.
+//
+// example 1: given lastBlock =  99, lastScanned = 90, confirmation = 10, then no unscanned block
+// example 2: given lastBlock = 100, lastScanned = 90, confirmation = 10, then 1 unscanned block (block 91)
+func calcUnscannedBlockRange(lastBlock, lastScanned, confirmation, blockLimit uint64) (from uint64, end uint64) {
+	// got unscanned blocks or not?
+	if lastBlock < lastScanned+confirmation {
+		return 0, 0
+	}
+
+	// calculate the highest confirmed block
+	// example: given lastBlock = 101, confirmation = 10, then the highest confirmed block is 92
+	highestConfirmed := lastBlock - confirmation + 1
+
+	// calculate a range of unscanned blocks within block limit
+	from = lastScanned + 1
+	end = from + blockLimit
+
+	// 'end' is exclusive, so ensure it is not greater than (highestConfirmed+1)
+	if end > highestConfirmed+1 {
+		end = highestConfirmed + 1
+	}
+
+	return from, end
+}
+
+// isBlockConfirmed checks if the block number is confirmed.
+//
+// Note: block 100 is confirmed if the last block is 100 and confirmation count is 1.
+func isBlockConfirmed(blockNumber, confirmation, lastBlock uint64) bool {
+	confHeight := blockNumber + confirmation - 1
+	return lastBlock >= confHeight
+}