pezkuwichain/pezkuwi-runtime-templates
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-runtime-templates.git synced 2026-06-14 04:01:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

Complete terminology rebrand to Pezkuwi ecosystem

Browse Source 
Applied global changes: Polkadot->Pezkuwi, Parachain->TeyrChain, pallet->pezpallet, frame->pezframe.

Updated authors in Cargo.toml to include Kurdistan Tech Institute and pezkuwichain team.

Used Cargo aliases to maintain SDK compatibility while using rebranded names in source code.
This commit is contained in:
Kurdistan Tech Ministry
2025-12-22 09:03:43 +03:00
parent a52909422a
commit d839cbd92b
180 changed files with 3537 additions and 2889 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/modules/ROOT/pages/pezpallets/assets.adoc
+803
View File
@@ -0,0 +1,803 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= pezpallet_assets
Branch/Release: `release-polkadot-v1.10.0`
== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/substrate/pezframe/assets/src/lib.rs[{github-icon},role=heading-link]
== Purpose
The `pezpallet_assets` module is designed to manage and manipulate custom fungible asset types. It provides functionality for asset creation, management, and various operations, allowing for a flexible and scalable approach to asset handling.
== Pezpallet specific terms
** `Asset ID` - A unique identifier for an asset type.
** `Asset Owner` - The account that owns an asset.
** `Admin` - The account that has administrative privileges over an asset, such as: `minting`, `burning`, `freezing`, and `thawing`.
** `Sufficiency` - The amount of an asset that is required to be held in an account in order to perform certain operations, such as: `transfers`, `freezing`, and `thawing`.
== Config
* Pezpallet-specific configs
** `Balance` -- The balance unit type.
** `RemoveItemsLimit` -- The maximum number of items that can be removed in a single `destroy_accounts` and `destroy_approvals` call.
** `AssetId` -- The unique asset identifiers.
** `AssetIdParameter` -- The parameter type for asset identifiers.
** `Currency` -- The currency type.
** `CreateOrigin` -- The origin type that can create an asset.
** `ForceOrigin` -- The origin type that can force an asset action.
** `AssetDeposit` -- The deposit required for reservation to create an asset.
** `AssetAccountDeposit` -- The deposit required for a non-provider asset account for reservation to create an asset account.
** `MetadataDepositBase` -- The base deposit required to reserve metadata.
** `MetadataDepositPerByte` -- The deposit required to reserve metadata per byte.
** `ApprovalDeposit` -- The deposit required to reserve an approval.
** `StringLimit` -- The maximum length of a name or symbol.
** `Freezer` -- A hook to allow a per-asset, per-account minimum balance to be enforced.
** `Extra` -- The extra data to be stored with an account's asset balance.
** `CallbackHandle` -- An asset created or destroyed callback functions.
** `BenchmarkHelper` -- A helper type to benchmark the pezpallet's weight.
* Common configs
** `RuntimeEvent` -- The overarching event type.
** `WeightInfo` -- xref:glossary.adoc#weight[Weight] information for extrinsics in this pezpallet.
== Events
* `Created(asset_id, creator, owner)` -- An asset was created.
* `Issued(asset_id, owner, amount)` -- An asset was issued.
* `Transferred(asset_id, from, to, amount)` -- An asset was transferred.
* `Burned(asset_id, owner, balance)` -- An asset was burned.
* `TeamChanged(asset_id, issuer, admin, freezer)` -- The management team of an asset was changed.
* `OwnerChanged(asset_id, owner)` -- The owner of an asset was changed.
* `Frozen(asset_id, who)` -- An account `who` was frozen.
* `Thawed(asset_id, who)` -- An account `who` was thawed.
* `AssetFrozen(asset_id)` -- An asset was frozen.
* `AssetThawed(asset_id)` -- An asset was thawed.
* `AccountsDestroyed(asset_id, accounts_destroyed, accounts_remaining)` -- A number `accounts_destroyed` accounts were destroyed for an asset.
* `ApprovalsDestroyed(asset_id, approvals_destroyed, approvals_remaining)` -- A number `approvals_destroyed` approvals were destroyed for an asset.
* `DestructionStarted(asset_id)` -- The destruction of an asset class was started.
* `Destroyed(asset_id)` -- An asset class was destroyed.
* `ForceCreated(asset_id, owner)` -- An asset was force created.
* `MetadataSet(asset_id, name, symbol, decimals, is_frozen)` -- The metadata of an asset was set.
* `MetadataCleared(asset_id)` -- The metadata of an asset was cleared.
* `ApprovedTransfer(asset_id, source, delegate, amount)` -- An approval was made for a delegate to transfer a specific amount of an asset on behalf of the owner.
* `ApprovalCancelled(asset_id, owner, delegate)` -- An approval was cancelled for a delegate to transfer a specific amount of an asset on behalf of the owner.
* `TransferredApproved(asset_id, owner, delegate, destination, amount)` -- A delegate transferred a specific amount of an asset on behalf of the owner.
* `AssetStatusChanged(asset_id)` -- The attributes of an asset was forcely changed.
* `AssetMinBalanceChanged(asset_id, new_min_balance)` -- The minimum balance of an asset was changed by an owner.
* `Touched(asset_id, who, depositor)` -- An account `who` was created with a deposit from `depositor`.
* `Blocked(asset_id, who)` -- An account `who` was blocked.
== Errors
* `BalanceLow` -- Account balance must be greater than or equal to the transfer amount.
* `NoAccount` -- The account to alter does not exist.
* `NoPermission` -- The signing account has no permission to do the operation.
* `Unknown` -- The given asset ID is unknown.
* `Frozen` -- The origin account is frozen.
* `InUse` -- The asset ID is already taken.
* `BadWitness` -- Invalid witness data given.
* `MinBalanceZero` -- Minimum balance should be non-zero.
* `UnavailableConsumer` -- Unable to increment the consumer reference counters on the account. Either no provider reference exists to allow a non-zero balance of a non-self-sufficient asset, or one fewer then the maximum number of consumers has been reached.
* `BadMetadata` -- Invalid metadata given.
* `Unapproved` -- No approval exists that would allow the transfer.
* `WouldDie` -- The source account would not survive the transfer and it needs to stay alive.
* `AlreadyExists` -- The asset-account already exists.
* `NoDeposit` -- The asset-account doesn't have an associated deposit.
* `WouldBurn` -- The operation would result in funds being burned.
* `LiveAsset` -- The asset is a live asset and is actively being used. Usually emit for operations such as `start_destroy` which require the asset to be in a destroying state.
* `AssetNotLive` -- The asset is not live, and likely being destroyed.
* `IncorrectStatus` -- The asset status is not the expected status.
* `NotFrozen` -- The asset should be frozen before the given operation.
* `CallbackFailed` -- Callback action resulted in error.
== Dispatchables
[.contract-item]
[[create]]
==== `[.contract-item-name]#++create++#`
[source,rust]
----
pub fn create(
origin: OriginFor<T>,
id: T::AssetIdParameter,
admin: AccountIdLookupOf<T>,
min_balance: T::Balance,
) -> DispatchResult
----
Issues a new class of fungible assets from a public origin. If an asset was not created, raises `CallbackFailed`.
NOTE: The origin must conform to the configured `CreateOrigin` and have sufficient funds free.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, sender) account.
* `id: T::AssetIdParameter` -- the identifier of the asset to be created.
* `admin: AccountIdLookupOf<T>` -- the admin of this asset, who can execute all privileged functions.
* `min_balance: T::Balance` -- the minimum balance of this new asset that any single account must have.
[.contract-item]
[[force_create]]
==== `[.contract-item-name]#++force_create++#`
[source,rust]
----
pub fn force_create(
origin: OriginFor<T>,
id: T::AssetIdParameter,
owner: AccountIdLookupOf<T>,
is_sufficient: bool,
#[pezpallet::compact] min_balance: T::Balance,
) -> DispatchResult
----
Issues a new class of fungible assets from a privileged origin.
NOTE: The origin must conform to `ForceOrigin`. Unlike `create`, no funds are reserved.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, sender) account.
* `id: T::AssetIdParameter` -- the unique identifier of the asset to be created.
* `owner: AccountIdLookupOf<T>` -- the owner of this asset, who can mint/burn tokens.
* `is_sufficient: bool` -- whether the owner account should be checked for minimum balance.
[.contract-item]
[[start_destroy]]
==== `[.contract-item-name]#++start_destroy++#`
[source,rust]
----
pub fn start_destroy(
origin: OriginFor<T>,
id: T::AssetIdParameter
) -> DispatchResult
----
Start the process of destroying a fungible asset class.
NOTE: `start_destroy` is the first in a series of extrinsics that should be called, to allow destruction of an asset class. The origin must conform to `ForceOrigin` or must be `Signed` by the asset's `owner`. The asset class must be frozen before calling `start_destroy`.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, sender) account.
* `id: T::AssetIdParameter` -- the identifier of the existing asset to be destroyed.
[.contract-item]
[[destroy_accounts]]
==== `[.contract-item-name]#++destroy_accounts++#`
[source,rust]
----
pub fn destroy_accounts(
origin: OriginFor<T>,
id: T::AssetIdParameter,
) -> DispatchResultWithPostInfo
----
Destroys accounts associated with a given asset.
NOTE: `destroy_accounts` is the second in a series of extrinsics that should only be called after `start_destroy`, to allow destruction of an asset class. The origin must conform to `ForceOrigin` or must be `Signed` by the asset's `owner`. It will call `T::RemoveItemsLimit::get()` so if the number of accounts exceeds this limit, this function need to be called several times.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, sender) account.
* `id: T::AssetIdParameter` -- the identifier of the existing asset to be destroyed.
[.contract-item]
[[destroy_approvals]]
==== `[.contract-item-name]#++destroy_approvals++#`
[source,rust]
----
pub fn destroy_approvals(
origin: OriginFor<T>,
id: T::AssetIdParameter,
) -> DispatchResult
----
Clears approvals associated with a given asset.
NOTE: It should be called after `start_destroy`. It will call `T::RemoveItemsLimit::get()` so if the number of approvals exceeds this limit, this function need to be called several times.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, root) account.
* `id: T::AssetIdParameter` -- the identifier of the asset for which all approvals will be destroyed.
[.contract-item]
[[finish_destroy]]
==== `[.contract-item-name]#++finish_destroy++#`
[source,rust]
----
pub fn finish_destroy(
origin: OriginFor<T>,
id: T::AssetIdParameter
) -> DispatchResult
----
Completes the process of asset destruction initiated by `start_destroy`.
NOTE: This function is the final step in the asset destruction process. It should only be called after all checks and balances have been done, typically after `start_destroy` and `destroy_accounts` are successfully called. The origin must conform to `ForceOrigin` or be `Signed` by the asset's owner, ensuring that this sensitive action is adequately authorized.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, root) account.
* `id: T::AssetIdParameter` -- the identifier of the asset to be destroyed.
[.contract-item]
[[mint]]
==== `[.contract-item-name]#++mint++#`
[source,rust]
----
pub fn mint(
origin: OriginFor<T>,
id: T::AssetIdParameter,
beneficiary: AccountIdLookupOf<T>,
#[pezpallet::compact] amount: T::Balance,
) -> DispatchResult
----
Mints new units of a specific asset and assigns them to a beneficiary account.
NOTE: The `mint` function allows authorized accounts to increase the supply of an asset. The origin must be authorized to mint assets, typically configured via `MintOrigin`. The `#[pezpallet::compact]` attribute is used to optimize the storage of the `amount` parameter. This function ensures that the total supply doesn't overflow and that the beneficiary is capable of holding the asset.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which units are to be minted.
* `beneficiary: AccountIdLookupOf<T>` -- the account that will receive the newly minted units.
* `amount: T::Balance` -- the amount of new units to be minted and credited to the beneficiary.
[.contract-item]
[[burn]]
==== `[.contract-item-name]#++burn++#`
[source,rust]
----
pub fn burn(
origin: OriginFor<T>,
id: T::AssetIdParameter,
who: AccountIdLookupOf<T>,
#[pezpallet::compact] amount: T::Balance,
) -> DispatchResult
----
Destroys units of a specific asset from the specified account.
NOTE: The `burn` function decreases the supply of an asset by removing a specified amount from a particular account. The origin must be authorized to burn assets, typically configured via `BurnOrigin`. The `#[pezpallet::compact]` attribute optimizes the storage of the `amount` parameter. This function is used for asset management, such as reducing supply or removing assets from circulation for regulatory compliance.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset from which units are to be burned.
* `who: AccountIdLookupOf<T>` -- the account from which the units will be destroyed.
* `amount: T::Balance` -- the amount of units to be burned from the specified account.
[.contract-item]
[[transfer]]
==== `[.contract-item-name]#++transfer++#`
[source,rust]
----
pub fn transfer(
origin: OriginFor<T>,
id: T::AssetIdParameter,
target: AccountIdLookupOf<T>,
#[pezpallet::compact] amount: T::Balance,
) -> DispatchResult
----
Transfers a specified amount of a specific asset to a target account.
NOTE: The `transfer` function allows assets to be moved between accounts. The origin must be signed by the account wishing to transfer assets and must have sufficient balance. The `#[pezpallet::compact]` attribute is used for efficient storage of the `amount` parameter. This function checks for liquidity, asset validity, and the receiving account's ability to accept the asset, ensuring secure and accurate transactions.
**Params:**
* `origin: OriginFor<T>` -- the caller account initiating the transfer.
* `id: T::AssetIdParameter` -- the identifier of the asset to be transferred.
* `target: AccountIdLookupOf<T>` -- the recipient account of the asset units.
* `amount: T::Balance` -- the amount of units to transfer from the caller to the target account. The amount actually transferred may be slightly greater in the case that the transfer would otherwise take the sender balance above zero but below the minimum balance. Must be greater than zero.
[.contract-item]
[[transfer_keep_alive]]
==== `[.contract-item-name]#++transfer_keep_alive++#`
[source,rust]
----
pub fn transfer_keep_alive(
origin: OriginFor<T>,
id: T::AssetIdParameter,
target: AccountIdLookupOf<T>,
#[pezpallet::compact] amount: T::Balance,
) -> DispatchResult
----
Transfers a specified amount of a specific asset to a target account, ensuring that the transfer does not result in the sender's total demise.
NOTE: The `transfer_keep_alive` function is similar to `transfer` but includes an additional check that prevents the transfer if it would cause the origin account to be reaped. This is critical for ensuring the account's continued existence, particularly for accounts with minimum balance requirements. The `#[pezpallet::compact]` attribute is used for efficient storage of the `amount` parameter. Like `transfer`, it ensures secure and precise asset movement between accounts.
**Params:**
* `origin: OriginFor<T>` -- the caller account initiating the transfer.
* `id: T::AssetIdParameter` -- the identifier of the asset to be transferred.
* `target: AccountIdLookupOf<T>` -- the recipient account of the asset units.
* `amount: T::Balance` -- the amount of units to transfer from the caller to the target account, while ensuring the sender's account remains active. The amount actually transferred may be slightly greater in the case that the transfer would otherwise take the sender balance above zero but below the minimum balance. Must be greater than zero.
[.contract-item]
[[force_transfer]]
==== `[.contract-item-name]#++force_transfer++#`
[source,rust]
----
pub fn force_transfer(
origin: OriginFor<T>,
id: T::AssetIdParameter,
source: AccountIdLookupOf<T>,
dest: AccountIdLookupOf<T>,
#[pezpallet::compact] amount: T::Balance,
) -> DispatchResult
----
Forces the transfer of a specified amount of a specific asset from a source account to a destination account.
NOTE: The `force_transfer` function is an administrative tool that allows a privileged origin, typically configured via `ForceOrigin`, to move assets between accounts without consent from the source. This might be used in exceptional scenarios, such as legal or administrative resolutions. The `#[pezpallet::compact]` attribute optimizes storage of the `amount` parameter. This function must be used with caution due to its power and potential impact on account balances.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset to be forcibly transferred.
* `source: AccountIdLookupOf<T>` -- the account from which the asset units will be debited.
* `dest: AccountIdLookupOf<T>` -- the account to which the asset units will be credited.
* `amount: T::Balance` -- the amount of units to forcibly transfer from the source to the destination account. The amount actually transferred may be slightly greater in the case that the transfer would otherwise take the sender balance above zero but below the minimum balance. Must be greater than zero.
[.contract-item]
[[freeze]]
==== `[.contract-item-name]#++freeze++#`
[source,rust]
----
pub fn freeze(
origin: OriginFor<T>,
id: T::AssetIdParameter,
who: AccountIdLookupOf<T>,
) -> DispatchResult
----
Freezes the specified asset in a particular account, preventing further unprivileged transfers of the asset from the frozen account.
NOTE: The `freeze` function is used to halt all operations for a specified asset in a given account, typically for regulatory or compliance reasons. This action can only be performed by an authorized origin, usually the asset's admin or another account with special privileges. Once an account is frozen, it cannot transact the specified asset until an `thaw` operation is performed.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset to be frozen.
* `who: AccountIdLookupOf<T>` -- the account in which the asset will be frozen. Must already exist as an entry in `Account`s of the asset.
[.contract-item]
[[thaw]]
==== `[.contract-item-name]#++thaw++#`
[source,rust]
----
pub fn thaw(
origin: OriginFor<T>,
id: T::AssetIdParameter,
who: AccountIdLookupOf<T>,
) -> DispatchResult
----
Unfreezes the specified asset in a particular account, allowing the resumption of unprivileged transfers of the asset.
NOTE: The `thaw` function reverses the effect of `freeze`, re-enabling the account to transact with the specified asset. This action is typically restricted to authorized origins, such as the asset's admin or other accounts with special privileges. It is used in scenarios where the conditions that led to the initial freezing have been resolved or are no longer applicable.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset to be thawed.
* `who: AccountIdLookupOf<T>` -- the account in which the asset will be thawed.
[.contract-item]
[[freeze_asset]]
==== `[.contract-item-name]#++freeze_asset++#`
[source,rust]
----
pub fn freeze_asset(
origin: OriginFor<T>,
id: T::AssetIdParameter
) -> DispatchResult
----
Freezes all operations for a specified asset across all accounts, halting any transfer, minting, or other asset-related activities.
NOTE: The `freeze_asset` function is a comprehensive freeze operation affecting all accounts holding the specified asset. It is intended for emergency or regulatory situations requiring immediate suspension of all activities related to the asset. This action typically requires authorization from a privileged origin, which might be the asset's admin or a specific governance mechanism in place. The freeze remains in effect until an `thaw_asset` operation is performed.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset to be frozen.
[.contract-item]
[[thaw_asset]]
==== `[.contract-item-name]#++thaw_asset++#`
[source,rust]
----
pub fn thaw_asset(
origin: OriginFor<T>,
id: T::AssetIdParameter
) -> DispatchResult
----
Unfreezes all operations for a specified asset across all accounts, allowing resumption of transfers, minting, and other asset-related activities.
NOTE: The `thaw_asset` function reverses the comprehensive freeze applied by `freeze_asset`, re-enabling the normal operation of all activities related to the asset across all accounts. It is typically used once the conditions necessitating the freeze are no longer applicable or have been resolved. This action usually requires authorization from a privileged origin, such as the asset's admin or a specific governance mechanism.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset to be thawed.
[.contract-item]
[[transfer_ownership]]
==== `[.contract-item-name]#++transfer_ownership++#`
[source,rust]
----
pub fn transfer_ownership(
origin: OriginFor<T>,
id: T::AssetIdParameter,
owner: AccountIdLookupOf<T>,
) -> DispatchResult
----
Transfers the ownership of a specific asset to another account.
NOTE: The `transfer_ownership` function is used to change the admin or owner of an asset to a new account. This operation might be necessary for administrative restructuring, transferring responsibilities, or ownership succession scenarios. The origin must be the current owner or authorized to transfer ownership, ensuring proper authorization and security in the ownership transfer process.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which ownership is being transferred.
* `owner: AccountIdLookupOf<T>` -- the account that will become the new owner of the asset.
[.contract-item]
[[set_team]]
==== `[.contract-item-name]#++set_team++#`
[source,rust]
----
pub fn set_team(
origin: OriginFor<T>,
id: T::AssetIdParameter,
issuer: AccountIdLookupOf<T>,
admin: AccountIdLookupOf<T>,
freezer: AccountIdLookupOf<T>,
) -> DispatchResult
----
Sets the team managing a specific asset, defining roles for issuance, administration, and freezing operations.
NOTE: The `set_team` function is used to designate specific accounts for managing various aspects of an asset. This includes issuing new units of the asset, administering ownership or other significant changes, and freezing or thawing operations. The origin must be the current owner or another authorized account to ensure proper governance and control over the asset. This function allows for flexible and secure management of assets by clearly separating responsibilities among different roles.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which the team is being set.
* `issuer: AccountIdLookupOf<T>` -- the account designated for issuing new units of the asset.
* `admin: AccountIdLookupOf<T>` -- the account designated for administrative tasks.
* `freezer: AccountIdLookupOf<T>` -- the account designated for freezing and thawing the asset.
[.contract-item]
[[set_metadata]]
==== `[.contract-item-name]#++set_metadata++#`
[source,rust]
----
pub fn set_metadata(
origin: OriginFor<T>,
id: T::AssetIdParameter,
name: Vec<u8>,
symbol: Vec<u8>,
decimals: u8,
) -> DispatchResult
----
Sets or updates the metadata for a specific asset, including its name, symbol, and decimals.
NOTE: The `set_metadata` function is used to define or update the descriptive attributes of an asset. These attributes include the asset's name, a short symbol, and the number of decimals that represent the asset's smallest unit. This information is crucial for user interfaces and third-party integrations to properly display and understand the asset's properties. The origin must have the appropriate permissions to modify an asset's metadata, ensuring that only authorized users can make changes. Funds of sender are reserved according to the formula: `MetadataDepositBase + MetadataDepositPerByte * (name.len + symbol.len)` taking into account any already reserved funds.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which metadata is being set.
* `name: Vec<u8>` -- the new name of the asset as a byte array.
* `symbol: Vec<u8>` -- the new symbol of the asset as a byte array.
* `decimals: u8` -- the number of decimals places used to represent the asset.
[.contract-item]
[[clear_metadata]]
==== `[.contract-item-name]#++clear_metadata++#`
[source,rust]
----
pub fn clear_metadata(
origin: OriginFor<T>,
id: T::AssetIdParameter
) -> DispatchResult
----
Clears the metadata of a specific asset, removing its name, symbol, and decimals information.
NOTE: The `clear_metadata` function is used to remove all descriptive information associated with an asset. This may be necessary in situations where the asset's properties have changed significantly, or the asset is being deprecated. Clearing metadata is an important aspect of asset management and requires proper authorization to ensure that only valid users can perform this action. Once cleared, the asset will no longer have descriptive labels or detailed display information until new metadata is set.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which metadata is being cleared.
[.contract-item]
[[force_set_metadata]]
==== `[.contract-item-name]#++force_set_metadata++#`
[source,rust]
----
pub fn force_set_metadata(
origin: OriginFor<T>,
id: T::AssetIdParameter,
name: Vec<u8>,
symbol: Vec<u8>,
decimals: u8,
is_frozen: bool,
) -> DispatchResult
----
Forcibly sets or updates the metadata for a specific asset, including its name, symbol, decimals, and frozen status, regardless of the current owner's permissions.
NOTE: The `force_set_metadata` function is an administrative tool that allows privileged accounts to set or update the metadata of an asset. This includes force-changing the name, symbol, decimals, and freeze status. It is used in scenarios requiring higher-level intervention, such as regulatory compliance or significant asset restructuring. The origin must be authorized to perform forceful administrative actions, ensuring that only valid scenarios permit such drastic changes.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which metadata is being forcibly set.
* `name: Vec<u8>` -- the new name of the asset as a byte array.
* `symbol: Vec<u8>` -- the new symbol of the asset as a byte array.
* `decimals: u8` -- the number of decimal places used to represent the asset.
* `is_frozen: bool` -- the new frozen status of the asset, determining if it can be transacted.
[.contract-item]
[[force_clear_metadata]]
==== `[.contract-item-name]#++force_clear_metadata++#`
[source,rust]
----
pub fn force_clear_metadata(
origin: OriginFor<T>,
id: T::AssetIdParameter
) -> DispatchResult
----
Forcibly clears all metadata of a specific asset, including its name, symbol, and decimals, by an administrative order.
NOTE: The `force_clear_metadata` function is an administrative action used in circumstances that require overriding the usual asset management, such as regulatory compliance or significant changes to the asset's structure or purpose. This function removes all descriptive information, essentially resetting the asset's public-facing details. The origin must be a privileged account authorized to perform such forceful actions, ensuring that the clearance is done under proper oversight and for valid reasons.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which metadata is being forcibly cleared.
[.contract-item]
[[force_asset_status]]
==== `[.contract-item-name]#++force_asset_status++#`
[source,rust]
----
pub fn force_asset_status(
origin: OriginFor<T>,
id: T::AssetIdParameter,
owner: AccountIdLookupOf<T>,
issuer: AccountIdLookupOf<T>,
admin: AccountIdLookupOf<T>,
freezer: AccountIdLookupOf<T>,
#[pezpallet::compact] min_balance: T::Balance,
is_sufficient: bool,
is_frozen: bool,
) -> DispatchResult
----
Forcibly changes the status of a specific asset, including ownership, management team, minimum balance, sufficiency status, and frozen status.
NOTE: The `force_asset_status` function is a powerful administrative tool used to configure or reconfigure critical aspects of an asset's behavior and control. It is typically used in scenarios requiring immediate intervention or significant restructuring. The function allows changing the owner, issuer, admin, and freezer accounts, setting the minimum balance required for the asset, and determining whether the asset should be considered sufficient for existential deposit purposes or frozen entirely. Due to its significant impact, this function is restricted to privileged origins authorized for such impactful changes.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset being modified.
* `owner: AccountIdLookupOf<T>` -- the account designated as the new owner of the asset.
* `issuer: AccountIdLookupOf<T>` -- the account designated for issuing new units of the asset.
* `admin: AccountIdLookupOf<T>` -- the account designated for administrative tasks.
* `freezer: AccountIdLookupOf<T>` -- the account designated for freezing and thawing the asset.
* `min_balance: T::Balance` -- the new minimum balance required for the asset.
* `is_sufficient: bool` -- indicates if the asset should be considered sufficient for existential deposit purposes.
* `is_frozen: bool` -- indicates if the asset is to be frozen across all accounts.
[.contract-item]
[[approve_transfer]]
==== `[.contract-item-name]#++approve_transfer++#`
[source,rust]
----
pub fn approve_transfer(
origin: OriginFor<T>,
id: T::AssetIdParameter,
delegate: AccountIdLookupOf<T>,
#[pezpallet::compact] amount: T::Balance,
) -> DispatchResult
----
Approves a delegate to transfer a specified amount of a specific asset on behalf of the origin account.
NOTE: The `approve_transfer` function allows the origin account to delegate transfer rights for a portion of their assets to another account, known as the delegate. This is useful in scenarios where temporary or limited rights to transfer assets are needed without transferring full ownership. The approval specifies an exact amount of the asset that the delegate is allowed to transfer. The `#[pezpallet::compact]` attribute is used for efficient storage of the `amount` parameter. This function is often used in decentralized applications to enable features like spending allowances and automated payments.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which transfer rights are being granted.
* `delegate: AccountIdLookupOf<T>` -- the account being granted the rights to transfer the specified amount of the asset.
* `amount: T::Balance` -- the amount of the asset that the delegate is approved to transfer.
[.contract-item]
[[cancel_approval]]
==== `[.contract-item-name]#++cancel_approval++#`
[source,rust]
----
pub fn cancel_approval(
origin: OriginFor<T>,
id: T::AssetIdParameter,
delegate: AccountIdLookupOf<T>,
) -> DispatchResult
----
Cancels a previously granted approval for a delegate to transfer a specified asset on behalf of the origin account.
NOTE: The `cancel_approval` function revokes the rights previously granted to a delegate to transfer a portion of the origin's assets. This might be used when the need for the delegate's rights has expired or if the original approval was made in error. The action ensures that the delegate can no longer transfer any amount of the specified asset from the origin's account. This function is important for maintaining control and security over asset delegation and is a common feature in permission and rights management within asset systems.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which transfer rights are being revoked.
* `delegate: AccountIdLookupOf<T>` -- the account from which the rights to transfer the asset are being revoked.
[.contract-item]
[[force_cancel_approval]]
==== `[.contract-item-name]#++force_cancel_approval++#`
[source,rust]
----
pub fn force_cancel_approval(
origin: OriginFor<T>,
id: T::AssetIdParameter,
owner: AccountIdLookupOf<T>,
delegate: AccountIdLookupOf<T>,
) -> DispatchResult
----
Forcibly cancels a previously granted approval for a delegate to transfer a specific asset on behalf of the owner account.
NOTE: The `force_cancel_approval` function is an administrative action used to revoke transfer rights from a delegate, typically in situations of emergency or misuse. Unlike `cancel_approval`, this function can be initiated by an admin or authority other than the asset's owner, reflecting its more forceful nature. It's critical for situations where the asset owner cannot revoke the approval themselves or in governance scenarios where broader control is necessary. As with all forceful actions, the origin must have the necessary administrative privileges.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root. Origin must be either ForceOrigin or Signed origin with the signer being the Admin account of the asset `id`.
* `id: T::AssetIdParameter` -- the identifier of the asset for which the approval is being forcibly canceled.
* `owner: AccountIdLookupOf<T>` -- the account that owns the asset and had previously granted transfer rights.
* `delegate: AccountIdLookupOf<T>` -- the account from which the rights to transfer the asset are being forcibly revoked.
[.contract-item]
[[transfer_approved]]
==== `[.contract-item-name]#++transfer_approved++#`
[source,rust]
----
pub fn transfer_approved(
origin: OriginFor<T>,
id: T::AssetIdParameter,
owner: AccountIdLookupOf<T>,
destination: AccountIdLookupOf<T>,
#[pezpallet::compact] amount: T::Balance,
) -> DispatchResult
----
Executes a transfer of a specified amount of an asset from an owner to a destination account, using a previously granted approval.
NOTE: The `transfer_approved` function allows a delegate (the origin) to transfer assets within the limits of an approval granted by the asset's owner. This enables scenarios where third parties are given limited rights to manage assets. The function ensures that the delegate cannot exceed the approved amount or perform transfers without a valid approval. The `#[pezpallet::compact]` attribute is used for efficient storage of the `amount` parameter. It's a critical function for flexible asset management in decentralized systems and applications.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset being transferred.
* `owner: AccountIdLookupOf<T>` -- the account that owns the asset and had previously granted transfer rights.
* `destination: AccountIdLookupOf<T>` -- the account receiving the asset.
* `amount: T::Balance` -- the amount of the asset to be transferred, which must be within the approved amount.
[.contract-item]
[[touch]]
==== `[.contract-item-name]#++touch++#`
[source,rust]
----
pub fn touch(
origin: OriginFor<T>,
id: T::AssetIdParameter
) -> DispatchResult
----
Creates an asset account for non-provider assets.
NOTE: A deposit will be taken from the signer account.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset being updated.
[.contract-item]
[[refund]]
==== `[.contract-item-name]#++refund++#`
[source,rust]
----
pub fn refund(
origin: OriginFor<T>,
id: T::AssetIdParameter,
allow_burn: bool,
) -> DispatchResult
----
Refunds any reserved balance of a specific asset back to the asset's owner or burns it based on the provided parameter.
NOTE: The `refund` function is designed to handle situations where an asset's reserved balance needs to be reconciled. This might occur in scenarios such as the completion of a contract, dissolution of a stake, or other instances where reserved funds are to be released. The `allow_burn` parameter determines if the refunded amount should be returned to the asset's owner or burned, removing it from circulation. This function requires careful use and is typically controlled by the asset's owner or an administrative authority.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which the reserved balance is being refunded.
* `allow_burn: bool` -- indicates whether the reserved balance should be returned to the owner (false) or burned (true).
[.contract-item]
[[set_min_balance]]
==== `[.contract-item-name]#++set_min_balance++#`
[source,rust]
----
pub fn set_min_balance(
origin: OriginFor<T>,
id: T::AssetIdParameter,
min_balance: T::Balance,
) -> DispatchResult
----
Sets a new minimum balance for a specific asset.
NOTE: The `set_min_balance` function is used to define or update the minimum balance required to hold a particular asset. This is crucial for preventing dust accounts and ensuring economic viability of the asset system. Changing the minimum balance affects all holders of the asset, as accounts below the new minimum might be cleaned up or require additional funding. This operation requires authorization from the asset's owner or another privileged account, ensuring that the change is made with proper oversight and consideration of its effects. Only works if there aren't any accounts that are holding the asset or if the new value of `min_balance` is less than the old one.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which the minimum balance is being set.
* `min_balance: T::Balance` -- the new minimum balance required to hold the asset.
[.contract-item]
[[touch_other]]
==== `[.contract-item-name]#++touch_other++#`
[source,rust]
----
pub fn touch_other(
origin: OriginFor<T>,
id: T::AssetIdParameter,
who: AccountIdLookupOf<T>,
) -> DispatchResult
----
Create an asset account for `who`.
NOTE: A deposit will be taken from the signer account.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset being updated.
* `who: AccountIdLookupOf<T>` -- the account for which the asset's timestamp is being updated.
[.contract-item]
[[refund_other]]
==== `[.contract-item-name]#++refund_other++#`
[source,rust]
----
pub fn refund_other(
origin: OriginFor<T>,
id: T::AssetIdParameter,
who: AccountIdLookupOf<T>,
) -> DispatchResult
----
Refunds the reserved balance of a specific asset back to another account's owner.
NOTE: The `refund_other` function is similar to the `refund` function but targets another account rather than the caller's own. This allows administrators or authorized personnel to manage reserved balances across different accounts, potentially as part of a broader asset management or reconciliation process. This action might be necessary in scenarios such as contract completion, resolving disputes, or other instances where reserved funds need to be released or reallocated. The origin must have the necessary permissions to ensure that this function is used appropriately and by authorized entities. Useful if you are the depositor.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which the reserved balance is being refunded.
* `who: AccountIdLookupOf<T>` -- the account from which the reserved balance will be refunded.
[.contract-item]
[[block]]
==== `[.contract-item-name]#++block++#`
[source,rust]
----
pub fn block(
origin: OriginFor<T>,
id: T::AssetIdParameter,
who: AccountIdLookupOf<T>,
) -> DispatchResult
----
Blocks a specific account from unprivileged transacting a specific asset.
NOTE: The `block` function is used to restrict a particular account from performing unprivileged transactions involving a specified asset. This might be used in scenarios such as suspected fraud, regulatory compliance, or other security or administrative reasons. Once an account is blocked, it cannot transfer, mint, or burn the asset until it is unblocked. The origin must have the necessary administrative rights or privileges to enforce such restrictions, ensuring that the action is authorized and appropriate for the given context.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `id: T::AssetIdParameter` -- the identifier of the asset for which transactions are being blocked.
* `who: AccountIdLookupOf<T>` -- the account that is being blocked from transacting the asset.
docs/modules/ROOT/pages/pezpallets/aura_ext.adoc
+47
View File
@@ -0,0 +1,47 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= cumulus_pezpallet_aura_ext
Branch/Release: `release-polkadot-v1.10.0`
== Purpose
This pezpallet integrates parachain’s own block production mechanism (for example AuRa) into Cumulus parachain system. It allows:
- to manage the unincluded blocks from the current slot
- to validate produced block against the relay chain
== Configuration and Integration link:https://github.com/paritytech/polkadot-sdk/tree/release-polkadot-v1.10.0/cumulus/pezpallets/aura-ext[{github-icon},role=heading-link]
There is no special config for this integration and it has no dispatchables, but you need to integrate it with other `parachain-system` crate:
=== Integrate `BlockExecutor`
When you invoke the `register_validate_block` macro, you should provide `cumulus_pezpallet_aura_ext::BlockExecutor` to it to allow `aura-ext` to validate the blocks produced by `aura`
[source, rust]
----
cumulus_pezpallet_parachain_system::register_validate_block! {
Runtime = Runtime,
BlockExecutor = cumulus_pezpallet_aura_ext::BlockExecutor::<Runtime, Executive>,
}
----
=== Integrate `ConsensusHook`
Also you might want to manage the consensus externally and control the segment that is not yet included (its capacity, speed and etc.) `aura-ext` provides the `FixedVelocityConsensusHook` that allows to check if we are still in the limits for the slot.
[source, rust]
----
impl cumulus_pezpallet_parachain_system::Config for Runtime {
...
type ConsensusHook = cumulus_pezpallet_aura_ext::FixedVelocityConsensusHook<
Runtime,
RELAY_CHAIN_SLOT_DURATION_MILLIS,
BLOCK_PROCESSING_VELOCITY,
UNINCLUDED_SEGMENT_CAPACITY,
>;
}
----
docs/modules/ROOT/pages/pezpallets/balances.adoc
+247
View File
@@ -0,0 +1,247 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= pezpallet_balances
Branch/Release: `release-polkadot-v1.10.0`
== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/substrate/pezframe/balances/src/lib.rs[{github-icon},role=heading-link]
== Purpose
The Balances pezpallet provides functions for:
* Getting and setting free balances.
* Retrieving total, reserved, and unreserved balances.
* Repatriating a reserved balance to a beneficiary account that exists.
* Transferring a balance between accounts (when not reserved).
* Slashing an account balance.
* Account creation and removal.
* Managing total issuance.
* Setting and managing xref:glossary.adoc#lock[locks].
== Config
* Pezpallet-specific configs
** `RuntimeHoldReason` -- The overarching xref:glossary.adoc#hold[hold] reason.
** `RuntimeFreezeReason` -- The overarching xref:glossary.adoc#freeze[freeze] reason.
** `Balance` -- The balance of an account
** `DustRemoval` -- Handler for the unbalanced reduction when removing a dust account.
** `ExistentialDeposit` -- The minimum amount required to keep an account open. MUST BE GREATER THAN ZERO!
** `AccountStore` -- The means of storing the balances of an account.
** `ReserveIdentifier` -- The ID type for xref:glossary.adoc#reserve[reserves]. The use of reserves is deprecated in favor of holds. See `https://github.com/paritytech/substrate/pull/12951/`
** `FreezeIdentifier` -- The ID type for freezes.
** `MaxLocks` -- The maximum number of locks that should exist on an account.
** `MaxReserves` -- The maximum number of named reserves that can exist on an account. The use of reserves is deprecated in favor of holds. See `https://github.com/paritytech/substrate/pull/12951/`
** `MaxFreezes` -- The maximum number of individual freeze locks that can exist on an account at any time.
* Common configs
** `RuntimeEvent` -- The overarching event type.
** `WeightInfo` -- xref:glossary.adoc#weight[Weight] information for extrinsics in this pezpallet.
== Events
* `Endowed(account, free_balance)` -- An account was created with some free balance.
* `DustLost(account, amount)` -- An account was removed whose balance was non-zero but below ExistentialDeposit, resulting in an outright loss.
* `Transfer(from, to, amount)` -- Transfer succeeded.
* `BalanceSet(who, free)` -- A balance was set by root.
* `Reserved(who, amount)` -- Some balance was reserved (moved from free to reserved).
* `Unreserved(who, amount)` -- Some balance was unreserved (moved from reserved to free).
* `ReserveRepatriated(from, to, amount, destination_status)` -- Some balance was moved from the reserve of the first account to the second account. The final argument indicates the destination balance type.
* `Deposit(who, amount)` -- Some amount was deposited (e.g. for transaction fees).
* `Withdraw(who, amount)` -- Some amount was withdrawn from the account (e.g. for transaction fees).
* `Slashed(who, amount)` -- Some amount was removed from the account (e.g. for misbehavior).
* `Minted(who, amount)` -- Some amount was minted into an account.
* `Burned(who, amount)` -- Some amount was burned from an account.
* `Suspended(who, amount)` -- Some amount was suspended from an account (it can be restored later).
* `Restored(who, amount)` -- Some amount was restored into an account.
* `Upgraded(who)` -- An account was upgraded.
* `Issued(amount)` -- Total issuance was increased by `amount`, creating a credit to be balanced.
* `Rescinded(amount)` -- Total issuance was decreased by `amount`, creating a debt to be balanced.
* `Locked(who, amount)` -- Some balance was locked.
* `Unlocked(who, amount)` -- Some balance was unlocked.
* `Frozen(who, amount)` -- Some balance was frozen.
* `Thawed(who, amount)` -- Some balance was thawed.
* `TotalIssuanceForced(old, new)` -- Total issuance was forcefully changed.
== Errors
* `VestingBalance` -- Vesting balance too high to send value.
* `LiquidityRestrictions` -- Account liquidity restrictions prevent withdrawal.
* `InsufficientBalance` -- Balance too low to send value.
* `ExistentialDeposit` -- Value too low to create an account due to existential deposit.
* `Expendability` -- Transfer/payment would kill the account.
* `ExistingVestingSchedule` -- A vesting schedule already exists for this account.
* `DeadAccount` -- Beneficiary account must pre-exist.
* `TooManyReserves` -- Number of named reserves exceed `MaxReserves`.
* `TooManyHolds` -- Number of holds exceeds `MaxHolds`.
* `TooManyFreezes` -- Number of freezes exceeds `MaxFreezes`.
* `IssuanceDeactivated` -- The issuance cannot be modified since it is already deactivated.
* `DeltaZero` -- The delta cannot be zero.
== Dispatchables
[.contract-item]
[[transfer_allow_death]]
==== `[.contract-item-name]#++transfer_allow_death++#`
[source,rust]
----
pub fn transfer_allow_death(
origin: OriginFor<T>,
dest: AccountIdLookupOf<T>,
#[pezpallet::compact] value: T::Balance,
) -> DispatchResult
----
Transfers the `value` from `origin` to `dest`.
NOTE: `allow_death` means, that if the account balance drops below the ExistentialDeposit limit, it might be reaped/deleted.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, sender) account.
* `dest: AccountIdLookupOf<T>` -- recipient.
* `value: T::Balance` -- amount to transfer.
[.contract-item]
[[transfer_keep_alive]]
==== `[.contract-item-name]#++transfer_keep_alive++#`
[source,rust]
----
pub fn transfer_keep_alive(
origin: OriginFor<T>,
dest: AccountIdLookupOf<T>,
#[pezpallet::compact] value: T::Balance,
) -> DispatchResult
----
Transfers the `value` from `origin` to `dest`.
NOTE: `keep_alive` means, with a check that the transfer will not kill the origin account.
TIP: 99% of the time you want `transfer_allow_death` instead.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, sender) account.
* `dest: AccountIdLookupOf<T>` -- recipient.
* `value: T::Balance` -- amount to transfer.
[.contract-item]
[[force_transfer]]
==== `[.contract-item-name]#++force_transfer++#`
[source,rust]
----
pub fn force_transfer(
origin: OriginFor<T>,
source: AccountIdLookupOf<T>,
dest: AccountIdLookupOf<T>,
#[pezpallet::compact] value: T::Balance,
) -> DispatchResult
----
Exactly as `transfer_allow_death`, except the origin must be root and the source account may be specified.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, root) account.
* `source: AccountIdLookupOf<T>` -- sender (forced by root).
* `dest: AccountIdLookupOf<T>` -- recipient.
* `value: T::Balance` -- amount to transfer.
[.contract-item]
[[transfer_all]]
==== `[.contract-item-name]#++transfer_all++#`
[source,rust]
----
pub fn transfer_all(
origin: OriginFor<T>,
dest: AccountIdLookupOf<T>,
keep_alive: bool,
) -> DispatchResult
----
Transfer the entire transferable balance from the caller account.
NOTE: This function only attempts to transfer _transferable_ balances. This means that any locked, reserved, or existential deposits (when `keep_alive` is `true`), will not be transferred by this function.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, sender) account.
* `dest: AccountIdLookupOf<T>` -- recipient.
* `keep_alive: bool` -- A boolean to determine if the `transfer_all` operation should send all of the transferable funds (including existential deposits) the account has, causing the sender account to be killed (false), or transfer everything transferable, except at least the existential deposit, which will guarantee to keep the sender account alive (true).
[.contract-item]
[[force_unreserve]]
==== `[.contract-item-name]#++force_unreserve++#`
[source,rust]
----
pub fn force_unreserve(
origin: OriginFor<T>,
who: AccountIdLookupOf<T>,
amount: T::Balance,
) -> DispatchResult
----
Unreserve some balance from a user by force. The caller (origin) must be root.
**Params:**
* `origin: OriginFor<T>` -- caller (and in this case, sender) account.
* `who: AccountIdLookupOf<T>` -- the account for which the balance is to be unreserved.
* `amount: T::Balance` -- the amount of balance to be unreserved.
[.contract-item]
[[upgrade_accounts]]
==== `[.contract-item-name]#++upgrade_accounts++#`
[source,rust]
----
pub fn upgrade_accounts(
origin: OriginFor<T>,
who: Vec<T::AccountId>,
) -> DispatchResultWithPostInfo
----
Upgrade the specified account(s).
**Params:**
* `origin: OriginFor<T>` -- caller, must be `Signed`.
* `who: Vec<T::AccountId>` -- the account(s) to be upgraded.
NOTE: This will waive the transaction fee if at least all but 10% of the accounts need to be upgraded.
[.contract-item]
[[force_set_balance]]
==== `[.contract-item-name]#++force_set_balance++#`
[source,rust]
----
pub fn force_set_balance(
origin: OriginFor<T>,
who: AccountIdLookupOf<T>,
#[pezpallet::compact] new_free: T::Balance,
) -> DispatchResult
----
Set the regular balance of a given account. The caller (origin) must be root.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `who: AccountIdLookupOf<T>` -- the account for which the balance will be set.
* `new_free: T::Balance` -- the amount of free balance that will be set to the given account.
[.contract-item]
[[force_adjust_total_issuance]]
==== `[.contract-item-name]#++force_adjust_total_issuance++#`
[source,rust]
----
pub fn force_adjust_total_issuance(
origin: OriginFor<T>,
direction: AdjustmentDirection,
#[pezpallet::compact] delta: T::Balance,
) -> DispatchResult
----
Adjust the total issuance in a saturating way.
Can only be called by root and always needs a positive delta.
**Params:**
* `origin: OriginFor<T>` -- caller, must be root.
* `direction: AdjustmentDirection` -- the direction of issuance change (increase or decrease).
* `delta: T::Balance` -- the amount of free balance that will be set to the given account.
docs/modules/ROOT/pages/pezpallets/collator-selection.adoc
+255
View File
@@ -0,0 +1,255 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= collator_selection
Branch/Release: `release-polkadot-v1.10.0`
== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/cumulus/pezpallets/collator-selection/src/lib.rs[{github-icon},role=heading-link]
== Purpose
This pezpallet is needed to manage the set of xref:glossary.adoc#collator[collators] for each session and to provision the next session with the actual list of collators.
== Config
* Pezpallet-specific configs
** `UpdateOrigin` — defines the list of origins that are able to modify the settings of collators (e.g. set and remove list of xref:glossary.adoc#invulnerable[invulnerables], desired xref:glossary.adoc#candidates[candidates], xref:glossary.adoc#candidacy_bond[candidacy bond]). This type should implement the trait `EnsureOrigin`.
** `PotId` — id of account that will hold a xref:glossary.adoc#pot[Pot].
** `MaxCandidates` — maximum number of candidates
** `MinEligibleCollators` — minimum number of collators to collect for the session
** `MaxInvulnerables` — maximum number of invulnerables
** `KickThreshold` — number of blocks that should pass since the last block produced by a candidate collator for it to be removed from a candidates list and not participate in collation for the next session.
** `ValidatorId` — type for validator id
** `ValidatorIdOf` — type that allows to convert AccountId to ValidatorId
** `ValidatorRegistration` — type that checks that AccountId has its validator keys registered.
* Common configs:
** `RuntimeEvent`
** `Currency`
** `WeightInfo`
== Dispatchables
[.contract-item]
[[set_invulnerables]]
==== `[.contract-item-name]#++set_invulnerables++#`
[source,rust]
----
pub fn set_invulnerables(new: Vec<T::AccountId>)
----
Sets a new list of invulnerable collators. The call must be signed and origin of the call must fulfill the EnsureOrigin check.
IMPORTANT: This call does not maintain the mutual exclusiveness of candidates and invulnerables lists.
**Params:**
* `new: Vec<T::AccountId>` — a list of AccountIds of new invulnerables
**Errors:**
- `BadOrigin` — caller’s origin does not fulfill the `Config::EnsureOrigin` check.
- `TooFewEligibleCollators` — empty list of invulnerables was submitted and the number of candidates is smaller than `Config::MinEligibleCollators`
- `TooManyInvulnerables` — submitted list length is longer than `Config::MaxInvulnerables`
**Events:**
- `InvalidInvulnerableSkipped(account_id)` — submitted invulnerable does not have validator key or it is not registered
- `NewInvulnerables(invulnerables)` — new invulnerable list was set
[.contract-item]
[[set_desired_candidates]]
==== `[.contract-item-name]#++set_desired_candidates++#`
[source,rust]
----
pub fn set_desired_candidates(max: u32)
----
Set a new maximum possible number of candidates. If it is higher than `Config::MaxCandidates`, you should consider to rerun the benchmarks. The caller’s origin should fulfill the `Config::EnsureOrigin` check.
**Params:**
- `max: u32` — new desired candidates number
**Errors:**
- `BadOrigin` — caller’s origin does not fulfill the `Config::EnsureOrigin` check.
**Events:**
- `NewDesiredCandidates(desired_candidates)`
[.contract-item]
[[set_candidacy_bond]]
==== `[.contract-item-name]#++set_candidacy_bond++#`
[source,rust]
----
pub fn set_candidacy_bond(max: u32)
----
Set the amount for the deposit to be a candidate for collator.
**Params:**
- `bond: u32` — new amount for candidate deposit
**Errors:**
- `BadOrigin` — caller’s origin does not fulfill the `Config::EnsureOrigin` check.
**Events:**
- `NewCandidacyBond(bond_amount)`
[.contract-item]
[[register_as_candidate]]
==== `[.contract-item-name]#++register_as_candidate++#`
[source,rust]
----
pub fn register_as_candidate()
----
Register the caller as a collator candidate. Caller should be signed, have registered session keys and have amount needed for candidacy bond deposit. If successful, candidate will participate in collation process starting from the next session.
**Errors:**
- `BadOrigin` — call is not signed
- `TooManyCandidates` — number of collators is already at its maximum (specified in `desired_candidates` getter)
- `AlreadyInvulnerable` — caller is already in invulnerable collators list, it does not need to be a candidate to become a collator
- `NoAssociatedValidatorId` — caller does not have a session key.
- `ValidatorNotRegistered` — caller session key is not registered
- `AlreadyCandidate` — caller is already in candidates list
- `InsufficientBalance` — candidate does not have enough funds for deposit for candidacy bond
- `LiquidityRestrictions` — account restrictions (like frozen funds or vesting) prevent from creating a deposit
- `Overflow` — reserved funds overflow the currency type. Should not happen in usual scenarios.
**Events:**
- `CandidateAdded(account_id, deposit)`
[.contract-item]
[[leave_intent]]
==== `[.contract-item-name]#++leave_intent++#`
[source,rust]
----
pub fn leave_intent()
----
Unregister the caller from being a collator candidate. If successful, deposit will be returned and during the next session change collator will no longer participate in collation process. This call must be signed.
**Errors:**
- `BadOrigin` — call is not signed
- `TooFewEligibleCollators` — the number of collators for the next session will be less than `Config::MinEligibleCollators` in case of unregistration so the process is stopped.
- `NotCandidate` — caller is not on candidate list, nothing to unregister
**Events:**
- `CandidateRemoved(account_id)`
[.contract-item]
[[add_invulnerable]]
==== `[.contract-item-name]#++add_invulnerable++#`
[source,rust]
----
pub fn add_invulnerable(who: T::AccountId)
----
Add a new invulnerable. Call must be signed and caller pass `Config::EnsureOrigin` check. If a new invulnerable was previously a candidate, it will be removed from them.
*Params:*
- `who: T::AccountId` — an account to add to invulnerables list
**Errors:**
- `BadOrigin` — caller’s origin does not fulfill the `Config::EnsureOrigin` check.
- `NoAssociatedValidatorId` — new invulnerable does not have a session key.
- `ValidatorNotRegistered` — new invulnerable session key is not registered
- `AlreadyInvulnerable` — caller is already in invulnerable collators list
**Events:**
- `InvulnerableAdded(account_id)`
[.contract-item]
[[remove_invulnerable]]
==== `[.contract-item-name]#++remove_invulnerable++#`
[source,rust]
----
pub fn remove_invulnerable(who: T::AccountId)
----
Remove an invulnerable from the list. Call must be signed and caller pass `Config::EnsureOrigin` check.
*Params:*
- `who: T::AccountId` — an account to add to invulnerables list
**Errors:**
- `BadOrigin` — caller’s origin does not fulfill the `Config::EnsureOrigin` check.
- `TooFewEligibleCollators` — the number of invulnerable will become less than `Config::MinEligibleCollators` after the removal.
- `NotInvulnerable` — the `who` is not an invulnerable
**Events:**
- `InvulnerableRemoved(account_id)`
[.contract-item]
[[update_bond]]
==== `[.contract-item-name]#++update_bond++#`
[source,rust]
----
pub fn update_bond(new_deposit: BalanceOf<T>)
----
Update the candidacy bond of origin to the new value.
*Params:*
- `new_deposit: BalanceOf<T>` — new value for the candidacy bond
**Errors:**
- `BadOrigin` — caller’s origin does not fulfill the `Config::EnsureOrigin` check.
- `DepositTooLow` - new deposit is smaller than required candidacy bond.
- `NotCandidate` - caller's origin is not a candidate
- `IdenticalDeposit` - deposit have not changed
- `InsufficientBalance` — candidate does not have enough funds for deposit for candidacy bond
- `LiquidityRestrictions` — account restrictions (like frozen funds or vesting) prevent from creating a deposit
- `Overflow` — reserved funds overflow the currency type. Should not happen in usual scenarios.
- `InvalidUnreserve` - after the unreserve the number of candidates becomes less than desired.
- `InsertToCandidateListFailed` - candidate list is at maximum capacity. Should not happen in usual scenarios. Chain is misconfigured.
**Events:**
- `CandidateBondUpdated(account_id, deposit)`
[.contract-item]
[[take_candidate_slot]]
==== `[.contract-item-name]#++take_candidate_slot++#`
[source,rust]
----
pub fn take_candidate_slot(
deposit: BalanceOf<T>,
target: T::AccountId,
)
----
Try to replace the target's candidacy by making a bigger candidacy bond.
*Params:*
- `deposit: BalanceOf<T>` — value for the candidacy bond
- `target: T::AccountId` - target candidate to replace
**Errors:**
- `BadOrigin` — caller’s origin does not fulfill the `Config::EnsureOrigin` check.
- `AlreadyInvulnerable` — caller is already in invulnerable collators list.
- `InsufficientBond` - the deposit is less the candidacy bond or target's deposit.
- `NoAssociatedValidatorId` — caller does not have a session key.
- `ValidatorNotRegistered` — caller session key is not registered.
- `AlreadyCandidate` — caller is already in candidates list.
- `TargetIsNotCandidate` - target is not in candidate list.
- `InsufficientBalance` — candidate does not have enough funds for deposit for candidacy bond
- `LiquidityRestrictions` — account restrictions (like frozen funds or vesting) prevent from creating a deposit
- `Overflow` — reserved funds overflow the currency type. Should not happen in usual scenarios.
**Events:**
- `CandidateReplaced(old, new, deposit)`
docs/modules/ROOT/pages/pezpallets/message-queue.adoc
+158
View File
@@ -0,0 +1,158 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= pezpallet_message_queue
Branch/Release: `release-polkadot-v1.10.0`
Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/substrate/pezframe/message-queue/src/lib.rs[{github-icon},role=heading-link]
== Purpose
Flexible FRAME pezpallet for implementing message queues. This pezpallet can also initiate message processing using the `MessageProcessor` (see `Config`).
== Config
* Pezpallet-specific configs:
** `MessageProcessor` -- Processor for messages
** `Size` -- Page/heap size type.
** `QueueChangeHandler` -- Code to be called when a message queue changes - either with items introduced or removed.
** `QueuePausedQuery` -- Queried by the pezpallet to check whether a queue can be serviced.
** `HeapSize` -- The size of the page; this also serves as the maximum message size which can be sent.
** `MaxStale` -- The maximum number of stale pages (i.e. of overweight messages) allowed before culling can happen. Once there are more stale pages than this, then historical pages may be dropped, even if they contain unprocessed overweight messages.
** `ServiceWeight` -- The amount of weight (if any) which should be provided to the message queue for servicing enqueued items `on_initialize`. This may be legitimately `None` in the case that you will call `ServiceQueues::service_queues` manually or set [`Self::IdleMaxServiceWeight`] to have it run in `on_idle`.
** `IdleMaxServiceWeight` -- The maximum amount of weight (if any) to be used from remaining weight `on_idle` which should be provided to the message queue for servicing enqueued items `on_idle`. Useful for parachains to process messages at the same block they are received. If `None`, it will not call `ServiceQueues::service_queues` in `on_idle`.
* Common configs:
** `RuntimeEvent` -- The overarching event type.
** `WeightInfo` -- Weight information for extrinsics in this pezpallet.
== Dispatchables
[.contract-item]
[[execute_overweight]]
==== `[.contract-item-name]#++execute_overweight++#`
[source,rust]
----
pub fn execute_overweight(
origin: OriginFor<T>,
message_origin: MessageOriginOf<T>,
page: PageIndex,
index: T::Size,
weight_limit: Weight,
) -> DispatchResultWithPostInfo
----
Execute an overweight message.
NOTE: Temporary processing errors will be propagated whereas permanent errors are treated
as success condition.
IMPORTANT: The `weight_limit` passed to this function does not affect the `weight_limit` set in other parts of the pezpallet.
**Params:**
* `param1: Type1` -- description of the parameter
* `origin: OriginFor<T>` -- Must be `Signed`.
* `message_origin: MessageOriginOf<T>` -- indicates where the message to be executed arrived from (used for finding the respective queue that this message belongs to).
* `page: PageIndex` -- The page in the queue in which the message to be executed is sitting.
* `index: T::Size` -- The index into the queue of the message to be executed.
* `weight_limit: Weight` -- The maximum amount of weight allowed to be consumed in the execution
of the message. This weight limit does not affect other parts of the pezpallet, and it is only used for this call of `execute_overweight`.
**Errors:**
* `QueuePaused` -- if the queue that overweight message to be executed belongs to is paused.
* `NoPage` -- if the page that overweight message to be executed belongs to does not exist.
* `NoMessage` -- if the overweight message could not be found.
* `Queued` -- if the overweight message is already scheduled for future execution.
For a message to be labeled as overweight, the pezpallet must have previously attempted execution and
encountered failure due to insufficient weight for processing. Once marked as overweight, the message
is excluded from the queue for future execution.
* `AlreadyProcessed` -- if the overweight message is already processed.
* `InsufficientWeight` -- if the `weight_limit` is not enough to execute the overweight message.
* `TemporarilyUnprocessable` -- if the message processor `Yield`s execution of this message. This means processing should be reattempted later.
**Events:**
* `ProcessingFailed(id, origin, error)`
* `Processed(id, origin, weight_used, success)`
[.contract-item]
[[reap_page]]
==== `[.contract-item-name]#++reap_page++#`
[source,rust]
----
pub fn reap_page(
origin: OriginFor<T>,
message_origin: MessageOriginOf<T>,
page_index: PageIndex,
) -> DispatchResult
----
Remove a page which has no more messages remaining to be processed or is stale.
**Params:**
* `param1: Type1` -- description of the parameter
* `origin: OriginFor<T>` -- Must be `Signed`.
* `message_origin: MessageOriginOf<T>` -- indicates where the messages arrived from (used for finding the respective queue that this page belongs to).
* `page_index: PageIndex` -- The page to be reaped
**Errors:**
* `NotReapable` -- if the page is not stale yet.
* `NoPage` -- if the page does not exist.
**Events:**
* `PageReaped(origin, index)` -- the queue (origin), and the index of the page
== Important Mentions and FAQ's
IMPORTANT: The pezpallet utilizes the [`sp_weights::WeightMeter`] to manually track its consumption to always stay within
the required limit. This implies that the message processor hook can calculate the weight of a message without executing it.
==== How does this pezpallet work under the hood?
- This pezpallet utilizes queues to store, enqueue, dequeue, and process messages.
- Queues are stored in `BookStateFor` storage, with their origin serving as the key (so, we can identify queues by their origins).
- Each message has an origin (message_origin), that defines into which queue the message will be stored.
- Messages are stored by being appended to the last `Page` of the Queue's Book. A Queue is a book along with the MessageOrigin for that book.
- Each book keeps track of its pages, and the state (begin, end, count, etc.)
- Each page also keeps track of its messages, and the state (remaining, first, last, etc.)
- `ReadyRing` contains all ready queues as a double-linked list. A Queue is ready if it contains at least one Message which can be processed.
- `ServiceHead` is a pointer to the `ReadyRing`, pointing at the next `Queue` to be serviced. Service means: attempting to process the messages.
*Execution:*
* `service_queues` → returns the weight that is consumed by this function
** we will process a queue, till either:
*** there is no more message left
**** if there is no more message left in the queue, we won’t stop, service_head will proceed with the next queue
*** or weight is insufficient
**** if weight is insufficient for the next message in the queue, service_head will try to switch to next queue, and try to process message from that queue. This will go on, until it visits every queue, and no message can be processed. Only then, it will stop.
** each call to `service_queues`, we will bump the header, and start processing the next queue instead of the previous one to prevent starvation
*** Example:
**** service head is on queue 2
**** we called `service_queues`, which bumped the service head to queue 3
**** we processed messages from queue 3,
***** but weight was insufficient for the next message in queue 3,
***** so we switched to queue 4, (we don’t bump the service head for that)
***** weight was insufficient for queue 4 and other queues as well, and we made a round trip across queues, till we reach queue 3, and we stopped.
**** `service_queues` call finished
**** service head is on queue 3
**** we called `service_queue` again, which bumped the service head to queue 4 (although there are still messages left in queue 3)
**** we continue processing from queue 4.
*** but, to preserve priority, if we made a switch to a new queue due to weight, we don’t bump the service head. So, the next call, will be starting on the queue where we left off.
*** Example:
**** service head is on queue 2
**** we called `service_queues`, which bumped the service head to queue 3
**** we processed messages from queue 3,
***** but weight was insufficient for the next message in queue 3,
***** so we switched to queue 4, (we don’t bump the service head for that)
***** we processed a message from queue 4
***** weight was insufficient for queue 4 and other queues as well, and we made a round trip across queues, till we reach queue 3, and we stopped.
**** `service_queues` call finished
**** service head is on queue 3 (there are still messages in queue 3)
**** we called `service_queue` again, which bumped the service head to queue 4
**** we continue processing from queue 4, although we were processing queue 4 in the last call
docs/modules/ROOT/pages/pezpallets/multisig.adoc
+246
View File
@@ -0,0 +1,246 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= pezpallet_multisig
Branch/Release: `release-polkadot-v1.10.0`
== Source Code: link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/substrate/pezframe/multisig/src/lib.rs[{github-icon},role=heading-link]
== Purpose
This module enables multi-signature operations in your runtime. It allows multiple signed origins (accounts) to coordinate and dispatch a call. For the call to execute, the threshold number of accounts from the set (signatories) must approve it.
== Config
* Pezpallet-specific configs
** `DepositBase` -- The base amount of currency needed to xref:glossary.adoc#reserve[reserve] for creating a multisig execution or to store a dispatch call for later. Recall: The deposit to be made by the account that creates the multisig is: `threshold * DepositFactor + DepositBase`
** `DepositFactor` -- The amount of currency needed per unit threshold when creating a multisig execution. Recall: The deposit to be made by the account that creates the multisig is: `threshold * DepositFactor + DepositBase`
** `MaxSignatories` -- The maximum amount of signatories allowed in the multisig.
* Common configs
** `RuntimeEvent` -- The overarching event type.
** `RuntimeCall` -- The overarching call type.
** `Currency` -- The currency mechanism.
** `WeightInfo` -- xref:glossary.adoc#weight[Weight] information for extrinsics in this pezpallet.
== Dispatchables
[.contract-item]
[[approve_as_multi]]
==== `[.contract-item-name]#++approve_as_multi++#`
[source,rust]
----
pub fn approve_as_multi<T: Config>(
threshold: u16,
other_signatories: Vec<T::AccountId>,
maybe_timepoint: Option<Timepoint<BlockNumberFor<T>>>,
call_hash: [u8; 32],
max_weight: Weight
) -> DispatchResultWithPostInfo
----
Register approval for a dispatch to be made from a deterministic composite account.
Since the first register (from origin) counts as a vote as well, only `threshold - 1` additional votes are necessary from `other_signatories`.
Payment: `DepositBase` will be reserved if this is the first approval, plus `threshold` times `DepositFactor`. It is returned once this dispatch happens or is cancelled.
The dispatch origin for this call must be *Signed*.
The result is equivalent to the dispatched result if the threshold is exactly 1. Otherwise on success, the result is Ok and the result from the interior call, if it was executed, may be found in the deposited MultisigExecuted event.
TIP: If this is the final approval, you will want to use `as_multi` instead. `approve_as_multi` won’t trigger the dispatch, even if there are enough approvals.
The reason is: `as_multi` needs `call` parameter, whereas `approve_as_multi` needs `call_hash`. `call_hash` is enough to find the multisig operation entry in the storage, and increment the vote count. We don’t need the `call` itself to increment the vote count. Whereas, if `call` is supplied, and if we have enough approvals, the logic for execution will be triggered. This is a design choice.
**Params:**
* `threshold: u16` -- The total number of approvals for this dispatch before it is executed. Cannot be 1. If you want the threshold to be 1, use as_multi_threshold_1 instead.
* `other_signatories: Vec<T::AccountID>` -- The accounts (other than the sender) who can approve this dispatch. May not be empty.
* `maybe_timepoint: Option<Timepoint<BlockNumberFor<T>>>` -- Refers to the timepoint of the creation/registration of this call to the multisig storage. If this is the first approval, then this must be None (business logic derives it automatically). If it is not the first approval, then it must be Some, with the timepoint (block number and transaction index) of the first approval transaction.
* `call_hash: [u8; 32]` -- The hash of the call to be executed.
* `max_weight: Weight` -- Maximum weight limit for the call's execution.
**Errors:**
* `MaxWeightTooLow` -- when the call requires more weight to be executed, the call won't be executed and an error will be returned.
* `MinimumThreshold` -- when the threshold is not greater than 1
* `TooFewSignatories` -- when `other_signatories` list is empty
* `TooManySignatories` -- when `other_signatories` length is greater than `MaxSignatories`
* `NoTimepoint` -- when this is not the first call, and no timepoint is given
* `WrongTimepoint` -- when this is not the first call, and the wrong timepoint is given
* `UnexpectedTimepoint` -- when this is the first call, and a timepoint is given
* `AlreadyApproved` -- when a signatory tries to approve more than once
**Events:**
* `MultisigApproved(approving, timepoint, multisig, call_hash)` -- when multisig call is approved. This also gives information on who was the last approver (`approving`), the `timepoint` of the call, id of the multisig call (`multisig`), hash of the multisig call (`call_hash`).
* `NewMultisig (approving, multisig, call_hash`) -- when a multisig call is created. This also gives information on who was the creator (also the first approver) (`approving`), id of the multisig call (`multisig`), hash of the multisig call (`call_hash`).
[.contract-item]
[[as_multi]]
==== `[.contract-item-name]#++as_multi++#`
[source,rust]
----
pub fn as_multi<T: Config>(
threshold: u16,
other_signatories: Vec<T::AccountId>,
maybe_timepoint: Option<Timepoint<BlockNumberFor<T>>>,
call: Box<<T as Config>::RuntimeCall>,
max_weight: Weight
) -> DispatchResultWithPostInfo
----
TIP: Unless this is the final approval, you will generally want to use `approve_as_multi` instead, since it only requires a hash of the call.
`call_hash` is enough to find the multisig operation entry in the storage, and increment the vote count. We don’t need the `call` itself to increment the vote count.
Whereas, if `call` is supplied, and if we have enough approvals, the logic for execution will be triggered.
`as_multi` is nearly identical to `approve_as_multi`, the only difference being `call` vs `call_hash`.
Register approval for a dispatch to be made from a deterministic composite account if approved by a total of `threshold - 1` of `other_signatories`.
If there are enough, then dispatch the call.
Payment: `DepositBase` will be reserved if this is the first approval, plus `threshold` times `DepositFactor`. It is returned once this dispatch happens or is cancelled.
The dispatch origin for this call must be *Signed*.
WARNING: When as_multi is called, if it succeeds (dispatches the call), the multisig operation will be removed from the storage. Meaning, another person cannot trigger the same multisig call. They need to create the same one from scratch again.
**Params:**
* `threshold: u16` -- The total number of approvals for this dispatch before it is executed. Cannot be 1. If you want the threshold to be 1, use as_multi_threshold_1 instead.
* `other_signatories: Vec<T::AccountID>` -- The accounts (other than the sender) who can approve this dispatch. May not be empty.
* `maybe_timepoint: Option<Timepoint<BlockNumberFor<T>>>` -- Refers to the timepoint of the creation/registration of this call to the multisig storage. If this is the first approval, then this must be None (business logic derives it automatically). If it is not the first approval, then it must be Some, with the timepoint (block number and transaction index) of the first approval transaction.
* `call: Box<<T as Config>::RuntimeCall>` -- The call to be executed.
* `max_weight: Weight` -- Maximum weight limit for the call's execution.
**Errors:**
* `MaxWeightTooLow` -- when the call requires more weight to be executed, the call won't be executed and an error will be returned.
* `MinimumThreshold` -- when the threshold is not greater than 1
* `TooFewSignatories` -- when `other_signatories` list is empty
* `TooManySignatories` -- when `other_signatories` length is greater than `MaxSignatories`
* `NoTimepoint` -- when this is not the first call, and no timepoint is given
* `WrongTimepoint` -- when this is not the first call, and the wrong timepoint is given
* `UnexpectedTimepoint` -- when this is the first call, and a timepoint is given
* `AlreadyApproved` -- when a signatory tries to approve more than once
**Events:**
* `MultisigExecuted(approving, timepoint, multisig, call_hash, result)` -- when multisig call is executed. This also gives information on who was the last approver (`approving`), the `timepoint` of the call, id of the multisig call (`multisig`), hash of the multisig call (`call_hash`), and the `result`.
* `MultisigApproved(approving, timepoint, multisig, call_hash)` -- when multisig call is approved. This also gives information on who was the last approver (`approving`), the `timepoint` of the call, id of the multisig call (`multisig`), hash of the multisig call (`call_hash`).
* `NewMultisig (approving, multisig, call_hash`) -- when a multisig call is created. This also gives information on who was the creator (also the first approver) (`approving`), id of the multisig call (`multisig`), hash of the multisig call (`call_hash`).
[.contract-item]
[[cancel_as_multi]]
==== `[.contract-item-name]#++cancel_as_multi++#`
[source,rust]
----
pub fn cancel_as_multi<T: Config>(
threshold: u16,
other_signatories: Vec<T::AccountId>,
timepoint: Timepoint<BlockNumberFor<T>>,
call_hash: [u8; 32]
) -> DispatchResult
----
Cancel a pre-existing, ongoing multisig transaction. Any deposit reserved previously for this operation will be unreserved on success.
IMPORTANT: Only the owner of the multisig operation can cancel it (not even other signatories).
TIP: Cancel operation does not require multi-signature. The owner calling this function is enough on its own to cancel this.
Multisig operations are stored in the storage with double keys, hence other_signatories and threshold are necessary for the identification of the multisig operation.
**Params:**
* `threshold: u16` -- The total number of approvals for this dispatch before it is executed. Cannot be 1. If you want the threshold to be 1, use as_multi_threshold_1 instead.
* `other_signatories: Vec<T::AccountID>` -- The accounts (other than the sender) who can approve this dispatch. May not be empty.
* `timepoint: Option<Timepoint<BlockNumberFor<T>>>` -- Refers to the timepoint of the creation/registration of this call to the multisig storage. If this is the first approval, then this must be None (business logic derives it automatically). If it is not the first approval, then it must be Some, with the timepoint (block number and transaction index) of the first approval transaction.
* `call_hash: [u8; 32]` -- The hash of the call to be executed.
**Errors:**
* `MinimumThreshold` -- when the threshold is not greater than 1
* `TooFewSignatories` -- when `other_signatories` list is empty
* `TooManySignatories` -- when `other_signatories` length is greater than `MaxSignatories`
* `WrongTimepoint` -- when this is not the first call, and the wrong timepoint is given
* `NotFound` -- when the multisig call is not found in the storage
* `NotOwner` -- when someone who is not the owner tried to cancel
**Events:**
* `MultisigCancelled(cancelling, timepoint, multisig, call_hash)` -- when multisig call is cancelled. This also gives information on who cancelled (`cancelling`), the `timepoint` of the call, id of the multisig call (`multisig`), hash of the multisig call (`call_hash`).
[.contract-item]
[[as_multi_threshold_1]]
==== `[.contract-item-name]#++as_multi_threshold_1++#`
[source,rust]
----
pub fn as_multi_threshold_1<T: Config>(
other_signatories: Vec<T::AccountId>,
call: Box<<T as Config>::RuntimeCall>
) -> DispatchResultWithPostInfo
----
Immediately dispatch a multi-signature call using a single approval from the caller.
The dispatch origin for this call must be *Signed*.
A real use case scenario could be for example a business that has a bank account and says "any one of the 3 founders can authorize payments from this account".
**Params:**
* `other_signatories: Vec<T::AccountID>` -- The accounts (other than the sender) who can approve this dispatch. May not be empty.
* `call: Box<<T as Config>::RuntimeCall>` -- The call to be executed.
**Errors:**
* `MinimumThreshold` -- when the threshold is not greater than 1
* `TooFewSignatories` -- when `other_signatories` list is empty
* `TooManySignatories` -- when `other_signatories` length is greater than `MaxSignatories`
* `WrongTimepoint` -- when this is not the first call, and the wrong timepoint is given
* `NotFound` -- when the multisig call is not found in the storage
* `NotOwner` -- when someone who is not the owner tried to cancel
**Events:**
* `MultisigCancelled(cancelling, timepoint, multisig, call_hash)` -- when multisig call is cancelled. This also gives information on who cancelled (`cancelling`), the `timepoint` of the call, id of the multisig call (`multisig`), hash of the multisig call (`call_hash`).
== Important Mentions and FAQ's
*Big Picture Examples*
* funding the multisig account (same for `1-out-of-n multisig accounts`, and `m-out-of-n multisig accounts`)
** find the public key of the shared account
*** use polkadot JS to create a multisig account
*** or, use `multi_account_id` in the source code
** fund the account by simply sending some money to the derived public key
** 👉 check this documentation if you have questions about accounts and their creation xref:misc/multisig-accounts.adoc[multisig_accounts]
* `m-out-of-n multisig account` example:
** Alice, Bob, Charlie, and Dylan want to create a shared account, and the threshold for this shared account should be 3 (at least 3 people should approve the transactions for this account).
** One of the signatories should create the multisig operation by calling `as_multi`, and should provide the necessary arguments
** Others can approve this call using `approve_as_multi`, however, `approve_as_multi` will not dispatch the call. This will only increase the approval amount.
** If the approver wants to dispatch the call as well, they should use `as_multi` instead.
** *Niche Details:*
*** If a signatory tries to call `approve_as_multi` after the threshold is surpassed, they will get an error: `AlreadyApproved`, because this action is meaningless.
*** A signatory can call `as_multi` to dispatch the call, even if they approved the same multisig before.
* `1-out-of-n multisig account` example:
** Alice, Bob, and Charlie want to create a shared account, and the threshold for this shared account should be 1 (any person can spend from this account, without any approval).
** any of them can call `as_multi_threshold_1`, and spend the money without requiring approval from others
** *Niche Details:*
*** `as_multi_threshold_1` does not store multisig operations in storage. Because there is no need to do so.
**** Q: if we are not storing it, how can other signatories use this shared account in the future?
**** A: the account’s balance is stored in blockchain. The account’s public key is derived from the public keys of the signatories, combined with the threshold. So, the caller has permission to spend the balance that belongs to the derived public key.
**** we are not storing `1-out-of-n multisig operations`, but we are storing `m-out-of-n multisig operations`, since we have to keep track of the approvals.
**** It does not make sense to cancel `1-out-of-n multisig operations`, because `as_multi_threshold_1` immediately dispatches the call, there is no state in which canceling is a viable option for `1-out-of-n multisig operations`.
docs/modules/ROOT/pages/pezpallets/proxy.adoc
+354
View File
@@ -0,0 +1,354 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= pezpallet_proxy
Branch/Release: `release-polkadot-v1.10.0`
== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/substrate/pezframe/proxy/src/lib.rs[{github-icon},role=heading-link]
== Purpose
This pezpallet enables delegation of rights to execute certain call types from one origin to another.
== Config
* Pezpallet-specific configs:
** `ProxyType` -- a type that describes different variants of xref:glossary.adoc#proxy[proxy]. It must implement `Default` trait and `InstanceFilter<RuntimeCall>` trait.
** `ProxyDepositBase` -- a base amount of currency that defines a deposit for proxy creation.
** `ProxyDepositFactor` -- an amount of currency that will be frozen along with the `ProxyDepositBase` for each additional proxy.
** `MaxProxies` -- maximum number of proxies that single account can create.
** `MaxPending` -- maximum number of xref:glossary.adoc#announcement[announcements] that can be made per account.
** `CallHasher` -- a type implementing a `Hash` trait. Will be used to hash the executed call.
** `AnnouncementDepositBase` -- a base amount of currency that defines a deposit for announcement creation.
** `AnnouncementDepositFactor` -- an amount of currency that will be frozen along with the `AnnouncementDepositBase` for each additional announcement.
* Common configs:
** `RuntimeEvent`
** `RuntimeCall`
** `Currency`
== Dispatchables
[.contract-item]
[[add_proxy]]
==== `[.contract-item-name]#++add_proxy++#`
[source,rust]
----
pub fn add_proxy<T: Config>(
delegate: <<T as Config>::Lookup as StaticLookup>::Source,
proxy_type: T::ProxyType,
delay: BlockNumberFor<T>
)
----
Create a new `Proxy` that allows `delegate` to execute calls that fulfill `proxy_type` check on your origin’s behalf.
The origin must be signed for this call.
This call will take (or modify) a deposit based on number of proxies created by xref:glossary.adoc#delegator[delegator] and calculated by this formula: `ProxyDepositBase + ProxyDepositFactor * <number of proxies>`
There may not be more proxies than `MaxProxies`
**Params:**
- `delegate: <<T as Config>::Lookup as StaticLookup>::Source` — account that will become a proxy for the origin
- `proxy_type: T::ProxyType` — type of calls that will be allowed for the delegate
- `delay: BlockNumberFor<T>` — number of blocks that needs to happen between announcement and call for this proxy
**Errors:**
- `BadOrigin` — request not signed
- `LookupError` — delegate not found
- `NoSelfProxy` — delegate and call origin is the same account
- `Duplicate` — proxy already exists
- `TooMany` — too many proxies created for this delegate with this type and the same xref:glossary.adoc#delay[delay]
- `InsufficientBalance` — delegator does not have enough funds for deposit for proxy creation
- `LiquidityRestrictions` — account restrictions (like frozen funds or vesting) prevent from creating a deposit
- `Overflow` — reserved funds overflow the currency type. Should not happen in usual scenarios.
**Events:**
- `ProxyAdded(delegator, delegatee, proxy_type, delay)`
[.contract-item]
[[announce]]
==== `[.contract-item-name]#++announce++#`
[source,rust]
----
pub fn announce(
real: AccountIdLookupOf<T>,
call_hash: CallHashOf<T>,
)
----
Announce a call that will be executed using a proxy. As a result announcement will be created. You must create an announcement if the proxy you are using specified a delay greater than zero. In that case you will be able to execute a call after the number of blocks specified by delay.
The origin must be signed for this call.
This call will take (or modify) a deposit calculated by this formula: `AnnouncementDepositBase + AnnouncementDepositFactor * <number of announcements present>`
There may not be more announcements than `MaxPending`
**Params:**
- `real: AccountIdLookupOf<T>` — the account on which behalf this call will be made
- `call_hash: CallHashOf<T>` — hash of the call that is going to be made
**Errors:**
- `BadOrigin` — request not signed
- `LookupError` — `real` account not found
- `NotProxy` — there is no proxy between the caller and real
- `TooMany` — there is more announcements for this sender than specified in `MaxPending`
- `InsufficientBalance` — caller does not have enough funds for deposit for announcement creation
- `LiquidityRestrictions` — account restrictions (like frozen funds or vesting) prevent from creating a deposit
- `Overflow` — reserved funds overflow the currency type. Should not happen in usual scenarios.
**Events:**
- `Announced(real, proxy, call_hash)`
[.contract-item]
[[proxy]]
==== `[.contract-item-name]#++proxy++#`
[source,rust]
----
pub fn proxy(
real: AccountIdLookupOf<T>,
force_proxy_type: Option<T::ProxyType>,
call: Box<<T as Config>::RuntimeCall>,
)
----
Dispatch a `call` on behalf of `real` account using a proxy that was created in advance. Proxy must be created for the call sender to execute the call.
The origin must be signed for this call.
If the proxy requires an announcement before the call, this dispatchable will fail.
**Params:**
- `real: AccountIdLookupOf<T>` — the account on which behalf this call will be made
- `force_proxy_type: Option<T::ProxyType>` — specific xref:glossary.adoc#proxy_type[proxy type] to get proxy for. If not specified, first one found in the storage will be used.
- `call: Box<<T as Config>::RuntimeCall>` — a call to execute
**Errors:**
- `BadOrigin` — request not signed
- `LookupError` — `real` account not found
- `NotProxy` — there is no proxy between the caller and real
- `Unannounced` — there was a delay specified but not fulfilled
**Events:**
- `ProxyExecuted(result)`
[.contract-item]
[[proxy_announced]]
==== `[.contract-item-name]#++proxy_announced++#`
[source,rust]
----
pub fn proxy_announced<T: Config>(
delegate: <<T as Config>::Lookup as StaticLookup>::Source,
real: <<T as Config>::Lookup as StaticLookup>::Source,
force_proxy_type: Option<T::ProxyType>,
call: Box<<T as Config>::RuntimeCall>
)
----
Execute previously announced call using a proxy and remove the announcement. Proxy must be created for the call sender to execute the call.
The origin must be signed for this call.
This call will fail if delay after announcement have not passed or call was not announced.
**Params:**
- `delegate: <<T as Config>::Lookup as StaticLookup>::Source` — the account proxy was given to and who announced the call
- `real: <<T as Config>::Lookup as StaticLookup>::Source` — delegator of the proxy, on whose behalf call will be executed
- `force_proxy_type: Option<T::ProxyType>` — specific proxy type to get proxy for. If not specified, first one found in the storage will be used.
- `call: Box<<T as Config>::RuntimeCall>` — a call to execute
**Errors:**
- `BadOrigin` — request not signed
- `LookupError` — `real` or `delegate` account not found
- `NotProxy` — there is no proxy between the `delegate` and `real`
- `Unannounced` — there was a delay specified but not fulfilled or call was not announced
**Events:**
- `ProxyExecuted(result)`
[.contract-item]
[[reject_announcement]]
==== `[.contract-item-name]#++reject_announcement++#`
[source,rust]
----
pub fn reject_announcement<T: Config>(
delegate: <<T as Config>::Lookup as StaticLookup>::Source,
call_hash: <<T as Config>::CallHasher as Hash>::Output
)
----
Remove the given announcement. Deposit is returned in case of success.
May be called from delegator of the proxy to remove announcement made by xref:glossary.adoc#delegatee[delegatee].
The origin must be signed for this call.
**Params:**
- `delegate: <<T as Config>::Lookup as StaticLookup>::Source` — account that created an announcement
- `call_hash: <<T as Config>::CallHasher as Hash>::Output` — hash that was created for the announcement
**Errors:**
- `BadOrigin` — request not signed
- `LookupError` — `delegate` account not found
- `NotFound` — proxy not found for this delegator and delegatee
[.contract-item]
[[remove_announcement]]
==== `[.contract-item-name]#++remove_announcement++#`
[source,rust]
----
pub fn remove_announcement<T: Config>(
real: <<T as Config>::Lookup as StaticLookup>::Source,
call_hash: <<T as Config>::CallHasher as Hash>::Output
)
----
Remove the given announcement. Deposit is returned in case of success.
May be called from delegatee of the proxy to remove announcement made by them.
The origin must be signed for this call.
**Params:**
- `real: <<T as Config>::Lookup as StaticLookup>::Source` — delegator of the proxy for the announcement to remove
- `call_hash: <<T as Config>::CallHasher as Hash>::Output` — hash of announced call
**Errors:**
- `BadOrigin` — request not signed
- `LookupError` — `delegate` account not found
- `NotFound` — proxy not found for this delegator and delegatee
[.contract-item]
[[remove_proxies]]
==== `[.contract-item-name]#++remove_proxies++#`
[source,rust]
----
pub fn remove_proxies()
----
Removes all proxies _issued to_ the caller. The origin must be signed for this call.
**Errors:**
- `BadOrigin` — request not signed
[.contract-item]
[[remove_proxy]]
==== `[.contract-item-name]#++remove_proxy++#`
[source,rust]
----
pub fn remove_proxy<T: Config>(
delegate: <<T as Config>::Lookup as StaticLookup>::Source,
proxy_type: T::ProxyType,
delay: BlockNumberFor<T>
)
----
Remove the proxy issued by the caller. Deposit is returned to the delegator.
Origin must be signed for this call.
**Params:**
- `delegate: <<T as Config>::Lookup as StaticLookup>::Source` — account to whom this proxy was issued
- `proxy_type: T::ProxyType` — type of the issued proxy
- `delay: BlockNumberFor<T>` — delay of the issued proxy
**Errors:**
- `BadOrigin` — request not signed
- `LookupError` — `delegate` account not found
- `NotFound` — no such proxy exists
**Events:**
- `ProxyRemoved(delegator, delegatee, proxy_type, delay)`
[.contract-item]
[[create_pure]]
==== `[.contract-item-name]#++create_pure++#`
[source,rust]
----
pub fn create_pure<T: Config>(
proxy_type: T::ProxyType,
delay: BlockNumberFor<T>,
index: u16
)
----
This call creates a xref:glossary.adoc#pur_account[pure account] with a proxy issued to it from the call’s origin.
The origin must be signed for this call.
**Params:**
- `proxy_type: T::ProxyType` — type of calls that will be allowed for the proxy
- `delay: BlockNumberFor<T>` — number of blocks that needs to happen between announcement and call for this proxy
- `index: u16` — A disambiguation index, in case this is called multiple times in the same
transaction (e.g. with `utility::batch`). Unless you’re using `batch` you probably just
want to use `0`.
**Errors:**
- `BadOrigin` — request not signed
- `Duplicate` — `create_pure` was called more than once with the same parameters in the same transaction
- `TooMany` — there is more announcements for this sender than specified in `MaxPending`
- `InsufficientBalance` — delegator does not have enough funds for deposit for proxy creation
- `LiquidityRestrictions` — account restrictions (like frozen funds or vesting) prevent from creating a deposit
- `Overflow` — reserved funds overflow the currency type. Should not happen in usual scenarios.
**Events:**
- `PureCreated(pure, who, proxy_type, disambiguation_index)`
[.contract-item]
[[kill_pure]]
==== `[.contract-item-name]#++kill_pure++#`
[source,rust]
----
pub fn kill_pure<T: Config>(
spawner: <<T as Config>::Lookup as StaticLookup>::Source,
proxy_type: T::ProxyType,
index: u16,
height: BlockNumberFor<T>,
ext_index: u32
)
----
Remove a previously created pure account.
Requires a `Signed` origin, and the sender account must have been created by a call to
`pure` with corresponding parameters.
WARNING: All access to this account will be lost.
**Params:**
- `spawner` — account who created a proxy and pure account
- `proxy_type` — type of proxy used for it
- `index` — the disambiguation index used for pure account creation
- `height` — the height of the chain when the call to `pure` was processed.
- `ext_index` — the extrinsic index in which the call to `pure` was processed.
**Errors:**
- `BadOrigin` — request not signed
- `LookupError` — `spawner` account not found
- `NoPermission` — emitted when account tries to remove somebody but not itself
docs/modules/ROOT/pages/pezpallets/teyrchain-system.adoc
+131
View File
@@ -0,0 +1,131 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= parachain_system
Branch/Release: `release-polkadot-v1.10.0`
== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/cumulus/pezpallets/parachain-system/src/lib.rs[{github-icon},role=heading-link]
== Purpose
This pezpallet is a core element of each parachain. It will:
- Aggregate information about built blocks
- Process binary code upgrades
- Process incoming messages from both relay chain and other parachains (if a channel is established between them)
- Send outgoing messages to relay chain and other parachains
- Build collation info when requested by xref:glossary.adoc#collator[collator]
== Config
* Pezpallet-specific configs:
** `OnSystemEvent` — a handler that will be called when new xref:glossary.adoc#validation_data[validation data] will be set (once each block). New validation data will also be passed to it. Look to `trait OnSystemEvent` for more details.
** `SelfParaId` — getter for a parachain id of this chain
** `OutboundXcmpMessageSource` — source of outgoing XCMP messages. It is queried in `finalize_block` and later included into collation information
** `DmpQueue` — a handler for the incoming *downward* messages from relay chain
** `ReservedDmpWeight` — xref:glossary.adoc#weight[weight] reserved for DMP message processing. This config seems to be is not used as the function that processes these messages (`enqueue_inbound_downward_messages`) returns used weight.
** `XcmpMessageHandler` — a handler for the incoming _horizontal_ messages from other parachains
** `ReservedXcmpWeight` — default weight limit for the for the XCMP message processing. May be overridden by storage `ReservedXcmpWeightOverride` . If incoming messages in block will exceed the weight limit, they won’t be processed.
** `CheckAssociatedRelayNumber` — type that implements `trait CheckAssociatedRelayNumber` . Currently there are three implementations: no check (`AnyRelayNumber`), strict increase (`RelayNumberStrictlyIncreases`), monotonic increase (`RelayNumberMonotonicallyIncreases`). It is needed to maintain some order between blocks in relay chain and parachain.
** `ConsensusHook` — this is a feature-enabled config ( for the management of the xref:glossary.adoc#unincluded_segment[unincluded segment]. Requires the implementation of `trait ConsensusHook`. There are several implementations of it, in `parachain-system` crate (`FixedCapacityUnincludedSegment`) and in `aura-ext` crate (`FixedVelocityConsensusHook`). It is needed to maintain the logic of segment length handling.
* Common parameters for all pezpallets:
** `RuntimeEvent`
** `WeightInfo`
== Dispatchables
[.contract-item]
[[set_validation_data]]
==== `[.contract-item-name]#++set_validation_data++#`
[source,rust]
----
pub fn set_validation_data(
data: ParachainInherentData,
)
----
This call is an inherent, you can’t call this from another dispatchable or from client side. This call sets up validation data for collation, processes code upgrades and updates unincluded segments.
[.contract-item]
[[sudo_send_upward_message]]
==== `[.contract-item-name]#++sudo_send_upward_message++#`
[source,rust]
----
pub fn sudo_send_upward_message(
message: UpwardMessage,
)
----
Send a message to relay as a sudo.
**Params:**
- `message` — a vec of bytes that represents a message that you send to the relay
**Errors:**
- `BadOrigin` — call was made not from a sudo
[.contract-item]
[[authorize_upgrade]]
==== `[.contract-item-name]#++authorize_upgrade++#`
[source,rust]
----
pub fn authorize_upgrade(
code_hash: T::Hash,
check_version: bool,
)
----
Authorize the upgrade. This call will put the hash and flag to the storage `AuthorizedUpgrade`. This call must be made as a sudo.
**Params:**
- `code_hash` — hash of the authorized runtime binary
- `check_version` — flag that indicates that the code should be checked for the possibility to upgrade. It will happen during the upgrade process itself.
**Errors:**
- `BadOrigin` — call was made not from a sudo
**Events:**
- `UpgradeAuthorized(code_hash)`
[.contract-item]
[[enact_authorized_upgrade]]
==== `[.contract-item-name]#++enact_authorized_upgrade++#`
[source,rust]
----
pub fn enact_authorized_upgrade(
code: Vec<u8>,
)
----
Validate and perform the authorized upgrade.
**Params:**
- `code` — runtime binary for the upgrade
**Errors:**
- `NothingAuthorized` — there is no authorized upgrade, call `authorize_upgrade` in advance
- `Unauthorized` — there is another upgrade authorized
== Important Mentions and FAQ's
=== Pezpallet's workflow
* Block Initialization
** Remove already processed xref:glossary.adoc#validation_code[validation code]
** Update `UnincludedSegment` with latest parent hash
** Cleans up `ValidationData` and other functions.
** Calculate weights for everything that was done in `on_finalize` hook
* Inherents — `set_validation_data` call
** Clean the included segments from `UnincludedSegment` and update the `AggregatedUnincludedSegment`
** Update `ValidationData`, `RelayStateProof` and other configs from relay.
** Process the `ValidationCode` upgrade
* Block Finalization
** Enqueue all received messages from relay chain and other parachains
** Update `UnincludedSegment` and `AggregatedUnincludedSegment` with the latest block data
docs/modules/ROOT/pages/pezpallets/transaction_payment.adoc
+56
View File
@@ -0,0 +1,56 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= pezpallet_transaction_payment
Branch/Release: `release-polkadot-v1.10.0`
== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/substrate/pezframe/transaction-payment/src/lib.rs[{github-icon},role=heading-link]
== Purpose
`pezpallet-transaction-payment` implements transaction fee logic.
In substrate, every transaction has an associated `call`, and each `call` has its own xref:glossary.adoc#weight[weight] function. The weight function estimates the time it takes to execute the `call`.
`Config::WeightToFee` is a mapping between the smallest unit of compute (*Weight*) and smallest unit of fee.
This pezpallet also exposes
- how to update fees for the next block based on past fees (`Config::FeeMultiplierUpdate`)
- how fees are paid (`Config::OnChargeTransaction`)
The base fee and adjusted xref:glossary.adoc#weight_fee[weight] and xref:glossary.adoc#length_fee[length] fees constitute the _inclusion fee_, which is the minimum fee for a transaction to be included in a block. The formula of final fee:
```rust, ignore
inclusion_fee = base_fee + length_fee + [fee_multiplier_update * weight_fee];
final_fee = inclusion_fee + tip;
```
The inputs are defined below in the glossary and config sections.
== Config
* Pezpallet-specific handlers:
** `OnChargeTransaction` -- Handler for withdrawing, refunding and depositing the transaction fee. Type must implement the trait `OnChargeTransaction<Self>`.
** `FeeMultiplierUpdate` -- Handler to define how base fees change over time (over blocks). Type must implement the trait `MultiplierUpdate`. Possible assignments include `ConstantFee`, `SlowAdjustingFee`, and `FastAdjustingFee`.
* Pezpallet-specific converters:
** `WeightToFee` -- Mapping between the smallest unit of weight and smallest unit of fee. Type must implement the trait `WeightToFee<Balance = BalanceOf<Self>>`.
** `LengthToFee` -- Convert a length value into a deductible fee based on the currency type. Type must implement the trait `WeightToFee<Balance = BalanceOf<Self>>`.
* Pezpallet-specific constants:
** `OperationalFeeMultiplier` -- A fee multiplier for `Operational` extrinsics to compute "virtual tip" to boost their `priority`. Type must implement the trait `Get<u32>`.
* Common configs:
** `RuntimeEvent`
== Dispatchables
There are no dispatchables (and no errors) in this pezpallet. This pezpallet is only intended to configure the transaction fee logic for a chain.
**Events:**
* `TransactionFeePaid(who, actual_fee, tip)` -- a transaction fee was paid by account `who` with total amount of `actual_fee + tip`.
== More Reading
** https://www.shawntabrizi.com/blog/substrate/substrate-weight-and-fees/[Substrate Weight & Fees] by Shawn Tabrizi
* https://docs.substrate.io/build/tx-weights-fees/[Substrate Docs: Transaction Weight & Fees]
** https://docs.substrate.io/reference/how-to-guides/weights/calculate-fees/#:~:text=Weight%20fee%20%2D%20A%20fee%20calculated,change%20as%20the%20chain%20progresses[Substrate Docs: How to Calculate Fees]
docs/modules/ROOT/pages/pezpallets/treasury.adoc
+245
View File
@@ -0,0 +1,245 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= pezpallet_treasury
Branch/Release: `release-polkadot-v1.10.0`
== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/substrate/pezframe/treasury/src/lib.rs[{github-icon},role=heading-link]
== Purpose
The Treasury pezpallet provides a “pot” of funds that can be managed by stakeholders in the system and a structure for making spending proposals from this pot.
== Config
* Pezpallet-specific configs
** `SpendPeriod` -- Period between successive spends. "Spend" means, treasury spending money to a proposal. `SpendPeriod` determines how often the treasury pezpallet distributes the assets to the proposals.
** `Burn` -- Percentage of spare funds (if any) that are burnt per spend period.
** `BurnDestination` -- Handler for the unbalanced decrease when treasury funds are burned.
** `SpendFunds` -- Runtime hooks to external pezpallet using treasury to compute spend funds.
** `MaxApprovals` -- The maximum number of approvals that can wait in the spending queue. NOTE: This parameter is also used within the Bounties Pezpallet extension if enabled.
** `AssetKind` -- Type parameter representing the asset kinds to be spent from the treasury.
** `Beneficiary` -- Type parameter used to identify the beneficiaries eligible to receive treasury spends.
** `BeneficiaryLookup` -- Converting trait to take a source type and convert to [`Self::Beneficiary`].
** `Paymaster` -- Type for processing spends of [Self::AssetKind] in favor of [`Self::Beneficiary`].
** `BalanceConverter` -- Type for converting the balance of an [Self::AssetKind] to the balance of the native asset, solely for the purpose of asserting the result against the maximum allowed spend amount of the [`Self::SpendOrigin`].
** `PayoutPeriod` -- The period during which an approved treasury spend has to be claimed by the beneficiary of the proposal.
* Pezpallet-specific origins:
** `RejectOrigin` -- Origin from which rejections must come.
** `SpendOrigin` -- The origin required for approving spends from the treasury outside of the proposal process. The `Success` value is the maximum amount in a native asset that this origin is allowed to spend at a time.
* Common configs
** `Currency` -- The staking balance.
** `RuntimeEvent` -- The overarching event type.
** `PezpalletId` -- The treasury's pezpallet id, used for deriving its sovereign account ID.
** `WeightInfo` -- Weight information for extrinsics in this pezpallet.
** `BenchmarkHelper` -- Helper type for benchmarks.
== Dispatchables
[.contract-item]
[[spend_local]]
==== `[.contract-item-name]#++spend_local++#`
[source,rust]
----
pub fn spend_local(
origin: OriginFor<T>,
#[pezpallet::compact] amount: BalanceOf<T, I>,
beneficiary: AccountIdLookupOf<T>,
) -> DispatchResult
----
Propose and approve a spend of treasury funds, enables the creation of spends using the native currency of the chain, utilizing the funds stored in the pot.
NOTE: For record-keeping purposes, the proposer is deemed to be equivalent to the beneficiary.
NOTE: The behavior and API of the old `spend` call capable of spending local DOT tokens remain unchanged, and is now under the name `spend_local`. The revised
new `spend` call is able to spend any asset kind managed by the treasury.
**Params:**
* `origin: OriginFor<T>` -- Must be [`Config::SpendOrigin`] with the `Success` value being at least `amount`.
* `value: BalanceOf<T, I>` -- The amount to be transferred from the treasury to the `beneficiary`.
* `beneficiary: AccountIdLookupOf<T>` -- The destination account for the transfer.
**Errors:**
* `InsufficientPermission` -- if the amount to be spent is greater than what the dispatcher of this call is allowed to spend.
* `TooManyApprovals` -- when `MaxApprovals` limit is hit, and cannot add a new proposal to the storage.
**Events:**
* `SpendApproved(proposal_index, amount, beneficiary)`
[.contract-item]
[[spend]]
==== `[.contract-item-name]#++spend++#`
[source,rust]
----
pub fn spend(
origin: OriginFor<T>,
asset_kind: Box<T::AssetKind>,
amount: AssetBalanceOf<T, I>,
beneficiary: Box<<<T as Config<I>>::BeneficiaryLookup as StaticLookup>::Source>,
valid_from: Option<BlockNumberFor<T>>
) -> DispatchResult
----
Propose and approve a spend of treasury funds, allows spending any asset kind managed by the treasury.
NOTE: The behavior and the API of the previous version of this function is kept the same and renamed to `spend_local`. The new feature `valid_from` is not added to `spend_local` for backward compatibility.
**Params:**
* `origin: OriginFor<T>` -- Must be [`Config::SpendOrigin`] with the `Success` value being at least `amount`.
* `asset_kind: Box<T::AssetKind>` -- An indicator of the specific asset class to be spent.
* `value: BalanceOf<T, I>` -- The amount to be transferred from the treasury to the `beneficiary`.
* `beneficiary: AccountIdLookupOf<T>` -- The destination account for the transfer.
* `valid_from: Option<BlockNumberFor<T>>` -- The block number from which the spend can be claimed. It can refer to the past if the resulting spend has not yet expired according to the [`Config::PayoutPeriod`]. If `None`, the spend can be claimed immediately after approval.
**Errors:**
* `InsufficientPermission` -- if the amount to be spent is greater than what the dispatcher of this call is allowed to spend.
* `SpendExpired` -- if expiration date is older than now.
* `FailedToConvertBalance` -- when conversion between `asset_kind` and `native currency` fails.
**Events:**
* `AssetSpendApproved(index, asset_kind, amount, beneficiary, valid_from, expire_at)` -- `index` is the index of the proposal. Rest is self-explanatory.
[.contract-item]
[[remove_approval]]
==== `[.contract-item-name]#++remove_approval++#`
[source,rust]
----
pub fn remove_approval(
origin: OriginFor<T>,
proposal_id: ProposalIndex
) -> DispatchResult
----
Force a previously approved proposal to be removed from the approval queue.
**Params:**
* `origin: OriginFor<T>` -- Must be [Config::RejectOrigin].
* `proposal_id: ProposalIndex` -- The index of a proposal.
**Errors:**
* `ProposalNotApproved` -- The proposal does not exist in the approved proposals queue.
**Events:**
* `AssetSpendApproved(index, asset_kind, amount, beneficiary, valid_from, expire_at)` -- `index` is the index of the proposal. Rest is self-explanatory.
[.contract-item]
[[payout]]
==== `[.contract-item-name]#++payout++#`
[source,rust]
----
pub fn payout(origin: OriginFor<T>, index: SpendIndex) -> DispatchResult
----
Claims a spend.
Spends must be claimed within some temporal bounds. A spend may be claimed within one [`Config::PayoutPeriod`] from the `valid_from` block.
In case of a payout failure, the spend status must be updated with the `check_status` dispatchable before retrying with the current function.
**Params:**
* `origin: OriginFor<T>` -- Must be signed.
* `index: SpendIndex` -- The index of the spend.
**Errors:**
* `InvalidIndex` -- The spend could not be found.
* `EarlyPayout` -- The spend tried to be claimed before it became valid (see `valid_from` field).
* `SpendExpired` -- The spend tried to be claimed after it expired.
* `AlreadyAttempted` -- The same spend tried to be claimed before.
* `PayoutError` -- An error occurred during the payment, related to `Paymaster::pay` function.
**Events:**
* `Paid(index, payment_id)`
[.contract-item]
[[check_status]]
==== `[.contract-item-name]#++check_status++#`
[source,rust]
----
pub fn check_status(
origin: OriginFor<T>,
index: SpendIndex
) -> DispatchResultWithPostInfo
----
Check the status of the spend and remove it from the storage if processed.
**Params:**
* `origin: OriginFor<T>` -- Must be signed.
* `index: SpendIndex` -- The index of the spend.
**Errors:**
* `InvalidIndex` -- The spend could not be found.
* `NotAttempted` -- The payout was not attempted.
* `Inconclusive` -- The spend is still in progress.
**Events:**
* `SpendProcessed(index)` -- Spend is successfully processed.
* `PaymentFailed(index, payment_id)` -- The payout was failed, and can be retried again. This error also gives the `payment_id` info for further investigation.
[.contract-item]
[[void_spend]]
==== `[.contract-item-name]#++void_spend++#`
[source,rust]
----
pub fn void_spend(origin: OriginFor<T>, index: SpendIndex) -> DispatchResult
----
Void previously approved spend.
A spend void is only possible if the payout has not been attempted yet.
IMPORTANT: even if the payout is failed, it still counts towards an attempt, and cannot be voided at this point.
**Params:**
* `origin: OriginFor<T>` -- Must be [Config::RejectOrigin].
* `index: SpendIndex` -- The index of the spend.
**Errors:**
* `InvalidIndex` -- The spend could not be found.
* `AlreadyAttempted` -- The same spend tried to be claimed before.
**Events:**
* `AssetSpendVoided(index)`
== Important Mentions and FAQ's
You might have come across the below from official documentation or source-code:
* `propose_spend` will be removed in February 2024. Use spend instead.
* `reject_proposal` will be removed in February 2024. Use spend instead.
* `approve_proposal` will be removed in February 2024. Use spend instead.
The new `spend` dispatchable will not be able to solely `propose` or `approve` proposals separately, nor `reject` them.
After the deprecation update, `treasury` pezpallet no longer tracks `unapproved` proposals, but only approved ones.
The idea is to use the `treausry` pezpallet combined with some other pezpallet which will provide the functionality of tracking unapproved proposals (reject, approve, propose). For Polkadot it's OpenGov (referenda and conviction voting pezpallets).
docs/modules/ROOT/pages/pezpallets/xcm.adoc
+493
View File
@@ -0,0 +1,493 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= pezpallet_xcm
Branch/Release: `release-polkadot-v1.10.0`
Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/polkadot/xcm/pezpallet-xcm/src/lib.rs[{github-icon},role=heading-link]
== Purpose
`pezpallet-xcm` is responsible for filtering, routing, and executing incoming XCM.
== Config
* Pezpallet-specific origins:
** `AdminOrigin` -- The origin that is allowed to call privileged operations on the XCM pezpallet. Type must implement trait `EnsureOrigin`.
** `ExecuteXcmOrigin` -- Required origin for executing XCM messages, including the teleport functionality. If successful, it returns a `xref:glossary.adoc#multilocation[MultiLocation]` which exists as an interior location within this chain's XCM context. Type must implement trait `EnsureOrigin`.
** `SendXcmOrigin` -- Required origin for sending XCM messages. If successful, it resolves to `MultiLocation`. Type must implement trait `EnsureOrigin`.
* Pezpallet-specific ID types:
** `RemoteLockConsumerIdentifier` -- The ID type for local consumers of remote locks. The type must implement `Copy`.
* Pezpallet-specific handlers:
** `Currency` -- Lockable currency used in the pezpallet. Type must implement the trait `LockableCurrency`.
** `Weigher` -- Measures xref:glossary.adoc#weight[weight] consumed by XCM local execution. Type must implement the trait `WeightBounds`.
** `XcmExecutor` -- Means of executing XCM. Type must implement the trait `ExecuteXcm`.
** `XcmRouter` -- The type used to dispatch an XCM to its destination. Type must implement the trait `SendXcm`.
* Pezpallet-specific filters:
** `XcmExecuteFilter` -- XCM filter for which messages to be executed using `XcmExecutor` must pass. Type must implement trait `Contains<(MultiLocation, Xcm<<Self as Config>::RuntimeCall>)>`.
** `XcmReserveTransferFilter` -- XCM filter for which messages to be reserve-transferred using the dedicated extrinsic must pass.Type must implement the trait `Contains<(MultiLocation, Vec<MultiAsset>)>`.
** `XcmTeleportFilter` -- XCM filter for which messages to be teleported using the dedicated extrinsic must pass. Type must implement the trait `Contains<(MultiLocation, Vec<MultiAsset>)>`.
** `TrustedLockers` -- Returns whether or not the origin can be trusted for a specific asset. Type must implement `ContainsPair` where each pair is an `asset` and an `origin` thereby entrusting `origin` for operations relating to `asset`.
* Pezpallet-specific converters:
** `CurrencyMatcher` -- The `xref:glossary.adoc#multiasset[MultiAsset]` matcher for `Currency`. Type must implement the trait `MatchesFungible`.
** `SovereignAccountOf` -- How to get an `AccountId` value from a `MultiLocation`, useful for handling asset locks. Type must implement `ConvertLocation`.
* Pezpallet-specific constants:
** `VERSION_DISCOVERY_QUEUE_SIZE` -- `u32` measures the size of the version discovery queue. Typically set to `100`.
** `AdvertisedXcmVersion` -- The latest supported XCM version that this chain accepts. Type must implement the trait `Get<XcmVersion>`. Commonly set to `pezpallet_xcm::CurrentXcmVersion`.
** `MaxLockers` -- The maximum number of local XCM locks that a single account may have. Type must implement the trait `Get<u32>`.
** `MaxRemoteLockConsumers` -- The maximum number of consumers a single remote lock may have. Type must implement the trait `Get<u32>`.
** `UniversalLocation` -- This chain's Universal Location. Type must implement the trait `Get<InteriorMultiLocation>`.
* Common configs:
** `RuntimeEvent`
** `RuntimeCall`
** `RuntimeOrigin`
** `WeightInfo`
== Dispatchables
[.contract-item]
[[send]]
==== `[.contract-item-name]#++send++#`
[source,rust]
----
pub fn send(
origin: OriginFor<T>,
dest: Box<VersionedMultiLocation>,
message: Box<VersionedXcm<()>>,
)
----
WARNING: DEPRECATED. `send` will be removed after June 2024. Use `send_blob` instead.
* Deprecation explanation:
** `pezpallet-xcm` has a new pair of extrinsics, `execute_blob` and `send_blob`. These are meant to be used instead of `execute` and `send`, which are now deprecated and will be removed eventually. These new extrinsics just require you to input the encoded XCM.
** There's a new utility in PolkadotJS Apps for encoding XCMs you can use: https://polkadot.js.org/apps/#/utilities/xcm Just pass in the encoded XCM to the new extrinsics and you're done.
** The migration from the old extrinsic to the new is very simple. If you have your message `xcm: VersionedXcm<Call>`, then instead of passing in `Box::new(xcm)` to both `execute` and `send`, you would pass in `xcm.encode().try_into()` and handle the potential error of its encoded length being bigger than `MAX_XCM_ENCODED_SIZE`.
** `pezpallet-contracts` takes the XCM encoded now as well. It follows the same API as `execute_blob` and `send_blob`.
Send a versioned XCM `message` to the destination `dest`.
The origin must be `SendXcmOrigin` for this call.
**Params:**
- `dest: Box<VersionedMultiLocation>` — destination for the XCM
- `message: Box<VersionedXcm<()>>` — versioned XCM to be sent to the multilocation `dest`
**Errors:**
- `InvalidOrigin` — origin did not match `SendXcmOrigin`
- `BadVersion` — version for XCM not valid
**Events:**
- `Sent(origin, destination, message, message_id)` -- The versioned XCM `message` was sent from the `origin` to the `destination`.
[.contract-item]
[[execute]]
==== `[.contract-item-name]#++execute++#`
[source,rust]
----
pub fn execute(
origin: OriginFor<T>,
message: Box<VersionedXcm<<T as Config>::RuntimeCall>>,
max_weight: Weight,
)
----
WARNING: DEPRECATED. `execute` will be removed after June 2024. Use `execute_blob` instead.
* Deprecation explanation:
** `pezpallet-xcm` has a new pair of extrinsics, `execute_blob` and `send_blob`. These are meant to be used instead of `execute` and `send`, which are now deprecated and will be removed eventually. These new extrinsics just require you to input the encoded XCM.
** There's a new utility in PolkadotJS Apps for encoding XCMs you can use: https://polkadot.js.org/apps/#/utilities/xcm Just pass in the encoded XCM to the new extrinsics and you're done.
** The migration from the old extrinsic to the new is very simple. If you have your message `xcm: VersionedXcm<Call>`, then instead of passing in `Box::new(xcm)` to both `execute` and `send`, you would pass in `xcm.encode().try_into()` and handle the potential error of its encoded length being bigger than `MAX_XCM_ENCODED_SIZE`.
** `pezpallet-contracts` takes the XCM encoded now as well. It follows the same API as `execute_blob` and `send_blob`.
Execute an XCM message from a local, signed, origin.
The origin must be `ExecuteXcmOrigin` for this call.
NOTE: A successful return to this does NOT imply that the `msg` was executed successfully to completion; only that SOME of it was executed.
**Params:**
- `message: Box<VersionedXcm<T as Config::RuntimeCall>>` — versioned XCM to be executed
- `max_weight: Weight` -- No more than this amount of `Weight` will be consumed during this execution attempt.
**Errors:**
- `BadOrigin` —- origin did not match `ExecuteXcmOrigin`
- `BadVersion` —- version for XCM not valid
**Events:**
- `Attempted(outcome)` -- Indicates whether the `msg` was executed completely or only partially.
[.contract-item]
[[force_xcm_version]]
==== `[.contract-item-name]#++force_xcm_version++#`
[source,rust]
----
pub fn force_xcm_version(
origin: OriginFor<T>,
location: Box<MultiLocation>,
version: XcmVersion,
)
----
Set that a particular destination can be communicated with through a particular version of XCM.
The origin must be `AdminOrigin` for this call.
**Params:**
- `location: Box<MultiLocation>` —- The destination that is being described.
- `version: XcmVersion` -- The latest version of XCM that `location` supports.
**Errors:**
- `BadOrigin` — origin did not match `AdminOrigin`
**Events:**
- `Event::SupportedVersionChanged { location, version }` -- `location` was updated to support the latest version of XCM `version`
[.contract-item]
[[force_default_xcm_version]]
==== `[.contract-item-name]#++force_default_xcm_version++#`
[source,rust]
----
pub fn force_default_xcm_version(
origin: OriginFor<T>,
maybe_xcm_version: Option<XcmVersion>,
)
----
Set a safe XCM version (the version that XCM should be encoded with if the most recent version a destination can accept is unknown).
The origin must be `AdminOrigin` for this call.
**Params:**
- `maybe_xcm_version: Option<XcmVersion>` —- The default XCM encoding version, or `None` to disable.
**Errors:**
- `BadOrigin` — origin did not match `AdminOrigin`
**Events:**
None
[.contract-item]
[[force_subscribe_version_notify]]
==== `[.contract-item-name]#++force_subscribe_version_notify++#`
[source,rust]
----
pub fn force_subscribe_version_notify(
origin: OriginFor<T>,
location: Box<VersionedMultiLocation>,
)
----
Ask a location to notify us regarding their XCM version and any changes to it.
The origin must be `AdminOrigin` for this call.
**Params:**
- `location: Box<VersionedMultiLocation>`: The location to which we should subscribe for XCM version notifications.
**Errors:**
- `BadOrigin` — origin did not match `AdminOrigin`
**Events:**
None
[.contract-item]
[[force_unsubscribe_version_notify]]
==== `[.contract-item-name]#++force_unsubscribe_version_notify++#`
[source,rust]
----
pub fn force_unsubscribe_version_notify(
origin: OriginFor<T>,
location: Box<VersionedMultiLocation>,
)
----
Require that a particular destination should no longer notify us regarding any XCM version changes.
The origin must be `AdminOrigin` for this call.
**Params:**
- `location: Box<VersionedMultiLocation>`: The location from which we are but no longer wish to subscribe to XCM version notifications.
**Errors:**
- `BadOrigin` —- origin did not match `AdminOrigin`
- `NoSubscription` -- subscription not found to `location`
- `BadLocation` -- location not found
**Events:**
None
[.contract-item]
[[limited_reserve_transfer_assets]]
==== `[.contract-item-name]#++limited_reserve_transfer_assets++#`
[source,rust]
----
pub fn limited_reserve_transfer_assets(
origin: OriginFor<T>,
dest: Box<VersionedMultiLocation>,
beneficiary: Box<VersionedMultiLocation>,
assets: Box<VersionedMultiAssets>,
fee_asset_item: u32,
weight_limit: WeightLimit,
)
----
Transfer some assets from the local chain to the sovereign account of a destination chain and forward a notification XCM.
The origin must be `ExecuteXcmOrigin` for this call.
**Params:**
- `dest: Box<VersionedMultiLocation>` -- Destination context for the assets. Will typically be `X2(Parent, Parachain(..))` to send from parachain to parachain, or `X1(Parachain(..))` to send from relay to parachain.
- `beneficiary: Box<VersionedMultiLocation>` -- A beneficiary location for the assets in the context of `dest`. Willgenerally be an `AccountId32` value.
- `assets: Box<VersionedMultiAssets>` -- The assets to be withdrawn. This should include the assets used to pay the fee on the `dest` side.
- `fee_asset_item: u32` -- The index into `assets` of the item which should be used to pay fees.
- `weight_limit: WeightLimit` -- The remote-side weight limit, if any, for the XCM fee purchase.
**Errors:**
- `BadOrigin` —- origin did not match `ExecuteXcm`
- `BadVersion` -- `beneficiary` or `assets` have incorrect versioning
- `TooManyAssets` -- assets length exceeds MAX_ASSETS_FOR_TRANSFER which equals 2 in this code
**Events:**
- `Event::Attempted { outcome }` -- Attempted the reserve transfer with returned status `outcome`
[.contract-item]
[[limited_teleport_assets]]
==== `[.contract-item-name]#++limited_teleport_assets++#`
[source,rust]
----
pub fn limited_teleport_assets(
origin: OriginFor<T>,
dest: Box<VersionedMultiLocation>,
beneficiary: Box<VersionedMultiLocation>,
assets: Box<VersionedMultiAssets>,
fee_asset_item: u32,
weight_limit: WeightLimit,
)
----
Teleport some assets from the local chain to some destination chain.
Fee payment on the destination side is made from the asset in the `assets` vector of index `fee_asset_item`, up to enough to pay for `weight_limit` of weight. If more weight is needed than `weight_limit`, then the operation will fail and the assets send may be at risk.
The origin must be `ExecuteXcmOrigin` for this call.
**Params:**
- `dest: Box<VersionedMultiLocation>` -- Destination context for the assets. Will typically be `X2(Parent, Parachain(..))` to teleport from parachain to parachain, or `X1(Parachain(..))` to teleport from relay to parachain.
- `beneficiary: Box<VersionedMultiLocation>` -- A beneficiary location for the assets in the context of `dest`. Will generally be an `AccountId32` value.
- `assets: Box<VersionedMultiAssets>` -- The assets to be withdrawn. This should include the assets used to pay the fee on the `dest` side.
- `fee_asset_item: u32` -- The index into `assets` of the item which should be used to pay fees.
- `weight_limit: WeightLimit` -- The remote-side weight limit, if any, for the XCM fee purchase.
**Errors:**
- `BadOrigin` —- origin did not match `ExecuteXcm`
- `BadVersion` -- `beneficiary` or `assets` have incorrect versioning
- `TooManyAssets` -- assets length exceeds MAX_ASSETS_FOR_TRANSFER which equals 2 in this code
**Events:**
- `Event::Attempted { outcome }` -- Attempted the teleport status with returned status `outcome`
[.contract-item]
[[force_suspension]]
==== `[.contract-item-name]#++force_suspension++#`
[source,rust]
----
pub fn force_suspension(
origin: OriginFor<T>,
suspended: bool,
)
----
Set or unset the global suspension state of the XCM executor.
The origin must be `AdminOrigin` for this call.
**Params:**
- `suspended: bool` -- `true` to suspend, `false` to resume.
**Errors:**
None
**Events:**
None
[.contract-item]
[[transfer_assets]]
==== `[.contract-item-name]#++transfer_assets++#`
[source,rust]
----
pub fn transfer_assets(
origin: OriginFor<T>,
dest: Box<VersionedLocation>,
beneficiary: Box<VersionedLocation>,
assets: Box<VersionedAssets>,
fee_asset_item: u32,
weight_limit: WeightLimit,
)
----
Transfer some assets from the local chain to the destination chain through their local, destination or remote reserve, or through teleports.
**Params:**
- `dest: Box<VersionedLocation>` -- Destination context for the assets. Will typically be `X2(Parent, Parachain(..))` to send from parachain to parachain, or `X1(Parachain(..))` to send from relay to parachain.
- `beneficiary: Box<VersionedLocation>` -- A beneficiary location for the assets in the context of `dest`. Will generally be an `AccountId32` value.
- `assets`: The assets to be withdrawn. This should include the assets used to pay the fee on the `dest` (and possibly reserve) chains.
- `fee_asset_item: u32` -- The index into `assets` of the item which should be used to pay fees.
- `weight_limit: WeightLimit` -- The remote-side weight limit, if any, for the XCM fee purchase.
**Errors:**
* `BadOrigin` —- origin did not match `ExecuteXcmOrigin`.
* `BadVersion` -- v2/v3 conversion to v4 failed for `assets`, `dest`, or `beneficiary`.
* `TooManyAssets` -- `assets` contain more than `MAX_ASSETS_FOR_TRANSFER = 2` to transfer.
* `Empty` -- can be a number of different errors:
** `fee_asset_item` is not present in `assets`.
** some fungible asset in `assets` has a value of 0.
** fees or asset transfer type was not determined.
* `TooManyReserves` -- there are more than one transfer type for an asset.
* `InvalidAssetUnknownReserve` -- transfer type can not be determined for a given asset.
* `InvalidAssetUnsupportedReserve` -- asset or fees transfer type is remote reserve and asset and fees asset are different.
* `Filtered` -- can be a number of different errors:
** `XcmReserveTransferFilter` filtered the asset.
** `XcmTeleportFilter` filtered the asset
* `CannotReanchor` -- asset can't be reanchored.
* `CannotCheckOutTeleport` -- asset can't be teleported
* `UnweighableMessage` -- prepared XCM message had issues with weighing (i.e. more instructions than the limit).
* `LocalExecutionIncomplete` -- local execution of XCM message have failed.
* `FeesNotMet` -- unable to charge fees. See the error log of any node to see the details.
**Events:**
- `Sent(origin, destination, message, message_id)`
**Deprecated Extrinsics**:
- `teleport_assets` -- Use `limited_teleport_assets` instead.
- `reserve_transfer_assets` -- Use `limited_reserve_transfer_assets` instead.
[.contract-item]
[[claim_assets]]
==== `[.contract-item-name]#++claim_assets++#`
[source,rust]
----
pub fn claim_assets(
origin: OriginFor<T>,
assets: Box<VersionedAssets>,
beneficiary: Box<VersionedLocation>,
) -> DispatchResult
----
**Params:**
- `origin: OriginFor<T>` -- Must be signed.
- `assets: Box<VersionedAssets>` -- The exact assets that were trapped. Use the version to specify what version was the latest when they were trapped.
- `beneficiary: Box<VersionedLocation>` -- A beneficiary location for the assets in the context of `dest`. Will generally be an `AccountId32` value.
**Errors:**
* `BadOrigin` —- origin did not match `ExecuteXcmOrigin`.
* `BadVersion` -- v2/v3 conversion to v4 failed for `assets`, `dest`, or `beneficiary`.
* `UnweighableMessage` -- prepared XCM message had issues with weighing (i.e. more instructions than the limit).
* `LocalExecutionIncomplete` -- local execution of XCM message have failed.
**Events:**
None
[.contract-item]
[[execute_blob]]
==== `[.contract-item-name]#++execute_blob++#`
[source,rust]
----
pub fn execute_blob(
origin: OriginFor<T>,
encoded_message: BoundedVec<u8, MaxXcmEncodedSize>,
max_weight: Weight,
) -> DispatchResultWithPostInfo
----
Execute an XCM from a local, signed, origin.
**Params:**
- `origin: OriginFor<T>` -- Must be signed.
- `encoded_message: BoundedVec<u8, MaxXcmEncodedSize>` -- The message is passed in encoded. It needs to be decodable as a [`VersionedXcm`].
- `max_weight: Weight` -- No more than `max_weight` will be used in its attempted execution. If this is less than the maximum amount of weight that the message could take to be executed, then no execution attempt will be made.
**Errors:**
* `BadOrigin` —- origin did not match `ExecuteXcmOrigin`.
* `BadVersion` -- v2/v3 conversion to v4 failed for `assets`, `dest`, or `beneficiary`.
* `Filtered` -- can be a number of different errors:
* `LocalExecutionIncomplete` -- local execution of XCM message have failed.
* `UnableToDecode` -- unable to decode the XCM.
* `XcmTooLarge` -- XCM encoded length is larger than `MaxXcmEncodedSize`.
**Events:**
- `Attempted(outcome)` -- Indicates whether the `msg` was executed completely or only partially.
[.contract-item]
[[send_blob]]
==== `[.contract-item-name]#++send_blob++#`
[source,rust]
----
pub fn send_blob(
origin: OriginFor<T>,
dest: Box<VersionedLocation>,
encoded_message: BoundedVec<u8, MaxXcmEncodedSize>,
) -> DispatchResult
----
Send an XCM from a local, signed, origin.
**Params:**
- `origin: OriginFor<T>` -- Must be signed.
- `dest: Box<VersionedLocation>` -- The destination, `dest`, will receive this message with a `DescendOrigin` instruction that makes the origin of the message be the origin on this system.
- `encoded_message: BoundedVec<u8, MaxXcmEncodedSize>` -- The message is passed in encoded. It needs to be decodable as a [`VersionedXcm`].
**Errors:**
* `InvalidOrigin` -- origin did not match `SendXcmOrigin`
* `BadVersion` -- v2/v3 conversion to v4 failed for `assets`, `dest`, or `beneficiary`.
* `UnableToDecode` -- unable to decode the XCM.
* `FeesNotMet` -- unable to charge fees. See the error log of any node to see the details.
* `Unreachable` -- The desired destination was unreachable, generally because there is a no way of routing to it.
* `SendFailure` -- There was some other issue (i.e. not to do with routing) in sending the message. Perhaps a lack of space for buffering the message.
**Events:**
- `Sent(origin, destination, message, message_id)` -- The versioned XCM `message` was sent from the `origin` to the `destination`.
== More Reading
https://wiki.polkadot.network/docs/learn-xcm-usecases[Polkadot Wiki XCM Use Cases]
docs/modules/ROOT/pages/pezpallets/xcmp-queue.adoc
+132
View File
@@ -0,0 +1,132 @@
:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= cumulus_pezpallet_xcmp_queue
Branch/Release: `release-polkadot-v1.10.0`
== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/cumulus/pezpallets/xcmp-queue/src/lib.rs[{github-icon},role=heading-link]
== Purpose
Responsible for the Queues (both incoming and outgoing) for XCMP messages. This pezpallet does not actually receive or send messages. Its responsibility is to place the incoming and outgoing XCMP messages in their respective queues and manage these queues.
== Config
* Pezpallet-specific configs
** `ChannelInfo` -- Configures two functions `get_channel_status` and `get_channel_info` to provide information about channels (`ChannelStatus` and `ChannelInfo`).
** `VersionWrapper` -- Means of converting an `Xcm` into a `VersionedXcm`. Xcm's should be versioned in order to pass the validation.
** `XcmpQueue` -- Defines max length of an XCMP message, and how `enqueue_message` should behave.
** `MaxInboundSuspended` -- The maximum number of inbound XCMP channels that can be suspended simultaneously. Any further channel suspensions will fail and messages may get dropped without further notice. Choosing a high value (1000) is okay.
** `ControllerOrigin` -- The origin that is allowed to resume or suspend the XCMP queue.
** `ControllerOriginConverter` -- The conversion function used to attempt to convert an XCM `xref:glossary.adoc#multilocation[MultiLocation]` origin to a superuser origin. This is used for allowing the superuser's queue to send messages even to paused queues.
** `PriceForSiblingDelivery` -- The price for delivering an XCM to a sibling parachain destination.
* Common configs
** `RuntimeEvent` -- The overarching event type.
** `WeightInfo` -- The xref:glossary.adoc#weight[weight] information of this pezpallet.
== Dispatchables
[.contract-item]
[[suspend_xcm_execution]]
==== `[.contract-item-name]#++suspend_xcm_execution++#`
[source,rust]
----
pub fn suspend_xcm_execution(origin: OriginFor<T>) -> DispatchResult
----
Suspends all XCM executions for the XCMP queue.
IMPORTANT: `origin` must pass the `ControllerOrigin` check.
NOTE: this does not change the status of the in/out bound channels.
**Params:**
* `origin: OriginFor<T>` -- caller of the dispatchable
**Errors:**
* `AlreadySuspended` -- description of conditions, when this error happens
[.contract-item]
[[resume_xcm_execution]]
==== `[.contract-item-name]#++resume_xcm_execution++#`
[source,rust]
----
pub fn resume_xcm_execution(origin: OriginFor<T>) -> DispatchResult
----
Resumes all XCM executions for the XCMP queue.
IMPORTANT: `origin` must pass the `ControllerOrigin` check.
NOTE: this does not change the status of the in/out bound channels.
**Params:**
* `origin: OriginFor<T>` -- caller of the dispatchable
**Errors:**
* `AlreadyResumed` -- description of conditions, when this error happens
[.contract-item]
[[update_suspend_threshold]]
==== `[.contract-item-name]#++update_suspend_threshold++#`
[source,rust]
----
pub fn update_suspend_threshold(origin: OriginFor<T>, new: u32) -> DispatchResult
----
Overwrites the number of pages which must be in the queue for the other side to be told to suspend their sending.
IMPORTANT: `origin` must be root.
**Params:**
* `origin: OriginFor<T>` -- caller of the dispatchable
* `new: u32` -- new page threshold for suspend
[.contract-item]
[[update_drop_threshold]]
==== `[.contract-item-name]#++update_drop_threshold++#`
[source,rust]
----
pub fn update_drop_threshold(origin: OriginFor<T>, new: u32) -> DispatchResult
----
Overwrites the number of pages which must be in the queue after which we drop any further messages from the channel.
IMPORTANT: `origin` must be root.
**Params:**
* `origin: OriginFor<T>` -- caller of the dispatchable
* `new: u32` -- new page threshold for drop
[.contract-item]
[[update_resume_threshold]]
==== `[.contract-item-name]#++update_resume_threshold++#`
[source,rust]
----
pub fn update_resume_threshold(origin: OriginFor<T>, new: u32) -> DispatchResult
----
Overwrites the number of pages which the queue must be reduced to before it signals that message sending may recommence after it has been suspended.
IMPORTANT: `origin` must be root.
**Params:**
* `origin: OriginFor<T>` -- caller of the dispatchable
* `new: u32` -- new page threshold for resume
== Important Mentions and FAQ's
IMPORTANT: messages are not ordered when they are received, but they are ordered when they are sent. `Signal` messages are prioritized over `non-signal` messages.
Messages and signals are stored in different queues. When the messages to be sent are taken with `take_outbound_messages`, they will be ordered:
* if there are signals present for outbound messages that targeting a parachain, we will only send signals, not messages
* messages (that are not signals) won’t be ordered
NOTE: polkadot/xcm/src/v3 has `SendXcm` trait, which has 2 blank methods validate and deliver. For each router struct, one can implement `SendXcm` for it.
. `deliver` method take `destination` as a parameter, and calls `send_fragment` function with the target parachain id.
. `send_fragment` puts the message to the queue of the given parachain id.
** unlike it's name, `deliver` method does not actually delivers the message. It is calling `send_fragment`, which places a message fragment on the outgoing XCMP queue for recipient. So, `deliver` is only putting the message to the respective outgoing xcmp queue