diff --git a/Cargo.lock b/Cargo.lock index de1d897be0b80..29f924aca1e53 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -14555,6 +14555,7 @@ dependencies = [ "frame-support", "frame-system", "kitchensink-runtime", + "log", "minimal-template-runtime", "pallet-asset-conversion-tx-payment", "pallet-asset-tx-payment", @@ -14581,6 +14582,7 @@ dependencies = [ "pallet-transaction-payment", "pallet-uniques", "pallet-utility", + "pallet-xcm", "parachain-template-runtime", "parity-scale-codec", "polkadot-sdk", @@ -14618,9 +14620,12 @@ dependencies = [ "staging-node-cli", "staging-parachain-info", "staging-xcm", + "staging-xcm-builder", + "staging-xcm-executor", "subkey", "substrate-wasm-builder", "xcm-docs", + "xcm-simulator", ] [[package]] diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index 96811a2772d77..cc1082347d20c 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -1,7 +1,7 @@ # Substrate Documentation Guidelines This document is focused on documenting parts of Substrate that relate to its external API. The list of such crates can -be found in [CODEOWNERS](./CODEOWNERS). Search for the crates auto-assigned to the `docs-audit` team. +be found in [CODEOWNERS](/.github/CODEOWNERS). Search for the crates auto-assigned to the `docs-audit` team. These crates are used by external developers and need thorough documentation. They are the most concerned with FRAME development. @@ -33,7 +33,7 @@ First, consider the case for all such crates, except for those that are pallets. The first question is, what should you document? Use this filter: -1. In the crates assigned to `docs-audit` in [CODEOWNERS](./CODEOWNERS), +1. In the crates assigned to `docs-audit` in [CODEOWNERS](/.github/CODEOWNERS), 2. All `pub` items need to be documented. If not `pub`, it doesn't appear in the rust-docs, and is not public facing. - Within `pub` items, sometimes they are only `pub` to be used by another internal crate, and you can foresee that @@ -88,20 +88,19 @@ sections](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/ru we will most likely not need to think about panic and safety in any runtime related code. Our code is never `unsafe`, and will (almost) never panic. -Use `# Examples as much as possible. These are great ways to further demonstrate what your APIs are doing, and add free -test coverage. As an additional benefit, any code in rust-docs is treated as an "integration tests", not unit tests, +Use `# Examples` as much as possible. These are great ways to further demonstrate what your APIs are doing, and add free +test coverage. As an additional benefit, any code in rust-docs is treated as an "integration test", which tests your crate in a different way than unit tests. So, it is both a win for "more documentation" and a win for "more test coverage". You can also consider having an `# Error` section optionally. Of course, this only applies if there is a `Result` being returned, and if the `Error` variants are overly complicated. -Strive to include correct links to other items in your written docs as much as possible. In other words, avoid -\`some_func\` and instead use \[\`some_fund\`\]. Read more about how to correctly use links in your rust-docs +Strive to include correct links to other items in your written docs as much as possible. +Read more about how to correctly use links in your rust-docs [here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links) and -[here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). Strive to -include correct links to other items in your written docs as much as possible. In other words, avoid `` `some_func` `` -and instead use ``[`some_func`]``. +[here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). +In other words, avoid `` `some_func` `` and instead use ``[`some_func`]``. > While you are linking, you might become conscious of the fact that you are in need of linking to (too many) foreign items in order to explain your API. This is leaning more towards API-Design rather than documentation, but it is a @@ -145,7 +144,7 @@ The following are a set of notes that may not necessarily hold in all circumstan You should make sure that your code is properly-named and well-organized so that your code functions as a form of documentation. However, within the complexity of our projects in Polkadot/Substrate that is not enough. Particularly, -things like examples, errors and panics cannot be documented only through properly- named and well-organized code. +things like examples, errors and panics cannot be documented only through properly-named and well-organized code. > Our north star is self-documenting code that also happens to be well-documented and littered with examples. @@ -272,7 +271,7 @@ For the top-level pallet docs, consider the following template: //! up> ``` -This template's details (heading 3s and beyond) are left flexible, and at the discretion of the developer to make the +This template's details (Heading 3s and beyond) are left flexible, and at the discretion of the developer to make the best final choice about. For example, you might want to include `### Terminology` or not. Moreover, you might find it more useful to include it in `## Overview`. diff --git a/docs/sdk/Cargo.toml b/docs/sdk/Cargo.toml index d3e48de5d1819..2f85171bb93d2 100644 --- a/docs/sdk/Cargo.toml +++ b/docs/sdk/Cargo.toml @@ -40,6 +40,7 @@ frame-support = { workspace = true } frame-executive = { workspace = true } pallet-example-single-block-migrations = { workspace = true, default-features = true } frame-metadata-hash-extension = { workspace = true, default-features = true } +log = { workspace = true, default-features = true } # Substrate Client sc-network = { workspace = true, default-features = true } @@ -107,7 +108,11 @@ sp-version = { workspace = true, default-features = true } # XCM xcm = { workspace = true, default-features = true } +xcm-builder = { workspace = true } xcm-docs = { workspace = true } +xcm-executor = { workspace = true } +xcm-simulator = { workspace = true } +pallet-xcm = { workspace = true } # runtime guides chain-spec-guide-runtime = { workspace = true } diff --git a/docs/sdk/src/guides/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs index f2f4dcabfd29b..a9fda2c3aa8ac 100644 --- a/docs/sdk/src/guides/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -27,8 +27,8 @@ //! "scheduling_lookahead": 2 //! ``` //! -//!
`scheduling_lookahead` must be set to 2, otherwise parachain block times -//! will degrade to worse than with sync backing!
+//!
scheduling_lookahead must be set to 2, otherwise parachain +//! block times will degrade to worse than with sync backing!
//! //! ## Phase 1 - Update Parachain Runtime //! diff --git a/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs b/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs index bc4f36c271fe3..939043b53529c 100644 --- a/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs +++ b/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs @@ -1,7 +1,7 @@ //! # Enable elastic scaling MVP for a parachain //! //!
This guide assumes full familiarity with Asynchronous Backing and its -//! terminology, as defined in https://wiki.polkadot.network/docs/maintain-guides-async-backing. +//! terminology, as defined in the Polkadot Wiki. //! Furthermore, the parachain should have already been upgraded according to the guide.
//! //! ## Quick introduction to elastic scaling @@ -70,9 +70,10 @@ //! - Ensure enough coretime is assigned to the parachain. For maximum throughput the upper bound is //! 3 cores. //! -//!
Phase 1 is not needed if using the `polkadot-parachain` binary built -//! from the latest polkadot-sdk release! Simply pass the `--experimental-use-slot-based` parameter -//! to the command line and jump to Phase 2.
+//!
Phase 1 is not needed if using the polkadot-parachain binary +//! built from the latest polkadot-sdk release! Simply pass the +//! --experimental-use-slot-based parameter to the command line and jump to Phase +//! 2.
//! //! The following steps assume using the cumulus parachain template. //! diff --git a/docs/sdk/src/guides/enable_metadata_hash.rs b/docs/sdk/src/guides/enable_metadata_hash.rs index b9cbae8533538..930afd4d8ff71 100644 --- a/docs/sdk/src/guides/enable_metadata_hash.rs +++ b/docs/sdk/src/guides/enable_metadata_hash.rs @@ -16,15 +16,15 @@ //! the metadata for one or more networks. The next problem is that the offline wallet/user can not //! trust the metadata to be correct. It is very important for the metadata to be correct or //! otherwise an attacker could change them in a way that the offline wallet decodes a transaction -//! in a different way than what it will be decoded to on chain. So, the user may signs an incorrect -//! transaction leading to unexpecting behavior. +//! in a different way than what it will be decoded to on chain. So, the user may sign an incorrect +//! transaction leading to unexpected behavior. //! //! The metadata hash verification circumvents the issues of the huge metadata and the need to trust //! some metadata blob to be correct. To generate a hash for the metadata, the metadata is chunked, //! these chunks are put into a merkle tree and then the root of this merkle tree is the "metadata //! hash". For a more technical explanation on how it works, see //! [RFC78](https://polkadot-fellows.github.io/RFCs/approved/0078-merkleized-metadata.html). At compile -//! time the metadata hash is generated and "backed" into the runtime. This makes it extremely cheap +//! time the metadata hash is generated and "baked" into the runtime. This makes it extremely cheap //! for the runtime to verify on chain that the metadata hash is correct. By having the runtime //! verify the hash on chain, the user also doesn't need to trust the offchain metadata. If the //! metadata hash doesn't match the on chain metadata hash the transaction will be rejected. The diff --git a/docs/sdk/src/guides/enable_pov_reclaim.rs b/docs/sdk/src/guides/enable_pov_reclaim.rs index 3c0c5fba21586..13b27d18956b4 100644 --- a/docs/sdk/src/guides/enable_pov_reclaim.rs +++ b/docs/sdk/src/guides/enable_pov_reclaim.rs @@ -1,3 +1,5 @@ +//! # Enable storage weight reclaiming +//! //! 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). Full diff --git a/docs/sdk/src/guides/mod.rs b/docs/sdk/src/guides/mod.rs index 9384f4c82ab3e..a7fd146ccdf3a 100644 --- a/docs/sdk/src/guides/mod.rs +++ b/docs/sdk/src/guides/mod.rs @@ -15,21 +15,21 @@ /// Write your first simple pallet, learning the most most basic features of FRAME along the way. pub mod your_first_pallet; -/// Writing your first real [runtime](`crate::reference_docs::wasm_meta_protocol`), and successfully +/// Write your first real [runtime](`crate::reference_docs::wasm_meta_protocol`), /// compiling it to [WASM](crate::polkadot_sdk::substrate#wasm-build). pub mod your_first_runtime; -/// Running the given runtime with a node. No specific consensus mechanism is used at this stage. +// /// Running the given runtime with a node. No specific consensus mechanism is used at this stage. // TODO // pub mod your_first_node; -/// How to enhance a given runtime and node to be cumulus-enabled, run it as a parachain and connect -/// it to a relay-chain. +// /// How to enhance a given runtime and node to be cumulus-enabled, run it as a parachain +// /// and connect it to a relay-chain. // TODO // 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. +// /// How to make a given runtime XCM-enabled, capable of sending messages (`Transact`) between +// /// itself and the relay chain to which it is connected. // TODO // pub mod xcm_enabled_parachain; diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index da4624f5ac2b8..3c74469e1768d 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -1,6 +1,6 @@ //! # Currency Pallet //! -//! By the end of this guide, you will write a small FRAME pallet (see +//! By the end of this guide, you will have written a small FRAME pallet (see //! [`crate::polkadot_sdk::frame_runtime`]) that is capable of handling a simple crypto-currency. //! This pallet will: //! @@ -18,7 +18,7 @@ //! //! To get started, use one of the templates mentioned in [`crate::polkadot_sdk::templates`]. We //! recommend using the `polkadot-sdk-minimal-template`. You might need to change small parts of -//! this guide, namely the crate/package names, based on which tutorial you use. +//! this guide, namely the crate/package names, based on which template you use. //! //! > Be aware that you can read the entire source code backing this tutorial by clicking on the //! > [`source`](./mod.rs.html) button at the top right of the page. @@ -45,8 +45,8 @@ //! Consider the following as a "shell pallet". We continue building the rest of this pallet based //! on this template. //! -//! [`pallet::config`] and [`pallet::pallet`] are both mandatory parts of any pallet. Refer to the -//! documentation of each to get an overview of what they do. +//! [`pallet::config`] and [`pallet::pallet`](frame_support::pallet) are both mandatory parts of any +//! pallet. Refer to the documentation of each to get an overview of what they do. #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", shell_pallet)] //! //! All of the code that follows in this guide should live inside of the `mod pallet`. @@ -73,7 +73,7 @@ //! as normal `fn`s attached to `struct Pallet`. #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", impl_pallet)] //! -//! The logic of the functions is self-explanatory. Instead, we will focus on the FRAME-related +//! The logic of these functions is self-explanatory. Instead, we will focus on the FRAME-related //! details: //! //! - Where do `T::AccountId` and `T::RuntimeOrigin` come from? These are both defined in @@ -83,7 +83,7 @@ //! document ([`crate::reference_docs::frame_origin`]). For now, you should only know the //! signature of the function: it takes a generic `T::RuntimeOrigin` and returns a //! `Result`. So by the end of this function call, we know that this dispatchable -//! was signed by `who`. +//! was signed by `sender`. #![doc = docify::embed!("../../substrate/frame/system/src/lib.rs", ensure_signed)] //! //! - Where does `mutate`, `get` and `insert` and other storage APIs come from? All of them are @@ -96,7 +96,7 @@ //! Which is more or less a normal Rust `Result`, with a custom [`frame::prelude::DispatchError`] as //! the `Err` variant. We won't cover this error in detail here, but importantly you should know //! that there is an `impl From<&'static string> for DispatchError` provided (see -//! [here](`frame::prelude::DispatchError#impl-From<%26'static+str>-for-DispatchError`)). Therefore, +//! [here](`frame::prelude::DispatchError#impl-From<%26str>-for-DispatchError`)). Therefore, //! we can use basic string literals as our error type and `.into()` them into `DispatchError`. //! //! - Why are all `get` and `mutate` functions returning an `Option`? This is the default behavior @@ -117,7 +117,7 @@ //! ergonomic. #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", transfer_better_checked)] //! -//! This is more or less all the logic that there is this basic currency pallet! +//! This is more or less all the logic that there is in this basic currency pallet! //! //! ### Your First (Test) Runtime //! diff --git a/docs/sdk/src/lib.rs b/docs/sdk/src/lib.rs index e211476d25144..bc0970c01f1ff 100644 --- a/docs/sdk/src/lib.rs +++ b/docs/sdk/src/lib.rs @@ -13,8 +13,8 @@ //! We suggest the following reading sequence: //! //! - Start by learning about the the [`polkadot_sdk`], its structure and context. -//! - Then, head over the [`guides`]. This modules contains in-depth guides about the most important -//! user-journeys of the Polkadot SDK. +//! - Then, head over to the [`guides`]. This modules contains in-depth guides about the most +//! important user-journeys of the Polkadot SDK. //! - Whilst reading the guides, you might find back-links to [`reference_docs`]. //! - Finally, is the parent website of this crate that contains the //! list of further tools related to the Polkadot SDK. @@ -36,7 +36,7 @@ pub mod meta_contributing; /// In-depth guides about the most common components of the Polkadot SDK. They are slightly more -/// high level and broad than reference docs. +/// high level and broad than [`reference_docs`]. pub mod guides; /// An introduction to the Polkadot SDK. Read this module to learn about the structure of the SDK, /// the tools that are provided as a part of it, and to gain a high level understanding of each. diff --git a/docs/sdk/src/meta_contributing.rs b/docs/sdk/src/meta_contributing.rs index a029595254c84..e1297151b2312 100644 --- a/docs/sdk/src/meta_contributing.rs +++ b/docs/sdk/src/meta_contributing.rs @@ -14,7 +14,7 @@ //! documentation up-to-date, as the overhead is reduced by making sure everything is in one //! repository, and everything being in `.rs` files. //! -//! > This is not say that a more visually appealing version of this crate (for example as an +//! > This is not to say that a more visually appealing version of this crate (for example as an //! > `md-book`) cannot exist, but it would be outside the scope of this crate. //! //! Moreover, we acknowledge that a major pain point has been not only outdated *concepts*, but also diff --git a/docs/sdk/src/polkadot_sdk/frame_runtime.rs b/docs/sdk/src/polkadot_sdk/frame_runtime.rs index 39255c8f51ad6..8acf19f764137 100644 --- a/docs/sdk/src/polkadot_sdk/frame_runtime.rs +++ b/docs/sdk/src/polkadot_sdk/frame_runtime.rs @@ -54,7 +54,7 @@ //! //! ### Example //! -//! The following examples showcases a minimal pallet. +//! The following example showcases a minimal pallet. #![doc = docify::embed!("src/polkadot_sdk/frame_runtime.rs", pallet)] //! //! @@ -85,7 +85,7 @@ //! [`crate::reference_docs::wasm_meta_protocol`]). Notable examples are: //! //! * writing a runtime in pure Rust, as done in [this template](https://github.com/JoshOrndorff/frameless-node-template). -//! * writing a runtime in AssemblyScript,as explored in [this project](https://github.com/LimeChain/subsembly). +//! * writing a runtime in AssemblyScript, as explored in [this project](https://github.com/LimeChain/subsembly). /// A FRAME based pallet. This `mod` is the entry point for everything else. All /// `#[pallet::xxx]` macros must be defined in this `mod`. Although, frame also provides an @@ -119,11 +119,11 @@ pub mod pallet { #[pallet::pallet] pub struct Pallet(PhantomData); - /// The events tha this pallet can emit. + /// The events that this pallet can emit. #[pallet::event] pub enum Event {} - /// A storage item that this pallet contains. This will be part of the state root trie/root + /// A storage item that this pallet contains. This will be part of the state root trie /// of the blockchain. #[pallet::storage] pub type Value = StorageValue; diff --git a/docs/sdk/src/polkadot_sdk/mod.rs b/docs/sdk/src/polkadot_sdk/mod.rs index 124d391421b90..32cad72fba7e2 100644 --- a/docs/sdk/src/polkadot_sdk/mod.rs +++ b/docs/sdk/src/polkadot_sdk/mod.rs @@ -12,7 +12,7 @@ //! //! [![RFCs](https://img.shields.io/badge/fellowship-RFCs-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/rfcs) //! [![Runtime](https://img.shields.io/badge/fellowship-runtimes-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/runtimes) -//! [![Manifesto](https://img.shields.io/badge/fellowship-manifesto-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/manifesto) +//! [![Manifesto](https://img.shields.io/badge/fellowship-manifesto-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/manifesto/blob/main/manifesto.pdf) //! //! ## Getting Started //! @@ -34,7 +34,7 @@ //! Repo](https://img.shields.io/badge/github-substrate-2324CC85)](https://github.com/paritytech/polkadot-sdk/blob/master/substrate) //! //! [`substrate`] is the base blockchain framework used to power the Polkadot SDK. It is a full -//! toolkit to create sovereign blockchains, including but not limited to those who connect to +//! toolkit to create sovereign blockchains, including but not limited to those which connect to //! Polkadot as parachains. //! //! #### FRAME @@ -82,7 +82,7 @@ //! //! A Substrate-based chain is a blockchain composed of a runtime and a node. As noted above, the //! runtime is the application logic of the blockchain, and the node is everything else. -//! See [`crate::reference_docs::wasm_meta_protocol`] for an in-depth explanation of this. The +//! See [`reference_docs::wasm_meta_protocol`] for an in-depth explanation of this. The //! former is built with [`frame`], and the latter is built with rest of Substrate. //! //! > You can think of a Substrate-based chain as a white-labeled blockchain. @@ -103,8 +103,8 @@ //! //! ## Trophy Section: Notable Downstream Projects //! -//! A list of projects and tools in the blockchain ecosystem that one way or another parts of the -//! Polkadot SDK: +//! A list of projects and tools in the blockchain ecosystem that one way or another use parts of +//! the Polkadot SDK: //! //! * [Polygon's spin-off, Avail](https://github.com/availproject/avail) //! * [Cardano Partner Chains](https://iohk.io/en/blog/posts/2023/11/03/partner-chains-are-coming-to-cardano/) @@ -116,7 +116,7 @@ //! [`polkadot`]: crate::polkadot_sdk::polkadot //! [`xcm`]: crate::polkadot_sdk::xcm -/// Lean about Cumulus, the framework that transforms [`substrate`]-based chains into +/// Learn about Cumulus, the framework that transforms [`substrate`]-based chains into /// [`polkadot`]-enabled parachains. pub mod cumulus; /// Learn about FRAME, the framework used to build Substrate runtimes. diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index e2dcca4dc7dfc..69532f323b9db 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -8,18 +8,18 @@ //! - [Polkadot Parachains](https://parachains.info/) //! - [Polkadot (multi-chain) Explorer: Subscan](https://subscan.io/) //! - Polkadot Fellowship -//! - [Manifesto](https://github.com/polkadot-fellows/manifesto) +//! - [Manifesto](https://github.com/polkadot-fellows/manifesto/blob/main/manifesto.pdf) //! - [Runtimes](https://github.com/polkadot-fellows/runtimes) //! - [RFCs](https://github.com/polkadot-fellows/rfcs) //! - [Dashboard](https://polkadot-fellows.github.io/dashboard/) -//! - [Polkadot Specs](spec.polkadot.network) +//! - [Polkadot Specs](http://spec.polkadot.network) //! - [The Polkadot Parachain Host Implementers' Guide](https://paritytech.github.io/polkadot-sdk/book/) //! - [Whitepaper](https://www.polkadot.network/whitepaper/) //! - [JAM Graypaper](https://graypaper.com) //! //! ## Alternative Node Implementations 🌈 //! -//! - [Smoldot](https://crates.io/crates/smoldot-light). Polkadot light node/client. +//! - [Smoldot](https://docs.rs/crate/smoldot-light/latest). Polkadot light node/client. //! - [KAGOME](https://github.com/qdrvm/kagome). C++ implementation of the Polkadot host. //! - [Gossamer](https://github.com/ChainSafe/gossamer). Golang implementation of the Polkadot host. //! @@ -45,7 +45,7 @@ //! > their execution and governance sovereignty. These chains are called "Parachains". //! //! * Shared Security: The idea of shared economic security sits at the core of Polkadot. Polkadot -//! enables different parachains* to pool their economic security from Polkadot (i.e. "*Relay +//! enables different parachains to pool their economic security from Polkadot (i.e. "*Relay //! Chain*"). //! * (heterogenous) Sharded Execution: Yet, each parachain is free to have its own execution logic //! (runtime), which also encompasses governance and sovereignty. Moreover, Polkadot ensures the @@ -80,7 +80,7 @@ //! Within the scope of Polkadot 1.x, two main scheduling ways have been considered: //! //! * Long term Parachains, obtained through locking a sum of DOT in an auction system. -//! * on-demand Parachains, purchased through paying DOT to the relay-chain whenever needed. +//! * On-demand Parachains, purchased through paying DOT to the relay-chain whenever needed. //! //! ### The Future //! diff --git a/docs/sdk/src/polkadot_sdk/substrate.rs b/docs/sdk/src/polkadot_sdk/substrate.rs index 69d74d86db1b5..56b89f8c9c2a3 100644 --- a/docs/sdk/src/polkadot_sdk/substrate.rs +++ b/docs/sdk/src/polkadot_sdk/substrate.rs @@ -11,9 +11,9 @@ //! 1. Society and technology evolves. //! 2. Humans are fallible. //! -//! This, makes the task of designing a correct, safe and long-lasting blockchain system hard. +//! This makes the task of designing a correct, safe and long-lasting blockchain system hard. //! -//! Nonetheless, in strive towards achieve this goal, Substrate embraces the following: +//! Nonetheless, in strive towards achieving this goal, Substrate embraces the following: //! //! 1. Use of **Rust** as a modern and safe programming language, which limits human error through //! various means, most notably memory and type safety. @@ -27,7 +27,7 @@ //! blob. //! //! In essence, the meta-protocol of all Substrate based chains is the "Runtime as WASM blob" -//! accord. This enables the Runtime to become inherently upgradeable, crucially without forks. The +//! accord. This enables the Runtime to become inherently upgradeable, crucially without [forks](https://en.wikipedia.org/wiki/Fork_(blockchain)). The //! upgrade is merely a matter of the WASM blob being changed in the state, which is, in principle, //! same as updating an account's balance. Learn more about this in detail in //! [`crate::reference_docs::wasm_meta_protocol`]. @@ -63,9 +63,9 @@ //! categories: //! //! * `sc-*` (short for *Substrate-client*) crates, located under `./client` folder. These are all -//! the crates that lead to the node software. Notable examples [`sc_network`], various consensus -//! crates, RPC ([`sc_rpc_api`]) and database ([`sc_client_db`]), all of which are expected to -//! reside in the node side. +//! the crates that lead to the node software. Notable examples are [`sc_network`], various +//! consensus crates, RPC ([`sc_rpc_api`]) and database ([`sc_client_db`]), all of which are +//! expected to reside in the node side. //! * `sp-*` (short for *substrate-primitives*) crates, located under `./primitives` folder. These //! are crates that facilitate both the node and the runtime, but are not opinionated about what //! framework is using for building the runtime. Notable examples are [`sp_api`] and [`sp_io`], @@ -86,7 +86,9 @@ //! //! Substrate-based runtimes use [`substrate_wasm_builder`] in their `build.rs` to automatically //! build their WASM files as a part of normal build command (e.g. `cargo build`). Once built, the -//! wasm file is placed in `./target/{debug|release}/wbuild/{runtime_name}.wasm`. +//! wasm file is placed in `./target/{debug|release}/wbuild/{runtime_name}/{runtime_name}.wasm`. +//! +//! In order to ensure that the WASM build is **deterministic**, the [Substrate Runtime Toolbox (srtool)](https://github.com/paritytech/srtool) can be used. //! //! ### Binaries //! diff --git a/docs/sdk/src/polkadot_sdk/xcm.rs b/docs/sdk/src/polkadot_sdk/xcm.rs index 58f5406864244..20841b0b55b93 100644 --- a/docs/sdk/src/polkadot_sdk/xcm.rs +++ b/docs/sdk/src/polkadot_sdk/xcm.rs @@ -5,7 +5,7 @@ //! //! ## Overview //! -//! XCM is a standard, whose specification lives in the [xcm format repo](https://github.com/paritytech/xcm-format). +//! XCM is a standard, specification of which lives in the [xcm format repo](https://github.com/paritytech/xcm-format). //! It's agnostic both in programming language and blockchain platform, which means it could be used //! in Rust in Polkadot, or in Go or C++ in any other platform like Cosmos or Ethereum. //! @@ -34,13 +34,12 @@ //! but will be moved to its own repo in the future. //! //! Its main components are: -//! - `src`: the definition of the basic types and instructions -//! - [`xcm-executor`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm_executor/struct.XcmExecutor.html): -//! an implementation of the virtual machine to execute instructions -//! - `pallet-xcm`: A FRAME pallet for interacting with the executor -//! - `xcm-builder`: a collection of types to configure the executor -//! - `xcm-simulator`: a playground for trying out different XCM programs and executor -//! configurations +//! - [`xcm`](::xcm): The definition of the basic types and instructions. +//! - [`xcm_executor`]: An implementation of the virtual machine to execute instructions. +//! - [`pallet_xcm`]: A FRAME pallet for interacting with the executor. +//! - [`xcm_builder`]: A collection of types to configure the executor. +//! - [`xcm_simulator`]: A playground for trying out different XCM programs and executor +//! configurations. //! //! ## Example //! diff --git a/docs/sdk/src/reference_docs/cli.rs b/docs/sdk/src/reference_docs/cli.rs index 5779e0f8d0495..b9cdbd60e9592 100644 --- a/docs/sdk/src/reference_docs/cli.rs +++ b/docs/sdk/src/reference_docs/cli.rs @@ -45,7 +45,7 @@ //! - `--chain=customSpec.json`: Uses the custom chain specification as input. //! - `--disable-default-bootnode`: Disables the default bootnodes in the node template. //! - `--raw`: Converts the chain specification into a raw format with encoded storage keys. -//! - `> customSpecRaw.json`: Outputs to customSpecRaw.json. +//! - `> customSpecRaw.json`: Outputs to `customSpecRaw.json`. //! //! #### Starting the First Node in a Private Network //! ```bash diff --git a/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs b/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs index 83a70606cb8dd..083ed9f77e102 100644 --- a/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs +++ b/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs @@ -1,7 +1,7 @@ //! # Custom RPC do's and don'ts //! -//! **TLDR:** don't create new custom RPCs. Instead, rely on custom Runtime APIs, combined with -//! `state_call` +//! **TLDR:** Don't create new custom RPCs. Instead, rely on custom Runtime APIs, combined with +//! `state_call`. //! //! ## Background //! @@ -20,9 +20,9 @@ //! - To upgrade or add a new RPC logic, the RPC node has to be upgraded. This can cause significant //! trouble when the RPC infrastructure is decentralized as we will need to coordinate multiple //! parties to upgrade the RPC nodes. -//! - A lot of boilerplate code are required to add custom RPC. -//! - It prevents the dApp to use a light client or alternative client. -//! - It makes ecosystem tooling integration much more complicated. For example, the dApp will not +//! - A lot of boilerplate code is required to add custom RPC. +//! - It prevents dApps from using a light client or an alternative client. +//! - It makes ecosystem tooling integration much more complicated. For example, dApps will not //! be able to use [Chopsticks](https://github.com/AcalaNetwork/chopsticks) for testing as //! Chopsticks will not have the custom RPC implementation. //! - Poorly implemented custom RPC can be a DoS vector. @@ -50,7 +50,7 @@ //! //! ## Create a new Runtime API //! -//! For example, let's take a look a the process through which the account nonce can be queried +//! For example, let's take a look at the process through which the account nonce can be queried //! through an RPC. First, a new runtime-api needs to be declared: #![doc = docify::embed!("../../substrate/frame/system/rpc/runtime-api/src/lib.rs", AccountNonceApi)] //! diff --git a/docs/sdk/src/reference_docs/defensive_programming.rs b/docs/sdk/src/reference_docs/defensive_programming.rs index 9828e1b50918f..82d624b01d97f 100644 --- a/docs/sdk/src/reference_docs/defensive_programming.rs +++ b/docs/sdk/src/reference_docs/defensive_programming.rs @@ -16,7 +16,7 @@ //! [Defensive programming](https://en.wikipedia.org/wiki/Defensive_programming) is a design paradigm that enables a program to continue //! running despite unexpected behavior, input, or events that may arise in runtime. //! Usually, unforeseen circumstances may cause the program to stop or, in the Rust context, -//! panic!. Defensive practices allow for these circumstances to be accounted for ahead of time +//! `panic!`. Defensive practices allow for these circumstances to be accounted for ahead of time //! and for them to be handled gracefully, which is in line with the intended fault-tolerant and //! deterministic nature of blockchains. //! @@ -71,7 +71,7 @@ //! ### Defensive Traits //! //! The [`Defensive`](frame::traits::Defensive) trait provides a number of functions, all of which -//! provide an alternative to 'vanilla' Rust functions, e.g.,: +//! provide an alternative to 'vanilla' Rust functions, e.g.: //! //! - [`defensive_unwrap_or()`](frame::traits::Defensive::defensive_unwrap_or) instead of //! `unwrap_or()` @@ -127,7 +127,7 @@ //! - [Fixed point types](sp_arithmetic::fixed_point) and their associated usage can be found here. //! - [PerThing](sp_arithmetic::per_things) and its associated types can be found here. //! -//! Using floating point number types (i.e., f32. f64) in the runtime should be avoided, as a single non-deterministic result could cause chaos for blockchain consensus along with the issues above. For more on the specifics of the peculiarities of floating point calculations, [watch this video by the Computerphile](https://www.youtube.com/watch?v=PZRI1IfStY0). +//! Using floating point number types (i.e. f32, f64) in the runtime should be avoided, as a single non-deterministic result could cause chaos for blockchain consensus along with the issues above. For more on the specifics of the peculiarities of floating point calculations, [watch this video by the Computerphile](https://www.youtube.com/watch?v=PZRI1IfStY0). //! //! The following methods demonstrate different ways to handle numbers natively in Rust safely, //! without fear of panic or unexpected behavior from wrapping. diff --git a/docs/sdk/src/reference_docs/development_environment_advice.rs b/docs/sdk/src/reference_docs/development_environment_advice.rs index 9ba95dfa03294..a5f38bb280def 100644 --- a/docs/sdk/src/reference_docs/development_environment_advice.rs +++ b/docs/sdk/src/reference_docs/development_environment_advice.rs @@ -15,8 +15,9 @@ //! ```json //! { //! // Use a separate target dir for Rust Analyzer. Helpful if you want to use Rust -//! // Analyzer and cargo on the command line at the same time. -//! "rust-analyzer.rust.analyzerTargetDir": "target/vscode-rust-analyzer", +//! // Analyzer and cargo on the command line at the same time, +//! // at the expense of duplicating build artifacts. +//! "rust-analyzer.cargo.targetDir": "target/vscode-rust-analyzer", //! // Improve stability //! "rust-analyzer.server.extraEnv": { //! "CHALK_OVERFLOW_DEPTH": "100000000", @@ -145,7 +146,7 @@ //! } //! ``` //! -//! //! and the same in Lua for `neovim/nvim-lspconfig`: +//! and the same in Lua for `neovim/nvim-lspconfig`: //! //! ```lua //! ["rust-analyzer"] = { diff --git a/docs/sdk/src/reference_docs/frame_benchmarking_weight.rs b/docs/sdk/src/reference_docs/frame_benchmarking_weight.rs index db77547a4bf0f..cf9e587914923 100644 --- a/docs/sdk/src/reference_docs/frame_benchmarking_weight.rs +++ b/docs/sdk/src/reference_docs/frame_benchmarking_weight.rs @@ -14,10 +14,10 @@ //! - improve documentation of `#[weight = ..]` and `#[pallet::weight(..)]`. All syntax variation //! should be covered. //! -//! on FRAME benchmarking machinery: +//! On FRAME benchmarking machinery: //! -//! - component analysis, why everything must be linear. -//! - how to write benchmarks, how you must think of worst case. -//! - how to run benchmarks. +//! - Component analysis, why everything must be linear. +//! - How to write benchmarks, how you must think of worst case. +//! - How to run benchmarks. //! //! - diff --git a/docs/sdk/src/reference_docs/frame_logging.rs b/docs/sdk/src/reference_docs/frame_logging.rs index 301fa7ef83f82..1b03c6a2e35b5 100644 --- a/docs/sdk/src/reference_docs/frame_logging.rs +++ b/docs/sdk/src/reference_docs/frame_logging.rs @@ -34,9 +34,9 @@ //! //! ## Using `log` //! -//! First, ensure you are familiar with the `log` crate. In short, each log statement has: +//! First, ensure you are familiar with the [`log`] crate. In short, each log statement has: //! -//! 1. `log-level`, signifying how important it is +//! 1. `log-level`, signifying how important it is. //! 2. `log-target`, signifying to which component it belongs. //! //! Add log statements to your pallet as such: diff --git a/docs/sdk/src/reference_docs/frame_offchain_workers.rs b/docs/sdk/src/reference_docs/frame_offchain_workers.rs index 1ec9212e23066..b0aaf1789d4cc 100644 --- a/docs/sdk/src/reference_docs/frame_offchain_workers.rs +++ b/docs/sdk/src/reference_docs/frame_offchain_workers.rs @@ -88,7 +88,7 @@ //! //! They can both read from the state, and have no means of updating the state, other than the route //! of submitting an extrinsic to the chain. Therefore, it is worth thinking twice before embedding -//! a logic as a part of Substrate's offchain worker API. Does it have to be there? can it not be a +//! a logic as a part of Substrate's offchain worker API. Does it have to be there? Can it not be a //! simple, actual offchain application that lives outside of the chain's WASM blob? //! //! Some of the reasons why you might want to do the opposite, and actually embed an offchain worker diff --git a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs index be464bbbf8359..a22137f979dc1 100644 --- a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs +++ b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs @@ -30,8 +30,8 @@ //! //! There are generally two ways to achieve this: //! -//! 1. Tight coupling pallets -//! 2. Loose coupling pallets +//! 1. Tight coupling pallets. +//! 2. Loose coupling pallets. //! //! To explain the difference between the two, consider two pallets, `A` and `B`. In both cases, `A` //! wants to use some functionality exposed by `B`. @@ -74,8 +74,8 @@ //! pallet makes its own `trait Config` be bounded by another pallet's `trait Config`, it is //! expressing two things: //! -//! 1. that it can only exist in a runtime if the other pallet is also present. -//! 2. that it can use the other pallet's functionality. +//! 1. That it can only exist in a runtime if the other pallet is also present. +//! 2. That it can use the other pallet's functionality. //! //! `pallet-foo`'s `Config` would then look like: #![doc = docify::embed!("./src/reference_docs/frame_pallet_coupling.rs", tight_config)] @@ -110,7 +110,7 @@ //! Crucially, when using loose coupling, we gain the flexibility of providing different //! implementations of `AuthorProvider`, such that different users of a `pallet-foo` can use //! different ones, without any code change being needed. For example, in the code snippets of this -//! module, you can fund [`OtherAuthorProvider`] which is an alternative implementation of +//! module, you can find [`OtherAuthorProvider`], which is an alternative implementation of //! [`AuthorProvider`]. #![doc = docify::embed!("./src/reference_docs/frame_pallet_coupling.rs", other_author_provider)] //! @@ -135,8 +135,8 @@ //! general, it is easier to argue about multiple pallet if they only communicate together via a //! known trait, rather than having access to all of each others public items, such as storage and //! dispatchables. -//! * If a group of pallets are meant to work together, and but are not foreseen to be generalized, -//! or used by others, consider tightly coupling pallets, *if it simplifies the development*. +//! * If a group of pallets is meant to work together, but is not foreseen to be generalized, or +//! used by others, consider tightly coupling pallets, *if it simplifies the development*. //! * If a pallet needs a functionality provided by another pallet, but multiple implementations can //! be foreseen, consider loosely coupling pallets. //! diff --git a/docs/sdk/src/reference_docs/frame_runtime_types.rs b/docs/sdk/src/reference_docs/frame_runtime_types.rs index 1eed9857a1d59..e99106ade8781 100644 --- a/docs/sdk/src/reference_docs/frame_runtime_types.rs +++ b/docs/sdk/src/reference_docs/frame_runtime_types.rs @@ -36,7 +36,7 @@ #![doc = docify::embed!("./src/reference_docs/frame_runtime_types.rs", pallet_bar)] //! //! Let's explore how each of these affect the [`RuntimeCall`], [`RuntimeOrigin`] and -//! [`RuntimeGenesisConfig`] generated in [`runtime`] by respectively. +//! [`RuntimeGenesisConfig`] generated in [`runtime`] respectively. //! //! As observed, [`RuntimeCall`] has 3 variants, one for each pallet and one for `frame_system`. If //! you explore further, you will soon realize that each variant is merely a pointer to the `Call` diff --git a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs index f9a69b892a315..065cbee25709b 100644 --- a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs +++ b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs @@ -2,8 +2,8 @@ //! //! At their core, blockchain logic consists of //! -//! 1. on-chain state and -//! 2. a state transition function +//! 1. on-chain state, +//! 2. a state transition function. //! //! In Substrate-based blockchains, state transition functions are referred to as //! [runtimes](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/blockchain_state_machines/index.html). @@ -43,9 +43,9 @@ //! for example when the encoding of a storage item is changed. However, they can also execute //! arbitrary logic such as: //! -//! - Calling arbitrary pallet methods -//! - Mutating arbitrary on-chain state -//! - Cleaning up some old storage items that are no longer needed +//! - Calling arbitrary pallet methods. +//! - Mutating arbitrary on-chain state. +//! - Cleaning up some old storage items that are no longer needed. //! //! ## Single Block Migrations //! @@ -88,9 +88,9 @@ //! //! Prior to deploying migrations, it is critical to perform additional checks to ensure that when //! run in our real runtime they will not brick the chain due to: -//! - Panicking -//! - Touching too many storage keys and resulting in an excessively large PoV -//! - Taking too long to execute +//! - Panicking. +//! - Touching too many storage keys and resulting in an excessively large PoV. +//! - Taking too long to execute. //! //! [`try-runtime-cli`](https://github.com/paritytech/try-runtime-cli) has a sub-command //! [`on-runtime-upgrade`](https://paritytech.github.io/try-runtime-cli/try_runtime_core/commands/enum.Action.html#variant.OnRuntimeUpgrade) @@ -129,7 +129,9 @@ //! //! Suitable for migrations which could use arbitrary amounts of block weight. //! -//! TODO: Link to multi block migration example/s once PR is merged (). +//! See the +//! [multi-block-migrations example](https://github.com/paritytech/polkadot-sdk/tree/0d7d2177807ec6b3094f4491a45b0bc0d74d3c8b/substrate/frame/examples/multi-block-migrations) +//! for reference. //! //! [`OnRuntimeUpgrade`]: frame_support::traits::OnRuntimeUpgrade //! [`StorageVersion`]: frame_support::traits::StorageVersion diff --git a/docs/sdk/src/reference_docs/frame_storage_derives.rs b/docs/sdk/src/reference_docs/frame_storage_derives.rs index 3d9edef398a07..4fbfb4a5cc839 100644 --- a/docs/sdk/src/reference_docs/frame_storage_derives.rs +++ b/docs/sdk/src/reference_docs/frame_storage_derives.rs @@ -1,6 +1,9 @@ -//!
-//! In all examples, a few lines of boilerplate have been hidden from each snippet for conciseness. -//!
+//! # Frame storage derives +//! +//! > **Note:** +//! > +//! > In all examples, a few lines of boilerplate have been hidden from each snippet for +//! > conciseness. //! //! Let's begin by starting to store a `NewType` in a storage item: //! @@ -134,7 +137,7 @@ //! - [`frame::prelude::PartialOrdNoBound`] //! - [`frame::prelude::OrdNoBound`] //! -//! The above traits are almost certainly needed for your tests: To print your type, assert equality +//! The above traits are almost certainly needed for your tests - to print your type, assert equality //! or clone it. //! //! We can fix the following example by using [`frame::prelude::DefaultNoBound`]. diff --git a/docs/sdk/src/reference_docs/frame_system_accounts.rs b/docs/sdk/src/reference_docs/frame_system_accounts.rs index 523fe70430849..c93e1196ea7e8 100644 --- a/docs/sdk/src/reference_docs/frame_system_accounts.rs +++ b/docs/sdk/src/reference_docs/frame_system_accounts.rs @@ -1,6 +1,6 @@ //! # FRAME Accounts //! -//! //! 🚧 Work In Progress 🚧 +//! 🚧 Work In Progress 🚧 //! //! How `frame_system` handles accountIds. Nonce. Consumers and Providers, reference counting. diff --git a/docs/sdk/src/reference_docs/frame_tokens.rs b/docs/sdk/src/reference_docs/frame_tokens.rs index 57b493fafa59c..a76e524ceb854 100644 --- a/docs/sdk/src/reference_docs/frame_tokens.rs +++ b/docs/sdk/src/reference_docs/frame_tokens.rs @@ -22,11 +22,11 @@ //! //! On completion of reading this doc, you should have a good understanding of: //! - The distinction between token traits and trait implementations in FRAME, and why this -//! distinction is helpful -//! - Token-related traits available in FRAME -//! - Token-related trait implementations in FRAME -//! - How to choose the right trait or trait implementation for your use case -//! - Where to go next +//! distinction is helpful. +//! - Token-related traits available in FRAME. +//! - Token-related trait implementations in FRAME. +//! - How to choose the right trait or trait implementation for your use case. +//! - Where to go next. //! //! ## Getting Started //! @@ -56,9 +56,16 @@ //! //! **Trait implementations** are concrete implementations of these traits. For example, one of the //! many traits [`pallet_balances`] implements is -//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`)*. It provides the concrete way -//! of inspecting the total issuance, balance of accounts, etc. There can be many implementations of -//! the same traits. +//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`)[^1]. It provides the concrete +//! way of inspecting the total issuance, balance of accounts, etc. There can be many +//! implementations of the same traits. +//! +//! [^1]: Rust Advanced Tip: The knowledge that [`pallet_balances`] implements +//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`) is not some arcane knowledge +//! that you have to know by heart or memorize. One can simply look at the list of the implementors +//! of any trait in the Rust Doc to find all implementors (e.g. +//! [Mutate trait implementors](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/tokens/fungible/trait.Mutate.html#implementors)), +//! or use the `rust-analyzer`'s `Implementations` action. //! //! The distinction between traits and trait implementations is helpful because it allows pallets //! and other logic to be generic over their dependencies, avoiding tight coupling. @@ -68,10 +75,10 @@ //! pallet may use [`pallet_balances`] in a tightly coupled manner, directly calling methods //! on the pallet to reserve and unreserve deposits. This approach works well, //! until someone has a use case requiring that an asset from a different pallet such as -//! [`pallet_assets`] is used for the deposit. Rather than tightly couple [`pallet_preimage`] to -//! [`pallet_balances`], [`pallet_assets`], and every other token-handling pallet a user -//! could possibly specify, [`pallet_preimage`] does not specify a concrete pallet as a dependency -//! but instead accepts any dependency which implements the +//! [`pallet_assets`] is used for the deposit. Rather than tightly coupling [`pallet_preimage`] to +//! [`pallet_balances`], [`pallet_assets`], and every other token-handling pallet, a user +//! could possibly specify that [`pallet_preimage`] does not specify a concrete pallet as a +//! dependency, but instead accepts any dependency which implements the //! [`currency::ReservableCurrency`](`frame_support::traits::tokens::currency::ReservableCurrency`) //! trait, namely via its [`Config::Currency`](`pallet_preimage::pallet::Config::Currency`) //! associated type. This allows [`pallet_preimage`] to support any arbitrary pallet implementing @@ -81,15 +88,6 @@ //! Read more about coupling, and the benefits of loose coupling //! [here](crate::reference_docs::frame_pallet_coupling). //! -//! ##### *Rust Advanced Tip -//! -//! The knowledge that [`pallet_balances`] implements -//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`) is not some arcane knowledge -//! that you have to know by heart or memorize. One can simply look at the list of the implementors -//! of any trait in the Rust Doc to find all implementors (e.g. -//! ), -//! or use the `rust-analyzer` `Implementations` action. -//! //! ## Fungible Token Traits in FRAME //! //! The [`fungible`](`frame_support::traits::fungible`) crate contains the latest set of FRAME diff --git a/docs/sdk/src/reference_docs/metadata.rs b/docs/sdk/src/reference_docs/metadata.rs index 96f92ac0c412b..485614088140e 100644 --- a/docs/sdk/src/reference_docs/metadata.rs +++ b/docs/sdk/src/reference_docs/metadata.rs @@ -21,5 +21,5 @@ //! //! A few noteworthy tools that inspect the (FRAME-based) metadata of a chain: //! -//! -//! +//! - +//! - diff --git a/docs/sdk/src/reference_docs/mod.rs b/docs/sdk/src/reference_docs/mod.rs index c69c79365427e..7f2edb08d46e9 100644 --- a/docs/sdk/src/reference_docs/mod.rs +++ b/docs/sdk/src/reference_docs/mod.rs @@ -7,14 +7,15 @@ //! //! ## What is a "reference document"? //! -//! First, see [why we use rust-docs for everything](crate#why-rust-docs) and our documentation -//! [principles](crate#principles). We acknowledge that as much of the crucial information should be -//! embedded in the low level rust-docs. Then, high level scenarios should be covered in -//! [`crate::guides`]. Finally, we acknowledge that there is a category of information that is: +//! First, see [why we use rust-docs for everything](crate::meta_contributing#why-rust-docs) and our +//! documentation [principles](crate::meta_contributing#principles). We acknowledge that as much of +//! the crucial information should be embedded in the low level rust-docs. Then, high level +//! scenarios should be covered in [`crate::guides`]. Finally, we acknowledge that there is a +//! category of information that is: //! -//! 1. crucial to know. -//! 2. is too high level to be in the rust-doc of any one `type`, `trait` or `fn`. -//! 3. is too low level to be encompassed in a [`crate::guides`]. +//! 1. Crucial to know. +//! 2. Is too high level to be in the rust-doc of any one `type`, `trait` or `fn`. +//! 3. Is too low level to be encompassed in a [`crate::guides`]. //! //! We call this class of documents "reference documents". Our goal should be to minimize the number //! of "reference" docs, as they incur maintenance burden. @@ -52,8 +53,8 @@ pub mod frame_storage_derives; /// Learn about how to write safe and defensive code in your FRAME runtime. pub mod defensive_programming; -/// Learn about composite enums and other runtime level types, such as "RuntimeEvent" and -/// "RuntimeCall". +/// Learn about composite enums and other runtime level types, such as `RuntimeEvent` and +/// `RuntimeCall`. pub mod frame_runtime_types; /// Learn about how to make a pallet/runtime that is fee-less and instead uses another mechanism to diff --git a/docs/sdk/src/reference_docs/runtime_vs_smart_contract.rs b/docs/sdk/src/reference_docs/runtime_vs_smart_contract.rs index 379b0c11b2ad0..4a0ba3ca48f5a 100644 --- a/docs/sdk/src/reference_docs/runtime_vs_smart_contract.rs +++ b/docs/sdk/src/reference_docs/runtime_vs_smart_contract.rs @@ -32,21 +32,14 @@ //! //! ## Comparative Table //! -//! | Aspect | Runtime -//! | Smart Contracts | +//! | Aspect | Runtime | Smart Contracts | //! |-----------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------| -//! | **Design Philosophy** | Core logic of a blockchain, allowing broad and deep customization. -//! | Designed for DApps deployed on the blockchain runtime.| | **Development Complexity** | Requires in-depth knowledge of Rust and Substrate. Suitable for complex blockchain architectures. | Easier to develop with knowledge of Smart Contract languages like Solidity or [ink!](https://use.ink/). | -//! | **Upgradeability and Flexibility** | Offers comprehensive upgradeability with migration logic -//! and on-chain governance, allowing modifications to the entire blockchain logic without hard -//! forks. | Less flexible in upgrade migrations but offers more straightforward deployment and -//! iteration. | | **Performance and Efficiency** | More efficient, optimized for specific needs of -//! the blockchain. | Can be less efficient due to its generic nature (e.g. the overhead of a -//! virtual machine). | | **Security Considerations** | Security flaws can affect the entire -//! blockchain. | Security risks usually localized to the individual -//! contract. | | **Weighing and Metering** | Operations can be weighed, allowing for precise -//! benchmarking. | Execution is metered, allowing for measurement of resource -//! consumption. | +//! | **Design Philosophy** | Core logic of a blockchain, allowing broad and deep customization. | Designed for DApps deployed on the blockchain runtime. | +//! | **Development Complexity** | Requires in-depth knowledge of Rust and Substrate. Suitable for complex blockchain architectures. | Easier to develop with knowledge of Smart Contract languages like Solidity or [ink!](https://use.ink/). | +//! | **Upgradeability and Flexibility** | Offers comprehensive upgradeability with migration logic and on-chain governance, allowing modifications to the entire blockchain logic without hard forks. | Less flexible in upgrade migrations but offers more straightforward deployment and iteration. | +//! | **Performance and Efficiency** | More efficient, optimized for specific needs of the blockchain. | Can be less efficient due to its generic nature (e.g. the overhead of a virtual machine). | +//! | **Security Considerations** | Security flaws can affect the entire blockchain. | Security risks usually localized to the individual contract. | +//! | **Weighing and Metering** | Operations can be weighed, allowing for precise benchmarking. | Execution is metered, allowing for measurement of resource consumption. | //! //! We will now explore these differences in more detail. //! diff --git a/docs/sdk/src/reference_docs/trait_based_programming.rs b/docs/sdk/src/reference_docs/trait_based_programming.rs index ace3138807071..90b38f63a5809 100644 --- a/docs/sdk/src/reference_docs/trait_based_programming.rs +++ b/docs/sdk/src/reference_docs/trait_based_programming.rs @@ -196,7 +196,7 @@ mod with_system { mod fully_qualified { use super::with_system::*; - // Simple of using fully qualified syntax. + // Example of using fully qualified syntax. type AccountIdOf = ::AccountId; } diff --git a/docs/sdk/src/reference_docs/umbrella_crate.rs b/docs/sdk/src/reference_docs/umbrella_crate.rs index 0b3445cfc4bc0..1074cde37693d 100644 --- a/docs/sdk/src/reference_docs/umbrella_crate.rs +++ b/docs/sdk/src/reference_docs/umbrella_crate.rs @@ -25,7 +25,7 @@ //! - `runtime`: As described above, enable all `no-std` crates. //! - `node`: As described above, enable all `std` crates. //! - There does *not* exist a dedicated docs feature. To generate docs, enable the `runtime` and -//! `node` feature. For docs.rs the manifest contains specific configuration to make it show up +//! `node` feature. For `docs.rs` the manifest contains specific configuration to make it show up //! all re-exports. //! //! There is a specific [`zepter`](https://github.com/ggwpez/zepter) check in place to ensure that @@ -77,7 +77,7 @@ //! ``` //! //! Apart from this, no issues are known. There could be some bugs with how macros locate their own -//! re-exports. Please compile issues that arise from using this crate. +//! re-exports. Please [report issues](https://github.com/paritytech/polkadot-sdk/issues) that arise from using this crate. //! //! ## Dependencies //! diff --git a/docs/sdk/src/reference_docs/wasm_meta_protocol.rs b/docs/sdk/src/reference_docs/wasm_meta_protocol.rs index 0e91e65c55e36..55b5cb204dc2d 100644 --- a/docs/sdk/src/reference_docs/wasm_meta_protocol.rs +++ b/docs/sdk/src/reference_docs/wasm_meta_protocol.rs @@ -29,7 +29,7 @@ //! Rust to different hardware targets. //! //! This design enables all Substrate-based chains to be fork-less-ly upgradeable, because the -//! Runtime can be updates on the fly, within the execution of a block, and the node is (for the +//! Runtime can be updated on the fly, within the execution of a block, and the node is (for the //! most part) oblivious to the change that is happening. //! //! Therefore, the high-level architecture of a any Substrate-based chain can be demonstrated as @@ -82,7 +82,7 @@ //! //! ## State //! -//! From the previous sections, we know that the a database component is part of the node, not the +//! From the previous sections, we know that the database component is part of the node, not the //! runtime. We also hinted that a set of host functions ([`sp_io::storage`]) are how the runtime //! issues commands to the node to read/write to the state. Let's dive deeper into this. //! @@ -143,13 +143,13 @@ //! At some point, based on the consensus algorithm's rules, the node decides to import (aka. //! *validate*) a block. //! -//! * First, the node will then fetch the state of the parent hash of the block that wishes to be +//! * First, the node will fetch the state of the parent hash of the block that wishes to be //! imported. //! * The runtime is fetched from this state, and placed into a WASM execution environment. -//! * The [`sp_api::Core::execute_block`] runtime API is called and the blocked is passed in as an +//! * The [`sp_api::Core::execute_block`] runtime API is called and the block is passed in as an //! argument. //! * The runtime will then execute the block, and update the state accordingly. Any state update is -//! issues via the [`sp_io::storage`] host functions. +//! issued via the [`sp_io::storage`] host functions. //! * Both the runtime and node will check the state-root of the state after the block execution to //! match the one claimed in the block header. //! diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index e1e1e0153de0c..bd571571ee24a 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -934,7 +934,7 @@ pub mod pallet_prelude { /// /// # 1 - Pallet module declaration /// -/// The module to declare a pallet is organized as follow: +/// The module to declare a pallet is organized as follows: /// ``` /// #[frame_support::pallet] // <- the macro /// mod pallet { @@ -1047,7 +1047,7 @@ pub mod pallet_prelude { /// If the attribute `set_storage_max_encoded_len` is set then the macro calls /// [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for each storage in the /// implementation of [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for the -/// pallet. Otherwise it implements +/// pallet. Otherwise, it implements /// [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for the pallet using the /// [`PartialStorageInfoTrait`](frame_support::traits::PartialStorageInfoTrait) /// implementation of storages.