From 1906ff6cab1417e657fbfd902659db19b327a6a5 Mon Sep 17 00:00:00 2001 From: Wil Wade Date: Fri, 31 May 2024 12:01:51 +0000 Subject: [PATCH 1/4] Capacity Pallet Documentation Improvements --- pallets/capacity/README.md | 59 +++++++++++++++++++++++++++++++++++++ pallets/capacity/src/lib.rs | 40 ++++++------------------- 2 files changed, 68 insertions(+), 31 deletions(-) create mode 100644 pallets/capacity/README.md diff --git a/pallets/capacity/README.md b/pallets/capacity/README.md new file mode 100644 index 0000000000..dd1e9d311e --- /dev/null +++ b/pallets/capacity/README.md @@ -0,0 +1,59 @@ +# Capacity Pallet + +Manages the staking and balances for Capacity, an alternative payment system on Frequency. + +## Summary + +Capacity is an alternative payment system for a subset of calls that renews each Epoch. +Tokens staked creates Capacity for a targeted Provider. +[Learn more about Capacity](https://docs.frequency.xyz/Tokenomics/ProviderIncentives.html#capacity-model). + +### Staking & Unstaking +Currently, the token to Capcity ratio is 50:1. +For example, if for a 5 token stake, a Provider would receive 0.1 Capacity. +Staking and unstaking effect available Capacity immediately. + +### Capacity Epoch + +A Capacity Epoch is the number of blocks before Capacity balances are able to be renewed. +The value is managed by Governance, but currently set to ~24 hours. + +### Thaw Period + +After unstaking, the tokens will still be frozen for a set amount of time before they are unencumbered and able to be transferred. +The `UnstakingThawPeriod` constant defines the number of Epochs that must pass before the tokens may be reclaimed for any use via `withdrawUnstaked()`. +Currently it is set to 30 Epochs or ~30 days after unstaking. + +### Actions + +The Capacity pallet provides for: + +- Staking to receive Capacity +- Unstaking & Thaw Period +- Capacity Epoch management + +## Interactions + +### Extrinsics + +| Name/Description | Caller | Payment | Key Events | Runtime Added | +| -------------------------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ------------- | +| `stake`
Lock tokens to gain Capacity | Token Account | Tokens | [`Staked`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.Staked) | 1 | +| `unstake`
Begin the process of unlocking tokens by unstaking currently staked tokens | Token Account | Tokens | [`UnStaked`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.UnStaked) | 1 | +| `withdraw_unstaked`
Compete the process of unlocking tokens staked by releasing locks on expired unlock chunks | Token Account | Tokens | [`StakeWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.StakeWithdrawn) | 1 | + +See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/struct.Pallet.html) for more details. + +### State Queries + +| Name | Description | Query | Runtime Added | +| --------- | ------------------- | ------------------------ | ------------- | +| Get Capacity Ledger | Returns the Capacity balance details for a Provider's MSA Id | `capacityLedger` | 1 | +| Get Current Epoch | Returns the current Capacity Epoch number | `currentEpoch` | 1 | +| Get Current Epoch Info | Returns information about the current Capacity Epoch such as what block it started | `currentEpochInfo` | 1 | +| Get Staking Account Ledger | Returns information about an account's current staking details | `stakingAccountLedger` | 1 | +| Staking Target Ledger | Returns information about an account's current staking details for a specific target Provider MSA Id | `stakingTargetLedger` | 1 | +| Get Unstake Information | Returns the information about an account's current unstaking details and the unlocking chunks | `unstakeUnlocks` | 1 | + + +See the [Rust Docs](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/storage_types/index.html) for additional state queries and details. diff --git a/pallets/capacity/src/lib.rs b/pallets/capacity/src/lib.rs index aafd3cbc0f..a9dae1a975 100644 --- a/pallets/capacity/src/lib.rs +++ b/pallets/capacity/src/lib.rs @@ -1,41 +1,19 @@ -//! # Capacity Pallet -//! The Capacity pallet provides functionality for staking tokens to the Frequency network. +//! Managages staking to the network for Capacity //! +//! ## Quick Links //! - [Configuration: `Config`](Config) //! - [Extrinsics: `Call`](Call) //! - [Event Enum: `Event`](Event) //! - [Error Enum: `Error`](Error) +#![doc = include_str!("../README.md")] //! -//! ## Overview -//! Capacity is a refillable resource that can be used to make transactions on the network. -//! Tokens may be staked to the network targeting a provider MSA account to which the network will grant Capacity. +//! ## Lazy Capacity Refill //! -//! The network generates Capacity based on a Capacity-generating function that considers usage and network congestion. -//! When token is staked, the targeted provider MSA receives the Capacity generated. -//! -//! This Capacity can be used to pay for transactions given that the key used to pay for those transactions have a minimum balance -//! of the existential deposit. -//! -//! The staked amount may be increased, targeting either the same or a different target to receive the newly generated Capacity. -//! As a result, every time the network is staked to, the staked tokens are locked until unstaked. -//! -//! Unstaking schedules some amount of token to be unlocked. Any amount up to the total staked amount may -//! be unstaked, however, there is a a limit on how many concurrently scheduled unstaking requests can exist. -//! After scheduling tokens to be unlocked, they must undergo a thaw period before being withdrawn. -//! -//! After thawing, the tokens may be withdrawn using the withdraw_unstaked extrinsic. -//! On success, the tokens are unlocked and free up space to submit more unstaking request. -//! -//! The Capacity pallet provides functions for: -//! -//! - staking and, updating, -//! -//! ## Terminology -//! * **Capacity:** A refillable and non-transferable resource that can be used to pay for transactions on the network. -//! * **Staker:** An account that stakes tokens to the Frequency network in exchange for Capacity. -//! * **Target** A provider MSA account that receives Capacity. -//! * **Epoch Period:** The length of an epoch in blocks, used for replenishment and thawing. -//! * **Replenishable:** The ability of a provider MSA account to be refilled with Capacity after an epoch period. +//! Capacity is refilled on an as needed basis. +//! Thus, the provider's capacity balance retains the information of the last epoch. +//! Upon use, if the last epoch is less than the current epoch, the balance is assumed to be the maximum as the reload "has" happened. +//! Thus, the first use of capacity in an epoch will update the last epoch number to match the current epoch. +//! If a provider does not use any capacity in an epoch, the provider's capacity balance information is never updated for that epoch. //! // Substrate macros are tripping the clippy::expect_used lint. #![allow(clippy::expect_used)] From dba0764486e379ca4d26e034c083c469afcd01f6 Mon Sep 17 00:00:00 2001 From: Wil Wade Date: Mon, 3 Jun 2024 12:10:11 +0000 Subject: [PATCH 2/4] PR Feedback addressed --- pallets/capacity/README.md | 12 ++++++------ pallets/capacity/src/lib.rs | 6 +++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/pallets/capacity/README.md b/pallets/capacity/README.md index dd1e9d311e..4901ba0386 100644 --- a/pallets/capacity/README.md +++ b/pallets/capacity/README.md @@ -5,18 +5,18 @@ Manages the staking and balances for Capacity, an alternative payment system on ## Summary Capacity is an alternative payment system for a subset of calls that renews each Epoch. -Tokens staked creates Capacity for a targeted Provider. +Tokens staked create Capacity for a targeted Provider. [Learn more about Capacity](https://docs.frequency.xyz/Tokenomics/ProviderIncentives.html#capacity-model). ### Staking & Unstaking Currently, the token to Capcity ratio is 50:1. -For example, if for a 5 token stake, a Provider would receive 0.1 Capacity. -Staking and unstaking effect available Capacity immediately. +For example, for a 5 token stake, a Provider would receive 0.1 Capacity. +Staking and unstaking affect available Capacity immediately. ### Capacity Epoch A Capacity Epoch is the number of blocks before Capacity balances are able to be renewed. -The value is managed by Governance, but currently set to ~24 hours. +The value is managed by Governance, and is currently set to ~24 hours. ### Thaw Period @@ -40,7 +40,7 @@ The Capacity pallet provides for: | -------------------------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ------------- | | `stake`
Lock tokens to gain Capacity | Token Account | Tokens | [`Staked`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.Staked) | 1 | | `unstake`
Begin the process of unlocking tokens by unstaking currently staked tokens | Token Account | Tokens | [`UnStaked`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.UnStaked) | 1 | -| `withdraw_unstaked`
Compete the process of unlocking tokens staked by releasing locks on expired unlock chunks | Token Account | Tokens | [`StakeWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.StakeWithdrawn) | 1 | +| `withdraw_unstaked`
Complete the process of unlocking tokens staked by releasing locks on expired unlock chunks | Token Account | Tokens | [`StakeWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.StakeWithdrawn) | 1 | See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/struct.Pallet.html) for more details. @@ -50,7 +50,7 @@ See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_capacity/pall | --------- | ------------------- | ------------------------ | ------------- | | Get Capacity Ledger | Returns the Capacity balance details for a Provider's MSA Id | `capacityLedger` | 1 | | Get Current Epoch | Returns the current Capacity Epoch number | `currentEpoch` | 1 | -| Get Current Epoch Info | Returns information about the current Capacity Epoch such as what block it started | `currentEpochInfo` | 1 | +| Get Current Epoch Info | Returns information about the current Capacity Epoch such as the starting block number | `currentEpochInfo` | 1 | | Get Staking Account Ledger | Returns information about an account's current staking details | `stakingAccountLedger` | 1 | | Staking Target Ledger | Returns information about an account's current staking details for a specific target Provider MSA Id | `stakingTargetLedger` | 1 | | Get Unstake Information | Returns the information about an account's current unstaking details and the unlocking chunks | `unstakeUnlocks` | 1 | diff --git a/pallets/capacity/src/lib.rs b/pallets/capacity/src/lib.rs index a9dae1a975..5b6b696e2f 100644 --- a/pallets/capacity/src/lib.rs +++ b/pallets/capacity/src/lib.rs @@ -11,9 +11,9 @@ //! //! Capacity is refilled on an as needed basis. //! Thus, the provider's capacity balance retains the information of the last epoch. -//! Upon use, if the last epoch is less than the current epoch, the balance is assumed to be the maximum as the reload "has" happened. -//! Thus, the first use of capacity in an epoch will update the last epoch number to match the current epoch. -//! If a provider does not use any capacity in an epoch, the provider's capacity balance information is never updated for that epoch. +//! Upon use, if the last Epoch is less than the current Epoch, the balance is assumed to be the maximum as the reload "has" happened. +//! Thus, the first use of Capacity in an Epoch will update the last Epoch number to match the current Epoch. +//! If a provider does not use any Capacity in an Epoch, the provider's capacity balance information is never updated for that Epoch. //! // Substrate macros are tripping the clippy::expect_used lint. #![allow(clippy::expect_used)] From d74595b722c80e9109c48c77f2e8a1cf992c4879 Mon Sep 17 00:00:00 2001 From: Wil Wade Date: Wed, 5 Jun 2024 09:59:12 -0400 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: V. Claire Olmstead <43625033+claireolmstead@users.noreply.github.com> Co-authored-by: Joe Caputo --- pallets/capacity/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pallets/capacity/README.md b/pallets/capacity/README.md index 4901ba0386..48d8eea598 100644 --- a/pallets/capacity/README.md +++ b/pallets/capacity/README.md @@ -1,6 +1,6 @@ # Capacity Pallet -Manages the staking and balances for Capacity, an alternative payment system on Frequency. +The Capacity Pallet manages the staking and balances for Capacity, an alternative payment system on Frequency. ## Summary @@ -9,14 +9,14 @@ Tokens staked create Capacity for a targeted Provider. [Learn more about Capacity](https://docs.frequency.xyz/Tokenomics/ProviderIncentives.html#capacity-model). ### Staking & Unstaking -Currently, the token to Capcity ratio is 50:1. +Currently, the token to Capacity ratio is 50:1. For example, for a 5 token stake, a Provider would receive 0.1 Capacity. Staking and unstaking affect available Capacity immediately. ### Capacity Epoch A Capacity Epoch is the number of blocks before Capacity balances are able to be renewed. -The value is managed by Governance, and is currently set to ~24 hours. +The value is managed by Governance, and is currently set to 7200 blocks (approximately 24 hours at the current average 12-second block time). ### Thaw Period @@ -26,7 +26,7 @@ Currently it is set to 30 Epochs or ~30 days after unstaking. ### Actions -The Capacity pallet provides for: +The Capacity Pallet provides for: - Staking to receive Capacity - Unstaking & Thaw Period @@ -38,7 +38,7 @@ The Capacity pallet provides for: | Name/Description | Caller | Payment | Key Events | Runtime Added | | -------------------------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ------------- | -| `stake`
Lock tokens to gain Capacity | Token Account | Tokens | [`Staked`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.Staked) | 1 | +| `stake`
Lock tokens to grant Capacity to a Provider | Token Account | Tokens | [`Staked`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.Staked) | 1 | | `unstake`
Begin the process of unlocking tokens by unstaking currently staked tokens | Token Account | Tokens | [`UnStaked`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.UnStaked) | 1 | | `withdraw_unstaked`
Complete the process of unlocking tokens staked by releasing locks on expired unlock chunks | Token Account | Tokens | [`StakeWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.StakeWithdrawn) | 1 | From 211cfbf2a9fb164db295ca75ff970222ef0a163b Mon Sep 17 00:00:00 2001 From: Wil Wade Date: Wed, 5 Jun 2024 15:49:57 -0400 Subject: [PATCH 4/4] Apply suggestions from code review --- pallets/capacity/README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/pallets/capacity/README.md b/pallets/capacity/README.md index 48d8eea598..83fb97678b 100644 --- a/pallets/capacity/README.md +++ b/pallets/capacity/README.md @@ -4,8 +4,10 @@ The Capacity Pallet manages the staking and balances for Capacity, an alternativ ## Summary -Capacity is an alternative payment system for a subset of calls that renews each Epoch. -Tokens staked create Capacity for a targeted Provider. +Capacity is an alternative to paying with tokens for a limited set of calls. +These Capacity eligible extrinsics are noted in each pallet's documentation with "Capacity" in the Payment column of the extrinsics section. +Tokens can be staked to generate Capacity for a targeted Provider. +The generated Capacity renews each [Epoch](#capacity-epoch). [Learn more about Capacity](https://docs.frequency.xyz/Tokenomics/ProviderIncentives.html#capacity-model). ### Staking & Unstaking @@ -15,8 +17,10 @@ Staking and unstaking affect available Capacity immediately. ### Capacity Epoch -A Capacity Epoch is the number of blocks before Capacity balances are able to be renewed. -The value is managed by Governance, and is currently set to 7200 blocks (approximately 24 hours at the current average 12-second block time). +A Capacity Epoch is a period consisting of a specific number of blocks, during which a Provider's utilization of network Capacity is capped at the amount of generated Capacity targeted to that Provider. +At the start of each new Epoch, the available Capacity is renewed for each Provider, regardless of how much they consumed in the prior Epoch. +The duration of a Capacity Epoch is determined by Governance, and is currently set to 7200 blocks. +With the current average block time of approximately 12 seconds, one Capacity Epoch lasts around 24 hours on Mainnet. ### Thaw Period