mirror of
https://github.com/pezkuwichain/pezkuwi-runtime-templates.git
synced 2026-04-22 02:07:55 +00:00
Nikita Khateev
@@ -4,3 +4,5 @@
|
||||
** xref:pallets/proxy.adoc[pallet_proxy]
|
||||
** xref:pallets/message-queue.adoc[pallet_message_queue]
|
||||
** xref:pallets/aura_ext.adoc[cumulus_aura_ext]
|
||||
** xref:pallets/collator-selection.adoc[collator_selection]
|
||||
** xref:pallets/parachain-system.adoc[parachain_system]
|
||||
|
||||
@@ -13,7 +13,7 @@ This pallet integrates parachain’s own block production mechanism (for example
|
||||
- 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/coderobe/release-polkadot-v1.3.0/cumulus/pallets/aura-ext[{github-icon},role=heading-link]
|
||||
== Configuration and Integration link:https://github.com/paritytech/polkadot-sdk/tree/release-polkadot-v1.3.0/cumulus/pallets/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:
|
||||
|
||||
|
||||
@@ -0,0 +1,197 @@
|
||||
: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.3.0`
|
||||
|
||||
== Purpose
|
||||
|
||||
This pallet is needed to manage the set of collators for each session and to provision the next session with the actual list of collators.
|
||||
|
||||
== Glossary
|
||||
|
||||
- _Collator_ — a node that gathers collation information and communicates it to relay chain to make a block.
|
||||
- _Pot_ — stake that will reward block authors. Block author will get half of the current stake.
|
||||
- _Candidate_ — a self-promoted collator, who deposited a candidacy bond to participate in collation process
|
||||
- _Candidacy Bond_ — fixed amount to deposit to become a collator
|
||||
- _Invulnerable_ — permissioned collator, that will always be part of the collation process.
|
||||
|
||||
== Config link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.3.0/cumulus/pallets/collator-selection/src/lib.rs#L118[{github-icon},role=heading-link]
|
||||
|
||||
* Pallet-specific configs
|
||||
** `UpdateOrigin` — defines the list of origins that are able to modify the settings of collators (e.g. set and remove list of invulnerables, desired candidates, candidacy bond). This type should implement the trait `EnsureOrigin`.
|
||||
** `PotId` — id of account that will hold a 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 link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.3.0/cumulus/pallets/collator-selection/src/lib.rs#L301[{github-icon},role=heading-link]
|
||||
|
||||
[.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)`
|
||||
@@ -0,0 +1,136 @@
|
||||
: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.3.0`
|
||||
|
||||
== Purpose
|
||||
|
||||
This pallet 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 collator
|
||||
|
||||
== Glossary
|
||||
|
||||
- _Validation Code_ — the runtime binary that runs in the parachain
|
||||
- _Validation Data_ — information passed from the relay chain to validate the next block
|
||||
- _(Aggregated) Unincluded Segment_ — sequence of blocks that were not yet included into the relay chain state transition
|
||||
|
||||
== Config link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.3.0/cumulus/pallets/parachain-system/src/lib.rs#L207[{github-icon},role=heading-link]
|
||||
|
||||
* Pallet-specific configs:
|
||||
** `OnSystemEvent` — a handler that will be called when new 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
|
||||
// it was added after 1.3.0. I am leaving it commented for the future updates
|
||||
// ** `DmpQueue` — a handler for the incoming *downward* messages from relay chain
|
||||
** `ReservedDmpWeight` — 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 overriden 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 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 pallets:
|
||||
** `RuntimeEvent`
|
||||
** `WeightInfo`
|
||||
|
||||
== Dispatchables link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.3.0/cumulus/pallets/parachain-system/src/lib.rs#L506[{github-icon},role=heading-link]
|
||||
|
||||
[.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
|
||||
|
||||
=== Pallet's workflow
|
||||
|
||||
* Block Initialization
|
||||
** Remove already processed 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
|
||||
Reference in New Issue
Block a user