--- category: Basics includes_base_categories: false base_categories: [] word_count: 39973 token_estimate: 63784 page_count: 32 build_timestamp: '2026-06-25T12:38:13.291384+00:00' version_hash: sha256:e7fba57ab6a83440fe8ef8ea669cad51456e0b1cdc27bbdb1cee823e987250e2 --- # Begin New Bundle: Basics --- Page Title: Blocks - Resolved Markdown: https://docs.polkadot.com/reference/parachains/blocks-transactions-fees/blocks.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/blocks-transactions-fees/blocks/ - Summary: Understand how blocks are produced, validated, and imported in Polkadot SDK-based blockchains, covering initialization, finalization, and authoring processes. - Word Count: 888; Token Estimate: 1331 - Last Updated: 2026-01-14T11:42:16+00:00 - Version Hash: sha256:fc4e5d8c317678c48e4349628c27d47fb8188752ee36a5d1f29e9408f18c22b0 # Blocks ## Introduction In the Polkadot SDK, blocks are fundamental to the functioning of the blockchain, serving as containers for [transactions](/reference/parachains/blocks-transactions-fees/transactions/) and changes to the chain's state. Blocks consist of headers and an array of transactions, ensuring the integrity and validity of operations on the network. This guide explores the essential components of a block, the process of block production, and how blocks are validated and imported across the network. By understanding these concepts, developers can better grasp how blockchains maintain security, consistency, and performance within the Polkadot ecosystem. ## What is a Block? In the Polkadot SDK, a block is a fundamental unit that encapsulates both the header and an array of transactions. The block header includes critical metadata to ensure the integrity and sequence of the blockchain. Here's a breakdown of its components: - **Block height**: Indicates the number of blocks created in the chain so far. - **Parent hash**: The hash of the previous block, providing a link to maintain the blockchain's immutability. - **Transaction root**: Cryptographic digest summarizing all transactions in the block. - **State root**: A cryptographic digest representing the post-execution state. - **Digest**: Additional information that can be attached to a block, such as consensus-related messages. Each transaction is part of a series that is executed according to the runtime's rules. The transaction root is a cryptographic digest of this series, which prevents alterations and enables succinct verification by light clients. This verification process allows light clients to confirm whether a transaction exists in a block with only the block header, avoiding downloading the entire block. ## Block Production When an authoring node is authorized to create a new block, it selects transactions from the transaction queue based on priority. This step, known as block production, relies heavily on the executive module to manage the initialization and finalization of blocks. The process is summarized as follows: ### Initialize Block The block initialization process begins with a series of function calls that prepare the block for transaction execution: 1. **Call `on_initialize`**: The executive module calls the [`on_initialize`](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/trait.Hooks.html#method.on_initialize) hook from the system pallet and other runtime pallets to prepare for the block's transactions. 2. **Coordinate runtime calls**: Coordinates function calls in the order defined by the transaction queue. 3. **Verify information**: Once [`on_initialize`](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/trait.Hooks.html#method.on_initialize) functions are executed, the executive module checks the parent hash in the block header and the trie root to verify information is consistent. ### Finalize Block Once transactions are processed, the block must be finalized before being broadcast to the network. The finalization steps are as follows: 1. **Call `on_finalize`**: The executive module calls the [`on_finalize`](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/trait.Hooks.html#method.on_finalize) hooks in each pallet to ensure any remaining state updates or checks are completed before the block is sealed and published. 2. **Verify information**: The block's digest and storage root in the header are checked against the initialized block to ensure consistency. 3. **Call `on_idle`**: The [`on_idle`](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/trait.Hooks.html#method.on_idle) hook is triggered to process any remaining tasks using the leftover weight from the block. ## Block Authoring and Import Once the block is finalized, it is gossiped to other nodes in the network. Nodes follow this procedure: 1. **Receive transactions**: The authoring node collects transactions from the network. 2. **Validate**: Transactions are checked for validity. 3. **Queue**: Valid transactions are placed in the transaction pool for execution. 4. **Execute**: State changes are made as the transactions are executed. 5. **Publish**: The finalized block is broadcast to the network. ### Block Import Queue After a block is published, other nodes on the network can import it into their chain state. The block import queue is part of the outer node in every Polkadot SDK-based node and ensures incoming blocks are valid before adding them to the node's state. In most cases, you don't need to know details about how transactions are gossiped or how other nodes on the network import blocks. The following traits are relevant, however, if you plan to write any custom consensus logic or want a deeper dive into the block import queue: - **[`ImportQueue`](https://paritytech.github.io/polkadot-sdk/master/sc_consensus/import_queue/trait.ImportQueue.html)**: The trait that defines the block import queue. - **[`Link`](https://paritytech.github.io/polkadot-sdk/master/sc_consensus/import_queue/trait.Link.html)**: The trait that defines the link between the block import queue and the network. - **[`BasicQueue`](https://paritytech.github.io/polkadot-sdk/master/sc_consensus/import_queue/struct.BasicQueue.html)**: A basic implementation of the block import queue. - **[`Verifier`](https://paritytech.github.io/polkadot-sdk/master/sc_consensus/import_queue/trait.Verifier.html)**: The trait that defines the block verifier. - **[`BlockImport`](https://paritytech.github.io/polkadot-sdk/master/sc_consensus/block_import/trait.BlockImport.html)**: The trait that defines the block import process. These traits govern how blocks are validated and imported across the network, ensuring consistency and security. ## Additional Resources To learn more about the block structure in the Polkadot SDK runtime, see the [`Block` reference](https://paritytech.github.io/polkadot-sdk/master/sp_runtime/traits/trait.Block.html) entry in the Rust Docs. --- Page Title: Chain Data - Resolved Markdown: https://docs.polkadot.com/reference/parachains/chain-data.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/chain-data/ - Summary: Learn how to expose and utilize chain data for blockchain applications. Discover runtime metadata, RPC APIs, and tools for efficient development. - Word Count: 2172; Token Estimate: 3645 - Last Updated: 2026-01-14T11:42:16+00:00 - Version Hash: sha256:f50b3bfaaa2a3f5799e4ff72c6540a835edcf20b67a637aae641a5818fb03a35 # Chain Data ## Introduction Understanding and leveraging on-chain data is a fundamental aspect of blockchain development. Whether you're building frontend applications or backend systems, accessing and decoding runtime metadata is vital to interacting with the blockchain. This guide introduces you to the tools and processes for generating and retrieving metadata, explains its role in application development, and outlines the additional APIs available for interacting with a Polkadot node. By mastering these components, you can ensure seamless communication between your applications and the blockchain. ## Application Development You might not be directly involved in building frontend applications as a blockchain developer. However, most applications that run on a blockchain require some form of frontend or user-facing client to enable users or other programs to access and modify the data that the blockchain stores. For example, you might develop a browser-based, mobile, or desktop application that allows users to submit transactions, post articles, view their assets, or track previous activity. The backend for that application is configured in the runtime logic for your blockchain, but the frontend client makes the runtime features accessible to your users. For your custom chain to be useful to others, you'll need to provide a client application that allows users to view, interact with, or update information that the blockchain keeps track of. In this article, you'll learn how to expose information about your runtime so that client applications can use it, see examples of the information exposed, and explore tools and libraries that use it. ## Understand Metadata Polkadot SDK-based blockchain networks are designed to expose their runtime information, allowing developers to learn granular details regarding pallets, RPC calls, and runtime APIs. The metadata also exposes their related documentation. The chain's metadata is [SCALE-encoded](/reference/parachains/data-encoding/), allowing for the development of browser-based, mobile, or desktop applications to support the chain's runtime upgrades seamlessly. It is also possible to develop applications compatible with multiple Polkadot SDK-based chains simultaneously. ## Expose Runtime Information as Metadata To interact with a node or the state of the blockchain, you need to know how to connect to the chain and access the exposed runtime features. This interaction involves a Remote Procedure Call (RPC) through a node endpoint address, commonly through a secure web socket connection. An application developer typically needs to know the contents of the runtime logic, including the following details: - Version of the runtime the application is connecting to. - Supported APIs. - Implemented pallets. - Defined functions and corresponding type signatures. - Defined custom types. - Exposed parameters users can set. As the Polkadot SDK is modular and provides a composable framework for building blockchains, there are limitless opportunities to customize the schema of properties. Each runtime can be configured with its properties, including function calls and types, which can be changed over time with runtime upgrades. The Polkadot SDK enables you to generate the runtime metadata schema to capture information unique to a runtime. The metadata for a runtime describes the pallets in use and types defined for a specific runtime version. The metadata includes information about each pallet's storage items, functions, events, errors, and constants. The metadata also provides type definitions for any custom types included in the runtime. Metadata provides a complete inventory of a chain's runtime. It is key to enabling client applications to interact with the node, parse responses, and correctly format message payloads sent back to that chain. ## Generate Metadata To efficiently use the blockchain's networking resources and minimize the data transmitted over the network, the metadata schema is encoded using the [Parity SCALE Codec](https://github.com/paritytech/parity-scale-codec?tab=readme-ov-file#parity-scale-codec). This encoding is done automatically through the [`scale-info`](https://docs.rs/scale-info/latest/scale_info/)crate. At a high level, generating the metadata involves the following steps: 1. The pallets in the runtime logic expose callable functions, types, parameters, and documentation that need to be encoded in the metadata. 2. The `scale-info` crate collects type information for the pallets in the runtime, builds a registry of the pallets that exist in a particular runtime, and the relevant types for each pallet in the registry. The type information is detailed enough to enable encoding and decoding for every type. 3. The [`frame-metadata`](https://github.com/paritytech/frame-metadata) crate describes the structure of the runtime based on the registry provided by the `scale-info` crate. 4. Nodes provide the RPC method `state_getMetadata` to return a complete description of all the types in the current runtime as a hex-encoded vector of SCALE-encoded bytes. ## Retrieve Runtime Metadata The type information provided by the metadata enables applications to communicate with nodes using different runtime versions and across chains that expose different calls, events, types, and storage items. The metadata also allows libraries to generate a substantial portion of the code needed to communicate with a given node, enabling libraries like [`subxt`](https://github.com/paritytech/subxt) to generate frontend interfaces that are specific to a target chain. ### Use Polkadot.js Visit the [Polkadot.js Portal](https://polkadot.js.org/apps/#/rpc) and select the **Developer** dropdown in the top banner. Select **RPC Calls** to make the call to request metadata. Follow these steps to make the RPC call: 1. Select **state** as the endpoint to call. 2. Select **`getMetadata(at)`** as the method to call. 3. Click **Submit RPC call** to submit the call and return the metadata in JSON format. ### Use Curl You can fetch the metadata for the network by calling the node's RPC endpoint. This request returns the metadata in bytes rather than human-readable JSON: ```sh curl -H "Content-Type: application/json" \ -d '{"id":1, "jsonrpc":"2.0", "method": "state_getMetadata"}' \ https://rpc.polkadot.io ``` ### Use Subxt [`subxt`](https://github.com/paritytech/subxt) may also be used to fetch the metadata of any data in a human-readable JSON format: ```sh subxt metadata --url wss://rpc.polkadot.io --format json > spec.json ``` Another option is to use the [`subxt` explorer web UI](https://paritytech.github.io/subxt-explorer/#/). ## Client Applications and Metadata The metadata exposes the expected way to decode each type, meaning applications can send, retrieve, and process application information without manual encoding and decoding. Client applications must use the [SCALE codec library](https://github.com/paritytech/parity-scale-codec?tab=readme-ov-file#parity-scale-codec) to encode and decode RPC payloads to use the metadata. Client applications use the metadata to interact with the node, parse responses, and format message payloads sent to the node. ## Metadata Format Although the SCALE-encoded bytes can be decoded using the `frame-metadata` and [`parity-scale-codec`](https://github.com/paritytech/parity-scale-codec) libraries, there are other tools, such as `subxt` and the Polkadot-JS API, that can convert the raw data to human-readable JSON format. The types and type definitions included in the metadata returned by the `state_getMetadata` RPC call depend on the runtime's metadata version. In general, the metadata includes the following information: - A constant identifying the file as containing metadata. - The version of the metadata format used in the runtime. - Type definitions for all types used in the runtime and generated by the `scale-info` crate. - Pallet information for the pallets included in the runtime in the order that they are defined in the `construct_runtime` macro. !!!tip Depending on the frontend library used (such as the [Polkadot API](https://papi.how/)), they may format the metadata differently than the raw format shown. The following example illustrates a condensed and annotated section of metadata decoded and converted to JSON: ```json [ 1635018093, { "V14": { "types": { "types": [{}] }, "pallets": [{}], "extrinsic": { "ty": 126, "version": 4, "signed_extensions": [{}] }, "ty": 141 } } ] ``` The constant `1635018093` is a magic number that identifies the file as a metadata file. The rest of the metadata is divided into the `types`, `pallets`, and `extrinsic` sections: - The `types` section contains an index of the types and information about each type's type signature. - The `pallets` section contains information about each pallet in the runtime. - The `extrinsic` section describes the type identifier and transaction format version that the runtime uses. Different extrinsic versions can have varying formats, especially when considering [signed transactions](/reference/parachains/blocks-transactions-fees/transactions/#signed-transactions). ### Pallets The following is a condensed and annotated example of metadata for a single element in the `pallets` array (the [`sudo`](https://paritytech.github.io/polkadot-sdk/master/pallet_sudo/index.html) pallet): ```json { "name": "Sudo", "storage": { "prefix": "Sudo", "entries": [ { "name": "Key", "modifier": "Optional", "ty": { "Plain": 0 }, "default": [0], "docs": ["The `AccountId` of the sudo key."] } ] }, "calls": { "ty": 117 }, "event": { "ty": 42 }, "constants": [], "error": { "ty": 124 }, "index": 8 } ``` Every element metadata contains the name of the pallet it represents and information about its storage, calls, events, and errors. You can look up details about the definition of the calls, events, and errors by viewing the type index identifier. The type index identifier is the `u32` integer used to access the type information for that item. For example, the type index identifier for calls in the Sudo pallet is 117. If you view information for that type identifier in the `types` section of the metadata, it provides information about the available calls, including the documentation for each call. For example, the following is a condensed excerpt of the calls for the Sudo pallet: ```json { "id": 117, "type": { "path": ["pallet_sudo", "pallet", "Call"], "params": [ { "name": "T", "type": null } ], "def": { "variant": { "variants": [ { "name": "sudo", "fields": [ { "name": "call", "type": 114, "typeName": "Box<::RuntimeCall>" } ], "index": 0, "docs": [ "Authenticates sudo key, dispatches a function call with `Root` origin" ] }, { "name": "sudo_unchecked_weight", "fields": [ { "name": "call", "type": 114, "typeName": "Box<::RuntimeCall>" }, { "name": "weight", "type": 8, "typeName": "Weight" } ], "index": 1, "docs": [ "Authenticates sudo key, dispatches a function call with `Root` origin" ] }, { "name": "set_key", "fields": [ { "name": "new", "type": 103, "typeName": "AccountIdLookupOf" } ], "index": 2, "docs": [ "Authenticates current sudo key, sets the given AccountId (`new`) as the new sudo" ] }, { "name": "sudo_as", "fields": [ { "name": "who", "type": 103, "typeName": "AccountIdLookupOf" }, { "name": "call", "type": 114, "typeName": "Box<::RuntimeCall>" } ], "index": 3, "docs": [ "Authenticates sudo key, dispatches a function call with `Signed` origin from a given account" ] } ] } } } } ``` For each field, you can access type information and metadata for the following: - **Storage metadata**: Provides the information required to enable applications to get information for specific storage items. - **Call metadata**: Includes information about the runtime calls defined by the `#[pallet]` macro including call names, arguments and documentation. - **Event metadata**: Provides the metadata generated by the `#[pallet::event]` macro, including the name, arguments, and documentation for each pallet event. - **Constants metadata**: Provides metadata generated by the `#[pallet::constant]` macro, including the name, type, and hex-encoded value of the constant. - **Error metadata**: Provides metadata generated by the `#[pallet::error]` macro, including the name and documentation for each pallet error. !!!tip Type identifiers change from time to time, so you should avoid relying on specific type identifiers in your applications. ### Extrinsic The runtime generates extrinsic metadata and provides useful information about transaction format. When decoded, the metadata contains the transaction version and the list of signed extensions. For example: ```json { "extrinsic": { "ty": 126, "version": 4, "signed_extensions": [ { "identifier": "CheckNonZeroSender", "ty": 132, "additional_signed": 41 }, { "identifier": "CheckSpecVersion", "ty": 133, "additional_signed": 4 }, { "identifier": "CheckTxVersion", "ty": 134, "additional_signed": 4 }, { "identifier": "CheckGenesis", "ty": 135, "additional_signed": 11 }, { "identifier": "CheckMortality", "ty": 136, "additional_signed": 11 }, { "identifier": "CheckNonce", "ty": 138, "additional_signed": 41 }, { "identifier": "CheckWeight", "ty": 139, "additional_signed": 41 }, { "identifier": "ChargeTransactionPayment", "ty": 140, "additional_signed": 41 } ] }, "ty": 141 } ``` The type system is [composite](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/frame_runtime_types/index.html), meaning each type identifier contains a reference to a specific type or to another type identifier that provides information about the associated primitive types. For example, you can encode the `BitVec` type, but to decode it properly, you must know the types used for the `Order` and `Store` types. To find type information for `Order` and `Store`, you can use the path in the decoded JSON to locate their type identifiers. ## Included RPC APIs A standard node comes with the following APIs to interact with a node: - **[`AuthorApiServer`](https://paritytech.github.io/polkadot-sdk/master/sc_rpc/author/trait.AuthorApiServer.html)**: Make calls into a full node, including authoring extrinsics and verifying session keys. - **[`ChainApiServer`](https://paritytech.github.io/polkadot-sdk/master/sc_rpc/chain/trait.ChainApiServer.html)**: Retrieve block header and finality information. - **[`OffchainApiServer`](https://paritytech.github.io/polkadot-sdk/master/sc_rpc/offchain/trait.OffchainApiServer.html)**: Make RPC calls for off-chain workers. - **[`StateApiServer`](https://paritytech.github.io/polkadot-sdk/master/sc_rpc/state/trait.StateApiServer.html)**: Query information about on-chain state such as runtime version, storage items, and proofs. - **[`SystemApiServer`](https://paritytech.github.io/polkadot-sdk/master/sc_rpc/system/trait.SystemApiServer.html)**: Retrieve information about network state, such as connected peers and node roles. ## Additional Resources The following tools can help you locate and decode metadata: - [Subxt Explorer](https://paritytech.github.io/subxt-explorer/#/) - [Metadata Portal 🌗](https://github.com/paritytech/metadata-portal) - [De[code] Sub[strate]](https://github.com/paritytech/desub) --- Page Title: Contract Deployment - Resolved Markdown: https://docs.polkadot.com/smart-contracts/for-eth-devs/contract-deployment.md - Canonical (HTML): https://docs.polkadot.com/smart-contracts/for-eth-devs/contract-deployment/ - Summary: Compare deployment flows for REVM and PVM-based smart contracts on the Polkadot Hub. Includes single-step REVM flows and PVM's two-step deployment model. - Word Count: 754; Token Estimate: 1150 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:b4d64a6b3f0ebc9b16a5cb6d856aea93991b4f807cafeb0b21329924085b0abf # Contract Deployment ## Introduction Polkadot's smart contract platform supports two distinct virtual machine backends: Rust Ethereum Virtual Machine (REVM) and PVM. Each backend has its own deployment characteristics and optimization strategies. REVM provides full Ethereum compatibility with familiar single-step deployment, while the RISC-V-based PVM uses a more structured two-step approach optimized for its architecture. Understanding these differences ensures smooth deployment regardless of which backend you choose for your smart contracts. ## REVM Deployment The REVM backend enables seamless deployment of Ethereum contracts without modification. Contracts deploy exactly as they would on Ethereum, using familiar tools and workflows. With REVM, deployment mirrors the Ethereum flow exactly including: - Contracts are bundled and deployed in a single transaction. - Factory contracts can create new contracts at runtime. - Runtime code generation, including inline assembly, is supported. - Existing familiar tools like Hardhat, Foundry, and Remix work out of the box. ## PVM Deployment PVM implements a fundamentally different deployment model optimized for its RISC-V architecture. While simple contract deployments work seamlessly, advanced patterns like factory contracts require understanding the two-step deployment process. ### Standard Contract Deployment For most use cases, such as deploying ERC-20 tokens, NFT collections, or standalone contracts, deployment is transparent and requires no special steps. The [Revive compiler](https://github.com/paritytech/revive) handles the deployment process automatically when using standard Solidity patterns. ### Two-Step Deployment Model PVM separates contract deployment into distinct phases: 1. **Code upload**: Contract bytecode must be uploaded to the chain before instantiation. 2. **Contract instantiation**: Contracts are created by referencing previously uploaded code via its hash. This architecture differs from the EVM's bundled approach and has important implications for specific deployment patterns. ### Factory Pattern Considerations The common EVM pattern, where contracts dynamically create other contracts, requires adaptation for PVM as follows: **EVM Factory Pattern:** ```solidity // This works on REVM but requires modification for PVM contract Factory { function createToken() public returns (address) } ``` **PVM Requirements:** - **Pre-upload dependent contracts**: All contracts that will be instantiated at runtime must be uploaded to the chain before the factory attempts to create them. - **Code hash references**: Factory contracts work with pre-uploaded code hashes rather than embedding bytecode. - **No runtime code generation**: Dynamic bytecode generation is not supported due to PVM's RISC-V format. ### Migration Strategy for Factory Contracts When migrating factory contracts from Ethereum to PVM: 1. **Identify all contracts**: Determine which contracts will be instantiated at runtime. 2. **Upload dependencies first**: Deploy all dependent contracts to the chain before deploying the factory. 3. **Use on-chain constructors**: Leverage PVM's on-chain constructor feature for flexible instantiation. 4. **Avoid assembly creation**: Don't use `create` or `create2` opcodes in assembly blocks for manual deployment. ### Architecture-Specific Limitations PVM's deployment model creates several specific constraints: - **`EXTCODECOPY` limitations**: Contracts using `EXTCODECOPY` to manipulate code at runtime will encounter issues. - **Runtime code modification**: Patterns that construct and mutate contract code on-the-fly are not supported. - **Assembly-based factories**: Factory contracts written in YUL assembly that generate code at runtime will fail with `CodeNotFound` errors. These patterns are rare in practice and typically require dropping down to assembly, making them non-issues for standard Solidity development. ### On-Chain Constructors PVM provides on-chain constructors as an elegant alternative to runtime code modification: - Enable contract instantiation without runtime code generation. - Support flexible initialization patterns. - Maintain separation between code upload and contract creation. - Provide predictable deployment costs. ## Gas Estimation vs Actual Consumption Both REVM and PVM deployments may show significant differences between gas estimation and actual consumption. You might see estimates that are several times higher than the actual gas consumed (often around 30% of the estimate). This is normal behavior because pre-dispatch estimation cannot distinguish between computation weight and storage deposits, leading to conservative overestimation. Contract deployments are particularly affected as they consume significant storage deposits for code storage. ## Deployment Comparison | Feature | REVM Backend | PVM Backend | |:---------------------:|:-----------------------:|:-------------------------------:| | **Deployment Model** | Single-step bundled | Two-step upload and instantiate | | **Factory Patterns** | Direct runtime creation | Requires pre-uploaded code | | **Code Bundling** | Bytecode in transaction | Code hash references | | **Runtime Codegen** | Fully supported | Not supported | | **Simple Contracts** | No modifications needed | No modifications needed | | **Assembly Creation** | Supported | Discouraged, limited support | ## Conclusion Both backends support contract deployment effectively, with REVM offering drop-in Ethereum compatibility and PVM providing a more structured two-step approach. For the majority of use cases—deploying standard contracts like tokens or applications—both backends work seamlessly. Advanced patterns like factory contracts may require adjustment for PVM, but these adaptations are straightforward with proper planning. --- Page Title: Create an Account - Resolved Markdown: https://docs.polkadot.com/chain-interactions/accounts/create-account.md - Canonical (HTML): https://docs.polkadot.com/chain-interactions/accounts/create-account/ - Summary: Step-by-step guide to creating Polkadot accounts using different programming languages and libraries, including JavaScript, Python, and Rust examples. - Word Count: 869; Token Estimate: 1594 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:442302c01bd6fa04b49eef8bce3451f8086d7b445ed6aabbd3d6ddcb464da9f8 # Create an Account ## Introduction Creating accounts is a fundamental operation when building applications on Polkadot and its parachains. Accounts serve as the basis for identity, asset ownership, and transaction signing. Understanding how to generate and manage accounts programmatically enables you to build wallets, automate operations, and create seamless user experiences. Polkadot accounts are based on the SR25519 signature scheme by default, though ED25519 and ECDSA are also supported. Each account consists of a public key (address) and a private key (seed/mnemonic). **Keep your private keys secure and never share them**. This tutorial will guide you through creating accounts using different programming languages and libraries. ## Prerequisites Before starting, make sure you have: - Basic understanding of public-key cryptography concepts - Development environment set up for your chosen language - Familiarity with the programming language you'll be using ## Use JavaScript/TypeScript JavaScript/TypeScript developers can use the Polkadot.js API to create and manage Polkadot accounts. 1. Create a new project directory and initialize it: ```bash mkdir account-creator cd account-creator npm init -y && npm pkg set type=module ``` 2. Install the required packages: ```bash npm install @polkadot/util-crypto @polkadot/keyring npm install --save-dev typescript tsx ``` 3. Create a file named `create-account.ts` and add the following code to it: ```typescript title="create-account.ts" import { cryptoWaitReady, mnemonicGenerate } from '@polkadot/util-crypto'; import { Keyring } from '@polkadot/keyring'; async function main()); const pair = keyring.addFromMnemonic(mnemonic); console.log(`Address: ${pair.address}`); console.log(`Mnemonic: ${mnemonic}`); } main().catch(console.error); ``` Key aspects of the code: - **Mnemonic generation**: Uses `mnemonicGenerate()` to create a 12-word BIP39 mnemonic phrase for human-readable key backup. - **Keyring**: The `Keyring` class manages accounts with a specified signature scheme and address format. - **SS58 format**: Setting `ss58Format: 0` configures addresses for the Polkadot relay chain. 4. Execute the script using `tsx`: ```bash npx tsx create-account.ts ``` You should see output similar to:
npx tsx create-account.ts Address: 15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5 Mnemonic: cushion dog echo people vendor curve truck begin latin romance rebuild ...
## Python Python developers can use the `substrate-interface` library to create and manage Polkadot accounts. 1. Create a new project directory and set up a virtual environment: ```bash mkdir account-creator-python cd account-creator-python python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 2. Install the required package: ```bash pip install substrate-interface ``` 3. Create a file named `create_account.py`: ```python title="create_account.py" from substrateinterface import Keypair mnemonic = Keypair.generate_mnemonic() keypair = Keypair.create_from_mnemonic(mnemonic) print(f"Address: {keypair.ss58_address}") print(f"Mnemonic: {mnemonic}") ``` Key aspects of the code: - **Mnemonic generation**: The `generate_mnemonic()` function creates a BIP39-compatible phrase. - **Keypair creation**: `Keypair.create_from_mnemonic()` derives keys from the mnemonic. 4. Execute the script: ```bash python create_account.py ``` You should see output similar to:
python create_account.py Address: 15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5 Mnemonic: cushion dog echo people vendor curve truck begin latin romance rebuild ...
## Rust Rust provides low-level access to Substrate primitives for account creation through the `sp-core` and `sp-keyring` crates. 1. Create a new Rust project: ```bash cargo new account-creator-rust cd account-creator-rust ``` 2. Add dependencies to your `Cargo.toml`: ```toml title="Cargo.toml" [package] name = "account-creator-rust" version = "0.1.0" edition = "2021" [dependencies] sp-core = "28.0" sp-runtime = "31.0" ``` 3. Create your account generation code in `src/main.rs`: ```rust title="src/main.rs" use sp_core::{crypto::Ss58Codec, Pair}; fn main()", address); println!("Mnemonic: {}", phrase); } ``` Key aspects of the code: - **Keypair generation**: [`sr25519::Pair::generate_with_phrase()`](https://docs.rs/sp-core/latest/sp_core/crypto/trait.Pair.html#method.generate_with_phrase) creates a new key pair with mnemonic. - **Public key extraction**: The [`public()`](https://docs.rs/sp-core/latest/sp_core/crypto/trait.Pair.html#tymethod.public) method retrieves the public key from the pair. - **SS58 encoding**: Uses Polkadot's address format for the human-readable address. 4. Build and run the project: ```bash cargo run ``` You should see output similar to:
cargo run Address: 15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5 Mnemonic: cushion dog echo people vendor curve truck begin latin romance rebuild ...
## Where to Go Next
- Guide __Send Transactions with SDKs__ --- Learn how to send signed transactions using your newly created accounts with Polkadot-API and Polkadot.js API libraries. [:octicons-arrow-right-24: Get Started](/chain-interactions/send-transactions/with-sdks/) - Guide __Calculate Transaction Fees__ --- Learn how to estimate transaction fees before sending transactions from your accounts. [:octicons-arrow-right-24: Get Started](/chain-interactions/send-transactions/calculate-transaction-fees/) - Guide __Query Chain Data__ --- Explore different methods for querying blockchain data, including account balances and other chain state. [:octicons-arrow-right-24: Get Started](/chain-interactions/query-data/query-sdks/)
--- Page Title: Cryptography - Resolved Markdown: https://docs.polkadot.com/reference/parachains/cryptography.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/cryptography/ - Summary: A concise guide to cryptography in blockchain, covering hash functions, encryption types, digital signatures, and elliptic curve applications. - Word Count: 1274; Token Estimate: 1736 - Last Updated: 2026-04-23T12:21:22+00:00 - Version Hash: sha256:40d07670a7bcbeba4d0137f394de08f29dc755575cc1ea2a8ebca288c2e4f415 # Cryptography ## Introduction Cryptography forms the backbone of blockchain technology, providing the mathematical verifiability crucial for consensus systems, data integrity, and user security. While a deep understanding of the underlying mathematical processes isn't necessary for most blockchain developers, grasping the fundamental applications of cryptography is essential. This page comprehensively overviews cryptographic implementations used across Polkadot SDK-based chains and the broader blockchain ecosystem. ## Hash Functions Hash functions are fundamental to blockchain technology, creating a unique digital fingerprint for any piece of data, including simple text, images, or any other form of file. They map input data of any size to a fixed-size output (typically 32 bytes) using complex mathematical operations. Hashing is used to verify data integrity, create digital signatures, and provide a secure way to store passwords. This form of mapping is known as the ["pigeonhole principle,"](https://en.wikipedia.org/wiki/Pigeonhole_principle) it is primarily implemented to efficiently and verifiably identify data from large sets. ### Key Properties of Hash Functions - **Deterministic**: The same input always produces the same output. - **Quick computation**: It's easy to calculate the hash value for any given input. - **Pre-image resistance**: It's infeasible to generate the input data from its hash. - **Small changes in input yield large changes in output**: Known as the ["avalanche effect"](https://en.wikipedia.org/wiki/Avalanche_effect). - **Collision resistance**: The probabilities are extremely low to find two different inputs with the same hash. ### Blake2 The Polkadot SDK utilizes Blake2, a state-of-the-art hashing method that offers: - Equal or greater security compared to [SHA-2](https://en.wikipedia.org/wiki/SHA-2). - Significantly faster performance than other algorithms. These properties make Blake2 ideal for blockchain systems, reducing sync times for new nodes and lowering the resources required for validation. For detailed technical specifications about Blake2, see the [official Blake2 paper](https://www.blake2.net/blake2.pdf). ## Types of Cryptography There are two different ways that cryptographic algorithms are implemented: symmetric cryptography and asymmetric cryptography. ### Symmetric Cryptography Symmetric encryption is a branch of cryptography that isn't based on one-way functions, unlike asymmetric cryptography. It uses the same cryptographic key to encrypt plain text and decrypt the resulting ciphertext. Symmetric cryptography is a type of encryption that has been used throughout history, such as the Enigma Cipher and the Caesar Cipher. It is still widely used today and can be found in Web2 and Web3 applications alike. There is only one single key, and a recipient must also have access to it to access the contained information. #### Advantages {: #symmetric-advantages } - Fast and efficient for large amounts of data. - Requires less computational power. #### Disadvantages {: #symmetric-disadvantages } - Key distribution can be challenging. - Scalability issues in systems with many users. ### Asymmetric Cryptography Asymmetric encryption is a type of cryptography that uses two different keys, known as a keypair: a public key, used to encrypt plain text, and a private counterpart, used to decrypt the ciphertext. The public key encrypts a fixed-length message that can only be decrypted with the recipient's private key and, sometimes, a set password. The public key can be used to cryptographically verify that the corresponding private key was used to create a piece of data without compromising the private key, such as with digital signatures. This has obvious implications for identity, ownership, and properties and is used in many different protocols across Web2 and Web3. #### Advantages {: #asymmetric-advantages } - Solves the key distribution problem. - Enables digital signatures and secure key exchange. #### Disadvantages {: #asymmetric-disadvantages } - Slower than symmetric encryption. - Requires more computational resources. ### Trade-offs and Compromises Symmetric cryptography is faster and requires fewer bits in the key to achieve the same level of security that asymmetric cryptography provides. However, it requires a shared secret before communication can occur, which poses issues to its integrity and a potential compromise point. On the other hand, asymmetric cryptography doesn't require the secret to be shared ahead of time, allowing for far better end-user security. Hybrid symmetric and asymmetric cryptography is often used to overcome the engineering issues of asymmetric cryptography, as it is slower and requires more bits in the key to achieve the same level of security. It encrypts a key and then uses the comparatively lightweight symmetric cipher to do the "heavy lifting" with the message. ## Digital Signatures Digital signatures are a way of verifying the authenticity of a document or message using asymmetric keypairs. They are used to ensure that a sender or signer's document or message hasn't been tampered with in transit, and for recipients to verify that the data is accurate and from the expected sender. Signing digital signatures only requires a low-level understanding of mathematics and cryptography. For a conceptual example -- when signing a check, it is expected that it cannot be cashed multiple times. This isn't a feature of the signature system but rather the check serialization system. The bank will check that the serial number on the check hasn't already been used. Digital signatures essentially combine these two concepts, allowing the signature to provide the serialization via a unique cryptographic fingerprint that cannot be reproduced. Unlike pen-and-paper signatures, knowledge of a digital signature cannot be used to create other signatures. Digital signatures are often used in bureaucratic processes, as they are more secure than simply scanning in a signature and pasting it onto a document. Polkadot SDK provides multiple different cryptographic schemes and is generic so that it can support anything that implements the [`Pair` trait](https://paritytech.github.io/polkadot-sdk/master/sp_core/crypto/trait.Pair.html). ### Example of Creating a Digital Signature The process of creating and verifying a digital signature involves several steps: 1. The sender creates a hash of the message. 2. The hash is encrypted using the sender's private key, creating the signature. 3. The message and signature are sent to the recipient. 4. The recipient decrypts the signature using the sender's public key. 5. The recipient hashes the received message and compares it to the decrypted hash. If the hashes match, the signature is valid, confirming the message's integrity and the sender's identity. ## Elliptic Curve Blockchain technology requires the ability to have multiple keys creating a signature for block proposal and validation. To this end, Elliptic Curve Digital Signature Algorithm (ECDSA) and Schnorr signatures are two of the most commonly used methods. While ECDSA is a far simpler implementation, Schnorr signatures are more efficient when it comes to multi-signatures. Schnorr signatures bring some noticeable features over the ECDSA/EdDSA schemes: - It is better for hierarchical deterministic key derivations. - It allows for native multi-signature through [signature aggregation](https://bitcoincore.org/en/2017/03/23/schnorr-signature-aggregation/). - It is generally more resistant to misuse. One sacrifice that is made when using Schnorr signatures over ECDSA is that both require 64 bytes, but only ECDSA signatures communicate their public key. ### Various Implementations - **[ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm)**: Polkadot SDK provides an ECDSA signature scheme using the [secp256k1](https://en.bitcoin.it/wiki/Secp256k1) curve. This is the same cryptographic algorithm used to secure [Bitcoin](https://en.wikipedia.org/wiki/Bitcoin) and [Ethereum](https://en.wikipedia.org/wiki/Ethereum). - **[Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519)**: An EdDSA signature scheme using [Curve25519](https://en.wikipedia.org/wiki/Curve25519). It is carefully engineered at several levels of design and implementation to achieve very high speeds without compromising security. - **[SR25519](https://wiki.polkadot.com/learn/learn-cryptography/#what-is-sr25519-and-where-did-it-come-from)**: Based on the same underlying curve as Ed25519. However, it uses Schnorr signatures instead of the EdDSA scheme. --- Page Title: Data Encoding - Resolved Markdown: https://docs.polkadot.com/reference/parachains/data-encoding.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/data-encoding/ - Summary: SCALE codec enables fast, efficient data encoding, ideal for resource-constrained environments like Wasm, supporting custom types and compact encoding. - Word Count: 1279; Token Estimate: 3106 - Last Updated: 2026-06-05T18:49:43+00:00 - Version Hash: sha256:c1b1ffe61a76feae29c001d601eacd14dc2b3e294da093514a1d933628aa2cdc # Data Encoding ## Introduction The Polkadot SDK uses a lightweight and efficient encoding/decoding mechanism to optimize data transmission across the network. This mechanism, known as the _SCALE_ codec, is used for serializing and deserializing data. The SCALE codec enables communication between the runtime and the outer node. This mechanism is designed for high-performance, copy-free data encoding and decoding in resource-constrained environments like the Polkadot SDK Wasm runtime. It is not self-describing, meaning the decoding context must fully know the encoded data types. Parity's libraries utilize the [`parity-scale-codec`](https://github.com/paritytech/parity-scale-codec) crate (a Rust implementation of the SCALE codec) to handle encoding and decoding for interactions between RPCs and the runtime. The `codec` mechanism is ideal for Polkadot SDK-based chains because: - It is lightweight compared to generic serialization frameworks like [`serde`](https://serde.rs/), which add unnecessary bulk to binaries. - It doesn’t rely on Rust’s `libstd`, making it compatible with `no_std` environments like Wasm runtime. - It integrates seamlessly with Rust, allowing easy derivation of encoding and decoding logic for new types using `#[derive(Encode, Decode)]`. Defining a custom encoding scheme in the Polkadot SDK-based chains, rather than using an existing Rust codec library, is crucial for enabling cross-platform and multi-language support. ## SCALE Codec The codec is implemented using the following traits: - [`Encode`](#encode) - [`Decode`](#decode) - [`CompactAs`](#compactas) - [`HasCompact`](#hascompact) - [`EncodeLike`](#encodelike) ### Encode The [`Encode`](https://docs.rs/parity-scale-codec/latest/parity_scale_codec/trait.Encode.html) trait handles data encoding into SCALE format and includes the following key functions: - **`size_hint(&self) -> usize`**: Estimates the number of bytes required for encoding to prevent multiple memory allocations. This should be inexpensive and avoid complex operations. Optional if the size isn’t known. - **`encode_to(&self, dest: &mut T)`**: Encodes the data, appending it to a destination buffer. - **`encode(&self) -> Vec`**: Encodes the data and returns it as a byte vector. - **`using_encoded R>(&self, f: F) -> R`**: Encodes the data and passes it to a closure, returning the result. - **`encoded_size(&self) -> usize`**: Calculates the encoded size. Should be used when the encoded data isn’t required. !!!tip For best performance, value types should override `using_encoded`, and allocating types should override `encode_to`. It's recommended to implement `size_hint` for all types where possible. ### Decode The [`Decode`](https://docs.rs/parity-scale-codec/latest/parity_scale_codec/trait.Decode.html) trait handles decoding SCALE-encoded data back into the appropriate types: - **`fn decode(value: &mut I) -> Result`**: Decodes data from the SCALE format, returning an error if decoding fails. ### CompactAs The [`CompactAs`](https://docs.rs/parity-scale-codec/latest/parity_scale_codec/trait.CompactAs.html) trait wraps custom types for compact encoding: - **`encode_as(&self) -> &Self::As`**: Encodes the type as a compact type. - **`decode_from(_: Self::As) -> Result`**: decodes from a compact encoded type. ### HasCompact The [`HasCompact`](https://docs.rs/parity-scale-codec/latest/parity_scale_codec/trait.HasCompact.html) trait indicates a type supports compact encoding. ### EncodeLike The [`EncodeLike`](https://docs.rs/parity-scale-codec/latest/parity_scale_codec/trait.EncodeLike.html) trait is used to ensure multiple types that encode similarly are accepted by the same function. When using `derive`, it is automatically implemented. ### Data Types The table below outlines how the Rust implementation of the Parity SCALE codec encodes different data types. | Type | Description | Example SCALE Decoded Value | SCALE Encoded Value | |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| | Boolean | Boolean values are encoded using the least significant bit of a single byte. | `false` / `true` | `0x00` / `0x01` | | Compact/general integers | A "compact" or general integer encoding is sufficient for encoding large integers (up to 2^536) and is more efficient at encoding most values than the fixed-width version. | `unsigned integer 0` / `unsigned integer 1` / `unsigned integer 42` / `unsigned integer 69` / `unsigned integer 65535` / `BigInt(100000000000000)` | `0x00` / `0x04` / `0xa8` / `0x1501` / `0xfeff0300` / `0x0b00407a10f35a` | | Enumerations (tagged-unions) | A fixed number of variants, each mutually exclusive and potentially implying a further value or series of values. Encoded as the first byte identifying the index of the variant that the value is. Any further bytes are used to encode any data that the variant implies. Thus, no more than 256 variants are supported. | `Int(42)` and `Bool(true)` where `enum IntOrBool { Int(u8), Bool(bool) }` | `0x002a` and `0x0101` | | Fixed-width integers | Basic integers are encoded using a fixed-width little-endian (LE) format. | `signed 8-bit integer 69` / `unsigned 16-bit integer 42` / `unsigned 32-bit integer 16777215` | `0x45` / `0x2a00` / `0xffffff00` | | Options | One or zero values of a particular type. | `Some` / `None` | `0x01` followed by the encoded value / `0x00` | | Results | Results are commonly used enumerations which indicate whether certain operations were successful or unsuccessful. | `Ok(42)` / `Err(false)` | `0x002a` / `0x0100` | | Strings | Strings are Vectors of bytes (Vec) containing a valid UTF8 sequence. | | | | Structs | For structures, the values are named, but that is irrelevant for the encoding (names are ignored - only order matters). | `SortedVecAsc::from([3, 5, 2, 8])` | `[3, 2, 5, 8] ` | | Tuples | A fixed-size series of values, each with a possibly different but predetermined and fixed type. This is simply the concatenation of each encoded value. | Tuple of compact unsigned integer and boolean: `(3, false)` | `0x0c00` | | Vectors (lists, series, sets) | A collection of same-typed values is encoded, prefixed with a compact encoding of the number of items, followed by each item's encoding concatenated in turn. | Vector of unsigned `16`-bit integers: `[4, 8, 15, 16, 23, 42]` | `0x18040008000f00100017002a00` | ## Encode and Decode Rust Trait Implementations Here's how the `Encode` and `Decode` traits are implemented: ```rust use parity_scale_codec::{Encode, Decode}; [derive(Debug, PartialEq, Encode, Decode)] enum EnumType { #[codec(index = 15)] A, B(u32, u64), C { a: u32, b: u64, }, } let a = EnumType::A; let b = EnumType::B(1, 2); let c = EnumType::C { a: 1, b: 2 }; a.using_encoded(|ref slice| { assert_eq!(slice, &b"\x0f"); }); b.using_encoded(|ref slice| { assert_eq!(slice, &b"\x01\x01\0\0\0\x02\0\0\0\0\0\0\0"); }); c.using_encoded(|ref slice| { assert_eq!(slice, &b"\x02\x01\0\0\0\x02\0\0\0\0\0\0\0"); }); let mut da: &[u8] = b"\x0f"; assert_eq!(EnumType::decode(&mut da).ok(), Some(a)); let mut db: &[u8] = b"\x01\x01\0\0\0\x02\0\0\0\0\0\0\0"; assert_eq!(EnumType::decode(&mut db).ok(), Some(b)); let mut dc: &[u8] = b"\x02\x01\0\0\0\x02\0\0\0\0\0\0\0"; assert_eq!(EnumType::decode(&mut dc).ok(), Some(c)); let mut dz: &[u8] = &[0]; assert_eq!(EnumType::decode(&mut dz).ok(), None); ``` ## SCALE Codec Libraries Several SCALE codec implementations are available in various languages. Here's a list of them: - **AssemblyScript**: [`LimeChain/as-scale-codec`](https://github.com/LimeChain/as-scale-codec) - **C**: [`MatthewDarnell/cScale`](https://github.com/MatthewDarnell/cScale) - **C++**: [`qdrvm/scale-codec-cpp`](https://github.com/qdrvm/scale-codec-cpp) - **JavaScript**: [`polkadot-js/api`](https://github.com/polkadot-js/api) - **Dart**: [`leonardocustodio/polkadart`](https://github.com/leonardocustodio/polkadart) - **Haskell**: [`airalab/hs-web3`](https://github.com/airalab/hs-web3/tree/master/packages/scale) - **Golang**: [`itering/scale.go`](https://github.com/itering/scale.go) - **Java**: [`splix/polkaj`](https://github.com/splix/polkaj) - **Python**: [`polkascan/py-scale-codec`](https://github.com/polkascan/py-scale-codec) - **Ruby**: [` wuminzhe/scale_rb`](https://github.com/wuminzhe/scale_rb) - **TypeScript**: [`parity-scale-codec-ts`](https://github.com/tjjfvi/subshape), [`scale-ts`](https://github.com/unstoppablejs/unstoppablejs/tree/main/packages/scale-ts#scale-ts), [`soramitsu/scale-codec-js-library`](https://github.com/soramitsu/scale-codec-js-library), [`subsquid/scale-codec`](https://github.com/subsquid/squid-sdk/tree/master/substrate/scale-codec) - **Solidity**: [`LucasGrasso/solidity-scale-codec`](https://github.com/LucasGrasso/solidity-scale-codec) _(not audited)_ --- Page Title: Deploy an ERC-20 Using Hardhat - Resolved Markdown: https://docs.polkadot.com/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-hardhat.md - Canonical (HTML): https://docs.polkadot.com/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-hardhat/ - Summary: Deploy an ERC-20 token on Polkadot Hub using PVM. This guide covers contract creation, compilation, deployment, and interaction via Hardhat. - Word Count: 1087; Token Estimate: 2046 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:adc4baa9da9436508faeab0d2274720a8e26135dae3fb5b3e8cf28fd6b798a2a # Deploy an ERC-20 Using Hardhat ## Introduction [ERC-20](https://eips.ethereum.org/EIPS/eip-20) tokens are fungible tokens commonly used for creating cryptocurrencies, governance tokens, and staking mechanisms. Polkadot Hub enables easy deployment of ERC-20 tokens via Ethereum-compatible smart contracts and tools. This guide demonstrates how to deploy an ERC-20 contract on Polkadot Hub TestNet using [Hardhat](https://hardhat.org/), an Ethereum development environment. The ERC-20 contract can be retrieved from OpenZeppelin's [GitHub repository](https://github.com/OpenZeppelin/openzeppelin-contracts/tree/v5.6.1/contracts/token/ERC20) or generated with the [OpenZeppelin Contracts Wizard for Polkadot](https://wizard.openzeppelin.com/polkadot). ## Prerequisites Before you begin, ensure you have the following: - A basic understanding of [Solidity](https://www.soliditylang.org/) programming and [ERC-20](https://ethereum.org/developers/docs/standards/tokens/erc-20/) fungible tokens. - [Node.js](https://nodejs.org/en/download) v22.13.1 or later installed. - Test tokens for gas fees, available from the [Polkadot faucet](https://faucet.polkadot.io/). See [Get Test Tokens](/smart-contracts/faucet/#get-test-tokens) for a guide to using the faucet. - A wallet with a private key for signing transactions. ## Set Up Your Project This tutorial uses a [Hardhat ERC-20 template](https://github.com/polkadot-developers/revm-hardhat-examples/tree/master/erc20-hardhat) that contains all the necessary files. To get started, take the following steps: 1. Clone the GitHub repository locally: ```bash git clone https://github.com/polkadot-developers/revm-hardhat-examples/ cd revm-hardhat-examples/erc20-hardhat ``` 2. Install the dependencies using the following command: ```bash npm i ``` This command will fetch all the necessary packages to help you use Hardhat to deploy an ERC-20 to Polkadot. ## Configure Hardhat If you started with the cloned Hardhat ERC-20 template, `hardhat.config.ts` is already configured to deploy to the Polkadot TestNet as shown in the example below: ```ts title="hardhat.config.ts" hl_lines="14-19" import { HardhatUserConfig, vars } from "hardhat/config"; import "@nomicfoundation/hardhat-toolbox"; const config: HardhatUserConfig = { solidity: { version: "0.8.28", settings: { optimizer: { enabled: true, runs: 200, }, }, }, networks: { polkadotTestnet: { url: "https://services.polkadothub-rpc.com/testnet", accounts: vars.has("TESTNET_PRIVATE_KEY") ? [vars.get("TESTNET_PRIVATE_KEY")] : [], }, }, mocha: { timeout: 40000, }, }; export default config; ``` !!! tip Visit the Hardhat [Configuration variables](https://v2.hardhat.org/hardhat-runner/docs/guides/configuration-variables) documentation to learn how to use Hardhat to handle your private keys securely. ## Compile the Contract Next, compile the contract included with the template by running the following command: ```bash npx hardhat compile ``` If everything compiles successfully, you will see output similar to the following:
npx hardhat compile Generating typings for: 23 artifacts in dir: typechain-types for target: ethers-v6 Successfully generated 62 typings! Compiled 21 Solidity files successfully (evm target: paris).
## Test the Contract You can view the predefined test file at [`test/MyToken.test.ts`](https://github.com/polkadot-developers/revm-hardhat-examples/blob/master/erc20-hardhat/test/MyToken.test.ts). This example test includes verification of the following: - The token name and symbol exist (confirms deployment) and are correct. - The token owner is correctly configured. - The initial token supply is zero. - The owner can mint tokens. - The total supply increases after a mint. - Successful mints to different test addresses with expected account balance and total supply changes. Run the tests using the following command: ```bash npx hardhat test --network polkadotTestnet ``` If tests are successful, you will see outputs similar to the following:
npx hardhat test --network polkadotTestnet   MyToken     Deployment       ✔ Should have correct name and symbol       ✔ Should set the right owner       ✔ Should have zero initial supply     Minting       ✔ Should allow owner to mint tokens       ✔ Should increase total supply on mint     Multiple mints       ✔ Should correctly track balance after multiple mints   6 passing (369ms)
## Deploy the Contract You are now ready to deploy the contract to your chosen network. This example demonstrates deployment to the Polkadot TestNet. Deploy the contract as follows: 1. Run the following command in your terminal: ```bash npx hardhat ignition deploy ./ignition/modules/MyToken.ts --network polkadotTestnet ``` 2. Confirm the target deployment network name and chain ID when prompted:
npx hardhat ignition deploy ./ignition/modules/MyToken.ts --network polkadotTestnet ✔ Confirm deploy to network polkadotTestnet (420420417)? … yes   Hardhat Ignition 🚀   Deploying [ TokenModule ]   Batch #1 Executed TokenModule#MyToken   Batch #2 Executed TokenModule#MyToken.mint   [ TokenModule ] successfully deployed 🚀   Deployed Addresses   TokenModule#MyToken - 0xc01Ee7f10EA4aF4673cFff62710E1D7792aBa8f3
Congratulations! You've successfully deployed an ERC-20 token contract to Polkadot Hub TestNet using Hardhat. Consider the following resources to build upon your progress. ## Where to Go Next
- Guide __Deploy an NFT__ --- Walk through deploying an NFT to the Polkadot Hub using Hardhat. [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-hardhat/) - Guide __Create a DApp__ --- Learn step-by-step how to build a fully functional dApp that interacts with a smart contract deployed via Hardhat. [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/dapps/zero-to-hero/)
--- Page Title: Deploy an ERC-20 Using Remix IDE - Resolved Markdown: https://docs.polkadot.com/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-remix.md - Canonical (HTML): https://docs.polkadot.com/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-remix/ - Summary: Deploy an ERC-20 token contract on Polkadot Hub. This guide covers contract creation, compilation, deployment, and interaction via the Remix IDE. - Word Count: 865; Token Estimate: 1402 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:b34b29c8409aafae22df8131de569fc8b4c264c13c1b11dd6aa1620e23e07f8c # Deploy an ERC-20 Using Remix IDE ## Introduction [ERC-20](https://eips.ethereum.org/EIPS/eip-20) tokens are fungible tokens commonly used for creating cryptocurrencies, governance tokens, and staking mechanisms. Polkadot Hub enables easy token deployment with Ethereum-compatible smart contracts and tools via the EVM backend. This tutorial covers deploying an ERC-20 contract on Polkadot Hub TestNet using [Remix IDE](https://remix.ethereum.org/), a web-based development tool. The ERC-20 contract can be retrieved from OpenZeppelin's [GitHub repository](https://github.com/OpenZeppelin/openzeppelin-contracts/tree/v5.6.1/contracts/token/ERC20) or generated with the [OpenZeppelin Contracts Wizard for Polkadot](https://wizard.openzeppelin.com/polkadot). ## Prerequisites Before you begin, ensure you have: - A basic understanding of [Solidity](https://www.soliditylang.org/) programming and [ERC-20](https://ethereum.org/developers/docs/standards/tokens/erc-20/) fungible tokens. - An EVM-compatible [wallet](/smart-contracts/connect/) connected to Polkadot Hub. This example utilizes [MetaMask](https://metamask.io/). - Test tokens for gas fees, available from the [Polkadot faucet](https://faucet.polkadot.io/). See [Get Test Tokens](/smart-contracts/faucet/#get-test-tokens) for a guide to using the faucet. ## Create Your Contract Follow the steps below to create the ERC-20 contract: 1. Navigate to [Remix IDE](https://remix.ethereum.org/) in your web browser. 2. Select the **Create new file** button under the **contracts** folder, and name your contract `MyToken.sol`. ![](/images/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-remix/remix-01.webp) 3. Now, paste the following ERC-20 contract code into `MyToken.sol`: ```solidity title="MyToken.sol" // SPDX-License-Identifier: MIT // Compatible with OpenZeppelin Contracts ^5.4.0 pragma solidity ^0.8.27; import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol"; import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol"; contract MyToken is ERC20, Ownable, ERC20Permit { constructor(address initialOwner) ERC20("MyToken", "MTK") Ownable(initialOwner) ERC20Permit("MyToken") {} function mint(address to, uint256 amount) public onlyOwner { _mint(to, amount); } } ``` !!! tip The [OpenZeppelin Contracts Wizard for Polkadot](https://wizard.openzeppelin.com/polkadot) was used to generate this example ERC-20 contract. Use it to customize and generate your own ERC-20, ERC-721, or other OpenZeppelin-standard contracts for Polkadot Hub. ## Compile the Contract Solidity source code compiles into bytecode that can be deployed on the blockchain. During this process, the compiler checks the contract for syntax errors, ensures type safety, and generates the machine-readable instructions needed for blockchain execution. Ensure your `MyToken.sol` contract is open in the Remix IDE Editor, and use the following steps to compile: 1. Select the **Solidity Compiler** plugin from the left panel. 2. Select the **Compile MyToken.sol** button. The **Solidity Compiler** icon will display a green checkmark once the contract compiles successfully. If any issues arise during contract compilation, errors and warnings will appear in the terminal panel at the bottom of the screen. ![](/images/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-remix/remix-03.gif) ## Deploy the Contract Follow these steps to deploy the contract using Remix: 1. Select **Deploy & Run Transactions** from the left panel. 2. Ensure your MetaMask wallet is connected to Polkadot Hub TestNet, then select the **Environment** dropdown and select **Injected Provider - MetaMask**. 3. Configure the contract parameters by entering the address that will own the deployed token contract. 4. Select the **Deploy** button to initiate the deployment. 4. Approve the transaction in your MetaMask wallet when prompted. 6. You will see the transaction details in the terminal when the deployment succeeds, including the contract address and deployment transaction hash. ![](/images/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-remix/remix-04.gif) Once successfully deployed, your contract will appear in the **Deployed Contracts** section, ready for interaction. ## Interact with the Contract Once deployed, you can interact with your contract through Remix. Find your contract under **Deployed/Unpinned Contracts**, and select it to expand the available methods. In this example, you'll mint some tokens to a given address using the following steps: 1. Expand the **mint** function, then enter the recipient address and the amount (remember to add 18 zeros for one whole token). 2. Select **transact**. 3. Approve the transaction in your MetaMask wallet when prompted. 4. You will see a green check mark in the terminal when the transaction is successful. 5. You can also call the **balanceOf** function by passing the address of the **mint** call to confirm the new balance. ![](/images/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-remix/remix-05.gif) Feel free to explore and interact with the contract's other functions by selecting the method, providing any required parameters, and confirming the transaction in MetaMask when prompted. Congratulations! You've successfully deployed an ERC-20 token contract to Polkadot Hub TestNet using Remix IDE. Consider the following resources to build upon your progress. ## Where to Go Next
- Guide __Deploy an NFT with Remix__ --- Walk through deploying an ERC-721 Non-Fungible Token (NFT) using OpenZeppelin's battle-tested NFT implementation and Remix. [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-remix/)
--- Page Title: Deploy an ERC-721 NFT Using Remix - Resolved Markdown: https://docs.polkadot.com/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-remix.md - Canonical (HTML): https://docs.polkadot.com/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-remix/ - Summary: Learn how to deploy an ERC-721 NFT contract to Polkadot Hub using Remix, a browser-based IDE for quick prototyping and learning. - Word Count: 673; Token Estimate: 1135 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:4f5abda2e8dd2b4cfdedf802e3f18e8424a76a74437ea25cbd105d56b379c1be # Deploy an NFT with Remix ## Introduction Non-Fungible Tokens (NFTs) represent unique digital assets commonly used for digital art, collectibles, gaming, and identity verification. This guide demonstrates how to deploy an [ERC-721](https://eips.ethereum.org/EIPS/eip-721) NFT contract to [Polkadot Hub](/smart-contracts/overview/#smart-contract-development). You'll use [OpenZeppelin's battle-tested NFT implementation](https://github.com/OpenZeppelin/openzeppelin-contracts) and [Remix](https://remix.ethereum.org/), a visual, browser-based environment perfect for rapid prototyping and learning. It requires no local installation and provides an intuitive interface for contract development. ## Prerequisites - A basic understanding of [Solidity](https://www.soliditylang.org/) programming and [ERC-721 NFT](https://ethereum.org/developers/docs/standards/tokens/erc-721/) standards. - An EVM-compatible [wallet](/smart-contracts/connect/) connected to Polkadot Hub. This example utilizes [MetaMask](https://metamask.io/). - Test tokens for gas fees (available from the [Polkadot faucet](https://faucet.polkadot.io/)). See [Get Test Tokens](/smart-contracts/faucet/#get-test-tokens) for a guide to using the faucet. ## Create Your Contract Follow the steps below to create the ERC-721 contract: 1. Navigate to [Remix IDE](https://remix.ethereum.org/) in your web browser. 2. Select the **Create new file** button under the **contracts** folder, and name your contract `MyNFT.sol`. ![](/images/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-remix/remix-01.webp) 3. Now, paste the following ERC-721 contract code into `MyNFT.sol`: ```solidity title="contracts/MyNFT.sol" // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import "@openzeppelin/contracts/token/ERC721/ERC721.sol"; import "@openzeppelin/contracts/access/Ownable.sol"; contract MyNFT is ERC721, Ownable { uint256 private _nextTokenId; constructor( address initialOwner ) ERC721("MyToken", "MTK") Ownable(initialOwner) {} function safeMint(address to) public onlyOwner { uint256 tokenId = _nextTokenId++; _safeMint(to, tokenId); } } ``` !!! tip The [OpenZeppelin Contracts Wizard for Polkadot](https://wizard.openzeppelin.com/polkadot) was used to generate this example ERC-721 contract. Use it to customize and generate your own ERC-20, ERC-721, or other OpenZeppelin-standard contracts for Polkadot Hub. ## Compile the Contract Solidity source code compiles into bytecode that can be deployed on the blockchain. During this process, the compiler checks the contract for syntax errors, ensures type safety, and generates the machine-readable instructions needed for blockchain execution. Ensure your `MyNFT.sol` contract is open in the Remix IDE Editor, and use the following steps to compile: 1. Select the **Solidity Compiler** plugin from the left panel. 2. Select the **Compile MyToken.sol** button. The **Solidity Compiler** icon will display a green checkmark once the contract compiles successfully. If any issues arise during contract compilation, errors and warnings will appear in the terminal panel at the bottom of the screen. ![](/images/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-remix/remix-02.webp) ## Deploy the Contract Follow these steps to deploy the contract using Remix: 1. Select **Deploy & Run Transactions** from the left panel. 2. Ensure your MetaMask wallet is connected to Polkadot Hub TestNet, then select the **Environment** dropdown and select **Injected Provider - MetaMask**. ![](/images/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-remix/remix-03.webp) 3. Configure the contract parameters by entering the address that will own the deployed NFT contract. 4. Select the **Deploy** button to initiate the deployment. 5. Approve the transaction in your MetaMask wallet when prompted. 6. You will see the transaction details in the terminal when the deployment succeeds, including the contract address and deployment transaction hash. ![](/images/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-remix/remix-04.webp) Once successfully deployed, your contract will appear in the **Deployed Contracts** section, ready for interaction. Congratulations! You've successfully deployed an ERC-721 NFT contract to Polkadot Hub TestNet using Remix IDE. Consider the following resources to build upon your progress. ## Where to Go Next
- Guide __Deploy an ERC-20__ --- Walk through deploying a fully-functional ERC-20 to Polkadot Hub using Remix. [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-remix/)
--- Page Title: Deploy an ERC-721 Using Hardhat - Resolved Markdown: https://docs.polkadot.com/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-hardhat.md - Canonical (HTML): https://docs.polkadot.com/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-hardhat/ - Summary: Learn how to deploy an ERC-721 NFT contract to Polkadot Hub using Hardhat, a comprehensive development environment with built-in deployment capabilities. - Word Count: 976; Token Estimate: 1826 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:cf85263483252c058f46af69eb0ca948509aa03334e933e7786decb689acf4d4 # Deploy an ERC-721 Using Hardhat ## Introduction Non-Fungible Tokens (NFTs) represent unique digital assets commonly used for digital art, collectibles, gaming, and identity verification. This guide demonstrates how to deploy an [ERC-721](https://eips.ethereum.org/EIPS/eip-721) NFT contract to [Polkadot Hub](/smart-contracts/overview/#smart-contract-development) TestNet. You'll use OpenZeppelin's battle-tested [NFT implementation](https://github.com/OpenZeppelin/openzeppelin-contracts) and [Hardhat](https://hardhat.org/docs/getting-started), a comprehensive development environment with built-in testing, debugging, and deployment capabilities. You can generate a custom NFT contract with the [OpenZeppelin Contracts Wizard for Polkadot](https://wizard.openzeppelin.com/polkadot), then use it in this Hardhat workflow. Hardhat uses standard Solidity compilation to generate EVM bytecode, making it fully compatible with Polkadot Hub's EVM environment. ## Prerequisites Before you begin, ensure you have the following: - A basic understanding of [Solidity](https://www.soliditylang.org/) programming and [ERC-721](https://ethereum.org/developers/docs/standards/tokens/erc-721/) non-fungible tokens. - [Node.js](https://nodejs.org/en/download) v22.13.1 or later installed. - Test tokens for gas fees, available from the [Polkadot faucet](https://faucet.polkadot.io/). See [Get Test Tokens](/smart-contracts/faucet/#get-test-tokens) for a guide to using the faucet. - A wallet with a private key for signing transactions. ## Set Up Your Project 1. Use the following terminal commands to create a directory and initialize your Hardhat project inside of it: ```bash mkdir hardhat-nft-deployment cd hardhat-nft-deployment npx hardhat@^2.27.0 init ``` 2. Install the OpenZeppelin contract dependencies using the command: ```bash npm install @openzeppelin/contracts ``` ## Configure Hardhat Open `hardhat.config.ts` and update to add `polkadotTestnet` to the `networks` configuration as highlighted in the following example code: ```typescript title="hardhat.config.ts" hl_lines='18-23' import type { HardhatUserConfig } from 'hardhat/config'; import hardhatToolboxViemPlugin from '@nomicfoundation/hardhat-toolbox-viem'; import { vars } from 'hardhat/config'; const config: HardhatUserConfig = { plugins: [hardhatToolboxViemPlugin], solidity: { version: '0.8.28', settings: { optimizer: { enabled: true, runs: 200, }, }, }, networks: { polkadotTestnet: { url: 'https://services.polkadothub-rpc.com/testnet', chainId: 420420417, accounts: [vars.get('PRIVATE_KEY')], }, }, }; export default config; ``` !!! tip Visit the Hardhat [Configuration variables](https://v2.hardhat.org/hardhat-runner/docs/guides/configuration-variables) documentation to learn how to use Hardhat to handle your private keys securely. ## Create the Contract Follow these steps to create your smart contract: 1. Delete the default contract file(s) in the `contracts` directory. 2. Create a new file named `MyNFT.sol` inside the `contracts` directory. 3. Add the following code to create the `MyNFT.sol` smart contract: ```solidity title="contracts/MyNFT.sol" // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import "@openzeppelin/contracts/token/ERC721/ERC721.sol"; import "@openzeppelin/contracts/access/Ownable.sol"; contract MyNFT is ERC721, Ownable { uint256 private _nextTokenId; constructor( address initialOwner ) ERC721("MyToken", "MTK") Ownable(initialOwner) {} function safeMint(address to) public onlyOwner { uint256 tokenId = _nextTokenId++; _safeMint(to, tokenId); } } ``` ## Compile the Contract Compile your `MyNFT.sol` contract using the following command: ```bash npx hardhat compile ``` You will see a message in the terminal confirming the contract was successfully compiled, similar to the following:
npx hardhat compile Downloading solc 0.8.28 Downloading solc 0.8.28 (WASM build) Compiled 1 Solidity file with solc 0.8.28 (evm target: cancun)
## Deploy the Contract You are now ready to deploy the contract to your chosen network. This example demonstrates deployment to the Polkadot TestNet. Deploy the contract as follows: 1. Delete the default file(s) inside the `ignition/modules` directory. 2. Create a new file named `MyNFT.ts` inside the `ignition/modules` directory. 3. Open `ignition/modules/MyNFT.ts` and add the following code to create your deployment module: ```typescript title="ignition/modules/MyNFT.ts" import { buildModule } from '@nomicfoundation/hardhat-ignition/modules'; export default buildModule('MyNFTModule', (m) => { const initialOwner = m.getParameter('initialOwner', 'INSERT_OWNER_ADDRESS'); const myNFT = m.contract('MyNFT', [initialOwner]); return { myNFT }; }); ``` Replace `INSERT_OWNER_ADDRESS` with your desired owner address. 4. Deploy your contract to Polkadot Hub TestNet using the following command: ```bash npx hardhat ignition deploy ignition/modules/MyNFT.ts --network polkadotTestnet ``` 5. Confirm the target deployment network name and chain ID when prompted:
npx hardhat ignition deploy ignition/modules/MyNFT.ts --network polkadotHubTestnet ✔ Confirm deploy to network polkadotTestnet (420420417)? … yes   Hardhat Ignition 🚀   Deploying [ MyNFTModule ]   Batch #1 Executed MyNFTModule#MyNFT   Batch #2 Executed MyNFTModule#MyNFT.safeMint   [ TokenModule ] successfully deployed 🚀   Deployed Addresses   MyNFTModule#MyNFT - 0x1234.......
Congratulations! You've successfully deployed an ERC-721 NFT contract to Polkadot Hub TestNet using Hardhat. Consider the following resources to build upon your progress. ## Where to Go Next
- Guide __Deploy an ERC-20__ --- Walk through deploying a fully-functional ERC-20 to Polkadot Hub using Hardhat. [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-hardhat/) - Guide __Create a DApp__ --- Learn step-by-step how to build a fully functional dApp that interacts with a smart contract deployed via Hardhat. [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/dapps/zero-to-hero/)
--- Page Title: Get Started with Parachain Development - Resolved Markdown: https://docs.polkadot.com/parachains/get-started.md - Canonical (HTML): https://docs.polkadot.com/parachains/get-started/ - Summary: Practical examples and tutorials for building and deploying Polkadot parachains, covering everything from launch to customization and cross-chain messaging. - Word Count: 238; Token Estimate: 557 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:33ba15486ecca4f2953ffecd2080f2fed3e8b3f42fa015ae2cef4a227bb84606 # Get Started The following sections provide practical recipes for building parachains on Polkadot—each focused on specific development scenarios with step-by-step, hands-on examples. ## Quick Start Guides Quick start guides help developers set up and interact with the Polkadot parachain ecosystem using various tools and frameworks. | Tutorial | Tools | Description | |:----------------------------------------------------------------------------------------------:|:---------------------:|:-----------------------------------------------------------------------:| | [Set Up the Parachain Template](/parachains/launch-a-parachain/set-up-the-parachain-template/) | Polkadot SDK | Learn how to set up and run the Polkadot SDK Parachain Template locally | | [Launch a Local Parachain](/parachains/testing/run-a-parachain-network/) | Zombienet, Chopsticks | Set up a local development environment for testing | | [Fork an Existing Parachain](/parachains/testing/fork-a-parachain/) | Chopsticks | Create a local fork of a live parachain for testing | ## Launch a Simple Parachain Learn the fundamentals of launching and deploying a parachain to the Polkadot network. ## Customize Your Runtime Build custom functionality for your parachain by composing and creating pallets. ### Pallet Development Deep dive into creating and managing custom pallets for your parachain. ## Testing Test your parachain in various environments before production deployment. ## Runtime Upgrades and Maintenance Manage your parachain's lifecycle with forkless upgrades and maintenance operations. ## Interoperability Configure your parachain for cross-chain communication using XCM (Cross-Consensus Messaging). ## Integrations Integrate your parachain with essential ecosystem tools and services. ## Additional Resources - [Polkadot SDK Documentation](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/index.html) - [Polkadot Wiki - Parachains](https://wiki.polkadot.com/learn/learn-parachains/) --- Page Title: Get Started with Smart Contracts - Resolved Markdown: https://docs.polkadot.com/smart-contracts/get-started.md - Canonical (HTML): https://docs.polkadot.com/smart-contracts/get-started/ - Summary: Practical examples for building and deploying smart contracts on Polkadot Hub, from connecting and tooling to deployment, integrations, and precompiles. - Word Count: 515; Token Estimate: 1168 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:6073c66c449fe1d6b8271e429308b0ed5ad5412e8de3dfc0a91818a1b5258eb9 # Get Started with Smart Contracts This resource provides quick-starts for building smart contracts on Polkadot Hub. Use the tables below to jump directly to the tools and workflows you need. ## Quick Starts Use these curated links to get connected, get funded, and deploy your first contract. | Quick Start | Tools | Description | |-----------------------------------------------------|-----------------------|-----------------------------------------------------------------| | [Connect to Polkadot](/smart-contracts/connect/) | Polkadot.js, MetaMask | Add the network, configure RPC, verify activity in the explorer | | [Get Test Tokens](/smart-contracts/faucet/) | - | Request test funds to deploy and interact with contracts | | [Explore Transactions](/smart-contracts/explorers/) | BlockScout, Routescan, Subscan | Inspect transactions, logs, token transfers, and contract state | ## Build and Test Locally Set up local environments and CI-friendly workflows to iterate quickly and validate changes before deploying. ## Ethereum Tool Differences on Polkadot EVM Tools like **Foundry** and **Hardhat** are built for standard Ethereum nodes. Polkadot EVM networks (such as Polkadot Hub) use the same [Ethereum JSON-RPC](https://ethereum.org/developers/docs/apis/json-rpc/) interface, but run on a different execution environment (Substrate with REVM or PVM). As a result: - **Local tests** (e.g., `forge test`, Hardhat's default network) run in the tool's own EVM, not Polkadot's—so behavior can differ from the real chain. - **Time and snapshot helpers** (e.g., `evm_increaseTime`, `loadFixture`) are often not supported on Polkadot nodes. - **Gas reports** from these tools may not match what you see on-chain. **Recommendation:** To check chain-specific behavior, run your contracts against a [local dev node](/smart-contracts/dev-environments/local-dev-node/) or a TestNet. For more details, see [EVM vs PVM](/smart-contracts/for-eth-devs/evm-vs-pvm/) and [Contract Deployment](/smart-contracts/for-eth-devs/contract-deployment/). ## Ethereum Developer Resources Bridge your Ethereum knowledge with Polkadot Hub specifics: account mapping, fees, JSON-RPC, and deployment. ## Cookbook: Hands-on Tutorials Follow step-by-step guides that walk through common tasks and complete dApp examples. | Tutorial | Tools | Description | |------------------------------------------------------------------------------------------------|---------------------|-------------------------------------------| | [Deploy a Basic Contract](/smart-contracts/cookbook/smart-contracts/deploy-basic/basic-remix/) | Remix | Minimal deployment walkthrough | | [Deploy an ERC-20](/smart-contracts/cookbook/smart-contracts/deploy-erc20/erc20-remix/) | Remix, OpenZeppelin | Create, deploy, and mint a fungible token | | [Deploy an NFT (ERC-721)](/smart-contracts/cookbook/smart-contracts/deploy-nft/nft-remix/) | Remix, OpenZeppelin | Build and deploy an NFT collection | | [Uniswap V2](/smart-contracts/cookbook/eth-dapps/uniswap-v2/) | Hardhat | Full dApp project: compile, test, deploy | | [Zero‑to‑Hero dApp](/smart-contracts/cookbook/dapps/zero-to-hero/) | Multiple | End‑to‑end dApp patterns and practices | ## Libraries Choose the client libraries that fit your stack for connecting wallets and calling contracts. ## Integrations Integrate essential services like wallets, indexers, and oracles to round out your dApp. ## Precompiles Discover precompiled system contracts available on the Hub and how to use them. From here, follow the quick starts to get connected, iterate locally with your preferred tools, and use the guides, libraries, integrations, and precompiles as you grow into production‑ready dApps. If you get stuck, [open an issue](https://github.com/polkadot-developers/polkadot-docs/issues/new?template=docs-issue.yml) or reach out in the community channels. --- Page Title: Get Started with XCM - Resolved Markdown: https://docs.polkadot.com/parachains/interoperability/get-started.md - Canonical (HTML): https://docs.polkadot.com/parachains/interoperability/get-started/ - Summary: Unlock blockchain interoperability with XCM — Polkadot's Cross-Consensus Messaging format for cross-chain interactions. - Word Count: 958; Token Estimate: 1453 - Last Updated: 2026-05-27T20:25:14+00:00 - Version Hash: sha256:5d1dcb77cc1d250220feb2c783695093359b47f4446ca1d25bd6f377df391559 # Get Started with XCM ## Introduction Polkadot’s unique value lies in its ability to enable interoperability between parachains and other blockchain systems. At the core of this capability is XCM (Cross-Consensus Messaging)—a flexible messaging format that facilitates communication and collaboration between independent consensus systems. With XCM, one chain can send intents to another one, fostering a more interconnected ecosystem. Although it was developed specifically for Polkadot, XCM is a universal format, usable in any blockchain environment. This guide provides an overview of XCM’s core principles, design, and functionality, alongside practical examples of its implementation. ## Messaging Format XCM is not a protocol but a standardized [messaging format](https://github.com/polkadot-fellows/xcm-format). It defines the structure and behavior of messages but does not handle their delivery. This separation allows developers to focus on crafting instructions for target systems without worrying about transmission mechanics. XCM messages are intent-driven, outlining desired actions for the receiving blockchain to consider and potentially alter its state. These messages do not directly execute changes; instead, they rely on the host chain's environment to interpret and implement them. By utilizing asynchronous composability, XCM facilitates efficient execution where messages can be processed independently of their original order, similar to how RESTful services handle HTTP requests without requiring sequential processing. ## The Four Principles of XCM XCM adheres to four guiding principles that ensure robust and reliable communication across consensus systems: - **Asynchronous**: XCM messages operate independently of sender acknowledgment, avoiding delays due to blocked processes. - **Absolute**: XCM messages are guaranteed to be delivered and interpreted accurately, in order, and timely. Once a message is sent, one can be sure it will be processed as intended. - **Asymmetric**: XCM messages follow the 'fire and forget' paradigm meaning no automatic feedback is provided to the sender. Any results must be communicated separately to the sender with an additional message back to the origin. - **Agnostic**: XCM operates independently of the specific consensus mechanisms, making it compatible across diverse systems. These principles guarantee that XCM provides a reliable framework for cross-chain communication, even in complex environments. ## The XCM Tech Stack ![Diagram of the XCM tech stack](/images/parachains/interoperability/get-started/intro-to-xcm-01.webp) The XCM tech stack is designed to facilitate seamless interoperable communication between chains that reside within the Polkadot ecosystem. XCM can be used to express the meaning of the messages over each of the communication channels. ## Core Functionalities of XCM XCM enhances cross-consensus communication by introducing several powerful features: - **Programmability**: Supports dynamic message handling, allowing for more comprehensive use cases. Includes branching logic, safe dispatches for version checks, and asset operations like NFT management. - **Functional Multichain Decomposition**: Enables mechanisms such as remote asset locking, asset namespacing, and inter-chain state referencing, with contextual message identification. - **Bridging**: Establishes a universal reference framework for multi-hop setups, connecting disparate systems like Ethereum and Bitcoin with the Polkadot relay chain acting as a universal location. The standardized format for messages allows parachains to handle tasks like user balances, governance, and staking, freeing the Polkadot relay chain to focus on shared security. These features make XCM indispensable for implementing scalable and interoperable blockchain applications. ## XCM Example The following is a simplified XCM message demonstrating a token transfer from Alice to Bob on the same chain (ParaA). ```rust let message = Xcm(vec![ WithdrawAsset((Here, amount).into()), BuyExecution { fees: (Here, amount).into(), weight_limit: WeightLimit::Unlimited }, DepositAsset { assets: All.into(), beneficiary: MultiLocation { parents: 0, interior: Junction::AccountId32 { network: None, id: BOB.clone().into() }.into(), }.into() } ]); ``` The message consists of three instructions described as follows: - **[WithdrawAsset](https://github.com/polkadot-fellows/xcm-format?tab=readme-ov-file#withdrawasset)**: Transfers a specified number of tokens from Alice's account to a holding register. ```rust WithdrawAsset((Here, amount).into()), ``` - **`Here`**: The native parachain token. - **`amount`**: The number of tokens that are transferred. The first instruction takes as an input the MultiAsset that should be withdrawn. The MultiAsset describes the native parachain token with the `Here` keyword. The `amount` parameter is the number of tokens that are transferred. The withdrawal account depends on the origin of the message. In this example the origin of the message is Alice. The `WithdrawAsset` instruction moves `amount` number of native tokens from Alice's account into the holding register. - **[BuyExecution](https://github.com/polkadot-fellows/xcm-format?tab=readme-ov-file#buyexecution)**: Allocates fees to cover the execution Weight of the XCM instructions. ```rust BuyExecution { fees: (Here, amount).into(), weight_limit: WeightLimit::Unlimited }, ``` - **`fees`**: Describes the asset in the holding register that should be used to pay for the weight. - **`weight_limit`**: Defines the maximum fees that can be used to buy weight. - **[DepositAsset](https://github.com/polkadot-fellows/xcm-format?tab=readme-ov-file#depositasset)**: Moves the remaining tokens from the holding register to Bob’s account. ```rust DepositAsset { assets: All.into(), beneficiary: MultiLocation { parents: 0, interior: Junction::AccountId32 { network: None, id: BOB.clone().into() }.into(), }.into() } ``` - **`All`**: The wildcard for the asset(s) to be deposited. In this case, all assets in the holding register should be deposited. This step-by-step process showcases how XCM enables precise state changes within a blockchain system. You can find a complete XCM message example in the [XCM repository](https://github.com/paritytech/xcm-docs/blob/main/examples/src/0_first_look/mod.rs). ## Overview XCM revolutionizes cross-chain communication by enabling use cases such as: - Token transfers between blockchains. - Asset locking for cross-chain smart contract interactions. - Remote execution of functions on other blockchains. These functionalities empower developers to build innovative, multi-chain applications, leveraging the strengths of various blockchain networks. To stay updated on XCM’s evolving format or contribute, visit the [XCM repository](https://github.com/paritytech/xcm-docs/blob/main/examples/src/0_first_look/mod.rs). --- Page Title: Install Polkadot SDK - Resolved Markdown: https://docs.polkadot.com/parachains/install-polkadot-sdk.md - Canonical (HTML): https://docs.polkadot.com/parachains/install-polkadot-sdk/ - Summary: Install all required Polkadot SDK dependencies, set up the SDK itself, and verify that it runs correctly on your machine. - Word Count: 3234; Token Estimate: 5120 - Last Updated: 2026-05-19T14:51:06+00:00 - Version Hash: sha256:71bd962e39b3eb74d9a69e19ba5ac881bf43703eba51286cffc8ad29940ebb19 # Install Polkadot SDK This guide provides step-by-step instructions for installing the Polkadot SDK on macOS, Linux, and Windows. The installation process consists of two main parts: - **Installing dependencies**: Setting up Rust, required system packages, and development tools. - **Building the Polkadot SDK**: Cloning and compiling the Polkadot SDK repository. Follow the appropriate section for your operating system to ensure all necessary tools are installed and configured properly. ## Install Dependencies: macOS You can install Rust and set up a Substrate development environment on Apple macOS computers with Intel or Apple M1 processors. ### Before You Begin {: #before-you-begin-mac-os } Before you install Rust and set up your development environment on macOS, verify that your computer meets the following basic requirements: - Operating system version is 10.7 Lion or later. - Processor speed of at least 2 GHz. Note that 3 GHz is recommended. - Memory of at least 8 GB RAM. Note that 16 GB is recommended. - Storage of at least 10 GB of available space. - Broadband Internet connection. ### Install Command Line Tools Xcode Command Line Tools provide essential build dependencies including `clang`, `make`, and other tools required to compile native crates like `librocksdb-sys`. To install them, run: ```bash xcode-select --install ``` ### Install Homebrew In most cases, you should use Homebrew to install and manage packages on macOS computers. If you don't already have Homebrew installed on your local computer, you should download and install it before continuing. To install Homebrew: 1. Open the Terminal application. 2. Download and install Homebrew by running the following command: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" ``` 3. Verify Homebrew has been successfully installed by running the following command: ```bash brew --version ``` The command displays output similar to the following:
brew --version Homebrew 4.3.15
### Support for Apple Silicon Protobuf must be installed before the build process can begin. To install it, run the following command: ```bash brew install protobuf ``` ### Install Required Packages and Rust {: #install-required-packages-and-rust-mac-os } Because the blockchain requires standard cryptography to support the generation of public/private key pairs and the validation of transaction signatures, you must also have a package that provides cryptography, such as `openssl`. To install `openssl` and the Rust toolchain on macOS: 1. Open the Terminal application. 2. Ensure you have an updated version of Homebrew by running the following command: ```bash brew update ``` 3. Install the `openssl` package by running the following command: ```bash brew install openssl ``` 4. Download the `rustup` installation program and use it to install Rust by running the following command: ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` 5. Follow the prompts displayed to proceed with a default installation. 6. Update your current shell to include Cargo by running the following command: ```bash source ~/.cargo/env ``` 7. Configure the Rust toolchain to default to the latest stable version by running the following commands: ```bash rustup default stable rustup update rustup target add wasm32-unknown-unknown rustup component add rust-src ``` 8. Proceed to [Build the Polkadot SDK](#build-the-polkadot-sdk). ## Install Dependencies: Linux Rust supports most Linux distributions. Depending on the specific distribution and version of the operating system you use, you might need to add some software dependencies to your environment. In general, your development environment should include a linker or a C-compatible compiler, such as `clang`, and an appropriate integrated development environment (IDE). ### Before You Begin {: #before-you-begin-linux } Check the documentation for your operating system for information about the installed packages and how to download and install any additional packages you might need. For example, if you use Ubuntu, you can use the Ubuntu Advanced Packaging Tool (`apt`) to install the `build-essential` package: ```bash sudo apt install build-essential ``` At a minimum, you need the following packages before you install Rust: ```text clang curl git make ``` Because the blockchain requires standard cryptography to support the generation of public/private key pairs and the validation of transaction signatures, you must also have a package that provides cryptography, such as `libssl-dev` or `openssl-devel`. ### Install Required Packages and Rust {: #install-required-packages-and-rust-linux } To install the Rust toolchain on Linux: 1. Open a terminal shell. 2. Check the packages installed on the local computer by running the appropriate package management command for your Linux distribution. 3. Add any package dependencies you are missing to your local development environment by running the appropriate package management command for your Linux distribution: === "Ubuntu" ```bash sudo apt install --assume-yes git clang curl libssl-dev llvm libclang-dev libudev-dev make protobuf-compiler ``` === "Debian" ```sh sudo apt install --assume-yes git clang curl libssl-dev llvm libclang-dev libudev-dev make protobuf-compiler ``` === "Arch" ```sh pacman -Syu --needed --noconfirm curl git clang make protobuf ``` === "Fedora" ```sh sudo dnf update sudo dnf install clang curl git openssl-devel make protobuf-compiler ``` === "OpenSUSE" ```sh sudo zypper install clang curl git openssl-devel llvm-devel libudev-devel make protobuf ``` Remember that different distributions might use different package managers and bundle packages in different ways. For example, depending on your installation selections, Ubuntu Desktop and Ubuntu Server might have different packages and different requirements. However, the packages listed in the command-line examples are applicable to many common Linux distributions, including Debian, Linux Mint, MX Linux, and Elementary OS. 4. Download the `rustup` installation program and use it to install Rust by running the following command: ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` 5. Follow the prompts displayed to proceed with a default installation. 6. Update your current shell to include Cargo by running the following command: ```bash source $HOME/.cargo/env ``` 7. Verify your installation by running the following command: ```bash rustc --version ``` 8. Configure the Rust toolchain to default to the latest stable version by running the following commands: ```bash rustup default stable rustup update rustup target add wasm32-unknown-unknown rustup component add rust-src ``` 9. Proceed to [Build the Polkadot SDK](#build-the-polkadot-sdk). ## Install Dependencies: Windows (WSL) In general, UNIX-based operating systems—like macOS or Linux—provide a better development environment for building Substrate-based blockchains. However, suppose your local computer uses Microsoft Windows instead of a UNIX-based operating system. In that case, you can configure it with additional software to make it a suitable development environment for building Substrate-based blockchains. To prepare a development environment on a Microsoft Windows computer, you can use Windows Subsystem for Linux (WSL) to emulate a UNIX operating environment. ### Before You Begin {: #before-you-begin-windows-wls } Before installing on Microsoft Windows, verify the following basic requirements: - You have a computer running a supported Microsoft Windows operating system: - **For Windows desktop**: You must be running Microsoft Windows 10, version 2004 or later, or Microsoft Windows 11 to install WSL. - **For Windows server**: You must be running Microsoft Windows Server 2019, or later, to install WSL on a server operating system. - You have a good internet connection and access to a shell terminal on your local computer. ### Set Up Windows Subsystem for Linux WSL enables you to emulate a Linux environment on a computer that uses the Windows operating system. The primary advantage of this approach for Substrate development is that you can use all of the code and command-line examples as described in the Substrate documentation. For example, you can run common commands—such as `ls` and `ps`—unmodified. By using WSL, you can avoid configuring a virtual machine image or a dual-boot operating system. To prepare a development environment using WSL: 1. Check your Windows version and build number to see if WSL is enabled by default. If you have Microsoft Windows 10, version 2004 (Build 19041 and higher), or Microsoft Windows 11, WSL is available by default and you can continue to the next step. If you have an older version of Microsoft Windows installed, see the [WSL manual installation steps for older versions](https://learn.microsoft.com/en-us/windows/wsl/install-manual). If you are installing on an older version of Microsoft Windows, you can download and install WLS 2 if your computer has Windows 10, version 1903 or higher. 2. Select **Windows PowerShell** or **Command Prompt** from the **Start** menu, right-click, then **Run as administrator**. 3. In the PowerShell or Command Prompt terminal, run the following command: ```bash wsl --install ``` This command enables the required WSL 2 components that are part of the Windows operating system, downloads the latest Linux kernel, and installs the Ubuntu Linux distribution by default. If you want to review the other Linux distributions available, run the following command: ```bash wsl --list --online ``` 4. After the distribution is downloaded, close the terminal. 5. Click the **Start** menu, select **Shut down or sign out**, then click **Restart** to restart the computer. Restarting the computer is required to start the installation of the Linux distribution. It can take a few minutes for the installation to complete after you restart. For more information about setting up WSL as a development environment, see the [Set up a WSL development environment](https://learn.microsoft.com/en-us/windows/wsl/setup/environment) docs. ### Install Required Packages and Rust {: #install-required-packages-and-rust-windows-wls } To install the Rust toolchain on WSL: 1. Click the **Start** menu, then select **Ubuntu**. 2. Type a UNIX user name to create a user account. 3. Type a password for your UNIX user, then retype the password to confirm it. 4. Download the latest updates for the Ubuntu distribution using the Ubuntu Advanced Packaging Tool (`apt`) by running the following command: ```bash sudo apt update ``` 5. Add the required packages for the Ubuntu distribution by running the following command: ```bash sudo apt install --assume-yes git clang curl libssl-dev llvm libclang-dev libudev-dev make protobuf-compiler ``` 6. Download the `rustup` installation program and use it to install Rust for the Ubuntu distribution by running the following command: ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` 7. Follow the prompts displayed to proceed with a default installation. 8. Update your current shell to include Cargo by running the following command: ```bash source ~/.cargo/env ``` 9. Verify your installation by running the following command: ```bash rustc --version ``` 10. Configure the Rust toolchain to use the latest stable version as the default toolchain by running the following commands: ```bash rustup default stable rustup update rustup target add wasm32-unknown-unknown rustup component add rust-src ``` 11. Proceed to [Build the Polkadot SDK](#build-the-polkadot-sdk). ## Build the Polkadot SDK After installing all dependencies, you can now clone and compile the Polkadot SDK repository to verify your setup. ### Clone the Polkadot SDK 1. Clone the Polkadot SDK repository: ```bash git clone https://github.com/paritytech/polkadot-sdk.git ``` 2. Navigate into the project directory: ```bash cd polkadot-sdk ``` ### Compile the Polkadot SDK Compile the entire Polkadot SDK repository to ensure your environment is properly configured: ```bash cargo build --release --locked ``` !!!note This initial compilation will take significant time, depending on your machine specifications. It compiles all components of the Polkadot SDK to verify your toolchain is correctly configured. ### Verify the Build Once the build completes successfully, verify the installation by checking the compiled binaries: ```bash ls target/release ``` You should see several binaries, including: - `polkadot`: The Polkadot relay chain node. - `polkadot-parachain`: The parachain collator node. - `polkadot-omni-node`:The omni node for running parachains. - `substrate-node`: The kitchensink node with many pre-configured pallets. Verify the Polkadot binary works by checking its version: ```bash ./target/release/polkadot --version ``` This should display version information similar to: ```bash polkadot 1.16.0-1234abcd567 ``` If you see the version output without errors, your development environment is correctly configured and ready for Polkadot SDK development! ## Optional: Run the Kitchensink Node The Polkadot SDK includes a feature-rich node called "kitchensink" located at `substrate/bin/node`. This node comes pre-configured with many pallets and features from the Polkadot SDK, making it an excellent reference for exploring capabilities and understanding how different components work together. !!!note If you've already compiled the Polkadot SDK in the previous step, the `substrate-node` binary is already built and ready to use. You can skip directly to running the node. ### Run the Kitchensink Node in Development Mode From the `polkadot-sdk` root directory, start the kitchensink node in development mode: ```bash ./target/release/substrate-node --dev ``` The `--dev` flag enables development mode, which: - Runs a single-node development chain. - Produces and finalizes blocks automatically. - Uses pre-configured development accounts (Alice, Bob, etc.). - Deletes all data when stopped, ensuring a clean state on restart.
./target/release/substrate-node --dev 2025-10-25 09:08:53 Substrate Node 2025-10-25 09:08:53 ✌️ version 3.0.0-dev-7304295748b 2025-10-25 09:08:53 ❤️ by Parity Technologies <admin@parity.io>, 2017-2025 2025-10-25 09:08:53 📋 Chain specification: Development 2025-10-25 09:08:53 🏷 Node name: squalid-shelf-0944 2025-10-25 09:08:53 👤 Role: AUTHORITY 2025-10-25 09:08:53 💾 Database: RocksDb at /var/folders/6t/fw37yfvx14qgwv5sl5p0lcph0000gn/T/substrate0XFsh7/chains/dev/db/full 2025-10-25 09:08:57 🔨 Initializing Genesis block/state (state: 0x9831…a36f, header-hash: 0x6eaf…0764) 2025-10-25 09:08:57 Creating transaction pool txpool_type=ForkAware ready=Limit { count: 8192, total_bytes: 20971520 } future=Limit { count: 819, total_bytes: 2097152 } 2025-10-25 09:08:57 👴 Loading GRANDPA authority set from genesis on what appears to be first startup. 2025-10-25 09:08:57 👶 Creating empty BABE epoch changes on what appears to be first startup. 2025-10-25 09:08:57 Using default protocol ID "sup" because none is configured in the chain specs 2025-10-25 09:08:57 Local node identity is: 12D3KooWFug81ps95nGBDXidDv8K9zth3JBwVw3nm8KanZ3Rdi4J 2025-10-25 09:08:57 Running litep2p network backend 2025-10-25 09:08:57 💻 Operating system: macos 2025-10-25 09:08:57 💻 CPU architecture: aarch64 2025-10-25 09:08:57 📦 Highest known block at #0 2025-10-25 09:08:57 〽️ Prometheus exporter started at 127.0.0.1:9615 2025-10-25 09:08:57 Running JSON-RPC server: addr=127.0.0.1:9944,[::1]:9944 2025-10-25 09:08:57 🏁 CPU single core score: 1.55 GiBs, parallelism score: 1.43 GiBs with expected cores: 8 2025-10-25 09:08:57 🏁 Memory score: 65.81 GiBs 2025-10-25 09:08:57 🏁 Disk score (seq. writes): 3.20 GiBs 2025-10-25 09:08:57 🏁 Disk score (rand. writes): 760.04 MiBs 2025-10-25 09:08:57 👶 Starting BABE Authorship worker 2025-10-25 09:08:57 Failed to load AddrCache from file, using empty instead: Failed to encode or decode AddrCache. 2025-10-25 09:08:57 Loaded persisted AddrCache with 0 authority ids. 2025-10-25 09:08:57 🥩 BEEFY gadget waiting for BEEFY pallet to become available... 2025-10-25 09:08:57 Successfully persisted AddrCache on disk 2025-10-25 09:09:00 🙌 Starting consensus session on top of parent 0x6eaf6f7689b01e21821690ce221c6f5a4eeab997242f60d232234b6c1da20764 (#0) 2025-10-25 09:09:00 🎁 Prepared block for proposing at 1 (5 ms) hash: 0xf1937d6bec79950210463b701e187abe7d0d5e3eb6e089f1c15e5857966471ca; parent_hash: 0x6eaf…0764; end: NoMoreTransactions; extrinsics_count: 2 2025-10-25 09:09:00 🔖 Pre-sealed block for proposal at 1. Hash now 0xcf78ec71ff34797161bfeaa325d21f14745b74cbaa59122ed879af024c7a1400, previously 0xf1937d6bec79950210463b701e187abe7d0d5e3eb6e089f1c15e5857966471ca. 2025-10-25 09:09:00 👶 New epoch 0 launching at block 0xcf78…1400 (block slot 587119380 >= start slot 587119380). 2025-10-25 09:09:00 👶 Next epoch starts at slot 587119580 2025-10-25 09:09:00 🏆 Imported #1 (0x6eaf…0764 → 0xcf78…1400) 2025-10-25 09:09:00 maintain txs=(0, 0) a=1 i=1 views=[(1, 0, 0)] event=NewBestBlock { hash: 0xcf78ec71ff34797161bfeaa325d21f14745b74cbaa59122ed879af024c7a1400, tree_route: None } duration=2.034958ms 2025-10-25 09:09:02 💤 Idle (0 peers), best: #1 (0xcf78…1400), finalized #0 (0x6eaf…0764), ⬇ 0 ⬆ 0 2025-10-25 09:09:03 🙌 Starting consensus session on top of parent 0xcf78ec71ff34797161bfeaa325d21f14745b74cbaa59122ed879af024c7a1400 (#1) 2025-10-25 09:09:03 🎁 Prepared block for proposing at 2 (4 ms) hash: 0xc5cc68c6f3dcda8bae3028f2e17a8dcd348c65750332f31af7972f25bf7a7d60; parent_hash: 0xcf78…1400; end: NoMoreTransactions; extrinsics_count: 2 2025-10-25 09:09:03 🔖 Pre-sealed block for proposal at 2. Hash now 0x67d0adc440feeb28c239da9650744d3dbda899b3ca3b8dc00050ce7269ea6aee, previously 0xc5cc68c6f3dcda8bae3028f2e17a8dcd348c65750332f31af7972f25bf7a7d60. 2025-10-25 09:09:03 🏆 Imported #2 (0xcf78…1400 → 0x67d0…6aee) 2025-10-25 09:09:03 maintain txs=(0, 0) a=1 i=2 views=[(2, 0, 0)] event=NewBestBlock { hash: 0x67d0adc440feeb28c239da9650744d3dbda899b3ca3b8dc00050ce7269ea6aee, tree_route: None } duration=301µs 2025-10-25 09:09:06 🙌 Starting consensus session on top of parent 0x67d0adc440feeb28c239da9650744d3dbda899b3ca3b8dc00050ce7269ea6aee (#2) 2025-10-25 09:09:06 🎁 Prepared block for proposing at 3 (5 ms) hash: 0x29eaa5f82783284b25e9c81e851ae5be63c54de28c94f438cbd733f680172ea2; parent_hash: 0x67d0…6aee; end: NoMoreTransactions; extrinsics_count: 2 2025-10-25 09:09:06 🔖 Pre-sealed block for proposal at 3. Hash now 0x8fb26c9192f8738b8971107072f9d106d364ee7f1ece94d8ae5acc9f69cc522f, previously 0x29eaa5f82783284b25e9c81e851ae5be63c54de28c94f438cbd733f680172ea2.
You should see log output indicating the node is running and producing blocks, with increasing block numbers after `finalized`. ### Interact with the Kitchensink Node The kitchensink node is accessible at `ws://localhost:9944`. Open [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer) in your browser to explore its features and connect to the local node. 1. Click the network icon in the top left corner. 2. Scroll to **Development** and select **Local Node**. 3. Click **Switch** to connect to your local node. ![](/images/parachains/install-polkadot-sdk/install-polkadot-sdk-1.webp) Once connected, the interface updates its color scheme to indicate a successful connection to the local node. ![](/images/parachains/install-polkadot-sdk/install-polkadot-sdk-2.webp) You can now explore the various pallets and features included in the kitchensink node, making it a valuable reference as you develop your own blockchain applications. To stop the node, press `Control-C` in the terminal. ## Where to Go Next
- __Get Started with Parachain Development__ --- Practical examples and tutorials for building and deploying Polkadot parachains, covering everything from launch to customization and cross-chain messaging. [:octicons-arrow-right-24: Get Started](/parachains/get-started/)
--- Page Title: Interoperability - Resolved Markdown: https://docs.polkadot.com/reference/parachains/interoperability.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/interoperability/ - Summary: Explore the importance of interoperability in the Polkadot ecosystem, covering XCM, bridges, and cross-chain communication. - Word Count: 581; Token Estimate: 763 - Last Updated: 2026-03-16T21:10:48+00:00 - Version Hash: sha256:72e1be74aca2fb4ee7bbba4de426997b42024a95b15886ec6a6ece0feea58aef # Interoperability ## Introduction Interoperability lies at the heart of the Polkadot ecosystem, enabling communication and collaboration across a diverse range of blockchains. By bridging the gaps between parachains, relay chains, and even external networks, Polkadot unlocks the potential for truly decentralized applications, efficient resource sharing, and scalable solutions. Polkadot’s design ensures that blockchains can transcend their individual limitations by working together as part of a unified system. This cooperative architecture is what sets Polkadot apart in the blockchain landscape. ## Why Interoperability Matters The blockchain ecosystem is inherently fragmented. Different blockchains excel in specialized domains such as finance, gaming, or supply chain management, but these chains function in isolation without interoperability. This lack of connectivity stifles the broader utility of blockchain technology. Interoperability solves this problem by enabling blockchains to: - **Collaborate across networks**: Chains can interact to share assets, functionality, and data, creating synergies that amplify their individual strengths. - **Achieve greater scalability**: Specialized chains can offload tasks to others, optimizing performance and resource utilization. - **Expand use-case potential**: Cross-chain applications can leverage features from multiple blockchains, unlocking novel user experiences and solutions. In the Polkadot ecosystem, interoperability transforms a collection of isolated chains into a cohesive, efficient network, pushing the boundaries of what blockchains can achieve together. ## Key Mechanisms for Interoperability At the core of Polkadot's cross-chain collaboration are foundational technologies designed to break down barriers between networks. These mechanisms empower blockchains to communicate, share resources, and operate as a cohesive ecosystem. ### Cross-Consensus Messaging (XCM): The Backbone of Communication Polkadot's Cross-Consensus Messaging (XCM) is the standard framework for interaction between parachains, relay chains, and, eventually, external blockchains. XCM provides a trustless, secure messaging format for exchanging assets, sharing data, and executing cross-chain operations. Through XCM, decentralized applications can: - Transfer tokens and other assets across chains. - Coordinate complex workflows that span multiple blockchains. - Enable seamless user experiences where underlying blockchain differences are invisible. - XCM exemplifies Polkadot’s commitment to creating a robust and interoperable ecosystem. For further information about XCM, check the [Get Started with XCM](/parachains/interoperability/get-started/) article. ### Bridges: Connecting External Networks While XCM enables interoperability within the Polkadot ecosystem, bridges extend this functionality to external blockchains such as Ethereum and Bitcoin. By connecting these networks, bridges allow Polkadot-based chains to access external liquidity, additional functionalities, and broader user bases. With bridges, developers and users gain the ability to: - Integrate external assets into Polkadot-based applications. - Combine the strengths of Polkadot’s scalability with the liquidity of other networks. - Facilitate accurate multi-chain applications that transcend ecosystem boundaries. For more information about bridges in the Polkadot ecosystem, see the [Bridge Hub](/reference/polkadot-hub/bridging/) guide. ## The Polkadot Advantage Polkadot was purpose-built for interoperability. Unlike networks that add interoperability as an afterthought, Polkadot integrates it as a fundamental design principle. This approach offers several distinct advantages: - **Developer empowerment**: Polkadot’s interoperability tools allow developers to build applications that leverage multiple chains’ capabilities without added complexity. - **Enhanced ecosystem collaboration**: Chains in Polkadot can focus on their unique strengths while contributing to the ecosystem’s overall growth. - **Future-proofing blockchain**: By enabling seamless communication, Polkadot ensures its ecosystem can adapt to evolving demands and technologies. ## Looking Ahead Polkadot’s vision of interoperability extends beyond technical functionality, representing a shift towards a more collaborative blockchain landscape. By enabling chains to work together, Polkadot fosters innovation, efficiency, and accessibility, paving the way for a decentralized future where blockchains are not isolated competitors but interconnected collaborators. --- Page Title: Networks - Resolved Markdown: https://docs.polkadot.com/reference/parachains/networks.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/networks/ - Summary: Explore Polkadot's networks, with Paseo as the official Polkadot TestNet for parachain and dApp development, plus Kusama and Westend for specialized use cases. - Word Count: 1497; Token Estimate: 2025 - Last Updated: 2026-03-16T21:10:48+00:00 - Version Hash: sha256:3c5781d367df932ca11255253b6ff946a269caf3e3b2b29fc3cea524d3636606 # Networks ## Introduction The Polkadot ecosystem is built on a robust set of networks that enable secure, scalable development. Whether you are testing new features or deploying to live production, Polkadot offers several network layers tailored to each stage of the development process. From local environments to the official Polkadot TestNet (Paseo), developers can thoroughly test, iterate, and validate their applications before deploying to Polkadot MainNet. This guide will introduce you to Polkadot's various networks and explain how they fit into the development workflow. ## Network Overview Polkadot's development process is structured to ensure that new features and upgrades are rigorously tested before deployment to live production networks. For all parachain and dApp developers, the recommended progression follows a well-defined path: starting from local environments, testing on Paseo (the official Polkadot TestNet), and ultimately deploying to either Kusama or Polkadot MainNet. The diagram below outlines the recommended development flow: ``` mermaid flowchart LR id1[Local] --> id2[Paseo TestNet] --> id3[Kusama] id1[Local] --> id2[Paseo TestNet] --> id4[Polkadot MainNet] ``` This flow ensures developers can thoroughly test and iterate without risking real tokens or affecting production networks. **Paseo TestNet is the recommended testing environment for all deployments**, whether targeting Kusama or Polkadot. Testing tools like [Chopsticks](#chopsticks) make it easier to experiment safely before releasing to production. ### Recommended Development Path For all parachain teams and dApp developers, the recommended journey looks like this: 1. **Local development node**: Development starts in a local environment, where developers can create, test, and iterate on upgrades or new features using a local development node. This stage enables rapid experimentation in an isolated setup with no external dependencies. Parachain developers can leverage local TestNets, such as [Zombienet](#zombienet), for multi-chain testing. 2. **Paseo (Polkadot TestNet)**: After testing locally, deploy to [Paseo](#polkadot-testnet-paseo), the official Polkadot TestNet. Paseo is a stable, community-run TestNet that mirrors Polkadot's runtime and is specifically designed for parachain teams and dApp developers to test before deploying to production networks. **This is the recommended TestNet whether you plan to deploy to Kusama or Polkadot MainNet**. 3. **Production deployment**: After thorough testing on Paseo, features are considered ready for deployment to either: - **Kusama**: An experimental "canary" network with real economic value, suitable for teams that want to deploy in a faster-moving production environment before Polkadot - **Polkadot MainNet**: The primary production network with enterprise-grade security ### Alternative Networks The Polkadot ecosystem also includes alternative networks, but these are not part of the recommended development flow: - **Westend**: A protocol-focused TestNet maintained by Parity Technologies, primarily used for testing low-level protocol changes and infrastructure updates. Westend is designed for infrastructure operators and core protocol developers, not for general parachain or dApp development. **The onboarding process for Westend is not clearly documented, and external developers should use Paseo TestNet instead.** See the [Other Networks](#other-networks) section for details. !!!note The Rococo TestNet was deprecated on October 14, 2024. Paseo is now the official Polkadot TestNet for parachain and dApp development. For protocol-level testing, teams may use Westend, but most external developers should use Paseo as the default TestNet. ## Polkadot MainNet Polkadot is the production network where real value and live applications operate. After thorough testing on Paseo and local development environments, teams deploy their parachains and dApps to Polkadot MainNet. Polkadot provides enterprise-grade security through its shared security model, where all parachains benefit from the collective security of the relay chain's validator set. The native token for Polkadot is DOT. For more information about DOT, visit the [Native Assets](https://wiki.polkadot.com/learn/learn-dot/) page on the Polkadot Wiki. ## Polkadot TestNet (Paseo) [Paseo](https://github.com/paseo-network) is the official Polkadot TestNet for parachain teams and dApp developers. As a stable, community-run TestNet that mirrors Polkadot's runtime, Paseo is specifically designed to provide a reliable testing environment for teams preparing to deploy to Polkadot MainNet. **Paseo is the recommended TestNet for the vast majority of external developers.** It provides a Polkadot-like environment without the risks and costs associated with live networks, making it ideal for testing parachains, smart contracts, cross-chain messaging (XCM), governance mechanisms, and other application features. Key characteristics of Paseo: - **Official Polkadot TestNet**: Recognized as the primary TestNet for Polkadot ecosystem development - **Stable and reliable**: Maintained by the community with a focus on stability and uptime - **Runtime parity**: Mirrors Polkadot's runtime, ensuring your tests accurately reflect MainNet behavior - **Community-driven**: Governed and operated by Polkadot community members - **Purpose-built for developers**: Specifically designed for parachain and dApp testing workflows The native token for Paseo is PAS. TestNet tokens are available from the [Polkadot faucet](https://faucet.polkadot.io/). Additional information on PAS is available on the [Native Assets](https://wiki.polkadot.com/learn/learn-dot/#__tabbed_2_1) page. For more details about Paseo's role as the official Polkadot TestNet, see the [forum announcement](https://forum.polkadot.network/t/testnets-paseo-officially-becomes-the-polkadot-testnet-temporary-passet-hub-chain-for-smart-contracts-testing/13209). ## Other Networks While Paseo serves as the default TestNet for most development workflows, the Polkadot ecosystem includes additional networks for specialized use cases. ### Kusama Network Kusama is Polkadot's "canary" network—an experimental, production-grade environment with real economic value. Unlike TestNets, Kusama operates as a live network with actual incentives and economic consequences. It moves faster than Polkadot and has lower barriers to entry, making it suitable for teams that want to deploy in a real economic environment before moving to Polkadot. Kusama is ideal for: - Teams that want to test with real economic incentives - Projects seeking a faster-moving governance and upgrade cycle - Experiments and innovations that may eventually move to Polkadot The native token for Kusama is KSM. For more information about KSM, visit the [Native Assets](https://wiki.polkadot.com/kusama/kusama-getting-started/) page. ### Westend Westend is a protocol-focused TestNet maintained by Parity Technologies, primarily used for testing low-level Polkadot protocol changes, runtime upgrades, and infrastructure updates before they reach Kusama or Polkadot. Unlike Paseo, Westend is intentionally unstable and receives cutting-edge protocol changes first, making it better suited to core protocol development and infrastructure testing than to parachain or dApp development. **Important**: Most external developers should **not** use Westend; instead, they should use Paseo TestNet. Westend's onboarding process is not clearly documented, and it is designed for infrastructure operators rather than general parachain teams. **Even if you plan to deploy to Kusama, you should test on Paseo TestNet, not Westend.** Westend is primarily relevant for: - Core Polkadot protocol developers testing runtime changes - Infrastructure operators and validators testing low-level integrations - Teams that specifically need to test against upcoming protocol changes before they reach production networks Unlike temporary test networks, Westend is permanent and is not reset to the genesis block, making it an ongoing environment for long-term protocol testing. The native token for Westend is WND. TestNet tokens are available from the [Polkadot faucet](https://faucet.polkadot.io/). More details about WND can be found on the [Native Assets](https://wiki.polkadot.com/learn/learn-dot/#__tabbed_2_2) page. ## Local Test Networks Local test networks are an essential part of the development cycle for blockchain developers using the Polkadot SDK. They allow for fast, iterative testing in controlled, private environments without connecting to public TestNets. Developers can quickly spin up local instances to experiment, debug, and validate their code before deploying to Paseo TestNet and ultimately to production. Two key tools for local network testing are Zombienet and Chopsticks. ### Zombienet [Zombienet](https://github.com/paritytech/zombienet) is a flexible testing framework for Polkadot SDK-based blockchains. It enables developers to create and manage ephemeral, short-lived networks. This feature makes Zombienet particularly useful for quick iterations, as it allows you to run multiple local networks concurrently, mimicking different runtime conditions. Whether you're developing a parachain or testing your custom blockchain logic, Zombienet gives you the tools to automate local testing. Key features of Zombienet include: - Creating dynamic, local networks with different configurations. - Running parachains and relay chains in a simulated environment. - Efficient testing of network components like cross-chain messaging and governance. Zombienet is ideal for developers looking to test quickly and thoroughly before moving to more resource-intensive public TestNets. ### Chopsticks [Chopsticks](https://github.com/AcalaNetwork/chopsticks) is a tool designed to create forks of Polkadot SDK-based blockchains, allowing developers to interact with network forks as part of their testing process. This capability makes Chopsticks a powerful option for testing upgrades, runtime changes, or cross-chain applications in a forked network environment. Key features of Chopsticks include: - Forking live Polkadot SDK-based blockchains for isolated testing. - Simulating cross-chain messages in a private, controlled setup. - Debugging network behavior by interacting with the fork in real-time. Chopsticks provides a controlled environment for developers to safely explore the effects of runtime changes. It ensures that network behavior is tested and verified before upgrades are deployed to live networks. --- Page Title: Node and Runtime - Resolved Markdown: https://docs.polkadot.com/reference/parachains/node-and-runtime.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/node-and-runtime/ - Summary: Learn how Polkadot SDK-based nodes function, how the client and runtime are separated, and how they communicate using SCALE-encoded data. - Word Count: 621; Token Estimate: 901 - Last Updated: 2026-01-14T11:42:16+00:00 - Version Hash: sha256:7713ea77c4631525511f4bcf4dbe10506b8b806acc92a2b72a4557f518460442 # Node and Runtime ## Introduction Every blockchain platform relies on a decentralized network of computers, called nodes, that communicate with each other about transactions and blocks. In this context, a node refers to the software running on the connected devices rather than the physical or virtual machines in the network. Polkadot SDK-based nodes consist of two main components, each with distinct responsibilities: the client (also called node) and the runtime. If the system were a monolithic protocol, any modification would require updating the entire system. Instead, Polkadot achieves true upgradeability by defining an immutable meta-protocol (the client) and a protocol (the runtime) that can be upgraded independently. This separation gives the [Polkadot relay chain](/reference/polkadot-hub/consensus-and-security/relay-chain/) and all connected [parachains](/reference/parachains/) an evolutionary advantage over other blockchain platforms. ## Architectural Principles The Polkadot SDK-based blockchain architecture is fundamentally built on two distinct yet interconnected components: - Client (Meta-protocol): - Handles the foundational infrastructure of the blockchain. - Manages runtime execution, networking, consensus, and other off-chain components. - Provides an immutable base layer that ensures network stability. - Upgradable only through hard forks. - Runtime (Protocol): - Defines the blockchain's state transition logic. - Determines the specific rules and behaviors of the blockchain. - Compiled to WebAssembly (Wasm) for platform-independent execution. - Capable of being upgraded without network-wide forking. ### Advantages of this Architecture - **Forkless upgrades**: Runtime can be updated without disrupting the entire network. - **Modularity**: Clear separation allows independent development of client and runtime. - **Flexibility**: Enables rapid iteration and evolution of blockchain logic. - **Performance**: WebAssembly compilation provides efficient, cross-platform execution. ## Node (Client) The node, also known as the client, is the core component responsible for executing the Wasm runtime and orchestrating various essential blockchain components. It ensures the correct execution of the state transition function and manages multiple critical subsystems, including: - **Wasm execution**: Runs the blockchain runtime, which defines the state transition rules. - **Database management**: Stores blockchain data. - **Networking**: Facilitates peer-to-peer communication, block propagation, and transaction gossiping. - **Transaction pool (Mempool)**: Manages pending transactions before they are included in a block. - **Consensus mechanism**: Ensures agreement on the blockchain state across nodes. - **RPC services**: Provides external interfaces for applications and users to interact with the node. ## Runtime The runtime is more than just a set of rules. It's the fundamental logic engine that defines a blockchain's entire behavior. In Polkadot SDK-based blockchains, the runtime represents a complete, self-contained description of the blockchain's state transition function. ### Characteristics The runtime is distinguished by three key characteristics: - **Business logic**: Defines the complete application-specific blockchain behavior. - **WebAssembly compilation**: Ensures platform-independent, secure execution. - **On-chain storage**: Stored within the blockchain's state, allowing dynamic updates. ### Key Functions The runtime performs several critical functions, such as: - Define state transition rules. - Implement blockchain-specific logic. - Manage account interactions. - Control transaction processing. - Define governance mechanisms. - Handle custom pallets and modules. ## Communication Between Node and Runtime The client and runtime communicate exclusively using [SCALE-encoded](/reference/parachains/data-encoding/) communication. This ensures efficient and compact data exchange between the two components. ### Runtime APIs The Runtime API consists of well-defined functions and constants a client assumes are implemented in the Runtime Wasm blob. These APIs enable the client to interact with the runtime to execute blockchain operations and retrieve information. The client invokes these APIs to: - Build, execute, and finalize blocks. - Access metadata. - Access consensus related information. - Handle transaction execution. ### Host Functions During execution, the runtime can access certain external client functionalities via host functions. The specific functions the client exposes allow the runtime to perform operations outside the WebAssembly domain. Host functions enable the runtime to: - Perform cryptographic operations. - Access the current blockchain state. - Handle storage modifications. - Allocate memory. --- Page Title: On-Chain Governance Overview - Resolved Markdown: https://docs.polkadot.com/reference/governance.md - Canonical (HTML): https://docs.polkadot.com/reference/governance/ - Summary: Discover Polkadot’s cutting-edge OpenGov system, enabling transparent, decentralized decision-making through direct democracy and flexible governance tracks. - Word Count: 984; Token Estimate: 1512 - Last Updated: 2026-01-14T11:42:16+00:00 - Version Hash: sha256:fd72debd641dda80a51f1cf76a0d8de8a267a51e33506a7906fa58753275d9d6 # On-Chain Governance ## Introduction Polkadot’s governance system exemplifies decentralized decision-making, empowering its community of stakeholders to shape the network’s future through active participation. The latest evolution, OpenGov, builds on Polkadot’s foundation by providing a more inclusive and efficient governance model. This guide will explain the principles and structure of OpenGov and walk you through its key components, such as Origins, Tracks, and Delegation. You will learn about improvements over earlier governance systems, including streamlined voting processes and enhanced stakeholder participation. With OpenGov, Polkadot achieves a flexible, scalable, and democratic governance framework that allows multiple proposals to proceed simultaneously, ensuring the network evolves in alignment with its community's needs. ## Governance Evolution Polkadot’s governance journey began with [Governance V1](https://wiki.polkadot.com/learn/learn-polkadot-opengov/#governance-summary), a system that proved effective in managing treasury funds and protocol upgrades. However, it faced limitations, such as: - Slow voting cycles, causing delays in decision-making. - Inflexibility in handling multiple referendums, restricting scalability. To address these challenges, Polkadot introduced OpenGov, a governance model designed for greater inclusivity, efficiency, and scalability. OpenGov replaces the centralized structures of Governance V1, such as the Council and Technical Committee, with a fully decentralized and dynamic framework. For a full comparison of the historic and current governance models, visit the [Gov1 vs. Polkadot OpenGov](https://wiki.polkadot.com/learn/learn-polkadot-opengov/#gov1-vs-polkadot-opengov) section of the Polkadot Wiki. ## OpenGov Key Features OpenGov transforms Polkadot’s governance into a decentralized, stakeholder-driven model, eliminating centralized decision-making bodies like the Council. Key enhancements include: - **Decentralization**: Shifts all decision-making power to the public, ensuring a more democratic process. - **Enhanced delegation**: Allows users to delegate their votes to trusted experts across specific governance tracks. - **Simultaneous referendums**: Multiple proposals can progress at once, enabling faster decision-making. - **Polkadot Technical Fellowship**: A broad, community-driven group replacing the centralized Technical Committee. This new system ensures Polkadot governance remains agile and inclusive, even as the ecosystem grows. ## Origins and Tracks In OpenGov, origins and tracks are central to managing proposals and votes. - **Origin**: Determines the authority level of a proposal (e.g., Treasury, Root) which decides the track of all referendums from that origin. - **Track**: Define the procedural flow of a proposal, such as voting duration, approval thresholds, and enactment timelines. Developers must be aware that referendums from different origins and tracks will take varying amounts of time to reach approval and enactment. The [Polkadot Technical Fellowship](https://wiki.polkadot.com/learn/learn-polkadot-technical-fellowship/) has the option to shorten this timeline by whitelisting a proposal and allowing it to be enacted through the [Whitelist Caller](https://wiki.polkadot.com/learn/learn-polkadot-opengov-origins/#whitelisted-caller) origin. Visit [Origins and Tracks Info](https://wiki.polkadot.com/learn/learn-polkadot-opengov/#origins-and-tracks) for details on current origins and tracks, associated terminology, and parameters. ## Referendums In OpenGov, anyone can submit a referendum, fostering an open and participatory system. The timeline for a referendum depends on the privilege level of the origin with more significant changes offering more time for community voting and participation before enactment. The timeline for an individual referendum includes four distinct periods: - **Lead-in**: A minimum amount of time to allow for community participation, available room in the origin, and payment of the decision deposit. Voting is open during this period. - **Decision**: Voting continues. - **Confirmation**: Referendum must meet [approval and support](https://wiki.polkadot.com/learn/learn-polkadot-opengov/#approval-and-support) criteria during entire period to avoid rejection. - **Enactment**: Changes approved by the referendum are executed. ### Vote on Referendums Voters can vote with their tokens on each referendum. Polkadot uses a voluntary token locking mechanism, called conviction voting, as a way for voters to increase their voting power. A token holder signals they have a stronger preference for approving a proposal based upon their willingness to lock up tokens. Longer voluntary token locks are seen as a signal of continual approval and translate to increased voting weight. See [Voting on a Referendum](https://wiki.polkadot.com/learn/learn-polkadot-opengov/#voting-on-a-referendum) for a deeper look at conviction voting and related token locks. ### Delegate Voting Power The OpenGov system also supports multi-role delegations, allowing token holders to assign their voting power on different tracks to entities with expertise in those areas. For example, if a token holder lacks the technical knowledge to evaluate proposals on the [Root track](https://wiki.polkadot.com/learn/learn-polkadot-opengov-origins/#root), they can delegate their voting power for that track to an expert they trust to vote in the best interest of the network. This ensures informed decision-making across tracks while maintaining flexibility for token holders. Visit [Multirole Delegation](https://wiki.polkadot.com/learn/learn-polkadot-opengov/#multirole-delegation) for more details on delegating voting power. ### Cancel a Referendum Polkadot OpenGov has two origins for rejecting ongoing referendums: - [**Referendum Canceller**](https://wiki.polkadot.com/learn/learn-polkadot-opengov-origins/#referendum-canceller): Cancels an active referendum when non-malicious errors occur and refunds the deposits to the originators. - [**Referendum Killer**](https://wiki.polkadot.com/learn/learn-polkadot-opengov-origins/#referendum-killer): Used for urgent, malicious cases this origin instantly terminates an active referendum and slashes deposits. See [Cancelling, Killing, and Blacklisting](https://wiki.polkadot.com/learn/learn-polkadot-opengov/#cancelling-killing--blacklisting) for additional information on rejecting referendums. ## Additional Resources - **[Democracy pallet](https://github.com/paritytech/polkadot-sdk/tree/polkadot-stable2603/substrate/frame/democracy/src)**: Handles administration of general stakeholder voting. - **[Gov2: Polkadot’s Next Generation of Decentralised Governance](https://medium.com/polkadot-network/gov2-polkadots-next-generation-of-decentralised-governance-4d9ef657d11b)**: Medium article by Gavin Wood. - **[Polkadot Direction](https://matrix.to/#/#Polkadot-Direction:parity.io)**: Matrix Element client. - **[Polkassembly](https://polkadot.polkassembly.io/)**: OpenGov dashboard and UI. - **[Polkadot.js Apps Governance](https://polkadot.js.org/apps/#/referenda)**: Overview of active referendums. --- Page Title: Overview of FRAME - Resolved Markdown: https://docs.polkadot.com/parachains/customize-runtime.md - Canonical (HTML): https://docs.polkadot.com/parachains/customize-runtime/ - Summary: Learn how Polkadot SDK’s FRAME framework simplifies blockchain development with modular pallets and support libraries for efficient runtime design. - Word Count: 1070; Token Estimate: 1745 - Last Updated: 2026-05-27T20:25:14+00:00 - Version Hash: sha256:4fdb3ca1ee8b7da2d73f02c7842e34b2a5164f87e7148c5867902e3fc61ad6d3 # Customize Your Runtime ## Introduction A blockchain runtime is more than just a fixed set of rules—it's a dynamic foundation that you can shape to match your specific needs. With Polkadot SDK's FRAME (Framework for Runtime Aggregation of Modularized Entities), customizing your runtime is straightforward and modular. Instead of building everything from scratch, you combine pre-built pallets with your own custom logic to create a runtime suited to your blockchain's purpose. This overview explains how runtime customization works, introduces the building blocks you'll use, and guides you through the key patterns for extending your runtime. ## Understanding Your Runtime The runtime is the core logic of your blockchain—it processes transactions, manages state, and enforces the rules that govern your network. When a transaction arrives at your blockchain, the [`frame_executive`](https://paritytech.github.io/polkadot-sdk/master/frame_executive/index.html) pallet receives it and routes it to the appropriate pallet for execution. Think of your runtime as a collection of specialized modules, each handling a different aspect of your blockchain. Need token balances? Use the Balances pallet. Want governance? Add the Governance pallets. Need something custom? Create your own pallet. By mixing and matching these modules, you build a runtime that's efficient, secure, and tailored to your use case. ## Runtime Architecture The following diagram shows how FRAME components work together to form your runtime: ![](/images/parachains/customize-runtime/index/frame-overview-01.webp) The main components are: - **`frame_executive`**: Routes all incoming transactions to the correct pallet for execution. - **Pallets**: Domain-specific modules that implement your blockchain's features and business logic. - **`frame_system`**: Provides core runtime primitives and storage. - **`frame_support`**: Utilities and macros that simplify pallet development. ## Building Blocks: Pallets [Pallets](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/pallet/index.html) are the fundamental units of runtime customization. Each pallet encapsulates specific functionality and can be independently developed, tested, and integrated. A pallet can implement virtually any blockchain feature you need: - Expose new transactions that users can submit. - Store data on-chain. - Enforce business rules and validation logic. - Emit events to notify users of state changes. - Handle errors gracefully. ### Pre-Built Pallets vs. Custom Pallets FRAME provides a comprehensive library of [pre-built pallets](https://github.com/paritytech/polkadot-sdk/tree/polkadot-stable2603/substrate/frame) for common blockchain features, including consensus, staking, balances, governance, and more. These pallets are battle-tested, optimized, and ready to use. However, you're not limited to pre-built functionality. When pre-built pallets don't meet your needs, you can create custom pallets with entirely custom logic. The real power of FRAME is the flexibility to use pre-built modules for standard features while building your own for unique requirements. ### Pallet Structure FRAME uses Rust macros extensively, allowing you to focus on your pallet's logic while the framework handles boilerplate and integration code. A typical pallet looks like this: ```rust pub use pallet::*; #[frame_support::pallet] pub mod pallet { use frame_support::pallet_prelude::*; use frame_system::pallet_prelude::*; #[pallet::pallet] #[pallet::generate_store(pub(super) trait Store)] pub struct Pallet(_); #[pallet::config] // snip #[pallet::event] // snip #[pallet::error] // snip #[pallet::storage] // snip #[pallet::call] // snip } ``` Every pallet can implement these core macros: - **`#[frame_support::pallet]`**: Marks your module as a FRAME pallet. - **`#[pallet::pallet]`**: Designates the struct that holds pallet metadata. - **`#[pallet::config]`**: Defines configuration and associated types. - **`#[pallet::event]`**: Defines events emitted by your pallet. - **`#[pallet::error]`**: Defines error types your pallet can return. - **`#[pallet::storage]`**: Defines on-chain storage items. - **`#[pallet::call]`**: Defines dispatchable functions (transactions). For a comprehensive reference, see the [`pallet_macros` documentation](https://paritytech.github.io/polkadot-sdk/master/frame_support/pallet_macros/index.html). ## How Runtime Customization Works Customizing your runtime typically follows these patterns: **Adding Pre-Built Pallets**: Select pallets from the FRAME library and integrate them into your runtime configuration. This is the fastest way to add functionality. **Creating Custom Pallets**: Write custom pallets for features that don't exist in the pre-built library. Custom pallets follow the same structure as pre-built ones and integrate seamlessly. **Combining Multiple Pallets**: Layer multiple pallets together to create complex behaviors. Pallets can call each other and share storage when needed. **Configuring Pallet Parameters**: Most pallets are configurable—you can adjust their behavior through configuration traits without modifying their code. The following diagram illustrates how pallets combine to form a complete runtime: ![](/images/parachains/customize-runtime/index/frame-overview-02.webp) ## Starting Templates The easiest way to begin customizing your runtime is with a starter template. These templates provide a pre-configured foundation so you can focus on customization rather than setup. - **[Polkadot SDK Parachain Template](https://github.com/paritytech/polkadot-sdk-parachain-template)**: The recommended choice for most developers, it includes pre-configured pallets for common features (balances, block production, governance), a complete runtime setup, and built-in parachain consensus support. This template offers the best balance of features and learning opportunities. - **[Polkadot SDK Minimal Template](https://github.com/paritytech/polkadot-sdk-minimal-template)**: Provides a bare-bones runtime with only essential components. Choose this if you want maximum flexibility and prefer building from a clean slate. - **[Polkadot SDK Solochain Template](https://github.com/paritytech/polkadot-sdk/tree/master/templates/solochain)**: Designed for building standalone blockchains with moderate features, simple consensus, and several core pallets. Use this if you want a sovereign blockchain independent of a relay chain. - **[OpenZeppelin Runtime Templates](https://github.com/OpenZeppelin/polkadot-runtime-templates)**: Provides security-focused configurations following industry best practices. The [generic-template](https://github.com/OpenZeppelin/polkadot-runtime-templates/tree/main/generic-template) includes curated pallet selections and production-ready defaults—ideal if security is your top priority. ## Key Customization Scenarios This section covers the most common customization patterns you'll encounter: - **[Add Existing Pallets to Your Runtime](/parachains/customize-runtime/add-existing-pallets/)**: Integrate pre-built pallets from the FRAME library with minimal configuration. - **[Add Multiple Instances of a Pallet](/parachains/customize-runtime/add-pallet-instances/)**: Run multiple instances of the same pallet with different configurations—useful for multi-token systems or parallel features. - **[Add Smart Contract Functionality](/parachains/customize-runtime/add-smart-contract-functionality/)**: Enable smart contract execution on your parachain using Contracts pallets. - **[Create Custom Pallets](/parachains/customize-runtime/pallet-development/create-a-pallet/)**: Build entirely custom pallets for features unique to your blockchain. - **[Test Your Runtime](/parachains/customize-runtime/pallet-development/pallet-testing/)**: Unit test pallets and mock complete runtimes to ensure everything works correctly. --- Page Title: Overview of the Polkadot Relay Chain - Resolved Markdown: https://docs.polkadot.com/reference/polkadot-hub/consensus-and-security/relay-chain.md - Canonical (HTML): https://docs.polkadot.com/reference/polkadot-hub/consensus-and-security/relay-chain/ - Summary: Explore Polkadot's core architecture, including its multi-chain vision, shared security, and the DOT token's governance and staking roles. - Word Count: 1705; Token Estimate: 2391 - Last Updated: 2026-05-27T20:25:14+00:00 - Version Hash: sha256:0859be89440366a78bd1d2c522b62b9294a357f3803dc4bab10f55eae2abf498 # Overview ## Introduction Polkadot is a next-generation blockchain protocol designed to support a multi-chain future by enabling secure communication and interoperability between different blockchains. Built as a Layer-0 protocol, Polkadot introduces innovations like application-specific Layer-1 chains ([parachains](/reference/parachains/)), shared security through Nominated Proof of Stake (NPoS), and cross-chain interactions via its native [Cross-Consensus Messaging Format (XCM)](/parachains/interoperability/get-started/). This guide covers key aspects of Polkadot’s architecture, including its high-level protocol structure, blockspace commoditization, and the role of its native token, DOT, in governance, staking, and resource allocation. ## Polkadot 1.0 Polkadot 1.0 represents the state of Polkadot as of 2023, coinciding with the release of [Polkadot runtime v1.0.0](https://github.com/paritytech/polkadot/releases/tag/v1.0.0). This section will focus on Polkadot 1.0, along with philosophical insights into network resilience and blockspace. As a Layer-0 blockchain, Polkadot contributes to the multi-chain vision through several key innovations and initiatives, including: - **Application-specific Layer-1 blockchains (parachains)**: Polkadot's sharded network allows for parallel transaction processing, with shards that can have unique state transition functions, enabling custom-built L1 chains optimized for specific applications. - **Shared security and scalability**: L1 chains connected to Polkadot benefit from its [Nominated Proof of Stake (NPoS)](/reference/polkadot-hub/consensus-and-security/pos-consensus/#nominated-proof-of-stake) system, providing security out-of-the-box without the need to bootstrap their own. - **Secure interoperability**: Polkadot's native interoperability enables seamless data and value exchange between parachains. This interoperability can also be used outside of the ecosystem for bridging with external networks. - **Resilient infrastructure**: Decentralized and scalable, Polkadot ensures ongoing support for development and community initiatives via its on-chain [treasury](https://wiki.polkadot.com/learn/learn-polkadot-opengov-treasury/) and governance. - **Rapid L1 development**: The [Polkadot SDK](/reference/parachains/) allows fast, flexible creation and deployment of Layer-1 chains. - **Cultivating the next generation of Web3 developers**: Polkadot supports the growth of Web3 core developers through initiatives such as. - [Polkadot Blockchain Academy](https://polkadot.academy/) - [EdX courses](https://www.edx.org/school/web3x) - Rust and Substrate courses (coming soon) ### High-Level Architecture Polkadot features a chain that serves as the central component of the system. This chain is depicted as a ring encircled by several parachains that are connected to it. According to Polkadot's design, any blockchain that can compile to WebAssembly (Wasm) and adheres to the Parachains Protocol becomes a parachain on the Polkadot network. Here’s a high-level overview of the Polkadot protocol architecture: ![](/images/reference/polkadot-hub/consensus-and-security/relay-chain/relay-chain-01.webp) Parachains propose blocks to Polkadot validators, who check for availability and validity before finalizing them. With the relay chain providing security, collators—full nodes of parachains—can focus on their tasks without needing strong incentives. The [Cross-Consensus Messaging Format (XCM)](/parachains/interoperability/get-started/) allows parachains to exchange messages freely, leveraging the chain's security for trust-free communication. In order to interact with chains that want to use their own finalization process (e.g., Bitcoin), Polkadot has [bridges](/reference/parachains/interoperability/#bridges-connecting-external-networks) that offer two-way compatibility, meaning that transactions can be made between different parachains. ### Polkadot's Additional Functionalities Historically, obtaining core slots on Polkadot chain relied upon crowdloans and auctions. Chain cores were leased through auctions for three-month periods, up to a maximum of two years. Crowdloans enabled users to securely lend funds to teams for lease deposits in exchange for pre-sale tokens, which is the only way to access slots on Polkadot 1.0. Auctions are now deprecated in favor of [coretime](/reference/polkadot-hub/consensus-and-security/agile-coretime/). Additionally, the chain handles [staking](https://wiki.polkadot.com/learn/learn-staking/), [accounts](/reference/parachains/accounts/), balances, and [governance](/reference/governance/). #### Agile Coretime The new and more efficient way of obtaining core on Polkadot is to go through the process of purchasing coretime. [Agile coretime](/reference/polkadot-hub/consensus-and-security/agile-coretime/) improves the efficient use of Polkadot's network resources and offers economic flexibility for developers, extending Polkadot's capabilities far beyond the original vision outlined in the [whitepaper](https://assets.polkadot.network/Polkadot-whitepaper.pdf).. It enables parachains to purchase monthly "bulk" allocations of coretime (the time allocated for utilizing a core, measured in Polkadot relay chain blocks), ensuring heavy-duty parachains that can author a block every six seconds with [Asynchronous Backing](https://wiki.polkadot.com/learn/learn-async-backing/#asynchronous-backing) can reliably renew their coretime each month. Although six-second block times are now the default, parachains have the option of producing blocks less frequently. Renewal orders are prioritized over new orders, offering stability against price fluctuations and helping parachains budget more effectively for project costs. ### Polkadot's Resilience Decentralization is a vital component of blockchain networks, but it comes with trade-offs: - An overly decentralized network may face challenges in reaching consensus and require significant energy to operate. - Also, a network that achieves consensus quickly risks centralization, making it easier to manipulate or attack. A network should be decentralized enough to prevent manipulative or malicious influence. In this sense, decentralization is a tool for achieving resilience. Polkadot 1.0 currently achieves resilience through several strategies: - **Nominated Proof of Stake (NPoS)**: Ensures that the stake per validator is maximized and evenly distributed among validators. - **Decentralized nodes**: Designed to encourage operators to join the network. This program aims to expand and diversify the validators in the ecosystem who aim to become independent of the program during their term. Feel free to explore more about the program on the official [Decentralized Nodes](https://nodes.web3.foundation/) page. - **On-chain treasury and governance**: Known as [OpenGov](/reference/governance/), this system allows every decision to be made through public referenda, enabling any token holder to cast a vote. ### Polkadot's Blockspace Polkadot 1.0’s design allows for the commoditization of blockspace. Blockspace is a blockchain's capacity to finalize and commit operations, encompassing its security, computing, and storage capabilities. Its characteristics can vary across different blockchains, affecting security, flexibility, and availability. - **Security**: Measures the robustness of blockspace in Proof of Stake (PoS) networks linked to the stake locked on validator nodes, the variance in stake among validators, and the total number of validators. It also considers social centralization (how many validators are owned by single operators) and physical centralization (how many validators run on the same service provider). - **Flexibility**: Reflects the functionalities and types of data that can be stored, with high-quality data essential to avoid bottlenecks in critical processes. - **Availability**: Indicates how easily users can access blockspace. It should be easily accessible, allowing diverse business models to thrive, ideally regulated by a marketplace based on demand and supplemented by options for "second-hand" blockspace. Polkadot is built on core blockspace principles, but there's room for improvement. Tasks like balance transfers, staking, and governance are managed on the relay chain. Delegating these responsibilities to [system chains](/reference/polkadot-hub/#core-components) could enhance flexibility and allow the relay chain to concentrate on providing shared security and interoperability. For more information about blockspace, read [Robert Habermeier’s technical blog post](https://www.rob.tech/blog/polkadot-blockspace-over-blockchains/). ## DOT Token DOT is the native token of the Polkadot network, much like BTC for Bitcoin and Ether for the Ethereum blockchain. DOT has 10 decimals, uses the Planck base unit, and has a balance type of `u128`. The same is true for Kusama's KSM token with the exception of having 12 decimals. ### Redenomination of DOT Polkadot conducted a community poll, which ended on 27 July 2020 at block 888,888, to decide whether to redenominate the DOT token. The stakeholders chose to redenominate the token, changing the value of 1 DOT from 1e12 plancks to 1e10 plancks. Importantly, this did not affect the network's total number of base units (plancks); it only affects how a single DOT is represented. The redenomination became effective 72 hours after transfers were enabled, occurring at block 1,248,328 on 21 August 2020 around 16:50 UTC. ### The Planck Unit The smallest unit of account balance on Polkadot SDK-based blockchains (such as Polkadot and Kusama) is called _Planck_, named after the Planck length, the smallest measurable distance in the physical universe. Similar to how BTC's smallest unit is the Satoshi and ETH's is the Wei, Polkadot's native token DOT equals 1e10 Planck, while Kusama's native token KSM equals 1e12 Planck. ### Uses for DOT DOT serves three primary functions within the Polkadot network: - **Governance**: It is used to participate in the governance of the network. - **Staking**: DOT is staked to support the network's operation and security. - **Buying coretime**: Used to purchase coretime in-bulk or on-demand and access the chain to benefit from Polkadot's security and interoperability. Additionally, DOT can serve as a transferable token. For example, DOT, held in the treasury, can be allocated to teams developing projects that benefit the Polkadot ecosystem. ## JAM and the Road Ahead The Join-Accumulate Machine (JAM) represents a transformative redesign of Polkadot's core architecture, envisioned as the successor to the current relay chain. Unlike traditional blockchain architectures, JAM introduces a unique computational model that processes work through two primary functions: - **Join**: Handles data integration. - **Accumulate**: Folds computations into the chain's state. JAM removes many of the opinions and constraints of the current relay chain while maintaining its core security properties. Expected improvements include: - **Permissionless code execution**: JAM is designed to be more generic and flexible, allowing for permissionless code execution through services that can be deployed without governance approval. - **More effective block time utilization**: JAM's efficient pipeline processing model places the prior state root in block headers instead of the posterior state root, enabling more effective utilization of block time for computations. This architectural evolution promises to enhance Polkadot's scalability and flexibility while maintaining robust security guarantees. JAM is planned to be rolled out to Polkadot as a single, complete upgrade rather than a stream of smaller updates. This approach seeks to minimize the developer overhead required to address any breaking changes. --- Page Title: Parachains Overview - Resolved Markdown: https://docs.polkadot.com/reference/parachains.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/ - Summary: Learn about parachains, specialized blockchains on Polkadot that gain shared security and interoperability. Discover how they work and the tools to build them. - Word Count: 1012; Token Estimate: 1706 - Last Updated: 2026-05-27T20:25:14+00:00 - Version Hash: sha256:4420c2a6316058662ff876d3d56cc41bf901bac99661daff6c190e7e1a9e5c95 # Parachains Overview ## Introduction A Parachain is a specialized blockchain that connects to the Polkadot relay chain, benefiting from shared security, interoperability, and scalability. Parachains are built using the [Polkadot SDK](https://github.com/paritytech/polkadot-sdk), a powerful toolkit written in Rust that provides everything needed to create custom blockchain logic while integrating seamlessly with the Polkadot network. Unlike standalone blockchains that must bootstrap their own validator sets and security, parachains leverage Polkadot's pooled security model. This allows parachain developers to focus on their application-specific functionality rather than consensus and security infrastructure. Parachains can communicate with each other through Cross-Consensus Messaging (XCM), enabling seamless interoperability across the Polkadot ecosystem. Key capabilities that parachains provide include: - **Shared security**: Inherit security from Polkadot's validator set without maintaining your own. - **Interoperability**: Communicate trustlessly with other parachains via XCM. - **Scalability**: Process transactions in parallel with other parachains. - **Customization**: Build application-specific logic tailored to your use case. - **Upgradeability**: Upgrade runtime logic without hard forks. ## Polkadot SDK: Parachain Architecture Building a parachain involves understanding and utilizing several key components of the Polkadot SDK: ![](/images/reference/parachains/index/overview-01.webp) - **[Substrate](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/substrate/index.html)**: The foundation providing core blockchain primitives and libraries. - **[FRAME](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html)**: A modular framework for building your parachain's runtime logic. - **[Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html)**: Essential libraries and pallets that enable parachain functionality. - **[XCM (Cross Consensus Messaging)](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/xcm/index.html)**: The messaging format for communicating with other parachains and the relay chain. - **[Polkadot](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/polkadot/index.html)**: The relay chain that provides security and coordination. ### Substrate: The Foundation Substrate provides the core infrastructure that every parachain is built upon. It handles the low-level blockchain functionality, allowing you to focus on your application's unique features. Substrate includes implementations for networking, database management, consensus participation, and the execution environment for your runtime. Every Polkadot SDK node consists of two main components: - **Client (Host)**: Handles infrastructure services. - Native binary that runs on validator and collator nodes. - Executes the Wasm-compiled runtime. - Manages networking, database, mempool, and block production. - Interfaces with the relay chain for validation. - **Runtime (State Transition Function)**: Contains your business logic. - Defines how your Polkadot SDK node processes transactions. - Compiled to [Wasm](https://webassembly.org/) for deterministic execution. - Stored on-chain and upgradeable via governance. ```mermaid %%{init: {'flowchart': {'padding': 5, 'nodeSpacing': 50, 'rankSpacing': 10}}}%% graph TB classDef title font-size:20px,font-weight:bold,stroke-width:0px classDef clientStyle font-size:16px,font-weight:bold classDef clientSubNodeStyle margin-top:10px classDef runtimeCallExecutorStyle padding-top:10px subgraph sg1[Parachain
Node] direction TB I[RuntimeCall Executor] B[Wasm Runtime - STF] subgraph sg2[Client] direction TB C[Network and Blockchain
Infrastructure Services
+ Relay Chain Interface] end I --> B end class sg1 title class sg2 clientStyle class C clientSubNodeStyle class I runtimeCallExecutorStyle ``` ### FRAME: Building Blocks for Your Runtime FRAME provides a modular component called a Pallet that you can configure and combine to build your parachain's runtime. Each pallet provides specific functionality that you can customize for your needs. This modular approach allows you to quickly assemble complex functionality without writing everything from scratch. ```mermaid graph LR subgraph SP["Parachain Runtime"] direction LR Timestamp ~~~ Aura ~~~ ParachainSystem Balances ~~~ TransactionPayment ~~~ Sudo subgraph Timestamp["Timestamp"] SS1[Custom Config] end subgraph Aura["Aura"] SS2[Custom Config] end subgraph ParachainSystem["Parachain System"] SS3[Custom Config] end subgraph Balances["Balances"] SS4[Custom Config] end subgraph TransactionPayment["Transaction Payment"] SS5[Custom Config] end subgraph Sudo["Sudo"] SS6[Custom Config] end style Timestamp stroke:#FF69B4 style Aura stroke:#FF69B4 style ParachainSystem stroke:#FF69B4 style Balances stroke:#FF69B4 style TransactionPayment stroke:#FF69B4 style Sudo stroke:#FF69B4 style SS1 stroke-dasharray: 5 style SS2 stroke-dasharray: 5 style SS3 stroke-dasharray: 5 style SS4 stroke-dasharray: 5 style SS5 stroke-dasharray: 5 style SS6 stroke-dasharray: 5 end subgraph AP["Available FRAME Pallets"] direction LR A1[Aura]~~~A2[Parachain
System]~~~A3[Transaction
Payment]~~~A4[Sudo] B1[Identity]~~~B2[Balances]~~~B3[Assets]~~~B4[EVM] C1[Timestamp]~~~C2[Staking]~~~C3[Contracts]~~~C4[and more...] end AP --> SP ``` ### Cumulus: Parachain-Specific Functionality Cumulus is what transforms a Polkadot SDK-based runtime into a parachain-capable runtime. It provides the essential components for communicating with the relay chain, participating in Polkadot's consensus, and handling parachain-specific operations like block validation and collation. Key Cumulus components include: - **Parachain system pallet**: Core parachain functionality and relay chain communication. - **Collator consensus**: Block production logic for parachain collators. - **Relay chain interface**: APIs for interacting with the Polkadot relay chain. - **Validation data**: Handling proof-of-validity data required by relay chain validators. ## Where to Go Next Building a parachain requires understanding the relationship between your chain and the Polkadot relay chain. The Polkadot SDK provides all the tools needed to design custom runtime logic, enable cross-chain communication, and deploy your parachain to production. The following sections provide detailed guidance on each aspect of parachain development, from initial design through deployment and ongoing maintenance.
- Guide __Launch a Simple Parachain__ --- Walk through the complete parachain launch flow: from setup and deployment to obtaining coretime. [:octicons-arrow-right-24: Deploy](/parachains/launch-a-parachain/set-up-the-parachain-template/) - Guide __Customize Your Runtime__ --- Design your parachain's runtime logic and choose appropriate pallets for your use case. [:octicons-arrow-right-24: Get Started](/parachains/customize-runtime/) - Guide __Interoperability__ --- Implement XCM for trustless cross-chain communication with other parachains. [:octicons-arrow-right-24: Learn More](/parachains/interoperability/get-started/) - Guide __Runtime Upgrades__ --- Upgrade your parachain's runtime without hard forks using forkless upgrade mechanisms. [:octicons-arrow-right-24: Maintain](/parachains/runtime-maintenance/runtime-upgrades/)
--- Page Title: Polkadot Hub Overview - Resolved Markdown: https://docs.polkadot.com/reference/polkadot-hub.md - Canonical (HTML): https://docs.polkadot.com/reference/polkadot-hub/ - Summary: Learn how Polkadot Hub serves as the entry point to Polkadot, providing access to smart contracts, staking, governance, identity management, and cross-ecosystem interoperability. - Word Count: 808; Token Estimate: 1209 - Last Updated: 2026-04-01T02:33:47+00:00 - Version Hash: sha256:9446faf408431203779c64f746efb53c9652095a368ad9b3da2b161b1ff43513 ## Introduction Polkadot Hub is the entry point for all users and application developers to Polkadot. It provides access to essential Web3 services, including smart contracts, staking, governance, identity management, and cross-ecosystem interoperability—without requiring you to deploy or manage a parachain. The Hub encompasses a set of core functionality that enables developers and users to build and interact with applications on Polkadot. This specialized system of parachains and services works together seamlessly to deliver a unified platform experience. The modular approach lets you interact with services optimized for specific use cases, while still benefiting from Polkadot's shared security. ## Polkadot Hub Capabilities Whether you're just getting started or building complex applications, the Hub supports the ability to: - Hold, send, and receive DOT and other assets across the network. - Stake DOT to participate in network security and earn rewards. - Vote in governance referendums and shape Polkadot's future. - Create both fungible and non-fungible tokens and assets for your projects. - Pay transaction fees in any asset, not just DOT. - Register as an individual and establish your on-chain identity. For more sophisticated development use cases, the Hub enables you to: - Deploy Ethereum-compatible smart contracts using Solidity or other EVM languages. - Build decentralized applications that leverage Polkadot's security and interoperability. - Create and manage fungible tokens and NFTs with low fees and flexible operations. - Manage cross-chain interactions through XCM messaging with other parachains. - Set verified identities and apply for network opportunities like the Ambassador Program. - Join collectives and participate in governance organizations with specialized roles. ## Core Components The Polkadot Hub consists of several specialized system parachains and services working together as described in the following sections. ### Smart Contracts [Smart Contracts](/reference/polkadot-hub/smart-contracts/) on Polkadot Hub enable developers to deploy Ethereum-compatible smart contracts written in Solidity and other familiar EVM languages. Build decentralized applications with full access to Polkadot's security, interoperability, and cross-chain capabilities. Smart contracts on the Hub benefit from lower fees and integration with native Polkadot features, such as identity management and asset operations. ### Asset Management [Asset Management](/reference/polkadot-hub/assets/) provides the foundation for on-chain asset management. Create, manage, and transfer fungible tokens and NFTs across the ecosystem. Asset Management offers significantly lower transaction fees—approximately one-tenth the cost of relay chain transactions—and reduced deposit requirements, making it ideal for projects managing digital assets at scale. It also enables payment of transaction fees in non-native assets, providing developers and users with greater flexibility. ### People Chain [People Chain](/reference/polkadot-hub/people-and-identity/) powers Polkadot's decentralized identity system. Establish verifiable on-chain identities, control disclosure of personal information, and receive verification from trusted registrars. People Chain enables secure identity management with hierarchical sub-account support, forming the foundation for trusted interactions throughout the ecosystem. ### Bridge Hub [Bridge Hub](/reference/polkadot-hub/bridging/) facilitates trustless interactions between Polkadot and external blockchains like Ethereum and Kusama. Through implementations such as Snowbridge, Bridge Hub enables secure cross-chain communication via on-chain light clients and trustless relayers. This component ensures seamless interoperability beyond the Polkadot ecosystem. ### Consensus & Security [Consensus and Security](/reference/polkadot-hub/consensus-and-security/relay-chain/) covers the fundamental mechanisms that protect the network. Learn about validator participation, how the relay chain validates all transactions, and the cryptoeconomic incentives that secure Polkadot. Understanding these mechanisms is essential for validators and anyone building critical infrastructure on the network. ### Collectives & DAOs [Collectives and DAOs](/reference/polkadot-hub/collectives-and-daos/) enable specialized governance organizations within Polkadot. Participate in collective membership, manage treasury operations, and engage in coordinated decision-making with groups aligned around specific purposes. This functionality supports the creation of autonomous organizations on Polkadot. ## Where to Go Next Consider the following resources to explore specific Hub functionality.
- Learn **Smart Contracts** --- Deploy Ethereum-compatible smart contracts and build decentralized applications. [:octicons-arrow-right-24: Reference](/reference/polkadot-hub/smart-contracts/) - Learn **Asset Management** --- Manage fungible tokens and NFTs with low fees and flexible asset operations. [:octicons-arrow-right-24: Reference](/reference/polkadot-hub/assets/) - Learn **People Chain** --- Establish and verify decentralized identities for trusted interactions on Polkadot. [:octicons-arrow-right-24: Reference](/reference/polkadot-hub/people-and-identity/) - Learn **Bridge Hub** --- Facilitate trustless cross-chain interactions with Ethereum and other blockchains. [:octicons-arrow-right-24: Reference](/reference/polkadot-hub/bridging/) - Learn **Consensus & Security** --- Understand how Polkadot validates transactions and secures the network. [:octicons-arrow-right-24: Reference](/reference/polkadot-hub/consensus-and-security/relay-chain/) - Learn **Collectives & DAOs** --- Participate in specialized governance organizations with coordinated decision-making. [:octicons-arrow-right-24: Reference](/reference/polkadot-hub/collectives-and-daos/)
--- Page Title: Polkadot SDK Accounts - Resolved Markdown: https://docs.polkadot.com/reference/parachains/accounts.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/accounts/ - Summary: Learn about account structures, balances, and address formats in the Polkadot SDK, including how to manage lifecycle, references, and balances. - Word Count: 4124; Token Estimate: 6300 - Last Updated: 2026-01-14T11:42:16+00:00 - Version Hash: sha256:ec3a15386bdb148a52a3b478469563de94e7565cd64e36c9c039355d68d67517 # Accounts ## Introduction Accounts are essential for managing identity, transactions, and governance on the network in the Polkadot SDK. Understanding these components is critical for seamless development and operation on the network, whether you're building or interacting with Polkadot-based chains. This page will guide you through the essential aspects of accounts, including their data structure, balance types, reference counters, and address formats. You’ll learn how accounts are managed within the runtime, how balances are categorized, and how addresses are encoded and validated. ## Account Data Structure Accounts are foundational to any blockchain, and the Polkadot SDK provides a flexible management system. This section explains how the Polkadot SDK defines accounts and manages their lifecycle through data structures within the runtime. ### Account The [`Account` data type](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/type.Account.html) is a storage map within the [System pallet](https://paritytech.github.io/polkadot-sdk/master/src/frame_system/lib.rs.html) that links an account ID to its corresponding data. This structure is fundamental for mapping account-related information within the chain. The code snippet below shows how accounts are defined: ```rs /// The full account information for a particular account ID. #[pallet::storage] #[pallet::getter(fn account)] pub type Account = StorageMap< _, Blake2_128Concat, T::AccountId, AccountInfo, ValueQuery, >; ``` The preceding code block defines a storage map named `Account`. The `StorageMap` is a type of on-chain storage that maps keys to values. In the `Account` map, the key is an account ID, and the value is the account's information. Here, `T` represents the generic parameter for the runtime configuration, which is defined by the pallet's configuration trait (`Config`). The `StorageMap` consists of the following parameters: - **`_`**: Used in macro expansion and acts as a placeholder for the storage prefix type. Tells the macro to insert the default prefix during expansion. - **`Blake2_128Concat`**: The hashing function applied to keys in the storage map. - **`T: :AccountId`**: Represents the key type, which corresponds to the account’s unique ID. - **`AccountInfo`**: The value type stored in the map. For each account ID, the map stores an `AccountInfo` struct containing: - **`T::Nonce`**: A nonce for the account, which is incremented with each transaction to ensure transaction uniqueness. - **`T: :AccountData`**: Custom account data defined by the runtime configuration, which could include balances, locked funds, or other relevant information. - **`ValueQuery`**: Defines how queries to the storage map behave when no value is found; returns a default value instead of `None`. For a detailed explanation of storage maps, see the [`StorageMap`](https://paritytech.github.io/polkadot-sdk/master/frame_support/storage/types/struct.StorageMap.html) entry in the Rust docs. ### Account Info The `AccountInfo` structure is another key element within the [System pallet](https://paritytech.github.io/polkadot-sdk/master/src/frame_system/lib.rs.html), providing more granular details about each account's state. This structure tracks vital data, such as the number of transactions and the account’s relationships with other modules. ```rs /// Information of an account. #[derive(Clone, Eq, PartialEq, Default, RuntimeDebug, Encode, Decode, TypeInfo, MaxEncodedLen)] pub struct AccountInfo { /// The number of transactions this account has sent. pub nonce: Nonce, /// The number of other modules that currently depend on this account's existence. The account /// cannot be reaped until this is zero. pub consumers: RefCount, /// The number of other modules that allow this account to exist. The account may not be reaped /// until this and `sufficients` are both zero. pub providers: RefCount, /// The number of modules that allow this account to exist for their own purposes only. The /// account may not be reaped until this and `providers` are both zero. pub sufficients: RefCount, /// The additional data that belongs to this account. Used to store the balance(s) in a lot of /// chains. pub data: AccountData, } ``` The `AccountInfo` structure includes the following components: - **`nonce`**: Tracks the number of transactions initiated by the account, which ensures transaction uniqueness and prevents replay attacks. - **`consumers`**: Counts how many other modules or pallets rely on this account’s existence. The account cannot be removed from the chain (reaped) until this count reaches zero. - **`providers`**: Tracks how many modules permit this account’s existence. An account can only be reaped once both `providers` and `sufficients` are zero. - **`sufficients`**: Represents the number of modules that allow the account to exist for internal purposes, independent of any other modules. - **`AccountData`**: A flexible data structure that can be customized in the runtime configuration, usually containing balances or other user-specific data. This structure helps manage an account's state and prevents its premature removal while it is still referenced by other on-chain data or modules. The [`AccountInfo`](https://paritytech.github.io/polkadot-sdk/master/frame_system/struct.AccountInfo.html) structure can vary as long as it satisfies the trait bounds defined by the `AccountData` associated type in the [`frame-system::pallet::Config`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/trait.Config.html) trait. ### Account Reference Counters Polkadot SDK uses reference counters to track an account’s dependencies across different runtime modules. These counters ensure that accounts remain active while data is associated with them. The reference counters include: - **`consumers`**: Prevents account removal while other pallets still rely on the account. - **`providers`**: Ensures an account is active before other pallets store data related to it. - **`sufficients`**: Indicates the account’s independence, ensuring it can exist even without a native token balance, such as when holding sufficient alternative assets. #### Providers Reference Counters The `providers` counter ensures that an account is ready to be depended upon by other runtime modules. For example, it is incremented when an account has a balance above the existential deposit, which marks the account as active. The system requires this reference counter to be greater than zero for the `consumers` counter to be incremented, ensuring the account is stable before any dependencies are added. #### Consumers Reference Counters The `consumers` counter ensures that the account cannot be reaped until all references to it across the runtime have been removed. This check prevents the accidental deletion of accounts that still have active on-chain data. It is the user’s responsibility to clear out any data from other runtime modules if they wish to remove their account and reclaim their existential deposit. #### Sufficients Reference Counter The `sufficients` counter tracks accounts that can exist independently without relying on a native account balance. This is useful for accounts holding other types of assets, like tokens, without needing a minimum balance in the native token. For instance, the [Assets pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html), may increment this counter for an account holding sufficient tokens. #### Account Deactivation In Polkadot SDK-based chains, an account is deactivated when its reference counters (such as `providers`, `consumers`, and `sufficient`) reach zero. These counters ensure the account remains active as long as other runtime modules or pallets reference it. When all dependencies are cleared and the counters drop to zero, the account becomes deactivated and may be removed from the chain (reaped). This is particularly important in Polkadot SDK-based blockchains, where accounts with balances below the existential deposit threshold are pruned from storage to conserve state resources. Each pallet that references an account has cleanup functions that decrement these counters when the pallet no longer depends on the account. Once these counters reach zero, the account is marked for deactivation. #### Updating Counters The Polkadot SDK provides runtime developers with various methods to manage account lifecycle events, such as deactivation or incrementing reference counters. These methods ensure that accounts cannot be reaped while still in use. The following helper functions manage these counters: - **`inc_consumers()`**: Increments the `consumer` reference counter for an account, signaling that another pallet depends on it. - **`dec_consumers()`**: Decrements the `consumer` reference counter, signaling that a pallet no longer relies on the account. - **`inc_providers()`**: Increments the `provider` reference counter, ensuring the account remains active. - **`dec_providers()`**: Decrements the `provider` reference counter, allowing for account deactivation when no longer in use. - **`inc_sufficients()`**: Increments the `sufficient` reference counter for accounts that hold sufficient assets. - **`dec_sufficients()`**: Decrements the `sufficient` reference counter. To ensure proper account cleanup and lifecycle management, a corresponding decrement should be made for each increment action. The `System` pallet offers three query functions to assist developers in tracking account states: - **[`can_inc_consumer()`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.can_inc_consumer)**: Checks if the account can safely increment the consumer reference. - **[`can_dec_provider()`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.can_dec_provider)**: Ensures that no consumers exist before allowing the decrement of the provider counter. - **[`is_provider_required()`](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html#method.is_provider_required)**: Verifies whether the account still has any active consumer references. This modular and flexible system of reference counters tightly controls the lifecycle of accounts in Polkadot SDK-based blockchains, preventing the accidental removal or retention of unneeded accounts. You can refer to the [System pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/frame_system/pallet/struct.Pallet.html) for more details. ## Account Balance Types In the Polkadot ecosystem, account balances are categorized into different types based on how the funds are utilized and their availability. These balance types determine the actions that can be performed, such as transferring tokens, paying transaction fees, or participating in governance activities. Understanding these balance types helps developers manage user accounts and implement balance-dependent logic. !!! note "A more efficient distribution of account balance types is in development" Soon, pallets in the Polkadot SDK will implement the [`Fungible` trait](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/tokens/fungible/index.html) (see the [tracking issue](https://github.com/paritytech/polkadot-sdk/issues/226) for more details). For example, the [`transaction-storage`](https://paritytech.github.io/polkadot-sdk/master/pallet_transaction_storage/index.html) pallet changed the implementation of the [`Currency`](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/tokens/currency/index.html) trait (see the [Refactor transaction storage pallet to use fungible traits](https://github.com/paritytech/polkadot-sdk/pull/1800) PR for further details): ```rust type BalanceOf = <::Currency as Currency<::AccountId>>::Balance; ``` To the [`Fungible`](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/tokens/fungible/index.html) trait: ```rust type BalanceOf = <::Currency as FnInspect<::AccountId>>::Balance; ``` This update will enable more efficient use of account balances, allowing the free balance to be utilized for on-chain activities such as setting proxies and managing identities. ### Balance Types The five main balance types are: - **Free balance**: Represents the total tokens available to the account for any on-chain activity, including staking, governance, and voting. However, it may not be fully spendable or transferrable if portions of it are locked or reserved. - **Locked balance**: Portions of the free balance that cannot be spent or transferred because they are tied up in specific activities like [staking](https://wiki.polkadot.com/learn/learn-staking/#nominating-validators), [vesting](https://wiki.polkadot.com/learn/learn-guides-transfers/#vested-transfers-with-the-polkadot-js-ui), or participating in [governance](https://wiki.polkadot.com/learn/learn-polkadot-opengov/#voting-on-a-referendum). While the tokens remain part of the free balance, they are non-transferable for the duration of the lock. - **Reserved balance**: Funds locked by specific system actions, such as setting up an [identity](https://wiki.polkadot.com/learn/learn-identity/), creating [proxies](https://wiki.polkadot.com/learn/learn-proxies/), or submitting [deposits for governance proposals](https://wiki.polkadot.com/learn/learn-guides-polkadot-opengov/#claiming-opengov-deposits). These tokens are not part of the free balance and cannot be spent unless they are unreserved. - **Spendable balance**: The portion of the free balance that is available for immediate spending or transfers. It is calculated by subtracting the maximum of locked or reserved amounts from the free balance, ensuring that existential deposit limits are met. - **Untouchable balance**: Funds that cannot be directly spent or transferred but may still be utilized for on-chain activities, such as governance participation or staking. These tokens are typically tied to certain actions or locked for a specific period. The spendable balance is calculated as follows: ```text spendable = free - max(locked - reserved, ED) ``` Here, `free`, `locked`, and `reserved` are defined above. The `ED` represents the [existential deposit](https://wiki.polkadot.com/learn/learn-accounts/#existential-deposit-and-reaping), the minimum balance required to keep an account active and prevent it from being reaped. You may find you can't see all balance types when looking at your account via a wallet. Wallet providers often display only spendable, locked, and reserved balances. ### Locks Locks are applied to an account's free balance, preventing that portion from being spent or transferred. Locks are automatically placed when an account participates in specific on-chain activities, such as staking or governance. Although multiple locks may be applied simultaneously, they do not stack. Instead, the largest lock determines the total amount of locked tokens. Locks follow these basic rules: - If different locks apply to varying amounts, the largest lock amount takes precedence. - If multiple locks apply to the same amount, the lock with the longest duration governs when the balance can be unlocked. #### Locks Example Consider an example where an account has 80 DOT locked for both staking and governance purposes like so: - 80 DOT is staked with a 28-day lock period. - 24 DOT is locked for governance with a 1x conviction and a 7-day lock period. - 4 DOT is locked for governance with a 6x conviction and a 224-day lock period. In this case, the total locked amount is 80 DOT because only the largest lock (80 DOT from staking) governs the locked balance. These 80 DOT will be released at different times based on the lock durations. In this example, the 24 DOT locked for governance will be released first since the shortest lock period is seven days. The 80 DOT stake with a 28-day lock period is released next. Now, all that remains locked is the 4 DOT for governance. After 224 days, all 80 DOT (minus the existential deposit) will be free and transferable. ![Illustration of Lock Example](/images/reference/parachains/accounts/accounts-01.webp) #### Edge Cases for Locks In scenarios where multiple convictions and lock periods are active, the lock duration and amount are determined by the longest period and largest amount. For example, if you delegate with different convictions and attempt to undelegate during an active lock period, the lock may be extended for the full amount of tokens. For a detailed discussion on edge case lock behavior, see this [Stack Exchange post](https://substrate.stackexchange.com/questions/5067/delegating-and-undelegating-during-the-lock-period-extends-it-for-the-initial-am). ### Balance Types on Polkadot.js Polkadot.js provides a user-friendly interface for managing and visualizing various account balances on Polkadot and Kusama networks. When interacting with Polkadot.js, you will encounter multiple balance types that are critical for understanding how your funds are distributed and restricted. This section explains how different balances are displayed in the Polkadot.js UI and what each type represents. ![](/images/reference/parachains/accounts/accounts-02.webp) The most common balance types displayed on Polkadot.js are: - **Total balance**: The total number of tokens available in the account. This includes all tokens, whether they are transferable, locked, reserved, or vested. However, the total balance does not always reflect what can be spent immediately. In this example, the total balance is 0.6274 KSM. - **Transferable balance**: Shows how many tokens are immediately available for transfer. It is calculated by subtracting the locked and reserved balances from the total balance. For example, if an account has a total balance of 0.6274 KSM and a transferable balance of 0.0106 KSM, only the latter amount can be sent or spent freely. - **Vested balance**: Tokens that allocated to the account but released according to a specific schedule. Vested tokens remain locked and cannot be transferred until fully vested. For example, an account with a vested balance of 0.2500 KSM means that this amount is owned but not yet transferable. - **Locked balance**: Tokens that are temporarily restricted from being transferred or spent. These locks typically result from participating in staking, governance, or vested transfers. In Polkadot.js, locked balances do not stack—only the largest lock is applied. For instance, if an account has 0.5500 KSM locked for governance and staking, the locked balance would display 0.5500 KSM, not the sum of all locked amounts. - **Reserved balance**: Refers to tokens locked for specific on-chain actions, such as setting an identity, creating a proxy, or making governance deposits. Reserved tokens are not part of the free balance, but can be freed by performing certain actions. For example, removing an identity would unreserve those funds. - **Bonded balance**: The tokens locked for staking purposes. Bonded tokens are not transferable until they are unbonded after the unbonding period. - **Redeemable balance**: The number of tokens that have completed the unbonding period and are ready to be unlocked and transferred again. For example, if an account has a redeemable balance of 0.1000 KSM, those tokens are now available for spending. - **Democracy balance**: Reflects the number of tokens locked for governance activities, such as voting on referenda. These tokens are locked for the duration of the governance action and are only released after the lock period ends. By understanding these balance types and their implications, developers and users can better manage their funds and engage with on-chain activities more effectively. ## Address Formats The SS58 address format is a core component of the Polkadot SDK that enables accounts to be uniquely identified across Polkadot-based networks. This format is a modified version of Bitcoin's Base58Check encoding, specifically designed to accommodate the multi-chain nature of the Polkadot ecosystem. SS58 encoding allows each chain to define its own set of addresses while maintaining compatibility and checksum validation for security. ### Basic Format SS58 addresses consist of three main components: ```text base58encode(concat(,
, )) ``` - **Address type**: A byte or set of bytes that define the network (or chain) for which the address is intended. This ensures that addresses are unique across different Polkadot SDK-based chains. - **Address**: The public key of the account encoded as bytes. - **Checksum**: A hash-based checksum which ensures that addresses are valid and unaltered. The checksum is derived from the concatenated address type and address components, ensuring integrity. The encoding process transforms the concatenated components into a Base58 string, providing a compact and human-readable format that avoids easily confused characters (e.g., zero '0', capital 'O', lowercase 'l'). This encoding function ([`encode`](https://docs.rs/bs58/latest/bs58/fn.encode.html)) is implemented exactly as defined in Bitcoin and IPFS specifications, using the same alphabet as both implementations. For more details about the SS58 address format implementation, see the [`Ss58Codec`](https://paritytech.github.io/polkadot-sdk/master/sp_core/crypto/trait.Ss58Codec.html) trait in the Rust Docs. ### Address Type The address type defines how an address is interpreted and to which network it belongs. Polkadot SDK uses different prefixes to distinguish between various chains and address formats: - **Address types `0-63`**: Simple addresses, commonly used for network identifiers. - **Address types `64-127`**: Full addresses that support a wider range of network identifiers. - **Address types `128-255`**: Reserved for future address format extensions. For example, Polkadot’s main network uses an address type of 0, while Kusama uses 2. This ensures that addresses can be used without confusion between networks. The address type is always encoded as part of the SS58 address, making it easy to quickly identify the network. Refer to the [SS58 registry](https://github.com/paritytech/ss58-registry) for the canonical listing of all address type identifiers and how they map to Polkadot SDK-based networks. ### Address Length SS58 addresses can have different lengths depending on the specific format. Address lengths range from as short as 3 to 35 bytes, depending on the complexity of the address and network requirements. This flexibility allows SS58 addresses to adapt to different chains while providing a secure encoding mechanism. | Total | Type | Raw account | Checksum | |-------|------|-------------|----------| | 3 | 1 | 1 | 1 | | 4 | 1 | 2 | 1 | | 5 | 1 | 2 | 2 | | 6 | 1 | 4 | 1 | | 7 | 1 | 4 | 2 | | 8 | 1 | 4 | 3 | | 9 | 1 | 4 | 4 | | 10 | 1 | 8 | 1 | | 11 | 1 | 8 | 2 | | 12 | 1 | 8 | 3 | | 13 | 1 | 8 | 4 | | 14 | 1 | 8 | 5 | | 15 | 1 | 8 | 6 | | 16 | 1 | 8 | 7 | | 17 | 1 | 8 | 8 | | 35 | 1 | 32 | 2 | SS58 addresses also support different payload sizes, allowing a flexible range of account identifiers. ### Checksum Types A checksum is applied to validate SS58 addresses. Polkadot SDK uses a Blake2b-512 hash function to calculate the checksum, which is appended to the address before encoding. The checksum length can vary depending on the address format (e.g., 1-byte, 2-byte, or longer), providing varying levels of validation strength. The checksum ensures that an address is not modified or corrupted, adding an extra layer of security for account management. ### Validating Addresses SS58 addresses can be validated using the subkey command-line interface or the Polkadot.js API. These tools help ensure an address is correctly formatted and valid for the intended network. The following sections will provide an overview of how validation works with these tools. #### Using Subkey [Subkey](https://paritytech.github.io/polkadot-sdk/master/subkey/index.html) is a CLI tool provided by Polkadot SDK for generating and managing keys. It can inspect and validate SS58 addresses. The `inspect` command gets a public key and an SS58 address from the provided secret URI. The basic syntax for the `subkey inspect` command is: ```bash subkey inspect [flags] [options] uri ``` For the `uri` command-line argument, you can specify the secret seed phrase, a hex-encoded private key, or an SS58 address. If the input is a valid address, the `subkey` program displays the corresponding hex-encoded public key, account identifier, and SS58 addresses. For example, to inspect the public keys derived from a secret seed phrase, you can run a command similar to the following: ```bash subkey inspect "caution juice atom organ advance problem want pledge someone senior holiday very" ``` The command displays output similar to the following:
subkey inspect "caution juice atom organ advance problem want pledge someone senior holiday very" Secret phrase `caution juice atom organ advance problem want pledge someone senior holiday very` is account: Secret seed: 0xc8fa03532fb22ee1f7f6908b9c02b4e72483f0dbd66e4cd456b8f34c6230b849 Public key (hex): 0xd6a3105d6768e956e9e5d41050ac29843f98561410d3a47f9dd5b3b227ab8746 Public key (SS58): 5Gv8YYFu8H1btvmrJy9FjjAWfb99wrhV3uhPFoNEr918utyR Account ID: 0xd6a3105d6768e956e9e5d41050ac29843f98561410d3a47f9dd5b3b227ab8746 SS58 Address: 5Gv8YYFu8H1btvmrJy9FjjAWfb99wrhV3uhPFoNEr918utyR
The `subkey` program assumes an address is based on a public/private key pair. If you inspect an address, the command returns the 32-byte account identifier. However, not all addresses in Polkadot SDK-based networks are based on keys. Depending on the command-line options you specify and the input you provided, the command output might also display the network for which the address has been encoded. For example: ```bash subkey inspect "12bzRJfh7arnnfPPUZHeJUaE62QLEwhK48QnH9LXeK2m1iZU" ``` The command displays output similar to the following:
subkey inspect "12bzRJfh7arnnfPPUZHeJUaE62QLEwhK48QnH9LXeK2m1iZU" Public Key URI `12bzRJfh7arnnfPPUZHeJUaE62QLEwhK48QnH9LXeK2m1iZU` is account: Network ID/Version: polkadot Public key (hex): 0x46ebddef8cd9bb167dc30878d7113b7e168e6f0646beffd77d69d39bad76b47a Account ID: 0x46ebddef8cd9bb167dc30878d7113b7e168e6f0646beffd77d69d39bad76b47a Public key (SS58): 12bzRJfh7arnnfPPUZHeJUaE62QLEwhK48QnH9LXeK2m1iZU SS58 Address: 12bzRJfh7arnnfPPUZHeJUaE62QLEwhK48QnH9LXeK2m1iZU
#### Using Polkadot.js API To verify an address in JavaScript or TypeScript projects, you can use the functions built into the [Polkadot.js API](https://polkadot.js.org/docs/). For example: ```js // Import Polkadot.js API dependencies const { decodeAddress, encodeAddress } = require('@polkadot/keyring'); const { hexToU8a, isHex } = require('@polkadot/util'); // Specify an address to test. const address = 'INSERT_ADDRESS_TO_TEST'; // Check address const isValidSubstrateAddress = () => { try { encodeAddress(isHex(address) ? hexToU8a(address) : decodeAddress(address)); return true; } catch (error) }; // Query result const isValid = isValidSubstrateAddress(); console.log(isValid); ``` If the function returns `true`, the specified address is a valid address. #### Other SS58 Implementations Support for encoding and decoding Polkadot SDK SS58 addresses has been implemented in several other languages and libraries. - **Crystal**: [`wyhaines/base58.cr`](https://github.com/wyhaines/base58.cr) - **Go**: [`itering/subscan-plugin`](https://github.com/itering/subscan-plugin) - **Python**: [`polkascan/py-scale-codec`](https://github.com/polkascan/py-scale-codec) - **TypeScript**: [`subsquid/squid-sdk`](https://github.com/subsquid/squid-sdk) --- Page Title: Randomness - Resolved Markdown: https://docs.polkadot.com/reference/parachains/randomness.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/randomness/ - Summary: Explore the importance of randomness in PoS blockchains, focusing on Polkadot’s VRF-based approach to ensure fairness and security in validator selection. - Word Count: 986; Token Estimate: 1336 - Last Updated: 2026-04-23T12:21:22+00:00 - Version Hash: sha256:e7d5de8207c507e8305224bd244333575155d0391ee6e8ae0db9ea9628c45b0e # Randomness ## Introduction Randomness is crucial in Proof of Stake (PoS) blockchains to ensure a fair and unpredictable distribution of validator duties. However, computers are inherently deterministic, meaning the same input always produces the same output. What we typically refer to as "random" numbers on a computer are actually pseudo-random. These numbers rely on an initial "seed," which can come from external sources like [atmospheric noise](https://www.random.org/randomness/), [heart rates](https://mdpi.altmetric.com/details/47574324), or even [lava lamps](https://en.wikipedia.org/wiki/Lavarand). While this may seem random, given the same "seed," the same sequence of numbers will always be generated. In a global blockchain network, relying on real-world entropy for randomness isn’t feasible because these inputs vary by time and location. If nodes use different inputs, blockchains can fork. Hence, real-world randomness isn't suitable for use as a seed in blockchain systems. Currently, two primary methods for generating randomness in blockchains are used: [`RANDAO`](#randao) and [`VRF`](#vrf) (Verifiable Random Function). Polkadot adopts the `VRF` approach for its randomness. ## VRF A Verifiable Random Function (VRF) is a cryptographic function that generates a random number and proof that ensures the submitter produced the number. This proof allows anyone to verify the validity of the random number. Polkadot's VRF is similar to the one used in [**Ouroboros Praos**](https://eprint.iacr.org/2017/573.pdf), which secures randomness for block production in systems like [BABE](/reference/polkadot-hub/consensus-and-security/pos-consensus/#block-production-babe) (Polkadot’s block production mechanism). The key difference is that Polkadot's VRF doesn’t rely on a central clock—avoiding the issue of whose clock to trust. Instead, it uses its own past results and slot numbers to simulate time and determine future outcomes. ### How VRF Works Slots on Polkadot are discrete units of time, each lasting six seconds, and can potentially hold a block. Multiple slots form an epoch, with 2400 slots making up one four-hour epoch. In each slot, validators execute a "die roll" using a VRF. The VRF uses three inputs: 1. A "secret key," unique to each validator, is used for the die roll. 2. An epoch randomness value, derived from the hash of VRF outputs from blocks two epochs ago (N-2), so past randomness influences the current epoch (N). 3. The current slot number. This process helps maintain fair randomness across the network. Here is a graphical representation: ![](/images/reference/parachains/randomness/randomness-01.webp) The VRF produces two outputs: a result (the random number) and a proof (verifying that the number was generated correctly). The result is checked by the validator against a protocol threshold. If it's below the threshold, the validator becomes a candidate for block production in that slot. The validator then attempts to create a block, submitting it along with the `PROOF` and `RESULT`. So, VRF can be expressed like: `(RESULT, PROOF) = VRF(SECRET, EPOCH_RANDOMNESS_VALUE, CURRENT_SLOT_NUMBER)` Put simply, performing a "VRF roll" generates a random number along with proof that the number was genuinely produced and not arbitrarily chosen. After executing the VRF, the `RESULT` is compared to a protocol-defined `THRESHOLD`. If the `RESULT` is below the `THRESHOLD`, the validator becomes a valid candidate to propose a block for that slot. Otherwise, the validator skips the slot. As a result, there may be multiple validators eligible to propose a block for a slot. In this case, the block accepted by other nodes will prevail, provided it is on the chain with the latest finalized block as determined by the GRANDPA finality gadget. It's also possible for no block producers to be available for a slot, in which case the AURA consensus takes over. AURA is a fallback mechanism that randomly selects a validator to produce a block, running in parallel with BABE and only stepping in when no block producers exist for a slot. Otherwise, it remains inactive. Because validators roll independently, no block candidates may appear in some slots if all roll numbers are above the threshold. To verify resolution of this issue and that Polkadot block times remain near constant-time, see the [PoS Consensus](/reference/polkadot-hub/consensus-and-security/pos-consensus/) page of this documentation. ## RANDAO An alternative on-chain randomness method is Ethereum's RANDAO, where validators perform thousands of hashes on a seed and publish the final hash during a round. The collective input from all validators forms the random number, and as long as one honest validator participates, the randomness is secure. To enhance security, RANDAO can optionally be combined with a Verifiable Delay Function (VDF), ensuring that randomness can't be predicted or manipulated during computation. For more information about RANDAO, see the [Randomness - RANDAO](https://eth2book.info/capella/part2/building_blocks/randomness/) section of the Upgrading Ethereum documentation. ## VDFs Verifiable Delay Functions (VDFs) are time-bound computations that, even on parallel computers, take a set amount of time to complete. They produce a unique result that can be quickly verified publicly. When combined with RANDAO, feeding RANDAO's output into a VDF introduces a delay that nullifies an attacker's chance to influence the randomness. However, VDF likely requires specialized ASIC devices to run separately from standard nodes. !!!warning While only one is needed to secure the system, and they will be open-source and inexpensive, running VDF devices involves significant costs without direct incentives, adding friction for blockchain users. ## Additional Resources For more information about the reasoning for choices made along with proofs, see Polkadot's research on blockchain randomness and sortition in the [Randomness](https://wiki.polkadot.com/learn/learn-cryptography/#randomness) entry of the Polkadot Wiki. For a discussion with Web3 Foundation researchers about when and under what conditions Polkadot's randomness can be utilized, see the [Discussion on Randomness used in Polkadot](https://github.com/use-ink/ink/issues/57) issue on GitHub. --- Page Title: Register a Local Asset - Resolved Markdown: https://docs.polkadot.com/chain-interactions/token-operations/register-local-asset.md - Canonical (HTML): https://docs.polkadot.com/chain-interactions/token-operations/register-local-asset/ - Summary: Learn how to register a local asset on Polkadot Hub, including prerequisites, deposits, and step-by-step instructions using Polkadot.js Apps. - Word Count: 988; Token Estimate: 1476 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:5e9bf242e67b73f8d06dde94177b29257b9ab7f5ebf430c4b43598dd3a9e1030 # Register a Local Asset on Polkadot Hub ## Introduction As detailed in the [Assets on Polkadot Hub Overview](/reference/polkadot-hub/assets/) page, Polkadot Hub accommodates two types of assets: local and foreign. Local assets are those that were created in Polkadot Hub and are identifiable by an integer ID. On the other hand, foreign assets originate from a sibling parachain and are identified by a Multilocation. This guide will take you through the steps of registering a local asset on Polkadot Hub. ## Prerequisites Before you begin, ensure you have access to the [Polkadot.js Apps](https://polkadot.js.org/apps/) interface and a funded wallet with DOT or KSM. - For Polkadot Hub, you would need a deposit of 10 DOT and around 0.201 DOT for the metadata. - For Kusama Hub, the deposit is 0.1 KSM and around 0.000669 KSM for the metadata. You need to ensure that your Polkadot Hub account balance is a bit more than the sum of those two deposits, which should seamlessly account for the required deposits and transaction fees. ## Register a Local Asset To register a local asset on Polkadot Hub, follow these steps: 1. Open the [Polkadot.js Apps](https://polkadot.js.org/apps/) interface and connect to the Polkadot Asset Hub using the network selector in the top left corner. - You may prefer to test local asset registration on TestNet before registering the asset on a MainNet hub. If you still need to set up a local testing environment, review the [Environment setup](#test-setup-environment) section for instructions. Once the local environment is set up, connect to the Local Node (Chopsticks) available on `ws://127.0.0.1:8000`. - For the live network, connect to the **Asset Hub** parachain. Either Polkadot or Kusama Asset Hub can be selected from the dropdown list, choosing the desired RPC provider. 2. Click on the **Network** tab on the top navigation bar and select **Assets** from the dropdown list. ![Access to Polkadot Hub through Polkadot.JS](/images/chain-interactions/token-operations/register-local-asset/register-a-local-asset-01.webp) 3. Now, you need to examine all the registered asset IDs. This step is crucial to ensure that the asset ID you are about to register is unique. Asset IDs are displayed in the **assets** column. ![Asset IDs on Polkadot Hub](/images/chain-interactions/token-operations/register-local-asset/register-a-local-asset-02.webp) 4. Once you have confirmed that the asset ID is unique, click on the **Create** button on the top right corner of the page. ![Create a new asset](/images/chain-interactions/token-operations/register-local-asset/register-a-local-asset-03.webp) 5. Fill in the required fields in the **Create Asset** form: 1. **creator account**: The account to be used for creating this asset and setting up the initial metadata. 2. **asset name**: The descriptive name of the asset you are registering. 3. **asset symbol**: The symbol that will be used to represent the asset. 4. **asset decimals**: The number of decimal places for this token, with a maximum of 20 allowed through the user interface. 5. **minimum balance**: The minimum balance for the asset. This is specified in the units and decimals as requested. 6. **asset ID**: The selected id for the asset. This should not match an already-existing asset id. 7. Click on the **Next** button. ![Create Asset Form](/images/chain-interactions/token-operations/register-local-asset/register-a-local-asset-04.webp) 6. Choose the accounts for the roles listed below: 1. **admin account**: The account designated for continuous administration of the token. 2. **issuer account**: The account that will be used for issuing this token. 3. **freezer account**: The account that will be used for performing token freezing operations. 4. Click on the **Create** button. ![Admin, Issuer, Freezer accounts](/images/chain-interactions/token-operations/register-local-asset/register-a-local-asset-05.webp) 7. Click on the **Sign and Submit** button to complete the asset registration process. ![Sign and Submit](/images/chain-interactions/token-operations/register-local-asset/register-a-local-asset-06.webp) ## Verify Asset Registration After completing these steps, the asset will be successfully registered. You can now view your asset listed on the [**Assets**](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fasset-hub-polkadot-rpc.dwellir.com#/assets) section of the Polkadot.js Apps interface. ![Asset listed on Polkadot.js Apps](/images/chain-interactions/token-operations/register-local-asset/register-a-local-asset-07.webp) !!! tip Take into consideration that the **Assets** section’s link may differ depending on the network you are using. For the local environment, enter `ws://127.0.0.1:8000` into the **Custom Endpoint** field. In this way, you have successfully registered a local asset on the Polkadot Hub. For an in-depth explanation about Polkadot Hub and its features, see the [Polkadot Hub](/chain-interactions/token-operations/convert-assets/) entry in the Polkadot Wiki. ## Test Setup Environment You can set up a local parachain environment to test the asset registration process before deploying it on the live network. This guide uses Chopsticks to simulate that process. For further information on chopsticks usage, refer to the [Chopsticks](/parachains/testing/fork-a-parachain/) documentation. To set up a test environment, execute the following command: ```bash npx @acala-network/chopsticks \ --config=https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/polkadot-asset-hub.yml ``` The above command will spawn a lazy fork of Polkadot Hub with the latest block data from the network. If you need to test Kusama Hub, replace `polkadot-asset-hub.yml` with `kusama-asset-hub.yml` in the command. A Polkadot Hub instance is now running locally, and you can proceed with the asset registration process. Note that the local registration process does not differ from the live network process. Once you have a successful TestNet transaction, you can use the same steps to register the asset on MainNet. --- Page Title: Set Up the Polkadot SDK Parachain Template - Resolved Markdown: https://docs.polkadot.com/parachains/launch-a-parachain/set-up-the-parachain-template.md - Canonical (HTML): https://docs.polkadot.com/parachains/launch-a-parachain/set-up-the-parachain-template/ - Summary: Learn how to set up and run the Polkadot SDK Parachain Template locally, creating a ready-to-customize foundation for your parachain. - Word Count: 1613; Token Estimate: 2571 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:9d7d1ff02d06fea92df66e2de5a860c6fa2535697d25c8992bc3b70b04886484 # Set Up the Polkadot SDK Parachain Template ## Introduction The [Polkadot SDK](https://github.com/paritytech/polkadot-sdk) includes several [templates](/parachains/customize-runtime/#starting-templates) designed to help you quickly start building your own blockchain. Each template offers a different level of configuration, from minimal setups to feature-rich environments, allowing you to choose the foundation that best fits your project's needs. Among these, the [Parachain Template](https://github.com/paritytech/polkadot-sdk-parachain-template) provides a preconfigured runtime with commonly used pallets, making it an ideal starting point for most parachain development projects. This guide walks you through the full process of working with this template. You will: - Set up the Polkadot SDK Parachain Template. - Understand the project structure and key components. - Verify your template is ready for development. - Run the parachain template locally in development mode. By the end of this guide, you'll have a working template ready to customize and deploy as a parachain. ## Prerequisites Before getting started, ensure you have done the following: - Completed the [Install Polkadot SDK](/parachains/install-polkadot-sdk/) guide and successfully installed [Rust](https://rust-lang.org/) and the required packages to set up your development environment. For this tutorial series, you need to use Rust `1.88`. Newer versions of the compiler may not work with this parachain template version. Run the following commands to set up the correct Rust version: === "macOS" ```bash rustup install 1.88 rustup default 1.88 rustup target add wasm32-unknown-unknown --toolchain 1.88-aarch64-apple-darwin rustup component add rust-src --toolchain 1.88-aarch64-apple-darwin ``` === "Ubuntu" ```bash rustup toolchain install 1.88.0 rustup default 1.88.0 rustup target add wasm32-unknown-unknown --toolchain 1.88.0 rustup component add rust-src --toolchain 1.88.0 ``` ## Polkadot SDK Utility Tools This tutorial requires two essential tools: - [**Chain spec builder**](https://crates.io/crates/staging-chain-spec-builder/16.0.0) - a Polkadot SDK utility for generating chain specifications. Refer to the [Generate Chain Specs](/parachains/launch-a-parachain/deploy-to-polkadot/#generate-the-chain-specification) documentation for detailed usage - [**Polkadot Omni Node**](https://crates.io/crates/polkadot-omni-node/0.13.2) - a white-labeled binary, released as a part of Polkadot SDK, that can act as the collator of a parachain in production, with all the related auxiliary functionalities that a normal collator node has: RPC server, archiving state, etc. It can also run the Wasm blob of the parachain locally for testing and development Download the pre-built binaries from the [Polkadot SDK release](https://github.com/paritytech/polkadot-sdk/releases/tag/polkadot-stable2512-2) (recommended): === "macOS" ```bash curl -L -o chain-spec-builder https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-stable2512-2/chain-spec-builder-aarch64-apple-darwin curl -L -o polkadot-omni-node https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-stable2512-2/polkadot-omni-node-aarch64-apple-darwin chmod +x chain-spec-builder polkadot-omni-node sudo mv chain-spec-builder polkadot-omni-node /usr/local/bin/ ``` === "Ubuntu" ```bash curl -L -o chain-spec-builder https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-stable2512-2/chain-spec-builder curl -L -o polkadot-omni-node https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-stable2512-2/polkadot-omni-node chmod +x chain-spec-builder polkadot-omni-node sudo mv chain-spec-builder polkadot-omni-node /usr/local/bin/ ``` Alternatively, you can install from source using `cargo`: ```bash cargo install --locked staging-chain-spec-builder@16.0.0 cargo install --locked polkadot-omni-node@0.13.2 ``` ## Clone the Template The [Polkadot SDK Parachain Template](https://github.com/paritytech/polkadot-sdk-parachain-template) provides a ready-to-use development environment for building with the [Polkadot SDK](https://github.com/paritytech/polkadot-sdk). Follow these steps to set up the template: 1. Clone the template repository: ```bash git clone https://github.com/paritytech/polkadot-sdk-parachain-template.git parachain-template ``` 2. Navigate into the project directory: ```bash cd parachain-template ``` ## Explore the Project Structure Before building the template, take a moment to familiarize yourself with its structure. Understanding this organization will help you navigate the codebase as you develop your parachain. The template follows a standard Polkadot SDK project layout: ```text parachain-template/ ├── node/ # Node implementation and client ├── pallets/ # Custom pallets for your parachain ├── runtime/ # Runtime configuration and logic ├── Cargo.toml # Workspace configuration └── README.md # Documentation ``` Key directories explained: - **runtime/**: Contains your parachain's state transition function and pallet configuration. This is where you'll define what your blockchain can do. - **node/**: Houses the client implementation that runs your blockchain, handles networking, and manages the database. - **pallets/**: Where you'll create custom business logic modules (pallets) for your specific use case. - **Cargo.toml**: The workspace configuration that ties all components together. !!!note The runtime is compiled to WebAssembly (Wasm), enabling forkless upgrades. The node binary remains constant while the runtime can be updated on-chain. ## Compile the Runtime Now that you understand the template structure, let's compile the runtime to ensure everything is working correctly. 1. Compile the runtime: ```bash cargo build --release --locked ``` !!!tip Initial compilation may take several minutes, depending on your machine specifications. Use the `--release` flag for improved runtime performance compared to the default `--debug` build. If you need to troubleshoot issues, the `--debug` build provides better diagnostics. For production deployments, consider using a dedicated `--profile production` flag - this can provide an additional 15-30% performance improvement over the standard `--release` profile. 2. Upon successful compilation, you should see output indicating the build was successful. The compiled runtime will be located at: `./target/release/wbuild/parachain-template-runtime/parachain_template_runtime.compact.compressed.wasm` ## Verify the Build After compilation completes, verify that the runtime was created successfully by checking for the Wasm blob: ```bash ls -la ./target/release/wbuild/parachain-template-runtime/ ``` You should see the `parachain_template_runtime.compact.compressed.wasm` file in the output, confirming the build was successful. ## Run the Node Locally After successfully compiling your runtime, you can spin up a local chain and produce blocks. This process will start your local parachain using the Polkadot Omni Node and allow you to interact with it. You'll first need to generate a chain specification that defines your network's identity, initial connections, and genesis state, providing the foundational configuration for how your nodes connect and what initial state they agree upon. Follow these steps to launch your node in development mode: 1. Generate the chain specification file of your parachain: ```bash chain-spec-builder create -t development \ --relay-chain paseo \ --para-id 1000 \ --runtime ./target/release/wbuild/parachain-template-runtime/parachain_template_runtime.compact.compressed.wasm \ named-preset development ``` 2. Start the Omni Node with the generated chain spec. You'll start it in development mode (without a relay chain config), producing and finalizing blocks: ```bash polkadot-omni-node --chain ./chain_spec.json --dev ``` The `--dev` option does the following: - Deletes all active data (keys, blockchain database, networking information) when stopped. - Ensures a clean working state each time you restart the node. 3. Verify that your node is running by reviewing the terminal output. You should see log messages indicating block production and finalization. 4. Confirm that your blockchain is producing new blocks by checking if the number after `finalized` is increasing in the output. The details of the log output will be explored in a later tutorial. For now, knowing that your node is running and producing blocks is sufficient. ## Interact with the Node When running the template node, it's accessible by default at `ws://localhost:9944`. To interact with your node using the [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer) interface, follow these steps: 1. Open [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer) in your web browser and click the network icon (which should be the Polkadot logo) in the top left corner: ![](/images/parachains/launch-a-parachain/set-up-the-parachain-template/parachain-template-01.webp) 2. Connect to your local node: 1. Scroll to the bottom and select **Development**. 2. Choose **Custom**. 3. Enter `ws://localhost:9944` in the **custom endpoint** input field. 4. Click the **Switch** button. ![](/images/parachains/launch-a-parachain/set-up-the-parachain-template/parachain-template-02.webp) 3. Once connected, you should see **parachain-template-runtime** in the top left corner, with the interface displaying information about your local blockchain. ![](/images/parachains/launch-a-parachain/set-up-the-parachain-template/parachain-template-03.webp) You are now connected to your local node and can interact with it through the Polkadot.js Apps interface. This tool enables you to explore blocks, execute transactions, and interact with your blockchain's features. For in-depth guidance on using the interface effectively, refer to the [Polkadot.js Guides](https://wiki.polkadot.com/general/polkadotjs/) available on the Polkadot Wiki. ## Stop the Node When you're done exploring your local node, you can stop it to remove any state changes you've made. Since you started the node with the `--dev` option, stopping the node will purge all persistent block data, allowing you to start fresh the next time. To stop the local node: 1. Return to the terminal window where the node output is displayed. 2. Press `Control-C` to stop the running process. 3. Verify that your terminal returns to the prompt in the `parachain-template` directory. ## Where to Go Next
- Tutorial __Deploy to Polkadot__ --- Learn how to deploy your parachain template to a relay chain testnet. Configure your chain specification, register as a parachain, and start producing blocks. [:octicons-arrow-right-24: Get Started](/parachains/launch-a-parachain/deploy-to-polkadot/)
--- Page Title: Smart Contracts Cookbook - Resolved Markdown: https://docs.polkadot.com/smart-contracts/cookbook.md - Canonical (HTML): https://docs.polkadot.com/smart-contracts/cookbook/ - Summary: Explore our full collection of tutorials and guides to learn step-by-step how to build, deploy, and work with smart contracts on Polkadot. - Word Count: 34; Token Estimate: 37 - Last Updated: 2026-06-04T16:08:37+00:00 - Version Hash: sha256:4aed37f738d115d9828ab18bb685636a4cb78b3653fb32d600929d52e4204027 # Smart Contracts Cookbook Welcome to the Polkadot smart contracts cookbook index. This page contains a list of all relevant tutorials and guides to help you get started coding smart contracts and dApps in Polkadot. --- Page Title: Smart Contracts Overview - Resolved Markdown: https://docs.polkadot.com/smart-contracts/overview.md - Canonical (HTML): https://docs.polkadot.com/smart-contracts/overview/ - Summary: Learn about smart contract development on Polkadot Hub with native PVM support, dual-VM execution, and seamless cross-chain capabilities. - Word Count: 572; Token Estimate: 883 - Last Updated: 2026-02-13T21:12:03+00:00 - Version Hash: sha256:dd1216cd7869f321a2335bc514c0392634aabd33921ee68c63237f61bc539bc2 # Smart Contracts on Polkadot Hub ## Introduction Polkadot Hub provides a production-ready smart contract platform that combines Ethereum compatibility with the performance and cross-chain capabilities of the Polkadot ecosystem. Developers can deploy smart contracts directly on Polkadot Hub while using familiar Ethereum tooling, workflows, and programming languages. Built with a dual-VM approach, Polkadot Hub offers two execution backends: REVM for unmodified EVM compatibility and native PVM for optimized computationally expensive workloads. This dual-VM architecture enables developers to migrate existing Ethereum contracts instantly or optimize for speed and efficiency with native execution. ## Why Build on Polkadot Hub ### Ethereum Compatibility Deploy existing Ethereum contracts with zero modifications while maintaining full compatibility with your existing development stack: - **Complete JSON-RPC API support**: Use MetaMask, Hardhat, Remix, Foundry, and all standard Ethereum tooling. - **Standard libraries**: Integrate Ethers.js, Web3.js, Viem, Wagmi, and Web3.py without changes. - **Solidity development**: Write contracts in Solidity or migrate existing code directly. Use the [OpenZeppelin Contracts Wizard for Polkadot](https://wizard.openzeppelin.com/polkadot) to generate secure ERC-20, ERC-721, and other OpenZeppelin-standard contracts. - **Familiar workflows**: Maintain your existing deployment, testing, and monitoring processes. ### Performance Options Choose between two execution backends: - **REVM**: Run unmodified Ethereum contracts with full EVM/Ethereum compatibility. - **PVM**: Compile to optimized RISC-V bytecode for enhanced performance and lower fees while keeping Ethereum-compatibility. You can write PVM contracts in Solidity (via `resolc`) or Rust—for Rust, tooling is maturing; use LLMs and coding agents to assist development. Both backends share the same RPC interface and tooling support, allowing seamless transitions. In addition, smart contracts can interact with Polkadot native services via [precompile contracts](/smart-contracts/precompiles/). ### Cross-VM & Cross-Chain Capabilities Smart contracts written for one VM (for example, EVM) can interact directly with other smart contracts written for the RISC-V PVM, and back. This allows to use full EVM compatible contracts but extend to heavy/complex execution workloads to the PVM RISC-V backend. Furthermore, all smart contracts in Polkadot Hub can interact with any service in the Polkadot ecosystem through [XCM](/smart-contracts/precompiles/xcm/), enabling token transfers, remote execution, and cross-chain composability without bridges or intermediaries. ## Other Smart Contract Environments Beyond Polkadot Hub's native EVM and PVM support, the ecosystem offers one main alternative for smart contract development: - **EVM-compatible parachains**: Provide access to Ethereum's extensive developer ecosystem, smart contract portability, and established tooling like Hardhat, Remix, Foundry, and OpenZeppelin. The main options include Moonbeam (the first full Ethereum-compatible parachain serving as an interoperability hub), Astar (featuring dual VM support for both EVM and WebAssembly contracts), and Acala (DeFi-focused with enhanced Acala EVM+ offering advanced DeFi primitives). ## Next Steps
- Guide __Get Started__ --- Quick-start guides for connecting, deploying, and building your first smart contract. [:octicons-arrow-right-24: Get Started](/smart-contracts/get-started/) - Guide __Cookbook__ --- Step-by-step tutorials for deploying contracts, tokens, NFTs, and full dApps. [:octicons-arrow-right-24: View Tutorials](/smart-contracts/cookbook/) - Guide __Ethereum Developers__ --- Understand key differences in accounts, fees, gas model, and deployment on Polkadot Hub. [:octicons-arrow-right-24: Learn More](/smart-contracts/for-eth-devs/accounts/) - Guide __Precompiles__ --- Discover advanced functionalities including XCM for cross-chain interactions. [:octicons-arrow-right-24: Explore Precompiles](/smart-contracts/precompiles/)
--- Page Title: Support - Resolved Markdown: https://docs.polkadot.com/get-support.md - Canonical (HTML): https://docs.polkadot.com/get-support/ - Summary: Start here to get developer support for Polkadot. Connect with the team, find help, and explore resources beyond the documentation. - Word Count: 582; Token Estimate: 1318 - Last Updated: 2026-03-31T17:52:40+00:00 - Version Hash: sha256:55d620780013f68098103785501b4e460e996daf7be25e03e27e0cf2f8acc837 # Polkadot Developer Support You're already in the docs — solid start. But sometimes you need more: answers, real examples, someone to talk to. This support hub is here to help you move forward — faster. If something’s missing, unclear, or broken — **[tell us](https://github.com/polkadot-developers/polkadot-docs/issues/new?template=docs-issue.yml)**. Your feedback makes the whole ecosystem better for everyone. ## Support Channels Use one of the channels below to get live technical support or ask questions.
- :simple-telegram:{ .sub } **Telegram: Polkadot Developer Support**
  • **Who’s there:** DevRel team and active developer community.
  • **Response time:** Within **2 business days (usually faster)**.
  • **Topics:** Any developer-related question is welcome.
👉 [Join Telegram](https://t.me/substratedevs) - :simple-discord:{ .sub } **Discord: Polkadot Official Server**
  • **Smart contracts:** Ask in `#solidity-smart-contracts` and `#ink_smart-contracts`.
  • **General developer support:** Ask in `#solidity-smart-contracts`.
  • **Response time:** Within **1 business day (usually faster)**.
👉 [Join Discord](https://polkadot-discord.w3f.tools/) - :simple-matrix:{ .sub } **Matrix: Polkadot Developer Support**
  • **Who’s there:** Parity, W3F, DevRel, and community contributors.
  • **Response time:** Within **1 business day (usually faster)**.
  • **Topics:** Full-spectrum developer support.
  • Bridged with Telegram (all messages synced).
👉 [Join Matrix](https://matrix.to/#/#substratedevs:matrix.org)
## Community Resources
- :fontawesome-brands-stack-exchange:{ .sub } **Stack Exchange**
  • Browse commonly asked technical questions.
  • Ask your own and get detailed responses from experienced devs.
👉 [Visit Polkadot Stack Exchange](https://substrate.stackexchange.com/) - :simple-reddit:{ .sub } **Reddit: r/Polkadot**
  • General discussions and community perspectives.
  • Developer questions are welcome — just tag them appropriately.
👉 [Visit r/Polkadot](https://www.reddit.com/r/Polkadot/) - :simple-youtube:{ .sub } **YouTube: @PolkadotNetwork**
  • Developer tutorials.
  • Ecosystem interviews.
  • Event recordings and walkthroughs.
👉 [Watch on YouTube](https://www.youtube.com/@PolkadotNetwork) - :fontawesome-brands-x-twitter:{ .sub } **X (Twitter): Official Accounts** - **[@PolkadotDevs](https://x.com/PolkadotDevs)**: Updates for developers. - **[@Polkadot](https://x.com/Polkadot)**: Network-wide news. - **[@Kusamanetwork](https://x.com/kusamanetwork)**: Kusama-specific updates. - **[@Web3Foundation](https://x.com/web3foundation)**: Grants, research, and ecosystem programs. - :fontawesome-brands-x-twitter:{ .sub } **X (Twitter): Community Accounts** - **[@PolkadotDeploy](https://x.com/PolkadotDeploy)**: News from the deployment portal and tooling updates. - :material-forum:{ .sub } **Polkadot Forum**
  • Join community discussions around the direction of the ecosystem.
👉 [Visit the Polkadot Forum](https://forum.polkadot.network/) - :material-vote:{ .sub } **Polkassembly: OpenGov**
  • Explore and vote on governance proposals for Polkadot and Kusama.
  • Help shape the future of the network.
👉 [Explore on Polkassembly](https://polkadot.polkassembly.io/) - :material-vote:{ .sub } **Subsquare: OpenGov**
  • Track, discuss, and vote on Polkadot OpenGov proposals.
  • Stay informed on governance activity across the network.
👉 [Explore on Subsquare](https://polkadot.subsquare.io/)
## AI Resources
- :fontawesome-solid-robot:{ .sub } **AI Resources** Access documentation structured and optimized for use with large language models (LLMs) and AI tools. These resources help build AI assistants, power code search, or enable custom tooling trained on Polkadot’s documentation. 👉 [Access LLM Files](/ai-resources/)
--- Page Title: Technical Reference Overview - Resolved Markdown: https://docs.polkadot.com/reference.md - Canonical (HTML): https://docs.polkadot.com/reference/ - Summary: Learn about Polkadot's technical architecture, governance framework, parachain ecosystem, and the tools you need to build and interact with the network. - Word Count: 888; Token Estimate: 1531 - Last Updated: 2026-06-16T14:17:44+00:00 - Version Hash: sha256:ac0e0c8b8514a78950c5df651820407b66da8c569086b8324e82c370604ba6a7 ## Introduction The Technical Reference section provides comprehensive documentation of Polkadot's architecture, core concepts, and development tooling. Whether you're exploring how Polkadot's relay chain coordinates parachains, understanding governance mechanisms, or building applications on the network, this reference covers the technical foundations you need. Polkadot is a multi-chain network that enables diverse, interconnected blockchains to share security and communicate seamlessly. Understanding how these components interact from the Relay Chain that validates parachains to the Governance mechanisms that evolve the protocol is essential for developers, validators, and network participants. This guide organizes technical documentation across five core areas: Polkadot Hub, Parachains, On-Chain Governance, Glossary, and Tools, each providing detailed information on different aspects of the Polkadot ecosystem. ## Polkadot Hub [Polkadot Hub](/reference/polkadot-hub/) is the entry point to Polkadot for all users and application developers. It provides access to essential Web3 services including smart contracts, asset management, staking, governance, identity management, and cross-ecosystem interoperability—without requiring you to deploy or manage a parachain. The Hub encompasses a set of core functionality that enables developers and users to build and interact with applications on Polkadot. Key capabilities include: - **Smart contracts**: Deploy Ethereum-compatible smart contracts and build decentralized applications. - **Asset management**: Create, manage, and transfer fungible tokens and NFTs across the ecosystem. - **Staking**: Participate in network security and earn rewards by staking DOT. - **Governance**: Vote on proposals and participate in Polkadot's decentralized decision-making through OpenGov. - **Identity services**: Register and manage on-chain identities, enabling access to governance roles and network opportunities. - **Cross-chain interoperability**: Leverage XCM messaging to interact securely with other chains in the Polkadot ecosystem. - **Collectives and DAOs**: Participate in governance collectives and decentralized autonomous organizations. ## Parachains [Parachains](/reference/parachains/) are specialized blockchains that connect to the Polkadot relay chain, inheriting its security while maintaining their own application-specific logic. The parachains documentation covers: - **Accounts**: Deep dive into account types, storage, and management on parachains. - **Blocks, transactions and fees**: Understand block production, transaction inclusion, and fee mechanisms. - **Consensus**: Learn how parachain blocks are validated and finalized through the relay chain's consensus. - **Chain data**: Explore data structures, storage layouts, and state management. - **Cryptography**: Study cryptographic primitives used in Polkadot SDK-based chains. - **Data encoding**: Understand how data is encoded and decoded for blockchain compatibility. - **Networks**: Learn about networking protocols and peer-to-peer communication. - **Interoperability**: Discover [Cross-Consensus Messaging (XCM)](/parachains/interoperability/get-started/), the standard for cross-chain communication. - **Randomness**: Understand how randomness is generated and used in Polkadot chains. - **Node and runtime**: Learn about parachain nodes, runtime environments, and the [Polkadot SDK](https://github.com/paritytech/polkadot-sdk). ## On-Chain Governance [On-Chain governance](/reference/governance/) is the decentralized decision-making mechanism for the Polkadot network. It manages the evolution and modification of the network's runtime logic, enabling community oversight and approval for proposed changes. The governance documentation details: - **OpenGov framework**: Understand Polkadot's next-generation governance system with enhanced delegation, flexible tracks, and simultaneous referendums. - **Origins and tracks**: Learn how governance proposals are categorized, prioritized, and executed based on their privilege level and complexity. - **Voting and delegation**: Explore conviction voting, vote delegation, and how token holders participate in governance. - **Governance evolution**: See how Polkadot's governance has evolved from Governance V1 to the current OpenGov system. ## Glossary The [Glossary](/reference/glossary/) provides quick-reference definitions for Polkadot-specific terminology. Essential terms include: - Blockchain concepts (blocks, transactions, state) - Consensus mechanisms (validators, collators, finality) - Polkadot-specific terms (relay chain, parachain, XCM, FRAME) - Network components (nodes, runtimes, storage) - Governance terminology (origins, tracks, referendums) ## Tools The [Tools](/reference/tools/zombienet/) section documents essential development and interaction tools for the Polkadot ecosystem: - **Light clients**: Lightweight solutions for interacting with the network without running full nodes. - **JavaScript/TypeScript tools**: Libraries like [Polkadot.js API](/reference/tools/polkadot-js-api/) and [PAPI](/reference/tools/papi/) for building applications. - **Rust tools**: [Polkadart](/reference/tools/polkadart/) and other Rust-based libraries for SDK development. - **Python tools**: [py-substrate-interface](/reference/tools/py-substrate-interface/) for Python developers. - **Testing and development**: Tools like [Moonwall](/reference/tools/moonwall/), [Chopsticks](/reference/tools/chopsticks/), and [Omninode](/reference/tools/omninode/) for smart contract and parachain testing. - **Indexing and monitoring**: [Sidecar](/reference/tools/sidecar/) for data indexing and [Dedot](/reference/tools/dedot/) for substrate interaction. - **Cross-chain tools**: [ParaSpell](/reference/tools/paraspell/) for XCM integration and asset transfers. ## Where to Go Next For detailed exploration of specific areas, proceed to any of the main sections:
- Learn **Polkadot Hub** --- Understand the relay chain's role in coordinating parachains, providing shared security, and enabling governance. [:octicons-arrow-right-24: Reference](/reference/polkadot-hub/) - Learn **Parachains** --- Deep dive into parachain architecture, consensus, data structures, and building application-specific blockchains. [:octicons-arrow-right-24: Reference](/reference/parachains/) - Learn **On-Chain Governance** --- Explore Polkadot's decentralized governance framework and how to participate in network decision-making. [:octicons-arrow-right-24: Reference](/reference/governance/) - Guide **Glossary** --- Quick reference for Polkadot-specific terminology and concepts used throughout the documentation. [:octicons-arrow-right-24: Reference](/reference/glossary/) - Guide **Tools** --- Discover development tools, libraries, and frameworks for building and interacting with Polkadot. [:octicons-arrow-right-24: Reference](/reference/tools/zombienet/)
--- Page Title: Transactions - Resolved Markdown: https://docs.polkadot.com/reference/parachains/blocks-transactions-fees/transactions.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/blocks-transactions-fees/transactions/ - Summary: Learn how to construct, submit, and validate transactions in the Polkadot SDK, covering signed, unsigned, and inherent types of transactions. - Word Count: 3300; Token Estimate: 4611 - Last Updated: 2026-01-14T11:42:16+00:00 - Version Hash: sha256:96d19c9c56bc35c73c5f003c55ffcff74bd39cd7d74cf17201abd20b15e2dd05 # Transactions ## Introduction Transactions are essential components of blockchain networks, enabling state changes and the execution of key operations. In the Polkadot SDK, transactions, often called extrinsics, come in multiple forms, including signed, unsigned, and inherent transactions. This guide walks you through the different transaction types and how they're formatted, validated, and processed within the Polkadot ecosystem. You'll also learn how to customize transaction formats and construct transactions for FRAME-based runtimes, ensuring a complete understanding of how transactions are built and executed in Polkadot SDK-based chains. ## What Is a Transaction? In the Polkadot SDK, transactions represent operations that modify the chain's state, bundled into blocks for execution. The term extrinsic is often used to refer to any data that originates outside the runtime and is included in the chain. While other blockchain systems typically refer to these operations as "transactions," the Polkadot SDK adopts the broader term "extrinsic" to capture the wide variety of data types that can be added to a block. There are three primary types of transactions (extrinsics) in the Polkadot SDK: - **Signed transactions**: Signed by the submitting account, often carrying transaction fees. - **Unsigned transactions**: Submitted without a signature, often requiring custom validation logic. - **Inherent transactions**: Typically inserted directly into blocks by block authoring nodes, without gossiping between peers. Each type serves a distinct purpose, and understanding when and how to use each is key to efficiently working with the Polkadot SDK. ### Signed Transactions Signed transactions require an account's signature and typically involve submitting a request to execute a runtime call. The signature serves as a form of cryptographic proof that the sender has authorized the action, using their private key. These transactions often involve a transaction fee to cover the cost of execution and incentivize block producers. Signed transactions are the most common type of transaction and are integral to user-driven actions, such as token transfers. For instance, when you transfer tokens from one account to another, the sending account must sign the transaction to authorize the operation. For example, the [`pallet_balances::Call::transfer_allow_death`](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/pallet/struct.Pallet.html#method.transfer_allow_death) extrinsic in the Balances pallet allows you to transfer tokens. Since your account initiates this transaction, your account key is used to sign it. You'll also be responsible for paying the associated transaction fee, with the option to include an additional tip to incentivize faster inclusion in the block. ### Unsigned Transactions Unsigned transactions do not require a signature or account-specific data from the sender. Unlike signed transactions, they do not come with any form of economic deterrent, such as fees, which makes them susceptible to spam or replay attacks. Custom validation logic must be implemented to mitigate these risks and ensure these transactions are secure. Unsigned transactions typically involve scenarios where including a fee or signature is unnecessary or counterproductive. However, due to the absence of fees, they require careful validation to protect the network. For example, [`pallet_im_online::Call::heartbeat`](https://paritytech.github.io/polkadot-sdk/master/pallet_im_online/pallet/struct.Pallet.html#method.heartbeat) extrinsic allows validators to send a heartbeat signal, indicating they are active. Since only validators can make this call, the logic embedded in the transaction ensures that the sender is a validator, making the need for a signature or fee redundant. Unsigned transactions are more resource-intensive than signed ones because custom validation is required, but they play a crucial role in certain operational scenarios, especially when regular user accounts aren't involved. ### Inherent Transactions Inherent transactions are a specialized type of unsigned transaction that is used primarily for block authoring. Unlike signed or other unsigned transactions, inherent transactions are added directly by block producers and are not broadcasted to the network or stored in the transaction queue. They don't require signatures or the usual validation steps and are generally used to insert system-critical data directly into blocks. A key example of an inherent transaction is inserting a timestamp into each block. The [`pallet_timestamp::Call::now`](https://paritytech.github.io/polkadot-sdk/master/pallet_timestamp/pallet/struct.Pallet.html#method.now-1) extrinsic allows block authors to include the current time in the block they are producing. Since the block producer adds this information, there is no need for transaction validation, like signature verification. The validation in this case is done indirectly by the validators, who check whether the timestamp is within an acceptable range before finalizing the block. Another example is the [`paras_inherent::Call::enter`](https://paritytech.github.io/polkadot-sdk/master/polkadot_runtime_parachains/paras_inherent/pallet/struct.Pallet.html#method.enter) extrinsic, which enables parachain collator nodes to send validation data to the relay chain. This inherent transaction ensures that the necessary parachain data is included in each block without the overhead of gossiped transactions. Inherent transactions serve a critical role in block authoring by allowing important operational data to be added directly to the chain without needing the validation processes required for standard transactions. ## Transaction Formats Understanding the structure of signed and unsigned transactions is crucial for developers building on Polkadot SDK-based chains. Whether you're optimizing transaction processing, customizing formats, or interacting with the transaction pool, knowing the format of extrinsics, Polkadot's term for transactions, is essential. ### Types of Transaction Formats In Polkadot SDK-based chains, extrinsics can fall into three main categories: - **Unchecked extrinsics**: Typically used for signed transactions that require validation. They contain a signature and additional data, such as a nonce and information for fee calculation. Unchecked extrinsics are named as such because they require validation checks before being accepted into the transaction pool. - **Checked extrinsics**: Typically used for inherent extrinsics (unsigned transactions); these don't require signature verification. Instead, they carry information such as where the extrinsic originates and any additional data required for the block authoring process. - **Opaque extrinsics**: Used when the format of an extrinsic is not yet fully committed or finalized. They are still decodable, but their structure can be flexible depending on the context. ### Signed Transaction Data Structure A signed transaction typically includes the following components: - **Signature**: Verifies the authenticity of the transaction sender. - **Call**: The actual function or method call the transaction is requesting (for example, transferring funds). - **Nonce**: Tracks the number of prior transactions sent from the account, helping to prevent replay attacks. - **Tip**: An optional incentive to prioritize the transaction in block inclusion. - **Additional data**: Includes details such as spec version, block hash, and genesis hash to ensure the transaction is valid within the correct runtime and chain context. Here's a simplified breakdown of how signed transactions are typically constructed in a Polkadot SDK runtime: ``` code + + ``` Each part of the signed transaction has a purpose, ensuring the transaction's authenticity and context within the blockchain. ### Signed Extensions Polkadot SDK also provides the concept of [signed extensions](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/signed_extensions/index.html), which allow developers to extend extrinsics with additional data or validation logic before they are included in a block. The [`SignedExtension`](https://paritytech.github.io/try-runtime-cli/sp_runtime/traits/trait.SignedExtension.html) set helps enforce custom rules or protections, such as ensuring the transaction's validity or calculating priority. The transaction queue regularly calls signed extensions to verify a transaction's validity before placing it in the ready queue. This safeguard ensures transactions won't fail in a block. Signed extensions are commonly used to enforce validation logic and protect the transaction pool from spam and replay attacks. In FRAME, a signed extension can hold any of the following types by default: - **[`AccountId`](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_frame/runtime/types_common/type.AccountId.html)**: To encode the sender's identity. - **[`Call`](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_frame/traits/trait.SignedExtension.html#associatedtype.Call)**: To encode the pallet call to be dispatched. This data is used to calculate transaction fees. - **[`AdditionalSigned`](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_frame/traits/trait.SignedExtension.html#associatedtype.AdditionalSigned)**: To handle any additional data to go into the signed payload allowing you to attach any custom logic prior to dispatching a transaction. - **[`Pre`](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_frame/traits/trait.SignedExtension.html#associatedtype.Pre)**: To encode the information that can be passed from before a call is dispatched to after it gets dispatched. Signed extensions can enforce checks like: - **[`CheckSpecVersion`](https://paritytech.github.io/polkadot-sdk/master/src/frame_system/extensions/check_spec_version.rs.html)**: Ensures the transaction is compatible with the runtime's current version. - **[`CheckWeight`](https://paritytech.github.io/polkadot-sdk/master/frame_system/struct.CheckWeight.html)**: Calculates the weight (or computational cost) of the transaction, ensuring the block doesn't exceed the maximum allowed weight. These extensions are critical in the transaction lifecycle, ensuring that only valid and prioritized transactions are processed. ## Transaction Construction Building transactions in the Polkadot SDK involves constructing a payload that can be verified, signed, and submitted for inclusion in a block. Each runtime in the Polkadot SDK has its own rules for validating and executing transactions, but there are common patterns for constructing a signed transaction. ### Construct a Signed Transaction A signed transaction in the Polkadot SDK includes various pieces of data to ensure security, prevent replay attacks, and prioritize processing. Here's an overview of how to construct one: 1. **Construct the unsigned payload**: Gather the necessary information for the call, including: - **Pallet index**: Identifies the pallet where the runtime function resides. - **Function index**: Specifies the particular function to call in the pallet. - **Parameters**: Any additional arguments required by the function call. 2. **Create a signing payload**: Once the unsigned payload is ready, additional data must be included: - **Transaction nonce**: Unique identifier to prevent replay attacks. - **Era information**: Defines how long the transaction is valid before it's dropped from the pool. - **Block hash**: Ensures the transaction doesn't execute on the wrong chain or fork. 3. **Sign the payload**: Using the sender's private key, sign the payload to ensure that the transaction can only be executed by the account holder. 4. **Serialize the signed payload**: Once signed, the transaction must be serialized into a binary format, ensuring the data is compact and easy to transmit over the network. 5. **Submit the serialized transaction**: Finally, submit the serialized transaction to the network, where it will enter the transaction pool and wait for processing by an authoring node. The following is an example of how a signed transaction might look: ``` rust node_runtime::UncheckedExtrinsic::new_signed( function.clone(), // some call sp_runtime::AccountId32::from(sender.public()).into(), // some sending account node_runtime::Signature::Sr25519(signature.clone()), // the account's signature extra.clone(), // the signed extensions ) ``` ### Transaction Encoding Before a transaction is sent to the network, it is serialized and encoded using a structured encoding process that ensures consistency and prevents tampering: - **`[1]`**: Compact encoded length in bytes of the entire transaction. - **`[2]`**: A u8 containing 1 byte to indicate whether the transaction is signed or unsigned (1 bit) and the encoded transaction version ID (7 bits). - **`[3]`**: If signed, this field contains an account ID, an SR25519 signature, and some extra data. - **`[4]`**: Encoded call data, including pallet and function indices and any required arguments. This encoded format ensures consistency and efficiency in processing transactions across the network. By adhering to this format, applications can construct valid transactions and pass them to the network for execution. To learn more about how compact encoding works using SCALE, see the [SCALE Codec](https://github.com/paritytech/parity-scale-codec) README on GitHub. ### Customize Transaction Construction Although the basic steps for constructing transactions are consistent across Polkadot SDK-based chains, developers can customize transaction formats and validation rules. For example: - **Custom pallets**: You can define new pallets with custom function calls, each with its own parameters and validation logic. - **Signed extensions**: Developers can implement custom extensions that modify how transactions are prioritized, validated, or included in blocks. By leveraging Polkadot SDK's modular design, developers can create highly specialized transaction logic tailored to their chain's needs. ## Lifecycle of a Transaction In the Polkadot SDK, transactions are often referred to as extrinsics because the data in transactions originates outside of the runtime. These transactions contain data that initiates changes to the chain state. The most common type of extrinsic is a signed transaction, which is cryptographically verified and typically incurs a fee. This section focuses on how signed transactions are processed, validated, and ultimately included in a block. ### Define Transaction Properties The Polkadot SDK runtime defines key transaction properties, such as: - **Transaction validity**: Ensures the transaction meets all runtime requirements. - **Signed or unsigned**: Identifies whether a transaction needs to be signed by an account. - **State changes**: Determines how the transaction modifies the state of the chain. Pallets, which compose the runtime's logic, define the specific transactions that your chain supports. When a user submits a transaction, such as a token transfer, it becomes a signed transaction, verified by the user's account signature. If the account has enough funds to cover fees, the transaction is executed, and the chain's state is updated accordingly. ### Process on a Block Authoring Node In Polkadot SDK-based networks, some nodes are authorized to author blocks. These nodes validate and process transactions. When a transaction is sent to a node that can produce blocks, it undergoes a lifecycle that involves several stages, including validation and execution. Non-authoring nodes gossip the transaction across the network until an authoring node receives it. The following diagram illustrates the lifecycle of a transaction that's submitted to a network and processed by an authoring node. ![Transaction lifecycle diagram](/images/reference/parachains/blocks-transactions-fees/transactions/transactions-01.webp) ### Validate and Queue Once a transaction reaches an authoring node, it undergoes an initial validation process to ensure it meets specific conditions defined in the runtime. This validation includes checks for: - **Correct nonce**: Ensures the transaction is sequentially valid for the account. - **Sufficient funds**: Confirms the account can cover any associated transaction fees. - **Signature validity**: Verifies that the sender's signature matches the transaction data. After these checks, valid transactions are placed in the transaction pool, where they are queued for inclusion in a block. The transaction pool regularly re-validates queued transactions to ensure they remain valid before being processed. To reach consensus, two-thirds of the nodes must agree on the order of the transactions executed and the resulting state change. Transactions are validated and queued on the local node in a transaction pool to prepare for consensus. #### Transaction Pool The transaction pool is responsible for managing valid transactions. It ensures that only transactions that pass initial validity checks are queued. Transactions that fail validation, expire, or become invalid for other reasons are removed from the pool. The transaction pool organizes transactions into two queues: - **Ready queue**: Transactions that are valid and ready to be included in a block. - **Future queue**: Transactions that are not yet valid but could be in the future, such as transactions with a nonce too high for the current state. Details on how the transaction pool validates transactions, including fee and signature handling, can be found in the [`validate_transaction`](https://paritytech.github.io/polkadot-sdk/master/sp_transaction_pool/runtime_api/trait.TaggedTransactionQueue.html#method.validate_transaction) method. #### Invalid Transactions If a transaction is invalid, for example, due to an invalid signature or insufficient funds, it is rejected and won't be added to the block. Invalid transactions might be rejected for reasons such as: - The transaction has already been included in a block. - The transaction's signature does not match the sender. - The transaction is too large to fit in the current block. ### Transaction Ordering and Priority When a node is selected as the next block author, it prioritizes transactions based on weight, length, and tip amount. The goal is to fill the block with high-priority transactions without exceeding its maximum size or computational limits. Transactions are ordered as follows: - **Inherents first**: Inherent transactions, such as block timestamp updates, are always placed first. - **Nonce-based ordering**: Transactions from the same account are ordered by their nonce. - **Fee-based ordering**: Among transactions with the same nonce or priority level, those with higher fees are prioritized. ### Transaction Execution Once a block author selects transactions from the pool, the transactions are executed in priority order. As each transaction is processed, the state changes are written directly to the chain's storage. It's important to note that these changes are not cached, meaning a failed transaction won't revert earlier state changes, which could leave the block in an inconsistent state. Events are also written to storage. Runtime logic should not emit an event before performing the associated actions. If the associated transaction fails after the event was emitted, the event will not revert. ## Transaction Mortality Transactions in the network can be configured as either mortal (with expiration) or immortal (without expiration). Every transaction payload contains a block checkpoint (reference block number and hash) and an era/validity period that determines how many blocks after the checkpoint the transaction remains valid. When a transaction is submitted, the network validates it against these parameters. If the transaction is not included in a block within the specified validity window, it is automatically removed from the transaction queue. - **Mortal transactions**: Have a finite lifespan and will expire after a specified number of blocks. For example, a transaction with a block checkpoint of 1000 and a validity period of 64 blocks will be valid from blocks 1000 to 1064. - **Immortal transactions**: Never expire and remain valid indefinitely. To create an immortal transaction, set the block checkpoint to 0 (genesis block), use the genesis hash as a reference, and set the validity period to 0. However, immortal transactions pose significant security risks through replay attacks. If an account is reaped (balance drops to zero, account removed) and later re-funded, malicious actors can replay old immortal transactions. The blockchain maintains only a limited number of prior block hashes for reference validation, called `BlockHashCount`. If your validity period exceeds `BlockHashCount`, the effective validity period becomes the minimum of your specified period and the block hash count. ## Unique Identifiers for Extrinsics Transaction hashes are **not unique identifiers** in Polkadot SDK-based chains. Key differences from traditional blockchains: - Transaction hashes serve only as fingerprints of transaction information. - Multiple valid transactions can share the same hash. - Hash uniqueness assumptions lead to serious issues. For example, when an account is reaped (removed due to insufficient balance) and later recreated, it resets to nonce 0, allowing identical transactions to be valid at different points: | Block | Extrinsic Index | Hash | Origin | Nonce | Call | Result | |-------|----------------|------|-----------|-------|---------------------|-------------------------------| | 100 | 0 | 0x01 | Account A | 0 | Transfer 5 DOT to B | Account A reaped | | 150 | 5 | 0x02 | Account B | 4 | Transfer 7 DOT to A | Account A created (nonce = 0) | | 200 | 2 | 0x01 | Account A | 0 | Transfer 5 DOT to B | Successful transaction | Notice that blocks 100 and 200 contain transactions with identical hashes (0x01) but are completely different, valid operations occurring at different times. Additional complexity comes from Polkadot SDK's origin abstraction. Origins can represent collectives, governance bodies, or other non-account entities that don't maintain nonces like regular accounts and might dispatch identical calls multiple times with the same hash values. Each execution occurs in different chain states with different results. The correct way to uniquely identify an extrinsic on a Polkadot SDK-based chain is to use the block ID (height or hash) and the extrinsic index. Since the Polkadot SDK defines blocks as headers plus ordered arrays of extrinsics, the index position within a canonical block provides guaranteed uniqueness. ## Additional Resources For a video overview of the lifecycle of transactions and the types of transactions that exist, see the [Transaction lifecycle](https://www.youtube.com/watch?v=3pfM0GOp02c) seminar from Parity Tech. --- Page Title: Transactions Weights and Fees - Resolved Markdown: https://docs.polkadot.com/reference/parachains/blocks-transactions-fees/fees.md - Canonical (HTML): https://docs.polkadot.com/reference/parachains/blocks-transactions-fees/fees/ - Summary: Overview of transaction weights and fees in Polkadot SDK chains, detailing how fees are calculated using a defined formula and runtime specifics. - Word Count: 2826; Token Estimate: 4200 - Last Updated: 2026-05-27T20:25:14+00:00 - Version Hash: sha256:a9b6429d3b95d59c930a3ec6dd4aecea4f5c2a7bd6eb4cea480ce3a4e34785e7 # Transactions Weights and Fees ## Introductions When transactions are executed, or data is stored on-chain, the activity changes the chain's state and consumes blockchain resources. Because the resources available to a blockchain are limited, managing how operations on-chain consume them is important. In addition to being limited in practical terms, such as storage capacity, blockchain resources represent a potential attack vector for malicious users. For example, a malicious user might attempt to overload the network with messages to stop the network from producing new blocks. To protect blockchain resources from being drained or overloaded, you need to manage how they are made available and how they are consumed. The resources to be aware of include: - Memory usage - Storage input and output - Computation - Transaction and block size - State database size The Polkadot SDK provides block authors with several ways to manage access to resources and to prevent individual components of the chain from consuming too much of any single resource. Two of the most important mechanisms available to block authors are weights and transaction fees. Weights manage the time it takes to validate a block and characterize the time it takes to execute the calls in the block's body. By controlling the execution time a block can consume, weights set limits on storage input, output, and computation. Some of the weight allowed for a block is consumed as part of the block's initialization and finalization. The weight might also be used to execute mandatory inherent extrinsic calls. To help ensure blocks don’t consume too much execution time and prevent malicious users from overloading the system with unnecessary calls, weights are combined with transaction fees. [Transaction fees](/reference/parachains/blocks-transactions-fees/transactions/#transaction-fees) provide an economic incentive to limit execution time, computation, and the number of calls required to perform operations. Transaction fees are also used to make the blockchain economically sustainable because they are typically applied to transactions initiated by users and deducted before a transaction request is executed. ## How Fees are Calculated The final fee for a transaction is calculated using the following parameters: - **`base fee`**: This is the minimum amount a user pays for a transaction. It is declared a base weight in the runtime and converted to a fee using the [`WeightToFee`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/pallet/trait.Config.html#associatedtype.WeightToFee) conversion. - **`weight fee`**: A fee proportional to the execution time (input and output and computation) that a transaction consumes. - **`length fee`**: A fee proportional to the encoded length of the transaction. - **`tip`**: An optional tip to increase the transaction’s priority, giving it a higher chance to be included in the transaction queue. The base fee and proportional weight and length fees constitute the inclusion fee. The inclusion fee is the minimum fee that must be available for a transaction to be included in a block. ```text inclusion fee = base fee + weight fee + length fee ``` Transaction fees are withdrawn before the transaction is executed. After the transaction is executed, the weight can be adjusted to reflect the resources used. If a transaction uses fewer resources than expected, the transaction fee is corrected, and the adjusted transaction fee is deposited. ## Using the Transaction Payment Pallet The [Transaction Payment pallet](https://github.com/paritytech/polkadot-sdk/tree/polkadot-stable2603/substrate/frame/transaction-payment) provides the basic logic for calculating the inclusion fee. You can also use the Transaction Payment pallet to: - Convert a weight value into a deductible fee based on a currency type using [`Config::WeightToFee`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/pallet/trait.Config.html#associatedtype.WeightToFee). - Update the fee for the next block by defining a multiplier based on the chain’s final state at the end of the previous block using [`Config::FeeMultiplierUpdate`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/pallet/trait.Config.html#associatedtype.FeeMultiplierUpdate). - Manage the withdrawal, refund, and deposit of transaction fees using [`Config::OnChargeTransaction`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/pallet/trait.Config.html#associatedtype.OnChargeTransaction). You can learn more about these configuration traits in the [Transaction Payment documentation](https://paritytech.github.io/polkadot-sdk/master/pallet_transaction_payment/index.html). ### Understanding the Inclusion Fee The formula for calculating the inclusion fee is as follows: ```text inclusion_fee = base_fee + length_fee + [targeted_fee_adjustment * weight_fee] ``` And then, for calculating the final fee: ```text final_fee = inclusion_fee + tip ``` In the first formula, the `targeted_fee_adjustment` is a multiplier that can tune the final fee based on the network’s congestion. - The `base_fee` derived from the base weight covers inclusion overhead like signature verification. - The `length_fee` is a per-byte fee that is multiplied by the length of the encoded extrinsic. - The `weight_fee` fee is calculated using two parameters: - The `ExtrinsicBaseWeight` that is declared in the runtime and applies to all extrinsics. - The `#[pallet::weight]` annotation that accounts for an extrinsic's complexity. To convert the weight to `Currency`, the runtime must define a `WeightToFee` struct that implements a conversion function, [`Convert`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/pallet/struct.Pallet.html#method.weight_to_fee). Note that the extrinsic sender is charged the inclusion fee before the extrinsic is invoked. The fee is deducted from the sender's balance even if the transaction fails upon execution. ### Accounts with an Insufficient Balance If an account does not have a sufficient balance to pay the inclusion fee and remain alive—that is, enough to pay the inclusion fee and maintain the minimum existential deposit—then you should ensure the transaction is canceled so that no fee is deducted and the transaction does not begin execution. The Polkadot SDK doesn't enforce this rollback behavior. However, this scenario would be rare because the transaction queue and block-making logic perform checks to prevent it before adding an extrinsic to a block. ### Fee Multipliers The inclusion fee formula always results in the same fee for the same input. However, weight can be dynamic and—based on how [`WeightToFee`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/pallet/trait.Config.html#associatedtype.WeightToFee) is defined—the final fee can include some degree of variability. The Transaction Payment pallet provides the [`FeeMultiplierUpdate`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/pallet/trait.Config.html#associatedtype.FeeMultiplierUpdate) configurable parameter to account for this variability. The Polkadot network inspires the default update function and implements a targeted adjustment in which a target saturation level of block weight is defined. If the previous block is more saturated, the fees increase slightly. Similarly, if the last block has fewer transactions than the target, fees are decreased by a small amount. For more information about fee multiplier adjustments, see the [Polkadot wiki](https://wiki.polkadot.com/learn/learn-transactions/#fee-multiplier). ## Transactions with Special Requirements Inclusion fees must be computable before execution and can only represent fixed logic. Some transactions warrant limiting resources with other strategies. For example: - Bonds are a type of fee that might be returned or slashed after some on-chain event. For example, you might want to require users to place a bond to participate in a vote. The bond might then be returned at the end of the referendum or slashed if the voter attempted malicious behavior. - Deposits are fees that might be returned later. For example, you might require users to pay a deposit to execute an operation that uses storage. The user’s deposit could be returned if a subsequent operation frees up storage. - Burn operations are used to pay for a transaction based on its internal logic. For example, a transaction might burn funds from the sender if the transaction creates new storage items to pay for the increased state size. - Limits enable you to enforce constant or configurable limits on specific operations. For example, the default [Staking pallet](https://github.com/paritytech/polkadot-sdk/tree/polkadot-stable2603/substrate/frame/staking) only allows nominators to nominate 16 validators to limit the complexity of the validator election process. It is important to note that if you query the chain for a transaction fee, it only returns the inclusion fee. ## Default Weight Annotations All dispatchable functions in the Polkadot SDK must specify a weight. The way of doing that is using the annotation-based system that lets you combine fixed values for database read/write weight and/or fixed values based on benchmarks. The most basic example would look like this: ```rust #[pallet::weight(100_000)] fn my_dispatchable() ``` Note that the [`ExtrinsicBaseWeight`](https://crates.parity.io/frame_support/weights/constants/struct.ExtrinsicBaseWeight.html) is automatically added to the declared weight to account for the costs of simply including an empty extrinsic into a block. ### Weights and Database Read/Write Operations To make weight annotations independent of the deployed database backend, they are defined as a constant and then used in the annotations when expressing database accesses performed by the dispatchable: ```rust #[pallet::weight(T::DbWeight::get().reads_writes(1, 2) + 20_000)] fn my_dispatchable() ``` This dispatchable allows one database to read and two to write, in addition to other things that add the additional 20,000. Database access is generally every time a value declared inside the [`#[pallet::storage]`](https://paritytech.github.io/polkadot-sdk/master/frame_support/pallet_macros/attr.storage.html) block is accessed. However, unique accesses are counted because after a value is accessed, it is cached, and reaccessing it does not result in a database operation. That is: - Multiple reads of the exact value count as one read. - Multiple writes of the exact value count as one write. - Multiple reads of the same value, followed by a write to that value, count as one read and one write. - A write followed by a read-only counts as one write. ### Dispatch Classes Dispatches are broken into three classes: - Normal - Operational - Mandatory If a dispatch is not defined as `Operational` or `Mandatory` in the weight annotation, the dispatch is identified as `Normal` by default. You can specify that the dispatchable uses another class like this: ```rust #[pallet::dispatch((DispatchClass::Operational))] fn my_dispatchable() ``` This tuple notation also allows you to specify a final argument determining whether the user is charged based on the annotated weight. If you don't specify otherwise, `Pays::Yes` is assumed: ```rust #[pallet::dispatch(DispatchClass::Normal, Pays::No)] fn my_dispatchable() ``` #### Normal Dispatches Dispatches in this class represent normal user-triggered transactions. These types of dispatches only consume a portion of a block's total weight limit. For information about the maximum portion of a block that can be consumed for normal dispatches, see [`AvailableBlockRatio`](https://paritytech.github.io/polkadot-sdk/master/frame_system/limits/struct.BlockLength.html). Normal dispatches are sent to the transaction pool. #### Operational Dispatches Unlike normal dispatches, which represent the usage of network capabilities, operational dispatches are those that provide network capabilities. Operational dispatches can consume the entire weight limit of a block. They are not bound by the [`AvailableBlockRatio`](https://paritytech.github.io/polkadot-sdk/master/frame_system/limits/struct.BlockLength.html). Dispatches in this class are given maximum priority and are exempt from paying the [`length_fee`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/). #### Mandatory Dispatches Mandatory dispatches are included in a block even if they cause the block to surpass its weight limit. You can only use the mandatory dispatch class for inherent transactions that the block author submits. This dispatch class is intended to represent functions in the block validation process. Because these dispatches are always included in a block regardless of the function weight, the validation process must prevent malicious nodes from abusing the function to craft valid but impossibly heavy blocks. You can typically accomplish this by ensuring that: - The operation performed is always light. - The operation can only be included in a block once. To make it more difficult for malicious nodes to abuse mandatory dispatches, they cannot be included in blocks that return errors. This dispatch class serves the assumption that it is better to allow an overweight block to be created than not to allow any block to be created at all. ### Dynamic Weights In addition to purely fixed weights and constants, the weight calculation can consider the input arguments of a dispatchable. The weight should be trivially computable from the input arguments with some basic arithmetic: ```rust use frame_support:: { dispatch:: { DispatchClass::Normal, Pays::Yes, }, weights::Weight, }; #[pallet::weight(FunctionOf( |args: (&Vec,)| args.0.len().saturating_mul(10_000), ) ] fn handle_users(origin, calls: Vec) ``` ## Post Dispatch Weight Correction Depending on the execution logic, a dispatchable function might consume less weight than was prescribed pre-dispatch. To correct weight, the function declares a different return type and returns its actual weight: ```rust #[pallet::weight(10_000 + 500_000_000)] fn expensive_or_cheap(input: u64) -> DispatchResultWithPostInfo { let was_heavy = do_calculation(input); if (was_heavy) else { // Return the actual weight consumed. Ok(Some(10_000).into()) } } ``` ## Custom Fees You can also define custom fee systems through custom weight functions or inclusion fee functions. ### Custom Weights Instead of using the default weight annotations, you can create a custom weight calculation type using the weights module. The custom weight calculation type must implement the following traits: - [`WeighData`](https://crates.parity.io/frame_support/weights/trait.WeighData.html) to determine the weight of the dispatch. - [`ClassifyDispatch`](https://crates.parity.io/frame_support/weights/trait.ClassifyDispatch.html) to determine the class of the dispatch. - [`PaysFee`](https://crates.parity.io/frame_support/weights/trait.PaysFee.html) to determine whether the sender of the dispatch pays fees. The Polkadot SDK then bundles the output information of the three traits into the [`DispatchInfo`](https://paritytech.github.io/polkadot-sdk/master/frame_support/dispatch/struct.DispatchInfo.html) struct and provides it by implementing the [`GetDispatchInfo`](https://docs.rs/frame-support/latest/frame_support/dispatch/trait.GetDispatchInfo.html) for all `Call` variants and opaque extrinsic types. This is used internally by the System and Executive modules. `ClassifyDispatch`, `WeighData`, and `PaysFee` are generic over T, which gets resolved into the tuple of all dispatch arguments except for the origin. The following example illustrates a struct that calculates the weight as `m * len(args)`, where `m` is a given multiplier and args is the concatenated tuple of all dispatch arguments. In this example, the dispatch class is `Operational` if the transaction has more than 100 bytes of length in arguments and will pay fees if the encoded length exceeds 10 bytes. ```rust struct LenWeight(u32); impl WeighData for LenWeight { fn weigh_data(&self, target: T) -> Weight { let multiplier = self.0; let encoded_len = target.encode().len() as u32; multiplier * encoded_len } } impl ClassifyDispatch for LenWeight { fn classify_dispatch(&self, target: T) -> DispatchClass { let encoded_len = target.encode().len() as u32; if encoded_len > 100 { DispatchClass::Operational } else { DispatchClass::Normal } } } impl PaysFee { fn pays_fee(&self, target: T) -> Pays { let encoded_len = target.encode().len() as u32; if encoded_len > 10 { Pays::Yes } else { Pays::No } } } ``` A weight calculator function can also be coerced to the final type of the argument instead of defining it as a vague type that can be encoded. The code would roughly look like this: ```rust struct CustomWeight; impl WeighData<(&u32, &u64)> for CustomWeight { fn weigh_data(&self, target: (&u32, &u64)) -> Weight { ... } } // given a dispatch: #[pallet::call] impl, I: 'static> Pallet { #[pallet::weight(CustomWeight)] fn foo(a: u32, b: u64) } ``` In this example, the `CustomWeight` can only be used in conjunction with a dispatch with a particular signature `(u32, u64)`, as opposed to `LenWeight`, which can be used with anything because there aren't any assumptions about ``. #### Custom Inclusion Fee The following example illustrates how to customize your inclusion fee. You must configure the appropriate associated types in the respective module. ```rust // Assume this is the balance type type Balance = u64; // Assume we want all the weights to have a `100 + 2 * w` conversion to fees struct CustomWeightToFee; impl WeightToFee for CustomWeightToFee { fn convert(w: Weight) -> Balance { let a = Balance::from(100); let b = Balance::from(2); let w = Balance::from(w); a + b * w } } parameter_types! { pub const ExtrinsicBaseWeight: Weight = 10_000_000; } impl frame_system::Config for Runtime { type ExtrinsicBaseWeight = ExtrinsicBaseWeight; } parameter_types! { pub const TransactionByteFee: Balance = 10; } impl transaction_payment::Config { type TransactionByteFee = TransactionByteFee; type WeightToFee = CustomWeightToFee; type FeeMultiplierUpdate = TargetedFeeAdjustment; } struct TargetedFeeAdjustment(sp_std::marker::PhantomData); impl> WeightToFee for TargetedFeeAdjustment { fn convert(multiplier: Fixed128) -> Fixed128 { // Don't change anything. Put any fee update info here. multiplier } } ``` ## Additional Resources You now know the weight system, how it affects transaction fee computation, and how to specify weights for your dispatchable calls. The next step is determining the correct weight for your dispatchable operations. You can use Substrate benchmarking functions and frame-benchmarking calls to test your functions with different parameters and empirically determine the proper weight in their worst-case scenarios. - [Benchmark](/parachains/customize-runtime/pallet-development/benchmark-pallet/) - [`SignedExtension`](https://paritytech.github.io/polkadot-sdk/master/sp_runtime/traits/trait.SignedExtension.html) - [Custom weights for the Example pallet](https://github.com/paritytech/polkadot-sdk/blob/polkadot-stable2603/substrate/frame/examples/basic/src/weights.rs) - [Polkadot wiki](https://wiki.polkadot.com/learn/learn-transactions/#fee-multiplier)