diff --git a/client/transaction-pool/README.md b/client/transaction-pool/README.md index 28846fdbb38f..e4f8ccb3d810 100644 --- a/client/transaction-pool/README.md +++ b/client/transaction-pool/README.md @@ -79,12 +79,15 @@ Field-specific rules are described below. ### `requires` / `provides` These two fields contain a set of `TransactionTag`s (opaque blobs) associated with -given transaction. Looking at these fields we can find dependencies between -transactions and their readiness for block inclusion. +a given transaction. This is a mechanism for the runtime to be able to +express dependencies between transactions (that this transaction pool can take +account of). By looking at these fields we can establish a transaction's readiness +for block inclusion. The `provides` set contains properties that will be *satisfied* in case the transaction -is successfully added to a block. `requires` contains properties that must be satisfied -**before** the transaction can be included to a block. +is successfully added to a block. Only a transaction in a block may provide a specific +tag. `requires` contains properties that must be satisfied **before** the transaction +can be included to a block. Note that a transaction with empty `requires` set can be added to a block immediately, there are no other transactions that it expects to be included before. @@ -131,7 +134,7 @@ Transaction priority describes importance of the transaction relative to other t in the pool. Block authors can expect benefiting from including such transactions before others. -Note that we can't simply order transactions in the pool by `priority`, cause first +Note that we can't simply order transactions in the pool by `priority`, because first we need to make sure that all of the transaction requirements are satisfied (see `requires/provides` section). However if we consider a set of transactions which all have their requirements (tags) satisfied, the block author should be @@ -234,7 +237,7 @@ feasible, so the actual implementation might need to take some shortcuts. ## Suggestions & caveats 1. The validity of transaction should not change significantly from block to - block. I.e. changes in validity should happen predicatably, e.g. `longevity` + block. I.e. changes in validity should happen predictably, e.g. `longevity` decrements by 1, `priority` stays the same, `requires` changes if transaction that provided a tag was included in block. `provides` does not change, etc. @@ -360,5 +363,5 @@ queue and attempted to be re-imported by the background task in the future. Runtime calls to verify transactions are performed from a separate (limited) thread pool to avoid interferring too much with other subsystems of the node. We -definitely don't want to have all cores validating network transactions, cause +definitely don't want to have all cores validating network transactions, because all of these transactions need to be considered untrusted (potentially DoS). diff --git a/client/transaction-pool/graph/src/ready.rs b/client/transaction-pool/graph/src/ready.rs index ba6ca97dc675..7b42033f9b50 100644 --- a/client/transaction-pool/graph/src/ready.rs +++ b/client/transaction-pool/graph/src/ready.rs @@ -108,11 +108,13 @@ Hence every hash retrieved from `provided_tags` is always present in `ready`; qed "#; +/// Validated transactions that are block ready with all their dependencies met. #[derive(Debug, parity_util_mem::MallocSizeOf)] pub struct ReadyTransactions { - /// Insertion id + /// Next free insertion id (used to indicate when a transaction was inserted into the pool). insertion_id: u64, /// tags that are provided by Ready transactions + /// (only a single transaction can provide a specific tag) provided_tags: HashMap, /// Transactions that are ready (i.e. don't have any requirements external to the pool) ready: TrackedMap>, @@ -235,7 +237,7 @@ impl ReadyTransactions { .fold(None, f) } - /// Returns true if given hash is part of the queue. + /// Returns true if given transaction is part of the queue. pub fn contains(&self, hash: &Hash) -> bool { self.ready.read().contains_key(hash) } diff --git a/client/transaction-pool/graph/src/watcher.rs b/client/transaction-pool/graph/src/watcher.rs index 6f8eb7c6e566..b93fe3154319 100644 --- a/client/transaction-pool/graph/src/watcher.rs +++ b/client/transaction-pool/graph/src/watcher.rs @@ -24,10 +24,11 @@ use sp_utils::mpsc::{tracing_unbounded, TracingUnboundedSender, TracingUnbounded /// Extrinsic watcher. /// -/// Represents a stream of status updates for particular extrinsic. +/// Represents a stream of status updates for a particular extrinsic. #[derive(Debug)] pub struct Watcher { receiver: TracingUnboundedReceiver>, + /// transaction hash of watched extrinsic hash: H, } diff --git a/primitives/transaction-storage-proof/README.md b/primitives/transaction-storage-proof/README.md index 1aa1805cfc5e..4a93e1d41fa3 100644 --- a/primitives/transaction-storage-proof/README.md +++ b/primitives/transaction-storage-proof/README.md @@ -1,3 +1,5 @@ -Authorship Primitives +Transaction Storage Proof Primitives -License: Apache-2.0 \ No newline at end of file +Contains types and basic code to extract storage proofs for indexed transactions. + +License: Apache-2.0 diff --git a/primitives/transaction-storage-proof/src/lib.rs b/primitives/transaction-storage-proof/src/lib.rs index 825de27b2a5a..0deee8691ff8 100644 --- a/primitives/transaction-storage-proof/src/lib.rs +++ b/primitives/transaction-storage-proof/src/lib.rs @@ -15,7 +15,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! Storge proof primitives. Constains types and basic code to extract storage +//! Storage proof primitives. Constains types and basic code to extract storage //! proofs for indexed transactions. #![cfg_attr(not(feature = "std"), no_std)] @@ -49,6 +49,8 @@ impl IsFatalError for InherentError { } } +/// Holds a chunk of data retrieved from storage along with +/// a proof that the data was stored at that location in the trie. #[derive(Encode, Decode, Clone, PartialEq, Debug)] pub struct TransactionStorageProof { /// Data chunk that is proved to exist. @@ -108,7 +110,7 @@ impl sp_inherents::InherentDataProvider for InherentDataProvider { } } -/// An utility function to extract chunk index from the source of randomness. +/// A utility function to extract a chunk index from the source of randomness. pub fn random_chunk(random_hash: &[u8], total_chunks: u32) -> u32 { let mut buf = [0u8; 8]; buf.copy_from_slice(&random_hash[0..8]); @@ -116,18 +118,24 @@ pub fn random_chunk(random_hash: &[u8], total_chunks: u32) -> u32 { (random_u64 % total_chunks as u64) as u32 } -/// An utility function to enocde transaction index as trie key. +/// A utility function to encode transaction index as trie key. pub fn encode_index(input: u32) -> Vec { codec::Encode::encode(&codec::Compact(input)) } /// An interface to request indexed data from the client. pub trait IndexedBody { + /// Get all indexed transactions for a block, + /// including renewed transactions. + /// + /// Note that this will only fetch transactions + /// that are indexed by the runtime with `storage_index_transaction`. fn block_indexed_body( &self, number: NumberFor, ) -> Result>>, Error>; + /// Get block number for a block hash. fn number( &self, hash: B::Hash, @@ -237,4 +245,3 @@ pub mod registration { ).unwrap(); } } -