docs: document TransactionStatus enum

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',
 }
 
 /**