From 1d5075fa65763bbd20a927bd8398f7db91ac1a09 Mon Sep 17 00:00:00 2001 From: Wil Wade Date: Fri, 24 May 2024 10:34:38 -0400 Subject: [PATCH 1/4] Frequency Transaction Pallet Documentation --- pallets/frequency-tx-payment/README.md | 54 +++++++++++++++++++++++++ pallets/frequency-tx-payment/src/lib.rs | 21 +++------- 2 files changed, 59 insertions(+), 16 deletions(-) create mode 100644 pallets/frequency-tx-payment/README.md diff --git a/pallets/frequency-tx-payment/README.md b/pallets/frequency-tx-payment/README.md new file mode 100644 index 0000000000..e9bc9f3f65 --- /dev/null +++ b/pallets/frequency-tx-payment/README.md @@ -0,0 +1,54 @@ +# Frequency Transaction Pallet + +Allows users to perform transactions using Capacity. + +## Summary + +Frequency supports the following alternative payments: + +- Capacity: A refillable resource limited to a subset of transactions. + +The Frequency Transaction Pallet proxies or nests one or more calls inside of the root call to enable them to be paid using an alternative method. +For example, to call something like `add_ipfs_message(params)` with Capacity, one would call `pay_with_capacity(add_ipfs_message(params))`. +The `pay_with_capacity` will verify that the inner call is allowed with capacity. + +### Requirements for Paying with Capacity + +The account must: +1. Be a current control key on a Provider. +2. Have a minimum balance of the existential deposit. + +### Capacity Stable Weights + +Capacity calls of the pallet also provide for stable capacity costs. +While the token cost can fluctuate with the change in benchmarks, the capacity cost remains relatively stable. +While these are updated from time to time, generally one may expect that if it takes x capacity to do a call, that exact same transaction will cost close to or less in a later update. + +### Actions + +The Frequency Transaction pallet provides for: + +- Transacting using only Capacity + +## Interactions + +### Extrinsics + +| Name/Description | Caller | Payment | Key Events | Runtime Added | +| -------------------------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ------------- | +| `pay_with_capacity`
Proxies a single capacity allowed call | Provider | Capacity | [`CapacityWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.CapacityWithdrawn)* | 1 | +| `pay_with_capacity_batch_all`
Proxies a batch (limit 10) of capacity allowed calls | Provider | Capacity | [`CapacityWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.CapacityWithdrawn)* | 1 | + +\* Note: This is just the event noting the use of Capacity. Additional events for the call being proxied will still occur. + +See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_frequency_tx_payment/pallet/struct.Pallet.html) for more details. + +### RPCs + +Note: May be restricted based on node settings and configuration. + +| Name | Description | Call | Node Version | +| ------- | ----------------- | ---------------------------------------------------------------------------------------------------- | ------------ | +| Compute Capacity Fee | Calculates the expected Capacity cost of the supplied transaction | [`computeCapacityFeeDetails`](https://frequency-chain.github.io/frequency/pallet_frequency_tx_payment_rpc/trait.CapacityPaymentApiServer.html#tymethod.compute_capacity_fee_details) | v1.8.0+ | + +See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_frequency_tx_payment_rpc/trait.CapacityPaymentApiServer.html) for more details. diff --git a/pallets/frequency-tx-payment/src/lib.rs b/pallets/frequency-tx-payment/src/lib.rs index f233dec315..0f802279da 100644 --- a/pallets/frequency-tx-payment/src/lib.rs +++ b/pallets/frequency-tx-payment/src/lib.rs @@ -1,24 +1,13 @@ -//! # Frequency-Transactions Pallet -//! The Frequency-transaction pallet allows users to transact using either capacity or token. +//! Allows transactions in alternative payment methods such as capacity //! +//! ## Quick Links //! - [Configuration: `Config`](Config) //! - [Extrinsics: `Call`](Call) +//! - [Runtime API: `CapacityTransactionPaymentRuntimeApi`](../pallet_frequency_tx_payment_runtime_api/trait.CapacityTransactionPaymentRuntimeApi.html) +//! - [Custom RPC API: `CapacityPaymentApiServer`](../pallet_frequency_tx_payment_rpc/trait.CapacityPaymentApiServer.html) //! - [Event Enum: `Event`](Event) //! - [Error Enum: `Error`](Error) -//! -//! ## Overview -//! Capacity is a refillable resource that can be used to make transactions on the network. -//! This pallets allows users to toggle between submitting transactions with capacity or tokens. -//! Note that tipping for capacity transactions is not allowed and is set to zero. Users who -//! use tokens to transact can continue to use a tip. -//! -//! The key that is used to pay with Capacity must have a minimum balance of the existential deposit. -//! -//! The Frequency-transaction pallet provides functions for: -//! -//! - pay_with_capacity -//! - +#![doc = include_str!("../README.md")] // Substrate macros are tripping the clippy::expect_used lint. #![allow(clippy::expect_used)] #![cfg_attr(not(feature = "std"), no_std)] From 2ac490a783080282b444de9a212661dd1c5e176b Mon Sep 17 00:00:00 2001 From: Wil Wade Date: Fri, 31 May 2024 16:35:56 +0000 Subject: [PATCH 2/4] Feedback --- pallets/frequency-tx-payment/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pallets/frequency-tx-payment/README.md b/pallets/frequency-tx-payment/README.md index e9bc9f3f65..efc871c755 100644 --- a/pallets/frequency-tx-payment/README.md +++ b/pallets/frequency-tx-payment/README.md @@ -20,9 +20,9 @@ The account must: ### Capacity Stable Weights -Capacity calls of the pallet also provide for stable capacity costs. -While the token cost can fluctuate with the change in benchmarks, the capacity cost remains relatively stable. -While these are updated from time to time, generally one may expect that if it takes x capacity to do a call, that exact same transaction will cost close to or less in a later update. +Token costs on a specific transaction can fluctuate due to benchmark changes, but the costs of capacity calls are setup to be relatively consistent. +This consistency is because the price of a capacity transaction is use a separate set of benchmark weights, which are kept constant at a given point in time. +While periodic updates do occur, the costs typically stay the same or may even decrease over time. ### Actions From 74df182d7266df5e755a5df12f632a21fc0d9aef Mon Sep 17 00:00:00 2001 From: Wil Wade Date: Fri, 31 May 2024 17:34:52 +0000 Subject: [PATCH 3/4] Feedback --- pallets/frequency-tx-payment/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/pallets/frequency-tx-payment/README.md b/pallets/frequency-tx-payment/README.md index efc871c755..0d788b83f1 100644 --- a/pallets/frequency-tx-payment/README.md +++ b/pallets/frequency-tx-payment/README.md @@ -17,6 +17,7 @@ The `pay_with_capacity` will verify that the inner call is allowed with capacity The account must: 1. Be a current control key on a Provider. 2. Have a minimum balance of the existential deposit. +3. Must have enough capacity for the call remaining in the current Epoch. ### Capacity Stable Weights From c9329c964decc8d420a82b301edcf1eddda75e91 Mon Sep 17 00:00:00 2001 From: Wil Wade Date: Mon, 3 Jun 2024 12:16:38 +0000 Subject: [PATCH 4/4] PR Feedback --- pallets/frequency-tx-payment/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pallets/frequency-tx-payment/README.md b/pallets/frequency-tx-payment/README.md index 0d788b83f1..e1ef84dea0 100644 --- a/pallets/frequency-tx-payment/README.md +++ b/pallets/frequency-tx-payment/README.md @@ -10,19 +10,19 @@ Frequency supports the following alternative payments: The Frequency Transaction Pallet proxies or nests one or more calls inside of the root call to enable them to be paid using an alternative method. For example, to call something like `add_ipfs_message(params)` with Capacity, one would call `pay_with_capacity(add_ipfs_message(params))`. -The `pay_with_capacity` will verify that the inner call is allowed with capacity. +The `pay_with_capacity` will verify that the inner call is allowed with Capacity. ### Requirements for Paying with Capacity The account must: 1. Be a current control key on a Provider. 2. Have a minimum balance of the existential deposit. -3. Must have enough capacity for the call remaining in the current Epoch. +3. Must have enough Capacity for the call remaining in the current Epoch. ### Capacity Stable Weights -Token costs on a specific transaction can fluctuate due to benchmark changes, but the costs of capacity calls are setup to be relatively consistent. -This consistency is because the price of a capacity transaction is use a separate set of benchmark weights, which are kept constant at a given point in time. +Token costs on a specific transaction can fluctuate due to benchmark changes, but the costs of Capacity calls are setup to be relatively consistent. +This consistency is because the price of a Capacity transaction uses a separate set of benchmark weights, which are kept constant at a given point in time. While periodic updates do occur, the costs typically stay the same or may even decrease over time. ### Actions @@ -37,8 +37,8 @@ The Frequency Transaction pallet provides for: | Name/Description | Caller | Payment | Key Events | Runtime Added | | -------------------------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ------------- | -| `pay_with_capacity`
Proxies a single capacity allowed call | Provider | Capacity | [`CapacityWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.CapacityWithdrawn)* | 1 | -| `pay_with_capacity_batch_all`
Proxies a batch (limit 10) of capacity allowed calls | Provider | Capacity | [`CapacityWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.CapacityWithdrawn)* | 1 | +| `pay_with_capacity`
Proxies a single Capacity allowed call | Provider | Capacity | [`CapacityWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.CapacityWithdrawn)* | 1 | +| `pay_with_capacity_batch_all`
Proxies a batch (limit 10) of Capacity allowed calls | Provider | Capacity | [`CapacityWithdrawn`](https://frequency-chain.github.io/frequency/pallet_capacity/pallet/enum.Event.html#variant.CapacityWithdrawn)* | 1 | \* Note: This is just the event noting the use of Capacity. Additional events for the call being proxied will still occur.