refactor: update cctx status to object to split error message into error and revert_error

changelog.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+### Unreleases
+
+### Refactor
+
+* [3326](https://github.com/zeta-chain/node/pull/3326) - improve error messages for cctx status object
+
 ## v25.0.0
 
 ### Features

docs/openapi/openapi.swagger.yaml

@@ -58515,6 +58515,11 @@ definitions:
         type: string
         format: int64
         description: when the CCTX was created. only populated on new transactions.
+      error_message_revert:
+        type: string
+        title: |-
+          error_message_revert carries information about the revert outbound tx ,
+          which is created if the first outbound tx fails
   zetacoreemissionsParams:
     type: object
     properties:

docs/zetacore/status_message.md

@@ -0,0 +1,70 @@
+# CCTX status message 
+
+The cctx object contains a field  `cctx_status` , which has the following structure 
+```go
+type Status struct {
+	Status CctxStatus `protobuf:"varint,1,opt,name=status,proto3,enum=zetachain.zetacore.crosschain.CctxStatus" json:"status,omitempty"`
+	StatusMessage string `protobuf:"bytes,2,opt,name=status_message,json=statusMessage,proto3" json:"status_message,omitempty"`
+	ErrorMessage        string `protobuf:"bytes,6,opt,name=error_message,json=errorMessage,proto3" json:"error_message,omitempty"`
+	LastUpdateTimestamp int64  `protobuf:"varint,3,opt,name=lastUpdate_timestamp,json=lastUpdateTimestamp,proto3" json:"lastUpdate_timestamp,omitempty"`
+	IsAbortRefunded     bool   `protobuf:"varint,4,opt,name=isAbortRefunded,proto3" json:"isAbortRefunded,omitempty"`
+	CreatedTimestamp int64 `protobuf:"varint,5,opt,name=created_timestamp,json=createdTimestamp,proto3" json:"created_timestamp,omitempty"`
+	ErrorMessageRevert string `protobuf:"bytes,7,opt,name=error_message_revert,json=errorMessageRevert,proto3" json:"error_message_revert,omitempty"`
+}
+```
+
+## Status 
+This is the most updated status for the cctx . This can be one of the following values
+- `PendingInbound` : The cctx is pending for the inbound to be finalized , this is an intermediately status used by the protocol only
+- `PendingOutbound` : This means that the inbound has been finalzied, and the outbound is pending
+- `OutboundMined` : The outbound has been successfully mined. This is a terminal status
+- `Aborted` : The cctx has been aborted. This is a terminal status
+- `PendingRevert` : The the cctx failed at some step and is pending for the revert to be finalized
+- `Reverted` : The cctx has been successfully reverted. This is a terminal status
+
+### StatusMessage
+The status message provides a some details about the current status.This is primiary meant for the user to quickly understand the status of the cctx.
+### LastUpdateTimestamp
+The last time the status was updated
+### IsAbortRefunded
+This is a boolean value which is true if the cctx has been refunded after being aborted or not .
+### CreatedTimestamp
+The time when the cctx was created
+### ErrorMessage and ErrorMessageRevert
+A cctx can have a maximum of two outbound params. We can refer to the first outbound as `outbound` and the second as `revert`.
+- A normal flow for a cctx is to go from `PendingOutbound` -> `OutboundMined` , which creates a single outbound
+- A cctx where the outbound fails has the transition `PendingOutbound` -> `PendingRevert` -> `Reverted` , which creates two outbounds
+- Any of the above two flows can abort the cctx at some point that can create either one or two outbounds
+
+  - The `ErrorMessage` field only contains a value if the original outbound failed. It contains details about the error that caused the outbound to fail
+  - The `ErrorMessageRevert` field only contains a value if the revert outbound failed. It contains details about the error that caused the revert outbound to fail.
+
+### Example values for StatusMessage field and how to interpret them
+- `initiating outbound` : The inbound votes have been successfully finalized, and the protocol is starting the outbound process
+- `outbound mined successfully` : The outbound was successfully mined
+- `revert successful` : The outbound failed , but the revert was successful
+- `revert failed` : The revert failed. This message also means that the initial outbound has failed.
+
+- `outbound failed` : The outbound failed, The protocol would try to create a revert either in the same block or schedule one to be picked up by zetaclient
+- `outbound failed for non-ZETA cctx` : Special case of outbound failed where we do not try to revert the cctx
+- `outbound failed for admin tx` : The outbound failed for an admin transaction, in this case we do not revert the cctx
+- `outbound failed deposit to ZEVM failed but contract call did not revert` : Special case of outbound failed The outbound/deposit failed, but the contract did not revert,
+   this is most likely caused by an internal error in the protocol.The CCTX is this case is aborted. Users can try connecting with the zetachain team to get a refund
+-  `outbound pre-processing failed` : The outbound failed during the pre-processing step. This means the outbound is never created. In this case the cctx is aborted
+- `cctx aborted with admin cmd` : The cctx was aborted manually by an admin command
+
+
+### Example values for ErrorMessage and ErrorMessageRevert fields and how to interpret them
+
+- For a failed deposit, the ErrorMessage would contain the following fields. The protocol generates the fields tagged as internal.
+```
+  - method: The method that was called by the protocol
+  - contract: The contract that his method was called on
+  - args:The argumets that were used for this call
+  - errorMessage[Internal]: Error message from the ZEVM call
+  - revertReason: Revert reason from the smart contract
+```
+
+- `outbound failed to external chain ,start revert` : withdraw failed to an external chain, and the protocol is starting the revert process back to ZEVM.
+- `coin type [CoinType] not supported for revert when source chain is Zetachain` : The coin type is not supported for revert when the source chain is Zetachain.
+- `error from EVMDeposit: [Error_String]` : Error returned by the protocol when trying to deposit tokens( and optionally call a contract) on ZEVM. The error string should explain the cause 

e2e/e2etests/test_bitcoin_deposit_and_call_revert_with_dust.go

@@ -52,5 +52,8 @@ func TestBitcoinDepositAndCallRevertWithDust(r *runner.E2ERunner, args []string)
 	cctx := utils.WaitCctxAbortedByInboundHash(r.Ctx, r, txHash.String(), r.CctxClient)
 
 	require.True(r, cctx.GetCurrentOutboundParam().Amount.Uint64() < constant.BTCWithdrawalDustAmount)
-	require.True(r, strings.Contains(cctx.CctxStatus.ErrorMessage, crosschaintypes.ErrInvalidWithdrawalAmount.Error()))
+	require.True(
+		r,
+		strings.Contains(cctx.CctxStatus.ErrorMessageRevert, crosschaintypes.ErrInvalidWithdrawalAmount.Error()),
+	)
 }

proto/zetachain/zetacore/crosschain/cross_chain_tx.proto

@@ -108,6 +108,18 @@ message Status {
   bool isAbortRefunded = 4;
   // when the CCTX was created. only populated on new transactions.
   int64 created_timestamp = 5;
+  // error_message_revert carries information about the revert outbound tx ,
+  // which is created if the first outbound tx fails
+  string error_message_revert = 7;
+}
+
+// StatusMessages is a message that carries status and error messages for a
+// cctx Currently this is only used internally to pass messages when updating
+// the status
+message StatusMessages {
+  string status_message = 1;
+  string error_message_outbound = 2;
+  string error_message_revert = 3;
 }
 
 // ProtocolContractVersion represents the version of the protocol contract used

typescript/zetachain/zetacore/crosschain/cross_chain_tx_pb.d.ts

@@ -395,6 +395,14 @@ export declare class Status extends Message<Status> {
    */
   createdTimestamp: bigint;
 
+  /**
+   * error_message_revert carries information about the revert outbound tx ,
+   * which is created if the first outbound tx fails
+   *
+   * @generated from field: string error_message_revert = 7;
+   */
+  errorMessageRevert: string;
+
   constructor(data?: PartialMessage<Status>);
 
   static readonly runtime: typeof proto3;
@@ -410,6 +418,44 @@ export declare class Status extends Message<Status> {
   static equals(a: Status | PlainMessage<Status> | undefined, b: Status | PlainMessage<Status> | undefined): boolean;
 }
 
+/**
+ * StatusMessages is a message that carries status and error messages for a
+ * cctx Currently this is only used internally to pass messages when updating
+ * the status
+ *
+ * @generated from message zetachain.zetacore.crosschain.StatusMessages
+ */
+export declare class StatusMessages extends Message<StatusMessages> {
+  /**
+   * @generated from field: string status_message = 1;
+   */
+  statusMessage: string;
+
+  /**
+   * @generated from field: string error_message_outbound = 2;
+   */
+  errorMessageOutbound: string;
+
+  /**
+   * @generated from field: string error_message_revert = 3;
+   */
+  errorMessageRevert: string;
+
+  constructor(data?: PartialMessage<StatusMessages>);
+
+  static readonly runtime: typeof proto3;
+  static readonly typeName = "zetachain.zetacore.crosschain.StatusMessages";
+  static readonly fields: FieldList;
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): StatusMessages;
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): StatusMessages;
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): StatusMessages;
+
+  static equals(a: StatusMessages | PlainMessage<StatusMessages> | undefined, b: StatusMessages | PlainMessage<StatusMessages> | undefined): boolean;
+}
+
 /**
  * RevertOptions represents the options for reverting a cctx
  *

x/crosschain/keeper/cctx_gateway_observers.go

@@ -75,7 +75,10 @@ func (c CCTXGatewayObservers) InitiateOutbound(
 	}()
 	if err != nil {
 		// do not commit anything here as the CCTX should be aborted
-		config.CCTX.SetAbort("internal error", err.Error())
+		config.CCTX.SetAbort(types.StatusMessages{
+			StatusMessage:        "outbound pre-processing failed",
+			ErrorMessageOutbound: fmt.Sprintf("unable to create outbound: %s", err.Error()),
+		})
 		return types.CctxStatus_Aborted, err
 	}
 	commit()

x/crosschain/keeper/cctx_gateway_zevm.go

@@ -1,6 +1,8 @@
 package keeper
 
 import (
+	"fmt"
+
 	sdk "github.com/cosmos/cosmos-sdk/types"
 
 	"github.com/zeta-chain/node/x/crosschain/types"
@@ -28,9 +30,10 @@ func (c CCTXGatewayZEVM) InitiateOutbound(
 
 	if err != nil && !isContractReverted {
 		// exceptional case; internal error; should abort CCTX
-		config.CCTX.SetAbort(
-			"error during deposit that is not smart contract revert",
-			err.Error())
+		config.CCTX.SetAbort(types.StatusMessages{
+			StatusMessage:        "outbound failed deposit to ZEVM failed but contract call did not revert",
+			ErrorMessageOutbound: fmt.Sprintf("error from EVMDeposit: %s", err.Error()),
+		})
 		return types.CctxStatus_Aborted, err
 	}
 

x/crosschain/keeper/cctx_orchestrator_validate_outbound.go

@@ -45,20 +45,25 @@
 	if depositErr != nil && isContractReverted {
 		tmpCtxRevert, commitRevert := ctx.CacheContext()
 		// contract call reverted; should refund via a revert tx
-		err := k.processFailedOutboundOnExternalChain(
+		reverErr := k.processFailedOutboundOnExternalChain(
 			tmpCtxRevert,
 			cctx,
 			types.CctxStatus_PendingOutbound,
 			depositErr.Error(),
 			cctx.InboundParams.Amount,
 		)
-		if err != nil {
+		if reverErr != nil {
+			// Error here would mean the outbound tx failed and we also failed to create a revert tx.
+			// This is the only case where we set outbound and revert messages,
+			// as both the outbound and the revert failed in the same block
 			cctx.SetAbort(
-				"revert failed",
-				fmt.Sprintf("deposit error: %s, processing error: %s", depositErr.Error(), err.Error()))
+				types.StatusMessages{
+					StatusMessage:        fmt.Sprintf("revert failed"),
+					ErrorMessageOutbound: depositErr.Error(),
+					ErrorMessageRevert:   reverErr.Error(),
+				})
 			return types.CctxStatus_Aborted
 		}
-
 		commitRevert()
 		return types.CctxStatus_PendingRevert
 	}
@@ -124,7 +129,9 @@
 	if cctx.InboundParams.CoinType == coin.CoinType_Cmd {
 		// if the cctx is of coin type cmd or the sender chain is zeta chain, then we do not revert, the cctx is aborted
 		cctx.GetCurrentOutboundParam().TxFinalizationStatus = types.TxFinalizationStatus_Executed
-		cctx.SetAbort("", "outbound failed for admin tx")
+		cctx.SetAbort(types.StatusMessages{
+			StatusMessage: "outbound failed for admin tx",
+		})
 	} else if chains.IsZetaChain(cctx.InboundParams.SenderChainId, k.GetAuthorityKeeper().GetAdditionalChainList(ctx)) {
 		switch cctx.InboundParams.CoinType {
 		// Try revert if the coin-type is ZETA
@@ -139,7 +146,10 @@
 		default:
 			{
 				cctx.GetCurrentOutboundParam().TxFinalizationStatus = types.TxFinalizationStatus_Executed
-				cctx.SetAbort("", "outbound failed for non-ZETA cctx")
+				cctx.SetAbort(types.StatusMessages{
+					StatusMessage:        "outbound failed for non-ZETA cctx",
+					ErrorMessageOutbound: fmt.Sprintf("coin type %s not supported for revert when source chain is Zetachain", cctx.InboundParams.CoinType),
+				})
 			}
 		}
 	} else {
@@ -158,7 +168,7 @@
 	ctx sdk.Context,
 	cctx *types.CrossChainTx,
 	oldStatus types.CctxStatus,
-	revertMsg string,
+	errorMsg string,
 	inputAmount math.Uint,
 ) error {
 	switch oldStatus {
@@ -210,10 +220,16 @@
 			return err
 		}
 		// Not setting the finalization status here, the required changes have been made while creating the revert tx
-		cctx.SetPendingRevert("", revertMsg)
+		cctx.SetPendingRevert(types.StatusMessages{
+			StatusMessage:        "outbound failed",
+			ErrorMessageOutbound: errorMsg,
+		})
 	case types.CctxStatus_PendingRevert:
 		cctx.GetCurrentOutboundParam().TxFinalizationStatus = types.TxFinalizationStatus_Executed
-		cctx.SetAbort("aborted while processing failed outbound", "outbound and revert failed")
+		cctx.SetAbort(types.StatusMessages{
+			StatusMessage:      "revert failed",
+			ErrorMessageRevert: errorMsg,
+		})
 	}
 	return nil
 }
@@ -240,9 +256,9 @@
 	oldStatus := cctx.CctxStatus.Status
 	switch oldStatus {
 	case types.CctxStatus_PendingRevert:
-		cctx.SetReverted("", "")
+		cctx.SetReverted(types.StatusMessages{StatusMessage: "revert successful"})
 	case types.CctxStatus_PendingOutbound:
-		cctx.SetOutboundMined("")
+		cctx.SetOutboundMined(types.StatusMessages{StatusMessage: "outbound mined successfully"})
 	default:
 		return
 	}
@@ -270,8 +286,12 @@
 		return fmt.Errorf("failed AddRevertOutbound: %s", err.Error())
 	}
 
-	// Trying to revert the transaction this would get set to a finalized status in the same block as this does not need a TSS singing
-	cctx.SetPendingRevert("", "outbound failed")
+	// Trying to revert the transaction, this would get set to a finalized status in the same block as this does not need a TSS singing
+	// The outbound failed due to majority of observer voting failure.We do not have the exact reason for the failure available on chain.
+	cctx.SetPendingRevert(types.StatusMessages{
+		StatusMessage:        "outbound failed",
+		ErrorMessageOutbound: "outbound failed to external chain ,start revert",
+	})
 	data, err := base64.StdEncoding.DecodeString(cctx.RelayedMessage)
 	if err != nil {
 		return fmt.Errorf("failed decoding relayed message: %s", err.Error())
@@ -305,7 +325,10 @@
 		return fmt.Errorf("failed ZETARevertAndCallContract: %s", err.Error())
 	}
 
-	cctx.SetReverted("", "outbound failed")
+	cctx.SetReverted(types.StatusMessages{
+		StatusMessage: "revert successful",
+	})
+
 	if len(ctx.TxBytes()) > 0 {
 		// add event for tendermint transaction hash format
 		hash := tmbytes.HexBytes(tmtypes.Tx(ctx.TxBytes()).Hash())
@@ -350,7 +373,10 @@
 		}
 
 		// update status
-		cctx.SetPendingRevert("", "outbound failed")
+		cctx.SetPendingRevert(types.StatusMessages{
+			StatusMessage:        "outbound failed",
+			ErrorMessageOutbound: "outbound failed to external chain ,start revert",
+		})
 
 		// process the revert on ZEVM
 		if err := k.fungibleKeeper.ProcessV2RevertDeposit(
@@ -368,7 +394,9 @@
 		}
 
 		// tx is reverted
-		cctx.SetReverted("", "outbound failed")
+		cctx.SetReverted(types.StatusMessages{
+			StatusMessage: "revert successful",
+		})
 
 		// add event for tendermint transaction hash format
 		if len(ctx.TxBytes()) > 0 {
@@ -381,7 +409,10 @@
 		cctx.GetCurrentOutboundParam().TxFinalizationStatus = types.TxFinalizationStatus_Executed
 	case types.CctxStatus_PendingRevert:
 		cctx.GetCurrentOutboundParam().TxFinalizationStatus = types.TxFinalizationStatus_Executed
-		cctx.SetAbort("aborted while processing failed outbound", "outbound and revert failed")
+		cctx.SetAbort(types.StatusMessages{
+			StatusMessage:      "revert failed",
+			ErrorMessageRevert: "outbound and revert failed",
+		})
 	}
 	return nil
 }

x/crosschain/keeper/evm_deposit.go

@@ -48,7 +48,7 @@
 		// 	- Return false will abort the cctx
 		indexBytes, err := cctx.GetCCTXIndexBytes()
 		if err != nil {
-			return false, err
+			return false, errors.Wrap(types.ErrUnableToParseCCTXIndexBytes, err.Error())
 		}
 		data, err := base64.StdEncoding.DecodeString(cctx.RelayedMessage)
 		if err != nil {

x/crosschain/keeper/initiate_outbound.go

@@ -38,6 +38,6 @@ func (k Keeper) InitiateOutbound(ctx sdk.Context, config InitiateOutboundConfig)
 		)
 	}
 
-	config.CCTX.SetPendingOutbound("")
+	config.CCTX.SetPendingOutbound(types.StatusMessages{StatusMessage: "initiating outbound"})
 	return cctxGateway.InitiateOutbound(ctx, config)
 }