Learn to build on Polkadot with Figment Learn

Polkadot 101

Polkadot’s goal is to solve the interoperability problem: how to exchange assets across independent blockchains. With a sophisticated architecture made of a hundred parachains, a relay chain and bridges to the outside world, it’s not a Web 3 project for the faint of heart. Check out Substrate, its framework for bootstrapping your own blockchain.

Polkadot

< 1 hour

1 hour

1.5 hours

2 hours +

Beginner

Intermediate

JS/TS

Rust

On-chain Governance

Application specific chains

React

NodeJS

Smart contracts

AssemblyScript

Solidity

Next.js

Payment

Tools & Infra

Time Commitment

Difficulty

Programming Language

Feature

Technology

Learn how to add uniqueness to your Substrate Kitties

Substrate Kitties - Create Kitties

[The original tutorial can be found in Substrate's official documentation here. ](https://substrate.dev/docs/en/tutorials/create-a-pallet/)

# Install the Node Template

You should already have version `v3.0.0` of the [Substrate Node Template](https://github.com/substrate-developer-hub/substrate-node-template) compiled on your computer from when you completed the [Create Your First Substrate Chain Tutorial](https://substrate.dev/docs/en/tutorials/create-your-first-substrate-chain/). If you do not, please complete that tutorial.

> Experienced developers who truly prefer to skip that tutorial, you may install the node template according to the instructions in its readme.

# Starting with the Pallet Template

We're not going to write our pallet directly as part of the node template, but rather as a separate Rust crate. This approach allows us to publish our pallet separately from our node and also allows others to easily import this pallet into their own Substrate runtime. There are two ways to go about this:

## Option 1: `Use This Template` from Github

On the [template page](https://github.com/substrate-developer-hub/substrate-pallet-template) you will see a big green button that invites you to `Use This Template` - clicking this will open up a dialog similar to a fork, but will start you with a base repository that is close with only the code from the template in your new repo.

Clone this new repo you own locally **inside the node template `/pallets` directory**

```text
cd pallets
git clone <your new pallet repo> <pallet directory name>
```

> example:
> git clone git@github.com:substrate-developer-hub/substrate-pallet-template.git test-pallet

## Option 2: Clone a copy of the Template

Clone the Substrate pallet template in the `pallets` directory of your node template:

```text
cd pallets
git clone -b v3.0.0 --depth 1 https://github.com/substrate-developer-hub/substrate-pallet-template test-pallet
```

> In this tutorial we have placed the pallet template _inside_ the node template's directory structure. This pattern is not required, and you can place the pallet template anywhere you like. Another popular option would be as a _sibling_ to the node template.

# The Substrate Pallet Template

Let's explore the Substrate pallet template, starting with the `Cargo.toml` file.

## Renaming Your Crate

In the `Cargo.toml` file, you must update the crate's name. In this tutorial, we're focusing on how to create and use the pallet rather than writing interesting pallet logic. So let's update the value of the `package.name` attribute in the `Cargo.toml` file to `test-pallet`.

The `package` section of the `Cargo.toml` file now looks like:

**`pallets/test-pallet/Cargo.toml`**

```toml
[package]
authors = ['Substrate DevHub <https://github.com/substrate-developer-hub>']
description = 'FRAME pallet template'
edition = '2018'
homepage = 'https://substrate.dev'
license = 'Unlicensed'
name = 'test-pallet'
repository = 'https://github.com/substrate-developer-hub/substrate-pallet-template/'
version = '3.0.0'
```

## Compile the Template Pallet

You should be able to successfully check the Substrate pallet template with:

```text
cd test-pallet
SKIP_WASM_BUILD=1 cargo check
```

## Your Pallet's `std` Feature

In your `pallets/test-pallet/Cargo.toml` file, you will notice a few lines about the "`std` feature". In Rust, when you enable `std`, you give your project access to [the Rust standard libraries](https://doc.rust-lang.org/std/). This works just fine when building native binaries.

However, Substrate also builds the runtime code to WebAssembly $Wasm$. In this case we use cargo features to disable the Rust standard library. Thus, all the dependencies we use for our pallet, and our entire runtime, must be able to compile with [`no_std`](https://rust-embedded.github.io/book/intro/no-std.html) feature. Our `Cargo.toml` file tells our pallet's dependencies to only use their `std` feature when this pallet also uses its `std` feature, like so:

**`pallets/test-pallet/Cargo.toml`**

```text
[features]
default = ['std']
std = [
    'codec/std',
    'frame-support/std',
    'frame-system/std',
]
```

## Consistent Substrate dependencies

All Substrate pallets will depend on some low-level FRAME libraries such as `frame-system` and `frame-support`. These libraries are pulled from crates.io. When people build their own FRAME-based runtimes, they will also have dependencies on these low-level libraries. You will need to ensure consistent dependencies between your pallet and your runtime.

**`pallets/test-pallet/Cargo.toml`**

```toml
[dependencies]
frame-support = { default-features = false, version = '3.0.0' }
```

From the above snippet, we see that this pallet template depends on version `3.0.0` of the low-level libraries. Thus it can be used in runtimes that also depend on `3.0.0`.

> Note that substrate adheres to the [semver](https://semver.org/) standards - thus each release is on the form `major.minor.patch`. 
> In general it is _not_ expected that major releases are compatible! Thus if you are developing a pallet, or integrating ones, be sure to match versions to keep things all working correctly.

## Your Pallet's Dev Dependencies

The final section of the `Cargo.toml` file specifies the dev dependencies. These are the dependencies that are needed in your pallet's tests, but not the actual pallet itself.

**`pallets/test-pallet/Cargo.toml`**

```toml
[dev-dependencies]
sp-core = { default-features = false, version = '3.0.0' }
```

You can confirm that the tests in the Substrate pallet template pass with:

```text
SKIP_WASM_BUILD=1 cargo test
```

When updating this pallet to include your own custom logic, you will likely add dependencies of your own to this `Cargo.toml` file.

# Add Your Pallet to Your Node

With our pallet now compiling and passing it's tests, we're ready to add it to our node.

> If you aren't familiar with including and using other crates, refer to [the Cargo book](https://doc.rust-lang.org/cargo/guide/creating-a-new-project.html) for an in-depth explanation.

We first add our newly-created crate as a dependency in the node's runtime `Cargo.toml`. Then we tell the pallet to only build its `std` feature when the runtime itself does, as follows:

**`runtime/Cargo.toml`**

```toml
test-pallet = { path = '../pallets/test-pallet', default-features = false, version = '3.0.0' }

[features]
default = ['std']
std = [
    'test-pallet/std',
]
```

> You **must** set `default-features = false` so that your runtime will successfully compile to WASM.

Next we will update `runtime/src/lib.rs` to actually use our new runtime pallet, by adding a trait implementation with our `test_pallet` and add it in our `construct_runtime!` macro. Add the following code blocks:

**`runtime/src/lib.rs`**

```rust
// add this line (or modify all of these to your named pallet 
// corresponding to `test-pallet` in it's cargo.toml file)
pub use test_pallet;

// --snip--

// add this block
impl test_pallet::Config for Runtime {
  type Event = Event;
}

// --snip--
construct_runtime!(
  pub enum Runtime where
    Block = Block,
    NodeBlock = opaque::Block,
    UncheckedExtrinsic = UncheckedExtrinsic
  {
    // --snip--
    // add the following line
    TestPallet: test_pallet::{Module, Call, Storage, Event<T>},
  }
);
```

# Run Your Node

At this point you have the pallet packaged up as it's own crate and included in your node's runtime.

Make sure you're back in the node template's root directory, then compile the node and start in development mode with the following command:

```text
cargo build --release
./target/release/node-template --tmp --dev
```

Now, start the [Polkadot-JS Apps connecting to your local node](https://polkadot.js.org/apps/#/extrinsics?rpc=ws://127.0.0.1:9944) to confirm that the pallet is working as expected.

> **Note:** You can also manually set the node URL in Polkadot-JS Apps by navigating to the **Settings** tab, and have the **remote node/endpoint to connect to** set to **Local Node**.

Congrats! You have created and integrated a new pallet inside it's own create for your node! If you want to see a solution to get to this step [here is one to compare to](https://github.com/substrate-developer-hub/substrate-node-template/commit/eee6f630ad3305caa7d53819aae5db4a31ffe205) using FRAME v1 macros.

# Publish Your Pallet

Once your pallet is no longer in test phase, you should consider publishing it to GitHub or crates.io.

## Publishing on GitHub

To publish on GitHub, you need to [create a GitHub repository](https://help.github.com/en/articles/create-a-repo) and [push your pallet's code](https://help.github.com/en/articles/pushing-to-a-remote) to it.

## Publishing on Crates.io

Crates.io allows permissionless publishing. Learn the procedure following their own guide about [publishing on crates.io](https://doc.rust-lang.org/cargo/reference/publishing.html)

## Updating your Runtime's Dependency

With your pallet now published on GitHub, crates.io, or both, we can update your runtime to use the code that is published instead of a hard-coded file system path.

## Dependencies from GitHub

**`runtime/Cargo.toml`**

```toml
[dependencies.your-pallet-name]
default_features = false
git = 'https://github.com/your-username/your-pallet'
branch = 'master'
```

You may choose a specific commit or tag instead of branch, using: 
- rev = '<git-commit>'
- tag = '<some tag>

## Dependencies from Crates.io

**`runtime/Cargo.toml`**

```toml
[dependencies.your-pallet-name]
default_features = false
version = 'some-compatible-version'
```

Compile one more time and notice that Cargo now grabs your pallet from GitHub or crates.io instead of using the local files.

# Conclusion

Congratulations! You've written a Substrate pallet in its own Rust crate, and published it. Other blockchain developers can now easily use your pallet in their runtime by simply including those same four lines of code in their runtime's `Cargo.toml` files and updating their runtime's `lib.rs` file.


Learn how to write a Substrate pallet that lives in its own crate, and include it in a node based on the substrate-node-template

Write a Pallet in its Own Crate

# 🧩 DataHub API keys

To make use of the Pathway content, you will require a DataHub account and a valid API key to access Polkadot via DataHub's infrastructure.
You will need to [sign up for a DataHub account](https://auth.figment.io/sign_up) and verify your email address.

To use your API key you must create a new file named `.env.local` in the project root directory `/learn-web3-dapp/`, copying the contents of the existing `.env.example` file. Your API key needs to be pasted into `.env.local` so that you can authenticate your connections with DataHub.

Your personal API key can be found on the [**DataHub Services Dashboard**](https://datahub.figment.io/). Click on the **Polkadot** icon in the list of available protocols and then copy your key as shown below:

![](../../../.gitbook/assets/pathways/polkadot/polkadot-setup.gif)

You can then paste your personal API key into `.env.local`, as the value for the environment variable `DATAHUB_POLKADOT_API_KEY`. This will authenticate you and enable you to make RPC requests to Polkadot via DataHub:

![API keys](https://user-images.githubusercontent.com/2707197/136940513-e1f95d43-f107-43ab-8cc4-bd0485510dbc.png)

---------------------------

{% hint style="info" %}
[**Join us on Discord**](https://figment.io/devchat), if you encounter any issues with the tutorial or have any questions!
{% endhint %}


Let's setup the project to connect & interact with Polkadot

Setup the project

In this tutorial we will cover how to set up and utilize social recovery for a Polkadot proxy account

Implement Social Recovery on Polkadot

In this tutorial, we will be creating a Polkadot account on the Westend testnet and funding it with **WND** tokens by connecting to a chatroom which hosts a *faucet*, a means for us to request free tokens.

There are currently a few different ways to create a new account on Polkadot or a testnet like Westend:

* **Programmatically** (with code) using the Polkadot API *(covered in this tutorial)*
* **Through a web browser** by using the [Polkadot Apps Wallet](https://polkadot.js.org/apps/#/accounts) (*in some kind of hurry for a hackathon?*)
* **Through a terminal** by using [SubKey](https://wiki.polkadot.network/docs/en/learn-account-generation#subkey) (*advanced, will not be covered in this tutorial*)

We will be creating an account programmatically using the API, however you might find it useful to explore the other options depending on your needs.

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/polkadot/account.ts`, implement the function and try to create your first account on the polkadot network. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const keyring = new Keyring({ type: "sr25519" });

    // Create mnemonic string
    const mnemonic = undefined;

    const isValidMnemonic = mnemonicValidate(mnemonic);
    if (!isValidMnemonic) {
      throw Error('Invalid Mnemonic')
    }

    // Add an account derived from the mnemonic
    const account = undefined;
    const address = undefined;
    const jsonWallet = undefined;
    res.status(200).json({
      address,
      mnemonic,
      jsonWallet,
    });
  }
//...
```

**Need some help?** Check out these links
* [**Keyring Basics**](https://polkadot.js.org/docs/keyring/start/basics)  
* [**Using address or publicKey**](https://polkadot.js.org/docs/keyring/start/sign-verify#verify-using-address-or-publickey)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const keyring = new Keyring({ type: "sr25519" });

    // Create mnemonic string
    const mnemonic = mnemonicGenerate();
    console.log(`Generated mnemonic: ${mnemonic}`);

    const isValidMnemonic = mnemonicValidate(mnemonic);
    if (!isValidMnemonic) {
      throw Error('Invalid Mnemonic')
    }

    // Add an account derived from the mnemonic
    const account = keyring.addFromUri(mnemonic);
    const address = account.address;
    const jsonWallet = JSON.stringify(keyring.toJson(account.address), null, 2)
    res.status(200).json({
      address,
      mnemonic,
      jsonWallet,
    });
  }
//...
```

**What happened in the code above?**

* First, we create a new `Keyring` instance of the `sr25519` type - This type parameter only applies to the default type of account created when no type is specified, it does not mean that the keyring can only store that type of account.
* Next, we generate a new BIP39 mnemonic using the `mnemonicGenerate` method.
* Next, we check if the mnemonic is valid using the `mnemonicValidate` method.
* Next we create our account from the mnemonic and add it to the keyring using the `addFromUri` method.
* Then, we return:
  * The address of our account.
  * The mnemonic, so we can restore our account later.
  * A JSON representation of our Wallet.
* Finally, we send this data back to the client-side as JSON.

------------------------

# Make sure it works

Once the code is complete and the file is saved, Next.js will rebuild the API route. Now click on **Generate a Keypair** and you should see:

![](../../../.gitbook/assets/pathways/polkadot/polkadot-account.gif)

-----------------------------

# Conclusion

Now that we have created a Polkadot account and funded it with **WND** testnet tokens, let’s move on to querying a Polkadot node to check the current balance of our account!


In this tutorial, we'll learn how to create an account on the Polkadot blockchain

Create an account

# Introduction

This guide will focus on the lifecycle of Polkadot's parachains, an integral part of the Polkadot ecosystem. An end-user or developer will learn how parachains will operate, and ways they can participate in the parachain lifecycle - from backing a parachain candidate to considerations for developing a parachain and what to expect when it's time to deploy.

# Prerequisites

It is recommended that you are have gone through the [Polkadot Blockchain Terms](https://learn.figment.io/tutorials/polkadot-blockchain-terms) guide and are familiar with the following:

* Polkadot Behind the Code, [Episode 1](https://www.youtube.com/watch?v=GcOKXAOh4Xw)
* An understanding of Polkadot's architecture: [Polkadot: Are You Ready to Start Building?](https://www.youtube.com/watch?v=_-k0xkooSlA).
* [Getting Started with Polkadot](https://wiki.polkadot.network/docs/en/getting-started).
* Are comfortable with blockchain computing & networking terminology.

# Parachain Lifecycle

## Summary of Parachains

Parachains are essentially clients of the relay chain. The relay chain _relays_ information like a router. The parachain slots on the relay chain are similar to router ports. Parachain slots can also be thought of as servers with shared resources; there are only a limited number of parachain slots.

There may only be a few slots that are unlocked every few months. The current goal is to eventually have 100 parachain slots available on Polkadot.

This limitation in slots requires different methods of allocation, such as:

* [Parathreads](https://wiki.polkadot.network/docs/en/learn-parathreads)
* [Common good parachains](https://wiki.polkadot.network/docs/en/learn-parachains#common-good-parachains)
* [Auction granted parachains](https://wiki.polkadot.network/docs/en/learn-auction)

_A parachain takes the form of a blockchain, but they do not have to be an actual blockchain._

Parachains are maintained by a network maintainer known as a [_collator_](https://wiki.polkadot.network/docs/en/learn-collator).

Taking the case for one parachain:

* There would be a start of a new block candidate,  with a block creation time. 
* The collator would be at the end of the process, aggregating all the transactions. 
* The collator would then sign the parachain block candidate and produce state transition proofs, which are a summary of the final account balances caused by the transactions in the candidate block. 
* The collator then passes on the candidate block and state transition proofs to the validators. 
* The validators that are staking with the DOT token verify the transactions within the parachain block candidate. 
* If all is well, the validator will share the candidate block with the relay chain.
* Parachain block candidates are collected together and a relay chain block candidate is produced. \[3\]

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/polkadot-consensus-example-1.png)

* Then the validators on the network will try to reach a consensus on the relay chain block candidate. Upon reaching consensus, the now validated relay chain block candidate is shared with the validators and collators, and the process repeats for new transactions. \[3\]

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/polkadot-consensus-example-2.png)

## Parachain Slot Auction

Parachain slots are _**only for lease, not for sale**_.

Acquiring a parachain is done through an unpermissioned candle auction. A candle auction is similar to an open auction but does not have a known end time. In the 1600s and 1700s, a candle was lit at the beginning of the auction, and the auction expired as soon as the flame went out \[1\].

Bidders still submit increasingly higher bids, where the highest bidder at the end of the auction is considered the winner \[1\]. There are random parameters put in place to offer the candle auction via blockchain. These random parameters make it impossible for any bidders to determine when the auction will end. As such, this prevents bidders from attempting last-minute bids and general auction sniping. This way, all the parachains trying to bid know the states of the bids at play, but not when the auction ends, encouraging the parachains to place a bid as soon as they can.

Polkadot uses a random beacon based on the [Vickrey auction](https://en.wikipedia.org/wiki/Vickrey_auction) which provides the randomness.

Each slot lifecycle is **two years** and is divided into **four, 6 month lease periods.** _**An auction is for the right to occupy a parachain slot in each of four periods.**_ \[4\]

* Parachains can have their own local economies and their own form of governance. Chain autonomy is a focus for the Polkadot network.
  * Decisions in governance impact a chain's growth and development. 
  * Chains can reproduce in parallel while holding a parachain slot.
* The cost of leasing a parachain slot is based on the market supply and demand.
* The overall Polkadot community will determine which additional features and network upgrades should be added to the network over time via governance \[1\].

## Bidding

Individuals $individual\(s$ or team$s$ representing a parachain\) or smart contracts $which stem from parachains themselves$ can bid. Bidders can also be existing parachains looking to renew or extend their lease. If a slot auction is won, the winner does not need anyone’s permission to deploy their parachain. Parachain bids can be placed in the auction by specifying the slot range that they want to lease with the number of tokens they are willing to reserve. The token reservation is the act of placing a deposit of DOT token for fixed-term. The deposit is returned at the end of the parachain’s lease.

Bidders can be either ordinary accounts or use the crowdloan functionality to source tokens from the community. A crowdloan allows a team to crowdsource DOT tokens to bootstrap its parachain auction.

Individuals and teams need to prepare a strategy for their parachain that accounts for aspects of their parachain ecosystem before auctioning:

* Economics
* Governance
* Fundraising

Up until a parachain is successful in an auction, they are considered candidates.

## After a slot expires

* Parachains can eventually be deprecated on the network or decide to not re-auction once their slot lifecycle comes to an end.
* The parachain team could host another crowdloan.
* The parachain team may want to move to a pay-as-you-go model: [Parathreads](https://wiki.polkadot.network/docs/en/learn-parathreads).

# Decentralized Crowdloans

_**Anyone can create a new crowdloan campaign for a parachain slot.**_

A campaign is configured as a range of slots with a cap and a duration that can last over several auctions. Each campaign has an index. Anyone can participate by referencing the campaign's index via a special transaction.

The parachain team does not have any control over the contributed funds: all tokens contributed by a parachain’s supporters will be locked in the Relay Chain for the entire duration of the parachain slot. Many parachain teams will crowdsource the tokens from their community.

## Unsuccessful in Auctioning

* Projects that are unable to secure a parachain slot through auction should also consider deploying their parachain on Polkadot's canary network, [Kusama](https://kusama.network/). In fact, Kusama will roll out parachain auctions first for testing and optimization.

Kusama is an early, unaudited release of Polkadot's source code that was made available before Polkadot's initial release.
Kusama allows developers to experiment with new applications before releasing them onto the network. The network intends to be a testbed for new features and *radical* development. 
In the future, Kusama will also act as a parachain to the Polkadot network. The specs of the Kusama network are relatively the same as its cousin, Polkadot.

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/kusama.png)

* The candidate parachain can consider transforming their parachain into a parathread and use the pay-as-you-go model. The parathread model has a fixed registration fee. This registration fee _only registers_ the parathread's source code onto the relay chain. The parathread is required to pay a fee to participate in a per-block auction for inclusion in the verification of the next Relay Chain block \[2\].

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/parathread-parachain-diff.png)

_**Parachain registration does not grant the right to the parathread as the parathreads are competing on a per-block basis.**_

**Why consider becoming a Parathread**

* Test an idea. 
* Not enough resources for a fully functional application or blockchain. 
* Community requires growth. 
* If the candidate parachain focusses on a specific use-case such as identity management. 
* The network you would like to deploy has limited traffic and does not need full throughput.

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/parathreads-pay-as-you-go.png)

* Parachain candidates can also attempt to deploy their application on an existing parachain via smart contracts.
* Parachain candidates can connect to Polkadot via [bridging](https://wiki.polkadot.network/docs/en/learn-bridges) as a solo-chain.

# Conclusion

Congratulations! This guide offered a friendly overview of the lifecycle of a parachain.  
After reading the guide, an end-user or developer should be familiar with how parachains will operate on Polkadot, and the different ways that they can participate in the parachain lifecycle.

More information about the breakdown of Polkadot parachain slots and the Parachain lifecycle is available at:

* [Polkadot Parachain Slots Medium Article](https://medium.com/polkadot-network/polkadot-parachain-slots-f3f051d41699)
* [Parachain Slot Auctions Wiki Page](https://wiki.polkadot.network/docs/en/learn-auction)

Consider using Substrate to create your own parachain!

# About the Author
This guide was created by Danny Salman. You can reach out to Danny on [Figment Forum](https://community.figment.io/u/salman.danny03/) & on GitHub for help or if you have questions pertaining to Polkadot and this guide.

# References

\[1\] [Crust Network \| Explaining the Polkadot Parachain Slot Auction Mechanism](https://medium.com/crustnetwork/crust-network-explaining-the-polkadot-parachain-slot-auction-mechanism-533381d42607#:~:text=Rules%20of%20the%20Polkadot%20Parachain%20Slot%20Auction&text=Each%20slot%20is%20divided%20into,periods%20according%20to%20their%20needs.)  
\[2\] [Parathreads: Pay-as-you-go Parachains](https://polkadot.network/parathreads-parathreads-pay-as-you-go-parachains/)  
\[3\] [Polkadot — An Early In-Depth Analysis — Part Two — How Consensus Works](https://cryptoseq.medium.com/polkadot-an-early-in-depth-analysis-part-two-how-consensus-works-1b2b2f3a2245)  
\[4\] [Polkadot & Kusama Crowdloans and Parachain Auctions — Simplified](https://danreecer.medium.com/polkadot-kusama-crowdloans-and-parachain-auctions-simplified-da89a05cd566)



This guide will focus on the lifecycle of Polkadot's parachains, an integral part of the Polkadot ecosystem.

Parachain Lifecycle

# Introduction
In this tutorial, we will be building a custom pallet using the Substrate development framework and FRAME v1. We will start with an overview to understand pallets and the FRAME framework. We will then take a look at the Substrate pallet template, using it to build our custom pallet, write test cases, publish using git and finally add the published pallet to our runtime.

# Prerequisites
This tutorial assumes the reader is somewhat familiar with the Rust programming language and has a basic understanding of the Substrate framework.

# Pallets
Pallets are domain-specific runtime modules, which allow us to have a modular design. We can add multiple pallets to our runtime.

For reference, some of the most popular prebuilt pallets can be found [on the Substrate developer site](https://substrate.dev/docs/en/knowledgebase/runtime/frame#prebuilt-pallets).

## FRAME v1
FRAME is the framework used to develop pallets, it comes with set of libraries and modules to get us started. Following is the skeleton of a FRAME based pallet:
1. Imports and Dependencies

The pallet supports the use of any Rust library which compiles with the `no_std` flag.

``` rust
use support::{decl_module, decl_event, decl_storage, ...}
```

2. Runtime Config Trait

All of the runtime types and consts will go in here. If the pallet is dependent on other pallets, then their configuration traits should be added to the inherited traits list.

```rust
pub trait Config: frame_system::Config { ... }
```

3. Runtime Events

Events are a simple means of reporting specific events that have happened which users, dApps and/or block explorers would find interesting and otherwise would be difficult to detect.

Read more about [Runtime Events](https://substrate.dev/docs/en/knowledgebase/runtime/events)

```rust
decl_event! { ... }
```

4. Runtime Storage 

This allows for type-safe usage of the Substrate storage database, so you can keep things around between blocks.

Read more about [Runtime Storage](https://substrate.dev/docs/en/knowledgebase/runtime/storage)

```rust
decl_storage! { ... }
```

5. Runtime Errors

This is an enum that allows us to define custom error types which could be called from the runtime module.

```rust
decl_error! { ... }
```

6. Runtime Module 

This defines the `Module` struct that is ultimately exported from this pallet. It defines the callable functions that this pallet exposes and orchestrates actions this pallet takes throughout block execution.

```rust
decl_module! { ... }
```

We will now take a look at how to build our pallet within this framework.

[More details about FRAME](​​https://substrate.dev/docs/en/knowledgebase/runtime/frame)

# Using the Template Pallet
We can start off using the Substrate pallet template, which provides the starter code using Frame v1

Check out the [Substrate Pallet Template](https://github.com/substrate-developer-hub/substrate-pallet-template)

![](https://raw.githubusercontent.com/prasad-kumkar/pallet-identity/master/resources/1.png)


![](https://raw.githubusercontent.com/prasad-kumkar/pallet-identity/master/resources/2.png)

Now you can clone the generated repository onto your local machine by running the following command in your terminal:
```text
git clone https://github.com/<YOUR_GITHUB_USERNAME>/pallet-identity.git
```
![](https://raw.githubusercontent.com/prasad-kumkar/pallet-identity/master/resources/3.png)

## Understanding the template code

First we are importing the rust macros from the frame_support library, which are required to build our runtime module: `decl_module`, storage: `decl_storage`, events: `decl_event`, errors: `decl_error`, `dispatch` for DispatchResult and the `Get` trait that is used by storage to convert types. We must also import ensure_signed from frame_system to check if transactions are signed.

We have also been importing `ensure_signed` from `frame_system` to check if transactions are signed.

```rust
#![cfg_attr(not(feature = "std"), no_std)]

use frame_support::{decl_module, decl_storage, decl_event, decl_error, dispatch, traits::Get};
use frame_system::ensure_signed;

#[cfg(test)]
mod mock;

#[cfg(test)]
mod tests;
```

## Configuration

```rust
pub trait Config: frame_system::Config {
	/// Because this pallet emits events, it depends on the runtime's definition of an event.
	type Event: From<Event<Self>> + Into<<Self as frame_system::Config>::Event>;
}

```

## Declaring Storage

Here the pallet's storage name `TemplateModule` should be different from other pallets' storage name. 

`Something` is a storage item, which can store an optional unsigned 32-bit integer. This storage item can be accessed from the runtime module using the `something()` function. We can define more storage items if we want.

Read more about declaring [Storage Items](https://substrate.dev/docs/en/knowledgebase/runtime/storage#declaring-storage-items)

```rust
decl_storage! {
	trait Store for Module<T: Config> as TemplateModule {
		Something get(fn something): Option<u32>;
	}
}
```

Runtime supports emitting specified events on method calls. We can pass in arguments with each event, here `SomethingStored` emits an unsigned 32-bit integer and an AccountId

Declaration of the events would be done here:

```rust
decl_event!(
	pub enum Event<T> where AccountId = <T as frame_system::Config>::AccountId {
		SomethingStored(u32, AccountId),
	}
);
```

We can declare events with the Error enum, which can be called from the module calls. This informs the user that something went wrong.

```rust
decl_error! {
	pub enum Error for Module<T: Config> {
		NoneValue,
		StorageOverflow,
	}
}
```

## Runtime Module
This is where we declare method calls (transactions) which could be used to modify/query chain state, they could also emit events and errors. For each dispatchable function, Weight must be mentioned and it must return a `DispatchResult`

```rust
decl_module! {
	pub struct Module<T: Config> for enum Call where origin: T::Origin {
		// Errors must be initialized if they are used by the pallet.
		type Error = Error<T>;

		// Events must be initialized if they are used by the pallet.
		fn deposit_event() = default;

		/// An example dispatchable that takes a singles value as a parameter, writes the value to
		/// storage and emits an event. This function must be dispatched by a signed extrinsic.
		#[weight = 10_000 + T::DbWeight::get().writes(1)]
		pub fn do_something(origin, something: u32) -> dispatch::DispatchResult {
			// Check that the extrinsic was signed and get the signer.
			// This function will return an error if the extrinsic is not signed.
			// https://substrate.dev/docs/en/knowledgebase/runtime/origin
			let who = ensure_signed(origin)?;

			// Update storage.
			Something::put(something);

			// Emit an event.
			Self::deposit_event(RawEvent::SomethingStored(something, who));
			// Return a successful DispatchResult
			Ok(())
		}

		/// An example dispatchable that may throw a custom error.
		#[weight = 10_000 + T::DbWeight::get().reads_writes(1,1)]
		pub fn cause_error(origin) -> dispatch::DispatchResult {
			let _who = ensure_signed(origin)?;

			// Read a value from storage.
			match Something::get() {
				// Return an error if the value has not been set.
				None => Err(Error::<T>::NoneValue)?,
				Some(old) => {
					// Increment the value read from storage; will error in the event of overflow.
					let new = old.checked_add(1).ok_or(Error::<T>::StorageOverflow)?;
					// Update the value in storage with the incremented result.
					Something::put(new);
					Ok(())
				},
			}
		}
	}
}
```

# Designing a Custom Pallet
In our example we are designing an identity pallet, where:
- Users could generate a new identity
- Add/remove attributes to that identity
- Delete the identity

**Storage Items**

- Identity map: Identity => AccountId 
- Attribute map: (Identity, Attribute_Key) => Attribute_Value

**Events**

- IdentityCreated(Identity, AccountId)
- AttributeAdded(Identity, Attribute_Key, Attribute_Value)
- AttributeRemoved(Identity, Attribute_Key),

**Errors**

- IdentityAlreadyClaimed
- IdentityNotFound
- NotAuthorized
- AttributeNotFound

**Function Calls**

- create_identity( Identity ) 
- add_attribute( Identity, Attribute_Key, Attribute_Value ) 
- remove_attribute( Identity, Attribute_Key )


# Implementing the pallet
Have a look at this [example code](https://github.com/prasad-kumkar/pallet-identity/blob/master/src/lib.rs)

## Storage
For storage, we have created an `Identity` mapping from Identity to AccountId. `Identity` here would be a string transformed into a vector of size u8.

Another storage item would be `Attribute` which is a mapping from a tuple of `identity vector` and `attribute key vector` to `attribute value vector`.

```rust
decl_storage! {
	trait Store for Module<T: Config> as IdentityModule {
		pub Identity get(fn get_identity): map hasher(blake2_128_concat) Vec<u8> => Option<T::AccountId>;

		// ( identity, attribute_key ) => attribute_value
		pub Attribute get(fn get_attribute): map hasher(blake2_128_concat) (Vec<u8>, Vec<u8>) => Vec<u8>;
	}
}
```

## Events

```rust
decl_event!(
	pub enum Event<T> where AccountId = <T as frame_system::Config>::AccountId {
		// Identity, AccountId
		IdentityCreated(Vec<u8>, AccountId),

		// Identity, Attribute Key, Attribute Value
		AttributeAdded(Vec<u8>, Vec<u8>, Vec<u8>),

		// Identity, Attribute Key
		AttributeRemoved(Vec<u8>, Vec<u8>),
	}
);
```

## Errors

```rust
// Errors inform users that something went wrong.
decl_error! {
	pub enum Error for Module<T: Config> {
		IdentityAlreadyClaimed,
		IdentityNotFound,
		NotAuthorized,
		AttributeNotFound,
	}
}
```

## Function Calls

1. Create Identity

Allows user to choose a unique identity. Should throw error when Identity is alreaedy claimed.

```rust
#[weight = 10_000 + T::DbWeight::get().reads_writes(1, 1)]
pub fn create_identity(
	origin, 
	identity: Vec<u8>
) -> dispatch::DispatchResult {

	let who = ensure_signed(origin)?;

	match <Identity<T>>::get(&identity) {
		// Return an error if signer is not identity owner
		None => {
			// Update storage.
			<Identity<T>>::insert(&identity, &who);
			// Emit an event.
			Self::deposit_event(RawEvent::IdentityCreated(identity, who));
			// Return a successful DispatchResult
			Ok(())
		},
		Some(_) => Err(Error::<T>::IdentityAlreadyClaimed)?
	}
	
}
```

2. Add attribute

Allows the identity owner to add attribute key-values to their own identity. This should throw an error when trying to add attributes to someone else's identity or if identity is not found.

```rust
// Allows identity owners to add attribute to their identity (key, value)
#[weight = 10_000 + T::DbWeight::get().reads_writes(1,1)]
pub fn add_attribute(
	origin,
	identity: Vec<u8>,
	attribute_key: Vec<u8>,
	attribute_value: Vec<u8>
) -> dispatch::DispatchResult {
	let who = ensure_signed(origin)?;

	// Read a value from storage.
	match <Identity<T>>::get(&identity) {
		// Return an error if signer is not identity owner
		None => Err(Error::<T>::IdentityNotFound)?,
		Some(address) => {
			if address != who {
				return Err(Error::<T>::NotAuthorized)?
			} else{
				Attribute::insert((&identity, &attribute_key), &attribute_value);
				Self::deposit_event(RawEvent::AttributeAdded(identity, attribute_key, attribute_value));
				Ok(())
			}
		},
	}
}
```

3. Remove Attribute

```rust
// Allows identity owners to remove identity
#[weight = 10_000 + T::DbWeight::get().reads_writes(1,1)]
pub fn remove_attribute(
	origin,
	identity: Vec<u8>,
	attribute_key: Vec<u8>,
) -> dispatch::DispatchResult {
	let who = ensure_signed(origin)?;

	// Read a value from storage.
	match <Identity<T>>::get(&identity) {
		// Return an error if signer is not identity owner
		None => Err(Error::<T>::IdentityNotFound)?,
		Some(address) => {
			if address != who {
				return Err(Error::<T>::NotAuthorized)?
			} else{
				Attribute::remove((&identity, &attribute_key));
				Self::deposit_event(RawEvent::AttributeRemoved(identity, attribute_key));
				Ok(())
			}
		},
	}
}
```

# Writing Test Cases
Check out the [example tests](https://github.com/prasad-kumkar/pallet-identity/blob/master/src/tests.rs).

We have implemented two test cases:


- Create Identity, 
- Add attributes and 
- Remove attribute

```rust
#[test]
fn should_not_throw_errors() {
	new_test_ext().execute_with(|| {
		// Dispatch a signed extrinsic
		// create identity "prasad" for accountId 1
		let identity = "prasad".as_bytes().to_vec();
		assert_ok!(IdentityModule::create_identity(Origin::signed(1), "prasad".as_bytes().to_vec() ));
		// Read pallet storage and assert an expected result.
		assert_eq!(IdentityModule::get_identity(&identity), Some(1));

		let attribute_key = "name".as_bytes().to_vec();
		let attribute_value = "prasad kumkar".as_bytes().to_vec();

		// add attribute name => prasad kumkar
		assert_ok!(IdentityModule::add_attribute(Origin::signed(1), "prasad".as_bytes().to_vec(), "name".as_bytes().to_vec(), "prasad kumkar".as_bytes().to_vec()));
		// check attribute value
		assert_eq!(IdentityModule::get_attribute((&identity, &attribute_key)), attribute_value);

		// Remmove attribute
		assert_ok!(IdentityModule::remove_attribute(Origin::signed(1), "prasad".as_bytes().to_vec(), "name".as_bytes().to_vec()));
		// after removing, attribute value should be blank
		assert_eq!(IdentityModule::get_attribute((identity, attribute_key)), "".as_bytes().to_vec());

	});
}
```


- `Account 1` creates identity 'prasad',
- Throw `IdentityAlreadyClaimed` when `Account 2` creates the same identity
- Throw `Not Authorized Error` error while adding attributes to `Account 1`'s identity from `Account 2`

```rust
#[test]
fn check_for_errors() {
	new_test_ext().execute_with(|| {
		// Dispatch a signed extrinsic.
		let identity = "prasad".as_bytes().to_vec();
		assert_ok!(IdentityModule::create_identity(Origin::signed(1), "prasad".as_bytes().to_vec() ));
		// Read pallet storage and assert an expected result.
		assert_eq!(IdentityModule::get_identity(&identity), Some(1));

		// Should throw error as identity "prasad" is already claimed
		let identity = "prasad".as_bytes().to_vec();
		assert_noop!(
			IdentityModule::create_identity(
				Origin::signed(2), 
				"prasad".as_bytes().to_vec()
			),
			Error::<Test>::IdentityAlreadyClaimed
		);

		// add_attribute signed by different identity (2)
		// should throw NotAuthorized error
		assert_noop!(
			IdentityModule::add_attribute(
				Origin::signed(2), 
				"prasad".as_bytes().to_vec(), 
				"name".as_bytes().to_vec(), 
				"prasad kumkar".as_bytes().to_vec()
			), 
			Error::<Test>::NotAuthorized
		);

		// Attribute value should be blank
		assert_eq!(IdentityModule::get_attribute((identity, "name".as_bytes().to_vec())), "".as_bytes().to_vec());
	});
}
```

# Building and Testing

To build the completed pallet with cargo, run `cargo build --release`.

To run the tests against the compiled code, run `cargo test`.

![](https://raw.githubusercontent.com/prasad-kumkar/pallet-identity/master/resources/4.png)

# Releasing the pallet

Before releasing our pallet, we need to update the pallet details. Here you would need to update the pallet name to `pallet-identity` and change the repository link.

```toml
[package]
authors = ['Prasad-Kumkar <https://github.com/prasad-kumkar>']
description = 'Basic FRAME pallet for managing identities.'
edition = '2018'
homepage = 'https://substrate.dev'
license = 'Unlicense'
name = 'pallet-identity'
repository = 'https://github.com/prasad-kumkar/pallet-identity'
version = '3.0.0'
```

After that, you can publish the code using git:

```text
git add .
git commit -am "commit message"
git push origin master
```

## Adding to Runtime

To add this pallet to your runtime, simply include the following section in your runtime's `Cargo.toml` file (remember to update the git link):

```toml
[dependencies.pallet-identity]
default_features = false
git = 'https://github.com/prasad-kumkar/pallet-identity.git'
```

Also update your runtime's std feature to include this pallet:

```toml
std = [
    # --snip--
    'pallet-identity/std',
]
```

## Runtime `lib.rs`

You should implement it's trait like so:

```rust
/// Used for test_module
impl pallet_identity::Config for Runtime {
	type Event = Event;
}
```

Also include it in your `construct_runtime!` macro:


```rust
IdentityPallet: pallet_identity::{Module, Call, Storage, Event<T>},
```

# Conclusion
To recap the knowledge gained during the tutorial, we have understood FRAME by reviewing the substrate pallet template. Then we went ahead to build our custom pallet (identity pallet) and we saw how to design, implement, test the pallet. We then looked at publishing the pallet and implementing that in our substrate runtime. I hope this would be helpful towards building any custom pallet.

# Author
[Prasad Kumkar](https://github.com/prasad-kumkar) is a blockchain engineer with over 2 years of experience, co-founder of [Chainvote](https://chainvote.co), a blockchain based corporate governance solution. His work has been across various blockchain architectures such as Substrate, Hyperledger Fabric, EVM-based chains, Solana and Near Protocol. His team was the winner at WyoHackathon 2020 and ETH Denver 2021.

Contact - prasad@chainvote.co

# References
[Substrate KnowledgeBase](https://substrate.dev/docs/en/knowledgebase)

[Pallet DID](https://github.com/substrate-developer-hub/pallet-did)

[Template Pallet](https://github.com/substrate-developer-hub/substrate-pallet-template)

[Substrate Rust Docs](https://substrate.dev/rustdocs)


Learn how to build a custom pallet using the Substrate development framework

How to build Custom Pallets with Substrate

[The original tutorial can be found in Substrate's official documentation here. ](https://substrate.dev/docs/en/tutorials/create-your-first-substrate-chain/)

# Introduction

In this tutorial, you will learn how to compile and launch the Substrate Developer Hub Node Template and interact with it using the Substrate Developer Hub Front-End Template.

This tutorial is aimed at someone who has never touched Substrate before and wants to get a **basic** and **quick** understanding of what Substrate is all about. We will not be going into depth about the intricacies of developing on Substrate, but will hopefully satisfy your curiosity so that you will continue your journey!

This tutorial should take you about **1 hour** to complete. We will be compiling [Rust](https://www.rust-lang.org/) code, but you do _not_ need to have any Rust experience to complete this guide. We provide you with working code and explain how to use it.

We only expect that:

* You are generally familiar with software development and command line interfaces.
* You are generally familiar with blockchains and smart contract platforms.
* You are open to learning about the bleeding edge of blockchain development.

If you run into an issue on this tutorial, **we are here to help!** You can [ask a question on Stack Overflow](https://stackoverflow.com/questions/tagged/substrate) and use the `substrate` tag or contact us on [Element](https://matrix.to/#/#substrate-technical:matrix.org).

### What you will be doing

Before we even get started, let's lay out what we are going to do over the course of this tutorial. We will:

1. Set up your computer to be able to develop with Substrate.
2. Use a node template project to run a Substrate-based blockchain.
3. Use a front-end template project to interact with the template node.

Sound reasonable? Good, then let's begin!

## Set Up Your Computer

Normally, we would teach you more about the Substrate blockchain development framework, however, setting up your computer for Substrate development can take a while.

To optimize your time, we will have you start the setup process. While things are compiling, you can continue to the next section to learn more about Substrate and what we are building.

# Prerequisites


You will probably need to do some set-up to prepare your computer for Substrate development.

#### Substrate Development

> Before you continue, complete the [official Installation guide](https://substrate.dev/docs/en/knowledgebase/getting-started/). After `rustup` has been installed and configured, and you've configured the Rust toolchain to default to the latest stable version you can return to these steps.

### Compiling Substrate

Once the prerequisites are installed, you can use Git to clone the Substrate Developer Hub Node Template, which serves as a good starting point for building on Substrate.

1. Clone the Node Template $version `v3.0.0`$.

   ```text
   git clone -b v3.0.0 --depth 1 https://github.com/substrate-developer-hub/substrate-node-template
   Copy
   ```

2. Compile the Node Template

   ```text
   cd substrate-node-template
   # NOTE: you should always use the `--release` flag
   cargo build --release
   # ^^ this will take a while!
   Copy
   ```

> The time required for the compilation step depends on the hardware you're using.
>
> **You should start building the node template** _**before**_ **moving on!**

### Install the Front-End Template

This tutorial uses a [ReactJS](https://reactjs.org/) front-end template to allow you to interact with the Substrate-based blockchain node that you should have started compiling in the previous step. You can use this same front-end template to create UIs for your own projects in the future.

To use the front-end template, you need [Yarn](https://yarnpkg.com/), which itself requires [Node.js](https://nodejs.org/). If you don't have these tools, you _must_ install them from these instructions:

* [Install Node.js](https://nodejs.org/en/download/)
* [Install Yarn](https://yarnpkg.com/lang/en/docs/install/)

Now you can proceed to set up the front-end template with these commands.

```text
# Clone the frontend template from github
git clone -b v3.0.0 --depth 1 https://github.com/substrate-developer-hub/substrate-front-end-template

# Install the dependencies
cd substrate-front-end-template
yarn install
```

## Background Information 

 While we wait for the [node template to build](https://substrate.dev/docs/en/tutorials/create-your-first-substrate-chain/setup/#compiling-substrate), let's learn a little bit about the Substrate blockchain development framework. The Node Template that you are compiling was built with this framework.

### Substrate

Substrate is an **open source**, **modular**, and **extensible** framework for building blockchains.

Substrate has been designed from the ground up to be flexible and allow innovators to design and build a blockchain network that meets their needs. It provides all the core components you need to build a customized blockchain node.

#### Substrate Developer Hub Node Template

We provide an out-of-the-box working Substrate-based node in the form of the Node Template, which should be compiling as you read this. Without making any changes, you and your friends could share this node template and create a working blockchain network with a cryptocurrency and everything!

We will teach you how to use this node in "development" mode, which allows you to run a network with a single node, and have some pre-configured user accounts with funds.

## Interacting With Your Node 

Now that your node has finished compiling, let's show you how everything works out of the box.

### Starting Your Node

Run the following command to start your node:

```text
# Run a temporary node in development mode
./target/release/node-template --dev --tmp
Copy
```

Note the flags:

* `--dev` this set ups a developer node [chain specification](https://substrate.dev/docs/en/knowledgebase/integrate/chain-spec)
* `--tmp` this saves all active data for the node $keys, blockchain database, networking info, ...$ and is deleted as soon as you properly terminate your node. So every time you start with this command, you will have a clean state to work from. If the node is killed, `/tmp` is cleaned automatically on the restart of your computer for linux based OSs, and these files can manually be removed if needed.

With this command, you should see something like this if your node is running successfully:

```text
2021-03-16 10:56:51  Running in --dev mode, RPC CORS has been disabled.
2021-03-16 10:56:51  Substrate Node
2021-03-16 10:56:51  ✌️  version 3.0.0-8370ddd-x86_64-linux-gnu
2021-03-16 10:56:51  ❤️  by Substrate DevHub <https://github.com/substrate-developer-hub>, 2017-2021
2021-03-16 10:56:51  📋 Chain specification: Development
2021-03-16 10:56:51  🏷 Node name: few-size-5380
2021-03-16 10:56:51  👤 Role: AUTHORITY
2021-03-16 10:56:51  💾 Database: RocksDb at /tmp/substrateP1jD7H/chains/dev/db
2021-03-16 10:56:51  ⛓  Native runtime: node-template-100 (node-template-1.tx1.au1)
2021-03-16 10:56:51  🔨 Initializing Genesis block/state (state: 0x17df…04a0, header-hash: 0xc43b…ed16)
2021-03-16 10:56:51  👴 Loading GRANDPA authority set from genesis on what appears to be first startup.
2021-03-16 10:56:51  ⏱  Loaded block-time = 6000 milliseconds from genesis on first-launch
2021-03-16 10:56:51  Using default protocol ID "sup" because none is configured in the chain specs
2021-03-16 10:56:51  🏷 Local node identity is: 12D3KooWQdU84EJCqDr4aqfhb7dxXU2fzd6i2Rn1XdNtsiM5jvEC
2021-03-16 10:56:51  📦 Highest known block at #0
2021-03-16 10:56:51  〽️ Prometheus server started at 127.0.0.1:9615
2021-03-16 10:56:51  Listening for new connections on 127.0.0.1:9944.
2021-03-16 10:56:54  🙌 Starting consensus session on top of parent 0xc43b4514877d7dcfff2459cdfe609a96cf8e9b9723589635d7215de6bf00ed16
2021-03-16 10:56:54  🎁 Prepared block for proposing at 1 [hash: 0x255bcf44df92dd4ccaca15d92d4a3db9d276e42843e21ab0cc840e207b2649d6; parent_hash: 0xc43b…ed16; extrinsics (1): [0x02bf…2cbd]]
2021-03-16 10:56:54  🔖 Pre-sealed block for proposal at 1. Hash now 0x9c14d9caccc37f8142fc348d184fb4bd8a8bc217a8979493d7f46d4220775616, previously 0x255bcf44df92dd4ccaca15d92d4a3db9d276e42843e21ab0cc840e207b2649d6.
2021-03-16 10:56:54  ✨ Imported #1 (0x9c14…5616)
2021-03-16 10:56:54  🙌 Starting consensus session on top of parent 0x9c14d9caccc37f8142fc348d184fb4bd8a8bc217a8979493d7f46d4220775616
2021-03-16 10:56:54  🎁 Prepared block for proposing at 2 [hash: 0x6cd4bd9d2a531750c10610bdaa5af0075745b6612ffa3623c14d699250b4e732; parent_hash: 0x9c14…5616; extrinsics (1): [0x3cc8…b8d9]]
2021-03-16 10:56:54  🔖 Pre-sealed block for proposal at 2. Hash now 0x05bd3317b51d717163dfa8847369d7f697c6180868c29f02d0b7ff79c5bbde3f, previously 0x6cd4bd9d2a531750c10610bdaa5af0075745b6612ffa3623c14d699250b4e732.
2021-03-16 10:56:54  ✨ Imported #2 (0x05bd…de3f)
2021-03-16 10:56:56  💤 Idle (0 peers), best: #2 (0x05bd…de3f), finalized #0 (0xc43b…ed16), ⬇ 0 ⬆ 0
2021-03-16 10:57:00  🙌 Starting consensus session on top of parent 0x05bd3317b51d717163dfa8847369d7f697c6180868c29f02d0b7ff79c5bbde3f
2021-03-16 10:57:00  🎁 Prepared block for proposing at 3 [hash: 0xa6990964cf4f184edc08acd61c3c01ac8975abbba6d42f4eec3f9658097aec04; parent_hash: 0x05bd…de3f; extrinsics (1): [0xd6ed…86a5]]
2021-03-16 10:57:00  🔖 Pre-sealed block for proposal at 3. Hash now 0xbe07e322ca525e580a3703637db191c6df091b0242a411b88fa0c43ef0ac31f8, previously 0xa6990964cf4f184edc08acd61c3c01ac8975abbba6d42f4eec3f9658097aec04.
2021-03-16 10:57:00  ✨ Imported #3 (0xbe07…31f8)
2021-03-16 10:57:01  💤 Idle (0 peers), best: #3 (0xbe07…31f8), finalized #1 (0x9c14…5616), ⬇ 0 ⬆ 0
Copy
```

If the number after `finalized:` is increasing, your blockchain is producing new blocks and reaching consensus about the state they describe!

A few notes on the example output above:

* `💾 Database: RocksDb at /tmp/substrateP1jD7H/chains/dev/db` : where chain data is being written
* `🏷 Local node identity is: 12D3KooWQdU84EJCqDr4aqfhb7dxXU2fzd6i2Rn1XdNtsiM5jvEC`: the node ID needed if you intend to connect to other nodes directly $more in the [private network tutorial](https://substrate.dev/docs/en/tutorials/start-a-private-network/index)$

> While not critical now, please do read all the startup logs for your node, as they help inform you of key configuration information as you continue to learn and move past these first basic tutorials.

### Start the Front-End Template

To interact with your local node, we will use [the Substrate Developer Hub Front-End Template](https://github.com/substrate-developer-hub/substrate-front-end-template), which is a collection of UI components that have been designed with common use cases in mind.

> Be sure to use the correct version of the template for the version of substrate you are using as [major versions](https://semver.org/) are _not_ expected to be interoperable!

You already installed the Front-End Template; let's launch it by executing the following command in the root directory of the Front-End Template:

```text
# Make sure to run this command in the root directory of the Front-End Template
yarn start
Copy
```

### Interact

Once the Front-End Template is running and loaded in your browser at [http://localhost:8000/](http://localhost:8000/), take a moment to explore its components. At the top, you will find lots of helpful information about the chain to which you're connected as well as an account selector that will let you control the account you use to perform on-chain operations.

![Chain Data &amp; Account Selector](https://substrate.dev/docs/assets/tutorials/first-chain/chain-data.png)

There is also a table that lists [the well-known test accounts](https://substrate.dev/docs/en/knowledgebase/integrate/subkey#well-known-keys) that you have access to. Some, like Alice and Bob, already have funds!

![Account Table](https://substrate.dev/docs/assets/tutorials/first-chain/accts-prefunded.png)

Beneath the account table there is a Transfer component that you can use to transfer funds from one account to another. Take note of the info box that describes the precision used by the Front-End Template; you should transfer at least `1000000000000` to make it easy for you to observe the changes you're making. Here we give the `dave` development account these funds:

![Balance Transfer](https://substrate.dev/docs/assets/tutorials/first-chain/apps-transfer.png)

Notice that the table of accounts is dynamic and that the account balances are updated as soon as the transfer is processed.

#### Runtime Metadata

The Front-End Template exposes many helpful features and you should explore all of them while you're connected to a local development node. One good way to get started is by clicking the "Show Metadata" button at the top of the template page and reviewing [the metadata that your runtime exposes](https://substrate.dev/docs/en/knowledgebase/runtime/metadata).

![Metadata JSON](https://substrate.dev/docs/assets/tutorials/first-chain/metadata.png)

#### Pallet Interactor & Events

You can use the runtime metadata to discover a runtime's capabilities. The Front-End Template provides a helpful Pallet Interactor component that provides several mechanisms for interacting with a Substrate runtime.

![Pallet Interactor &amp; Events](https://substrate.dev/docs/assets/tutorials/first-chain/interactor-events.png)

[Extrinsics](https://substrate.dev/docs/en/knowledgebase/learn-substrate/extrinsics) are the runtime's callable functions; if you are already familiar with blockchain concepts, you can think of them as transactions for now. The Pallet Interactor allows you to submit [unsigned](https://substrate.dev/docs/en/knowledgebase/learn-substrate/extrinsics#unsigned-transactions) or [signed](https://substrate.dev/docs/en/knowledgebase/learn-substrate/extrinsics#signed-transactions) extrinsics and also provides a button that makes it easy to invoke an extrinsic by way of [the `sudo` function from the Sudo pallet](https://substrate.dev/rustdocs/v3.0.0/pallet_sudo/enum.Call.html#variant.sudo). You can learn more about using the "SUDO" button to invoke privileged extrinsics in the [Add a Pallet](https://substrate.dev/docs/en/tutorials/add-a-pallet) tutorial.

You can select Query interactions to read [the values present in your runtime's storage](https://substrate.dev/docs/en/knowledgebase/runtime/storage). The RPC and Constant options provide additional mechanisms for runtime interaction.

Like many blockchains, Substrate chains use [events](https://substrate.dev/docs/en/knowledgebase/runtime/events) to report the results of asynchronous operations. If you have already used the Front-End Template to perform a balance transfer as described above, you should see an event for the transfer in the Event component next to the Pallet Interactor.

# Next Steps

🎉 Congratulations!!! 🎉

You have launched a working Substrate-based blockchain, attached a user interface to that chain, and made token transfers among users. We hope you'll continue learning about Substrate!

Your next step may be:

* Extend the features of the template node in the [Add a Pallet](https://substrate.dev/docs/en/tutorials/add-a-pallet) tutorial.
* Learn about forkless runtime upgrades in the [Forkless Upgrade a Chain](https://substrate.dev/docs/en/tutorials/forkless-upgrade) tutorial.

If you experienced any issues with this tutorial or want to provide feedback, You can [ask a question on Stack Overflow](https://stackoverflow.com/questions/tagged/substrate) and use the `substrate` tag or contact us on [Element](https://matrix.to/#/#substrate-technical:matrix.org).



Learn how to compile and launch the Substrate Developer Hub Node Template and interact with it using the Substrate Developer Hub Front-End Template.

Create Your First Substrate Chain

In this tutorial, we will learn how to make a transfer of tokens on Polkadot. Transferring is a basic and fundamental feature of the Polkadot network. Transfers are not free, as they modify the state of the blockchain. How can we estimate the fees associated with a simple transfer? 

We'll explore how to estimate fees in this challenge.

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/polkadot/estimate.ts`, implement the function and try to estimate the fees required for a simple transfer. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const { address } = req.body;

    const url = getSafeUrl();
    const provider = new WsProvider(url);
    const api = await ApiPromise.create({ provider: provider });
    
    // A generic address for recipient (//Alice) and an amount to send
    const recipient = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
    const transferAmount = '1000000000';

    // Transfer tokens
    const transfer =  undefined;
    const info = undefined;
    const fees = undefined;

    res.status(200).json(fees);
  }
//...
```

**Need some help?** Check out these links
* [**How do I estimate the transaction fees?**](https://polkadot.js.org/docs/api/cookbook/tx#how-do-i-estimate-the-transaction-fees)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const { address } = req.body;

    const url = getSafeUrl();
    const provider = new WsProvider(url);
    const api = await ApiPromise.create({ provider: provider });
    
    // A generic address for recipient (//Alice) and an amount to send
    const recipient = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
    const transferAmount = '1000000000'; // 1 milli WND

    // Transfer tokens
    const transfer =  api.tx.balances.transfer(recipient, transferAmount);
    const info = await transfer.paymentInfo(address);
    const fees = info.partialFee.toNumber();

    res.status(200).json(fees)
  }
//...
```

**What happened in the code above?**

* First, we create a new transaction for a transfer using the `tx.balances.transfer` method, passing the `recipient` and `transferAmount`.
* Next, we call the `paymentInfo` method on the transaction object.
* Then we convert the `partialFee` property to a number with `toNumber`.
* Finally, we send the information back to the client-side as JSON.

------------------------

# Make sure it works

Once the code is complete and the file has been saved, click on **Estimate Fees**.

![](../../../.gitbook/assets/pathways/polkadot/polkadot-estimate.gif)

-----------------------------

# Conclusion

Now that we understand how to estimate the fees required to pay for a transaction on Polkadot, let’s move on to querying a Polkadot node to get the current balance of our account!


In this tutorial, we'll learn how to estimate the transaction fees

Estimate transaction fees

It’s time to submit your first transaction on Polkadot! In this tutorial, we will connect to a Westend node hosted by DataHub to transfer some testnet tokens. As you remember from previous tutorials, we funded our account on the **WESTEND** testnet with 1 **WND**. Now let’s try to transfer some tokens.

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/polkadot/transfer.ts`, implement the function and try to transfer an amount of tokens. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
    // Initialize account from the mnemonic
    const keyring = new Keyring({type: 'sr25519'});
    const account = keyring.addFromUri(mnemonic);
  
    // Initialize account from the mnemonic
    const recipient = keyring.addFromUri('//Alice');
    const recipientAddr = recipient.address

    // Transfer tokens
    const transfer = undefined;
    const hash = await transfer.signAndSend(account);
    
    res.status(200).json(hash.toString())
  }
//...
```

**Need some help?** Check out these links
* [**Polkadot.js documentation**](https://polkadot.js.org/docs/)  
* [**Code examples**](https://polkadot.js.org/docs/api/examples/promise/)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
    // Initialize account from the mnemonic
    const keyring = new Keyring({type: 'sr25519'});
    const account = keyring.addFromUri(mnemonic);
  
    // Initialize account from the mnemonic
    const recipient = keyring.addFromUri('//Alice');
    const recipientAddr = recipient.address;

    // Transfer tokens
    const transfer = await api.tx.balances.transfer(recipientAddr, txAmount);
    const hash = await transfer.signAndSend(account);
    
    res.status(200).json(hash.toString());
  }
//...
```

**What happened in the code above?**

* First, we need to instantiate our connection to the Polkadot API.
* Next, we call the `transfer` method of the `tx.balances` module, passing:
  * The recipient's address, from a [dev account](https://polkadot.js.org/docs/keyring/start/suri#dev-accounts) named "Alice".
  * The amount to transfer.
* Then we _sign and send_ the transaction passing our account as an argument to the `signAndSend` method - This specifies our account as the one paying the transfer fee, as well as signing the transaction.

------------------------

# Make sure it works

Once the code is complete and the file is saved, Next.js will rebuild the API route.
* Fill in the amount of **Planck** you want to send.
* Click on **Submit Transfer**.

![](../../../.gitbook/assets/pathways/polkadot/polkadot-transfer.gif)

-----------------------------

# Conclusion

Congratulations! You have now completed the Polkadot Pathway! 

There are many things that are beyond the scope of this Pathway, but the links provided to expand on some of the concepts contained in the tutorials should at least provide ample starting points for further study. Consider refining and playing with the code from the Pathway, to see what can be built out of these foundational blocks of Polkadot.

If you had any difficulties following this tutorial or simply want to discuss Polkadot with other developers you can join [our Discord](https://discord.gg/fszyM7K) or head over to our [community forums](https://community.figment.io).


In this tutorial, we'll learn how to transfer Token from one account to another

Transfer some Token

On Substrate blockchains, an account can stay active only if it maintains a minimal amount known as the **existential deposit**. If an account balance falls below this amount, then the system will erase the account and the remaining token dust will be lost.

In this tutorial, we'll learn how to query the system in order to retrieve the existential deposit.

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/polkadot/deposit.ts`, implement the function and try to determine the existential deposit an account needs to have in order to remain active. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const url = getSafeUrl();
    const provider = new WsProvider(url);
    const api = await ApiPromise.create({ provider: provider });
    const deposit = undefined;
    res.status(200).json(deposit);
  }
//...
```

**Need some help?** Check out these links
* [**Polkadot.js documentation**](https://polkadot.js.org/docs/)  
* [**Code examples**](https://polkadot.js.org/docs/api/examples/promise/)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const url = getSafeUrl();
    const provider = new WsProvider(url);
    const api = await ApiPromise.create({ provider: provider });
    const deposit = api.consts.balances.existentialDeposit.toNumber();
    res.status(200).json(deposit);
  }
//...
```

**What happened in the code above?**

* First, we need to instantiate our connection to the Polkadot API.
* Next, we call `existentialDeposit` of the `const.balances` module, converting the property to a number with `toNumber`.
* Finally, we send the `deposit` amount back to the client-side as JSON.

------------------------

# Make sure it works

Once the code is complete and the file has been saved, Next.js will rebuild the API route. Click the button to display the existential deposit amount.

![](../../../.gitbook/assets/pathways/polkadot/polkadot-deposit.gif)

-----------------------------

# Conclusion

Now that we've learned about fees, balances and the existential deposit on Polkadot - we can move on to making a token transfer! In the next tutorial, we will learn how to send tokens to other accounts. Ready? Let's go!



In this tutorial, we're going to learn how to determine the existential deposit.

Existential Deposit

# Part IV: Interacting with your Kitties

_Add pallet capabilities that unleash the potential of your Substrate Kitty application._

# Overview

Up until this point in the tutorial, we've built a chain capable of only creating and tracking the ownership of Kitties. In this part of the tutorial, we want to make our runtime more like a game by introducing other functions like buying and selling Kitties. In order to achieve this, we'll first need to enable users to update the price of their Kitty. Then we can add functionality to enable users to transfer, buy and breed Kitties.

## Learning outcomes

➡️ Learn how to create a dispatchable that updates an object in storage.

➡️ Getting a value from a struct in storage.

➡️ How to use the `transfer` from FRAME's Currency trait.

➡️ How to write sanity check using `ensure!()`.

# Steps

## Set a price for each Kitty

In [the helper file for this part of the tutorial](https://github.com/substrate-developer-hub/substrate-how-to-guides/blob/main/static/code/kitties-tutorial/04-interacting-functions.rs), you'll notice that the structure of `set_price` is already laid out.

Your job is to replace ACTION lines number 1, number 2 and number 3 lines with what you'll learn in sections A-D below. 
### Checking Kitty owner

As we create functions which modify objects in storage, we
should always check that only the appropriate users are successful when calling those dispatchable functions.

For modifying a Kitty object, we'll first need to get the `Hash` value of the owner of the
Kitty to ensure that it's the same as the sender.

> `KittyOwner` stores a mapping to an `Option<T::AccountId>` but that given `Hash` may not point to a generated and owned Kitty yet. This means, whenever we fetch the owner of a Kitty, we need to resolve the possibility that it returns `None`. This could be caused by bad user input or even some sort of problem with our runtime. Checking will help prevent these kinds of problems.

The general pattern for an ownership check will look something like this:

```rust
let owner = Self::owner_of(object_id).ok_or("No owner for this object")?;

ensure!(owner == sender, "You are not the owner");
```

**Your turn!** Paste in this code snippet to replace ACTION number 1:

```rust
            // Check that the Kitty has an owner (i.e. if it exists).
            let owner = Self::owner_of(kitty_id).ok_or("No owner for this kitty")?;
            // Make sure the owner matches the corresponding owner.
            ensure!(owner == sender, "You do not own this cat");
```
### Updating a the price of our Kitty object

Every Kitty object has a price attribute that we've set to [`0u8`][rust-u8] as a default value inside the
`create_kitty` function in [Part II](./dispatchables-and-events#2-write-the-create_kitty-dispatchable):

```rust
let new_kitty = Kitty {
    id: random_hash,
    dna: random_hash,
    price: 0u8.into(), // <-- here 
    gender: Kitty::<T, T>::gender(random_hash),
};
```

> Note
> We'll use this default value to check if the Kitty is for sale when we write the `buy_kitty` dispatchable in the next section.

To update the price of a Kitty, we'll need to:

- Get the Kitty object.
- Update the price.
- Push it back into storage.

Changing a value in an existing object in storage would be written in the following way:

```rust
let mut object = Self::get_object(object_id);
object.value = new_value;

<Object<T>>::insert(object_id, object);
```

> Note
> Rust expects you to declare a variable as mutable (using the `mut` keyword) whenever its value is going to be updated.

**Your turn!** Paste in the following snippet to replace the ACTION number 2 line: 

```rust
// Set the Kitty price.
let mut kitty = Self::kitty(kitty_id);
kitty.price = new_price;

// Update new Kitty infomation to storage.
<Kitties<T>>::insert(kitty_id, kitty);
```

### Sanity checks

In a similar vain of checking permissions, we also need to ensure that our runtime performs regular sanity
checks to mitigate any risk that things go wrong &mdash; such as users flooding the chain with heavy transactions or anything that could break the chain.

If we're creating a function geared to update the value of an object in storage,
the first thing we better do is make sure the object exists at all.
By using `ensure!`, we can create a safe guard against poor user input, whether malicious or unintentional. For example:

```rust
ensure!(<MyObject<T>>::exists(object_id));
```

This is already declared in the template helper code, but is an important check to remind ourselves about.

### Deposit an event

Once all checks are passed and the new price is written to storage, we can deposit an event 
[just like we did in Part III](/docs/tutorials/Kitties/dispatchables-and-events#4-implement-pallet-events). 
Replace the line marked as ACTION number 3 with:

 ```rust
 Self::deposit_event(Event::PriceSet(sender, kitty_id, new_price));
 ```

 Now whenever the `set_price` dispatchable is called successfully, it will emit a `PriceSet` event. 🎉

## Transfer a Kitty

Our pallet's storage items already handles ownership of Kitties
&mdash; this means that all our `transfer_kitty` function needs to do is update following storage items:

- `KittyOwner`: to update the owner of the Kitty.
- `OwnedKittiesArray`: to update the owned Kitty map for each acount.
- `OwnedKittiesIndex`: to update the owned Kitty index for each owner.
- `OwnedKittiesCount`: to update the amount of Kitties a account has.

You already have the tools you'll need to create the transfer functionality from [part 1](#1-set-a-price-for-each-kitty). The main difference in how we will
create this functionality for our runtime is that it will have **two parts to it**:

- 1. **A dispatchable function called `transfer()`:** this is what's exposed by your pallet.
- 2. **A private function called `transfer_from()`:** this will be a helper function called by `transfer()` to handle all storage updates when transferring a Kitty.

Separating the logic this way makes the private `transfer_from()` function reusable
by other dispatchable functions of our pallet, without needing to rewrite the same logic over and over again. In our case, we're going to reuse it for
the `buy_kitty` dispatchable we're creating in the next section.

Paste in the following snippet to replace ACTION number 4 in the template code:

```rust
#[pallet::weight(100)]
pub fn transfer(
    origin: OriginFor<T>,
    to: T::AccountId,
    kitty_id: T::Hash,
) -> DispatchResultWithPostInfo {
    let sender = ensure_signed(origin)?;

    // Verify Kitty owner: must be the account invoking this transaction.
    let owner = Self::owner_of(kitty_id).ok_or("No owner for this kitty")?;
    ensure!(owner == sender, "You do not own this kitty");

    // Transfer.
    Self::transfer_from(sender, to, kitty_id)?;

    Ok(().into())
}
```
## Buy a Kitty

### Check a Kitty is for Sale

We can use the `set_price()` function to check if the Kitty is for sale. Remember that we said a Kitty with the
price of `0` means it's not for sale? Easy enough then: write this check by simple using `ensure!()` (replacing line ACTION number 5):

```rust
// Check if the Kitty is for sale.
ensure!(!kitty_price.is_zero(), "This Kitty is not for sale!");
ensure!(
    kitty_price <= ask_price,
    "This Kitty is out of your budget!"
);
```

### Making a Payment

In the [Step 2](#2-transfer-a-kitty), we added the functions necessary to transfer the _ownership_ of our
Kitties. But, in the event that the Kitty was bought or sold, we never actually specified a currrency associated to our pallet.

In this step we'll learn how to use [FRAME's Currency trait][currency-frame-rustdocs] to adjust account balances
using its very own [`transfer` method][transfer-currency-rustdocs]. It's useful to understand why it's important to use the `transfer` method in particular and how we'll be accessing it:

- The reason we'll be using it is to ensure our runtime has the same understanding of currency throughout the pallets it interacts with. The way that we ensure this is to use the `Currency` trait from `frame_support`.

- Conveniently, it handles a [`Balance`][currency-balances-rustdocs] type, making it compatible with [`pallet_balances`][balances-frame] which we've been using in our pallet's configuration trait. Take a look at how the `transfer` function we'll be using is structured (from the [Rust docs][currency-transfer-rustdocs]):

```rust
fn transfer(
    source: &AccountId,
    dest: &AccountId,
    value: Self::Balance,
    existence_requirement: ExistenceRequirement
) -> DispatchResult
```

Now we can finally make use of the  `frame_support` imports &ndash; `Currency` and `ExistenceRequirement` &ndash; that we [initially started with in Part I](/docs/tutorials/Kitties/basic-setup#2-write-out-pallet_kitties-scaffold).

**Feeling confident?**

Here's how you would write `buy_Kitty` from scratch.

**Perform basic sanity checks**
 
- it will take 3 arguments: `origin`, `Kitty_id` and `max_price`
- check that `Kitty_id` corresponds to a Kitty in storage
- check that the Kitty has an owner

**Check if purchasing a Kitty is authorized**

- check that the account buying the Kitty doesn't already own it
- check that the price of the Kitty is not zero (if it is, throw an error)
- check that the Kitty price is not greater than `ask_price`
 
**Update storage items**
 
- use the `transfer` method from the `Currency` trait to update account balances
- use our pallet's `transfer_from` function to change the ownership of the Kitty from `owner` to `sender`
- update the price of the Kitty to the price it was sold at

**Your turn!** Paste in the following code snippet, replacing ACTION number 6:

```rust
<pallet_balances::Pallet<T> as Currency<_>>::transfer(
      &sender,
      &owner,
      kitty_price,
      ExistenceRequirement::KeepAlive,
  )?;
```

Now that that the `transfer` method from FRAME's Currency trait has been called, we can call a private helper function called `transfer_from` (which we'll write later) to write the new changes in ownership to storage. Replace this with what's on line ACTION number 7:

```rust
// Transfer ownership of Kitty.
Self::transfer_from(owner.clone(), sender.clone(), kitty_id).expect(
    "`owner` is shown to own the kitty; \
    `owner` must have greater than 0 kitties, so transfer cannot cause underflow; \
    `all_kitty_count` shares the same type as `owned_kitty_count` \
    and minting ensure there won't ever be more than `max()` kitties, \
    which means transfer cannot cause an overflow; \
    qed",
);

// Set the price of the Kitty to the new price it was sold at.
kitty.price = ask_price.into();
<Kitties<T>>::insert(kitty_id, kitty);
```

## Breed Kitties

The logic behind breeding two Kitties is to multiply each corresponding DNA segment from two Kitties,
which will produce a new DNA sequence. Then, that DNA is used when minting a new Kitty. 

Paste in the following to complete the `breed_kitty` function, replacing line ACTION number 8:

```rust
    let random_hash = Self::random_hash(&sender);
    let kitty_1 = Self::kitty(kitty_id_1);
    let kitty_2 = Self::kitty(kitty_id_2);

    let mut final_dna = kitty_1.dna;
    for (i, (dna_2_element, r)) in kitty_2
        .dna
        .as_ref()
        .iter()
        .zip(random_hash.as_ref().iter())
        .enumerate()
    {
        if r % 2 == 0 {
            final_dna.as_mut()[i] = *dna_2_element;
        }
    }
```

Now that we've used the user inputs of Kitty IDs and combined them to create a new unique Kitty ID, we can
use the `mint()` function to wirte that new Kitty to storage (replace line ACTION number 9):

```rust
let new_kitty = Kitty {
    id: random_hash,
    dna: final_dna,
    price: 0u8.into(),
    gender: Kitty::<T, T>::gender(final_dna),
};

Self::mint(sender, random_hash, new_kitty)?;
Self::increment_nonce()?;
```
Of course, after calling the `mint` function, we call `increment_nonce()` to maintain maximum entropy as described in [Part II](./create-kitties#nonce).

## Write the transfer_from helper 

Similar to writing the `mint` function, the `transfer_from` function is a helper called by the public `buy_kitty` dipatchable to perform all storage updates once a Kitty has been bought and sold.

Copy the following to replace ACTION number 10:

```rust
// Helper to handle transferring a Kitty from one account to another.
fn transfer_from(
    from: T::AccountId,
    to: T::AccountId,
    kitty_id: T::Hash,
) -> DispatchResult {
    // Verify that the owner is the rightful owner of this Kitty.
    let owner = Self::owner_of(kitty_id).ok_or("No owner for this kitty")?;
    ensure!(owner == from, "'from' account does not own this kitty");

    // Address to send from.
    let owned_kitty_count_from = Self::owned_kitty_count(&from);

    // Address to send to.
    let owned_kitty_count_to = Self::owned_kitty_count(&to);

    // Increment the amount of owned Kitties by 1.
    let new_owned_kitty_count_to = owned_kitty_count_to
        .checked_add(1)
        .ok_or("Transfer causes overflow of 'to' kitty balance")?;

    // Increment the amount of owned Kitties by 1.
    let new_owned_kitty_count_from = owned_kitty_count_from
        .checked_sub(1)
        .ok_or("Transfer causes underflow of 'from' kitty balance")?;

    // Get current Kitty index.
    let kitty_index = <OwnedKittiesIndex<T>>::get(kitty_id);

    // Update storage items that require updated index.
    if kitty_index != new_owned_kitty_count_from {
        let last_kitty_id =
            <OwnedKittiesArray<T>>::get((from.clone(), new_owned_kitty_count_from));
        <OwnedKittiesArray<T>>::insert((from.clone(), kitty_index), last_kitty_id);
        <OwnedKittiesIndex<T>>::insert(last_kitty_id, kitty_index);
    }

    // Write new Kitty ownership to storage items.
    <KittyOwner<T>>::insert(&kitty_id, Some(&to));
    <OwnedKittiesIndex<T>>::insert(kitty_id, owned_kitty_count_to);

    <OwnedKittiesArray<T>>::remove((from.clone(), new_owned_kitty_count_from));
    <OwnedKittiesArray<T>>::insert((to.clone(), owned_kitty_count_to), kitty_id);

    <OwnedKittiesCount<T>>::insert(&from, new_owned_kitty_count_from);
    <OwnedKittiesCount<T>>::insert(&to, new_owned_kitty_count_to);

    Self::deposit_event(Event::Transferred(from, to, kitty_id));

    Ok(())
}
```

## Write the transfer dispatchable

Now that we've included the `transfer_from` helper function, let's write out the `transfer` dispatchable. This will allow 
any user to attempt to transfer a Kitty to another account (it's important to _verify first and write last_!). 

Paste the following snippet to replace ACTION number 11:

```rust
#[pallet::weight(100)]
pub fn transfer(
    origin: OriginFor<T>,
    to: T::AccountId,
    kitty_id: T::Hash,
) -> DispatchResultWithPostInfo {
    let sender = ensure_signed(origin)?;

    // Verify Kitty owner: must be the account invoking this transaction.
    let owner = Self::owner_of(kitty_id).ok_or("No owner for this kitty")?;
    ensure!(owner == sender, "You do not own this kitty");

    // Transfer.
    Self::transfer_from(sender, to, kitty_id)?;

    Ok(().into())
}
```
By now the above pattern should be familiar. We always check that the transaction is signed; then we verify that the Kitty is owned by the sender of this transaction; and last we call the `transfer_from` helper which will update all storage items appropriately.

## Genesis configuration

The final step before our pallet is ready to be used is to set the genesis state of our storage items. We'll make use of
FRAME's `[pallet::genesis_config]` to do this. Essentially, we're declaring what the Kitties object in storage contains 
in the genesis block. Copy the following code to replace ACTION number 12: 

```rust
// Our pallet's genesis configuration.
#[pallet::genesis_config]
pub struct GenesisConfig<T: Config> {
    pub kitties: Vec<(T::AccountId, T::Hash, T::Balance)>,
}

// Required to implement default for GenesisConfig.
#[cfg(feature = "std")]
impl<T: Config> Default for GenesisConfig<T> {
    fn default() -> GenesisConfig<T> {
        GenesisConfig { kitties: vec![] }
    }
}

#[pallet::genesis_build]
impl<T: Config> GenesisBuild<T> for GenesisConfig<T> {
    fn build(&self) {
        for &(ref acct, hash, balance) in &self.kitties {
            let k = Kitty {
                id: hash,
                dna: hash,
                price: balance,
                gender: Gender::Male,
            };

            let _ = <Pallet<T>>::mint(acct.clone(), hash, k);
        }
    }
}
```
## Update runtime/lib.rs and interact with your Kitties

If you've completed all of the preceding parts and steps of this tutorial, you're
all geared up to run your chain and start interacting with all the new capabilities of your Kitties pallet.

Build and run your chain using the following commands:

```text
cargo build --release
./target/release/node-kitties --dev
```

Now check your work using the Polkadot-JS Apps UI just like [we did in the previous part](/docs/Tutorials/Kitties/dispatchables-and-events#5-testing-with-polkadotjs-apps). Once your chain is running and connected to the PolkadotJS Apps UI, perform these manual checks:

- Fund multiple users with tokens so they can all participate
- Have each user create multiple Kitties
- Try to transfer a Kitty from one user to another using the right and wrong owner
- Try to set the price of a Kitty using the right and wrong owner
- Buy a Kitty using an owner and another user
- Use too little funds to purchase a Kitty
- Overspend on the cost of the Kitty and ensure that the balance is reduced appropriately
- Breed a Kitty and check that the new DNA is a mix of the old and new

After all of these actions, confirm that all users have the right number of Kitties, the total Kitty count is correct, and any other storage variables are correctly represented

# Conclusion

**Congratulations!** You've successfully created the backend of a fully functional Substrate chain capable of creating and managing Substrate Kitties. It could also be abstracted to other NFT-like use cases. Most importantly, at this point in the tutorial you should have all the knowledge you need to start creating your own pallet logic and dispatchable functions.

# About the Author
Contributed by [Kresna Sucandra](https://github.com/SHA888), a medical doctor turned programmer and a Substrate ecosystem contributor.

# References
This tutorial is part of [Substrate Developer Hub's How-to Guides](https://substrate.dev/substrate-how-to-guides/) tutorial by [Sacha Lansky](https://github.com/sacha-l)

[transfer-currency-rustdocs]: https://crates.parity.io/frame_support/traits/tokens/currency/trait.Currency.html#tymethod.transfer
[frame-balances-rustdocs]: https://crates.parity.io/frame_support/traits/tokens/currency/trait.Currency.html
[polkadotjs-ui]: https://polkadot.js.org/apps/#/explorer
[rust-u8]: https://doc.rust-lang.org/std/primitive.u8.html
[currency-frame-rustdocs]: https://substrate.dev/rustdocs/latest/frame_support/traits/tokens/currency/index.html
[currency-balances-rustdocs]: https://substrate.dev/rustdocs/latest/frame_support/traits/tokens/currency/trait.Currency.html#associatedtype.Balance
[balances-frame]: https://substrate.dev/rustdocs/latest/pallet_balances/index.html
[currency-transfer-rustdocs]: https://substrate.dev/rustdocs/latest/frame_support/traits/tokens/currency/trait.Currency.html#tymethod.transfer


Learn how to add interactivity to your Substrate Kitties

Substrate Kitties - Interacting with your Kitties

# Introduction

Decentralization of blockchains has advantages and disadvantages, one of the major advantages is that there is no single unit which has complete power over a system.
From the other side, a disadvantage is that in the environment without centralized control, upgrading is hard due to the need for coordinating so many nodes at one time. One of the well known solutions of upgrading blockchains is the so-called "hard fork", however this has many potential vectors of attack and is hard to coordinate.

The newest solution for upgrading decentralized systems based on the Substrate framework is called `runtime-upgrade`. The solution works smoothly and in this tutorial, I will show you how you can easily upgrade your Substrate based chain. We will examine how adaptability is implemented in the Substrate framework.

# Prerequisites

To successfully follow this tutorial, you should have a basic knowledge about the Rust programming language and Polkadot's Substrate framework.

# Getting started

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/runtime-upgrade.png)

During the tutorial we will progress through these steps:
1. Build the simplest Substrate based blockchain
2. Run the Substrate chain locally (on your own hardware)
3. Add a new feature to the runtime
4. Build a WebAssembly (WASM) file
5. Verify the upgrade by checking the version

Upgrading the runtime state transition function consists of the following steps:

- Bump (increase) the spec_version
- Build the WASM file: `WASM_TARGET_DIRECTORY="$(pwd)" cargo build`
- Use the `sudo` command to start the runtime

# Building a simple Substrate blockchain

Checkout the master branch of https://github.com/TomaszWaszczyk/substrate-runtime-upgrade-tutorial, then execute the command make init and after around 10 minutes (depends on performance of your machine) you should see something like:

```text
Compiling sc-finality-grandpa v0.8.0
Compiling rocksdb v0.15.0
Compiling kvdb-rocksdb v0.9.1
Compiling sc-client-db v0.8.0
Compiling sc-service v0.8.0
Compiling sc-cli v0.8.0
Compiling frame-benchmarking-cli v2.0.0
Finished dev [unoptimized + debuginfo] target(s) in 13m 01s
```

> Note: If you want to build an optimized version of the project execute `cargo build --release`

# Run the Substrate node locally

Use the `make run` command:

```text
Running `target/debug/node-template --dev -lruntime=debug`
Sep 29 18:18:09.106  WARN Running in --dev mode, RPC CORS has been disabled.    
Sep 29 18:18:09.106  INFO Substrate Node    
Sep 29 18:18:09.106  INFO ✌️  version 2.0.0-73d7748-x86_64-linux-gnu    
Sep 29 18:18:09.106  INFO ❤️  by Substrate DevHub <https://github.com/substrate-developer-hub>, 2017-2021    
Sep 29 18:18:09.106  INFO 📋 Chain specification: Development    
Sep 29 18:18:09.106  INFO 🏷  Node name: frantic-insect-7496    
Sep 29 18:18:09.106  INFO 👤 Role: AUTHORITY    
Sep 29 18:18:09.107  INFO 💾 Database: RocksDb at /home/tomek/.local/share/node-template/chains/dev/db    
Sep 29 18:18:09.107  INFO ⛓  Native runtime: node-template-1 (node-template-1.tx1.au1)    
Sep 29 18:18:10.070  INFO 🔨 Initializing Genesis block/state (state: 0x0f2a…c2cc, header-hash: 0x1e1d…f017)    
Sep 29 18:18:10.073  INFO 👴 Loading GRANDPA authority set from genesis on what appears to be first startup.    
Sep 29 18:18:10.294  INFO ⏱  Loaded block-time = 2000 milliseconds from genesis on first-launch    
Sep 29 18:18:10.295  WARN Using default protocol ID "sup" because none is configured in the chain specs    
Sep 29 18:18:10.296  INFO 🏷  Local node identity is: 12D3KooWNo1348XGxpiA9uFJn4GJdptp7NcX72pFXsGZXghPKLYa (legacy representation: 12D3KooWNo1348XGxpiA9uFJn4GJdptp7NcX72pFXsGZXghPKLYa)    
Sep 29 18:18:10.618  INFO 📦 Highest known block at #0    
Sep 29 18:18:10.620  INFO 〽️ Prometheus server started at 127.0.0.1:9615    
Sep 29 18:18:10.624  INFO Listening for new connections on 127.0.0.1:9944.    
Sep 29 18:18:12.249  INFO 🙌 Starting consensus session on top of parent 0x1e1dd820c46a22dbd297afd5a62e73511208bafe64c6dc9e6a171562c443f017    
Sep 29 18:18:12.397  INFO 🎁 Prepared block for proposing at 1 [hash: 0x3b7c2d4f453358a70095cc0ad55a5f157a5be3d145c42213ea88c419b48966bf; parent_hash: 0x1e1d…f017; extrinsics (1): [0xff0f…0d06]]    
Sep 29 18:18:12.515  INFO 🔖 Pre-sealed block for proposal at 1. Hash now 0xc61a8f6ea035c0fd2e8acef986a60ec92abbaaa1f30c4781603d4ec83591b216, previously 0x3b7c2d4f453358a70095cc0ad55a5f157a5be3d145c42213ea88c419b48966bf.    
Sep 29 18:18:12.517  INFO ✨ Imported #1 (0xc61a…b216)    
Sep 29 18:18:14.123  INFO 🙌 Starting consensus session on top of parent 0xc61a8f6ea035c0fd2e8acef986a60ec92abbaaa1f30c4781603d4ec83591b216
```

Access the front-end of the local node via: <https://polkadot.js.org/apps/#/extrinsics?rpc=ws://127.0.0.1:9944>

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/before-upgrade.png)

We can see that the kitties pallet has only a create() function, it is our current state transition function in the runtime. To demonstrate how adaptable Substrate based blockchains are, we can add a new feature - the breed() function.

# Adding a feature to the runtime

Before making an upgrade, spec_version would be 1. Now that we are making an upgrade, we have incremented the field, so it will now be 2 as shown below:

```rust
pub const VERSION: RuntimeVersion = RuntimeVersion {
	spec_name: create_runtime_str!("node-template"),
	impl_name: create_runtime_str!("node-template"),
	authoring_version: 1,
	spec_version: 2, // incremented version
	impl_version: 1,
	apis: RUNTIME_API_VERSIONS,
	transaction_version: 1,
};
```

Our upgrade will add a new function to the kitties pallet called `breed`, here is the implementation:

```rust
/// Breed kitties
#[weight = 1000]
pub fn breed(origin, kitty_id_1: u32, kitty_id_2: u32) {
  let sender = ensure_signed(origin)?;
  let kitty1 = Self::kitties(&sender, kitty_id_1).ok_or(Error::<T>::InvalidKittyId)?;
  let kitty2 = Self::kitties(&sender, kitty_id_2).ok_or(Error::<T>::InvalidKittyId)?;

  ensure!(kitty1.gender() != kitty2.gender(), Error::<T>::SameGender);
    
  let kitty_id = Self::get_next_kitty_id()?;

  let kitty1_dna = kitty1.0;
  let kitty2_dna = kitty2.0;

  let selector = Self::random_value(&sender);
  let mut new_dna = [0u8; 16];

  // Combine parents and selector to create new kitty
  for i in 0..kitty1_dna.len() {
    new_dna[i] = combine_dna(kitty1_dna[i], kitty2_dna[i], selector[i]);
  }

  let new_kitty = Kitty(new_dna);

  Kitties::<T>::insert(&sender, kitty_id, &new_kitty);
  Self::deposit_event(RawEvent::KittyBred(sender, kitty_id, new_kitty));
}
```

After adding this breed function to the kitties pallet, we need to build the WASM file.

Here is a link to the whole new implementation: https://github.com/TomaszWaszczyk/substrate-runtime-upgrade-tutorial/blob/after-runtime-upgrade/pallets/kitties/src/lib.rs

After performing the upgrade, we expect that the kitties pallet will contain the new `breed` function without needing to restart the running Substrate node. Real adaptability of the blockchain!

# Building the runtime WASM file

Run the terminal command `WASM_TARGET_DIRECTORY="$(pwd)" cargo build` in order to build the runtime WASM file.

After a successful build, we expect to have a new file in the current directory:

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/wasm.png)

# Upgrading the runtime

We have a running Substrate node with version 1 and want to upgrade the runtime into version 2. Proof of a successful upgrade will be our freshly added breed function. Let's check, using the front-end.

To perform the upgrade, go to the **Developer** tab, then select **Sudo**. Make sure that you have selected the `system` pallet and `setCode(code)`, check in `file upload` and select the freshly created WASM file made in the previous step: `node_template_runtime.wasm`. Next, check the **with weight override** and in the field **unchecked weight for this call** type a value like 100, for example. To confirm the upgrade, click on **Submit Sudo Unchecked**.

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/upgrade.png)

After successfully upgrade you should see updated `spec_version` and have access to our new function:

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/after-upgrade.png)

In the screenshot above, we can see the result of a successful upgrade. Notice that `spec_version` has been incremented to 2 (where it says "node-template/2").

# Troubleshooting

## Problem: Rust errors when building

You may encounter an error while building, such as the one shown below. This means that you do not have the proper version of Rust installed.

```text
   Compiling prost-derive v0.6.1
error[E0034]: multiple applicable items in scope
   --> /home/tomek/.cargo/registry/src/github.com-1ecc6299db9ec823/prost-derive-0.6.1/src/lib.rs:111:14
    |
111 |             .intersperse(quote!(|));
    |              ^^^^^^^^^^^ multiple `intersperse` found
    |
    = note: candidate #1 is defined in an impl of the trait `Iterator` for the type `Map<I, F>`
    = note: candidate #2 is defined in an impl of the trait `Itertools` for the type `T`
help: disambiguate the associated function for candidate #1
    |
107 ~         let tags = Iterator::intersperse(field
108 +             .tags()
109 +             .into_iter()
110 +             .map(|tag| quote!(#tag)), {
111 +         let mut _s = $crate::__private::TokenStream::new();
112 +         $crate::quote_each_token!(_s $($tt)*);
  ...
help: disambiguate the associated function for candidate #2
    |
107 ~         let tags = Itertools::intersperse(field
108 +             .tags()
109 +             .into_iter()
110 +             .map(|tag| quote!(#tag)), {
111 +         let mut _s = $crate::__private::TokenStream::new();
112 +         $crate::quote_each_token!(_s $($tt)*);
  ...

For more information about this error, try `rustc --explain E0034`.
   Compiling asn1_der_derive v0.1.2
error: could not compile `prost-derive` due to previous error
warning: build failed, waiting for other jobs to finish...
error: build failed
make: *** [Makefile:11: build-full] Error 101
```

Solution - configure and make default proper version of Rust language on your machine

You need to install and set as default the specified nightly build of Rust: `rustup update nightly-2020-08-23` Rust language

1. Installation

`rustup update nightly-2020-08-23`

2. Make default version

`rustup default nightly-2020-08-23-x86_64-unknown-linux-gnu`

3. Checking of default version

`rustup show` and in the output you should see following output:

```text
active toolchain
----------------

nightly-2020-08-23-x86_64-unknown-linux-gnu (default)
rustc 1.47.0-nightly (663d2f5cd 2020-08-22)
```

# Conclusion

Congratulations! You have already understood the importance of how adaptability is important in decentralized blockchains and how the feature is implemented in Substrate framework.

During reading the tutorial you have learnt basics of Rust language, how to compile Substrate based chain and how to generate and then upload wasm file in order to deliver new feature for the chain.

# About The Author

The tutorial was created by Tomasz Waszczyk. In case any questions, you can reach out to Tomasz on [Figment Forum](https://community.figment.io/u/pantarhei) and on [Github](https://github.com/tomaszwaszczyk) for help or explaining doubts pertaining to Polkadot/Kusama ecosystem and this guide.

# References

When you have completed the tutorial, you are ready to learn more about [Forkless upgrading runtime](https://substrate.dev/docs/en/tutorials/forkless-upgrade/) tutorial by Jimmy Chu.


Learn how to upgrade a Substrate pallet without forking the blockchain

Perform a forkless upgrade of a Substrate pallet

In this tutorial, we will learn how to query an account balance on Polkadot. Account balances are important to keep track of so that users know if they can afford to send a transaction, or to afford what is called the **existential deposit**, which will be explained in the next tutorial.

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/polkadot/balance.ts`, implement the function and try to query the balance of your account. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const { address } = req.body;
    const url = getSafeUrl();
    const provider = new WsProvider(url);
    const api = await ApiPromise.create({ provider: provider });
    const { data: balance } = undefined;
    const amount = undefined;
    res.status(200).json(amount);
  } 
//...
```

**Need some help?** Check out these links
* [**Basic queries**](https://polkadot.js.org/docs/api/start/api.query#basic-queries)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const { address } = req.body;
    const url = getSafeUrl();
    const provider = new WsProvider(url);
    const api = await ApiPromise.create({ provider: provider });
    const { data: balance } = await api.query.system.account(address);
    const amount = balance.free.toNumber();
    res.status(200).json(amount);
  } 
//...
```

**What happened in the code above?**

* First, we need instantiate our connection to the Polkadot API.
* Next, we destructure the data returned by the `query.system.account` method as `balance`.
* Then we can access the available balance of our account via the `free` property, converting it into a number with `toNumber`.
* Finally, we send the `amount` back to the client-side as JSON.

------------------------

# Make sure it works

Once the code is complete and the file is saved, Next.js will rebuild the API route. Click on **Check Balance** and you should see the balance displayed on the page:

![](../../../.gitbook/assets/pathways/polkadot/polkadot-balance.gif)

-----------------------------

# Conclusion

Querying the balance information is fun, but being able to submit transactions and change the state of a blockchain is even better! Soon, we will dive deeper and submit our first transactions on Polkadot. But first, we need to understand the **existential deposit** feature of Polkadot accounts. 


In this tutorial, we'll learn how to check our account balance

Get the Balance

# Part III: Dispatchables, Events and Errors

_Write a dispatchable function that creates a Kitty capable of emitting its associated Event._

## Overview

In the previous section of this tutorial, we laid down the foundations geared to manage the ownership of our Kitties &mdash; even though they don't really exist yet! In this part of the tutorial, we'll be putting these foundations to use
by giving our pallet the ability to create a Kitty using the storage items we declared in the previous part. Breaking things down a little, we're going to:

- **Write `create_kitty`**: a dispatchable or publicly callable function allowing an account to mint a Kitty.
- **Write `mint()`**: a helper function that updates our pallet's storage items and performs error checks, called by `create_kitty`.
- **Include `Events`**: using FRAME's `#[pallet::events]` macro.

At the end of this part, we'll check that everything compiles without error and call our `create_kitty` extrinsic using the PolkadotJS Apps UI.

> Note
> If you're feeling confident, you can continue building on your codebase from the previous part.
> If you prefer using the "ACTION" items as a way to assist you through each step, replace the code from the Part II with [this part's helper code][helper-code-pt3].

## Learning outcomes

➡️ Write a dispatchable function that updates storage items using a helper function.

➡️ Write a private helper function with error handling

➡️ Write and use pallet Events and Errors.

➡️ Use PolkadotJS Apps UI to test pallet functionality.

# Steps

## Public and private functions

Before we dive right in, it's important to understand the pallet design decisions we'll be making around coding up our Kitty pallet's minting and ownership management capabilities.

As developers, we want to make sure the code we write is efficient and elegant. Oftentimes, optimizing for one optimizes for the other.
The way we're going to set up our pallet up to optimize for both will be to break-up the "heavy lifting" dispatchable
functions into private helper functions. This improves code readability and reusability too. As we'll see, we can
create private functions which can be called by multiple dispatchable functions without compromizing on security. In fact, building this way can be considered an additive security feauture.

> Check out [this how-to guide](https://substrate.dev/substrate-how-to-guides/docs/basics/basic-pallet-integration/) about writing and using helper functions to learn more.

Before jumping into implementing this approach, let's first paint the big picture of what combining dispatchables and helper functions looks like:

**`create_kitty`** (dispatchable function)

- check the origin is signed
- generate a random hash with the signing account
- create a new Kitty object using the random hash
- call a private `mint()` function
- increment the nonce using `increment_nonce()` from [Part II](./create-kitties)

**`mint`** (private helper function)

- check that the Kitty doesn't already exist
- update storage with the new Kitty ID (for all Kitties and for the owner's account)
- update the new total Kitty count for storage and the new owner's account
- deposit an Event to signal that a Kitty has succesfully been created

## Write the `create_kitty` dispatchable

A [dispatchable][dispatchable-kb] in FRAME always follows the same structure. All pallet dispatchables live under the `#[pallet::call]` macro which requires declaring the dispatchables section with ` impl<T: Config> Pallet<T> {}`. Read the
[documentation][frame-macros-kb] on these FRAME macros to learn how they work. All we need to know here is that they're a useful feature of FRAME that minimizes the code required to write for pallets to be properly integrated in a Substrate chain's runtime.

### Weights

As per the requirement for `#[pallet::call]` described in the its documentation, every dispatchable function must have an associated weight to it. Weights are
an important part of developing with Substrate as they provide safe-guards around the amount of computation to fit in a block at execution time.
[Substrate's weighting system][weights-kb] forces developers to think about the computational complexity each [extrinsic][extrinsics-kb] carries before it is called so that
a node will account for it's worst case, avoiding lagging the network with extrinsics that may take longer than the specified block time. Weights are also intimately linked to the [fee system][txn-fees-kb] for a signed extrinsic.

For this simple application, we're going to default all weights to 100.

Find ACTION number 1 and replace it with the following code:

```rust
#[pallet::weight(100)]
pub fn create_kitty(origin: OriginFor<T>) -> DispatchResultWithPostInfo {
    let sender = ensure_signed(origin)?;
    let random_hash = Self::random_hash(&sender);

    let new_kitty = Kitty {
        id: random_hash,
        dna: random_hash,
        price: 0u8.into(),
        gender: Kitty::<T, T>::gender(random_hash),
    };

    Self::mint(sender, random_hash, new_kitty)?;
    Self::increment_nonce()?;

    Ok(().into())
}
```

## Write the `mint()` function

As seen when we wrote `create_kitty` in the previous section, we'll need to create `mint()` for
writing our new unique Kitty object to the various storage items declared in Part II of this tutorial.

Let's get right to it. Our `mint()` function will take the following arguments:

- **`to`**: of type `T::AccountId`
- **`kitty_id`**: of type `T::Hash`
- **`new_kitty`**: of type `Kitty<T::Hash, T::Balance>`

And it will return `DispatchResult`.

> Note 
> Why "DispatchResult" and not "DispatchResultWithPostInfo" ?
> In `create_kitty` our return was of type `DispatchResultWithPostInfo`. Since `mint()` is a helper for `create_kitty`, we don't need to overwrite `PostDispatchInfo`, so we can use a return type of [`DispatchResult`][dispatchresult-rustdocs] &mdash; its unaugmented version.

Paste in the following code snippet to write the beginning of the `mint` function, replacing ACTION number 2 in the working codebase:

```rust
// Helper to mint a Kitty.
fn mint(
    to: T::AccountId,
    kitty_id: T::Hash,
    new_kitty: Kitty<T::Hash, T::Balance>,
) -> DispatchResult {
    ensure!(
        !<KittyOwner<T>>::contains_key(kitty_id),
        "Kitty already contains_key"
    );
    // Update total Kitty counts.
    let owned_kitty_count = Self::owned_kitty_count(&to);
    let new_owned_kitty_count = owned_kitty_count
        .checked_add(1)
        .ok_or("Overflow adding a new kitty to account balance")?;

    let all_kitties_count = Self::all_kitties_count();
    let new_all_kitties_count = all_kitties_count
        .checked_add(1)
        .ok_or("Overflow adding a new kitty to total supply")?;

    // Update storage with new Kitty.
    <Kitties<T>>::insert(kitty_id, new_kitty);
    <KittyOwner<T>>::insert(kitty_id, Some(&to));

    // Write Kitty counting information to storage.
    <AllKittiesArray<T>>::insert(new_all_kitties_count, kitty_id);
    <AllKittiesCount<T>>::put(new_all_kitties_count);
    <AllKittiesIndex<T>>::insert(kitty_id, new_all_kitties_count);

    // Write Kitty counting information to storage.
    <OwnedKittiesArray<T>>::insert((to.clone(), new_owned_kitty_count), kitty_id);
    <OwnedKittiesCount<T>>::insert(&to, new_owned_kitty_count);
    <OwnedKittiesIndex<T>>::insert(kitty_id, new_owned_kitty_count);
```

Let's go over what the above code is doing.

The first thing we're doing is to check whether the Kitty being passed in doesn't already exist. To accomplish this, we use the built-in `ensure!` macro that Rust provides us, along with a method provided by FRAME's `StorageMap` called `contains_key`.

[`contains_key`][contains-key-rustdocs] will check if a key matches the Hash value in an existing Kitty object. And `ensure!` will return an error if the storage map already contains the given Kitty ID.

Once we've done the check, we proceed with updating our storage items with the Kitty object passed into our function call. To do this, we make use of
the [`insert`][insert-rustdocs] method from our StorageMap API, using the following pattern:

```rust
<SomeStorageMapStruct<T>>::insert(some_key, new_key);
```

Finally, we compute a few variables to update our storage items that keep track of:

- The indices and count **for all** Kitties.
- The indices and count **of owned** Kitties.

All this requires us to do is add 1 to the current values held by `<AllKittiesCount<T>>` and `<OwnedKittiesCount<T>>`. We can use the same pattern as we did in the previous part [when we created `increment_nonce`](/create-kitties#nonce), using Rust's `checked_add` and `ok_or`. Generically, this looks like:

```rust
let new_value = previous_value.checked_add(1).ok_or("Overflow error!");
```

A quick recap of our storage items

- **`<Kitties<T>>`**: Stores a Kitty's unique traits and price, by storing the Kitty object.
- **`<KittyOwner<T>>`**: Keeps track of what accounts own what Kitty.
- **`<AllKittiesArray<T>>`**: An index to track of all Kitties.
- **`<AllKittiesCount<T>>`**: Stores the total amount of Kitties in existence.
- **`<AllKittiesIndex<T>>`**: Keeps track of all the Kitties.
- **`<OwnedKittiesArray<T>>`**: Keep track of who a Kitty is owned by.
- **`<OwnedKittiesCount<T>>`**: Keeps track of the total amount of Kitties owned.
- **`<OwnedKittiesIndex<T>>`**: Keeps track of all owned Kitties by index.

> Note
> There's 8 storage items in total and each type of storage exposes a number of different methods. Have a glance at the [methods `StorageValue`][storage-value-rustdocs] and [`StorageMap` expose][storagemap-rustdocs] to learn more.

## Implement pallet Events

In Substrate, even though a transaction may be finalized, it does not necessarily imply that the function executed by that 
transaction fully succeeded. To verify this, we make our pallet emit an [Event][events-kb] at the end of the function. This not only 
reports the success of a function's execution, but also tells the "off-chain world" that some particular state transition has happened.

FRAME helps us easily manage and declare our pallet's events using the [`#[pallet::event]`][events-rustdocs] macro. With FRAME macros, events are just an enum declared like this:

```rust
#[pallet::event]
#[pallet::generate_deposit(pub(super) fn deposit_event)]
pub enum Event<T: Config>{
    /// A function succeeded. [time, day]
    Success(T::Time, T::Day),
}
```

As you can see in the above snippet, we use:

`#[pallet::generate_deposit(pub(super) fn deposit_event)]` 

This allows us to deposit a specifc event using the pattern below:

```rust
Self::deposit_event(Event::Success(var_time, var_day));
```

In order to use events inside our pallet, we need to have the `Event` type declared inside our pallet's configuration trait, `Config`. Additionally &mdash; just as when adding any type to our pallet's `Config` trait &mdash; we need to let our runtime know about it. 

This pattern is the same as when we added the `KittyRandomness` type in [Part II of this tutorial](/docs/Tutorials/Kitties/create-kitties#2-implementing-randomness) and has already been included from the initial scaffolding of our codebase: 

```rust
  /// Configure the pallet by specifying the parameters and types it depends on.
  #[pallet::config]
  pub trait Config: pallet_balances::Config + frame_system::Config {
      /// Because this pallet emits events, it depends on the runtime's definition of an event.
      type Event: From<Event<Self>> + IsType<<Self as frame_system::Config>::Event>;
      //--snip--//
  }
```

> Notice that each event deposit is meant to be informative which is why it carries the various types associated with it.
>
> It's good practice to get in the habit of documenting your event declarations so that your code is easy to read. It is convention to document events as such:
>
> `/// Description. [types]`
>
> Learn more about events [here][events-kb].

Declare your pallet events by replacing the ACTION #3 line with:

```rust
Created(T::AccountId, T::Hash),
PriceSet(T::AccountId, T::Hash, T::Balance),
Transferred(T::AccountId, T::AccountId, T::Hash),
Bought(T::AccountId, T::AccountId, T::Hash, T::Balance),
```

We'll be using most of these events in Part IV of this tutorial. For now let's use the relevant event for our `mint` function.

In order to complete our `mint` function, replace the ACTION number 4 line with:

```rust
Self::deposit_event(Event::Created(to, kitty_id));
```
> Note
> If you're building your codebase from the previous part (and haven't been using the helper file for this part) you'll need to add `Ok(())` and properly close the `mint` function.

## Error handling 

In [Part II when we created the `increment_nonce`](/docs/tutorials/Kitties/create-kitties#nonce) function, we specified the error message _"Overflow"_ using Rust's `ok_or` function. FRAME provides us with an error handling system using [`[#pallet::errors]`][errors-kb] which allows us to specify errors for our pallet and use them across our pallet's functions. 

In this case, let's declare a single error for when checking for overflow in the `increment_nonce` function. 

First, declare the error using the provided FRAME macro under `#[pallet::error]` (replace line ACTION #5a):

```rust
/// Nonce has overflowed past u64 limits
NonceOverflow,
```

Then, use it on `ok_or` inside `increment_nonce` (replace line ACTION number 5b):

```rust
let next = nonce.checked_add(1).ok_or(Error::<T>::NonceOverflow)?;
```

Now's a good time to see if your chain can compile. Instead of only checking if your pallet compiles, run the following command to see if everything can build:

```
cargo +nightly build --release
```

> Tip
> If you ran into errors, scroll to the first error message in your terminal, identify what line is giving an error and check whether you've followed each step correctly. Sometimes a mismatch of curly brackets will unleash a whole bunch of errors that are difficult to understand &mdash; double check your code!

Did that build fine? Congratulations! That's the core functionality of our Kitties pallet. In the next step you'll be able to 
see everything you've built so far in action.

## Testing with PolkadotJS Apps

Assuming that you successfully built your chain, let's run it and use the [PolkadotJS Apps UI](https://polkadot.js.org/apps/#/explorer) to interact with it.

In your chain's project directory, run:

```text
./target/release/node-kitties --tmp --dev
```

By doing this, we're specifying to run a temporary chain in developer mode, so as not to need to purge storage each time we want to start a fresh chain.

Assuming that blocks are being finalized (which you should be able to see from your terminal in which you ran the above command), head over to [Poladot.js Apps][polkadotjsapps].

**Follow these steps:**

1. Check that you're connected to Local Node, under "Development". Your node will default to `127.0.0.1.:9944`.
2. Tell the UI about your custom types. 
This requires you to paste them into the "_Settings_" -> "_Developers_" section.
3. Go to "_Developer_" -> "_Extrinsics_". Paste this in the JSON code editor:

```text
{
  "AccountInfo": {
    "nonce": "Index",
    "consumers": "RefCount",
    "providers": "RefCount",
    "data": "AccountData"
  },
  "Address": "MultiAddress",
  "LookupSource": "AccountId",
  "Gender": {
    "_enum": ["male", "female"]
  },
  "Kitty": {
    "id": "H256",
    "dna": "H256",
    "price": "Balance",
    "gender": "Gender"
  }
}
```

> The reason we need this is because we created types that PolkadotJS Apps isn't designed to read by default. By adding them, it can properly decode each of our storage items that rely on custom types.

3. Now go to: _"Developer"_ -> _"Extrinsics"_ and submit a signed extrinsic using _substrateKitties_ by calling the `createKitty()` dispatchable. Make 3 different transactions from Alice, Bob and Charlie's accounts
4. Check for the associated event _"Created"_ by going to "_Network_" -> "_Explorer_". You should be able to see the event emitted and query its block details.
5. Check your newly created Kitty's details by going to "_Developer_" -> "_Chain State_". Select the _substrateKitties_ pallet and query `Kitties(Hash): Kitty`. **Note:** You'll notice that this is actually querying all of your pallet's storage items!

Be sure to uncheck the "include option" box and you should be able to see the details of your newly minted Kitty in the following format:

```json
substrateKitties.kitties: Kitty
[
    [
      0xf78c3e9c10498c350d639a10fa773cb878b85bf2c5989e38f8b1cd5c0bafb7ee
    ],
    {
      id: 0xf78c3e9c10498c350d639a10fa773cb878b85bf2c5989e38f8b1cd5c0bafb7ee,
      dna: 0xf78c3e9c10498c350d639a10fa773cb878b85bf2c5989e38f8b1cd5c0bafb7ee,
      price: 0,
      gender: female
    }
  ],
```

5. Check that other storage items correctly reflect the creation of additional Kitties.

**Congratulations!**
You're pretty much able to take it from here at this point! We've learned how to implement the key parts of what powers a FRAME pallet and how to put them to use. All part IV of this tutorial covers is adding more capabilities to our pallet by taking what we've learnt in this part.
 
 To recap, in this part of the tutorial you've learnt how to:
 
- Distinguish between implementing a dispatchable function and a private helper function.
- Use `#[pallet::call]`, `#[pallet::events]` and `#[pallet::error]`.
- Implement basic error checking with FRAME.
- Update values in storage with safety checks.
- Implement FRAME events and use them in a function.
- Query storage items and chain state using the PolkadotJS Apps UI.

# Next steps

- Create a dispatchable to buy a Kitty
- Create a dispatchable to transfer a Kitty
- Create a dispatchable to breed two Kitties

[frame-macros-kb]: https://substrate.dev/docs/en/knowledgebase/runtime/macros#palletcall
[txn-fees-kb]: https://substrate.dev/docs/en/knowledgebase/runtime/fees
[weights-kb]: https://substrate.dev/docs/en/knowledgebase/learn-substrate/weight
[contains-key-rustdocs]: https://substrate.dev/rustdocs/latest/frame_support/storage/trait.StorageMap.html#tymethod.contains_key
[insert-rustdocs]: https://substrate.dev/rustdocs/latest/frame_support/storage/trait.StorageMap.html#tymethod.insert
[storage-value-rustdocs]: https://substrate.dev/rustdocs/latest/frame_support/storage/types/struct.StorageValue.html#method.put
[storagemap-rustdocs]: https://substrate.dev/rustdocs/latest/frame_support/storage/types/struct.StorageMap.html#method.insert
[events-rustdocs]: https://crates.parity.io/frame_support/attr.pallet.html#event-palletevent-optional
[events-kb]: https://substrate.dev/docs/en/knowledgebase/runtime/events
[polkadotjsapps]: https://polkadot.js.org/apps/#/explorer
[dispatchresult-rustdocs]: https://substrate.dev/rustdocs/latest/frame_support/dispatch/type.DispatchResult.html
[dispatchable-kb]: https://substrate.dev/docs/en/knowledgebase/getting-started/glossary#dispatch
[extrinsics-kb]:  https://substrate.dev/docs/en/knowledgebase/runtime/execution#executing-extrinsics
[helper-code-pt3]: https://github.com/substrate-developer-hub/substrate-how-to-guides/blob/main/static/code/kitties-tutorial/03-dispatchables-and-events.rs
[errors-kb]: https://substrate.dev/docs/en/knowledgebase/runtime/errors


Learn how to use storage with your Substrate Pallet

Substrate Kitties - Dispatchables & Events

In this tutorial, we will connect to a Polkadot node hosted by [DataHub](https://docs.figment.io/introduction/what-is-datahub) using a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) Provider. DataHub lets developers use the most powerful and unique features of a blockchain without having to become protocol experts. WebSockets make it possible to open a two-way interactive communication session between the user's browser and a server. 

Polkadot has built a [JavaScript library](https://github.com/polkadot-js/api) to help developers interface easily with its API. The documentation for Polkadot.js can be found at [https://polkadot.js.org/docs/](https://polkadot.js.org/docs/).

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/polkadot/connect.ts`, implement the function and try to establish your first connection to the Polkadot network. You must replace the instances of `undefined` with working code to accomplish this.  
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const url = getSafeUrl();
    const provider = new WsProvider(url);
    const api = undefined;
    const rawVersion = undefined;
    const version = rawVersion.toHuman();
    res.status(200).json(version);
  }
//...
```

**Need some help?** Check out these links
* [**Basics & Metadata**](https://polkadot.js.org/docs/api/start/basics)  
* [**Providers**](https://polkadot.js.org/docs/api/start/create#providers)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const url = getSafeUrl();
    const provider = new WsProvider(url);
    const api = await ApiPromise.create({ provider: provider });
    const rawVersion = await api.rpc.system.version();
    const version = rawVersion.toHuman();
    res.status(200).json(version);
  }
//...
```

**What happened in the code above?**

* The `getSafeUrl` helper function constructs a DataHub URL for either Mainnet or the Westend testnet using the API key provided in `.env.local` - It can also be used with the `force` option to return the public Westend RPC endpoint as a fallback.  
* With the endpoint URL, we can create a new `WsProvider` instance.
* Then we use `ApiPromise.create` to initialize the API, passing the provider as an object.
* Using the `rpc` module, we can then query the `system.version` method. 
* To display a human readable string of the version number, we use the `toHuman` method.
* Finally, we send the `version` back to the client-side as JSON.

------------------------

# Make sure it works

Once the code is complete and the file has been saved, refresh the page to see it update & display the current version.

![](../../../.gitbook/assets/pathways/polkadot/polkadot-connect.gif)

-----------------------------

# Conclusion

In this tutorial you’ve learned how to use the [Polkadot.js](https://polkadot.js.org/docs/) package and DataHub to connect to a Polkadot node. You also learned how to run a simple query to test that connection.


In this tutorial, we're going to connect with the Polkadot network

Connect to Polkadot

[The original tutorial can be found in Substrate's official documentation here. ](https://substrate.dev/docs/en/tutorials/add-contracts-pallet/)

# Introduction

The [Substrate Node Template](https://github.com/substrate-developer-hub/substrate-node-template) provides a minimal working runtime which you can use to quickly get started with building your own custom blockchain. However, in the attempts to remain minimal, it does not include most of the pallets from [FRAME](https://substrate.dev/docs/en/knowledgebase/runtime/frame).

This guide will show you how you can add the [Contracts pallet](https://substrate.dev/rustdocs/v3.0.0/pallet_contracts/) to your runtime in order to allow your blockchain to support Wasm smart contracts. You can follow similar patterns to add additional FRAME pallets to your runtime, however you should note that each pallet is a little different in terms of the specific configuration settings needed to use it correctly.

## Install the Node Template

You should already have version `v3.0.0` of the [Substrate Node Template](https://github.com/substrate-developer-hub/substrate-node-template) compiled on your computer from when you completed the [Create Your First Substrate Chain Tutorial](https://substrate.dev/docs/en/tutorials/create-your-first-substrate-chain/). If you do not, please complete that tutorial.

> Experienced developers who truly prefer to skip that tutorial, you may install the node template according to the instructions in its readme.

## File Structure

We will now modify the `substrate-node-template` to include the Contracts pallet.

Open the `substrate-node-template` in your favorite code editor. We will be editing two files: `runtime/src/lib.rs`, and `runtime/Cargo.toml`.

```text
substrate-node-template
|
+-- runtime
|   |
|   +-- Cargo.toml   <-- One change in this file
|   |
|   +-- build.rs
|   |
|   +-- src
|      |
|      +-- lib.rs    <-- Most changes in this file
|
+-- pallets
|
+-- scripts
|
+-- node             <-- changes in this directory
|
+-- ...
```

## Importing a Pallet Crate

The first thing you need to do to add the Contracts pallet is to import the `pallet-contracts` crate in your runtime's `Cargo.toml` file. If you want a proper primer into Cargo References, you should check out [their official documentation](https://doc.rust-lang.org/cargo/reference/index.html).

Open `substrate-node-template/runtime/Cargo.toml` and you will see a list of all the dependencies your runtime has. For example, it depends on the [Balances pallet](https://substrate.dev/rustdocs/v3.0.0/pallet_balances/):

**`runtime/Cargo.toml`**

```toml
[dependencies]
pallet-balances = { default-features = false, version = '3.0.0' }
```

## Crate Features

One important thing we need to call out with importing pallet crates is making sure to set up the crate `features` correctly. In the code snippet above, you will notice that we set `default_features = false`. If you explore the `Cargo.toml` file even closer, you will find something like:

**`runtime/Cargo.toml`**

```toml
[features]
default = ['std']
std = [
    'codec/std',
    'frame-executive/std',
    'frame-support/std',
    'frame-system/std',
    'frame-system-rpc-runtime-api/std',
    'pallet-balances/std',
    #--snip--
]
```

This second line defines the `default` features of your runtime crate as `std`. You can imagine, each pallet crate has a similar configuration defining the default feature for the crate. Your feature will determine the features that should be used on downstream dependencies. For example, the snippet above should be read as:

> The default feature for this Substrate runtime is `std`. When `std` feature is enabled for the runtime, `parity-scale-codec`, `primitives`, `client`, and all the other listed dependencies should use their `std` feature too.

This is important to enable the Substrate runtime to compile to both native binaries $which support Rust [`std`](https://doc.rust-lang.org/std/)$ and Wasm binaries $which do not: [`no_std`](https://rust-embedded.github.io/book/intro/no-std.html)$.

To see how these features actually get used in the runtime code, we can open the project file:

**`runtime/src/lib.rs`**

```rust
//! The Substrate Node Template runtime. This can be compiled with `#[no_std]`, ready for Wasm.

#![cfg_attr(not(feature = "std"), no_std)]
// `construct_runtime!` does a lot of recursion and requires us to increase the limit to 256.
#![recursion_limit="256"]

// Make the Wasm binary available.
#[cfg(feature = "std")]
include!(concat!(env!("OUT_DIR"), "/wasm_binary.rs"));

// --snip--
```

You can see that at the top of the file, we define that we will use `no_std` when we are _not_ using the `std` feature. A few lines lower you can see `#[cfg(feature = "std")]` above the `wasm_binary.rs` import, which is a flag saying to only import the Wasm binary when we have enabled the `std` feature.

## Importing the Contracts Pallet Crate

Okay, now that we have covered the basics of crate features, we can actually import the Contracts pallet. The Contracts pallet is probably the most complicated pallet in FRAME, so it makes for a good example of some of the trickiness that can be involved when adding additional pallets.

First we will add the new dependency by simply copying an existing pallet, and changing the values. So based on the `balances` import shown above, the `contracts` import will look like:

**`runtime/Cargo.toml`**

```toml
[dependencies]
#--snip--
pallet-contracts = { default-features = false, version = '3.0.0' }
pallet-contracts-primitives = { default-features = false, version = '3.0.0' }
```

As with other pallets, the Contracts pallet has an `std` feature. We should build its `std` feature when the runtime is built with its own `std` feature. Add the following two lines to the runtime's `std` feature.

**`runtime/Cargo.toml`**

```toml
[features]
default = ['std']
std = [
    #--snip--
    'pallet-contracts/std',
    'pallet-contracts-primitives/std',
    #--snip--
]
```

## Adding the Contracts Pallet

Now that we have successfully imported the Contracts pallet crate, we need to add it to our Runtime.

### Implementing the Contract Trait

Every pallet has a configuration trait called `Config` that the runtime must implement.

To figure out what we need to implement for this pallet specifically, you can take a look at the FRAME

[`pallet_contracts::Config` documentation](https://substrate.dev/rustdocs/v3.0.0/pallet_contracts/trait.Config.html).

For our runtime, the implementation will look like this:

**`runtime/src/lib.rs`**

```rust
use pallet_transaction_payment::CurrencyAdapter;
   /* --snip-- */

/*** Add This Line ***/
use pallet_contracts::weights::WeightInfo;

// These time units are defined in number of blocks.
   /* --snip-- */

/*** Add This Block ***/
// Contracts price units.
pub const MILLICENTS: Balance = 1_000_000_000;
pub const CENTS: Balance = 1_000 * MILLICENTS;
pub const DOLLARS: Balance = 100 * CENTS;

const fn deposit(items: u32, bytes: u32) -> Balance {
    items as Balance * 15 * CENTS + (bytes as Balance) * 6 * CENTS
}

/// We assume that ~10% of the block weight is consumed by `on_initalize` handlers.
/// This is used to limit the maximal weight of a single extrinsic.
const AVERAGE_ON_INITIALIZE_RATIO: Perbill = Perbill::from_percent(10);

/*** End Added Block ***/
```

```rust
impl pallet_timestamp::Config for Runtime {
    /* --snip-- */
}

/*** Add This Block ***/
parameter_types! {
    pub const TombstoneDeposit: Balance = deposit(
        1,
        sp_std::mem::size_of::<pallet_contracts::ContractInfo<Runtime>>() as u32
    );
    pub const DepositPerContract: Balance = TombstoneDeposit::get();
    pub const DepositPerStorageByte: Balance = deposit(0, 1);
    pub const DepositPerStorageItem: Balance = deposit(1, 0);
    pub RentFraction: Perbill = Perbill::from_rational_approximation(1u32, 30 * DAYS);
    pub const SurchargeReward: Balance = 150 * MILLICENTS;
    pub const SignedClaimHandicap: u32 = 2;
    pub const MaxDepth: u32 = 32;
    pub const MaxValueSize: u32 = 16 * 1024;
    // The lazy deletion runs inside on_initialize.
    pub DeletionWeightLimit: Weight = AVERAGE_ON_INITIALIZE_RATIO *
        BlockWeights::get().max_block;
    // The weight needed for decoding the queue should be less or equal than a fifth
    // of the overall weight dedicated to the lazy deletion.
    pub DeletionQueueDepth: u32 = ((DeletionWeightLimit::get() / (
            <Runtime as pallet_contracts::Config>::WeightInfo::on_initialize_per_queue_item(1) -
            <Runtime as pallet_contracts::Config>::WeightInfo::on_initialize_per_queue_item(0)
        )) / 5) as u32;
    pub MaxCodeSize: u32 = 128 * 1024;
}

impl pallet_contracts::Config for Runtime {
    type Time = Timestamp;
    type Randomness = RandomnessCollectiveFlip;
    type Currency = Balances;
    type Event = Event;
    type RentPayment = ();
    type SignedClaimHandicap = SignedClaimHandicap;
    type TombstoneDeposit = TombstoneDeposit;
    type DepositPerContract = DepositPerContract;
    type DepositPerStorageByte = DepositPerStorageByte;
    type DepositPerStorageItem = DepositPerStorageItem;
    type RentFraction = RentFraction;
    type SurchargeReward = SurchargeReward;
    type MaxDepth = MaxDepth;
    type MaxValueSize = MaxValueSize;
    type WeightPrice = pallet_transaction_payment::Module<Self>;
    type WeightInfo = pallet_contracts::weights::SubstrateWeight<Self>;
    type ChainExtension = ();
    type DeletionQueueDepth = DeletionQueueDepth;
    type DeletionWeightLimit = DeletionWeightLimit;
    type MaxCodeSize = MaxCodeSize;
}
/*** End Added Block ***/
```

At this point, it is recommended to explore the [Contracts pallet source code](https://github.com/paritytech/substrate/blob/v3.0.0/frame/contracts/src/lib.rs) if things don't make sense or you want to gain a deeper understanding.

## Adding Contracts to the construct_runtime! Macro

Next, we need to add the pallet to the `construct_runtime!` macro. For this, we need to determine the types that the pallet exposes so that we can tell our runtime that they exist. The complete list of possible types can be found in the [`construct_runtime!` macro documentation](https://substrate.dev/rustdocs/v3.0.0/frame_support/macro.construct_runtime.html).

If we look at the Contracts pallet in detail, we know it has:

* Module **Storage**: Because it uses the `decl_storage!` macro.
* Module **Event**: Because it uses the `decl_event!` macro.
* **Call**able Functions: Because it has dispatchable functions in the `decl_module!` macro.
* **Config**uration Values: Because the `decl_storage!` macro has `config()` parameters.
* The **Module** type from the `decl_module!` macro.

Thus, when we add the pallet, it will look like this:

**`runtime/src/lib.rs`**

```rust
construct_runtime!(
    pub enum Runtime where
        Block = Block,
        NodeBlock = opaque::Block,
        UncheckedExtrinsic = UncheckedExtrinsic
    {
        /* --snip-- */

        /*** Add This Line ***/
        Contracts: pallet_contracts::{Module, Call, Config<T>, Storage, Event<T>},
    }
);
```

Note that not all pallets will expose all of these runtime types, and some may expose more than just these! Always look at the source code of a pallet or the documentation of the pallet you're using to determine which of these types you need to expose.

This is another good time to check that your runtime compiles correctly so far. Although the runtime should compile, the entire node will not $yet$. So we will use this command to just check the runtime only:

```rust
cargo check -p node-template-runtime
```

## Exposing The Contracts API

Some pallets, including the Contracts pallet, expose custom runtime APIs and RPC endpoints. In the case of the Contracts pallet, this enables reading contracts state from off chain.

It's not required to enable the RPC calls on the Contracts pallet to use it in our chain. However, we'll do it to make calls to our node's storage without making a transaction.

We start by adding the required API dependencies in our `Cargo.toml`.

**`runtime/Cargo.toml`**

```toml
[dependencies]
#--snip--
pallet-contracts-rpc-runtime-api = { default-features = false, version = '3.0.0' }
Copy
```

**`runtime/Cargo.toml`**

```toml
[features]
default = ['std']
std = [
    #--snip--
    'pallet-contracts-rpc-runtime-api/std',
]
```

Now we must add the `ContractsApi` dependency required to implement the Contracts runtime API. Add this with the other `use` statements.

To get the state of a contract variable, we have to call a getter function that will return a `ContractExecResult` wrapper with the current state of the execution.

**`runtime/src/lib.rs`**

We're now ready to implement the contracts runtime API. This happens in the `impl_runtime_apis!` macro near the end of your runtime.

```rust
impl_runtime_apis! {
   /* --snip-- */

   /*** Add This Block ***/
    impl pallet_contracts_rpc_runtime_api::ContractsApi<Block, AccountId, Balance, BlockNumber>
    for Runtime
    {
        fn call(
            origin: AccountId,
            dest: AccountId,
            value: Balance,
            gas_limit: u64,
            input_data: Vec<u8>,
        ) -> pallet_contracts_primitives::ContractExecResult {
            Contracts::bare_call(origin, dest, value, gas_limit, input_data)
        }

        fn get_storage(
            address: AccountId,
            key: [u8; 32],
        ) -> pallet_contracts_primitives::GetStorageResult {
            Contracts::get_storage(address, key)
        }

        fn rent_projection(
            address: AccountId,
        ) -> pallet_contracts_primitives::RentProjectionResult<BlockNumber> {
            Contracts::rent_projection(address)
        }
    }
   /*** End Added Block ***/
}
```

This is another good time to check that your runtime compiles correctly so far.

```rust
cargo check -p node-template-runtime
```

## Updating the Outer Node

At this point we have finished adding a pallet to the runtime. We now turn our attention to the outer node which will often need some corresponding updates. In the case of the Contracts pallet we will add the custom RPC endpoint and a genesis configuration.

### Adding the RPC API extension

With the proper runtime API exposed, now we can add the RPC to the node's service to call into that runtime API. Because we are now working in the outer node, we are not building to `no_std` and we don't have to maintain a dedicated `std` feature.

**`node/Cargo.toml`**

```toml
[dependencies]
jsonrpc-core = '15.1.0'
structopt = '0.3.8'
#--snip--
# *** Add these 2 lines ***
pallet-contracts  = '3.0.0'
pallet-contracts-rpc  = '3.0.0'
```

Substrate provides an RPC to interact with our node. However, it does not contain access to the Contracts pallet by default. To interact with this pallet, we have to extend the existing RPC and add the Contracts pallet along with its API.

**`node/src/rpc.rs`**

```rust
use node_template_runtime::{opaque::Block, AccountId, Balance, Index, BlockNumber}; // NOTE THIS IS AN ADJUSTMENT TO AN EXISTING LINE
use pallet_contracts_rpc::{Contracts, ContractsApi};
```

```rust
/// Instantiate all full RPC extensions.
pub fn create_full<C, P>(
    deps: FullDeps<C, P>,
) -> jsonrpc_core::IoHandler<sc_rpc::Metadata> where
    /* --snip-- */
    C: Send + Sync + 'static,
    C::Api: substrate_frame_rpc_system::AccountNonceApi<Block, AccountId, Index>,
    /*** Add This Line ***/
    C::Api: pallet_contracts_rpc::ContractsRuntimeApi<Block, AccountId, Balance, BlockNumber>,
    /* --snip-- */
{
    /* --snip-- */
    io.extend_with(
        TransactionPaymentApi::to_delegate(TransactionPayment::new(client.clone()))
    );
    /*** Add This Block ***/
    // Contracts RPC API extension
    io.extend_with(
        ContractsApi::to_delegate(Contracts::new(client.clone()))
    );
    /*** End Added Block ***/
    io
}
```

> Note: RPC additions must appear in this section in the expected syntax:

 ```rust
   // Extend this RPC with a custom API by using the following syntax.
   // `YourRpcStruct` should have a reference to a client, which is needed
   // to call into the runtime:
   // io.extend_with(YourRpcTrait::to_delegate(YourRpcStruct::new(ReferenceToClient, ...)));
 ```

## Genesis Configuration

Not all pallets will have a genesis configuration, but if yours does, you can use its documentation to learn about it. For example, [`pallet_contracts::GenesisConfig` documentation](https://substrate.dev/rustdocs/v3.0.0/pallet_contracts/struct.GenesisConfig.html) describes all the fields you need to define for the Contracts pallet.

Genesis configurations are controlled in `node/src/chain_spec.rs`. We need to modify this file to include the `ContractsConfig` type and the contract price units at the top:

**`node/src/chain_spec.rs`**

```rust
use node_template_runtime::ContractsConfig;
```

Then inside the `testnet_genesis` function we need to add our Contract pallet's configuration to the returned `GenesisConfig` object as followed:

> IMPORTANT: We are taking the value `_enable_println` from the function parameters. Make sure to remove the underscore that precedes the parameter definition.

```rust
/// Configure initial storage state for FRAME modules.
fn testnet_genesis(
    wasm_binary: &[u8],
    initial_authorities: Vec<(AuraId, GrandpaId)>,
    root_key: AccountId,
    endowed_accounts: Vec<AccountId>,
    enable_println: bool, // Update this line
) -> GenesisConfig {
    GenesisConfig {
        /* --snip-- */

        /*** Add This Block ***/
        pallet_contracts: Some(ContractsConfig {
            current_schedule: pallet_contracts::Schedule {
                    enable_println,
                    ..Default::default()
            },
        }),
        /*** End Added Block ***/
    }
}
```

## Start Your Upgraded Chain

Now you are ready to compile and run your contract-capable node. Compile the node in release mode with:

```text
cargo build --release
```

## Run a temporary node in development mode

Now launch the executable you just built by running this command:

```text
./target/release/node-template --dev --tmp
```

# Adding Other FRAME pallets

In this guide, we walked through specifically how to import the Contracts pallet, but as mentioned in the beginning of this guide, each pallet will be a little different. Have no fear, you can always refer to the [demonstration Substrate node runtime](https://github.com/paritytech/substrate/tree/v3.0.0/bin/node/runtime) which includes nearly every pallet in the FRAME.

In the `Cargo.toml` file of the Substrate node runtime, you will see an example of how to import each of the different pallets, and in the `lib.rs` file you will find how to add each pallet to your runtime. You can basically copy what was done there to your own runtime.


Learn how to add a contract pallet to a runtime

Add the Contracts Pallets to a Runtime

# Introduction

Polkadot allows blockchains and applications to come together and work with each other in parallel. To have a decentralized web, an internet of interoperable blockchains is key. **A sharded blockchain protocol.** Polkadot considers itself to be a next-generation blockchain, or better yet, a foundational network layer that will truly drive the "web 3.0 vision" to create a unified network of specialized, self-governed, optimal blockchains that work together via interoperability. Polkadot offers scalability through its shared model, where blockchains that used to operate in isolation can take advantage of the Polkadot architecture to eliminate bottlenecks and network traffic.

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/polkadot-graphic.jpg)

Bitcoin gave us the first real concept of a money protocol; a blockchain that is now generally accepted at being a store of value. Ethereum extended this idea to, well, almost anything - creating the next wave of new finance and allowing us to develop real-world applications on-chain through smart contracts. Polkadot aims to bring these blockchains together, along with many others, while supporting web 3.0 protocols and other key blockchain features on-chain - acting as an infrastructure for infrastructures.

This guide will outline key blockchain concepts through the eyes of Polkadot by creating distinctions and drawing conclusions for each concept. Namely, the focus will be on smart contracts, parachains, parathreads, and decentralized applications. The differences between common blockchain concepts within the Polkadot ecosystem can be best understood by appreciating Polkadot's vision to act as a foundational layer for web 3.0 protocols, that allows for arbitrary data $not just tokens$ to be transferred across blockchains.

This is done through _true interoperability_, _pooled security_, _heterogeneous chains_ and _thought-through governance_.

# Prerequisites

This tutorial aims to be beginner-friendly. Nonetheless, it is recommended that you are familiar with the following:

* [Polkadot Behind the Code, Episode 1](https://www.youtube.com/watch?v=GcOKXAOh4Xw)
* An understanding of Polkadot's architecture: [Polkadot: Are You Ready to Start Building?](https://www.youtube.com/watch?v=_-k0xkooSlA).
* [Getting Started with Polkadot](https://wiki.polkadot.network/docs/en/getting-started).

# Introduction to Advanced Concepts in Polkadot

## Polkadot and Smart Contracts

A `smart contract` is a set of instructions $in the form of code$ that are deployed on-chain. These instructions represent an agreement between parties that are presented as an executable computer program. The computer program is executed by a blockchain-based platform that enables the deployment of smart contracts. In other words, the smart contract allows for application-level source code to be deployed on-chain. The execution only takes place when predetermined conditions are met. External actors can call upon the smart contract only after it is executed on-chain. The smart contract that is created from the set of instructions will be associated with a specific chain address.

Polkadot itself does not enable the deployment of smart contracts. The Polkadot mainnet will have other chains connected that act as smart contract platforms. External chains that are connected on Polkadot are generally referred to as **Parachains**, which is explained below.

[Parity Technologies](https://www.parity.io/) is a core developer for the Polkadot network. Their main product, [Substrate](https://substrate.dev/en/) is a robust framework that can be used to develop blockchains seamlessly. Parachains are using Substrate to develop modern blockchains that will connect to the Polkadot network.

> **NOTE: There are different implementations of Polkadot. Parity Polkadot is the Rust client. Other implementations exist and are being worked on in C++, Go, and JavaScript. It is important to have multiple implementations of the Polkadot protocol to promote decentralization and progress the protocol in a meaningful way.**

If these external chains would like to offer support for smart contracts, they can do so using the [EVM Pallet](https://substrate.dev/docs/en/knowledgebase/smart-contracts/evm-pallet), which allows a parachain to implement the Ethereum Virtual Machine $[EVM](https://ethereum.org/en/developers/docs/evm/)$.

In addition, Substrate also offers a built-in [contract pallet](https://substrate.dev/rustdocs/v3.0.0/pallet_contracts/index.html) that parachains can adapt to. This provides the necessary specs for the deployment and execution of _WebAssembly_ smart contracts.

## Background

As the name suggests, the `Ethereum Virtual Machine` is a virtual machine for Ethereum. The EVM abstracts necessary computational resources into a virtual stack and acts as a runtime environment for smart contracts. [Solidity](https://docs.soliditylang.org/en/v0.8.4/#) is the programming language used for developing smart contracts that run on the EVM.

[WebAssembly](https://webassembly.org/) is an instruction format that works across the web and runs on modern web browsers.

**Fun Fact \[4\]:** The co-founder and former CTO of Ethereum, Dr. Gavin James Wood, who is also the founder of the [Web 3 Foundation](https://web3.foundation/) and [Parity Technologies](https://www.parity.io/), is an inventor of the Solidity language and was the initial proposer in 2014 \[4\].

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/polkadot-substrate-ethereum.png)

## Advantages of Smart Contracts

_**Trustfulness, Transparency, Reliability, Accuracy & Automative**_

* Smart contracts are Immutable: ensures that no one can tamper with or break the contract. The contract also

  holds integrity and credibility at the point in time it was executed.

* Smart contracts allow centralized use cases to be decentralized: some examples include decentralized finance

  $DeFi$, governance, and digital identity management.

## Disadvantages of Smart Contracts

_**Scalability, Limitations, Dependencies**_

* Traditional smart contracts can only exist on a single-chain: wanting to execute the same contract on a different

  chain requires its own smart contract to be deployed on that chain.

* Smart contracts are too general for most use-cases.
* Smart contracts are constrained by the properties of their host chain. 
* Smart contracts are dependant on their own ability to upgrade and must limit their own execution.
  * Because the smart contract is resource dependant, the code that is executed needs to use the resources of the chain's ecosystem. If there are aspects of the smart contract that are heavy on computational resources, this can be problematic, resulting in a halting problem. With a powerful language, it is impossible to know ahead of time whether or not a program will cease execution. Some platforms address this through a very restricted scripting language $e.g. Bitcoin$. Other web 3.0 ecosystems charge a fee, usually referred to as a "gas fee" - for the rights to execute the code on-chain and use those computational resources $e.g. Ethereum$. However, if a smart contract executes indefinitely, it will cease its own execution by "running out of gas". Limiting a smart contract's execution is also necessary for preventing DOS attacks.
  * Smart contracts are Immutable: if there are updates to be made in the code within the smart contract, that means an entirely new smart contract needs to be deployed that will be tied to a new chain address; anything referring to the previous chain address also needs to be moved over to the new chain address.

# What is a Parachain?

The Polkadot network has a central chain called the [relay chain](https://wiki.polkadot.network/docs/en/learn-architecture#relay-chain). Polkadot's Nominated Proof of Stake $NPoS$ model is used to select validators, allowing them to participate in the consensus protocol. These validators are staked on the Relay chain. Parachains are maintained by a network maintainer known as a [_collator_](https://wiki.polkadot.network/docs/en/learn-collator).

External chains can connect to the Relay chain as `Parachains`. A parachain is an individual blockchain that runs in parallel on the Polkadot network. As such, parachains can also be considered "parallelizable chains" \[5\].

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/one_parachain.png)

Polkadot is considered to be a _layer-0 multi-chain network_, and Parachains run in parallel as individual _layer-1 blockchains_. For reference, _Bitcoin_ and _Ethereum_ are considered to be layer-1 blockchains. The parachain model allows for individual blockchains to achieve scalability at layer-1 \[3\].

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/polkadot-relay-chain.png)

> A prominent issue in the Ethereum ecosystem is the ability to scale where a dependency is created on possible _layer-2_ scaling solutions.

## Comparing Parachains and Smart Contracts

After developing a smart contract, the next thing to do is to deploy it. This means there is a need for a target chain, where the target chain has its own environment. Using a parachain, the developer can declare the environment of their own chain. Parachains can also upgrade themselves through a root command or the governance pallet, allowing developers to update code. This is an essential parachain feature to prevent forks - unlike smart contracts, which have exhaustive upgrade issues.

Polkadot does not use a _gas-metering model_, but a _weight-fee model_, meaning Parachains do not have a gas-metered model in their logic. Parachains can implement powerful programming languages. Better put, parachains try to be proactive, while smart contract platforms are event-driven.

Using Ethereum as an example of a smart contract platform:

Ethereum

* Smart contracts can call each other synchronously in the same shard.
* Smart contracts can call each other asynchronously between shards.

Polkadot

* Smart contracts can call each other synchronously in the same parachain.
* Smart contracts can call each other asynchronously across parachains.

## Benefits in becoming a Parachain

_**Security, Scability, Developer friendly, On-chain Governance, Crowdloan functionality**_

* Substrate development is component-based and abstracts the nitty-gritty of blockchain development so the

  developer can focus on what matters.

* Any chain connected to the relay chain shares the security of all chains active on the network.
* Block Verification and finalization are performed by the validators on the relay chain.
* Ability to send messages to other chains through [XCMP](https://wiki.polkadot.network/docs/en/learn-crosschain#docsNav).
* On-chain governance as compared to other platforms that have off-chain governance.

Parachain's participation on polkadot is auction-based and requires the parachain to secure an available parachain slot on the relay chain.

## What about Parathreads?

`Parathreads` are parachains that do not stay connected to the relay chain. Parathreads are essentially pay-as-you-go parachains and temporarily participate on the network on a per-block basis \[2\].

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/parathread-pool.png)

The main difference between parachains and parathreads is **economic**. A parachain auction happens every six months for securing a slot on the network. A fee auction happens every block for a parathread.

# Polkadot and dApps

`dApp` stands for decentralized application; no single entity has complete control. dApps run on peer-to-peer, distributed networks. Smart contracts are known as the core pillar for dApps, as application-level source code is within the logic of the contract itself. Since the apps are based on a decentralized blockchain, there is an incentivization system for the validators through some form of digital asset $often a token$. A dApp requires a consensus mechanism to convey the proof of value in the system.

**WASM vs EVM: Why Substrate encourages WebAssembly**

Every blockchain ecosystem essentially needs a virtual machine to process events on-chain. The EVM is considered to be a lightweight Virtual Machine that allows you to run smart contracts on the Ethereum network. There are some problems currently facing the EVM that ultimately limit the throughput of the network and create a bottleneck.

* The EVM isn’t as fast as it should be and directly impact network efficiency.
* The EVM uses opcodes that are not optimized for different hardware platforms.
* The support and reach for developing smart contracts are limited.

`Wasm`, or WebAssembly, was developed by the World Wide Web Consortium $W3C$; it is essentially a new type of code that can execute directly on the browser.

* Wasm expands the supported languages that a developer can write a smart contract in, such as Rust, C/C++, C\#, and Typescript.
* Wasm is high performance.
* Wasm is optimized for different hardware platforms.

This [article](https://www.parity.io/wasm-smart-contract-development/#:~:text=While%20Wasm%20itself%20benefits%20from,and%20interact%20with%20the%20blockchain) offers a perspective from Parity Technologies about WebAssembly being an alternative to the EVM.

_**Runtime development is different than dApp development**_

* Using a smart contract platform to develop a dApp allows the developer to focus on the logic within the contract itself. Deploying a dApp on a parachain is different than creating a parachain as this requires runtime development. Each parachain can have a unique implementation with its own runtime logic. Generally, there are two approaches to dApp development on Polkadot:
  1. Develop dApp in Wasm where it will run on a native parachain.
  2. Deploy a dApp via Solidity on an EVM-based chain.

_**Building a dApp on Polkadot can be seen as building a dApp on a Substrate-based chain**_

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/parachains-substrate-polkadot-venn-diagram-1.png)

> NOTE: Remember, Polkadot supports parachains that are not built on Substrate. Chains can also be built on Substrate and are not required to be deployed onto Polkadot \[1\].

# Conclusion

Congratulations! This tutorial offered a friendly architectural view of Polkadot, in the eyes of Polkadot. The tutorial branched off from "what the blockchain space has" to "where it's going" by discussing the differences between smart contracts, parachains, parathreads and DApps.

# What's next?

To dive more into these concepts, see the following pages on the official Polkadot Wiki.

* [Architecture](https://wiki.polkadot.network/docs/en/learn-architecture)
* [Smart Contracts](https://wiki.polkadot.network/docs/en/build-smart-contracts)
* [Parachains](https://wiki.polkadot.network/docs/en/learn-parachains)
* [Parathreads](https://wiki.polkadot.network/docs/en/learn-parathreads)
* [Glossary](https://wiki.polkadot.network/docs/en/glossary)

Why not try building your first Substrate-based chain!

# About the Author

This guide was created by Danny Salman. You can reach out to Danny on [Figment Forum](https://community.figment.io/u/salman.danny03/) & on GitHub for help or if you have questions pertaining to Polkadot and this guide.

# References

\[1\] [A brief summary of everything Substrate and Polkadot](https://www.parity.io/a-brief-summary-of-everything-substrate-polkadot/)  
\[2\] [Parathreads: Pay-as-you-go Parachains](https://polkadot.network/parathreads-parathreads-pay-as-you-go-parachains/)  
\[3\] [Polkadot: The Foundation of a New Internet](https://medium.com/polkadot-network/polkadot-the-foundation-of-a-new-internet-e8800ec81c7)  
\[4\] [Polkadot, Substrate and Ethereum](https://medium.com/polkadot-network/polkadot-substrate-and-ethereum-f0bf1ccbfd13)  
\[5\] [Research at Web3 Foundation](https://research.web3.foundation/en/latest/polkadot/overview/1-polkadot-introduction.html?highlight=parachains)



Polkadot Blockchain Terms

# Part I: Basic set-up

> This tutorial assumes that you have already installed the prerequisites for building with Substrate on your machine. If you haven't already, head over to our [installation guide][installation].

## Overview

Before we can start making Kitties, we first need to do a little groundwork. This part covers the basic patterns involved with using the Substrate Node Template to set up a custom pallet and include a simple storage item.

## Learning outcomes

➡️ Renaming a Substrate Node Template using the Kickstart tool.

➡️ Basic patterns for building and running a Substrate node.

➡️ Create a storage item to keep track of a single `u64` value.

# Steps

## Set-up your template node

The [Substrate Node Template][substrate-node-template] provides us with an "out-of-the-box" blockchain node. Our biggest advantage
in using it are that both networking and consensus layers are already built and all we need to focus on is building out
our [runtime][runtime-kb] and [pallet][pallets-kb] logic. Before we get there, we need to set-up our project in terms of naming and dependencies.

We'll use a CLI tool called [kickstart][kickstart-tool] to easily rename our node template.

In the root directory of your local workspace, run the following command:

```text
kickstart https://github.com/sacha-l/kickstart-substrate
```

This command will clone a copy of the most recent Node Template and ask you would like to call your node and pallet. Type in:

- `kitties` - as the name of our node
- `mykitties` - as the name of your pallet

This will create a directory called `kitties` with a copy of the [Substrate Node Template][substrate-node-template] containing the name changes that correspond our template node, runtime and pallet.

Open the `kitties` directory in your favorite code editor and rename it to `kitties-tutorial`. Renaming this directory will be helpful once you start creating other projects with the node template &mdash; it'll help keep things organized! 

> Notice the directories that the `kickstart` command modified:
>
> - **`/node/`** - This contains all the logic that allows your node to interact with your runtime and RPC clients.
> - **`/pallets/`** - Here's where all your custom pallets live.
> - **`/runtime/`** - This is where all pallets (both custom "internal" and "external" ones) are aggregated and implemented for the chain's runtime.

By default, you'll notice that the instance of our modified template pallet name remains `TemplateModule`. Change it to
`SubstrateKitties` (in `runtime/src/lib.rs`):

```rust
construct_runtime!(
    pub enum Runtime where
    Block = Block,
    NodeBlock = opaque::Block,
    UncheckedExtrinsic = UncheckedExtrinsic
    {
        // --snip
        SubstrateKitties: pallet_mykitties::{Pallet, Call, Storage, Event<T>},
    }
);
```

We can already build the node as is by navigating to directory `kitties` in terminal and running this command:

```text
cargo +nightly build --release
```

It's normal if this command takes a little while depending on your machine &mdash; it's building 
a whole bunch of crates from the Substrate crates and libraries. The nice thing is that once we run this command the first time, it
won't need to rebuild all the crates when we build subsequent times.

Assuming that your node builds successfully, launch it in development mode to make sure it works:

```text
./target/release/node-kitties --tmp --dev
```

You should see blocks being created in your terminal. The `--tmp` and `--dev` flags mean we're running a temporary node in development mode. 

## Write out pallet_kitties scaffold

We'll be spending most of this tutorial in the `pallets` directory of our template node.
Let's take a glance at the folder structure in our workspace:

```text
kitties-tutorial           <--  The name of our project directory
|
+-- node
|
+-- pallets
|   |
|   +-- mykitties           
|       |
|       +-- Cargo.toml     
|       |
|       +-- src
|           |
|           +-- lib.rs     <-- Remove contents
|           |
|           +-- mock.rs    <-- Remove file
|           |
|           +-- tests.rs   <-- Remove file
|
+-- Cargo.toml              
```

> You can go ahead and remove `mock.rs` and `tests.rs`. **We won't be learning about using these in this tutorial.** Have a look at [this how-to guide](https://substrate.dev/substrate-how-to-guides/docs/testing/test-transfer) if you're curious to learn how testing works.

[Pallets][pallets-kb] in Substrate are used to define runtime logic. In our case, we'll be creating a single pallet that manages all of the
logic of our Substrate Kitties application.

Let's lay out the basic structure of our pallet by outlining the parts inside the `pallets/mykitties/src/lib.rs`. 

> Our pallet's directory `pallets/mykitties/` is not the same as our pallet's name. The name of our pallet as Cargo understands it is `pallet-mykitties`.

Every FRAME pallet has:

- A set of `frame_support` and `frame_system` dependencies.
- Required [attribute macros][macros-kb] (i.e. configuration traits, storage items and function calls).

> We'll be updating additional dependencies as we progress through the next parts of this tutorial.

Here's the most bare-bones version of the Kitties pallet we will be building in this tutorial. It contains the starting point for 
adding code for the next sections of this tutorial, with comments marked with "TODO" to indicate code we will be writing later, and 
"ACTION" to indicate code that will be written in the current part of the tutorial.

Paste the following code in `/pallets/mykitties/src/lib.rs`: 

```rust
#![cfg_attr(not(feature = "std"), no_std)]

pub use pallet::*;

#[frame_support::pallet]
pub mod pallet {
    use frame_support::{sp_runtime::traits::{Hash, Zero},
                        dispatch::{DispatchResultWithPostInfo, DispatchResult}, 
                        traits::{Currency, ExistenceRequirement, Randomness},
                        pallet_prelude::*};
    use frame_system::pallet_prelude::*;
    use sp_core::H256;

    // TODO Part II: Struct for holding Kitty information.

    // TODO Part II: Enum and implementation to handle Gender type in Kitty struct.

    #[pallet::pallet]
    #[pallet::generate_store(trait Store)]
    pub struct Pallet<T>(_);

    /// Configure the pallet by specifying the parameters and types it depends on.
    #[pallet::config]
    pub trait Config: pallet_balances::Config + frame_system::Config {
        /// Because this pallet emits events, it depends on the runtime's definition of an event.
        type Event: From<Event<Self>> + IsType<<Self as frame_system::Config>::Event>;

        // TODO Part II: The type of Random we want to specify for runtime.
    }

    // Errors.
    #[pallet::error]
    pub enum Error<T> {
        // TODO Part III
    }

    #[pallet::event]
    #[pallet::metadata(T::AccountId = "AccountId")]
    #[pallet::generate_deposit(pub(super) fn deposit_event)]
    pub enum Event<T: Config> {
        // TODO Part III
    }

    // ACTION: Storage item to keep track of all Kitties.

    // TODO Part II: Remaining storage items.

    // TODO Part III: Our pallet's genesis configuration.

    #[pallet::call]
    impl<T: Config> Pallet<T> {
        
        // TODO Part III: create_kitty
        
        // TODO Part III: set_price
        
        // TODO Part III: transfer

        // TODO Part III: buy_kitty
        
        // TODO Part III: breed_kitty
    }

    // TODO Parts II: helper function for Kitty struct

    impl<T: Config> Pallet<T> {
        // TODO Part III: helper functions for dispatchable functions
        
        // TODO: increment_nonce, random_hash, mint, transfer_from
        
    }
}
```

> Your turn! Copy over the bare-bones of the Kitties pallet into `mykitties/src/lib.rs`.


Now try running the following command to rebuild your chain:

```text
cargo +nightly build --release
```

Get an error about dependencies? That's normal! Our pallet structure is using FRAME's `pallet-balances` and `sp-io` 
but these aren't part of the node template we used so we must specify them ourselves. In `pallets/mykitties/Cargo.toml`, 
add the following:

```toml
[dependencies.sp-core]
default-features = false
git = 'https://github.com/paritytech/substrate.git'
tag = 'monthly-2021-08'
version = '4.0.0-dev'

[dependencies.pallet-balances]
default-features = false
git = 'https://github.com/paritytech/substrate.git'
tag = 'monthly-2021-08'
version = '4.0.0-dev'
```

> WARNING! Check that you're using the correct `monthly-*` tag and `version` otherwise you will get a dependency error. Here, we're using the most up-to-date tag as of the writing of this tutorial.

Now run `cargo +nightly build --release` again to make sure it builds without errors.

You'll notice the Rust compiler giving you warnings about unused imports. That's fine! Just ignore them &mdash; we're going to be using those imports in the later parts of the tutorial.

In the next step we will include the first storage item our Kitty application will require.

## Include a storage item to track all Kitties

Let's start by adding the most simple logic we can to our runtime: a function which stores a variable in runtime.

To do this we'll use [`StorageValue`][storagevalue-rustdocs] from Substrate's [storage API][storage-api-rustdocs] which is a trait that depends
on the [storage macro][storage-macro-kb].

All that means for our purposes is that for any storage item we want to declare, we must include the `#[pallet::storage]`  macro beforehand. Learn more about declaring storage items [click here](https://substrate.dev/docs/en/knowledgebase/runtime/storage#declaring-storage-items). 

In `mykitties/src/lib.rs`, replace the ACTION line with: 

```rust
    #[pallet::storage]
    #[pallet::getter(fn all_kitties_count)]
    pub(super) type AllKittiesCount<T: Config> = StorageValue<
        _, 
        u64, 
        ValueQuery
        >;
```

This creates a storage item for our pallet to keep track of a counter that will correspond to the total amount of Kitties
in existence.

## Build pallet

From the previous step, your pallet should contain a storage item called `AllKittiesCount` which keeps track of a
single `u64` value. As part of the basic setup, we're doing great!

>As mentioned in the [overview of this tutorial series](https://learn.figment.io/tutorials/substrate-kitties-overview), you'll be implementing a total of 9 storage items which you'll discover as you write out your pallet's logic in the next parts.

Before we move on, let's make sure everything compiles. We don't need to rebuild our entire node each time we update our pallet.
Instead, we can use a command that only builds our pallet. From inside your pallet directory, run the following:

```text
cargo build -p pallet-mykitties
```

Does your pallet compile without error? Well done if it does! If not, go back and check that all the macros are in place and that 
you've included the FRAME dependencies.

> Congratulations! You've completed the first part of this series. At this stage, you've learnt the various patterns for:
>
> - Customizing the Substrate node template and including a custom pallet.
> - Building a Substrate chain and checking that a target pallet compiles.
> - Declaring a single value `u64` storage item.

# Next steps

- Writing a struct in a `StorageMap` to store details about our Kitties
- Using the Randomness trait to create unique Kitties
- Creating our pallet's remaining storage items

[Click here](https://learn.figment.io/tutorials/substrate-kitties-create-kitties) to go to the next part of this tutorial series.

[installation]: https://substrate.dev/docs/en/knowledgebase/getting-started/
[substrate-node-template]: https://github.com/substrate-developer-hub/substrate-node-template
[pallets-kb]: https://substrate.dev/docs/en/knowledgebase/runtime/pallets
[macros-kb]: https://substrate.dev/docs/en/knowledgebase/runtime/macros#frame-v2-macros-and-attributes
[storagevalue-rustdocs]: https://substrate.dev/rustdocs/v3.0.0/frame_support/storage/trait.StorageValue.html
[storage-api-rustdocs]: https://substrate.dev/rustdocs/v3.0.0/frame_support/storage/index.html
[template-code]: https://github.com/substrate-developer-hub/substrate-how-to-guides/tree/main/static/code/kitties-tutorial
[runtime-kb]: https://substrate.dev/docs/en/knowledgebase/runtime/
[kickstart-tool]: https://github.com/Keats/kickstart
[storage-macro-kb]: https://substrate.dev/docs/en/knowledgebase/runtime/macros#palletstorage


Learn how to use the Substrate Node template

Substrate Kitties - Basic Setup

In this tutorial, we'll learn how to restore a wallet from a mnemonic and how to derive the address and the private key when the wallet has been restored.

Ready? Let's go!

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/polkadot/restore.ts`, implement the function and try to restore your account using your mnemonic. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const { mnemonic } = req.body;
    const keyring = undefined;
    const account = undefined;
    const address = undefined;
    res.status(200).json(address);
  }
//...
```

**Need some help?** Check out these links
* [**Keyring Basics**](https://polkadot.js.org/docs/keyring/start/basics)  
* [**Using address or publicKey**](https://polkadot.js.org/docs/keyring/start/sign-verify#verify-using-address-or-publickey)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const { mnemonic } = req.body;  
    const keyring = new Keyring({type: 'sr25519'});
    const account = keyring.addFromUri(mnemonic);
    const address = account.address;
    res.status(200).json(address);
  }
//...
```

**What happened in the code above?**

* First, we create a new `Keyring` instance of the `sr25519` type.
* Then we can use the `addFromUri` method to add the supplied mnemonic to the keyring - this is the account.
* We can now access the public address via the `address` property of the `account`.
* Finally, we send the address of the account back to the client-side as JSON.
------------------------

# Make sure it works

When you have completed the code, click on **Restore Account**

![](../../../.gitbook/assets/pathways/polkadot/polkadot-restore.gif)

-----------------------------

# Conclusion

The ability to restore an account without requiring a third party is a great feature of **Polkadot**. Now, we're ready to go further and prepare our first transaction. In the next tutorial, we're going to learn how to estimate the fees required to submit a simple transfer.


In this tutorial, we'll how one can restore an account from mnemonic

Restore an account

# Introduction

Welcome to the Substrate Kitties tutorial. This 4 part tutorial series will teach you everything you need to know to build a blockchain designed to handle the creation and ownership management of Substrate Kitties. Before jumping into the next section, let's have a look at what we'll be doing.

_This is a 4 part tutorial series that steps you through building a dApp for managing Substrate Kitties from scratch. Each part could take 30-60 minutes to complete depending on your level of experience._
_This tutorial only covers the blockchain part and does not include the front-end part._

> You may find it useful to come back to this page as you progress through each part &mdash; just to keep track of the bigger picture.

[**Part I**:](https://learn.figment.io/tutorials/substrate-kitties-setup) Basic setup

[**Part II**:](https://learn.figment.io/tutorials/substrate-kitties-create-kitties) Uniqueness, custom types & storage maps

[**Part III**:](https://learn.figment.io/tutorials/substrate-kitties-dispatchables-and-events) Dispatchables, Events and Errors

[**Part IV**:](https://learn.figment.io/tutorials/substrate-kitties-interacting-functions) Interacting with your Kitties

# Learning outcomes

➡️ Write and integrate a custom FRAME pallet to your runtime.

➡️ Use structs in storage and how to create and update storage items.

➡️ Write extrinsics and helper functions.

# What we're building

In this tutorial, we'll intentionally keep things simple so that you can decide on how you'd like to improve your Substrate Kitties chain. For the purposes of what we're building, Kitties really can only do the following things:

😺 Be created either by some original source or by being bred using existing Kitties.

😼 Be sold at a price set by their owner.

😿 Be transferred from one owner to another.

# What we won't cover

The following fall outside the scope of this tutorial:

 - Writing tests for our pallet.
 - Declaring a configuration for the genesis of our chain.
 - Customize frontend for our Substrate Kitties.

 You can refer to the [Substrate how-to guides](https://substrate.dev/substrate-how-to-guides/docs/intro/) on how to do this once you've completed this tutorial series.

---

Bringing things down to a more granular level, this translates to the following application design:

1. [**Basic setup**](https://learn.figment.io/tutorials/substrate-kitties-setup). We'll need to spin up a Substrate node and create a custom pallet

2. [**Runtime storage**](https://learn.figment.io/tutorials/substrate-kitties-setup). We'll need a total of 9 storage items in our pallet to keep track of the amount of Kitties; their index; their owners and their
   owner account IDs.

3. [**Dispatchable functions**](https://learn.figment.io/tutorials/substrate-kitties-dispatchables-and-events). We'll need a total of 5 dispatchable functions: `create`, `set_price`, `transfer`, `buy_kitty` and `breed_kitty`

4. [**Private functions**](https://learn.figment.io/tutorials/substrate-kitties-create-kitties). We'll write 2 helper functions to handle randomness: `increment_nonce` and `random_hash`

5. [**Helper functions**](https://learn.figment.io/tutorials/substrate-kitties-interacting-functions). We'll write 2 helper functions for our dispatchable functions: `mint` and `transfer_from`.

> Follow each step at your own pace &mdash; the goal is for you to learn and the best way to do that is to try it yourself! Before moving on from one section to the next, make sure your pallet builds without any error. You'll be writing most of the code yourself! Use the template files [here](https://github.com/substrate-developer-hub/substrate-how-to-guides/tree/main/static/code/kitties-tutorial) to help you complete each part.

[Click here](https://learn.figment.io/tutorials/substrate-kitties-setup) to go to get started with the project setup!


Substrate Kitties Overview

In this tutorial we will cover the process of creating a multisig - an account which shares authority for transactions across multiple addresses.

Implement Multisig Accounts on Polkadot

Learn how to add a pallet to your runtime

Add A Pallet To Your Runtime

# What is Polkadot?

Polkadot enables scalability by allowing specialized blockchains to communicate with each other in a secure, trust-free environment.

Polkadot is built to connect and secure unique blockchains, whether they be public, permission-less networks, private consortium chains, or oracles and other Web3 technologies. It enables an internet where independent blockchains can exchange information under common security guarantees.

Polkadot is a living network with the core pillars of governance and upgradeability. The network has an advanced suite of governance tools and, using the [WebAssembly](https://webassembly.org/) standard as a "meta-protocol", can autonomously deploy network upgrades. Polkadot adapts to your growing needs without the risks of network forks.

By connecting these dots, Polkadot serves as a foundational part of a decentralized web, where users control their data and are not limited by trust bounds within the network.

## Why build in the Polkadot ecosystem?

Polkadot is a sharded blockchain, meaning it connects several chains together in a single network, allowing them to process transactions in parallel and exchange data between chains with security guarantees.

Developers can build application-specific chains using [Substrate](https://www.substrate.io/) optimized for their unique use case. Here are the advantages of the Substrate framework and the Polkadot ecosystem:

1. Native Polkadot compatibility: Any blockchain built with Substrate will be natively compatible with Polkadot, so when the mainnet comes you can connect to Polkadot as a parachain.
2. Interchain Connectivity: By connecting your blockchain to Polkadot, your blockchain will be able to pass arbitrary messages to other chains in the Polkadot network.
3. Fork-free upgrades: Upgrade your blockchain without a hard fork. Your runtime is a Wasm binary stored on-chain and can be updated using your chain’s governance mechanism.
4. Instant security: Simply by connecting your blockchain to Polkadot, your blockchain will be secured by Polkadot's [pooled security](https://medium.com/polkadot-network/how-polkadot-tackles-the-biggest-problems-facing-blockchain-innovators-1affc1309b0f).
5. Plug-and-play modular framework: Substrate allows you to simply plug in the functionalities you need, while also giving you the freedom to customize as needed.
6. Multiple Languages:** With Substrate, you can write your blockchain logic in any language that can compile to WebAssembly (Rust, C/C++, C#, Go, etc).

## What can you build on Polkadot?

Substrate comes with everything you need to build your blockchain. Use Substrate’s pallets to easily create what you want, or craft your own custom logic. The Polkadot ecosystem already hosts over 100 application-specific blockchains in development, focus on smart contracts, DeFi, IoT, governance, identity, privacy, and more.

# Network Specifications

## Transaction Fees

Polkadot uses a weight-based fee model as opposed to a gas-metering model. As such, fees are charged prior to transaction execution; once the fee is paid (in DOT), nodes will execute the transaction.

Fees on the Polkadot Relay Chain are calculated based on three parameters:

* A per-byte fee (also known as the "length fee")
* A weight fee
* A tip (optional)

The length fee is the product of a constant per-byte fee and the size of the transaction in bytes.

## Transaction Speed & Finality

While custom consensus mechanics can be implemented for your application-specific blockchain, Polkadot's finality protocol finalizes batches of blocks based on availability and validity checks that happen as the proposed chain grows.

The time to finality varies with the number of checks that need to be performed (and invalidity reports cause the protocol to require extra checks). The expected time to finality is 12-60 seconds on the relay chain.

## Languages supported

Polkadot has [implementations in various programming languages](https://wiki.polkadot.network/docs/en/learn-implementations) ranging from Rust to JavaScript. Currently, the leading implementation is built in Rust and built using the Substrate framework.

With Substrate, you can write your blockchain logic in any language that can compile to WebAssembly (Rust, C/C++, C#, Go, etc).

## EVM compatibility

Substrate EVM will allow Substrate-based blockchains, including Polkadot parachains, to host a nearly-complete instance of the Ethereum state transition function on-chain, alongside any additional Substrate modules as required for custom functionality.

Existing Solidity applications can be deployed and executed in this environment, and will gain the added benefits of being part of a Substrate-based blockchain.

## Role of the DOT token

DOT serve three key functions in Polkadot:

* to be used for governance of the network,
* to be staked for operation of the network,
* to be bonded to connect a chain to Polkadot as a parachain.

DOT can also serve ancillary functions by virtue of being a transferrable token. For example, DOT stored in the Treasury can be sent to teams working on relevant projects for the Polkadot network.


Learn how Polkadot works and what makes it special

Introduction

Learn to create a custom "Proof of Existence" dApp using the Substrate blockchain development framework and FRAME runtime libraries