From 4c73c83dd3feb7114ac3a2fcd73f48a657b9926c Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Fri, 19 Apr 2024 16:03:15 +0200 Subject: [PATCH 1/9] Initial draft --- Cargo.lock | 5 ++ docs/sdk/Cargo.toml | 5 ++ docs/sdk/src/guides/enable_pov_reclaim.rs | 56 +++++++++++++++++++++++ docs/sdk/src/guides/mod.rs | 3 ++ 4 files changed, 69 insertions(+) create mode 100644 docs/sdk/src/guides/enable_pov_reclaim.rs diff --git a/Cargo.lock b/Cargo.lock index 27cb7af04d63..d33e392d49ec 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -13895,8 +13895,11 @@ dependencies = [ name = "polkadot-sdk-docs" version = "0.0.1" dependencies = [ + "cumulus-client-service", "cumulus-pallet-aura-ext", "cumulus-pallet-parachain-system", + "cumulus-primitives-proof-size-hostfunction", + "cumulus-primitives-storage-weight-reclaim", "docify", "frame-executive", "frame-support", @@ -13934,9 +13937,11 @@ dependencies = [ "sc-consensus-grandpa", "sc-consensus-manual-seal", "sc-consensus-pow", + "sc-executor", "sc-network", "sc-rpc", "sc-rpc-api", + "sc-service", "scale-info", "simple-mermaid", "sp-api", diff --git a/docs/sdk/Cargo.toml b/docs/sdk/Cargo.toml index 426c5d9de4a0..fc6ecc1a769a 100644 --- a/docs/sdk/Cargo.toml +++ b/docs/sdk/Cargo.toml @@ -96,3 +96,8 @@ sp-version = { path = "../../substrate/primitives/version" } # XCM xcm = { package = "staging-xcm", path = "../../polkadot/xcm" } +cumulus-primitives-proof-size-hostfunction = { version = "0.2.0", path = "../../cumulus/primitives/proof-size-hostfunction" } +sc-executor = { path = "../../substrate/client/executor" } +cumulus-client-service = { path = "../../cumulus/client/service" } +sc-service = { path = "../../substrate/client/service" } +cumulus-primitives-storage-weight-reclaim = { version = "1.0.0", path = "../../cumulus/primitives/storage-weight-reclaim" } diff --git a/docs/sdk/src/guides/enable_pov_reclaim.rs b/docs/sdk/src/guides/enable_pov_reclaim.rs new file mode 100644 index 000000000000..a9e16453e5f0 --- /dev/null +++ b/docs/sdk/src/guides/enable_pov_reclaim.rs @@ -0,0 +1,56 @@ +//! This guide will teach you how to enable storage weight reclaiming for a parachain. +//! +//! # 1. Add the host function to your node +//! +//! In order to reclaim excess storage weight that was benchmarked, your parachain runtime needs to +//! be able to fetch the size of the storage proof from the runtime. To do this, it needs access to +//! the [storage_proof_size](cumulus_primitives_proof_size_hostfunction::storage_proof_size) host +//! function. For convenience, cumulus provides +//! [ParachainHostFunctions](cumulus_client_service::ParachainHostFunctions), a set of typically +//! expected hostfunctions typically expected by parachain runtimes. +//! +//! ## WasmExecutor +//! If your node is using the [WasmExecutor][`sc_executor::WasmExecutor`], add the hostfunctions +//! like this: +//! ```rust +//! let executor = WasmExecutor::::builder() +//! .with_execution_method(config.wasm_method) +//! .with_onchain_heap_alloc_strategy(heap_pages) +//! .with_offchain_heap_alloc_strategy(heap_pages) +//! .with_max_runtime_instances(config.max_runtime_instances) +//! .with_runtime_cache_size(config.runtime_cache_size) +//! .build(); +//! ``` +//! +//! # 2. Enable storage proof recording during import +//! +//! The reclaim mechanism reads the size of the currently recorded storage proof multiple times +//! during block execution. This entails that the host function to query the storage proof size will +//! also be called during block import. Therefore we need to make sure that storage proof recording +//! is enabled during block import. In your project find the place where your build node components +//! by calling [new_full_parts](sc_service::new_full_parts). Replace this by +//! [new_full_parts_record_import](sc_service::new_full_parts_record_import) and make sure to pass +//! `true` as the last parameter to enable import recording. +//! +//! # 3. Add the SignedExtension to your runtime +//! +//! In your runtime, you will find a list of SignedExtensions. +//! ```rust +//! pub type SignedExtra = ( +//! frame_system::CheckNonZeroSender, +//! frame_system::CheckSpecVersion, +//! frame_system::CheckTxVersion, +//! frame_system::CheckGenesis, +//! frame_system::CheckEra, +//! frame_system::CheckNonce, +//! frame_system::CheckWeight, +//! pallet_transaction_payment::ChargeTransactionPayment, +//! cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim, +//! ; +//! ``` +//! To enable reclaim, +//! just add [StorageWeightReclaim](cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim) +//! to that list. + +#![deny(rustdoc::broken_intra_doc_links)] +#![deny(rustdoc::private_intra_doc_links)] diff --git a/docs/sdk/src/guides/mod.rs b/docs/sdk/src/guides/mod.rs index 3120f2533109..93dee6aab518 100644 --- a/docs/sdk/src/guides/mod.rs +++ b/docs/sdk/src/guides/mod.rs @@ -23,3 +23,6 @@ pub mod cumulus_enabled_parachain; /// How to make a given runtime XCM-enabled, capable of sending messages (`Transact`) between itself /// and the relay chain to which it is connected. pub mod xcm_enabled_parachain; + +/// How to enable storage weigt reclaiming in a parachain node and runtime. +pub mod enable_pov_reclaim; From 93abe1bb0d00b9b8493ffaa85ab92678ee25a6cb Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Mon, 22 Apr 2024 09:30:43 +0200 Subject: [PATCH 2/9] Move code to docify --- docs/sdk/src/guides/enable_pov_reclaim.rs | 27 +++++++++++++---------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/sdk/src/guides/enable_pov_reclaim.rs b/docs/sdk/src/guides/enable_pov_reclaim.rs index a9e16453e5f0..2eecb2b5ef3f 100644 --- a/docs/sdk/src/guides/enable_pov_reclaim.rs +++ b/docs/sdk/src/guides/enable_pov_reclaim.rs @@ -2,25 +2,17 @@ //! //! # 1. Add the host function to your node //! -//! In order to reclaim excess storage weight that was benchmarked, your parachain runtime needs to +//! In order to reclaim excess storage weight that was benchmarked, a parachain runtime needs to //! be able to fetch the size of the storage proof from the runtime. To do this, it needs access to //! the [storage_proof_size](cumulus_primitives_proof_size_hostfunction::storage_proof_size) host //! function. For convenience, cumulus provides -//! [ParachainHostFunctions](cumulus_client_service::ParachainHostFunctions), a set of typically -//! expected hostfunctions typically expected by parachain runtimes. +//! [ParachainHostFunctions](cumulus_client_service::ParachainHostFunctions), a set of hostfunctions +//! typically used by parachains. //! //! ## WasmExecutor //! If your node is using the [WasmExecutor][`sc_executor::WasmExecutor`], add the hostfunctions //! like this: -//! ```rust -//! let executor = WasmExecutor::::builder() -//! .with_execution_method(config.wasm_method) -//! .with_onchain_heap_alloc_strategy(heap_pages) -//! .with_offchain_heap_alloc_strategy(heap_pages) -//! .with_max_runtime_instances(config.max_runtime_instances) -//! .with_runtime_cache_size(config.runtime_cache_size) -//! .build(); -//! ``` +#![doc = docify::embed!("src/guides/enable_pov_reclaim.rs",wasm_executor)] //! //! # 2. Enable storage proof recording during import //! @@ -54,3 +46,14 @@ #![deny(rustdoc::broken_intra_doc_links)] #![deny(rustdoc::private_intra_doc_links)] + +#[cfg(test)] +mod test { + use cumulus_client_service::ParachainHostFunctions; + use sc_executor::WasmExecutor; + + #[docify::export_content(wasm_executor)] + fn test() { + let executor = WasmExecutor::::builder().build(); + } +} From 2aacaed87e997c29d58c6ba605c0c585ff4e6084 Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Mon, 22 Apr 2024 16:56:34 +0200 Subject: [PATCH 3/9] Improve wording, use template as example --- docs/sdk/src/guides/enable_pov_reclaim.rs | 113 +++++++++++++--------- docs/sdk/src/guides/mod.rs | 2 +- docs/sdk/src/meta_contributing.rs | 2 +- templates/parachain/node/src/service.rs | 2 + templates/parachain/runtime/src/lib.rs | 1 + 5 files changed, 72 insertions(+), 48 deletions(-) diff --git a/docs/sdk/src/guides/enable_pov_reclaim.rs b/docs/sdk/src/guides/enable_pov_reclaim.rs index 2eecb2b5ef3f..4fee50e35034 100644 --- a/docs/sdk/src/guides/enable_pov_reclaim.rs +++ b/docs/sdk/src/guides/enable_pov_reclaim.rs @@ -1,59 +1,80 @@ -//! This guide will teach you how to enable storage weight reclaiming for a parachain. +//! This guide will teach you how to enable storage weight reclaiming for a parachain. The +//! explanations in this guide assume a project structure similar to the one detailed in +//! the [substrate documentation](crate::polkadot_sdk::substrate#anatomy-of-a-binary-crate). //! -//! # 1. Add the host function to your node +//! # What is PoV reclaim? +//! When a parachain submits a block to a relay chain like Polkadot or Kusama, it sends the block +//! itself and a storage proof. Together they form the Proof-of-Validity (PoV). The PoV allows the +//! relay chain to validate the parachain block by re-executing it. Relay chain +//! validators distribute this PoV among themselves over the network. This distribution is costly +//! and limits the size of the storage proof. The storage weight dimension of FRAME weights reflects +//! this cost and limits the size of the storage proof. However, the storage weight determined +//! during [benchmarking](crate::reference_docs::frame_benchmarking_weight) represents the worst +//! case. In reality, runtime operations often consume less space in the storage proof. PoV reclaim +//! offers a mechanism to reclaim the difference between the benchmarked worst-case and the real +//! proof-size consumption. //! -//! In order to reclaim excess storage weight that was benchmarked, a parachain runtime needs to -//! be able to fetch the size of the storage proof from the runtime. To do this, it needs access to -//! the [storage_proof_size](cumulus_primitives_proof_size_hostfunction::storage_proof_size) host -//! function. For convenience, cumulus provides +//! +//! # How to enable PoV reclaim +//! ## 1. Add the host function to your node +//! +//! To reclaim excess storage weight, a parachain runtime needs the +//! ability to fetch the size of the storage proof from the node. The reclaim +//! mechanism uses the +//! [storage_proof_size](cumulus_primitives_proof_size_hostfunction::storage_proof_size) +//! hostfunction for this purpose. For convenience, cumulus provides //! [ParachainHostFunctions](cumulus_client_service::ParachainHostFunctions), a set of hostfunctions -//! typically used by parachains. +//! typically used by cumulus-based parachains. In the binary crate of your parachain, find the +//! instantiation of the [WasmExecutor](sc_executor::WasmExecutor) and set the correct generic type. +//! +//! This example from the parachain-template shows a type definition that includes the correct +//! hostfunctions. +#![doc = docify::embed!("../../templates/parachain/node/src/service.rs", wasm_executor)] //! -//! ## WasmExecutor -//! If your node is using the [WasmExecutor][`sc_executor::WasmExecutor`], add the hostfunctions -//! like this: -#![doc = docify::embed!("src/guides/enable_pov_reclaim.rs",wasm_executor)] +//! > **Note:** +//! > +//! > If you see error `runtime requires function imports which are not present on the host: +//! > 'env:ext_storage_proof_size_storage_proof_size_version_1'`, it is likely +//! > that this step in the guide was not set up correctly. //! -//! # 2. Enable storage proof recording during import +//! ## 2. Enable storage proof recording during import //! //! The reclaim mechanism reads the size of the currently recorded storage proof multiple times -//! during block execution. This entails that the host function to query the storage proof size will -//! also be called during block import. Therefore we need to make sure that storage proof recording -//! is enabled during block import. In your project find the place where your build node components -//! by calling [new_full_parts](sc_service::new_full_parts). Replace this by -//! [new_full_parts_record_import](sc_service::new_full_parts_record_import) and make sure to pass -//! `true` as the last parameter to enable import recording. +//! during block authoring and block import. Proof recording during authoring is already enabled on +//! parachains. You must also ensure that storage proof recording is enabled during block import. +//! Find where your node builds the fundamental substrate components by calling +//! [new_full_parts](sc_service::new_full_parts). Replace this +//! with [new_full_parts_record_import](sc_service::new_full_parts_record_import) and +//! pass `true` as the last parameter to enable import recording. +#![doc = docify::embed!("../../templates/parachain/node/src/service.rs", component_instantiation)] //! -//! # 3. Add the SignedExtension to your runtime +//! > **Note:** +//! > +//! > If you see error `Storage root must match that calculated.` during block import, it is likely +//! > that this step in the guide was not +//! > set up correctly. +//! +//! ## 3. Add the SignedExtension to your runtime //! //! In your runtime, you will find a list of SignedExtensions. -//! ```rust -//! pub type SignedExtra = ( -//! frame_system::CheckNonZeroSender, -//! frame_system::CheckSpecVersion, -//! frame_system::CheckTxVersion, -//! frame_system::CheckGenesis, -//! frame_system::CheckEra, -//! frame_system::CheckNonce, -//! frame_system::CheckWeight, -//! pallet_transaction_payment::ChargeTransactionPayment, -//! cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim, -//! ; +//! To enable the reclaiming, +//! add [StorageWeightReclaim](cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim) +//! to that list. The extension will check the size of the storage proof before and after an +//! extrinsic execution. It reclaims the difference between the calculated size and the benchmarked +//! size. +#![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", template_signed_extra)] +//! ## Optional: Verify that reclaim works +//! Start your node with the log target `runtime::storage_reclaim` set to `trace` to enable full +//! logging for `StorageWeightReclaim`. The following log is an example from a local testnet. To +//! trigger the log, execute any extrinsic on the network. +//! +//! ```ignore +//! ... +//! 2024-04-22 17:31:48.014 TRACE runtime::storage_reclaim: [ferdie] Reclaiming storage weight. benchmarked: 3593, consumed: 265 unspent: 0 +//! ... //! ``` -//! To enable reclaim, -//! just add [StorageWeightReclaim](cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim) -//! to that list. - +//! +//! In the above example we see a benchmarked size of 3593 bytes, while the extrinsic only consumed +//! 265 bytes of proof size. This results in 3328 bytes of reclaim. #![deny(rustdoc::broken_intra_doc_links)] #![deny(rustdoc::private_intra_doc_links)] - -#[cfg(test)] -mod test { - use cumulus_client_service::ParachainHostFunctions; - use sc_executor::WasmExecutor; - - #[docify::export_content(wasm_executor)] - fn test() { - let executor = WasmExecutor::::builder().build(); - } -} diff --git a/docs/sdk/src/guides/mod.rs b/docs/sdk/src/guides/mod.rs index 93dee6aab518..2dc807af8eae 100644 --- a/docs/sdk/src/guides/mod.rs +++ b/docs/sdk/src/guides/mod.rs @@ -24,5 +24,5 @@ pub mod cumulus_enabled_parachain; /// and the relay chain to which it is connected. pub mod xcm_enabled_parachain; -/// How to enable storage weigt reclaiming in a parachain node and runtime. +/// How to enable storage weight reclaiming in a parachain node and runtime. pub mod enable_pov_reclaim; diff --git a/docs/sdk/src/meta_contributing.rs b/docs/sdk/src/meta_contributing.rs index fcdcea9934bb..a029595254c8 100644 --- a/docs/sdk/src/meta_contributing.rs +++ b/docs/sdk/src/meta_contributing.rs @@ -139,7 +139,7 @@ //! //! ```sh //! SKIP_WASM_BUILD=1 \ -//! RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/headers/header.html --extend-css $(pwd)/docs/sdk/headers/theme.css --default-theme=ayu" \ +//! RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/assets/header.html --extend-css $(pwd)/docs/sdk/assets/theme.css --default-theme=ayu" \ //! cargo doc -p polkadot-sdk-docs --no-deps --open //! ``` //! diff --git a/templates/parachain/node/src/service.rs b/templates/parachain/node/src/service.rs index 373df01b0c43..70f01e6d616d 100644 --- a/templates/parachain/node/src/service.rs +++ b/templates/parachain/node/src/service.rs @@ -35,6 +35,7 @@ use sc_transaction_pool_api::OffchainTransactionPoolFactory; use sp_keystore::KeystorePtr; use substrate_prometheus_endpoint::Registry; +#[docify::export(wasm_executor)] type ParachainExecutor = WasmExecutor; type ParachainClient = TFullClient; @@ -57,6 +58,7 @@ pub type Service = PartialComponents< /// /// Use this macro if you don't actually need the full service, but just the builder in order to /// be able to perform chain operations. +#[docify::export(component_instantiation)] pub fn new_partial(config: &Configuration) -> Result { let telemetry = config .telemetry_endpoints diff --git a/templates/parachain/runtime/src/lib.rs b/templates/parachain/runtime/src/lib.rs index 5bfd6f290c1b..7bd32b98f588 100644 --- a/templates/parachain/runtime/src/lib.rs +++ b/templates/parachain/runtime/src/lib.rs @@ -75,6 +75,7 @@ pub type SignedBlock = generic::SignedBlock; pub type BlockId = generic::BlockId; /// The SignedExtension to the basic transaction logic. +#[docify::export(template_signed_extra)] pub type SignedExtra = ( frame_system::CheckNonZeroSender, frame_system::CheckSpecVersion, From b9d1e33965603ae500fd54f3567107309ec2ceb6 Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Mon, 22 Apr 2024 18:08:21 +0200 Subject: [PATCH 4/9] Fix links --- docs/sdk/Cargo.toml | 12 ++++++------ docs/sdk/src/guides/enable_pov_reclaim.rs | 17 +++++++++-------- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/sdk/Cargo.toml b/docs/sdk/Cargo.toml index fc6ecc1a769a..d7a38ed1c3f1 100644 --- a/docs/sdk/Cargo.toml +++ b/docs/sdk/Cargo.toml @@ -51,6 +51,8 @@ sc-consensus-grandpa = { path = "../../substrate/client/consensus/grandpa" } sc-consensus-beefy = { path = "../../substrate/client/consensus/beefy" } sc-consensus-manual-seal = { path = "../../substrate/client/consensus/manual-seal" } sc-consensus-pow = { path = "../../substrate/client/consensus/pow" } +sc-executor = { path = "../../substrate/client/executor" } +sc-service = { path = "../../substrate/client/service" } substrate-wasm-builder = { path = "../../substrate/utils/wasm-builder" } @@ -60,9 +62,12 @@ cumulus-pallet-parachain-system = { path = "../../cumulus/pallets/parachain-syst "parameterized-consensus-hook", ] } parachain-info = { package = "staging-parachain-info", path = "../../cumulus/parachains/pallets/parachain-info" } -pallet-aura = { path = "../../substrate/frame/aura", default-features = false } +cumulus-primitives-proof-size-hostfunction = { version = "0.2.0", path = "../../cumulus/primitives/proof-size-hostfunction" } +cumulus-client-service = { path = "../../cumulus/client/service" } +cumulus-primitives-storage-weight-reclaim = { version = "1.0.0", path = "../../cumulus/primitives/storage-weight-reclaim" } # Pallets and FRAME internals +pallet-aura = { path = "../../substrate/frame/aura" } pallet-timestamp = { path = "../../substrate/frame/timestamp" } pallet-balances = { path = "../../substrate/frame/balances" } pallet-assets = { path = "../../substrate/frame/assets" } @@ -96,8 +101,3 @@ sp-version = { path = "../../substrate/primitives/version" } # XCM xcm = { package = "staging-xcm", path = "../../polkadot/xcm" } -cumulus-primitives-proof-size-hostfunction = { version = "0.2.0", path = "../../cumulus/primitives/proof-size-hostfunction" } -sc-executor = { path = "../../substrate/client/executor" } -cumulus-client-service = { path = "../../cumulus/client/service" } -sc-service = { path = "../../substrate/client/service" } -cumulus-primitives-storage-weight-reclaim = { version = "1.0.0", path = "../../cumulus/primitives/storage-weight-reclaim" } diff --git a/docs/sdk/src/guides/enable_pov_reclaim.rs b/docs/sdk/src/guides/enable_pov_reclaim.rs index 4fee50e35034..b09f253b7224 100644 --- a/docs/sdk/src/guides/enable_pov_reclaim.rs +++ b/docs/sdk/src/guides/enable_pov_reclaim.rs @@ -9,7 +9,7 @@ //! validators distribute this PoV among themselves over the network. This distribution is costly //! and limits the size of the storage proof. The storage weight dimension of FRAME weights reflects //! this cost and limits the size of the storage proof. However, the storage weight determined -//! during [benchmarking](crate::reference_docs::frame_benchmarking_weight) represents the worst +//! during [benchmarking](`crate::reference_docs::frame_benchmarking_weight`) represents the worst //! case. In reality, runtime operations often consume less space in the storage proof. PoV reclaim //! offers a mechanism to reclaim the difference between the benchmarked worst-case and the real //! proof-size consumption. @@ -21,11 +21,12 @@ //! To reclaim excess storage weight, a parachain runtime needs the //! ability to fetch the size of the storage proof from the node. The reclaim //! mechanism uses the -//! [storage_proof_size](cumulus_primitives_proof_size_hostfunction::storage_proof_size) +//! [storage_proof_size](`cumulus_primitives_proof_size_hostfunction::storage_proof_size`) //! hostfunction for this purpose. For convenience, cumulus provides -//! [ParachainHostFunctions](cumulus_client_service::ParachainHostFunctions), a set of hostfunctions -//! typically used by cumulus-based parachains. In the binary crate of your parachain, find the -//! instantiation of the [WasmExecutor](sc_executor::WasmExecutor) and set the correct generic type. +//! [ParachainHostFunctions](`cumulus_client_service::ParachainHostFunctions`), a set of +//! hostfunctions typically used by cumulus-based parachains. In the binary crate of your parachain, +//! find the instantiation of the [WasmExecutor](`sc_executor::WasmExecutor`) and set the correct +//! generic type. //! //! This example from the parachain-template shows a type definition that includes the correct //! hostfunctions. @@ -43,8 +44,8 @@ //! during block authoring and block import. Proof recording during authoring is already enabled on //! parachains. You must also ensure that storage proof recording is enabled during block import. //! Find where your node builds the fundamental substrate components by calling -//! [new_full_parts](sc_service::new_full_parts). Replace this -//! with [new_full_parts_record_import](sc_service::new_full_parts_record_import) and +//! [new_full_parts](`sc_service::new_full_parts`). Replace this +//! with [new_full_parts_record_import](`sc_service::new_full_parts_record_import`) and //! pass `true` as the last parameter to enable import recording. #![doc = docify::embed!("../../templates/parachain/node/src/service.rs", component_instantiation)] //! @@ -58,7 +59,7 @@ //! //! In your runtime, you will find a list of SignedExtensions. //! To enable the reclaiming, -//! add [StorageWeightReclaim](cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim) +//! add [StorageWeightReclaim](`cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim`) //! to that list. The extension will check the size of the storage proof before and after an //! extrinsic execution. It reclaims the difference between the calculated size and the benchmarked //! size. From f7ac054ea2c094cdec562003f1f162697b3b7fad Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Tue, 23 Apr 2024 11:04:21 +0200 Subject: [PATCH 5/9] Remove version numbers from Cargo.toml --- docs/sdk/Cargo.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/Cargo.toml b/docs/sdk/Cargo.toml index d7a38ed1c3f1..fe53845d8490 100644 --- a/docs/sdk/Cargo.toml +++ b/docs/sdk/Cargo.toml @@ -62,9 +62,9 @@ cumulus-pallet-parachain-system = { path = "../../cumulus/pallets/parachain-syst "parameterized-consensus-hook", ] } parachain-info = { package = "staging-parachain-info", path = "../../cumulus/parachains/pallets/parachain-info" } -cumulus-primitives-proof-size-hostfunction = { version = "0.2.0", path = "../../cumulus/primitives/proof-size-hostfunction" } +cumulus-primitives-proof-size-hostfunction = { path = "../../cumulus/primitives/proof-size-hostfunction" } cumulus-client-service = { path = "../../cumulus/client/service" } -cumulus-primitives-storage-weight-reclaim = { version = "1.0.0", path = "../../cumulus/primitives/storage-weight-reclaim" } +cumulus-primitives-storage-weight-reclaim = { path = "../../cumulus/primitives/storage-weight-reclaim" } # Pallets and FRAME internals pallet-aura = { path = "../../substrate/frame/aura" } From e2584fb466cac3f9962f926b3926b8cbf880566f Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Tue, 23 Apr 2024 13:02:54 +0200 Subject: [PATCH 6/9] Add note about adding the SE last. Improve formatting. --- docs/sdk/src/guides/enable_pov_reclaim.rs | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/sdk/src/guides/enable_pov_reclaim.rs b/docs/sdk/src/guides/enable_pov_reclaim.rs index b09f253b7224..0f6885406f0f 100644 --- a/docs/sdk/src/guides/enable_pov_reclaim.rs +++ b/docs/sdk/src/guides/enable_pov_reclaim.rs @@ -21,11 +21,11 @@ //! To reclaim excess storage weight, a parachain runtime needs the //! ability to fetch the size of the storage proof from the node. The reclaim //! mechanism uses the -//! [storage_proof_size](`cumulus_primitives_proof_size_hostfunction::storage_proof_size`) +//! [`storage_proof_size`](`cumulus_primitives_proof_size_hostfunction::storage_proof_size`) //! hostfunction for this purpose. For convenience, cumulus provides -//! [ParachainHostFunctions](`cumulus_client_service::ParachainHostFunctions`), a set of +//! [`ParachainHostFunctions`](`cumulus_client_service::ParachainHostFunctions`), a set of //! hostfunctions typically used by cumulus-based parachains. In the binary crate of your parachain, -//! find the instantiation of the [WasmExecutor](`sc_executor::WasmExecutor`) and set the correct +//! find the instantiation of the [`WasmExecutor`](`sc_executor::WasmExecutor`) and set the correct //! generic type. //! //! This example from the parachain-template shows a type definition that includes the correct @@ -44,8 +44,8 @@ //! during block authoring and block import. Proof recording during authoring is already enabled on //! parachains. You must also ensure that storage proof recording is enabled during block import. //! Find where your node builds the fundamental substrate components by calling -//! [new_full_parts](`sc_service::new_full_parts`). Replace this -//! with [new_full_parts_record_import](`sc_service::new_full_parts_record_import`) and +//! [`new_full_parts`](`sc_service::new_full_parts`). Replace this +//! with [`new_full_parts_record_import`](`sc_service::new_full_parts_record_import`) and //! pass `true` as the last parameter to enable import recording. #![doc = docify::embed!("../../templates/parachain/node/src/service.rs", component_instantiation)] //! @@ -59,12 +59,14 @@ //! //! In your runtime, you will find a list of SignedExtensions. //! To enable the reclaiming, -//! add [StorageWeightReclaim](`cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim`) -//! to that list. The extension will check the size of the storage proof before and after an -//! extrinsic execution. It reclaims the difference between the calculated size and the benchmarked -//! size. +//! add [`StorageWeightReclaim`](`cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim`) +//! to that list. For maximum efficiency, make sure that `StorageWeightReclaim` is last in the list. +//! The extension will check the size of the storage proof before and after an extrinsic execution. +//! It reclaims the difference between the calculated size and the benchmarked size. #![doc = docify::embed!("../../templates/parachain/runtime/src/lib.rs", template_signed_extra)] +//! //! ## Optional: Verify that reclaim works +//! //! Start your node with the log target `runtime::storage_reclaim` set to `trace` to enable full //! logging for `StorageWeightReclaim`. The following log is an example from a local testnet. To //! trigger the log, execute any extrinsic on the network. From dd6c9ccf96521c7ef2b70ffc6714b975cc86915f Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Tue, 23 Apr 2024 13:15:56 +0200 Subject: [PATCH 7/9] Add docify to deps --- Cargo.lock | 2 ++ templates/parachain/node/Cargo.toml | 1 + templates/parachain/runtime/Cargo.toml | 1 + 3 files changed, 4 insertions(+) diff --git a/Cargo.lock b/Cargo.lock index 743708330c64..2499de4c9345 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -11846,6 +11846,7 @@ dependencies = [ "cumulus-primitives-core", "cumulus-primitives-parachain-inherent", "cumulus-relay-chain-interface", + "docify", "frame-benchmarking", "frame-benchmarking-cli", "futures", @@ -11901,6 +11902,7 @@ dependencies = [ "cumulus-primitives-core", "cumulus-primitives-storage-weight-reclaim", "cumulus-primitives-utility", + "docify", "frame-benchmarking", "frame-executive", "frame-support", diff --git a/templates/parachain/node/Cargo.toml b/templates/parachain/node/Cargo.toml index 63267acdbca8..ed857b4e4b9f 100644 --- a/templates/parachain/node/Cargo.toml +++ b/templates/parachain/node/Cargo.toml @@ -24,6 +24,7 @@ serde = { features = ["derive"], workspace = true, default-features = true } jsonrpsee = { version = "0.22", features = ["server"] } futures = "0.3.28" serde_json = { workspace = true, default-features = true } +docify = "0.2.8" # Local parachain-template-runtime = { path = "../runtime" } diff --git a/templates/parachain/runtime/Cargo.toml b/templates/parachain/runtime/Cargo.toml index 0d985796a11e..4a400bac99e9 100644 --- a/templates/parachain/runtime/Cargo.toml +++ b/templates/parachain/runtime/Cargo.toml @@ -28,6 +28,7 @@ scale-info = { version = "2.11.1", default-features = false, features = [ "derive", ] } smallvec = "1.11.0" +docify = "0.2.8" # Local pallet-parachain-template = { path = "../pallets/template", default-features = false } From 8ee5be5db072c0096560cd1df5659e56ada5e43b Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Wed, 24 Apr 2024 11:42:55 +0200 Subject: [PATCH 8/9] Remove unnecessary backticks --- docs/sdk/src/guides/enable_pov_reclaim.rs | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/sdk/src/guides/enable_pov_reclaim.rs b/docs/sdk/src/guides/enable_pov_reclaim.rs index 0f6885406f0f..2740a3986966 100644 --- a/docs/sdk/src/guides/enable_pov_reclaim.rs +++ b/docs/sdk/src/guides/enable_pov_reclaim.rs @@ -9,7 +9,7 @@ //! validators distribute this PoV among themselves over the network. This distribution is costly //! and limits the size of the storage proof. The storage weight dimension of FRAME weights reflects //! this cost and limits the size of the storage proof. However, the storage weight determined -//! during [benchmarking](`crate::reference_docs::frame_benchmarking_weight`) represents the worst +//! during [benchmarking](crate::reference_docs::frame_benchmarking_weight) represents the worst //! case. In reality, runtime operations often consume less space in the storage proof. PoV reclaim //! offers a mechanism to reclaim the difference between the benchmarked worst-case and the real //! proof-size consumption. @@ -21,11 +21,11 @@ //! To reclaim excess storage weight, a parachain runtime needs the //! ability to fetch the size of the storage proof from the node. The reclaim //! mechanism uses the -//! [`storage_proof_size`](`cumulus_primitives_proof_size_hostfunction::storage_proof_size`) +//! [`storage_proof_size`](cumulus_primitives_proof_size_hostfunction::storage_proof_size) //! hostfunction for this purpose. For convenience, cumulus provides -//! [`ParachainHostFunctions`](`cumulus_client_service::ParachainHostFunctions`), a set of +//! [`ParachainHostFunctions`](cumulus_client_service::ParachainHostFunctions), a set of //! hostfunctions typically used by cumulus-based parachains. In the binary crate of your parachain, -//! find the instantiation of the [`WasmExecutor`](`sc_executor::WasmExecutor`) and set the correct +//! find the instantiation of the [`WasmExecutor`](sc_executor::WasmExecutor) and set the correct //! generic type. //! //! This example from the parachain-template shows a type definition that includes the correct @@ -44,8 +44,8 @@ //! during block authoring and block import. Proof recording during authoring is already enabled on //! parachains. You must also ensure that storage proof recording is enabled during block import. //! Find where your node builds the fundamental substrate components by calling -//! [`new_full_parts`](`sc_service::new_full_parts`). Replace this -//! with [`new_full_parts_record_import`](`sc_service::new_full_parts_record_import`) and +//! [`new_full_parts`](sc_service::new_full_parts). Replace this +//! with [`new_full_parts_record_import`](sc_service::new_full_parts_record_import) and //! pass `true` as the last parameter to enable import recording. #![doc = docify::embed!("../../templates/parachain/node/src/service.rs", component_instantiation)] //! @@ -59,7 +59,7 @@ //! //! In your runtime, you will find a list of SignedExtensions. //! To enable the reclaiming, -//! add [`StorageWeightReclaim`](`cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim`) +//! add [`StorageWeightReclaim`](cumulus_primitives_storage_weight_reclaim::StorageWeightReclaim) //! to that list. For maximum efficiency, make sure that `StorageWeightReclaim` is last in the list. //! The extension will check the size of the storage proof before and after an extrinsic execution. //! It reclaims the difference between the calculated size and the benchmarked size. From 760d2f7bc15a69becb2d38c498637ae8a9ac2248 Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Thu, 2 May 2024 10:32:49 +0200 Subject: [PATCH 9/9] hostfunction -> host function + mention original PR --- docs/sdk/src/guides/enable_pov_reclaim.rs | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/sdk/src/guides/enable_pov_reclaim.rs b/docs/sdk/src/guides/enable_pov_reclaim.rs index 2740a3986966..3c0c5fba2158 100644 --- a/docs/sdk/src/guides/enable_pov_reclaim.rs +++ b/docs/sdk/src/guides/enable_pov_reclaim.rs @@ -1,6 +1,7 @@ //! This guide will teach you how to enable storage weight reclaiming for a parachain. The //! explanations in this guide assume a project structure similar to the one detailed in -//! the [substrate documentation](crate::polkadot_sdk::substrate#anatomy-of-a-binary-crate). +//! the [substrate documentation](crate::polkadot_sdk::substrate#anatomy-of-a-binary-crate). Full +//! technical details are available in the original [pull request](https://github.com/paritytech/polkadot-sdk/pull/3002). //! //! # What is PoV reclaim? //! When a parachain submits a block to a relay chain like Polkadot or Kusama, it sends the block @@ -22,14 +23,14 @@ //! ability to fetch the size of the storage proof from the node. The reclaim //! mechanism uses the //! [`storage_proof_size`](cumulus_primitives_proof_size_hostfunction::storage_proof_size) -//! hostfunction for this purpose. For convenience, cumulus provides +//! host function for this purpose. For convenience, cumulus provides //! [`ParachainHostFunctions`](cumulus_client_service::ParachainHostFunctions), a set of -//! hostfunctions typically used by cumulus-based parachains. In the binary crate of your parachain, -//! find the instantiation of the [`WasmExecutor`](sc_executor::WasmExecutor) and set the correct -//! generic type. +//! host functions typically used by cumulus-based parachains. In the binary crate of your +//! parachain, find the instantiation of the [`WasmExecutor`](sc_executor::WasmExecutor) and set the +//! correct generic type. //! //! This example from the parachain-template shows a type definition that includes the correct -//! hostfunctions. +//! host functions. #![doc = docify::embed!("../../templates/parachain/node/src/service.rs", wasm_executor)] //! //! > **Note:**