From 795b63e68673d1f770233604d62108517e171005 Mon Sep 17 00:00:00 2001 From: 4meta5 Date: Sun, 10 Dec 2023 21:13:47 -0500 Subject: [PATCH 1/7] init transaction payment doc --- docs/modules/ROOT/nav.adoc | 3 +- .../pages/pallet_transaction_payment.adoc | 86 +++++++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 docs/modules/ROOT/pages/pallet_transaction_payment.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 80121a4..6489733 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,3 +1,4 @@ * General Guides * Runtime Descriptions -* Pallet Specifications \ No newline at end of file +* Pallet Specifications +* [Pallet Transaction Payment](./pages/pallet_transaction_payment.adoc) \ No newline at end of file diff --git a/docs/modules/ROOT/pages/pallet_transaction_payment.adoc b/docs/modules/ROOT/pages/pallet_transaction_payment.adoc new file mode 100644 index 0000000..d979d15 --- /dev/null +++ b/docs/modules/ROOT/pages/pallet_transaction_payment.adoc @@ -0,0 +1,86 @@ +:source-highlighter: highlight.js +:highlightjs-languages: rust +:github-icon: pass:[] + += Transaction Payment link:https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/transaction-payment[{github-icon},role=heading-link] + +== Purpose + +`pallet-transaction-payment` implements transaction fee logic. + +To implement this pallet, the runtime configures a mapping between the minimum unit of computation/block space (*Weight*) and the minimum unit of fees ([`Config::WeightToFee`]). + +This pallet also exposes +- how to update fees for the next block based on past fees ([`Config::FeeMultiplierUpdate`]). +- how fees are paid ([`Config::OnChargeTransaction`]). + +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. +The formula of final fee: +```ignore +inclusion_fee = base_fee + length_fee + [targeted_fee_adjustment * weight_fee]; +final_fee = inclusion_fee + tip; +``` +- `targeted_fee_adjustment`: This is a multiplier that can tune the final fee based on +the congestion of the network. +- `weight_fee`: A fee proportional to amount of weight a transaction consumes. +- `length_fee`: A fee proportional to the encoded length of the transaction. +- `tip`: An optional tip. Tip increases the priority of the transaction, giving it a higher +chance to be included by the transaction queue. + +== Glossary + +- _weight_: time it takes to execute a transaction in the body of a block. By controlling the execution time that a block can consume, weight bounds the storage changes and computation per block. +- _weight fee_: A fee proportional to amount of weight a transaction consumes. +- _length fee_: A fee proportional to the encoded length of the transaction. +- _tip_: An optional tip. Tip increases the priority of the transaction, giving it a higher chance to be included by the transaction queue. + +== config + +- [`Config::WeightToFee`]: The mapping between one unit of weight to one unit of fee. +- [`Config::FeeMultiplierUpdate`]: A means of updating the fee for the next block, via defining a multiplier, based on the +final state of the chain at the end of the previous block. Possible values include `ConstantFee`, SlowAdjustingFee`, FastAdjustingFee`, etc. +- [`Config::OnChargeTransaction`]: A means of defining the storage and state changes associated with paying transaction fees. + +== Dispatchables + +[.contract-item] +[[dispatchable_name]] +==== `[.contract-item-name]#++dispatchable_name++#` +[source,rust] +---- +pub fn dispatchable_name( + param1: Type1, + param2: Type2 +) -> DispatchResult +---- +Freeform description of the dispatchable. It is good to include the important things that should be included there. + +// four following blocks show how to make a higlight of some information. It will become a styled block + +NOTE: This is how you state important information that should be acknowledged + +IMPORTANT: This is how you put some information that should not be missed + +WARNING: This thing is for important information missing which may lead to dangerous consequences + +TIP: This is how you should give some useful advice + +**Params:** + +* `param1: Type1` -- description of the parameter + +**Errors:** + +* `ErrorName` -- description of conditions, when this error happens + +**Events:** + +* `EventName(param1, param2)` -- description of event, if needed (they are often self-explanatory) + +== More Reading + +- [Substrate Weight & Fees](https://www.shawntabrizi.com/blog/substrate/substrate-weight-and-fees/) by Shawn Tabrizi +* [Substrate Docs: Transaction Weight & Fees]https://docs.substrate.io/build/tx-weights-fees/ +* [Substrate Docs: How to Calculate Fees](https://docs.substrate.io/reference/how-to-guides/weights/calculate-fees/#:~:text=Weight%20fee%20%2D%20A%20fee%20calculated,change%20as%20the%20chain%20progresses) + From a461a7d959d3763747579eb5e1295c9218a2f5d2 Mon Sep 17 00:00:00 2001 From: 4meta5 Date: Fri, 15 Dec 2023 16:46:28 -0500 Subject: [PATCH 2/7] fix --- .../modules/ROOT/pages/pallet_transaction_payment.adoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/modules/ROOT/pages/pallet_transaction_payment.adoc b/docs/modules/ROOT/pages/pallet_transaction_payment.adoc index d979d15..ad5fcb2 100644 --- a/docs/modules/ROOT/pages/pallet_transaction_payment.adoc +++ b/docs/modules/ROOT/pages/pallet_transaction_payment.adoc @@ -8,16 +8,18 @@ `pallet-transaction-payment` implements transaction fee logic. -To implement this pallet, the runtime configures a mapping between the minimum unit of computation/block space (*Weight*) and the minimum unit of fees ([`Config::WeightToFee`]). +In substrate, every transaction has an associated `pallet::call`, and each `pallet::call` has a weight function. The weight function estimates the time it takes to execute the call. -This pallet also exposes +[`Config::WeightToFee`] is set to a mapping between the smallest unit of compute (*Weight*) and smallest unit of fee. + +The pallet also exposes - how to update fees for the next block based on past fees ([`Config::FeeMultiplierUpdate`]). - how fees are paid ([`Config::OnChargeTransaction`]). 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. The formula of final fee: -```ignore +```rust,ignore inclusion_fee = base_fee + length_fee + [targeted_fee_adjustment * weight_fee]; final_fee = inclusion_fee + tip; ``` @@ -37,7 +39,7 @@ chance to be included by the transaction queue. == config -- [`Config::WeightToFee`]: The mapping between one unit of weight to one unit of fee. +- [`Config::WeightToFee`]: mapping between the smallest unit of weight and smallest unit of fee - [`Config::FeeMultiplierUpdate`]: A means of updating the fee for the next block, via defining a multiplier, based on the final state of the chain at the end of the previous block. Possible values include `ConstantFee`, SlowAdjustingFee`, FastAdjustingFee`, etc. - [`Config::OnChargeTransaction`]: A means of defining the storage and state changes associated with paying transaction fees. From 26fc900a7dca0888f246c832b293c64347487bba Mon Sep 17 00:00:00 2001 From: 4meta5 Date: Fri, 15 Dec 2023 17:13:37 -0500 Subject: [PATCH 3/7] reduce scope to only transaction fee pallet to improve reviewability --- .../pallets/pallet_transaction_payment.adoc | 80 ++++++------------- 1 file changed, 24 insertions(+), 56 deletions(-) diff --git a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc index e1f973c..3d3fa64 100644 --- a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc +++ b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc @@ -2,48 +2,44 @@ :highlightjs-languages: rust :github-icon: pass:[] -= Transaction Payment link:https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/transaction-payment[{github-icon},role=heading-link] += Transaction Payment link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.3.0/substrate/frame/transaction-payment[{github-icon},role=heading-link] == Purpose `pallet-transaction-payment` implements transaction fee logic. -In substrate, every transaction has an associated `pallet::call`, and each `pallet::call` has a weight function. The weight function estimates the time it takes to execute the call. +In substrate, every transaction has an associated `call`, and each `call` has its own weight function. The weight function estimates the time it takes to execute the `call`. -[`Config::WeightToFee`] is set to a mapping between the smallest unit of compute (*Weight*) and smallest unit of fee. +`Config::WeightToFee` is a mapping between the smallest unit of compute (*Weight*) and smallest unit of fee. -The pallet also exposes -- how to update fees for the next block based on past fees ([`Config::FeeMultiplierUpdate`]). -- how fees are paid ([`Config::OnChargeTransaction`]). +This pallet also exposes +- how to update fees for the next block based on past fees (`Config::FeeMultiplierUpdate`) +- how fees are paid (`Config::OnChargeTransaction`) -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. -The formula of final fee: -```rust,ignore -inclusion_fee = base_fee + length_fee + [targeted_fee_adjustment * weight_fee]; +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. The formula of final fee: +```rust, ignore +inclusion_fee = base_fee + length_fee + [fee_multiplier_update * weight_fee]; final_fee = inclusion_fee + tip; ``` -- `targeted_fee_adjustment`: This is a multiplier that can tune the final fee based on -the congestion of the network. -- `weight_fee`: A fee proportional to amount of weight a transaction consumes. -- `length_fee`: A fee proportional to the encoded length of the transaction. -- `tip`: An optional tip. Tip increases the priority of the transaction, giving it a higher -chance to be included by the transaction queue. +The inputs are defined below in the glossary and config sections. == Glossary -- _weight_: time it takes to execute a transaction in the body of a block. By controlling the execution time that a block can consume, weight bounds the storage changes and computation per block. -- _weight fee_: A fee proportional to amount of weight a transaction consumes. -- _length fee_: A fee proportional to the encoded length of the transaction. -- _tip_: An optional tip. Tip increases the priority of the transaction, giving it a higher chance to be included by the transaction queue. +** `Weight` -- The time it takes to execute runtime logic. By controlling the execution time that a block can consume, weight bounds the storage changes and computation per block. +** `WeightFee` -- A fee proportional to amount of weight a transaction consumes. +** `LengthFee` -- A fee proportional to the encoded length of the transaction. +** `Tip` -- An optional tip. Tip increases the priority of the transaction, giving it a higher chance to be included by the transaction queue. == Config link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.3.0/substrate/frame/pallet-transaction-payment/src/lib.rs#L445[{github-icon},role=heading-link] -* Pallet-specific configs: -** `WeightToFee` -- mapping between the smallest unit of weight and smallest unit of fee -** `Config::FeeMultiplierUpdate` -- A means of updating the fee for the next block, via defining a multiplier, based on the -final state of the chain at the end of the previous block. Possible values include `ConstantFee`, SlowAdjustingFee`, FastAdjustingFee`, etc. -** `Config::OnChargeTransaction` -- A means of defining the storage and state changes associated with paying transaction fees. +* Pallet-specific handlers: +** `OnChargeTransaction` -- Handler for withdrawing, refunding and depositing the transaction fee. Type must implement the trait `OnChargeTransaction`. +** `FeeMultiplierUpdate` -- Handler to define how base fees change over time (over blocks). Type must implement the trait `MultiplierUpdate`. Possible assignments include `ConstantFee`, SlowAdjustingFee`, and `FastAdjustingFee`. +* Pallet-specific converters: +** `WeightToFee` -- Mapping between the smallest unit of weight and smallest unit of fee. Type must implement the trait `WeightToFee>`. +** `LengthToFee` -- Convert a length value into a deductible fee based on the currency type. Type must implement the trait `WeightToFee>`. +* Pallet-specific constants: +** `OperationalFeeMultiplier` -- A fee mulitiplier for `Operational` extrinsics to compute "virtual tip" to boost their `priority`. Type must implement the trait `Get`. * Common configs: ** `RuntimeEvent` ** `Currency` @@ -51,39 +47,11 @@ final state of the chain at the end of the previous block. Possible values inclu == Dispatchables -[.contract-item] -[[dispatchable_name]] -==== `[.contract-item-name]#++dispatchable_name++#` -[source,rust] ----- -pub fn dispatchable_name( - param1: Type1, - param2: Type2 -) -> DispatchResult ----- -Freeform description of the dispatchable. It is good to include the important things that should be included there. - -// four following blocks show how to make a higlight of some information. It will become a styled block - -NOTE: This is how you state important information that should be acknowledged - -IMPORTANT: This is how you put some information that should not be missed - -WARNING: This thing is for important information missing which may lead to dangerous consequences - -TIP: This is how you should give some useful advice - -**Params:** - -* `param1: Type1` -- description of the parameter - -**Errors:** - -* `ErrorName` -- description of conditions, when this error happens +There are no dispatchables (and no errors) in this pallet. This pallet is only intended to configure the transaction fee logic for a chain. **Events:** -* `EventName(param1, param2)` -- description of event, if needed (they are often self-explanatory) +* `TransactionFeePaid(who, actual_fee, tip)` -- a transaction fee was paid by account `who` with total amount of `actual_fee + tip`. == More Reading From 4f4c43e7842155c0e420f797c899080d384bea8c Mon Sep 17 00:00:00 2001 From: Amar Singh Date: Fri, 15 Dec 2023 17:18:06 -0500 Subject: [PATCH 4/7] Update docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc --- docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc index 3d3fa64..bc794e5 100644 --- a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc +++ b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc @@ -34,7 +34,7 @@ The inputs are defined below in the glossary and config sections. * Pallet-specific handlers: ** `OnChargeTransaction` -- Handler for withdrawing, refunding and depositing the transaction fee. Type must implement the trait `OnChargeTransaction`. -** `FeeMultiplierUpdate` -- Handler to define how base fees change over time (over blocks). Type must implement the trait `MultiplierUpdate`. Possible assignments include `ConstantFee`, SlowAdjustingFee`, and `FastAdjustingFee`. +** `FeeMultiplierUpdate` -- Handler to define how base fees change over time (over blocks). Type must implement the trait `MultiplierUpdate`. Possible assignments include `ConstantFee`, `SlowAdjustingFee`, and `FastAdjustingFee`. * Pallet-specific converters: ** `WeightToFee` -- Mapping between the smallest unit of weight and smallest unit of fee. Type must implement the trait `WeightToFee>`. ** `LengthToFee` -- Convert a length value into a deductible fee based on the currency type. Type must implement the trait `WeightToFee>`. From 98b3619363b714580f17d7c70d9278a110d7bd94 Mon Sep 17 00:00:00 2001 From: Amar Singh Date: Fri, 15 Dec 2023 17:18:57 -0500 Subject: [PATCH 5/7] Update docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc --- docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc index bc794e5..25c749b 100644 --- a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc +++ b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc @@ -42,8 +42,6 @@ The inputs are defined below in the glossary and config sections. ** `OperationalFeeMultiplier` -- A fee mulitiplier for `Operational` extrinsics to compute "virtual tip" to boost their `priority`. Type must implement the trait `Get`. * Common configs: ** `RuntimeEvent` -** `Currency` -** `WeightInfo` == Dispatchables From 1f9a285d07351fb4269e43d2432b65595ecb58e2 Mon Sep 17 00:00:00 2001 From: 4meta5 Date: Sun, 17 Dec 2023 21:35:52 -0500 Subject: [PATCH 6/7] clean --- .../ROOT/pages/pallets/pallet_transaction_payment.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc index 25c749b..deb0d84 100644 --- a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc +++ b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc @@ -53,7 +53,7 @@ There are no dispatchables (and no errors) in this pallet. This pallet is only i == More Reading -- [Substrate Weight & Fees](https://www.shawntabrizi.com/blog/substrate/substrate-weight-and-fees/) by Shawn Tabrizi -* [Substrate Docs: Transaction Weight & Fees]https://docs.substrate.io/build/tx-weights-fees/ -* [Substrate Docs: How to Calculate Fees](https://docs.substrate.io/reference/how-to-guides/weights/calculate-fees/#:~:text=Weight%20fee%20%2D%20A%20fee%20calculated,change%20as%20the%20chain%20progresses) +** https://www.shawntabrizi.com/blog/substrate/substrate-weight-and-fees/[Substrate Weight & Fees] by Shawn Tabrizi +* https://docs.substrate.io/build/tx-weights-fees/[Substrate Docs: Transaction Weight & Fees] +** https://docs.substrate.io/reference/how-to-guides/weights/calculate-fees/#:~:text=Weight%20fee%20%2D%20A%20fee%20calculated,change%20as%20the%20chain%20progresses[Substrate Docs: How to Calculate Fees] From ed61c11263799cf226af10a24d80ad9cc30d62d6 Mon Sep 17 00:00:00 2001 From: 4meta5 Date: Mon, 18 Dec 2023 08:11:14 -0500 Subject: [PATCH 7/7] fmt --- .../ROOT/pages/pallets/pallet_transaction_payment.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc index deb0d84..7d414d3 100644 --- a/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc +++ b/docs/modules/ROOT/pages/pallets/pallet_transaction_payment.adoc @@ -2,7 +2,9 @@ :highlightjs-languages: rust :github-icon: pass:[] -= Transaction Payment link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.3.0/substrate/frame/transaction-payment[{github-icon},role=heading-link] += pallet_transaction_payment + +Branch/Release: `release-polkadot-v{1.3.0}` == Purpose