Crate pallet_example_basic

source ·
Expand description

Basic Example Pallet

The Example: A simple example of a FRAME pallet demonstrating concepts, APIs and structures common to most FRAME runtimes.

Run cargo doc --package pallet-example-basic --open to view this pallet’s documentation.

This pallet serves as an example and is not meant to be used in production.

Documentation Guidelines:

  • Documentation comments (i.e. /// comment) - should accompany pallet functions and be restricted to the pallet interface, not the internals of the pallet implementation. Only state inputs, outputs, and a brief description that mentions whether calling it requires root, but without repeating the source code details. Capitalize the first word of each documentation comment and end it with a full stop. See Generic example of annotating source code with documentation comments
  • Self-documenting code - Try to refactor code to be self-documenting.
  • Code comments - Supplement complex code with a brief explanation, not every line of code.
  • Identifiers - surround by backticks (i.e. INHERENT_IDENTIFIER, InherentType, u64)
  • Usage scenarios - should be simple doctests. The compiler should ensure they stay valid.
  • Extended tutorials - should be moved to external files and refer to.
  • Mandatory - include all of the sections/subsections where MUST is specified.
  • Optional - optionally include sections/subsections where CAN is specified.

Documentation Template:

Copy and paste this template from frame/examples/basic/src/lib.rs into file frame/<INSERT_CUSTOM_PALLET_NAME>/src/lib.rs of your own custom pallet and complete it.

// Add heading with custom pallet name

# <INSERT_CUSTOM_PALLET_NAME> Pallet


// Add simple description


// Include the following links that shows what trait needs to be implemented to use the pallet
// and the supported dispatchables that are documented in the Call enum.


    

  • [Config]
    • 

  • [Call]
    • 

  • [Pallet]
    • 



## Overview



// Short description of pallet’s purpose.
// Links to Traits that should be implemented.
// What this pallet is for.
// What functionality the pallet provides.
// When to use the pallet (use case examples).
// How it is used.
// Inputs it uses and the source of each input.
// Outputs it produces.




## Terminology


// Add terminology used in the custom pallet. Include concepts, storage items, or actions that
you think // deserve to be noted to give context to the rest of the documentation or pallet
usage. The author needs to // use some judgment about what is included. We don’t want a list of
every storage item nor types - the user // can go to the code for that. For example, “transfer
fee” is obvious and should not be included, but // “free balance” and “reserved balance” should
be noted to give context to the pallet. // Please do not link to outside resources. The
reference docs should be the ultimate source of truth.



## Goals


// Add goals that the custom pallet is designed to achieve.



### Scenarios



#### <INSERT_SCENARIO_NAME>


// Describe requirements prior to interacting with the custom pallet.
// Describe the process of interacting with the custom pallet for this scenario and public API
functions used.


## Interface


### Supported Origins


// What origins are used and supported in this pallet (root, signed, none)
// i.e. root when `ensure_root` used
// i.e. none when `ensure_none` used
// i.e. signed when `ensure_signed` used


`inherent` <INSERT_DESCRIPTION>




### Types


// Type aliases. Include any associated types and where the user would typically define them.


`ExampleType` <INSERT_DESCRIPTION>



// Reference documentation of aspects such as storageItems and dispatchable functions should
// only be included in the https://docs.rs Rustdocs for Substrate and not repeated in the
// README file.


### Dispatchable Functions



// A brief description of dispatchable functions and a link to the rustdoc with their actual
documentation.


// MUST have link to Call enum
// MUST have origin information included in function doc
// CAN have more info up to the user


### Public Functions



// A link to the rustdoc and any notes about usage in the pallet, not for specific functions.
// For example, in the Balances Pallet: “Note that when using the publicly exposed functions,
// you (the runtime developer) are responsible for implementing any necessary checks
// (e.g. that the sender is the signer) before calling a function that will affect storage.”



// It is up to the writer of the respective pallet (with respect to how much information to
provide).


#### Public Inspection functions - Immutable (getters)


// Insert a subheading for each getter function signature


##### `example_getter_name()`


// What it returns
// Why, when, and how often to call it
// When it could panic or error
// When safety issues to consider


#### Public Mutable functions (changing state)


// Insert a subheading for each setter function signature


##### `example_setter_name(origin, parameter_name: T::ExampleType)`


// What state it changes
// Why, when, and how often to call it
// When it could panic or error
// When safety issues to consider
// What parameter values are valid and why


### Storage Items


// Explain any storage items included in this pallet


### Digest Items


// Explain any digest items included in this pallet


### Inherent Data


// Explain what inherent data (if any) is defined in the pallet and any other related types


### Events:


// Insert events for this pallet if any


### Errors:


// Explain what generates errors


## Usage


// Insert 2-3 examples of usage and code snippets that show how to
// use <INSERT_CUSTOM_PALLET_NAME> Pallet in a custom pallet.


### Prerequisites


// Show how to include necessary imports for <INSERT_CUSTOM_PALLET_NAME> and derive
// your pallet configuration trait with the INSERT_CUSTOM_PALLET_NAME trait.


```rust
use <INSERT_CUSTOM_PALLET_NAME>;


pub trait Config: <INSERT_CUSTOM_PALLET_NAME>::Config { }
```


### Simple Code Snippet


// Show a simple example (e.g. how to query a public getter function of
<INSERT_CUSTOM_PALLET_NAME>)


### Example from FRAME


// Show a usage example in an actual runtime


// See:
// - Substrate TCR https://github.com/parity-samples/substrate-tcr
// - Substrate Kitties https://shawntabrizi.github.io/substrate-collectables-workshop/#/


## Genesis Config



## Dependencies


// Dependencies on other FRAME pallets and the genesis config should be mentioned,
// but not the Rust Standard Library.
// Genesis configuration modifications that may be made to incorporate this pallet
// Interaction with other pallets



## Related Pallets


// Interaction with other pallets in the form of a bullet point list


## References



// Links to reference material, if applicable. For example, Phragmen, W3F research, etc.
// that the implementation is based on.

Re-exports

Modules

  • pallet
    The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
  • weights
    Autogenerated weights for pallet_example_basic

Structs

  • WatchDummy
    A simple signed extension that checks for the set_dummy call. In that case, it increases the priority and prints some log.