diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 774a7e4..0d59e2e 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,4 +1,5 @@ * General Guides +** xref:guides/weights_fees.adoc[weights_fees] * Runtime Descriptions * Pallet Specifications ** xref:pallets/proxy.adoc[pallet_proxy] diff --git a/docs/modules/ROOT/pages/guides/weights_fees.adoc b/docs/modules/ROOT/pages/guides/weights_fees.adoc new file mode 100644 index 0000000..44e0e0e --- /dev/null +++ b/docs/modules/ROOT/pages/guides/weights_fees.adoc @@ -0,0 +1,77 @@ +:source-highlighter: highlight.js +:highlightjs-languages: rust +:github-icon: pass:[] + += Weights & Fees + +Weight provides a metric to estimate the time it takes to execute code. + +By assigning a weight to every transaction, Substrate uses this metric to bound the time it takes to execute and verify each batch of transactions organized into a block. + +By converting the transaction's weight to fees, Substrate charges the transaction's caller with fees in proportion to the cost of execution. + +Table of Contents: +** Limit and bound non-linear complexity +** Weights should be conservative +** Underestimating weight exposes DDOS +** Steps To Generate Runtime-Specific Weights +** References + +== Limit and bound non-linear complexity + +TODO + +== Weights should be conservative + +To limit the execution time for each block, runtime constraints on Weight implicitly enforce upper bounds on computation and storage changes per block. + +TODO: which runtime constraints and how are they enforced? + +TODO + +== Underestimating weight exposes DDOS + +* Important that benchmarking hardware is not significantly more high performance than the hardware used by nodes participating in network consensus (i.e. validators, collators) + +* Using worse hardware (i.e. developer hardware) does take longer and, therefore, indirectly underestimates weights. + + +== Steps to Generate Runtime-Specific Weights + +TODO: why are runtime-specific weights important + +1. Ensure Compilation With Runtime Benchmarks +2. Generate Weights Using Production Hardware +3. Write Weights to Runtime +4. Automate via Bench Bot + +=== Ensure Compilation With Runtime Benchmarks + +* compile `cargo build --features runtime-benchmarks` +* compile `cargo build --release --features runtime-benchmarks` +* Enforce with CI + +=== Generate Weights Using Production Hardware + +Technically, *Weight* represents the time it takes to execute code on *production hardware* used by nodes actively participating in the network's consensus. + +``` +1 unit of weight = 1 picosecond of execution time on target reference hardware +``` + +https://wiki.polkadot.network/docs/maintain-guides-how-to-validate-polkadot#:~:text=Reference%20Hardware%E2%80%8B,instance%20on%20GCP%20and%20c6i.[Polkadot Reference Hardware Docs] provides more information on Polkadot validator hardware requirements. + +It is important to ONLY generate weights by running `cargo build --features runtime-benchmarks --release` on *production hardware*. + +=== Write Weights to Runtime. + +TODO: where/why + +=== Automate via Bench Bot + +* examples and references + +== References + +** *https://www.shawntabrizi.com/blog/substrate/substrate-weight-and-fees/[Substrate Weight & Fees] by https://github.com/shawntabrizi/[Shawn Tabrizi]* +