From 405320104663ab56e5fd33058e294f21f4ca5ced Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Drwi=C4=99ga?= <tomusdrw@users.noreply.github.com>
Date: Sat, 15 Feb 2020 10:41:42 +0100
Subject: [PATCH] Remove rename for finalized event and add some docs. (#4930)
* Remove rename for finalized event.
* ADd some docs.
* Document timeout.
---
.../primitives/transaction-pool/src/pool.rs | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/substrate/primitives/transaction-pool/src/pool.rs b/substrate/primitives/transaction-pool/src/pool.rs
index 6912bc79d6e..8d8ff47cbe3 100644
--- a/substrate/primitives/transaction-pool/src/pool.rs
+++ b/substrate/primitives/transaction-pool/src/pool.rs
@@ -67,16 +67,22 @@ impl PoolStatus {
/// 2. Inside `Ready` queue:
/// - `Broadcast`
/// 3. Leaving the pool:
-/// - `Finalized`
+/// - `InBlock`
/// - `Invalid`
/// - `Usurped`
/// - `Dropped`
+/// 4. Re-entering the pool:
+/// - `Retracted`
+/// 5. Block finalized:
+/// - `Finalized`
+/// - `FinalityTimeout`
///
/// 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.
+/// I.e. only one of the listed ones should be triggered.
///
/// 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
@@ -86,8 +92,15 @@ impl PoolStatus {
/// 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).
+/// 4. `Retracted` transactions might be included in some next block.
///
-/// However the user needs to re-subscribe to receive such notifications.
+/// The stream is considered finished only when either `Finalized` or `FinalityTimeout`
+/// event is triggered. You are however free to unsubscribe from notifications at any point.
+/// The first one will be emitted when the block, in which transaction was included gets
+/// finalized. The `FinalityTimeout` event will be emitted when the block did not reach finality
+/// within 512 blocks. This either indicates that finality is not available for your chain,
+/// or that finality gadget is lagging behind. If you choose to wait for finality longer, you can
+/// re-subscribe for a particular transaction hash manually again.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum TransactionStatus<Hash, BlockHash> {
@@ -98,7 +111,6 @@ pub enum TransactionStatus<Hash, BlockHash> {
/// 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),
/// The block this transaction was included in has been retracted.
Retracted(BlockHash),
--
GitLab