Skip to content

Commit a3abf5b

Browse files
wilwadeJoeCap08055
wilwade
and
JoeCap08055
authored
MSA Pallet Docs (#1962)
# Goal The goal of this PR is to improve the documentation of the Pallets and make that documentation be able to be used on `docs.frequency.xyz`. Part of frequency-chain/docs#59 # Discussion - This is the first one, so it includes the needed documentation and templates as well. - Please suggest additional content that would be useful as well - Had a hard time getting it to look nice in both markdown and the rendered html. - Disabling soft wrap will help it look better - The idea was to keep rust specific things out of the readme and in the `lib.rs` # Testing - `make docs` - `open target/doc/pallet_msa/index.html` Co-authored-by: Joe Caputo <[email protected]>
1 parent e0a5242 commit a3abf5b

File tree

6 files changed

+156
-45
lines changed

6 files changed

+156
-45
lines changed

‎Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,7 @@ benchmarks-capacity:
197197

198198
.PHONY: docs
199199
docs:
200-
RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo doc --no-deps --features frequency
200+
RUSTC_BOOTSTRAP=1 RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo doc --no-deps --features frequency
201201

202202
# Cleans unused docker resources and artifacts
203203
.PHONY: docs

‎pallets/README.md

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,34 +2,33 @@
22

33
## Pallet Documentation Template
44

5+
- The pallet should have a `README.md` file in the root. See `README.template.md` for a template.
6+
- The Readme file should strictly follow the standard as the contents may be used elsewhere.
7+
- The Readme file _must only_ use full links so the links work where ever the content is used.
8+
- Any additional technical notes for Frequency developers may be placed in the docs after the Readme is included.
9+
10+
The standard documentation header for `lib.rs`:
11+
512
```rust
6-
//! # Pallet Name
713
//! Super short description
814
//!
15+
//! ## Quick Links
916
//! - [Configuration: `Config`](Config)
1017
//! - [Extrinsics: `Call`](Call)
1118
//! - [Runtime API: `PALLETRuntimeApi`](../pallet_PALLET_runtime_api/trait.PALLETRuntimeApi.html)
1219
//! - [Custom RPC API: `PALLETApiServer`](../pallet_PALLET_rpc/trait.PALLETApiServer.html)
1320
//! - [Event Enum: `Event`](Event)
1421
//! - [Error Enum: `Error`](Error)
15-
//!
16-
//! ## Overview
17-
//! What does this pallet do or provide?
18-
//!
19-
//! ## Terminology
20-
//! - **Term Here:** definition
21-
//! - **Term Here:** Some term duplication between pallets is fine
22-
//!
23-
//! ## Implementations
24-
//! (Beyond the standard, if any)
25-
//!
26-
//! - [`Trait`](../remember_to_use_links/when_outside_the_pallet/trait.TRAIT.html)
27-
//!
22+
#![doc = include_str!("../README.md")]
23+
//! Optional additional Rust developer documentation
2824
```
2925

26+
Feel free to add additional Rust developer documentation after the Readme.
27+
3028
## Add Documentation Lints
3129

3230
In these files:
31+
3332
- `src/lib.rs`
3433
- `src/runtime-api/src/lib.rs`
3534
- `src/rpc/src/lib.rs`

‎pallets/README.template.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# {Name} Pallet
2+
3+
{Short description of the pallet}
4+
5+
## Summary
6+
7+
{What does this pallet do?}
8+
9+
### {Key Concept}
10+
11+
{Description}
12+
13+
### Actions
14+
15+
The {Name} pallet provides for:
16+
17+
- {Feature}
18+
- {Feature}
19+
- {Feature}
20+
21+
## Interactions
22+
23+
### Extrinsics
24+
25+
| Name/Description | Caller | Payment | Key Events | Runtime Added |
26+
| -------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------- | ------------- |
27+
| `{extrinsic}`<br />{Description} | Tokens | Free | [`{Event}`](https://frequency-chain.github.io/frequency/{pallet_name}/pallet/enum.Event.html#variant.{Event}) | 1 |
28+
29+
See [Rust Docs](https://frequency-chain.github.io/frequency/{pallet_name}/pallet/struct.Pallet.html) for more details.
30+
31+
### State Queries
32+
33+
| Name | Description | Query | Runtime Added |
34+
| --------- | ------------------- | ------------------------ | ------------- |
35+
| {Query 1} | {Query Desctiption} | `{queryCallInCamelCase}` | 1 |
36+
37+
See the [Rust Docs](https://frequency-chain.github.io/frequency/{pallet_name}/pallet/storage_types/index.html) for additional state queries and details.
38+
39+
### RPCs
40+
41+
Note: May be restricted based on node settings and configuration.
42+
43+
| Name | Description | Call | Node Version |
44+
| ------- | ----------------- | ---------------------------------------------------------------------------------------------------- | ------------ |
45+
| {RPC 1} | {RPC Description} | [`checkDelegations`]({link to the ApiServer method on https://frequency-chain.github.io/frequency/}) | v1.0.0+ |
46+
47+
\* Must be enabled with off-chain indexing
48+
49+
See [Rust Docs]({link to the ApiServer on https://frequency-chain.github.io/frequency/}) for more details.

‎pallets/msa/README.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# MSA Pallet
2+
3+
The MSA Pallet provides functionality for handling Message Source Accounts.
4+
5+
## Summary
6+
7+
The Message Source Account (MSA) is the primary user account system on Frequency for Messages and Stateful Storage.
8+
All users on Frequency must have an MSA in order to:
9+
10+
1. Acquire a User Handle
11+
2. Delegate tasks to Providers (defining specific tasks for specific providers)
12+
3. Become a Provider so they may do Provider level tasks on their own behalf
13+
4. Have Message or Stateful Storage data
14+
15+
### MSA Id and Keys
16+
17+
Once a user creates an MSA, they are assigned an MSA Id, a unique number the time of creation with one or more keys attached for control.
18+
(A control key may only be attached to ONE MSA at any single point in time.)
19+
20+
### Actions
21+
22+
The MSA pallet provides for:
23+
24+
- Creating, reading, updating, and deleting operations for MSAs.
25+
- Managing delegation relationships for MSAs.
26+
- Managing keys associated with MSAs.
27+
28+
## Interactions
29+
30+
### Extrinsics
31+
32+
| Name/Description | Caller | Payment | Key Events | Runtime Added |
33+
| --------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
34+
| `add_public_key_to_msa`<br />Add MSA control key | MSA Control Key or Provider with Signature | Capacity or Tokens | [`PublicKeyAdded`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.PublicKeyAdded) | 1 |
35+
| `create`<br />Create new MSA | Token Account | Tokens | [`MsaCreated`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.MsaCreated) | 1 |
36+
| `create_provider`<br />Convert an MSA into a Provider | Testnet: Provider or Mainnet: Governance | Tokens | [`ProviderCreated`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.ProviderCreated) | 1 |
37+
| `create_provider_via_governance`<br />Convert an MSA into a Provider | Frequency Council | Tokens | [`ProviderCreated`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.ProviderCreated) | 12 |
38+
| `create_sponsored_account_with_delegation`<br />Create new MSA via Provider with a Delegation | Provider | Capacity or Tokens | [`MsaCreated`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.MsaCreated), [`DelegationGranted`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.DelegationGranted) | 1 |
39+
| `delete_msa_public_key`<br />Remove MSA control key | Delegator | Free | [`PublicKeyDeleted`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.PublicKeyDeleted) | 1 |
40+
| `grant_delegation`<br />Create or alter a delegation | Provider with Signature | Capacity | [`DelegationGranted`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.DelegationGranted) | 1 |
41+
| `propose_to_be_provider`<br />Request the council to convert an MSA to a Provider | Token Account | Tokens | [`Proposed`](https://paritytech.github.io/polkadot-sdk/master/pallet_collective/pallet/enum.Event.html#variant.Proposed) | 12 |
42+
| `retire_msa`<br />Remove all keys and mark the MSA as retired | Delegator | Free | [`PublicKeyDeleted`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.PublicKeyDeleted), [`MsaRetired`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.MsaRetired) | 18 |
43+
| `revoke_delegation_by_delegator`<br />Remove delegation | Delegator | Free | [`DelegationRevoked`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.DelegationRevoked) | 1 |
44+
| `revoke_delegation_by_provider`<br />Remove delegation | Provider | Free | [`DelegationRevoked`](https://frequency-chain.github.io/frequency/pallet_msa/pallet/enum.Event.html#variant.DelegationRevoked) | 1 |
45+
46+
See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_msa/pallet/struct.Pallet.html) for more details.
47+
48+
### State Queries
49+
50+
| Name | Description | Query | Runtime Added |
51+
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------- |
52+
| Get MSA Id | Returns the MSA Id connected to the given control key | `publicKeyToMsaId` | 1 |
53+
| Get Current Maximum MSA Id | Returns the maximum MSA Id in existence | `currentMsaIdentifierMaximum` | 1 |
54+
| Get Current Delegator to Provider | Returns the current relationship between the specified Delegator and specified Provider at the given block number | `delegatorAndProviderToDelegation` | 1 |
55+
| Get Public Key Count for MSA Id | Returns the number of public keys for the given MSA Id | `publicKeyCountforMsaId` | 1 |
56+
57+
See the [Rust Docs](https://frequency-chain.github.io/frequency/pallet_msa/pallet/storage_types/index.html) for additional state queries and details.
58+
59+
### RPCs
60+
61+
Note: May be restricted based on node settings and configuration.
62+
63+
| Name | Description | Call | Node Version |
64+
| ---------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ |
65+
| Check Delegations | Test a list of MSAs to see if they have delegated to the provider MSA | [`checkDelegations`](https://frequency-chain.github.io/frequency/pallet_msa_rpc/trait.MsaApiServer.html#tymethod.check_delegations) | v1.0.0+ |
66+
| Delegation Schema Grants | Fetch the list of Schema Ids that a delegator has granted to a provider | [`grantedSchemaIdsByMsaId`](https://frequency-chain.github.io/frequency/pallet_msa_rpc/trait.MsaApiServer.html#tymethod.get_granted_schemas_by_msa_id) | v1.0.0+ |
67+
| Get Control Keys by MSA Id\* | Fetch the list of current control keys for an MSA from the off-chain index | [`getKeysByMsaId`](https://frequency-chain.github.io/frequency/pallet_msa_rpc/trait.MsaApiServer.html#tymethod.get_keys_by_msa_id) | v1.10.0+ |
68+
69+
\* Must be enabled with off-chain indexing
70+
71+
See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_msa_rpc/trait.MsaApiServer.html) for more details.

‎pallets/msa/src/lib.rs

Lines changed: 6 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,13 @@
1-
//! # MSA Pallet
2-
//! The MSA pallet provides functionality for handling Message Source Accounts.
1+
//! Message Source Account Management
32
//!
3+
//! ## Quick Links
44
//! - [Configuration: `Config`](Config)
55
//! - [Extrinsics: `Call`](Call)
66
//! - [Runtime API: `MsaRuntimeApi`](../pallet_msa_runtime_api/trait.MsaRuntimeApi.html)
77
//! - [Custom RPC API: `MsaApiServer`](../pallet_msa_rpc/trait.MsaApiServer.html)
88
//! - [Event Enum: `Event`](Event)
99
//! - [Error Enum: `Error`](Error)
10-
//!
11-
//! ## Overview
12-
//!
13-
//! The Message Source Account (MSA) is an account that can be sponsored such that public keys attached to the account
14-
//! to control the MSA are not required to hold any balance, while still being able to control revocation of any delegation or control.
15-
//!
16-
//! The MSA is represented by an Id and has one or more public keys attached to it for control.
17-
//! The same public key may only be attached to ONE MSA at any single point in time.
18-
//!
19-
//! The MSA pallet provides functions for:
20-
//!
21-
//! - Creating, reading, updating, and deleting operations for MSAs.
22-
//! - Managing delegation relationships for MSAs.
23-
//! - Managing keys associated with MSA.
24-
//!
25-
//! ## Terminology
26-
//! * **MSA:** Message Source Account. A Source or Provider Account for Frequency Messages. It may or may not have `Capacity`. It must have at least one public key (`AccountId`) associated with it.
27-
//! An MSA is required for sending Capacity-based messages and for creating Delegations.
28-
//! * **MSA ID:** the ID number created for a new Message Source Account and associated with one or more Public Keys.
29-
//! * **MSA Public Key:** the keys that control the MSA, represented by Substrate `AccountId`.
30-
//! * **Delegator:** a Message Source Account that has provably delegated certain actions to a Provider, typically sending a `Message`
31-
//! * **Provider:** the Message Source Account that a Delegator has delegated specific actions to.
32-
//! * **Delegation:** A stored Delegator-Provider association between MSAs which permits the Provider to perform specific actions on the Delegator's behalf.
10+
#![doc = include_str!("../README.md")]
3311
//!
3412
//! ## Implementations
3513
//!
@@ -39,12 +17,10 @@
3917
//! - [`DelegationValidator`](../common_primitives/msa/trait.DelegationValidator.html): Functions for validating delegations.
4018
//! - [`SchemaGrantValidator`](../common_primitives/msa/trait.SchemaGrantValidator.html): Functions for validating schema grants.
4119
//!
42-
//! ### Assumptions
43-
//!
44-
//! * Total MSA keys should be less than the constant `Config::MSA::MaxPublicKeysPerMsa`.
45-
//! * Maximum schemas, for which provider has publishing rights, be less than `Config::MSA::MaxSchemaGrantsPerDelegation`
20+
//! ## Assumptions
4621
//!
47-
// Substrate macros are tripping the clippy::expect_used lint.
22+
//! - Total MSA keys should be less than the constant `Config::MSA::MaxPublicKeysPerMsa`.
23+
//! - Maximum schemas, for which any single provider has publishing rights on behalf of a single user, must be less than `Config::MSA::MaxSchemaGrantsPerDelegation`
4824
#![allow(clippy::expect_used)]
4925
#![cfg_attr(not(feature = "std"), no_std)]
5026
// Strong Documentation Lints

‎tools/scripts/show-runtime-version.sh

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/bin/sh
2+
3+
# Quick script to output the runtime spec_version at a particular commit.
4+
5+
# set -ex
6+
7+
if [[ -z "$1" ]]; then
8+
cat <<-EOF
9+
Usage: $0 <git commit sha>
10+
EOF
11+
12+
exit 1
13+
fi
14+
15+
(git cat-file -p "${1}:runtime/frequency/src/lib.rs" | grep "spec_version:") 2>/dev/null \
16+
|| (git cat-file -p "${1}:runtime/mrc/src/lib.rs" | grep "spec_version:" )

0 commit comments

Comments
 (0)