Docs Update (#250)

* Updating the docs

* fix fmt

* suggestion

---------

Co-authored-by: Özgün Özerk <ozgunozerk.elo@gmail.com>

evm-template/runtime/src/configs/asset_config.rs

@@ -62,7 +62,8 @@ impl pallet_assets::Config for Runtime {
     type RemoveItemsLimit = RemoveItemsLimit;
     type RuntimeEvent = RuntimeEvent;
     type StringLimit = StringLimit;
-    type WeightInfo = weights::pallet_assets::WeightInfo<Runtime>; //FIXME: run & update
+    /// Rerun benchmarks if you are making changes to runtime configuration.
+    type WeightInfo = weights::pallet_assets::WeightInfo<Runtime>;
 }
 
 // Our AssetType. For now we only handle Xcm Assets
@@ -180,5 +181,6 @@ impl pallet_asset_manager::Config for Runtime {
     type ForeignAssetModifierOrigin = EnsureRoot<AccountId>;
     type ForeignAssetType = AssetType;
     type RuntimeEvent = RuntimeEvent;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_asset_manager::WeightInfo<Runtime>;
 }

evm-template/runtime/src/configs/governance/mod.rs

@@ -32,6 +32,7 @@ impl pallet_conviction_voting::Config for Runtime {
     type Polls = Referenda;
     type RuntimeEvent = RuntimeEvent;
     type VoteLockingPeriod = VoteLockingPeriod;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_conviction_voting::WeightInfo<Runtime>;
 }
 
@@ -47,6 +48,7 @@ impl pallet_whitelist::Config for Runtime {
     type Preimages = Preimage;
     type RuntimeCall = RuntimeCall;
     type RuntimeEvent = RuntimeEvent;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_whitelist::WeightInfo<Runtime>;
     type WhitelistOrigin = EnsureRoot<Self::AccountId>;
 }
@@ -74,5 +76,6 @@ impl pallet_referenda::Config for Runtime {
     type Tracks = tracks::TracksInfo;
     type UndecidingTimeout = UndecidingTimeout;
     type Votes = pallet_conviction_voting::VotesOf<Runtime>;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_referenda::WeightInfo<Runtime>;
 }

evm-template/runtime/src/configs/mod.rs

@@ -175,6 +175,7 @@ impl pallet_scheduler::Config for Runtime {
     type RuntimeEvent = RuntimeEvent;
     type RuntimeOrigin = RuntimeOrigin;
     type ScheduleOrigin = EnsureRoot<AccountId>;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_scheduler::WeightInfo<Runtime>;
 }
 
@@ -198,6 +199,7 @@ impl pallet_preimage::Config for Runtime {
     type Currency = Balances;
     type ManagerOrigin = EnsureRoot<AccountId>;
     type RuntimeEvent = RuntimeEvent;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_preimage::WeightInfo<Runtime>;
 }
 
@@ -209,6 +211,7 @@ impl pallet_timestamp::Config for Runtime {
     /// A timestamp: milliseconds since the unix epoch.
     type Moment = u64;
     type OnTimestampSet = Aura;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_timestamp::WeightInfo<Runtime>;
 }
 
@@ -283,6 +286,7 @@ impl pallet_proxy::Config for Runtime {
     type ProxyType = ProxyType;
     type RuntimeCall = RuntimeCall;
     type RuntimeEvent = RuntimeEvent;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_proxy::WeightInfo<Runtime>;
 }
 
@@ -308,6 +312,7 @@ impl pallet_balances::Config for Runtime {
     type RuntimeEvent = RuntimeEvent;
     type RuntimeFreezeReason = RuntimeFreezeReason;
     type RuntimeHoldReason = RuntimeHoldReason;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_balances::WeightInfo<Runtime>;
 }
 
@@ -318,6 +323,10 @@ parameter_types! {
 }
 
 impl pallet_transaction_payment::Config for Runtime {
+    /// There are two possible mechanisms available: slow and fast adjusting.
+    /// With slow adjusting fees stay almost constant in short periods of time, changing only in long term.
+    /// It may lead to long inclusion times during spikes, therefore tipping is enabled.
+    /// With fast adjusting fees change rapidly, but fixed for all users at each block (no tipping)
     type FeeMultiplierUpdate = SlowAdjustingFeeUpdate<Self>;
     type LengthToFee = ConstantMultiplier<Balance, TransactionByteFee>;
     type OnChargeTransaction = pallet_transaction_payment::CurrencyAdapter<Balances, ()>;
@@ -329,6 +338,7 @@ impl pallet_transaction_payment::Config for Runtime {
 impl pallet_sudo::Config for Runtime {
     type RuntimeCall = RuntimeCall;
     type RuntimeEvent = RuntimeEvent;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_sudo::WeightInfo<Runtime>;
 }
 
@@ -351,6 +361,7 @@ impl cumulus_pallet_parachain_system::Config for Runtime {
     type ReservedXcmpWeight = ReservedXcmpWeight;
     type RuntimeEvent = RuntimeEvent;
     type SelfParaId = parachain_info::Pallet<Runtime>;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::cumulus_pallet_parachain_system::WeightInfo<Runtime>;
     type XcmpMessageHandler = XcmpQueue;
 }
@@ -383,6 +394,7 @@ impl pallet_message_queue::Config for Runtime {
     type RuntimeEvent = RuntimeEvent;
     type ServiceWeight = MessageQueueServiceWeight;
     type Size = u32;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_message_queue::WeightInfo<Runtime>;
 }
 
@@ -401,9 +413,11 @@ impl cumulus_pallet_xcmp_queue::Config for Runtime {
     type ControllerOrigin = EnsureRoot<AccountId>;
     type ControllerOriginConverter = XcmOriginToTransactDispatchOrigin;
     type MaxInboundSuspended = MaxInboundSuspended;
+    /// Ensure that this value is not set to null (or NoPriceForMessageDelivery) to prevent spamming
     type PriceForSiblingDelivery = PriceForSiblingParachainDelivery;
     type RuntimeEvent = RuntimeEvent;
     type VersionWrapper = ();
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::cumulus_pallet_xcmp_queue::WeightInfo<Runtime>;
     // Enqueue XCMP messages from siblings for later processing.
     type XcmpQueue = TransformOrigin<MessageQueue, AggregateMessageOrigin, ParaId, ParaIdToSibling>;
@@ -424,6 +438,7 @@ impl pallet_multisig::Config for Runtime {
     type MaxSignatories = MaxSignatories;
     type RuntimeCall = RuntimeCall;
     type RuntimeEvent = RuntimeEvent;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_multisig::WeightInfo<Runtime>;
 }
 
@@ -447,6 +462,7 @@ impl pallet_session::Config for Runtime {
     type ValidatorId = <Self as frame_system::Config>::AccountId;
     // we don't have stash and controller, thus we don't need the convert as well.
     type ValidatorIdOf = pallet_collator_selection::IdentityCollator;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_session::WeightInfo<Runtime>;
 }
 
@@ -503,6 +519,7 @@ impl pallet_utility::Config for Runtime {
     type PalletsOrigin = OriginCaller;
     type RuntimeCall = RuntimeCall;
     type RuntimeEvent = RuntimeEvent;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_utility::WeightInfo<Runtime>;
 }
 
@@ -557,6 +574,7 @@ impl pallet_treasury::Config for Runtime {
     type SpendFunds = ();
     type SpendOrigin = TreasurySpender;
     type SpendPeriod = SpendPeriod;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_treasury::WeightInfo<Runtime>;
 }
 
@@ -572,7 +590,9 @@ impl pallet_ethereum::Config for Runtime {
 }
 
 parameter_types! {
+    /// Block gas limit is calculated with target for 75% of block capacity and ratio of maximum block weight and weight per gas
     pub BlockGasLimit: U256 = U256::from(NORMAL_DISPATCH_RATIO * MAXIMUM_BLOCK_WEIGHT.ref_time() / WEIGHT_PER_GAS);
+    /// To calculate ratio of Gas Limit to PoV size we take the BlockGasLimit we calculated before, and divide it on MAX_POV_SIZE
     pub GasLimitPovSizeRatio: u64 = BlockGasLimit::get().min(u64::MAX.into()).low_u64().saturating_div(cumulus_primitives_core::relay_chain::MAX_POV_SIZE as u64);
     pub PrecompilesValue: OpenZeppelinPrecompiles<Runtime> = OpenZeppelinPrecompiles::<_>::new();
     pub WeightPerGas: Weight = Weight::from_parts(WEIGHT_PER_GAS, 0);
@@ -598,6 +618,7 @@ impl pallet_evm::Config for Runtime {
     type RuntimeEvent = RuntimeEvent;
     type SuicideQuickClearLimit = SuicideQuickClearLimit;
     type Timestamp = Timestamp;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_evm::WeightInfo<Self>;
     type WeightPerGas = WeightPerGas;
     type WithdrawOrigin = EnsureAccountId20;

evm-template/runtime/src/configs/xcm_config.rs

@@ -203,6 +203,7 @@ impl xcm_executor::Config for XcmConfig {
     type AssetTrap = PolkadotXcm;
     type Barrier = Barrier;
     type CallDispatcher = RuntimeCall;
+    /// When changing this config, keep in mind, that you should collect fees.
     type FeeManager = XcmFeeManagerFromComponents<
         IsChildSystemParachain<primitives::Id>,
         XcmFeeToAccount<Self::AssetTransactor, AccountId, TreasuryAccount>,
@@ -210,6 +211,9 @@ impl xcm_executor::Config for XcmConfig {
     type HrmpChannelAcceptedHandler = ();
     type HrmpChannelClosingHandler = ();
     type HrmpNewChannelOpenRequestHandler = ();
+    /// Please, keep these two configs (`IsReserve` and `IsTeleporter`) mutually exclusive.
+    /// The IsReserve type must be set to specify which <MultiAsset, MultiLocation> pair we trust to deposit reserve assets on our chain. We can also use the unit type () to block ReserveAssetDeposited instructions.
+    /// The IsTeleporter type must be set to specify which <MultiAsset, MultiLocation> pair we trust to teleport assets to our chain. We can also use the unit type () to block ReceiveTeleportedAssets instruction.
     type IsReserve = NativeAsset;
     type IsTeleporter = ();
     type MaxAssetsIntoHolding = MaxAssetsIntoHolding;
@@ -289,6 +293,7 @@ impl pallet_xcm::Config for Runtime {
     type TrustedLockers = ();
     type UniversalLocation = UniversalLocation;
     type Weigher = FixedWeightBounds<UnitWeightCost, RuntimeCall, MaxInstructions>;
+    /// Rerun benchmarks if you are making changes to runtime configuration.
     type WeightInfo = weights::pallet_xcm::WeightInfo<Runtime>;
     type XcmExecuteFilter = Nothing;
     // ^ Disable dispatchable execute on the XCM pallet.

evm-template/runtime/src/constants.rs

@@ -13,6 +13,11 @@ pub mod currency {
     pub const DOLLARS: Balance = 100 * CENTS;
     pub const GRAND: Balance = 1_000 * DOLLARS;
 
+    /// NB: Notice, that existential deposit was set to 0 intentionally to increase compatibility with EVM.
+    /// Hovewer, it leads to some risks, most importantly state bloating.
+    /// We acknowledge that there is such a risk and we have an opened issue to resolve it:
+    /// https://github.com/OpenZeppelin/polkadot-runtime-templates/issues/195
+    /// If you read this message please check out this issue to see if it is resolved and what can you do to implement the fix.
     #[cfg(not(feature = "runtime-benchmarks"))]
     pub const EXISTENTIAL_DEPOSIT: Balance = 0;