Document TransactionStatus and fix termination conditions. (#4446)

* Document TransactionStatus and fix termination conditions.

* Update client/rpc-api/src/author/mod.rs

Co-Authored-By: Bastian Köcher <bkchr@users.noreply.github.com>

substrate/primitives/transaction-pool/src/pool.rs

@@ -55,6 +55,38 @@ impl PoolStatus {
 }
 
 /// Possible transaction status events.
+///
+/// This events are being emitted by `TransactionPool` watchers,
+/// which are also exposed over RPC.
+///
+/// The status events can be grouped based on their kinds as:
+/// 1. Entering/Moving within the pool:
+///		- `Future`
+///		- `Ready`
+/// 2. Inside `Ready` queue:
+///		- `Broadcast`
+/// 3. Leaving the pool:
+///		- `InBlock`
+///		- `Invalid`
+///		- `Usurped`
+///		- `Dropped`
+///
+/// The events will always be received in the order described above, however
+/// there might be cases where transactions alternate between `Future` and `Ready`
+/// pool, and are `Broadcast` in the meantime.
+///
+/// There is also only single event causing the transaction to leave the pool.
+///
+/// Note that there are conditions that may cause transactions to reappear in the pool.
+/// 1. Due to possible forks, the transaction that ends up being in included
+/// in one block, may later re-enter the pool or be marked as invalid.
+/// 2. Transaction `Dropped` at one point, may later re-enter the pool if some other
+/// transactions are removed.
+/// 3. `Invalid` transaction may become valid at some point in the future.
+/// (Note that runtimes are encouraged to use `UnknownValidity` to inform the pool about
+/// such case).
+///
+/// However the user needs to re-subscribe to receive such notifications.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub enum TransactionStatus<Hash, BlockHash> {
@@ -62,15 +94,17 @@ pub enum TransactionStatus<Hash, BlockHash> {
 	Future,
 	/// Transaction is part of the ready queue.
 	Ready,
-	/// Transaction has been finalized in block with given hash.
-	Finalized(BlockHash),
-	/// Some state change (perhaps another transaction was included) rendered this transaction invalid.
-	Usurped(Hash),
 	/// The transaction has been broadcast to the given peers.
 	Broadcast(Vec<String>),
+	/// Transaction has been included in block with given hash.
+	#[serde(rename = "finalized")] // See #4438
+	InBlock(BlockHash),
+	/// Transaction has been replaced in the pool, by another transaction
+	/// that provides the same tags. (e.g. same (sender, nonce)).
+	Usurped(Hash),
 	/// Transaction has been dropped from the pool because of the limit.
 	Dropped,
-	/// Transaction was detected as invalid.
+	/// Transaction is no longer valid in the current state.
 	Invalid,
 }