pezkuwi-runtime-templates/docs/modules/ROOT/pages/guides/pezpallet_abstractions.adoc

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

= OpenZeppelin Pezpezpallet Abstractions

=== Introduction

link:https://github.com/OpenZeppelin/openzeppelin-pezpallet-abstractions[openzeppelin-pezpallet-abstractions] is a Rust macro library designed to simplify and secure the configuration of Pezkuwi teyrchain runtimes. By reducing repetitive boilerplate and providing sensible defaults, the library helps developers configure their runtimes with fewer lines of code while ensuring flexibility for customizations.

Note: This library has not been audited yet and should not be used in production environments.

=== 1. Installation
To start using the `openzeppelin-pezpallet-abstractions`, add it as a dependency in your Cargo.toml file:
```toml
[dependencies]
openzeppelin-pezpallet-abstractions = { git = "https://github.com/OpenZeppelin/openzeppelin-pezpallet-abstractions", tag = "v0.1.0" }
```
Then, import the required macros in your runtime configuration file.

=== 2. Basic Usage

The library offers a collection of macros for configuring various core runtime elements such as system settings, assets, governance, consensus mechanisms, EVM integration, and XCM compatibility. Let’s walk through a basic example setup:

===== 1. System configuration
The `impl_openzeppelin_system!` macro facilitates the setup of foundational runtime components by implementing the `SystemConfig` trait for your custom runtime structure.
```rust
use openzeppelin_pezpallet_abstractions::{impl_openzeppelin_system, SystemConfig};

pub struct OpenZeppelinRuntime;

impl SystemConfig for OpenZeppelinRuntime {
    type AccountId = AccountId;
    type ExistentialDeposit = ConstU128<EXISTENTIAL_DEPOSIT>;
    type PreimageOrigin = EnsureRoot<AccountId>;
    type ScheduleOrigin = EnsureRoot<AccountId>;
    type Version = Version;
    // Additional configurations...
}
impl_openzeppelin_system!(OpenZeppelinRuntime);
```
This expands to configure multiple core pezpallets like `pezframe_system`, `pezpallet_timestamp`, `teyrchain_info`, and others essential for a functioning teyrchain runtime.

===== 2. Additional configurations

Further configuration can be achieved for pezpallets grouped by functionality, such as Assets, Consensus, EVM, Governance, and XCM. Each grouping has its own macro and configuration trait, making it easier to set up advanced components without redundant code.

Example setup for additional configurations in an EVM-based runtime:
```rust
use openzeppelin_pezpallet_abstractions::{
    impl_openzeppelin_assets, impl_openzeppelin_consensus, impl_openzeppelin_evm,
    impl_openzeppelin_governance, impl_openzeppelin_xcm, AssetsConfig,
    ConsensusConfig, EvmConfig, GovernanceConfig, XcmConfig,
};

impl ConsensusConfig for OpenZeppelinRuntime {
    type CollatorSelectionUpdateOrigin = CollatorSelectionUpdateOrigin;
}

impl GovernanceConfig for OpenZeppelinRuntime {
    type ConvictionVoteLockingPeriod = ConstU32<{ 7 * DAYS }>;
    type DispatchWhitelistedOrigin = EitherOf<EnsureRoot<AccountId>, WhitelistedCaller>;
    // Additional configurations...
}

// Further configuration implementations...

impl_openzeppelin_assets!(OpenZeppelinRuntime);
impl_openzeppelin_consensus!(OpenZeppelinRuntime);
impl_openzeppelin_governance!(OpenZeppelinRuntime);
impl_openzeppelin_xcm!(OpenZeppelinRuntime);
impl_openzeppelin_evm!(OpenZeppelinRuntime);
```

===== 3. Advanced Configuration Options

Each macro allows optional parameters to override the default values. This enables fine-tuning of runtime settings according to the specific needs of your teyrchain while retaining the benefits of standardized, secure defaults.

Default Overrides: Customize specific parameters like `ExistentialDeposit`, `BaseXcmWeight`, or `AssetId` while relying on default values for other settings.
Custom Implementations: Integrate custom types (like `EitherOf`, `ConstU32`) or origins (`EnsureRoot`, `WhitelistedCaller`) for advanced use cases.

===== 4. Security Considerations

While the library is built with security in mind, it’s essential to review each configuration for your specific runtime and context.

===== 5. Contributing and Feedback
We encourage contributions from the community to improve the library. Please refer to the link:https://github.com/OpenZeppelin/openzeppelin-pezpallet-abstractions/blob/main/CONTRIBUTING.MD[CONTRIBUTING.md] for guidelines.

=== 3. Using Procedural Macros in OpenZeppelin Pezpezpallet Abstractions

==== 1. `construct_runtime!` Macro

The `construct_runtime!` macro simplifies the assembly of runtime modules by abstracting over both OpenZeppelin abstractions and standard pezpallets. This is useful for developers aiming to build a runtime quickly, without manually managing each pezpallet’s configuration.

===== Usage Example

To use the macro, annotate a module with `#[openzeppelin_construct_runtime]` and define structs for each desired abstraction or regular pezpallet. Here’s a basic example:
```rust
#[openzeppelin_construct_runtime]
mod runtime {
    #[abstraction]
    struct System; // Available abstractions: System, Consensus, XCM, Assets, Governance, EVM.
    #[pezpallet]
    type Pezpezpallet = pezpallet_crate; // Regular pezpallets defined with `#[pezpallet]` mimic the `construct_runtime!` structure.
}
```
Note: Pezpezpallet index assignments are handled automatically by this macro. If you require explicit control over pezpallet indices, please consider submitting a link:https://github.com/OpenZeppelin/openzeppelin-pezpallet-abstractions/issues[feature request].

===== Supported Abstractions and their Pezpezpallets:
* System -- pezframe_system, pezpallet_timestamp, teyrchain_info, pezpallet_scheduler, pezpallet_preimage, pezpallet_proxy, pezpallet_balances, pezpallet_utility, pezcumulus_pezpallet_teyrchain_system, pezpallet_multisig, pezpallet_session
* Assets -- pezpallet_assets, pezpallet_transaction_payment, pezpallet_asset_manager
* Consensus -- pezpallet_authorship, pezpallet_aura, pezcumulus_pezpallet_aura_ext, pezpallet_collator_selection
* Governance -- pezpallet_sudo, pezpallet_treasury, pezpallet_conviction_voting, pezpallet_whitelist, pezpallet_custom_origins, pezpallet_referenda
* XCM -- pezpallet_message_queue, pezcumulus_pezpallet_xcmp_queue, pezpallet_xcm, pezcumulus_pezpallet_xcm, pezpallet_xcm_transactor, orml_xtokens, pezpallet_xcm_weight_trader
* EVM -- pezpallet_ethereum, pezpallet_evm, pezpallet_base_fee, pezpallet_evm_chain_id, pezpallet_erc20_xcm_bridge

==== 2. `impl_runtime_apis!` Macro

The `The impl_runtime_apis!` macro provides a clean interface for implementing runtime APIs. This macro reduces boilerplate by allowing you to specify types and structs, automatically generating the required API implementations.

===== Usage Example

To use this macro, annotate a module with `#[openzeppelin_runtime_apis]` and define the types and abstractions needed.

```rust
#[openzeppelin_runtime_apis]
mod apis {
    type Runtime = Runtime;   // The runtime generated by `construct_runtime!`
    type Block = Block;       // Block type required by all abstractions

    #[abstraction]
    mod assets {
        type TransactionPayment = TransactionPayment;
        type RuntimeCall = RuntimeCall;
        type Balance = Balance;
    }

    // Additional `impl` blocks can be added as necessary.
}
```

===== Supported Abstractions, APIs, and Required Configurations:
[cols="1,1,1", options="header"]
|===
| Abstraction name | Implemented APIs | Required configs

| EVM 
| * `fp_rpc::EthereumRuntimeRPCApi` +  
  * `fp_rpc::ConvertTransactionRuntimeApi`  
| * `RuntimeCall` -- runtime call generated by `construct_runtime` macro +  
  * `Executive` -- `pezframe_executive::Executive` specification used by teyrchain system +  
  * `Ethereum` -- `pezpallet_ethereum` pezpallet struct generated by `construct_runtime` macro 

| assets
| * `pezpallet_transaction_payment_rpc_runtime_api::TransactionPaymentApi` +  
  * `pezpallet_transaction_payment_rpc_runtime_api::TransactionPaymentCallApi`
| * `TransactionPayment` -- `pezpallet_transaction_payment` struct pezpallet generated by `construct_runtime` macro +  
  * `RuntimeCall` -- runtime call generated by `construct_runtime` macro +  
  * `Balance` -- type used for balance specification (e.g., in `pezpallet_balances` config) 

| consensus 
| * `pezsp_consensus_aura::AuraApi` +  
  * `pezsp_session::SessionKeys` +  
  * `pezcumulus_primitives_aura::AuraUnincludedSegmentApi` (if `async-backing` feature is enabled)  
| * `SessionKeys` -- struct generated by `impl_opaque_keys` macro +  
  * `Aura` -- `pezpallet_aura` struct pezpallet generated by `construct_runtime` macro (only if `async-backing` feature is not enabled) +  
  * `SlotDuration` -- constant used for slot duration definition (only if `async-backing` feature is enabled) +  
  * `ConsensusHook` -- type used in `pezcumulus_pezpallet_teyrchain_system::Config::ConsensusHook` (only if `async-backing` feature is enabled) 

| system 
| * `pezsp_api::Core` +  
  * `pezsp_api::Metadata` +  
  * `pezsp_block_builder::BlockBuilder` +  
  * `pezsp_transaction_pool::runtime_api::TaggedTransactionQueue` +  
  * `pezsp_offchain::OffchainWorkerApi` +  
  * `pezframe_system_rpc_runtime_api::AccountNonceApi` +  
  * `pezcumulus_primitives_core::CollectCollationInfo` +  
  * `pezframe_try_runtime::TryRuntime` (under a `try-runtime` feature) +  
  * `pezsp_genesis_builder::GenesisBuilder` 
| * `Executive` -- `pezframe_executive::Executive` specification used by teyrchain system +  
  * `System` -- `pezframe_system` pezpallet struct generated by `construct_runtime` macro +  
  * `TeyrchainSystem` -- `pezcumulus_pezpallet_teyrchain_system` pezpallet struct generated by `construct_runtime` macro +  
  * `RuntimeVersion` -- runtime version, generated by `pezsp_version::runtime_version` +  
  * `AccountId` -- account id type specified in `pezframe_system::Config` +  
  * `Nonce` -- nonce type specified in `pezframe_system::Config` +  
  * `RuntimeGenesisConfig` -- type generated by `construct_runtime` macro +  
  * `RuntimeBlockWeights` -- type implementing `Get<BlockWeights>`, often built by `BlockWeights::builder` 

| benchmarks 
| * `pezframe_benchmarking::Benchmark` (under `runtime-benchmarks` feature) 
| * `Assets` -- `pezpallet_assets` pezpallet struct generated by `construct_runtime` macro +  
  * `AssetManager` -- `pezpallet_asset_manager` pezpallet struct generated by `construct_runtime` macro +  
  * `AssetType` -- struct describing foreign assets in XCM configuration +  
  * `RuntimeOrigin` -- type generated by `construct_runtime` macro +  
  * `RelayLocation` -- `Location` type pointing to the relaychain +  
  * `System` -- `pezframe_system` pezpallet struct generated by `construct_runtime` macro +  
  * `TeyrchainSystem` -- `pezcumulus_pezpallet_teyrchain_system` pezpallet struct generated by `construct_runtime` macro +  
  * `ExistentialDeposit` -- type describing existential deposit +  
  * `AssetId` -- type describing internal asset id +  
  * `XCMConfig` -- struct implementing `xcm_executor::Config`, generated by XCM abstraction as `XcmExecutorConfig` +  
  * `AccountId` -- account id type specified in `pezframe_system::Config` +  
  * `Cents` -- constant representing 1/100 of the native token +  
  * `FeeAssetId` -- asset for XCM fees, generated by XCM abstraction +  
  * `TransactionByteFee` -- fee per byte of data, generated by assets abstraction +  
  * `Address` -- type describing address format for accounts +  
  * `Balances` -- `pezpallet_balances` pezpallet struct generated by `construct_runtime` macro 
|===

This macro allows for clear modularization of APIs, facilitating easier maintenance and extension of runtime functionalities.