Frequency Transaction Pallet Documentation Improvement

pallets/frequency-tx-payment/README.md

@@ -0,0 +1,55 @@
+# 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.
+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 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
+
+The Frequency Transaction pallet provides for:
+
+- Transacting using only Capacity
+
+## Interactions
+
+### Extrinsics
+
+| Name/Description                 | Caller        | Payment | Key Events                                                                                                    | Runtime Added |
+| -------------------------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ------------- |
+| `pay_with_capacity`<br />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`<br />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.

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)]