refactor(backport): add documentation for ZetaClient logging fields (#4174)

renan061 · renan061 · commit 61fea7312545 · 2025-09-26T22:08:20.000-03:00
* refactor: use coin.CoinType for compliance logging

* refactor: add documentation for zetaclient logging fields
diff --git a/changelog.md b/changelog.md
@@ -12,6 +12,7 @@
 
 * [4144](https://github.com/zeta-chain/node/pull/4144) - standardize structured logging for zetaclient
 * [4180](https://github.com/zeta-chain/node/pull/4180) - remove unused loggers and log fields
+* [4174](https://github.com/zeta-chain/node/pull/4174) - add documentation for ZetaClient logging fields
 
 ### Fixes
 
diff --git a/zetaclient/chains/base/signer.go b/zetaclient/chains/base/signer.go
@@ -171,7 +171,7 @@ func (s *Signer) PassesCompliance(cctx *types.CrossChainTx) bool {
 		cctx.Index,
 		cctx.InboundParams.Sender,
 		params.Receiver,
-		params.CoinType.String(),
+		&params.CoinType,
 	)
 
 	return false
diff --git a/zetaclient/chains/bitcoin/observer/event.go b/zetaclient/chains/bitcoin/observer/event.go
@@ -9,6 +9,7 @@ import (
 	"github.com/pkg/errors"
 
 	"github.com/zeta-chain/node/pkg/chains"
+	"github.com/zeta-chain/node/pkg/coin"
 	"github.com/zeta-chain/node/pkg/constant"
 	"github.com/zeta-chain/node/pkg/crypto"
 	"github.com/zeta-chain/node/pkg/memo"
@@ -168,8 +169,9 @@ func (ob *Observer) IsEventProcessable(event BTCInboundEvent) bool {
 		logger.Info().Msg("thank you rich folk for your donation!")
 		return false
 	case clienttypes.InboundCategoryRestricted:
-		compliance.PrintComplianceLog(ob.logger.Inbound, ob.logger.Compliance,
-			false, ob.Chain().ChainId, event.TxHash, event.FromAddress, event.ToAddress, "BTC")
+		coinType := coin.CoinType_Gas
+		compliance.PrintComplianceLog(ob.logger.Inbound, ob.logger.Compliance, false,
+			ob.Chain().ChainId, event.TxHash, event.FromAddress, event.ToAddress, &coinType)
 		return false
 	default:
 		logger.Error().Any("category", category).Msg("unreachable code got InboundCategory")
diff --git a/zetaclient/chains/evm/observer/inbound.go b/zetaclient/chains/evm/observer/inbound.go
@@ -611,6 +611,7 @@ func (ob *Observer) buildInboundVoteMsgForDepositedEvent(
 		maybeReceiver = parsedAddress.Hex()
 	}
 	if config.ContainRestrictedAddress(sender.Hex(), clienttypes.BytesToEthHex(event.Recipient), maybeReceiver) {
+		coinType := coin.CoinType_ERC20
 		compliance.PrintComplianceLog(
 			ob.Logger().Inbound,
 			ob.Logger().Compliance,
@@ -619,7 +620,7 @@ func (ob *Observer) buildInboundVoteMsgForDepositedEvent(
 			event.Raw.TxHash.Hex(),
 			sender.Hex(),
 			clienttypes.BytesToEthHex(event.Recipient),
-			"ERC20",
+			&coinType,
 		)
 		return nil
 	}
@@ -681,8 +682,9 @@ func (ob *Observer) buildInboundVoteMsgForZetaSentEvent(
 	// https://github.com/zeta-chain/node/issues/4057
 	sender := event.ZetaTxSenderAddress.Hex()
 	if config.ContainRestrictedAddress(sender, destAddr, event.SourceTxOriginAddress.Hex()) {
+		coinType := coin.CoinType_Zeta
 		compliance.PrintComplianceLog(ob.Logger().Inbound, ob.Logger().Compliance,
-			false, ob.Chain().ChainId, event.Raw.TxHash.Hex(), sender, destAddr, "Zeta")
+			false, ob.Chain().ChainId, event.Raw.TxHash.Hex(), sender, destAddr, &coinType)
 		return nil
 	}
 
@@ -737,8 +739,9 @@ func (ob *Observer) buildInboundVoteMsgForTokenSentToTSS(
 		maybeReceiver = parsedAddress.Hex()
 	}
 	if config.ContainRestrictedAddress(sender.Hex(), maybeReceiver) {
+		coinType := coin.CoinType_Gas
 		compliance.PrintComplianceLog(ob.Logger().Inbound, ob.Logger().Compliance,
-			false, ob.Chain().ChainId, tx.Hash, sender.Hex(), sender.Hex(), "Gas")
+			false, ob.Chain().ChainId, tx.Hash, sender.Hex(), sender.Hex(), &coinType)
 		return nil
 	}
 
diff --git a/zetaclient/chains/evm/observer/v2_inbound.go b/zetaclient/chains/evm/observer/v2_inbound.go
@@ -40,7 +40,7 @@ func (ob *Observer) isEventProcessable(
 			txHash.Hex(),
 			sender.Hex(),
 			receiver.Hex(),
-			"Deposit",
+			nil,
 		)
 		return false
 	}
@@ -379,22 +379,22 @@ func (ob *Observer) observeGatewayDepositAndCall(
 
 // parseAndValidateDepositAndCallEvents collects and sorts events by block number, tx index, and log index
 func (ob *Observer) parseAndValidateDepositAndCallEvents(
-	rawLogs []ethtypes.Log,
+	ethlogs []ethtypes.Log,
 	gatewayAddr ethcommon.Address,
 	gatewayContract *gatewayevm.GatewayEVM,
 ) []*gatewayevm.GatewayEVMDepositedAndCalled {
 	// collect and sort validEvents by block number, then tx index, then log index (ascending)
 	validEvents := make([]*gatewayevm.GatewayEVMDepositedAndCalled, 0)
-	for _, log := range rawLogs {
-		err := common.ValidateEvmTxLog(&log, gatewayAddr, "", common.TopicsGatewayDepositAndCall)
+	for _, ethlog := range ethlogs {
+		err := common.ValidateEvmTxLog(&ethlog, gatewayAddr, "", common.TopicsGatewayDepositAndCall)
 		if err != nil {
 			continue
 		}
-		depositAndCallEvent, err := gatewayContract.ParseDepositedAndCalled(log)
+		depositAndCallEvent, err := gatewayContract.ParseDepositedAndCalled(ethlog)
 		if err != nil {
 			ob.Logger().Inbound.Warn().
-				Stringer(logs.FieldTx, log.TxHash).
-				Uint64(logs.FieldBlock, log.BlockNumber).
+				Stringer(logs.FieldTx, ethlog.TxHash).
+				Uint64(logs.FieldBlock, ethlog.BlockNumber).
 				Msg("invalid DepositedAndCall event")
 			continue
 		}
diff --git a/zetaclient/chains/solana/observer/inbound.go b/zetaclient/chains/solana/observer/inbound.go
@@ -213,7 +213,7 @@ func (ob *Observer) IsEventProcessable(event clienttypes.InboundEvent) bool {
 		return false
 	case clienttypes.InboundCategoryRestricted:
 		compliance.PrintComplianceLog(ob.Logger().Inbound, ob.Logger().Compliance,
-			false, ob.Chain().ChainId, event.TxHash, event.Sender, event.Receiver, event.CoinType.String())
+			false, ob.Chain().ChainId, event.TxHash, event.Sender, event.Receiver, &event.CoinType)
 		return false
 	default:
 		ob.Logger().Inbound.Error().Interface("category", category).Msg("unreachable code, got InboundCategory")
diff --git a/zetaclient/chains/solana/signer/increment_nonce.go b/zetaclient/chains/solana/signer/increment_nonce.go
@@ -8,6 +8,7 @@ import (
 	"github.com/near/borsh-go"
 	"github.com/rs/zerolog"
 
+	"github.com/zeta-chain/node/pkg/coin"
 	contracts "github.com/zeta-chain/node/pkg/contracts/solana"
 	"github.com/zeta-chain/node/x/crosschain/types"
 	"github.com/zeta-chain/node/zetaclient/compliance"
@@ -24,6 +25,7 @@ func (signer *Signer) prepareIncrementNonceTx(
 	// compliance check
 	cancelTx := compliance.IsCCTXRestricted(cctx)
 	if cancelTx {
+		coinType := coin.CoinType_Gas
 		compliance.PrintComplianceLog(
 			logger,
 			signer.Logger().Compliance,
@@ -32,7 +34,7 @@ func (signer *Signer) prepareIncrementNonceTx(
 			cctx.Index,
 			cctx.InboundParams.Sender,
 			params.Receiver,
-			"SOL",
+			&coinType,
 		)
 	}
 
diff --git a/zetaclient/chains/sui/observer/inbound.go b/zetaclient/chains/sui/observer/inbound.go
@@ -194,7 +194,7 @@ func (ob *Observer) constructInboundVote(
 			event.TxHash,
 			deposit.Sender,
 			deposit.Receiver.String(),
-			asset,
+			&coinType,
 		)
 		return nil, errCompliance
 	}
diff --git a/zetaclient/chains/ton/observer/inbound.go b/zetaclient/chains/ton/observer/inbound.go
@@ -333,7 +333,7 @@ func (ob *Observer) inboundComplianceCheck(inbound inboundData) (restricted bool
 		txHash,
 		inbound.sender.ToRaw(),
 		inbound.receiver.Hex(),
-		inbound.coinType.String(),
+		&inbound.coinType,
 	)
 
 	return true
diff --git a/zetaclient/chains/ton/observer/inbound_test.go b/zetaclient/chains/ton/observer/inbound_test.go
@@ -277,7 +277,7 @@ func TestInbound(t *testing.T) {
 
 		// Check that NO cctx was sent && log contains entry for restricted address
 		require.Len(t, ts.votesBag, 0)
-		require.Contains(t, ts.logger.String(), "Restricted address detected in inbound")
+		require.Contains(t, ts.logger.String(), "restricted address detected in inbound")
 	})
 
 	// Yep, it's possible to have withdrawals here because we scroll through all gateway's txs
diff --git a/zetaclient/chains/ton/signer/signer_compose.go b/zetaclient/chains/ton/signer/signer_compose.go
@@ -64,7 +64,7 @@ func (s *Signer) composeOutbound(cctx *cctypes.CrossChainTx) (outbound, error) {
 			cctx.Index,
 			cctx.InboundParams.Sender,
 			params.Receiver,
-			params.CoinType.String(),
+			&params.CoinType,
 		)
 	}
 
diff --git a/zetaclient/compliance/compliance.go b/zetaclient/compliance/compliance.go
@@ -4,6 +4,7 @@ package compliance
 import (
 	"github.com/rs/zerolog"
 
+	"github.com/zeta-chain/node/pkg/coin"
 	crosschaintypes "github.com/zeta-chain/node/x/crosschain/types"
 	"github.com/zeta-chain/node/zetaclient/config"
 	"github.com/zeta-chain/node/zetaclient/logs"
@@ -20,36 +21,32 @@ func IsCCTXRestricted(cctx *crosschaintypes.CrossChainTx, additionalAddresses ..
 	return config.ContainRestrictedAddress(additionalAddresses...)
 }
 
-// PrintComplianceLog prints compliance log with fields [chain, cctx/inbound, chain, sender, receiver, token]
+// PrintComplianceLog prints compliance log with fields
+// [chain, sender, receiver, coin_type, cctx/tx] (coinType is optional)
 func PrintComplianceLog(
 	logger, complianceLogger zerolog.Logger,
 	outbound bool,
 	chainID int64,
-	identifier, sender, receiver, token string,
+	identifier, sender, receiver string,
+	coinType *coin.CoinType,
 ) {
-	var (
-		message string
-		fields  map[string]any
-	)
+	var message string
+	fields := map[string]any{
+		logs.FieldChain: chainID,
+		"sender":        sender,
+		"receiver":      receiver,
+	}
+
+	if coinType != nil {
+		fields[logs.FieldCoinType] = *coinType
+	}
 
 	if outbound {
-		message = "Restricted address detected in cctx"
-		fields = map[string]any{
-			logs.FieldChain:    chainID,
-			logs.FieldCoinType: token,
-			"identifier":       identifier,
-			"sender":           sender,
-			"receiver":         receiver,
-		}
+		message = "restricted address detected in CCTX"
+		fields[logs.FieldCctxIndex] = identifier
 	} else {
-		message = "Restricted address detected in inbound"
-		fields = map[string]any{
-			logs.FieldChain:    chainID,
-			logs.FieldCoinType: token,
-			logs.FieldTx:       identifier,
-			"sender":           sender,
-			"receiver":         receiver,
-		}
+		message = "restricted address detected in inbound"
+		fields[logs.FieldTx] = identifier
 	}
 
 	logger.Warn().Fields(fields).Msg(message)
diff --git a/zetaclient/logs/fields.go b/zetaclient/logs/fields.go
@@ -1,24 +1,48 @@
 package logs
 
-// A group of predefined field keys and module names for zetaclient logs
+// A group of predefined field keys and module names for the zetaclient logs.
 const (
-	FieldModule      = "module"
-	FieldChain       = "chain"
-	FieldNetwork     = "network"
-	FieldBlock       = "block"
-	FieldNonce       = "nonce"
-	FieldTx          = "tx"
-	FieldCctxIndex   = "cctx_index"
-	FieldZetaTx      = "zeta_tx"
-	FieldOutboundID  = "outbound_id"
+	// The module in the ZetaClient that originated the message.
+	// Check the ModName constants for possible values.
+	FieldModule = "module"
+
+	// Chain identifier.
+	FieldChain = "chain"
+
+	// Chain network.
+	FieldNetwork = "network"
+
+	// Height of a block.
+	FieldBlock = "block"
+
+	// Nonce of a transaction.
+	FieldNonce = "nonce"
+
+	// Hash of a transaction from an external chain.
+	FieldTx = "tx"
+
+	// Hash of a ZetaChain transaction.
+	FieldZetaTx = "zeta_tx"
+
+	// Unique identifier (index) of a cross-chain transaction.
+	FieldCctxIndex = "cctx_index"
+
+	// Unique identifier of an outbound transaction.
+	// Usually contains the nonce of the outbound in the external chain plus the chain identifier.
+	FieldOutboundID = "outbound_id"
+
+	// Index of a ballot from voting on an inbound or outbound cross-chain transaction.
 	FieldBallotIndex = "ballot_index"
-	FieldCoinType    = "coin_type"
 
-	// chain specific
+	// Type of the asset in the cross-chain transaction.
+	// This field can take one of the following values: Gas, ERC20, ZETA, and NoAssetCall.
+	FieldCoinType = "coin_type"
+
+	// TXID from a Bitcoin transaction.
 	FieldBtcTxid = "txid"
 )
 
-// module names
+// Range of values for FieldModule.
 const (
 	ModNameOrchestrator   = "orchestrator"
 	ModNameInbound        = "inbound"

Original file line number	Diff line number	Diff line change
`@@ -171,7 +171,7 @@ func (s Signer) PassesCompliance(cctx types.CrossChainTx) bool {`
`171`	`171`	`cctx.Index,`
`172`	`172`	`cctx.InboundParams.Sender,`
`173`	`173`	`params.Receiver,`
`174`		`- params.CoinType.String(),`
	`174`	`+ &params.CoinType,`
`175`	`175`	`)`
`176`	`176`
`177`	`177`	`return false`
Original file line number	Diff line number	Diff line change
`@@ -611,6 +611,7 @@ func (ob *Observer) buildInboundVoteMsgForDepositedEvent(`
`611`	`611`	`maybeReceiver = parsedAddress.Hex()`
`612`	`612`	`}`
`613`	`613`	`if config.ContainRestrictedAddress(sender.Hex(), clienttypes.BytesToEthHex(event.Recipient), maybeReceiver) {`
	`614`	`+ coinType := coin.CoinType_ERC20`
`614`	`615`	`compliance.PrintComplianceLog(`
`615`	`616`	`ob.Logger().Inbound,`
`616`	`617`	`ob.Logger().Compliance,`
`@@ -619,7 +620,7 @@ func (ob *Observer) buildInboundVoteMsgForDepositedEvent(`
`619`	`620`	`event.Raw.TxHash.Hex(),`
`620`	`621`	`sender.Hex(),`
`621`	`622`	`clienttypes.BytesToEthHex(event.Recipient),`
`622`		`- "ERC20",`
	`623`	`+ &coinType,`
`623`	`624`	`)`
`624`	`625`	`return nil`
`625`	`626`	`}`
`@@ -681,8 +682,9 @@ func (ob *Observer) buildInboundVoteMsgForZetaSentEvent(`
`681`	`682`	`// https://github.com/zeta-chain/node/issues/4057`
`682`	`683`	`sender := event.ZetaTxSenderAddress.Hex()`
`683`	`684`	`if config.ContainRestrictedAddress(sender, destAddr, event.SourceTxOriginAddress.Hex()) {`
	`685`	`+ coinType := coin.CoinType_Zeta`
`684`	`686`	`compliance.PrintComplianceLog(ob.Logger().Inbound, ob.Logger().Compliance,`
`685`		`- false, ob.Chain().ChainId, event.Raw.TxHash.Hex(), sender, destAddr, "Zeta")`
	`687`	`+ false, ob.Chain().ChainId, event.Raw.TxHash.Hex(), sender, destAddr, &coinType)`
`686`	`688`	`return nil`
`687`	`689`	`}`
`688`	`690`
`@@ -737,8 +739,9 @@ func (ob *Observer) buildInboundVoteMsgForTokenSentToTSS(`
`737`	`739`	`maybeReceiver = parsedAddress.Hex()`
`738`	`740`	`}`
`739`	`741`	`if config.ContainRestrictedAddress(sender.Hex(), maybeReceiver) {`
	`742`	`+ coinType := coin.CoinType_Gas`
`740`	`743`	`compliance.PrintComplianceLog(ob.Logger().Inbound, ob.Logger().Compliance,`
`741`		`- false, ob.Chain().ChainId, tx.Hash, sender.Hex(), sender.Hex(), "Gas")`
	`744`	`+ false, ob.Chain().ChainId, tx.Hash, sender.Hex(), sender.Hex(), &coinType)`
`742`	`745`	`return nil`
`743`	`746`	`}`
`744`	`747`
Original file line number	Diff line number	Diff line change
`@@ -194,7 +194,7 @@ func (ob *Observer) constructInboundVote(`
`194`	`194`	`event.TxHash,`
`195`	`195`	`deposit.Sender,`
`196`	`196`	`deposit.Receiver.String(),`
`197`		`- asset,`
	`197`	`+ &coinType,`
`198`	`198`	`)`
`199`	`199`	`return nil, errCompliance`
`200`	`200`	`}`
Original file line number	Diff line number	Diff line change
`@@ -333,7 +333,7 @@ func (ob *Observer) inboundComplianceCheck(inbound inboundData) (restricted bool`
`333`	`333`	`txHash,`
`334`	`334`	`inbound.sender.ToRaw(),`
`335`	`335`	`inbound.receiver.Hex(),`
`336`		`- inbound.coinType.String(),`
	`336`	`+ &inbound.coinType,`
`337`	`337`	`)`
`338`	`338`
`339`	`339`	`return true`