diff --git a/packages/transaction-controller/src/types.ts b/packages/transaction-controller/src/types.ts index c84593ab406..9cbc4e0cd72 100644 --- a/packages/transaction-controller/src/types.ts +++ b/packages/transaction-controller/src/types.ts @@ -450,39 +450,83 @@ 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. + * + * 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 { + /** + * 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', } /**