Expand description

MSA-centric Storage for [PayloadLocation::Paginated] and [PayloadLocation::Itemized]

§Stateful Storage Pallet

The Stateful Storage Pallet provides per-MSA functionality for reading and writing stateful data where only the latest state is relevant.

§Summary

When a Schema uses Paginated or Itemized, the payload data is stored in this pallet. Data stored is user-centric instead of time-centric as with the Messages Pallet. The pallet storage uses child storage making direct query access complex. Custom RPCs are provided for easy access to data.

§Paginated Data (PayloadLocation:Paginated)

Data is stored in multiple pages, each 1_024 bytes in size (as defined by constants::MaxPaginatedPageSizeBytes). Each page contains a single item of the associated schema. Page count is limited to 33 per Schema Id, though there may be holes in that range (limit defined by constants::MaxPaginatedPageId). This is most useful for schemas with a larger per-item size and smaller potential item count.

§Itemized Data (PayloadLocation:Itemized)

Data is stored in a single page with a max size of 10_240 bytes (defined by constants::MaxItemizedPageSizeBytes). The page contains multiple items of the associated schema. The maximum size of each items is 1_024 bytes (defined by constants::MaxItemizedBlobSizeBytes) . This is most useful for schemas with a relatively small item size and higher potential item count. The read and write complexity is O(n) when n is the number of bytes for all items.

§Actions

The Stateful Storage pallet provides for:

  • Per MSA and Schema storage of stateful data
  • Read/write access storage cost limited to a single MSA Id and Schema Id pair
  • A high write throughput
  • A high read throughput
  • Data race condition protection

§Interactions

§Extrinsics

Name/DescriptionCallerPaymentKey EventsRuntime Added
apply_item_actions
Applies a set of actions to an itemized storage array
Provider or MSA OwnerCapacity or TokensItemizedPageUpdated
ItemizedPageDeleted
22
apply_item_actions_with_signature_v2
Applies a set of actions to an itemized storage array with a signature authorization
Provider or MSA OwnerCapacity or TokensItemizedPageUpdated
ItemizedPageDeleted
45
upsert_page
Sets the data for a specific page index
Provider or MSA OwnerCapacity or TokensPaginatedPageUpdated22
delete_page
Deletes a specific page index
Provider or MSA OwnerCapacity or TokensPaginatedPageDeleted22
upsert_page_with_signature_v2
Sets the data for a specific page index with a signature authorization
Provider or MSA OwnerCapacity or TokensPaginatedPageUpdated46
delete_page_with_signature_v2
Deletes a specific page index with a signature authorization
Provider or MSA OwnerCapacity or TokensPaginatedPageDeleted46

See Rust Docs for more details.

§RPCs

Note: May be restricted based on node settings and configuration.

NameDescriptionCallNode Version
Get Paginated StorageRetrieves the paginated storage for the given MSA Id and Schema IdgetPaginatedStoragev1.4.0+
Get Itemized StorageRetrieves the itemized storage for the given MSA Id and Schema IdgetItemizedStoragev1.4.0+

See Rust Docs for more details.

§Terminology

  • Page: Block of on-chain data of a fixed size, which is the underlying type for Itemized and Paginated storage.
  • ItemizedPage: A page containing itemized data
  • PaginatedPage: A page containing paginated data

Re-exports§

Modules§

  • The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
  • Types for the Stateful Storage Pallet
  • Autogenerated weights for pallet_stateful_storage