Messages Pallet Documentation Improvement

pallets/messages/README.md

@@ -0,0 +1,65 @@
+# Messages Pallet
+
+Stores block-indexed data for a Schema using `OnChain` or `IPFS` payload location.
+
+## Summary
+
+Messages stores metadata and message payload data for a set Schema.
+Message payloads are meant for streaming data, where when the message was sent is the focus.
+Discovery is via the `MessagesInBlock` on new blocks or requesting messages from a block.
+Retrieval is via RPC.
+
+### Metadata vs Payload
+
+Messages have both metadata and payloads.
+The payload should always match the data structure or the message is considered invalid.
+The metadata is the Block Number, Schema Id, and other data useful for discovering and organizing the payload information.
+
+### Payload Options
+
+- `IPFS`: Storage of the CID and length of the file on IPFS
+- `OnChain`: Storage of the entire payload data, usually for sub-256 byte payloads
+
+### Message Ordering
+
+Messages are ordered by block number, and within each block, they follow a specific order based on their transaction sequence within that block.
+This order is immutable.
+
+### Actions
+
+The Messages pallet provides for:
+
+- Adding messages for a given schema
+- Enabling the retrieval of messages for a given schema
+
+## Interactions
+
+### Extrinsics
+
+| Name/Description                                                                         | Caller   | Payment            | Key Events                                                                                                                        | Runtime Added |
+| ---------------------------------------------------------------------------------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `add_ipfs_message`<br />Add a message to a Schema with an `IPFS` payload location        | Provider | Capacity or Tokens | [`MessagesInBlock`](https://frequency-chain.github.io/frequency/pallet_messages/pallet/enum.Event.html#variant.MessagesInBlock)\* | 1             |
+| `add_onchain_message`<br />Add a message to a Schema with an `ON_CHAIN` payload location | Provider | Capacity or Tokens | [`MessagesInBlock`](https://frequency-chain.github.io/frequency/pallet_messages/pallet/enum.Event.html#variant.MessagesInBlock)\* | 1             |
+
+\* The `MessagesInBlock` may not occur more than once per block and does _not_ indicate which schema received messages.
+
+See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_messages/pallet/struct.Pallet.html) for more details.
+
+### State Queries
+
+| Name            | Description                                                                                                                   | Query        | Runtime Added |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- |
+| Get Messages v2 | _Suggested_: Use RPC instead of this storage directly. Storage for the messages by Block number, Schema Id, and Message Index | `messagesV2` | 61            |
+| Get Messages v1 | Removed in Runtime 60                                                                                                         | `messages`   | 1-60          |
+
+See the [Rust Docs](https://frequency-chain.github.io/frequency/pallet_messages/pallet/storage_types/index.html) for additional state queries and details.
+
+### RPCs
+
+Note: May be restricted based on node settings and configuration.
+
+| Name                      | Description                                                                                      | Call                                                                                                                                               | Node Version |
+| ------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| Get Messages by Schema Id | Fetch paginated messages for a specific Schema Id in the given block range for a given Schema Id | [`getBySchemaId`](https://frequency-chain.github.io/frequency/pallet_messages_rpc/trait.MessagesApiServer.html#tymethod.get_messages_by_schema_id) | v1.0.0+      |
+
+See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_messages_rpc/trait.MessagesApiServer.html) for more details.

pallets/messages/src/lib.rs

@@ -1,37 +1,13 @@
-//! # Messages pallet
-//! A pallet for storing messages.
+//! Stores messages for `IPFS` and `OnChain` Schema payload locations
 //!
+//! ## Quick Links
 //! - [Configuration: `Config`](Config)
 //! - [Extrinsics: `Call`](Call)
 //! - [Runtime API: `MessagesRuntimeApi`](../pallet_messages_runtime_api/trait.MessagesRuntimeApi.html)
 //! - [Custom RPC API: `MessagesApiServer`](../pallet_messages_rpc/trait.MessagesApiServer.html)
 //! - [Event Enum: `Event`](Event)
 //! - [Error Enum: `Error`](Error)
-//!
-//! ## Overview
-//!
-//! Messages allow for discovery of new content matching a given Schema.
-//! Each message MUST have either a provider or a validated source and provider.
-//! Message is the metadata of the source, order, schema for a payload or referenced payload.
-//!
-//! The Messages Pallet provides functions for:
-//!
-//! - Adding messages for a given schema.
-//! - Enabling retrieving messages for a given schema.
-//! - (FUTURE) Removing messages after expiration
-//!
-//! ## Terminology
-//!
-//! - **Message:** A message that matches a registered Schema (on-chain or off-chain).
-//! - **Payload:** The data in a `Message` that matches a `Schema`.
-//! - **MSA Id:** The 64 bit unsigned integer associated with an `Message Source Account`.
-//! - **MSA:** Message Source Account. A registered identifier with the [MSA pallet](../pallet_msa/index.html).
-//! - **Schema:** A registered data structure and the settings around it. (See [Schemas pallet](../pallet_schemas/index.html))
-//! - **Schema Id:** A U16 bit identifier for a schema stored on-chain.
-//!
-//! ## Implementations
-//! - None
-//!
+#![doc = include_str!("../README.md")]
 // Substrate macros are tripping the clippy::expect_used lint.
 #![allow(clippy::expect_used)]
 // Ensure we're `no_std` when compiling for Wasm.