From 1b2c3340f4073a2ce2f2debdc19bd156253bc40f Mon Sep 17 00:00:00 2001 From: Derek Brans Date: Thu, 6 Jun 2024 14:04:34 -0400 Subject: [PATCH 1/2] document TransactionStatus enum --- packages/transaction-controller/src/types.ts | 66 ++++++++++++++++---- 1 file changed, 53 insertions(+), 13 deletions(-) diff --git a/packages/transaction-controller/src/types.ts b/packages/transaction-controller/src/types.ts index c84593ab406..cb2c318f77f 100644 --- a/packages/transaction-controller/src/types.ts +++ b/packages/transaction-controller/src/types.ts @@ -450,39 +450,79 @@ export type SendFlowHistoryEntry = { }; /** - * The status of the transaction. Each status represents the state of the transaction internally - * in the wallet. Some of these correspond with the state of the transaction on the network, but - * some are wallet-specific. + * Represents the status of a transaction within the wallet. + * Each status reflects the state of the transaction internally, + * with some statuses corresponding to the transaction's state on the network. */ export enum TransactionStatus { + /** + * The initial state of a transaction before user approval. + */ // TODO: Either fix this lint violation or explain why it's necessary to ignore. // eslint-disable-next-line @typescript-eslint/naming-convention - approved = 'approved', - /** @deprecated Determined by the clients using the transaction type. No longer used. */ + unapproved = 'unapproved', + + /** + * The transaction has been approved by the user but is not yet signed. + * This status is usually brief but may be longer for scenarios like hardware wallet usage. + */ // TODO: Either fix this lint violation or explain why it's necessary to ignore. // eslint-disable-next-line @typescript-eslint/naming-convention - cancelled = 'cancelled', + approved = 'approved', + + /** + * The transaction is signed and in the process of being submitted to the network. + * This status is typically short-lived but can be longer for certain cases, such as smart transactions. + */ // TODO: Either fix this lint violation or explain why it's necessary to ignore. // eslint-disable-next-line @typescript-eslint/naming-convention - confirmed = 'confirmed', + signed = 'signed', + + /** + * The transaction has been submitted to the network and is awaiting confirmation. + */ // TODO: Either fix this lint violation or explain why it's necessary to ignore. // eslint-disable-next-line @typescript-eslint/naming-convention - dropped = 'dropped', + submitted = 'submitted', + + /** + * The transaction has been successfully executed and confirmed on the blockchain. + * This is a final state. + */ // TODO: Either fix this lint violation or explain why it's necessary to ignore. // eslint-disable-next-line @typescript-eslint/naming-convention - failed = 'failed', + confirmed = 'confirmed', + + /** + * The transaction encountered an error during execution on the blockchain and failed. + * This is a final state. + */ // TODO: Either fix this lint violation or explain why it's necessary to ignore. // eslint-disable-next-line @typescript-eslint/naming-convention - rejected = 'rejected', + failed = 'failed', + + /** + * The transaction was superseded by another transaction, resulting in its dismissal. + * This is a final state. + */ // TODO: Either fix this lint violation or explain why it's necessary to ignore. // eslint-disable-next-line @typescript-eslint/naming-convention - signed = 'signed', + dropped = 'dropped', + + /** + * The transaction was rejected by the user and not processed further. + * This is a final state. + */ // TODO: Either fix this lint violation or explain why it's necessary to ignore. // eslint-disable-next-line @typescript-eslint/naming-convention - submitted = 'submitted', + rejected = 'rejected', + + /** + * @deprecated This status is no longer used. + */ // TODO: Either fix this lint violation or explain why it's necessary to ignore. // eslint-disable-next-line @typescript-eslint/naming-convention - unapproved = 'unapproved', + cancelled = 'cancelled', } /** From 9e07236218ee8e78308fdbe29da097d0ee69e928 Mon Sep 17 00:00:00 2001 From: Derek Brans Date: Thu, 6 Jun 2024 14:12:36 -0400 Subject: [PATCH 2/2] updated comment with typical lifecycle --- packages/transaction-controller/src/types.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/transaction-controller/src/types.ts b/packages/transaction-controller/src/types.ts index cb2c318f77f..9cbc4e0cd72 100644 --- a/packages/transaction-controller/src/types.ts +++ b/packages/transaction-controller/src/types.ts @@ -453,6 +453,10 @@ export type SendFlowHistoryEntry = { * Represents the status of a transaction within the wallet. * Each status reflects the state of the transaction internally, * with some statuses corresponding to the transaction's state on the network. + * + * The typical transaction lifecycle follows this state machine: + * unapproved -> approved -> signed -> submitted -> FINAL_STATE + * where FINAL_STATE is one of: confirmed, failed, dropped, or rejected. */ export enum TransactionStatus { /**