pezkuwi-runtime-templates/docs/modules/ROOT/pages/runtimes/generic.adoc

:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
= Generic Runtime

== Purpose

Generic Runtime Template is constructed with the purpose of providing the most generic template that is working out of the box.

The pezpallet list is constructed by the contributions of Parity, the community, and OpenZeppelin.

Our motivation for crafting the pezpallet list was to be as minimalistic as possible,
whilst preserving the most important pezpallets that are used in the Pezkuwi ecosystem.

We designed this template to be generic, so that it can be used as a starting point for any other project/template,
and we aim to base our future templates off of this one.

To demystify the hard concepts, we provided a documentation, in which you can find:

* Explanation of the pezpallets that are used in this template (purpose, terminology, configuration, dispatchables, etc.).
* General guides regarding this template.
* Runtime related guides.
* And miscellaneous topics.

== Configuration

=== System Support
.click to expand
[%collapsible]
====

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezframe_system/index.html#[pezframe_system] is responsible from creating the runtime, initializing the storage, and providing the base functionality for the runtime.

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezcumulus_pezpallet_teyrchain_system/index.html#[pezcumulus_pezpallet_teyrchain_system] handles low-level details of being a teyrchain.

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezpallet_timestamp/index.html#[pezpallet_timestamp] provides a way for consensus systems to set and check the onchain time.

* https://docs.rs/staging-teyrchain-info/latest/staging_teyrchain_info/index.html#[teyrchain_info] provides a way for teyrchains to report their teyrchain id and the relay chain block number.

* https://docs.rs/pezpallet-proxy/latest/pezpallet_proxy/#[pezpallet_proxy] enables delegation of rights to execute certain call types from one origin to another.

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezpallet_utility/index.html#[pezpallet_utility] contains two basic pieces of functionality:

** Batch dispatch: A stateless operation, allowing any origin to execute multiple calls in a single dispatch. This can be useful to amalgamate proposals, combining `set_code` with corresponding `set_storage`s, for efficient multiple payouts with just a single signature verify, or in combination with one of the other two dispatch functionality.
*** https://pezkuwichain.github.io/pezkuwi-sdk/master/pezpallet_utility/pezpallet/struct.Pezpezpallet.html#method.force_batch[force_batch]: Sends a batch of dispatch calls. Errors are allowed and won’t interrupt
*** https://pezkuwichain.github.io/pezkuwi-sdk/master/pezpallet_utility/pezpallet/struct.Pezpezpallet.html#method.batch[batch]: Sends a batch of dispatch calls. This will return `Ok` in all circumstances. To determine the success of the batch, an event is deposited. If a call failed and the batch was interrupted, then the `BatchInterrupted` event is deposited, along with the number of successful calls made and the error of the failed call. If all were successful, then the `BatchCompleted` event is deposited.
*** https://pezkuwichain.github.io/pezkuwi-sdk/master/pezpallet_utility/pezpallet/struct.Pezpezpallet.html#method.batch_all[batch_all]: Send a batch of dispatch calls and atomically execute them. The whole transaction will rollback and fail if any of the calls failed.
** Pseudonymal dispatch: A stateless operation, allowing a signed origin to execute a call from an alternative signed origin. Each account has 2 * 2**16 possible “pseudonyms” (alternative account IDs) and these can be stacked. This can be useful as a key management tool, where you need multiple distinct accounts (e.g. as controllers for many staking accounts), but where it’s perfectly fine to have each of them controlled by the same underlying keypair. Derivative accounts are, for the purposes of proxy filtering considered exactly the same as the origin and are thus hampered with the origin’s filters.

* https://docs.rs/pezpallet-multisig/latest/pezpallet_multisig/#[pezpallet_multisig] enables multi-signature operations in your runtime. This module 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.

* https://docs.rs/pezpallet-scheduler/latest/pezpallet_scheduler/#[pezpallet_scheduler] schedules runtime calls.

* https://docs.rs/pezpallet-preimage/latest/pezpallet_preimage/#[preimage] allows for the users and the runtime to store the preimage of a hash on chain. This can be used by other pezpallets for storing and managing large byte-blobs.

====

=== Monetary
.click to expand
[%collapsible]
====

* https://docs.rs/pezpallet-balances/latest/pezpallet_balances/#[pezpallet_balances] 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 locks.

* https://docs.rs/pezpallet-transaction-payment/latest/pezpallet_transaction_payment/#[pezpallet_transaction_payment] provides the basic logic needed to pay the absolute minimum amount needed for a transaction to be included. This includes:
** *base fee*: This is the minimum amount a user pays for a transaction. It is declared as a base *weight* in the runtime and converted to a fee using `WeightToFee`.
** *weight fee*: A fee proportional to amount of weight a transaction consumes.
** *length fee*: A fee proportional to the encoded length of the transaction.
** *tip*: An optional tip. Tip increases the priority of the transaction, giving it a higher chance to be included by the transaction queue.

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezpallet_assets/index.html#[pezpallet_assets] deals with sets of assets implementing fungible traits, via [fungibles] traits in a simple, secure manner. This pezpallet makes heavy use of concepts such as Holds and Freezes from the [pezframe_support::traits::fungible] traits, therefore you should read and understand those docs as a prerequisite to understanding this pezpallet.

* https://docs.rs/pezpallet-treasury/latest/pezpallet_treasury/#[pezpallet_treasury] provides a “pot” of funds that can be managed by stakeholders in the system and a structure for making spending proposals from this pot.

====

=== Governance
.click to expand
[%collapsible]
====

* https://docs.rs/pezpallet-sudo/latest/pezpallet_sudo/#[pezpallet_sudo] provides a way to execute privileged runtime calls using a specified sudo (“superuser do”) account.

* https://docs.rs/pezpallet-conviction-voting/latest/pezpallet_conviction_voting/#[pezpallet_conviction_voting] manages actual voting in polls

* https://docs.rs/pezpallet-referenda/latest/pezpallet_referenda/#[pezpallet_referenda] executes referenda. No voting logic is present here, and the Polling and PollStatus traits are used to allow the voting logic (likely in a pezpallet) to be utilized.

* https://github.com/OpenZeppelin/pezkuwi-runtime-templates/blob/main/evm-template/runtime/src/configs/governance/origins.rs#[pezpallet_custom_origins] allows custom origins for governance. // TODO: double check this, is it really our own pezpallet, or just copy paste?

* https://docs.rs/pezpallet-whitelist/latest/pezpallet_whitelist/index.html#[pezpallet_whitelist] allows some configurable origin: `Config::WhitelistOrigin` to whitelist some hash of a call, and allows another configurable origin: `Config::DispatchWhitelistedOrigin` to dispatch them with the root origin.


====

=== Collator support
.click to expand
[%collapsible]
====

* https://docs.rs/pezpallet-authorship/latest/pezpallet_authorship/#[pezpallet_authorship] provides authorship tracking for PEZFRAME runtimes. This tracks the current author of the block and recent uncles.

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezpallet_collator_selection/index.html#[pezpallet_collator_selection] - manages the collators of a teyrchain. **Collation is *not* a secure activity** and this pezpallet does not implement any game-theoretic mechanisms to meet BFT safety assumptions of the chosen set. This pezpallet can:
** set invulnerable candidates (fixed candidates)
** set desired candidates (ideal number of non-fixed)
** set candidacy bond
** remove invulnerability (turn candidate into not fixed)
** and many more (all related to collators)

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezpallet_session/index.html#[pezpallet_session] allows validators to manage their session keys, provides a function for changing the session length, and handles session rotation.

* https://docs.rs/pezpallet-aura/latest/pezpallet_aura/#[pezpallet_aura] extends Aura consensus by managing offline reporting. It can:
** get the current slot
** get the slot duration
** change and initialize authorities
** ensure the correctness of the state of this pezpallet

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezcumulus_pezpallet_aura_ext/index.html#[pezcumulus_pezpallet_aura_ext] extends the Bizinikiwi AuRa pezpallet to make it compatible with teyrchains. It provides the Pezpezpallet, the Config and the GenesisConfig.

====

=== XCM Helpers
.click to expand
[%collapsible]
====

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezcumulus_pezpallet_xcmp_queue/index.html#[pezcumulus_pezpallet_xcmp_queue] 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.

* https://docs.rs/pezpallet-xcm/6.0.0/pezpallet_xcm/#[pezpallet_xcm] is responsible for filtering, routing, and executing incoming XCM.

* https://pezkuwichain.github.io/pezkuwi-sdk/master/pezcumulus_pezpallet_xcm/index.html#[pezcumulus_pezpallet_xcm] is responsible from detecting and ensuring whether XCM's are coming from *Relay* or *Sibling* chain.

* https://docs.rs/pezpallet-message-queue/latest/pezpallet_message_queue/#[MessageQueue] provides generalized message queuing and processing capabilities on a per-queue basis for arbitrary use-cases.

====