From dd7216af4c1e423148ec8fdc3fdc1f2c4b33655e Mon Sep 17 00:00:00 2001
From: joe petrowski <25483142+joepetrowski@users.noreply.github.com>
Date: Thu, 21 May 2020 16:23:51 +0200
Subject: [PATCH] clarify docs on query_info and partial_fee (#6090)
---
.../rpc/runtime-api/src/lib.rs | 6 ++--
.../frame/transaction-payment/src/lib.rs | 30 ++++++++++++-------
2 files changed, 22 insertions(+), 14 deletions(-)
diff --git a/substrate/frame/transaction-payment/rpc/runtime-api/src/lib.rs b/substrate/frame/transaction-payment/rpc/runtime-api/src/lib.rs
index 43928073389..17a8bcdf44e 100644
--- a/substrate/frame/transaction-payment/rpc/runtime-api/src/lib.rs
+++ b/substrate/frame/transaction-payment/rpc/runtime-api/src/lib.rs
@@ -26,7 +26,7 @@ use codec::{Encode, Codec, Decode};
use serde::{Serialize, Deserialize, Serializer, Deserializer};
use sp_runtime::traits::{MaybeDisplay, MaybeFromStr};
-/// Some information related to a dispatchable that can be queried from the runtime.
+/// Information related to a dispatchable's class, weight, and fee that can be queried from the runtime.
#[derive(Eq, PartialEq, Encode, Decode, Default)]
#[cfg_attr(feature = "std", derive(Debug, Serialize, Deserialize))]
#[cfg_attr(feature = "std", serde(rename_all = "camelCase"))]
@@ -35,8 +35,8 @@ pub struct RuntimeDispatchInfo<Balance> {
pub weight: Weight,
/// Class of this dispatch.
pub class: DispatchClass,
- /// The partial inclusion fee of this dispatch. This does not include tip or anything else which
- /// is dependent on the signature (aka. depends on a `SignedExtension`).
+ /// The inclusion fee of this dispatch. This does not include a tip or anything else that
+ /// depends on the signature (i.e. depends on a `SignedExtension`).
#[cfg_attr(feature = "std", serde(bound(serialize = "Balance: std::fmt::Display")))]
#[cfg_attr(feature = "std", serde(serialize_with = "serialize_as_string"))]
#[cfg_attr(feature = "std", serde(bound(deserialize = "Balance: std::str::FromStr")))]
diff --git a/substrate/frame/transaction-payment/src/lib.rs b/substrate/frame/transaction-payment/src/lib.rs
index 71ef8a56c2f..11b86170e7a 100644
--- a/substrate/frame/transaction-payment/src/lib.rs
+++ b/substrate/frame/transaction-payment/src/lib.rs
@@ -107,8 +107,9 @@ decl_module! {
impl<T: Trait> Module<T> {
/// Query the data that we know about the fee of a given `call`.
///
- /// As this module is not and cannot be aware of the internals of a signed extension, it only
- /// interprets them as some encoded value and takes their length into account.
+ /// This module is not and cannot be aware of the internals of a signed extension, for example
+ /// a tip. It only interprets the extrinsic as some encoded value and accounts for its weight
+ /// and length, the runtime's extrinsic base weight, and the current fee multiplier.
///
/// All dispatchables must be annotated with weight and will have some fee info. This function
/// always returns.
@@ -137,17 +138,24 @@ impl<T: Trait> Module<T> {
/// Compute the final fee value for a particular transaction.
///
/// The final fee is composed of:
- /// - _base_fee_: This is the minimum amount a user pays for a transaction.
- /// - _len_fee_: This is the amount paid merely to pay for size of the transaction.
- /// - _weight_fee_: This amount is computed based on the weight of the transaction. Unlike
- /// size-fee, this is not input dependent and reflects the _complexity_ of the execution
- /// and the time it consumes.
- /// - _targeted_fee_adjustment_: This is a multiplier that can tune the final fee based on
+ /// - `base_fee`: This is the minimum amount a user pays for a transaction. It is declared
+ /// as a base _weight_ in the runtime and converted to a fee using `WeightToFee`.
+ /// - `len_fee`: The length fee, the amount paid for the encoded length (in bytes) of the
+ /// transaction.
+ /// - `weight_fee`: This amount is computed based on the weight of the transaction. Weight
+ /// accounts for the execution time of a transaction.
+ /// - `targeted_fee_adjustment`: This is a multiplier that can tune the final fee based on
/// the congestion of the network.
- /// - (optional) _tip_: if included in the transaction, it will be added on top. Only signed
- /// transactions can have a tip.
+ /// - (Optional) `tip`: If included in the transaction, the tip will be added on top. Only
+ /// signed transactions can have a tip.
///
- /// final_fee = base_fee + targeted_fee_adjustment(len_fee + weight_fee) + tip;
+ /// The base fee and adjusted weight and length fees constitute the _inclusion fee,_ which is
+ /// the minimum fee for a transaction to be included in a block.
+ ///
+ /// ```ignore
+ /// inclusion_fee = base_fee + targeted_fee_adjustment * (len_fee + weight_fee);
+ /// final_fee = inclusion_fee + tip;
+ /// ```
pub fn compute_fee(
len: u32,
info: &DispatchInfoOf<T::Call>,
--
GitLab