From e3bb8bc7dc25960684e8963ca0df077cad41e04e Mon Sep 17 00:00:00 2001 From: Erin Shaben Date: Fri, 4 Oct 2024 15:36:46 -0400 Subject: [PATCH] grammar and formatting --- .../account-data-structure-1.rs} | 4 +- .../account-data-structure-2.rs} | 12 ++- .../accounts/account-data-structure.md | 90 ++++++++++--------- 3 files changed, 56 insertions(+), 50 deletions(-) rename .snippets/code/polkadot-protocol/protocol-components/accounts/{account-id-information.md => account-data-structure/account-data-structure-1.rs} (72%) rename .snippets/code/polkadot-protocol/protocol-components/accounts/{account-info.md => account-data-structure/account-data-structure-2.rs} (79%) diff --git a/.snippets/code/polkadot-protocol/protocol-components/accounts/account-id-information.md b/.snippets/code/polkadot-protocol/protocol-components/accounts/account-data-structure/account-data-structure-1.rs similarity index 72% rename from .snippets/code/polkadot-protocol/protocol-components/accounts/account-id-information.md rename to .snippets/code/polkadot-protocol/protocol-components/accounts/account-data-structure/account-data-structure-1.rs index ed3f45eed..cb754aae0 100644 --- a/.snippets/code/polkadot-protocol/protocol-components/accounts/account-id-information.md +++ b/.snippets/code/polkadot-protocol/protocol-components/accounts/account-data-structure/account-data-structure-1.rs @@ -1,5 +1,4 @@ -```rs -/// The full account information for a particular account ID. +/// The full account information for a particular account ID #[pallet::storage] #[pallet::getter(fn account)] pub type Account = StorageMap< @@ -9,4 +8,3 @@ pub type Account = StorageMap< AccountInfo, ValueQuery, >; -``` \ No newline at end of file diff --git a/.snippets/code/polkadot-protocol/protocol-components/accounts/account-info.md b/.snippets/code/polkadot-protocol/protocol-components/accounts/account-data-structure/account-data-structure-2.rs similarity index 79% rename from .snippets/code/polkadot-protocol/protocol-components/accounts/account-info.md rename to .snippets/code/polkadot-protocol/protocol-components/accounts/account-data-structure/account-data-structure-2.rs index 104c96a2c..9d28b0fd3 100644 --- a/.snippets/code/polkadot-protocol/protocol-components/accounts/account-info.md +++ b/.snippets/code/polkadot-protocol/protocol-components/accounts/account-data-structure/account-data-structure-2.rs @@ -1,19 +1,17 @@ -```rs #[derive(Clone, Eq, PartialEq, Default, RuntimeDebug, Encode, Decode)] pub struct AccountInfo { - /// The number of transactions this account has sent. + /// The number of transactions this account has sent pub nonce: Nonce, /// The number of other modules that currently depend on this account's existence. The account - /// cannot be reaped until this is zero. + /// cannot be reaped until this is zero pub consumers: RefCount, /// The number of other modules that allow this account to exist. The account may not be reaped - /// until this and `sufficients` are both zero. + /// until this and `sufficients` are both zero pub providers: RefCount, /// The number of modules that allow this account to exist for their own purposes only. The - /// account may not be reaped until this and `providers` are both zero. + /// account may not be reaped until this and `providers` are both zero pub sufficients: RefCount, /// The additional data that belongs to this account. Used to store the balance(s) in a lot of - /// chains. + /// chains pub data: AccountData, } -``` \ No newline at end of file diff --git a/polkadot-protocol/protocol-components/accounts/account-data-structure.md b/polkadot-protocol/protocol-components/accounts/account-data-structure.md index 967af68a2..754b6bb99 100644 --- a/polkadot-protocol/protocol-components/accounts/account-data-structure.md +++ b/polkadot-protocol/protocol-components/accounts/account-data-structure.md @@ -9,92 +9,102 @@ Accounts are a foundational element of any blockchain. This page explains how ac ## Account -The `Account` data type is a generically defined storage map within the [`frame-system`](https://paritytech.github.io/polkadot-sdk/master/src/frame_system/lib.rs.html#900){target=\_blank} pallet: +The [`Account` data type](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/type.Account.html) is a generically defined storage map within the [System pallet](https://paritytech.github.io/polkadot-sdk/master/src/frame_system/lib.rs.html){target=\_blank}: - --8<-- 'code/polkadot-protocol/protocol-components/accounts/account-id-information.md' +```rs + --8<-- 'code/polkadot-protocol/protocol-components/accounts/account-data-structure/account-data-structure-1.rs' +``` -The StorageMap for an Account consists of the following parameters: +This defines a storage map named `Account`. The `StorageMap` is a type of on-chain storage in Substrate that maps keys to values. Here, `T` represents the generic parameter for the runtime configuration, which is defined by the pallet's configuration trait (`Config`). -- The first parameter `(_)` is used in macro expansion. -- `Blake2_128Concat` specifies the hashing algorithm to use. -- `T::AccountId` is used as the key for over the `AccountInfo` struct. +The `StorageMap` consists of the following parameters: + +- **`_`** - used in macro expansion and acts as a placeholder for the storage prefix type. Since the default storage prefix (derived from the pallet and storage item name) is used here, it is represented as `_` (underscore), which tells the macro to insert the default prefix during expansion +- **`Blake2_128Concat`** - the hashing function used for keys in the storage map +- **`T::AccountId`** - the key type for the storage map, representing the account ID, which is used to access the corresponding `AccountInfo` struct in storage +- `AccountInfo` - the value type stored in the map. For each account ID, the map stores an `AccountInfo` struct containing: + - **`T::Nonce`** - a nonce for the account, which is incremented with each transaction to ensure transaction uniqueness + - **`T::AccountData`** - custom account data defined by the runtime configuration, which could include balances, locked funds, or other relevant information +- **`ValueQuery`** - a trait that defines how queries to the storage map behave when no value is found, returning the default value if a query for a key returns no result (instead of `None`) !!! note - See [StorageMap API](https://paritytech.github.io/polkadot-sdk/master/frame_support/storage/types/struct.StorageMap.html){target=\_blank} for more details. + See the [`StorageMap` API](https://paritytech.github.io/polkadot-sdk/master/frame_support/storage/types/struct.StorageMap.html){target=\_blank} for more details. ## Account Info -The `AccountInfo` for an account is also defined within the [`frame-system`](https://paritytech.github.io/polkadot-sdk/master/src/frame_system/lib.rs.html){target=\_blank} pallet: +The `AccountInfo` for an account is also defined within the [System pallet](https://paritytech.github.io/polkadot-sdk/master/src/frame_system/lib.rs.html){target=\_blank}: ---8<-- 'code/polkadot-protocol/protocol-components/accounts/account-info.md' +```rs +--8<-- 'code/polkadot-protocol/protocol-components/accounts/account-data-structure/account-data-structure-2.rs' +``` Each account has an `AccountInfo` structure that includes the following components: -- `nonce`: Tracks the number of transactions the account has sent. -- `consumers`: A reference counter indicating the number of other modules that depend on this account's existence. -- `providers`: A reference counter indicating the number of modules that permit this account to exist. -- `sufficients`: A reference counter indicating the number of modules that allow this account to exist for their own purposes only. -- `AccountData`: A configurable structure that can store various types of data specific to the account. +- **`nonce`** - the number of transactions the account has sent +- **`consumers`** - the number of other modules that depend on this account's existence +- **`providers`** - the number of modules that permit this account to exist +- **`sufficients`** - the number of modules that allow this account to exist for their own purposes only +- **`AccountData`** - a configurable structure that can store various types of data specific to the account ## Account Reference Counters -Account reference counters track dependencies in the runtime. For instance, if data is stored in a map associated with an account, you wouldn't want to delete the account until the data under its control has been removed. +Account reference counters track dependencies in the runtime and include the `consumers`, `providers`, and `sufficients` counters. For instance, if data is stored in a map associated with an account, you wouldn't want to delete the account until the data under its control has been removed. -The `consumers` and `providers` reference counters are intended to work together. For example, in the [`session`](https://docs.rs/pallet-session/latest/pallet_session/){target=\_blank} pallet, the consumers counter is incremented when an account sets its session keys before becoming a validator. +The `consumers` and `providers` reference counters are intended to work together. For example, in the [Session pallet](https://docs.rs/pallet-session/latest/pallet_session/){target=\_blank}, the `consumers` counter is incremented when an account sets its session keys before becoming a validator. -The providers counter must be greater than zero for the consumers counter to be incremented. +The `providers` counter must be greater than zero for the `consumers` counter to be incremented. ### Providers Reference Counters The `providers` reference counter indicates whether an account is ready to be depended upon. For example, it is incremented when a new account is created with a balance greater than the existential deposit. -The `providers` reference counter prevents Substrate pallets from storing data about an account until the account is active (`providers` > 0) +The `providers` reference counter prevents Substrate pallets from storing data about an account until the account is active (`providers` greater than 0). ### Consumers Reference Counters -The `consumers` reference counter ensures that other runtime pallets don't remove an account until all associated data across pallets is deleted (that is, when `consumers` == 0). +The `consumers` reference counter ensures that other runtime pallets don't remove an account until all associated data across pallets is deleted (that is, when `consumers` equal 0). It holds users accountable for the data they store on-chain. If users wish to delete their accounts and reclaim their existential deposit, they must first remove all data stored across all on-chain pallets to decrement the `consumers` counter. ### Sufficients Reference Counter -The `sufficients` reference counter indicates whether an account is self-sufficient and can exist independently. +The `sufficients` reference counter indicates whether an account is self-sufficient and can exist independently. -For example, in the [`assets`](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank} pallet, an account may hold a sufficient quantity of specific assets without needing to maintain a native account balance. +For example, in the [Assets pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank}, an account may hold a sufficient quantity of specific assets without maintaining a native account balance. -### Account Deactivation +### Account Deactivation -Pallets also include cleanup functions that decrement the `providers` reference counter, marking the account as deactivated within the pallet-managed scope. +Pallets also include cleanup functions that decrement the `providers` reference counter, marking the account as deactivated within the pallet-managed scope. -Once both the `providers` and `consumers` reference counters reach zero, the account is considered deactivated by all on-chain pallets. +Once both the `providers` and `consumers` reference counters reach zero, all on-chain pallets consider the account deactivated. ### Updating Counters -Runtime developers can manage these counters using the: +Runtime developers can manage these counters using the following: -- `inc_consumers()` - Increment the reference counter on an account. -- `dec_consumers()` - Decrement the reference counter on an account. -- `inc_providers()` - Increment the provider reference counter on an account. -- `dec_providers()` - Decrement the provider reference counter on an account. -- `inc_sufficients()` - Increment the self-sufficient reference counter on an account. -- `dec_sufficients()` - Decrement the sufficients reference counter on an account. +- **`inc_consumers()`** - increment the reference counter on an account +- **`dec_consumers()`** - decrement the reference counter on an account +- **`inc_providers()`** - increment the provider reference counter on an account +- **`dec_providers()`** - decrement the provider reference counter on an account +- **`inc_sufficients()`** - increment the self-sufficient reference counter on an account +- **`dec_sufficients()`** - decrement the sufficients reference counter on an account !!!note - All these methods are provided by the [`frame-system`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method){target=\_blank} pallet. + The [System pallet](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method){target=\_blank} provides all these methods. -For every increment of a counter during an account's lifecycle, a corresponding decrement should be called to ensure proper management of the account state. +For every counter increment during an account's lifecycle, a corresponding decrement should be called to ensure proper management of the account state. There are also three query functions to ease usage on these counters: -- [`can_inc_consumer()`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.can_inc_consumer){target=\_blank} to check if an account is ready to be used (`providers` > 0). -- [`can_dec_provider()`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.can_dec_provider){target=\_blank} to check if an account is no longer referenced in runtime whatsoever (`consumers` == 0) before decrementing providers to 0. -- [`is_provider_required()`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.is_provider_required){target=\_blank} to check if an account has outstanding consumer references (`consumers` > 0). +- [**`can_inc_consumer()`**](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.can_inc_consumer){target=\_blank} - to check if an account is ready to be used (`providers` greater than 0) +- [**`can_dec_provider()`**](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.can_dec_provider){target=\_blank} - to check if an account is no longer referenced in the runtime whatsoever (`consumers` equal 0) before decrementing `providers` to 0 +- [**`is_provider_required()`**](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.is_provider_required){target=\_blank} to check if an account has outstanding consumer references (`consumers` greater than 0) !!! note - See [frame-system API](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html){target=\_blank} for more details. + See the [System pallet API](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html){target=\_blank} for more details. -## AccountData Trait and Implementation +## Account Data Trait and Implementation -The [`AccountInfo`](https://paritytech.github.io/polkadot-sdk/master/frame_system/struct.AccountInfo.html){target=\_blank} can be any structure, provided it meets the requirements of the associated type `AccountData` trait bound defined in the [`frame-system::pallet::Config`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/trait.Config.html){target=\_blank} trait. +The [`AccountInfo`](https://paritytech.github.io/polkadot-sdk/master/frame_system/struct.AccountInfo.html){target=\_blank} structure can vary as long as it satisfies the trait bounds defined by the `AccountData` associated type in the [`frame-system::pallet::Config`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/trait.Config.html){target=\_blank} trait. -By default, the Substrate runtime configures `AccountInfo` as defined in the [`pallet-balances`](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/struct.AccountData.html){target=\_blank}. \ No newline at end of file +By default, the Substrate runtime configures the `AccountInfo` structure, as defined in the [Balances pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/struct.AccountData.html){target=\_blank}.