diff --git a/.ai/categories/polkadot-protocol.md b/.ai/categories/polkadot-protocol.md index 386b644d8..20d1518b9 100644 --- a/.ai/categories/polkadot-protocol.md +++ b/.ai/categories/polkadot-protocol.md @@ -162,234 +162,6 @@ It is the action of dividing bulk coretime into multiple contiguous regions. Thi Polkadot has dedicated cores assigned to provide core time on demand. These cores are excluded from the coretime sales and are reserved for on-demand parachains, which pay in DOT per block. ---- - -Page Title: Asset Hub - -- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-assets-and-smart-contracts.md -- Canonical (HTML): https://docs.polkadot.com/reference/polkadot-hub/assets-and-smart-contracts/ -- Summary: Learn about Asset Hub in Polkadot, managing on-chain assets, foreign asset integration, and using XCM for cross-chain asset transfers. - -# Asset Hub - -## Introduction - -The Asset Hub is a critical component in the Polkadot ecosystem, enabling the management of fungible and non-fungible assets across the network. Since the relay chain focuses on maintaining security and consensus without direct asset management, Asset Hub provides a streamlined platform for creating, managing, and using on-chain assets in a fee-efficient manner. This guide outlines the core features of Asset Hub, including how it handles asset operations, cross-chain transfers, and asset integration using XCM, as well as essential tools like [API Sidecar](#api-sidecar) and [`TxWrapper`](#txwrapper) for developers working with on-chain assets. - -## Assets Basics - -In the Polkadot ecosystem, the relay chain does not natively support additional assets beyond its native token (DOT for Polkadot, KSM for Kusama). The Asset Hub parachain on Polkadot and Kusama provides a fungible and non-fungible assets framework. Asset Hub allows developers and users to create, manage, and use assets across the ecosystem. - -Asset creators can use Asset Hub to track their asset issuance across multiple parachains and manage assets through operations such as minting, burning, and transferring. Projects that need a standardized method of handling on-chain assets will find this particularly useful. The fungible asset interface provided by Asset Hub closely resembles Ethereum's ERC-20 standard but is directly integrated into Polkadot's runtime, making it more efficient in terms of speed and transaction fees. - -Integrating with Asset Hub offers several key benefits, particularly for infrastructure providers and users: - -- **Support for non-native on-chain assets**: Asset Hub enables seamless asset creation and management, allowing projects to develop tokens or assets that can interact with the broader ecosystem. -- **Lower transaction fees**: Asset Hub offers significantly lower transaction costs—approximately one-tenth of the fees on the relay chain, providing cost-efficiency for regular operations. -- **Reduced deposit requirements**: Depositing assets in Asset Hub is more accessible, with deposit requirements that are around one one-hundredth of those on the relay chain. -- **Payment of transaction fees with non-native assets**: Users can pay transaction fees in assets other than the native token (DOT or KSM), offering more flexibility for developers and users. - -Assets created on the Asset Hub are stored as part of a map, where each asset has a unique ID that links to information about the asset, including details like: - -- The management team. -- The total supply. -- The number of accounts holding the asset. -- **Sufficiency for account existence**: Whether the asset alone is enough to maintain an account without a native token balance. -- The metadata of the asset, including its name, symbol, and the number of decimals for representation. - -Some assets can be regarded as sufficient to maintain an account's existence, meaning that users can create accounts on the network without needing a native token balance (i.e., no existential deposit required). Developers can also set minimum balances for their assets. If an account's balance drops below the minimum, the balance is considered dust and may be cleared. - -## Assets Pallet - -The Polkadot SDK's Assets pallet is a powerful module designated for creating and managing fungible asset classes with a fixed supply. It offers a secure and flexible way to issue, transfer, freeze, and destroy assets. The pallet supports various operations and includes permissioned and non-permissioned functions to cater to simple and advanced use cases. - -Visit the [Assets Pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank} for more in-depth information. - -### Key Features - -Key features of the Assets pallet include: - -- **Asset issuance**: Allows the creation of a new asset, where the total supply is assigned to the creator's account. -- **Asset transfer**: Enables transferring assets between accounts while maintaining a balance in both accounts. -- **Asset freezing**: Prevents transfers of a specific asset from one account, locking it from further transactions. -- **Asset destruction**: Allows accounts to burn or destroy their holdings, removing those assets from circulation. -- **Non-custodial transfers**: A non-custodial mechanism to enable one account to approve a transfer of assets on behalf of another. - -### Main Functions - -The Assets pallet provides a broad interface for managing fungible assets. Some of the main dispatchable functions include: - -- **`create()`**: Create a new asset class by placing a deposit, applicable when asset creation is permissionless. -- **`issue()`**: Mint a fixed supply of a new asset and assign it to the creator's account. -- **`transfer()`**: Transfer a specified amount of an asset between two accounts. -- **`approve_transfer()`**: Approve a non-custodial transfer, allowing a third party to move assets between accounts. -- **`destroy()`**: Destroy an entire asset class, removing it permanently from the chain. -- **`freeze()` and `thaw()`**: Administrators or privileged users can lock or unlock assets from being transferred. - -For a full list of dispatchable and privileged functions, see the [dispatchables Rust docs](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/enum.Call.html){target=\_blank}. - -### Querying Functions - -The Assets pallet exposes several key querying functions that developers can interact with programmatically. These functions allow you to query asset information and perform operations essential for managing assets across accounts. The two main querying functions are: - -- **`balance(asset_id, account)`**: Retrieves the balance of a given asset for a specified account. Useful for checking the holdings of an asset class across different accounts. - -- **`total_supply(asset_id)`**: Returns the total supply of the asset identified by `asset_id`. Allows users to verify how much of the asset exists on-chain. - -In addition to these basic functions, other utility functions are available for querying asset metadata and performing asset transfers. You can view the complete list of querying functions in the [Struct Pallet Rust docs](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/struct.Pallet.html){target=\_blank}. - -### Permission Models and Roles - -The Assets pallet incorporates a robust permission model, enabling control over who can perform specific operations like minting, transferring, or freezing assets. The key roles within the permission model are: - -- **Admin**: Can freeze (preventing transfers) and forcibly transfer assets between accounts. Admins also have the power to reduce the balance of an asset class across arbitrary accounts. They manage the more sensitive and administrative aspects of the asset class. -- **Issuer**: Responsible for minting new tokens. When new assets are created, the Issuer is the account that controls their distribution to other accounts. -- **Freezer**: Can lock the transfer of assets from an account, preventing the account holder from moving their balance. This function is useful for freezing accounts involved in disputes or fraud. -- **Owner**: Has overarching control, including destroying an entire asset class. Owners can also set or update the Issuer, Freezer, and Admin roles. - -These permissions provide fine-grained control over assets, enabling developers and asset managers to ensure secure, controlled operations. Each of these roles is crucial for managing asset lifecycles and ensuring that assets are used appropriately across the network. - -### Asset Freezing - -The Assets pallet allows you to freeze assets. This feature prevents transfers or spending from a specific account, effectively locking the balance of an asset class until it is explicitly unfrozen. Asset freezing is beneficial when assets are restricted due to security concerns or disputes. - -Freezing assets is controlled by the Freezer role, as mentioned earlier. Only the account with the Freezer privilege can perform these operations. Here are the key freezing functions: - -- **`freeze(asset_id, account)`**: Locks the specified asset of the account. While the asset is frozen, no transfers can be made from the frozen account. -- **`thaw(asset_id, account)`**: Corresponding function for unfreezing, allowing the asset to be transferred again. - -This approach enables secure and flexible asset management, providing administrators the tools to control asset movement in special circumstances. - -### Non-Custodial Transfers (Approval API) - -The Assets pallet also supports non-custodial transfers through the Approval API. This feature allows one account to approve another account to transfer a specific amount of its assets to a third-party recipient without granting full control over the account's balance. Non-custodial transfers enable secure transactions where trust is required between multiple parties. - -Here's a brief overview of the key functions for non-custodial asset transfers: - -- **`approve_transfer(asset_id, delegate, amount)`**: Approves a delegate to transfer up to a certain amount of the asset on behalf of the original account holder. -- **`cancel_approval(asset_id, delegate)`**: Cancels a previous approval for the delegate. Once canceled, the delegate no longer has permission to transfer the approved amount. -- **`transfer_approved(asset_id, owner, recipient, amount)`**: Executes the approved asset transfer from the owner’s account to the recipient. The delegate account can call this function once approval is granted. - -These delegated operations make it easier to manage multi-step transactions and dApps that require complex asset flows between participants. - -## Foreign Assets - -Foreign assets in Asset Hub refer to assets originating from external blockchains or parachains that are registered in the Asset Hub. These assets are typically native tokens from other parachains within the Polkadot ecosystem or bridged tokens from external blockchains such as Ethereum. - -Once a foreign asset is registered in the Asset Hub by its originating blockchain's root origin, users are able to send these tokens to the Asset Hub and interact with them as they would any other asset within the Polkadot ecosystem. - -### Handling Foreign Assets - -The Foreign Assets pallet, an instance of the Assets pallet, manages these assets. Since foreign assets are integrated into the same interface as native assets, developers can use the same functionalities, such as transferring and querying balances. However, there are important distinctions when dealing with foreign assets. - -- **Asset identifier**: Unlike native assets, foreign assets are identified using an XCM Multilocation rather than a simple numeric `AssetId`. This multilocation identifier represents the cross-chain location of the asset and provides a standardized way to reference it across different parachains and relay chains. - -- **Transfers**: Once registered in the Asset Hub, foreign assets can be transferred between accounts, just like native assets. Users can also send these assets back to their originating blockchain if supported by the relevant cross-chain messaging mechanisms. - -## Integration - -Asset Hub supports a variety of integration tools that make it easy for developers to manage assets and interact with the blockchain in their applications. The tools and libraries provided by Parity Technologies enable streamlined operations, such as querying asset information, building transactions, and monitoring cross-chain asset transfers. - -Developers can integrate Asset Hub into their projects using these core tools: - -### API Sidecar - -[API Sidecar](https://github.com/paritytech/substrate-api-sidecar){target=\_blank} is a RESTful service that can be deployed alongside Polkadot and Kusama nodes. It provides endpoints to retrieve real-time blockchain data, including asset information. When used with Asset Hub, Sidecar allows querying: - -- **Asset look-ups**: Retrieve specific assets using `AssetId`. -- **Asset balances**: View the balance of a particular asset on Asset Hub. - -Public instances of API Sidecar connected to Asset Hub are available, such as: - -- [Polkadot Asset Hub Sidecar](https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/){target=\_blank} -- [Kusama Asset Hub Sidecar](https://kusama-asset-hub-public-sidecar.parity-chains.parity.io/){target=\_blank} - -These public instances are primarily for ad-hoc testing and quick checks. - -### TxWrapper - -[`TxWrapper`](https://github.com/paritytech/txwrapper-core){target=\_blank} is a library that simplifies constructing and signing transactions for Polkadot SDK-based chains, including Polkadot and Kusama. This tool includes support for working with Asset Hub, enabling developers to: - -- Construct offline transactions. -- Leverage asset-specific functions such as minting, burning, and transferring assets. - -`TxWrapper` provides the flexibility needed to integrate asset operations into custom applications while maintaining the security and efficiency of Polkadot's transaction model. - - -### Parachain Node - -To fully leverage the Asset Hub's functionality, developers will need to run a system parachain node. Setting up an Asset Hub node allows users to interact with the parachain in real time, syncing data and participating in the broader Polkadot ecosystem. Guidelines for setting up an [Asset Hub node](https://github.com/paritytech/polkadot-sdk/tree/polkadot-stable2506-2/cumulus#asset-hub-){target=\_blank} are available in the Parity documentation. - -Using these integration tools, developers can manage assets seamlessly and integrate Asset Hub functionality into their applications, leveraging Polkadot's powerful infrastructure. - -## XCM Transfer Monitoring - -Since Asset Hub facilitates cross-chain asset transfers across the Polkadot ecosystem, XCM transfer monitoring becomes an essential practice for developers and infrastructure providers. This section outlines how to monitor the cross-chain movement of assets between parachains, the relay chain, and other systems. - -### Monitor XCM Deposits - -As assets move between chains, tracking the cross-chain transfers in real time is crucial. Whether assets are transferred via a teleport from system parachains or through a reserve-backed transfer from any other parachain, each transfer emits a relevant event (such as the `balances.minted` event). - -To ensure accurate monitoring of these events: - -- **Track XCM deposits**: Query every new block created in the relay chain or Asset Hub, loop through the events array, and filter for any `balances.minted` events which confirm the asset was successfully transferred to the account. -- **Track event origins**: Each `balances.minted` event points to a specific address. By monitoring this, service providers can verify that assets have arrived in the correct account. - -### Track XCM Information Back to the Source - -While the `balances.minted` event confirms the arrival of assets, there may be instances where you need to trace the origin of the cross-chain message that triggered the event. In such cases, you can: - -1. Query the relevant chain at the block where the `balances.minted` event was emitted. -2. Look for a `messageQueue(Processed)` event within that block's initialization. This event contains a parameter (`Id`) that identifies the cross-chain message received by the relay chain or Asset Hub. You can use this `Id` to trace the message back to its origin chain, offering full visibility of the asset transfer's journey. - -### Practical Monitoring Examples - -The preceding sections outline the process of monitoring XCM deposits to specific accounts and then tracing back the origin of these deposits. The process of tracking an XCM transfer and the specific events to monitor may vary based on the direction of the XCM message. Here are some examples to showcase the slight differences: - -- **Transfer from parachain to relay chain**: Track `parachainsystem(UpwardMessageSent)` on the parachain and `messagequeue(Processed)` on the relay chain. -- **Transfer from relay chain to parachain**: Track `xcmPallet(sent)` on the relay chain and `dmpqueue(ExecutedDownward)` on the parachain. -- **Transfer between parachains**: Track `xcmpqueue(XcmpMessageSent)` on the system parachain and `xcmpqueue(Success)` on the destination parachain. - -### Monitor for Failed XCM Transfers - -Sometimes, XCM transfers may fail due to liquidity or other errors. Failed transfers emit specific error events, which are key to resolving issues in asset transfers. Monitoring for these failure events helps catch issues before they affect asset balances. - -- **Relay chain to system parachain**: Look for the `dmpqueue(ExecutedDownward)` event on the parachain with an `Incomplete` outcome and an error type such as `UntrustedReserveLocation`. -- **Parachain to parachain**: Monitor for `xcmpqueue(Fail)` on the destination parachain with error types like `TooExpensive`. - -For detailed error management in XCM, see Gavin Wood's blog post on [XCM Execution and Error Management](https://polkadot.com/blog/xcm-part-three-execution-and-error-management/){target=\_blank}. - -## Where to Go Next - -
- -- Tutorial __Register a Local Asset__ - - --- - - Comprehensive guide to registering a local asset on the Asset Hub system parachain, including step-by-step instructions. - - [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/register-local-asset/) - -- Tutorial __Register a Foreign Asset__ - - --- - - An in-depth guide to registering a foreign asset on the Asset Hub parachain, providing clear, step-by-step instructions. - - [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/register-foreign-asset/) - -- Tutorial __Convert Assets__ - - --- - - A guide detailing the step-by-step process of converting assets on Asset Hub, helping users efficiently navigate asset management on the platform. - - [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/convert-assets/) - -
- - --- Page Title: Asynchronous Backing @@ -5630,6 +5402,142 @@ You must contact specific registrars individually to request judgment. Each regi +--- + +Page Title: Polkadot Hub Assets + +- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-assets.md +- Canonical (HTML): https://docs.polkadot.com/reference/polkadot-hub/assets/ +- Summary: Learn about asset management on Polkadot Hub, including on-chain assets, foreign asset integration, and XCM for cross-chain asset transfers. + +# Assets on Polkadot Hub + +## Introduction + +Polkadot Hub is Polkadot’s system parachain that provides core functionality for the network, including issuing and managing on-chain assets. While the relay chain provides security, Polkadot Hub handles asset logic—minting, burning, transfers, and metadata—efficiently and cost-effectively. + +Polkadot Hub supports native assets issued on the parachain and foreign assets from other chains, both of which can move seamlessly across the network via XCM. + +This guide explains how assets are created, managed, and moved across chains, including key operations, roles, and the differences between native and foreign assets. + +## Why Use Polkadot Hub? + +Polkadot Hub provides a standardized framework for creating and managing fungible and non-fungible assets. Projects can issue tokens, manage supply, and transfer assets across parachains, extending the functionality of the Polkadot relay chain, which only supports its native token (DOT). + +**Key features**: + +- **Built-in asset operations**: Mint, burn, and transfer like ERC-20 on Ethereum, but native to Polkadot's runtime. +- **Custom asset creation**: Issue tokens or NFTs with configurable permissions and metadata. +- **Low fees**: Transactions cost roughly one-tenth of relay chain fees. +- **Lower deposits**: Minimal on-chain storage costs for asset data. +- **Pay fees in any asset**: Users don’t need DOT to transact; supported assets can cover fees. +- **Cross-chain ready**: Assets can be transferred to other parachains using XCM. + +## Types of Assets + +Polkadot Hub supports two types of assets: + +- **Native assets**: Tokens and NFTs issued directly on Polkadot Hub using the Assets pallet. These assets benefit from the platform's custom features, such as configurable permissions and low fees +- **Foreign assets**: Tokens originating from other Polkadot parachains or external networks (like Ethereum, via bridges). Once registered on Polkadot Hub, they are treated similarly to native assets. + +## Asset Structure + +Each asset is identified by a unique ID and stores: + +- Asset administrators +- Total supply and holder count +- Minimum balance configuration +- Sufficiency–whether the asset can keep an account alive without DOT +- Metadata (name, symbol, decimals) + +If a balance falls below the configured minimum, called the [existential deposit](/reference/glossary/#existential-deposit){target=\_blank}, it may be removed as “dust.” This ensures efficient storage while giving developers control over asset economics. + +## How Native Assets Work + +Native assets on Polkadot Hub are created and managed via the Assets pallet from the Polkadot SDK. This pallet defines the runtime logic for issuing, configuring, and administering fungible assets with customizable permissions. + +It supports both permissioned and permissionless asset creation, enabling everything from simple user-issued tokens to governed assets controlled by teams or DAOs. + +For implementation details, see the [Assets Pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank}. + +### Asset Operations + +The Assets pallet provides both state-changing operations and read-only queries for full lifecycle management of assets. + +Core operations include: + +- **Asset issuance**: Create new assets and assign initial supply. +- **Transfers**: Move assets between accounts with balance tracking. +- **Burning**: Reduce total supply by destroying tokens. +- **Delegated transfers**: Approve transfers on behalf of another account without giving up custody. +- **Freezing and thawing**: Temporarily lock and unlock an account's balance. + +For a complete list of extrinsics, see the [`pallet-assets` dispatchable functions reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/enum.Call.html){target=\_blank}. + +Data queries make it possible to: + +- Check account balances and total supply. +- Retrieve asset metadata and configuration details. +- Inspect account and asset status on-chain. + +For a full list of queries, see the [Pallet reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/struct.Pallet.html){target=\_blank}. + +### Roles and Permissions + +The Assets pallet uses role-based permissions to control who can manage different parts of an asset’s lifecycle: + +- **Owner**: Overarching control, including destroying an asset class; can set or update Issuer, Freezer, and Admin roles. +- **Admin**: Can freeze assets and forcibly transfer balances between accounts. Admins can also reduce the balance of an asset class across arbitrary accounts. +- **Issuer**: Responsible for minting new tokens. When new assets are created, the Issuer is the account that controls their distribution to other accounts. +- **Freezer**: Can lock the transfer of assets from an account, preventing the account holder from moving their balance. + +These roles allow projects to enforce governance and security policies around their assets. + +### Freezing Assets + +Assets can be temporarily locked to prevent transfers from specific accounts. This is useful for dispute resolution, fraud prevention, or compliance controls. + +**How it works**: + +- Only authorized parties can freeze or unfreeze (thaw) assets. +- Freezing pauses the movement of the asset without burning or removing it. +- Once thawed, the asset can be transferred normally. + +Freezing provides a safe way to control asset flow while maintaining full ownership. + +**Key functions**: `freeze` and `thaw`. + +### Delegated Transfers + +Polkadot Hub supports delegated asset transfers, allowing one account to authorize another to move a limited amount of its assets—without giving up full control. This is useful for escrow logic, automated payments, and multi-party applications. + +**How it works**: + +- An account can grant permission to another account to transfer a specific amount of its assets. +- Permissions can be revoked at any time, preventing further transfers. +- Authorized accounts can execute transfers on behalf of the original owner within the approved limits. + +Delegated transfers simplify multi-step transactions and enable complex asset flows. + +**Key functions**: `approve_transfer`, `cancel_approval`, and `transfer_approved`. + +## How Foreign Assets Work + +Foreign assets are assets originating from other chains and are managed on Polkadot Hub via an instance of the Assets pallet that is configured specifically for foreign assets. It enables transfers, balance checks, and other standard asset operations, while handling foreign-asset specifics such as: + +- **Asset identifiers**: Foreign assets use an XCM multilocation as their identifier, rather than a numeric AssetId. This ensures assets from different chains can be referenced and moved safely across parachains. + +- **Transfers**: Once registered on Polkadot Hub, foreign assets can be transferred between accounts just like native assets. If supported, they can also be returned to their original blockchain using cross-chain messaging. + +This unified interface makes it easy for dApps to handle both native and cross-chain assets. + +## Moving Assets Across Chains + +Polkadot Hub enables assets to move safely between parachains and the relay chain using XCM (Cross-Consensus Messaging). XCM ensures assets can move securely between chains while preserving ownership and traceability + +To learn more about asset transfers with XCM, please refer to the [Introduction to XCM](/parachains/interoperability/get-started/) page. + + --- Page Title: Polkadot Hub Overview @@ -5749,6 +5657,73 @@ Consider the following resources to explore specific Hub functionality. +--- + +Page Title: Polkadot Hub Smart Contracts + +- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-smart-contracts.md +- Canonical (HTML): https://docs.polkadot.com/reference/polkadot-hub/smart-contracts/ +- Summary: Learn how Polkadot Hub supports smart contracts through the REVM, a Rust-based Ethereum Virtual Machine compatible runtime. + +# Smart Contracts on Polkadot Hub + +## Introduction + +Polkadot Hub enables developers to deploy and interact with Solidity contracts through REVM, a high-performance, Rust-based Ethereum Virtual Machine implementation. Polkadot-native precompiles bring Ethereum compatibility to Polkadot Hub, letting teams use familiar Solidity tooling, integrate with on-chain features like governance and XCM, and take advantage of cross-chain interoperability. + +For projects that require maximum computational performance, Polkadot Hub also supports PolkaVM (PVM), a native RISC-V execution engine. PVM is optional and designed for high-throughput, performance-intensive smart contracts. + +### REVM Smart Contracts + +[REVM](https://github.com/bluealloy/revm){target=_blank} brings full EVM compatibility to Polkadot Hub through a fast, memory-safe Rust implementation of the Ethereum Virtual Machine. Unlike PolkaVM, which compiles contracts to RISC-V for native execution, REVM executes standard Ethereum bytecode directly—making it ideal for teams who want to migrate existing Solidity projects to Polkadot with minimal changes. + +With REVM, developers can: + +- Deploy existing Solidity contracts without rewriting them. +- Use familiar Ethereum tooling like Hardhat, Foundry, Remix, and MetaMask. +- Interact with other parachains and on-chain assets using XCM and Polkadot Hub features. + +REVM builds on Rust’s safety guarantees and performance optimizations while retaining full opcode compatibility with the EVM. + +Ethereum-native developers can use Polkadot-native precompiles to access Polkadot features—such as governance, treasury, multisig, and XCM—within a unified, interoperable runtime environment. + +### PVM Smart Contracts + +PVM is Polkadot Hub’s native, high-performance smart contract engine. Instead of emulating EVM bytecode, it runs contracts compiled to a [RISC-V](https://en.wikipedia.org/wiki/RISC-V){target=_blank} instruction set, unlocking higher performance and parallel execution while staying friendly to Ethereum-style development. + +With PVM, developers can: + +- Write Solidity contracts and use familiar tooling (e.g., Hardhat, Foundry) targeting PVM +- Benefit from fast, predictable execution with carefully metered gas/weight. +- Access detailed observability through Substrate events and contract logs for indexing and debugging. + +PolkaVM delivers maximum performance for computationally intensive contracts, offering a native, high-throughput option for Ethereum-style developers on Polkadot Hub. + +!!! smartcontract "PolkaVM Preview Release" + PolkaVM smart contracts with Ethereum compatibility are in **early-stage development and may be unstable or incomplete**. +## Where to Go Next + +
+ +- Guide __Deploy a Basic Contract__ + + --- + + Learn step-by-step how to deploy a basic Solidity smart contract to Polkadot Hub. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/smart-contracts/deploy-basic/basic-remix/) + +- Guide __Explore Development Environments__ + + --- + + Check out the development environments you can use to build, test, and deploy smart contracts. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/local-dev-node/) + +
+ + --- Page Title: Polkadot SDK Accounts diff --git a/.ai/pages/reference-polkadot-hub-assets-and-smart-contracts.md b/.ai/pages/reference-polkadot-hub-assets-and-smart-contracts.md deleted file mode 100644 index 4773cc0df..000000000 --- a/.ai/pages/reference-polkadot-hub-assets-and-smart-contracts.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -title: Asset Hub -description: Learn about Asset Hub in Polkadot, managing on-chain assets, foreign asset integration, and using XCM for cross-chain asset transfers. -categories: Polkadot Protocol -url: https://docs.polkadot.com/reference/polkadot-hub/assets-and-smart-contracts/ ---- - -# Asset Hub - -## Introduction - -The Asset Hub is a critical component in the Polkadot ecosystem, enabling the management of fungible and non-fungible assets across the network. Since the relay chain focuses on maintaining security and consensus without direct asset management, Asset Hub provides a streamlined platform for creating, managing, and using on-chain assets in a fee-efficient manner. This guide outlines the core features of Asset Hub, including how it handles asset operations, cross-chain transfers, and asset integration using XCM, as well as essential tools like [API Sidecar](#api-sidecar) and [`TxWrapper`](#txwrapper) for developers working with on-chain assets. - -## Assets Basics - -In the Polkadot ecosystem, the relay chain does not natively support additional assets beyond its native token (DOT for Polkadot, KSM for Kusama). The Asset Hub parachain on Polkadot and Kusama provides a fungible and non-fungible assets framework. Asset Hub allows developers and users to create, manage, and use assets across the ecosystem. - -Asset creators can use Asset Hub to track their asset issuance across multiple parachains and manage assets through operations such as minting, burning, and transferring. Projects that need a standardized method of handling on-chain assets will find this particularly useful. The fungible asset interface provided by Asset Hub closely resembles Ethereum's ERC-20 standard but is directly integrated into Polkadot's runtime, making it more efficient in terms of speed and transaction fees. - -Integrating with Asset Hub offers several key benefits, particularly for infrastructure providers and users: - -- **Support for non-native on-chain assets**: Asset Hub enables seamless asset creation and management, allowing projects to develop tokens or assets that can interact with the broader ecosystem. -- **Lower transaction fees**: Asset Hub offers significantly lower transaction costs—approximately one-tenth of the fees on the relay chain, providing cost-efficiency for regular operations. -- **Reduced deposit requirements**: Depositing assets in Asset Hub is more accessible, with deposit requirements that are around one one-hundredth of those on the relay chain. -- **Payment of transaction fees with non-native assets**: Users can pay transaction fees in assets other than the native token (DOT or KSM), offering more flexibility for developers and users. - -Assets created on the Asset Hub are stored as part of a map, where each asset has a unique ID that links to information about the asset, including details like: - -- The management team. -- The total supply. -- The number of accounts holding the asset. -- **Sufficiency for account existence**: Whether the asset alone is enough to maintain an account without a native token balance. -- The metadata of the asset, including its name, symbol, and the number of decimals for representation. - -Some assets can be regarded as sufficient to maintain an account's existence, meaning that users can create accounts on the network without needing a native token balance (i.e., no existential deposit required). Developers can also set minimum balances for their assets. If an account's balance drops below the minimum, the balance is considered dust and may be cleared. - -## Assets Pallet - -The Polkadot SDK's Assets pallet is a powerful module designated for creating and managing fungible asset classes with a fixed supply. It offers a secure and flexible way to issue, transfer, freeze, and destroy assets. The pallet supports various operations and includes permissioned and non-permissioned functions to cater to simple and advanced use cases. - -Visit the [Assets Pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank} for more in-depth information. - -### Key Features - -Key features of the Assets pallet include: - -- **Asset issuance**: Allows the creation of a new asset, where the total supply is assigned to the creator's account. -- **Asset transfer**: Enables transferring assets between accounts while maintaining a balance in both accounts. -- **Asset freezing**: Prevents transfers of a specific asset from one account, locking it from further transactions. -- **Asset destruction**: Allows accounts to burn or destroy their holdings, removing those assets from circulation. -- **Non-custodial transfers**: A non-custodial mechanism to enable one account to approve a transfer of assets on behalf of another. - -### Main Functions - -The Assets pallet provides a broad interface for managing fungible assets. Some of the main dispatchable functions include: - -- **`create()`**: Create a new asset class by placing a deposit, applicable when asset creation is permissionless. -- **`issue()`**: Mint a fixed supply of a new asset and assign it to the creator's account. -- **`transfer()`**: Transfer a specified amount of an asset between two accounts. -- **`approve_transfer()`**: Approve a non-custodial transfer, allowing a third party to move assets between accounts. -- **`destroy()`**: Destroy an entire asset class, removing it permanently from the chain. -- **`freeze()` and `thaw()`**: Administrators or privileged users can lock or unlock assets from being transferred. - -For a full list of dispatchable and privileged functions, see the [dispatchables Rust docs](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/enum.Call.html){target=\_blank}. - -### Querying Functions - -The Assets pallet exposes several key querying functions that developers can interact with programmatically. These functions allow you to query asset information and perform operations essential for managing assets across accounts. The two main querying functions are: - -- **`balance(asset_id, account)`**: Retrieves the balance of a given asset for a specified account. Useful for checking the holdings of an asset class across different accounts. - -- **`total_supply(asset_id)`**: Returns the total supply of the asset identified by `asset_id`. Allows users to verify how much of the asset exists on-chain. - -In addition to these basic functions, other utility functions are available for querying asset metadata and performing asset transfers. You can view the complete list of querying functions in the [Struct Pallet Rust docs](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/struct.Pallet.html){target=\_blank}. - -### Permission Models and Roles - -The Assets pallet incorporates a robust permission model, enabling control over who can perform specific operations like minting, transferring, or freezing assets. The key roles within the permission model are: - -- **Admin**: Can freeze (preventing transfers) and forcibly transfer assets between accounts. Admins also have the power to reduce the balance of an asset class across arbitrary accounts. They manage the more sensitive and administrative aspects of the asset class. -- **Issuer**: Responsible for minting new tokens. When new assets are created, the Issuer is the account that controls their distribution to other accounts. -- **Freezer**: Can lock the transfer of assets from an account, preventing the account holder from moving their balance. This function is useful for freezing accounts involved in disputes or fraud. -- **Owner**: Has overarching control, including destroying an entire asset class. Owners can also set or update the Issuer, Freezer, and Admin roles. - -These permissions provide fine-grained control over assets, enabling developers and asset managers to ensure secure, controlled operations. Each of these roles is crucial for managing asset lifecycles and ensuring that assets are used appropriately across the network. - -### Asset Freezing - -The Assets pallet allows you to freeze assets. This feature prevents transfers or spending from a specific account, effectively locking the balance of an asset class until it is explicitly unfrozen. Asset freezing is beneficial when assets are restricted due to security concerns or disputes. - -Freezing assets is controlled by the Freezer role, as mentioned earlier. Only the account with the Freezer privilege can perform these operations. Here are the key freezing functions: - -- **`freeze(asset_id, account)`**: Locks the specified asset of the account. While the asset is frozen, no transfers can be made from the frozen account. -- **`thaw(asset_id, account)`**: Corresponding function for unfreezing, allowing the asset to be transferred again. - -This approach enables secure and flexible asset management, providing administrators the tools to control asset movement in special circumstances. - -### Non-Custodial Transfers (Approval API) - -The Assets pallet also supports non-custodial transfers through the Approval API. This feature allows one account to approve another account to transfer a specific amount of its assets to a third-party recipient without granting full control over the account's balance. Non-custodial transfers enable secure transactions where trust is required between multiple parties. - -Here's a brief overview of the key functions for non-custodial asset transfers: - -- **`approve_transfer(asset_id, delegate, amount)`**: Approves a delegate to transfer up to a certain amount of the asset on behalf of the original account holder. -- **`cancel_approval(asset_id, delegate)`**: Cancels a previous approval for the delegate. Once canceled, the delegate no longer has permission to transfer the approved amount. -- **`transfer_approved(asset_id, owner, recipient, amount)`**: Executes the approved asset transfer from the owner’s account to the recipient. The delegate account can call this function once approval is granted. - -These delegated operations make it easier to manage multi-step transactions and dApps that require complex asset flows between participants. - -## Foreign Assets - -Foreign assets in Asset Hub refer to assets originating from external blockchains or parachains that are registered in the Asset Hub. These assets are typically native tokens from other parachains within the Polkadot ecosystem or bridged tokens from external blockchains such as Ethereum. - -Once a foreign asset is registered in the Asset Hub by its originating blockchain's root origin, users are able to send these tokens to the Asset Hub and interact with them as they would any other asset within the Polkadot ecosystem. - -### Handling Foreign Assets - -The Foreign Assets pallet, an instance of the Assets pallet, manages these assets. Since foreign assets are integrated into the same interface as native assets, developers can use the same functionalities, such as transferring and querying balances. However, there are important distinctions when dealing with foreign assets. - -- **Asset identifier**: Unlike native assets, foreign assets are identified using an XCM Multilocation rather than a simple numeric `AssetId`. This multilocation identifier represents the cross-chain location of the asset and provides a standardized way to reference it across different parachains and relay chains. - -- **Transfers**: Once registered in the Asset Hub, foreign assets can be transferred between accounts, just like native assets. Users can also send these assets back to their originating blockchain if supported by the relevant cross-chain messaging mechanisms. - -## Integration - -Asset Hub supports a variety of integration tools that make it easy for developers to manage assets and interact with the blockchain in their applications. The tools and libraries provided by Parity Technologies enable streamlined operations, such as querying asset information, building transactions, and monitoring cross-chain asset transfers. - -Developers can integrate Asset Hub into their projects using these core tools: - -### API Sidecar - -[API Sidecar](https://github.com/paritytech/substrate-api-sidecar){target=\_blank} is a RESTful service that can be deployed alongside Polkadot and Kusama nodes. It provides endpoints to retrieve real-time blockchain data, including asset information. When used with Asset Hub, Sidecar allows querying: - -- **Asset look-ups**: Retrieve specific assets using `AssetId`. -- **Asset balances**: View the balance of a particular asset on Asset Hub. - -Public instances of API Sidecar connected to Asset Hub are available, such as: - -- [Polkadot Asset Hub Sidecar](https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/){target=\_blank} -- [Kusama Asset Hub Sidecar](https://kusama-asset-hub-public-sidecar.parity-chains.parity.io/){target=\_blank} - -These public instances are primarily for ad-hoc testing and quick checks. - -### TxWrapper - -[`TxWrapper`](https://github.com/paritytech/txwrapper-core){target=\_blank} is a library that simplifies constructing and signing transactions for Polkadot SDK-based chains, including Polkadot and Kusama. This tool includes support for working with Asset Hub, enabling developers to: - -- Construct offline transactions. -- Leverage asset-specific functions such as minting, burning, and transferring assets. - -`TxWrapper` provides the flexibility needed to integrate asset operations into custom applications while maintaining the security and efficiency of Polkadot's transaction model. - - -### Parachain Node - -To fully leverage the Asset Hub's functionality, developers will need to run a system parachain node. Setting up an Asset Hub node allows users to interact with the parachain in real time, syncing data and participating in the broader Polkadot ecosystem. Guidelines for setting up an [Asset Hub node](https://github.com/paritytech/polkadot-sdk/tree/polkadot-stable2506-2/cumulus#asset-hub-){target=\_blank} are available in the Parity documentation. - -Using these integration tools, developers can manage assets seamlessly and integrate Asset Hub functionality into their applications, leveraging Polkadot's powerful infrastructure. - -## XCM Transfer Monitoring - -Since Asset Hub facilitates cross-chain asset transfers across the Polkadot ecosystem, XCM transfer monitoring becomes an essential practice for developers and infrastructure providers. This section outlines how to monitor the cross-chain movement of assets between parachains, the relay chain, and other systems. - -### Monitor XCM Deposits - -As assets move between chains, tracking the cross-chain transfers in real time is crucial. Whether assets are transferred via a teleport from system parachains or through a reserve-backed transfer from any other parachain, each transfer emits a relevant event (such as the `balances.minted` event). - -To ensure accurate monitoring of these events: - -- **Track XCM deposits**: Query every new block created in the relay chain or Asset Hub, loop through the events array, and filter for any `balances.minted` events which confirm the asset was successfully transferred to the account. -- **Track event origins**: Each `balances.minted` event points to a specific address. By monitoring this, service providers can verify that assets have arrived in the correct account. - -### Track XCM Information Back to the Source - -While the `balances.minted` event confirms the arrival of assets, there may be instances where you need to trace the origin of the cross-chain message that triggered the event. In such cases, you can: - -1. Query the relevant chain at the block where the `balances.minted` event was emitted. -2. Look for a `messageQueue(Processed)` event within that block's initialization. This event contains a parameter (`Id`) that identifies the cross-chain message received by the relay chain or Asset Hub. You can use this `Id` to trace the message back to its origin chain, offering full visibility of the asset transfer's journey. - -### Practical Monitoring Examples - -The preceding sections outline the process of monitoring XCM deposits to specific accounts and then tracing back the origin of these deposits. The process of tracking an XCM transfer and the specific events to monitor may vary based on the direction of the XCM message. Here are some examples to showcase the slight differences: - -- **Transfer from parachain to relay chain**: Track `parachainsystem(UpwardMessageSent)` on the parachain and `messagequeue(Processed)` on the relay chain. -- **Transfer from relay chain to parachain**: Track `xcmPallet(sent)` on the relay chain and `dmpqueue(ExecutedDownward)` on the parachain. -- **Transfer between parachains**: Track `xcmpqueue(XcmpMessageSent)` on the system parachain and `xcmpqueue(Success)` on the destination parachain. - -### Monitor for Failed XCM Transfers - -Sometimes, XCM transfers may fail due to liquidity or other errors. Failed transfers emit specific error events, which are key to resolving issues in asset transfers. Monitoring for these failure events helps catch issues before they affect asset balances. - -- **Relay chain to system parachain**: Look for the `dmpqueue(ExecutedDownward)` event on the parachain with an `Incomplete` outcome and an error type such as `UntrustedReserveLocation`. -- **Parachain to parachain**: Monitor for `xcmpqueue(Fail)` on the destination parachain with error types like `TooExpensive`. - -For detailed error management in XCM, see Gavin Wood's blog post on [XCM Execution and Error Management](https://polkadot.com/blog/xcm-part-three-execution-and-error-management/){target=\_blank}. - -## Where to Go Next - -
- -- Tutorial __Register a Local Asset__ - - --- - - Comprehensive guide to registering a local asset on the Asset Hub system parachain, including step-by-step instructions. - - [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/register-local-asset/) - -- Tutorial __Register a Foreign Asset__ - - --- - - An in-depth guide to registering a foreign asset on the Asset Hub parachain, providing clear, step-by-step instructions. - - [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/register-foreign-asset/) - -- Tutorial __Convert Assets__ - - --- - - A guide detailing the step-by-step process of converting assets on Asset Hub, helping users efficiently navigate asset management on the platform. - - [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/convert-assets/) - -
diff --git a/.ai/pages/reference-polkadot-hub-assets.md b/.ai/pages/reference-polkadot-hub-assets.md new file mode 100644 index 000000000..9dab561c6 --- /dev/null +++ b/.ai/pages/reference-polkadot-hub-assets.md @@ -0,0 +1,133 @@ +--- +title: Polkadot Hub Assets +description: Learn about asset management on Polkadot Hub, including on-chain assets, foreign asset integration, and XCM for cross-chain asset transfers. +categories: Polkadot Protocol +url: https://docs.polkadot.com/reference/polkadot-hub/assets/ +--- + +# Assets on Polkadot Hub + +## Introduction + +Polkadot Hub is Polkadot’s system parachain that provides core functionality for the network, including issuing and managing on-chain assets. While the relay chain provides security, Polkadot Hub handles asset logic—minting, burning, transfers, and metadata—efficiently and cost-effectively. + +Polkadot Hub supports native assets issued on the parachain and foreign assets from other chains, both of which can move seamlessly across the network via XCM. + +This guide explains how assets are created, managed, and moved across chains, including key operations, roles, and the differences between native and foreign assets. + +## Why Use Polkadot Hub? + +Polkadot Hub provides a standardized framework for creating and managing fungible and non-fungible assets. Projects can issue tokens, manage supply, and transfer assets across parachains, extending the functionality of the Polkadot relay chain, which only supports its native token (DOT). + +**Key features**: + +- **Built-in asset operations**: Mint, burn, and transfer like ERC-20 on Ethereum, but native to Polkadot's runtime. +- **Custom asset creation**: Issue tokens or NFTs with configurable permissions and metadata. +- **Low fees**: Transactions cost roughly one-tenth of relay chain fees. +- **Lower deposits**: Minimal on-chain storage costs for asset data. +- **Pay fees in any asset**: Users don’t need DOT to transact; supported assets can cover fees. +- **Cross-chain ready**: Assets can be transferred to other parachains using XCM. + +## Types of Assets + +Polkadot Hub supports two types of assets: + +- **Native assets**: Tokens and NFTs issued directly on Polkadot Hub using the Assets pallet. These assets benefit from the platform's custom features, such as configurable permissions and low fees +- **Foreign assets**: Tokens originating from other Polkadot parachains or external networks (like Ethereum, via bridges). Once registered on Polkadot Hub, they are treated similarly to native assets. + +## Asset Structure + +Each asset is identified by a unique ID and stores: + +- Asset administrators +- Total supply and holder count +- Minimum balance configuration +- Sufficiency–whether the asset can keep an account alive without DOT +- Metadata (name, symbol, decimals) + +If a balance falls below the configured minimum, called the [existential deposit](/reference/glossary/#existential-deposit){target=\_blank}, it may be removed as “dust.” This ensures efficient storage while giving developers control over asset economics. + +## How Native Assets Work + +Native assets on Polkadot Hub are created and managed via the Assets pallet from the Polkadot SDK. This pallet defines the runtime logic for issuing, configuring, and administering fungible assets with customizable permissions. + +It supports both permissioned and permissionless asset creation, enabling everything from simple user-issued tokens to governed assets controlled by teams or DAOs. + +For implementation details, see the [Assets Pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank}. + +### Asset Operations + +The Assets pallet provides both state-changing operations and read-only queries for full lifecycle management of assets. + +Core operations include: + +- **Asset issuance**: Create new assets and assign initial supply. +- **Transfers**: Move assets between accounts with balance tracking. +- **Burning**: Reduce total supply by destroying tokens. +- **Delegated transfers**: Approve transfers on behalf of another account without giving up custody. +- **Freezing and thawing**: Temporarily lock and unlock an account's balance. + +For a complete list of extrinsics, see the [`pallet-assets` dispatchable functions reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/enum.Call.html){target=\_blank}. + +Data queries make it possible to: + +- Check account balances and total supply. +- Retrieve asset metadata and configuration details. +- Inspect account and asset status on-chain. + +For a full list of queries, see the [Pallet reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/struct.Pallet.html){target=\_blank}. + +### Roles and Permissions + +The Assets pallet uses role-based permissions to control who can manage different parts of an asset’s lifecycle: + +- **Owner**: Overarching control, including destroying an asset class; can set or update Issuer, Freezer, and Admin roles. +- **Admin**: Can freeze assets and forcibly transfer balances between accounts. Admins can also reduce the balance of an asset class across arbitrary accounts. +- **Issuer**: Responsible for minting new tokens. When new assets are created, the Issuer is the account that controls their distribution to other accounts. +- **Freezer**: Can lock the transfer of assets from an account, preventing the account holder from moving their balance. + +These roles allow projects to enforce governance and security policies around their assets. + +### Freezing Assets + +Assets can be temporarily locked to prevent transfers from specific accounts. This is useful for dispute resolution, fraud prevention, or compliance controls. + +**How it works**: + +- Only authorized parties can freeze or unfreeze (thaw) assets. +- Freezing pauses the movement of the asset without burning or removing it. +- Once thawed, the asset can be transferred normally. + +Freezing provides a safe way to control asset flow while maintaining full ownership. + +**Key functions**: `freeze` and `thaw`. + +### Delegated Transfers + +Polkadot Hub supports delegated asset transfers, allowing one account to authorize another to move a limited amount of its assets—without giving up full control. This is useful for escrow logic, automated payments, and multi-party applications. + +**How it works**: + +- An account can grant permission to another account to transfer a specific amount of its assets. +- Permissions can be revoked at any time, preventing further transfers. +- Authorized accounts can execute transfers on behalf of the original owner within the approved limits. + +Delegated transfers simplify multi-step transactions and enable complex asset flows. + +**Key functions**: `approve_transfer`, `cancel_approval`, and `transfer_approved`. + +## How Foreign Assets Work + +Foreign assets are assets originating from other chains and are managed on Polkadot Hub via an instance of the Assets pallet that is configured specifically for foreign assets. It enables transfers, balance checks, and other standard asset operations, while handling foreign-asset specifics such as: + +- **Asset identifiers**: Foreign assets use an XCM multilocation as their identifier, rather than a numeric AssetId. This ensures assets from different chains can be referenced and moved safely across parachains. + +- **Transfers**: Once registered on Polkadot Hub, foreign assets can be transferred between accounts just like native assets. If supported, they can also be returned to their original blockchain using cross-chain messaging. + +This unified interface makes it easy for dApps to handle both native and cross-chain assets. + +## Moving Assets Across Chains + +Polkadot Hub enables assets to move safely between parachains and the relay chain using XCM (Cross-Consensus Messaging). XCM ensures assets can move securely between chains while preserving ownership and traceability + +To learn more about asset transfers with XCM, please refer to the [Introduction to XCM](/parachains/interoperability/get-started/) page. diff --git a/.ai/pages/reference-polkadot-hub-smart-contracts.md b/.ai/pages/reference-polkadot-hub-smart-contracts.md new file mode 100644 index 000000000..71137c8f4 --- /dev/null +++ b/.ai/pages/reference-polkadot-hub-smart-contracts.md @@ -0,0 +1,64 @@ +--- +title: Polkadot Hub Smart Contracts +description: Learn how Polkadot Hub supports smart contracts through the REVM, a Rust-based Ethereum Virtual Machine compatible runtime. +categories: Polkadot Protocol +url: https://docs.polkadot.com/reference/polkadot-hub/smart-contracts/ +--- + +# Smart Contracts on Polkadot Hub + +## Introduction + +Polkadot Hub enables developers to deploy and interact with Solidity contracts through REVM, a high-performance, Rust-based Ethereum Virtual Machine implementation. Polkadot-native precompiles bring Ethereum compatibility to Polkadot Hub, letting teams use familiar Solidity tooling, integrate with on-chain features like governance and XCM, and take advantage of cross-chain interoperability. + +For projects that require maximum computational performance, Polkadot Hub also supports PolkaVM (PVM), a native RISC-V execution engine. PVM is optional and designed for high-throughput, performance-intensive smart contracts. + +### REVM Smart Contracts + +[REVM](https://github.com/bluealloy/revm){target=_blank} brings full EVM compatibility to Polkadot Hub through a fast, memory-safe Rust implementation of the Ethereum Virtual Machine. Unlike PolkaVM, which compiles contracts to RISC-V for native execution, REVM executes standard Ethereum bytecode directly—making it ideal for teams who want to migrate existing Solidity projects to Polkadot with minimal changes. + +With REVM, developers can: + +- Deploy existing Solidity contracts without rewriting them. +- Use familiar Ethereum tooling like Hardhat, Foundry, Remix, and MetaMask. +- Interact with other parachains and on-chain assets using XCM and Polkadot Hub features. + +REVM builds on Rust’s safety guarantees and performance optimizations while retaining full opcode compatibility with the EVM. + +Ethereum-native developers can use Polkadot-native precompiles to access Polkadot features—such as governance, treasury, multisig, and XCM—within a unified, interoperable runtime environment. + +### PVM Smart Contracts + +PVM is Polkadot Hub’s native, high-performance smart contract engine. Instead of emulating EVM bytecode, it runs contracts compiled to a [RISC-V](https://en.wikipedia.org/wiki/RISC-V){target=_blank} instruction set, unlocking higher performance and parallel execution while staying friendly to Ethereum-style development. + +With PVM, developers can: + +- Write Solidity contracts and use familiar tooling (e.g., Hardhat, Foundry) targeting PVM +- Benefit from fast, predictable execution with carefully metered gas/weight. +- Access detailed observability through Substrate events and contract logs for indexing and debugging. + +PolkaVM delivers maximum performance for computationally intensive contracts, offering a native, high-throughput option for Ethereum-style developers on Polkadot Hub. + +!!! smartcontract "PolkaVM Preview Release" + PolkaVM smart contracts with Ethereum compatibility are in **early-stage development and may be unstable or incomplete**. +## Where to Go Next + +
+ +- Guide __Deploy a Basic Contract__ + + --- + + Learn step-by-step how to deploy a basic Solidity smart contract to Polkadot Hub. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/smart-contracts/deploy-basic/basic-remix/) + +- Guide __Explore Development Environments__ + + --- + + Check out the development environments you can use to build, test, and deploy smart contracts. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/local-dev-node/) + +
diff --git a/.ai/site-index.json b/.ai/site-index.json index c87b30833..ddca6a0ab 100644 --- a/.ai/site-index.json +++ b/.ai/site-index.json @@ -4849,15 +4849,15 @@ "token_estimator": "heuristic-v1" }, { - "id": "reference-polkadot-hub-assets-and-smart-contracts", - "title": "Asset Hub", - "slug": "reference-polkadot-hub-assets-and-smart-contracts", + "id": "reference-polkadot-hub-assets", + "title": "Polkadot Hub Assets", + "slug": "reference-polkadot-hub-assets", "categories": [ "Polkadot Protocol" ], - "raw_md_url": "https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-assets-and-smart-contracts.md", - "html_url": "https://docs.polkadot.com/reference/polkadot-hub/assets-and-smart-contracts/", - "preview": "The Asset Hub is a critical component in the Polkadot ecosystem, enabling the management of fungible and non-fungible assets across the network. Since the relay chain focuses on maintaining security and consensus without direct asset management, Asset Hub provides a streamlined platform for creating, managing, and using on-chain assets in a fee-efficient manner. This guide outlines the core features of Asset Hub, including how it handles asset operations, cross-chain transfers, and asset integra", + "raw_md_url": "https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-assets.md", + "html_url": "https://docs.polkadot.com/reference/polkadot-hub/assets/", + "preview": "Polkadot Hub is Polkadot’s system parachain that provides core functionality for the network, including issuing and managing on-chain assets. While the relay chain provides security, Polkadot Hub handles asset logic—minting, burning, transfers, and metadata—efficiently and cost-effectively.", "outline": [ { "depth": 2, @@ -4866,112 +4866,62 @@ }, { "depth": 2, - "title": "Assets Basics", - "anchor": "assets-basics" + "title": "Why Use Polkadot Hub?", + "anchor": "why-use-polkadot-hub" }, { "depth": 2, - "title": "Assets Pallet", - "anchor": "assets-pallet" - }, - { - "depth": 3, - "title": "Key Features", - "anchor": "key-features" - }, - { - "depth": 3, - "title": "Main Functions", - "anchor": "main-functions" - }, - { - "depth": 3, - "title": "Querying Functions", - "anchor": "querying-functions" - }, - { - "depth": 3, - "title": "Permission Models and Roles", - "anchor": "permission-models-and-roles" - }, - { - "depth": 3, - "title": "Asset Freezing", - "anchor": "asset-freezing" - }, - { - "depth": 3, - "title": "Non-Custodial Transfers (Approval API)", - "anchor": "non-custodial-transfers-approval-api" + "title": "Types of Assets", + "anchor": "types-of-assets" }, { "depth": 2, - "title": "Foreign Assets", - "anchor": "foreign-assets" - }, - { - "depth": 3, - "title": "Handling Foreign Assets", - "anchor": "handling-foreign-assets" + "title": "Asset Structure", + "anchor": "asset-structure" }, { "depth": 2, - "title": "Integration", - "anchor": "integration" - }, - { - "depth": 3, - "title": "API Sidecar", - "anchor": "api-sidecar" - }, - { - "depth": 3, - "title": "TxWrapper", - "anchor": "txwrapper" + "title": "How Native Assets Work", + "anchor": "how-native-assets-work" }, { "depth": 3, - "title": "Parachain Node", - "anchor": "parachain-node" - }, - { - "depth": 2, - "title": "XCM Transfer Monitoring", - "anchor": "xcm-transfer-monitoring" + "title": "Asset Operations", + "anchor": "asset-operations" }, { "depth": 3, - "title": "Monitor XCM Deposits", - "anchor": "monitor-xcm-deposits" + "title": "Roles and Permissions", + "anchor": "roles-and-permissions" }, { "depth": 3, - "title": "Track XCM Information Back to the Source", - "anchor": "track-xcm-information-back-to-the-source" + "title": "Freezing Assets", + "anchor": "freezing-assets" }, { "depth": 3, - "title": "Practical Monitoring Examples", - "anchor": "practical-monitoring-examples" + "title": "Delegated Transfers", + "anchor": "delegated-transfers" }, { - "depth": 3, - "title": "Monitor for Failed XCM Transfers", - "anchor": "monitor-for-failed-xcm-transfers" + "depth": 2, + "title": "How Foreign Assets Work", + "anchor": "how-foreign-assets-work" }, { "depth": 2, - "title": "Where to Go Next", - "anchor": "where-to-go-next" + "title": "Moving Assets Across Chains", + "anchor": "moving-assets-across-chains" } ], "stats": { - "chars": 18211, - "words": 2649, - "headings": 21, - "estimated_token_count_total": 3678 + "chars": 7453, + "words": 1061, + "headings": 11, + "estimated_token_count_total": 1493 }, - "hash": "sha256:3d10c04cffc5f737ff75b079d661c2c1904629d23ae1e415e64fd6ae4e98759e", + "hash": "sha256:98b6ce18a56ea53a3f2e4bd2ebe8e25647d3d79404a63cd87d39cfb79adc0e94", "token_estimator": "heuristic-v1" }, { @@ -5327,6 +5277,47 @@ "hash": "sha256:8239d1e8d8642cb7c10e9e5f971c99b999e9e4a87373b50bf4a691225c1e4702", "token_estimator": "heuristic-v1" }, + { + "id": "reference-polkadot-hub-smart-contracts", + "title": "Polkadot Hub Smart Contracts", + "slug": "reference-polkadot-hub-smart-contracts", + "categories": [ + "Polkadot Protocol" + ], + "raw_md_url": "https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-smart-contracts.md", + "html_url": "https://docs.polkadot.com/reference/polkadot-hub/smart-contracts/", + "preview": "Polkadot Hub enables developers to deploy and interact with Solidity contracts through REVM, a high-performance, Rust-based Ethereum Virtual Machine implementation. Polkadot-native precompiles bring Ethereum compatibility to Polkadot Hub, letting teams use familiar Solidity tooling, integrate with on-chain features like governance and XCM, and take advantage of cross-chain interoperability.", + "outline": [ + { + "depth": 2, + "title": "Introduction", + "anchor": "introduction" + }, + { + "depth": 3, + "title": "REVM Smart Contracts", + "anchor": "revm-smart-contracts" + }, + { + "depth": 3, + "title": "PVM Smart Contracts", + "anchor": "pvm-smart-contracts" + }, + { + "depth": 2, + "title": "Where to Go Next", + "anchor": "where-to-go-next" + } + ], + "stats": { + "chars": 3309, + "words": 452, + "headings": 4, + "estimated_token_count_total": 652 + }, + "hash": "sha256:f92ae15a26b1cd86d398cb66a05b93bc7e0b4125a6b1523026854c8d79af8b77", + "token_estimator": "heuristic-v1" + }, { "id": "reference-polkadot-hub", "title": "Polkadot Hub Overview", diff --git a/.chain-interactions/token-operations/register-foreign-asset.md b/.chain-interactions/token-operations/register-foreign-asset.md index d51606bd4..e357f4290 100644 --- a/.chain-interactions/token-operations/register-foreign-asset.md +++ b/.chain-interactions/token-operations/register-foreign-asset.md @@ -34,10 +34,12 @@ Before you start, ensure that you have: This guide will use Polkadot, its local Asset Hub instance, and the [Astar](https://astar.network/){target=\_blank} parachain (`ID` 2006), as stated in the [Test Environment Setup](#test-environment-setup) section. However, the process is the same for other relay chains and their respective Asset Hub parachain, regardless of the network you are using and the parachain owner of the foreign asset. -## Steps to Register a Foreign Asset +## Register a Foreign Asset ### Asset Hub +To register a foreign asset on the Asset Hub parachain, follow these steps: + 1. Open the [Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank} interface and connect to the Asset Hub parachain using the network selector in the top left corner. - Testing foreign asset registration is recommended on TestNet before proceeding to MainNet. If you haven't set up a local testing environment yet, consult the [Environment setup](#test-environment-setup) guide. After setting up, connect to the Local Node (Chopsticks) at `ws://127.0.0.1:8000`. @@ -86,6 +88,8 @@ This guide will use Polkadot, its local Asset Hub instance, and the [Astar](http ### Source Parachain +With the encoded call data you generated in the previous section, you can take the following steps on the source parachain to complete the asset registration process: + 1. Navigate to the **Developer > Extrinsics** section. 2. Create the extrinsic to register the foreign asset through XCM: diff --git a/.chain-interactions/token-operations/register-local-asset.md b/.chain-interactions/token-operations/register-local-asset.md index 60023e30c..aa0c32c3b 100644 --- a/.chain-interactions/token-operations/register-local-asset.md +++ b/.chain-interactions/token-operations/register-local-asset.md @@ -22,7 +22,7 @@ Before you begin, ensure you have access to the [Polkadot.js Apps](https://polka You need to ensure that your Asset 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. -## Steps to Register a Local Asset +## Register a Local Asset To register a local asset on the Asset Hub parachain, follow these steps: diff --git a/llms-full.jsonl b/llms-full.jsonl index afc011fd9..9313539c6 100644 --- a/llms-full.jsonl +++ b/llms-full.jsonl @@ -686,27 +686,17 @@ {"page_id": "reference-parachains", "page_title": "Parachains Overview", "index": 3, "depth": 3, "title": "FRAME: Building Blocks for Your Runtime", "anchor": "frame-building-blocks-for-your-runtime", "start_char": 4333, "end_char": 6265, "estimated_token_count": 409, "token_estimator": "heuristic-v1", "text": "### FRAME: Building Blocks for Your Runtime\n\nFRAME provides modular components called [pallets](/reference/glossary#pallet){target=\\_blank} that you can compose to build your parachain's runtime. Each pallet provides specific functionality that you can customize and configure for your needs. This modular approach allows you to quickly assemble complex functionality without writing everything from scratch.\n\n```mermaid\ngraph LR\n subgraph SP[\"Parachain Runtime\"]\n direction LR\n Timestamp ~~~ Aura ~~~ ParachainSystem\n Balances ~~~ TransactionPayment ~~~ Sudo\n subgraph Timestamp[\"Timestamp\"]\n SS1[Custom Config]\n end\n subgraph Aura[\"Aura\"]\n SS2[Custom Config]\n end\n subgraph ParachainSystem[\"Parachain System\"]\n SS3[Custom Config]\n end\n subgraph Balances[\"Balances\"]\n SS4[Custom Config]\n end\n subgraph TransactionPayment[\"Transaction Payment\"]\n SS5[Custom Config]\n end\n subgraph Sudo[\"Sudo\"]\n SS6[Custom Config]\n end\n style Timestamp stroke:#FF69B4\n style Aura stroke:#FF69B4\n style ParachainSystem stroke:#FF69B4\n style Balances stroke:#FF69B4\n style TransactionPayment stroke:#FF69B4\n style Sudo stroke:#FF69B4\n style SS1 stroke-dasharray: 5\n style SS2 stroke-dasharray: 5\n style SS3 stroke-dasharray: 5\n style SS4 stroke-dasharray: 5\n style SS5 stroke-dasharray: 5\n style SS6 stroke-dasharray: 5\n\n end\n subgraph AP[\"Available FRAME Pallets\"]\n direction LR\n A1[Aura]~~~A2[Parachain
System]~~~A3[Transaction
Payment]~~~A4[Sudo]\n B1[Identity]~~~B2[Balances]~~~B3[Assets]~~~B4[EVM]\n C1[Timestamp]~~~C2[Staking]~~~C3[Contracts]~~~C4[and more...]\n end\n AP --> SP\n```"} {"page_id": "reference-parachains", "page_title": "Parachains Overview", "index": 4, "depth": 3, "title": "Cumulus: Parachain-Specific Functionality", "anchor": "cumulus-parachain-specific-functionality", "start_char": 6265, "end_char": 6970, "estimated_token_count": 133, "token_estimator": "heuristic-v1", "text": "### Cumulus: Parachain-Specific Functionality\n\nCumulus 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.\n\nKey Cumulus components include:\n\n- **Parachain system pallet**: Core parachain functionality and relay chain communication.\n- **Collator consensus**: Block production logic for parachain collators.\n- **Relay chain interface**: APIs for interacting with the Polkadot relay chain.\n- **Validation data**: Handling proof-of-validity data required by relay chain validators."} {"page_id": "reference-parachains", "page_title": "Parachains Overview", "index": 5, "depth": 2, "title": "Where to Go Next", "anchor": "where-to-go-next", "start_char": 6970, "end_char": 8495, "estimated_token_count": 329, "token_estimator": "heuristic-v1", "text": "## Where to Go Next\n\nBuilding 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.\n\nThe following sections provide detailed guidance on each aspect of parachain development, from initial design through deployment and ongoing maintenance.\n\n
\n\n- Guide __Launch a Simple Parachain__\n\n ---\n\n Walk through the complete parachain launch flow: from setup and deployment to obtaining coretime.\n\n [:octicons-arrow-right-24: Deploy](/parachains/launch-a-parachain/set-up-the-parachain-template/)\n\n\n- Guide __Customize Your Runtime__\n\n ---\n\n Design your parachain's runtime logic and choose appropriate pallets for your use case.\n\n [:octicons-arrow-right-24: Get Started](/parachains/customize-runtime/)\n\n- Guide __Interoperability__\n\n ---\n\n Implement XCM for trustless cross-chain communication with other parachains.\n\n [:octicons-arrow-right-24: Learn More](/parachains/interoperability/get-started/)\n\n- Guide __Runtime Upgrades__\n\n ---\n\n Upgrade your parachain's runtime without hard forks using forkless upgrade mechanisms.\n\n [:octicons-arrow-right-24: Maintain](/parachains/runtime-maintenance/runtime-upgrades/)\n\n
"} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 0, "depth": 2, "title": "Introduction", "anchor": "introduction", "start_char": 13, "end_char": 682, "estimated_token_count": 131, "token_estimator": "heuristic-v1", "text": "## Introduction\n\nThe Asset Hub is a critical component in the Polkadot ecosystem, enabling the management of fungible and non-fungible assets across the network. Since the relay chain focuses on maintaining security and consensus without direct asset management, Asset Hub provides a streamlined platform for creating, managing, and using on-chain assets in a fee-efficient manner. This guide outlines the core features of Asset Hub, including how it handles asset operations, cross-chain transfers, and asset integration using XCM, as well as essential tools like [API Sidecar](#api-sidecar) and [`TxWrapper`](#txwrapper) for developers working with on-chain assets."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 1, "depth": 2, "title": "Assets Basics", "anchor": "assets-basics", "start_char": 682, "end_char": 3257, "estimated_token_count": 493, "token_estimator": "heuristic-v1", "text": "## Assets Basics\n\nIn the Polkadot ecosystem, the relay chain does not natively support additional assets beyond its native token (DOT for Polkadot, KSM for Kusama). The Asset Hub parachain on Polkadot and Kusama provides a fungible and non-fungible assets framework. Asset Hub allows developers and users to create, manage, and use assets across the ecosystem.\n\nAsset creators can use Asset Hub to track their asset issuance across multiple parachains and manage assets through operations such as minting, burning, and transferring. Projects that need a standardized method of handling on-chain assets will find this particularly useful. The fungible asset interface provided by Asset Hub closely resembles Ethereum's ERC-20 standard but is directly integrated into Polkadot's runtime, making it more efficient in terms of speed and transaction fees.\n\nIntegrating with Asset Hub offers several key benefits, particularly for infrastructure providers and users:\n\n- **Support for non-native on-chain assets**: Asset Hub enables seamless asset creation and management, allowing projects to develop tokens or assets that can interact with the broader ecosystem.\n- **Lower transaction fees**: Asset Hub offers significantly lower transaction costs—approximately one-tenth of the fees on the relay chain, providing cost-efficiency for regular operations.\n- **Reduced deposit requirements**: Depositing assets in Asset Hub is more accessible, with deposit requirements that are around one one-hundredth of those on the relay chain.\n- **Payment of transaction fees with non-native assets**: Users can pay transaction fees in assets other than the native token (DOT or KSM), offering more flexibility for developers and users.\n\nAssets created on the Asset Hub are stored as part of a map, where each asset has a unique ID that links to information about the asset, including details like:\n\n- The management team.\n- The total supply.\n- The number of accounts holding the asset.\n- **Sufficiency for account existence**: Whether the asset alone is enough to maintain an account without a native token balance.\n- The metadata of the asset, including its name, symbol, and the number of decimals for representation.\n\nSome assets can be regarded as sufficient to maintain an account's existence, meaning that users can create accounts on the network without needing a native token balance (i.e., no existential deposit required). Developers can also set minimum balances for their assets. If an account's balance drops below the minimum, the balance is considered dust and may be cleared."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 2, "depth": 2, "title": "Assets Pallet", "anchor": "assets-pallet", "start_char": 3257, "end_char": 3793, "estimated_token_count": 112, "token_estimator": "heuristic-v1", "text": "## Assets Pallet\n\nThe Polkadot SDK's Assets pallet is a powerful module designated for creating and managing fungible asset classes with a fixed supply. It offers a secure and flexible way to issue, transfer, freeze, and destroy assets. The pallet supports various operations and includes permissioned and non-permissioned functions to cater to simple and advanced use cases.\n\nVisit the [Assets Pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\\_blank} for more in-depth information."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 3, "depth": 3, "title": "Key Features", "anchor": "key-features", "start_char": 3793, "end_char": 4454, "estimated_token_count": 140, "token_estimator": "heuristic-v1", "text": "### Key Features\n\nKey features of the Assets pallet include:\n\n- **Asset issuance**: Allows the creation of a new asset, where the total supply is assigned to the creator's account.\n- **Asset transfer**: Enables transferring assets between accounts while maintaining a balance in both accounts.\n- **Asset freezing**: Prevents transfers of a specific asset from one account, locking it from further transactions.\n- **Asset destruction**: Allows accounts to burn or destroy their holdings, removing those assets from circulation.\n- **Non-custodial transfers**: A non-custodial mechanism to enable one account to approve a transfer of assets on behalf of another."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 4, "depth": 3, "title": "Main Functions", "anchor": "main-functions", "start_char": 4454, "end_char": 5397, "estimated_token_count": 235, "token_estimator": "heuristic-v1", "text": "### Main Functions\n\nThe Assets pallet provides a broad interface for managing fungible assets. Some of the main dispatchable functions include:\n\n- **`create()`**: Create a new asset class by placing a deposit, applicable when asset creation is permissionless.\n- **`issue()`**: Mint a fixed supply of a new asset and assign it to the creator's account.\n- **`transfer()`**: Transfer a specified amount of an asset between two accounts.\n- **`approve_transfer()`**: Approve a non-custodial transfer, allowing a third party to move assets between accounts.\n- **`destroy()`**: Destroy an entire asset class, removing it permanently from the chain.\n- **`freeze()` and `thaw()`**: Administrators or privileged users can lock or unlock assets from being transferred.\n\nFor a full list of dispatchable and privileged functions, see the [dispatchables Rust docs](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/enum.Call.html){target=\\_blank}."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 5, "depth": 3, "title": "Querying Functions", "anchor": "querying-functions", "start_char": 5397, "end_char": 6347, "estimated_token_count": 193, "token_estimator": "heuristic-v1", "text": "### Querying Functions\n\nThe Assets pallet exposes several key querying functions that developers can interact with programmatically. These functions allow you to query asset information and perform operations essential for managing assets across accounts. The two main querying functions are:\n\n- **`balance(asset_id, account)`**: Retrieves the balance of a given asset for a specified account. Useful for checking the holdings of an asset class across different accounts.\n\n- **`total_supply(asset_id)`**: Returns the total supply of the asset identified by `asset_id`. Allows users to verify how much of the asset exists on-chain.\n\nIn addition to these basic functions, other utility functions are available for querying asset metadata and performing asset transfers. You can view the complete list of querying functions in the [Struct Pallet Rust docs](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/struct.Pallet.html){target=\\_blank}."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 6, "depth": 3, "title": "Permission Models and Roles", "anchor": "permission-models-and-roles", "start_char": 6347, "end_char": 7634, "estimated_token_count": 239, "token_estimator": "heuristic-v1", "text": "### Permission Models and Roles\n\nThe Assets pallet incorporates a robust permission model, enabling control over who can perform specific operations like minting, transferring, or freezing assets. The key roles within the permission model are:\n\n- **Admin**: Can freeze (preventing transfers) and forcibly transfer assets between accounts. Admins also have the power to reduce the balance of an asset class across arbitrary accounts. They manage the more sensitive and administrative aspects of the asset class.\n- **Issuer**: Responsible for minting new tokens. When new assets are created, the Issuer is the account that controls their distribution to other accounts.\n- **Freezer**: Can lock the transfer of assets from an account, preventing the account holder from moving their balance. This function is useful for freezing accounts involved in disputes or fraud.\n- **Owner**: Has overarching control, including destroying an entire asset class. Owners can also set or update the Issuer, Freezer, and Admin roles.\n\nThese permissions provide fine-grained control over assets, enabling developers and asset managers to ensure secure, controlled operations. Each of these roles is crucial for managing asset lifecycles and ensuring that assets are used appropriately across the network."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 7, "depth": 3, "title": "Asset Freezing", "anchor": "asset-freezing", "start_char": 7634, "end_char": 8552, "estimated_token_count": 172, "token_estimator": "heuristic-v1", "text": "### Asset Freezing\n\nThe Assets pallet allows you to freeze assets. This feature prevents transfers or spending from a specific account, effectively locking the balance of an asset class until it is explicitly unfrozen. Asset freezing is beneficial when assets are restricted due to security concerns or disputes.\n\nFreezing assets is controlled by the Freezer role, as mentioned earlier. Only the account with the Freezer privilege can perform these operations. Here are the key freezing functions:\n\n- **`freeze(asset_id, account)`**: Locks the specified asset of the account. While the asset is frozen, no transfers can be made from the frozen account.\n- **`thaw(asset_id, account)`**: Corresponding function for unfreezing, allowing the asset to be transferred again.\n\nThis approach enables secure and flexible asset management, providing administrators the tools to control asset movement in special circumstances."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 8, "depth": 3, "title": "Non-Custodial Transfers (Approval API)", "anchor": "non-custodial-transfers-approval-api", "start_char": 8552, "end_char": 9746, "estimated_token_count": 232, "token_estimator": "heuristic-v1", "text": "### Non-Custodial Transfers (Approval API)\n\nThe Assets pallet also supports non-custodial transfers through the Approval API. This feature allows one account to approve another account to transfer a specific amount of its assets to a third-party recipient without granting full control over the account's balance. Non-custodial transfers enable secure transactions where trust is required between multiple parties.\n\nHere's a brief overview of the key functions for non-custodial asset transfers:\n\n- **`approve_transfer(asset_id, delegate, amount)`**: Approves a delegate to transfer up to a certain amount of the asset on behalf of the original account holder.\n- **`cancel_approval(asset_id, delegate)`**: Cancels a previous approval for the delegate. Once canceled, the delegate no longer has permission to transfer the approved amount.\n- **`transfer_approved(asset_id, owner, recipient, amount)`**: Executes the approved asset transfer from the owner’s account to the recipient. The delegate account can call this function once approval is granted.\n\nThese delegated operations make it easier to manage multi-step transactions and dApps that require complex asset flows between participants."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 9, "depth": 2, "title": "Foreign Assets", "anchor": "foreign-assets", "start_char": 9746, "end_char": 10290, "estimated_token_count": 94, "token_estimator": "heuristic-v1", "text": "## Foreign Assets\n\nForeign assets in Asset Hub refer to assets originating from external blockchains or parachains that are registered in the Asset Hub. These assets are typically native tokens from other parachains within the Polkadot ecosystem or bridged tokens from external blockchains such as Ethereum.\n\nOnce a foreign asset is registered in the Asset Hub by its originating blockchain's root origin, users are able to send these tokens to the Asset Hub and interact with them as they would any other asset within the Polkadot ecosystem."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 10, "depth": 3, "title": "Handling Foreign Assets", "anchor": "handling-foreign-assets", "start_char": 10290, "end_char": 11225, "estimated_token_count": 166, "token_estimator": "heuristic-v1", "text": "### Handling Foreign Assets\n\nThe Foreign Assets pallet, an instance of the Assets pallet, manages these assets. Since foreign assets are integrated into the same interface as native assets, developers can use the same functionalities, such as transferring and querying balances. However, there are important distinctions when dealing with foreign assets.\n\n- **Asset identifier**: Unlike native assets, foreign assets are identified using an XCM Multilocation rather than a simple numeric `AssetId`. This multilocation identifier represents the cross-chain location of the asset and provides a standardized way to reference it across different parachains and relay chains.\n\n- **Transfers**: Once registered in the Asset Hub, foreign assets can be transferred between accounts, just like native assets. Users can also send these assets back to their originating blockchain if supported by the relevant cross-chain messaging mechanisms."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 11, "depth": 2, "title": "Integration", "anchor": "integration", "start_char": 11225, "end_char": 11668, "estimated_token_count": 71, "token_estimator": "heuristic-v1", "text": "## Integration\n\nAsset Hub supports a variety of integration tools that make it easy for developers to manage assets and interact with the blockchain in their applications. The tools and libraries provided by Parity Technologies enable streamlined operations, such as querying asset information, building transactions, and monitoring cross-chain asset transfers.\n\nDevelopers can integrate Asset Hub into their projects using these core tools:"} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 12, "depth": 3, "title": "API Sidecar", "anchor": "api-sidecar", "start_char": 11668, "end_char": 12511, "estimated_token_count": 211, "token_estimator": "heuristic-v1", "text": "### API Sidecar\n\n[API Sidecar](https://github.com/paritytech/substrate-api-sidecar){target=\\_blank} is a RESTful service that can be deployed alongside Polkadot and Kusama nodes. It provides endpoints to retrieve real-time blockchain data, including asset information. When used with Asset Hub, Sidecar allows querying:\n\n- **Asset look-ups**: Retrieve specific assets using `AssetId`.\n- **Asset balances**: View the balance of a particular asset on Asset Hub.\n\nPublic instances of API Sidecar connected to Asset Hub are available, such as:\n\n- [Polkadot Asset Hub Sidecar](https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/){target=\\_blank}\n- [Kusama Asset Hub Sidecar](https://kusama-asset-hub-public-sidecar.parity-chains.parity.io/){target=\\_blank}\n\nThese public instances are primarily for ad-hoc testing and quick checks."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 13, "depth": 3, "title": "TxWrapper", "anchor": "txwrapper", "start_char": 12511, "end_char": 13113, "estimated_token_count": 113, "token_estimator": "heuristic-v1", "text": "### TxWrapper\n\n[`TxWrapper`](https://github.com/paritytech/txwrapper-core){target=\\_blank} is a library that simplifies constructing and signing transactions for Polkadot SDK-based chains, including Polkadot and Kusama. This tool includes support for working with Asset Hub, enabling developers to:\n\n- Construct offline transactions.\n- Leverage asset-specific functions such as minting, burning, and transferring assets.\n\n`TxWrapper` provides the flexibility needed to integrate asset operations into custom applications while maintaining the security and efficiency of Polkadot's transaction model."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 14, "depth": 3, "title": "Parachain Node", "anchor": "parachain-node", "start_char": 13113, "end_char": 13766, "estimated_token_count": 131, "token_estimator": "heuristic-v1", "text": "### Parachain Node\n\nTo fully leverage the Asset Hub's functionality, developers will need to run a system parachain node. Setting up an Asset Hub node allows users to interact with the parachain in real time, syncing data and participating in the broader Polkadot ecosystem. Guidelines for setting up an [Asset Hub node](https://github.com/paritytech/polkadot-sdk/tree/polkadot-stable2506-2/cumulus#asset-hub-){target=\\_blank} are available in the Parity documentation.\n\nUsing these integration tools, developers can manage assets seamlessly and integrate Asset Hub functionality into their applications, leveraging Polkadot's powerful infrastructure."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 15, "depth": 2, "title": "XCM Transfer Monitoring", "anchor": "xcm-transfer-monitoring", "start_char": 13766, "end_char": 14109, "estimated_token_count": 56, "token_estimator": "heuristic-v1", "text": "## XCM Transfer Monitoring\n\nSince Asset Hub facilitates cross-chain asset transfers across the Polkadot ecosystem, XCM transfer monitoring becomes an essential practice for developers and infrastructure providers. This section outlines how to monitor the cross-chain movement of assets between parachains, the relay chain, and other systems."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 16, "depth": 3, "title": "Monitor XCM Deposits", "anchor": "monitor-xcm-deposits", "start_char": 14109, "end_char": 14901, "estimated_token_count": 160, "token_estimator": "heuristic-v1", "text": "### Monitor XCM Deposits\n\nAs assets move between chains, tracking the cross-chain transfers in real time is crucial. Whether assets are transferred via a teleport from system parachains or through a reserve-backed transfer from any other parachain, each transfer emits a relevant event (such as the `balances.minted` event).\n\nTo ensure accurate monitoring of these events:\n\n- **Track XCM deposits**: Query every new block created in the relay chain or Asset Hub, loop through the events array, and filter for any `balances.minted` events which confirm the asset was successfully transferred to the account.\n- **Track event origins**: Each `balances.minted` event points to a specific address. By monitoring this, service providers can verify that assets have arrived in the correct account."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 17, "depth": 3, "title": "Track XCM Information Back to the Source", "anchor": "track-xcm-information-back-to-the-source", "start_char": 14901, "end_char": 15568, "estimated_token_count": 146, "token_estimator": "heuristic-v1", "text": "### Track XCM Information Back to the Source\n\nWhile the `balances.minted` event confirms the arrival of assets, there may be instances where you need to trace the origin of the cross-chain message that triggered the event. In such cases, you can:\n\n1. Query the relevant chain at the block where the `balances.minted` event was emitted.\n2. Look for a `messageQueue(Processed)` event within that block's initialization. This event contains a parameter (`Id`) that identifies the cross-chain message received by the relay chain or Asset Hub. You can use this `Id` to trace the message back to its origin chain, offering full visibility of the asset transfer's journey."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 18, "depth": 3, "title": "Practical Monitoring Examples", "anchor": "practical-monitoring-examples", "start_char": 15568, "end_char": 16379, "estimated_token_count": 163, "token_estimator": "heuristic-v1", "text": "### Practical Monitoring Examples\n\nThe preceding sections outline the process of monitoring XCM deposits to specific accounts and then tracing back the origin of these deposits. The process of tracking an XCM transfer and the specific events to monitor may vary based on the direction of the XCM message. Here are some examples to showcase the slight differences:\n\n- **Transfer from parachain to relay chain**: Track `parachainsystem(UpwardMessageSent)` on the parachain and `messagequeue(Processed)` on the relay chain.\n- **Transfer from relay chain to parachain**: Track `xcmPallet(sent)` on the relay chain and `dmpqueue(ExecutedDownward)` on the parachain.\n- **Transfer between parachains**: Track `xcmpqueue(XcmpMessageSent)` on the system parachain and `xcmpqueue(Success)` on the destination parachain."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 19, "depth": 3, "title": "Monitor for Failed XCM Transfers", "anchor": "monitor-for-failed-xcm-transfers", "start_char": 16379, "end_char": 17187, "estimated_token_count": 176, "token_estimator": "heuristic-v1", "text": "### Monitor for Failed XCM Transfers\n\nSometimes, XCM transfers may fail due to liquidity or other errors. Failed transfers emit specific error events, which are key to resolving issues in asset transfers. Monitoring for these failure events helps catch issues before they affect asset balances.\n\n- **Relay chain to system parachain**: Look for the `dmpqueue(ExecutedDownward)` event on the parachain with an `Incomplete` outcome and an error type such as `UntrustedReserveLocation`.\n- **Parachain to parachain**: Monitor for `xcmpqueue(Fail)` on the destination parachain with error types like `TooExpensive`.\n\nFor detailed error management in XCM, see Gavin Wood's blog post on [XCM Execution and Error Management](https://polkadot.com/blog/xcm-part-three-execution-and-error-management/){target=\\_blank}."} -{"page_id": "reference-polkadot-hub-assets-and-smart-contracts", "page_title": "Asset Hub", "index": 20, "depth": 2, "title": "Where to Go Next", "anchor": "where-to-go-next", "start_char": 17187, "end_char": 18211, "estimated_token_count": 244, "token_estimator": "heuristic-v1", "text": "## Where to Go Next\n\n
\n\n- Tutorial __Register a Local Asset__\n\n ---\n\n Comprehensive guide to registering a local asset on the Asset Hub system parachain, including step-by-step instructions.\n\n [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/register-local-asset/)\n\n- Tutorial __Register a Foreign Asset__\n\n ---\n\n An in-depth guide to registering a foreign asset on the Asset Hub parachain, providing clear, step-by-step instructions.\n\n [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/register-foreign-asset/)\n\n- Tutorial __Convert Assets__\n\n ---\n\n A guide detailing the step-by-step process of converting assets on Asset Hub, helping users efficiently navigate asset management on the platform.\n\n [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/convert-assets/)\n\n
"} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 0, "depth": 2, "title": "Introduction", "anchor": "introduction", "start_char": 26, "end_char": 664, "estimated_token_count": 114, "token_estimator": "heuristic-v1", "text": "## Introduction\n\nPolkadot Hub is Polkadot’s system parachain that provides core functionality for the network, including issuing and managing on-chain assets. While the relay chain provides security, Polkadot Hub handles asset logic—minting, burning, transfers, and metadata—efficiently and cost-effectively.\n\nPolkadot Hub supports native assets issued on the parachain and foreign assets from other chains, both of which can move seamlessly across the network via XCM.\n\nThis guide explains how assets are created, managed, and moved across chains, including key operations, roles, and the differences between native and foreign assets."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 1, "depth": 2, "title": "Why Use Polkadot Hub?", "anchor": "why-use-polkadot-hub", "start_char": 664, "end_char": 1531, "estimated_token_count": 198, "token_estimator": "heuristic-v1", "text": "## Why Use Polkadot Hub?\n\nPolkadot Hub provides a standardized framework for creating and managing fungible and non-fungible assets. Projects can issue tokens, manage supply, and transfer assets across parachains, extending the functionality of the Polkadot relay chain, which only supports its native token (DOT).\n\n**Key features**:\n\n- **Built-in asset operations**: Mint, burn, and transfer like ERC-20 on Ethereum, but native to Polkadot's runtime.\n- **Custom asset creation**: Issue tokens or NFTs with configurable permissions and metadata.\n- **Low fees**: Transactions cost roughly one-tenth of relay chain fees.\n- **Lower deposits**: Minimal on-chain storage costs for asset data.\n- **Pay fees in any asset**: Users don’t need DOT to transact; supported assets can cover fees.\n- **Cross-chain ready**: Assets can be transferred to other parachains using XCM."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 2, "depth": 2, "title": "Types of Assets", "anchor": "types-of-assets", "start_char": 1531, "end_char": 1995, "estimated_token_count": 91, "token_estimator": "heuristic-v1", "text": "## Types of Assets\n\nPolkadot Hub supports two types of assets:\n\n- **Native assets**: Tokens and NFTs issued directly on Polkadot Hub using the Assets pallet. These assets benefit from the platform's custom features, such as configurable permissions and low fees\n- **Foreign assets**: Tokens originating from other Polkadot parachains or external networks (like Ethereum, via bridges). Once registered on Polkadot Hub, they are treated similarly to native assets."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 3, "depth": 2, "title": "Asset Structure", "anchor": "asset-structure", "start_char": 1995, "end_char": 2518, "estimated_token_count": 104, "token_estimator": "heuristic-v1", "text": "## Asset Structure\n\nEach asset is identified by a unique ID and stores:\n\n- Asset administrators\n- Total supply and holder count\n- Minimum balance configuration\n- Sufficiency–whether the asset can keep an account alive without DOT\n- Metadata (name, symbol, decimals)\n\nIf a balance falls below the configured minimum, called the [existential deposit](/reference/glossary/#existential-deposit){target=\\_blank}, it may be removed as “dust.” This ensures efficient storage while giving developers control over asset economics."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 4, "depth": 2, "title": "How Native Assets Work", "anchor": "how-native-assets-work", "start_char": 2518, "end_char": 3094, "estimated_token_count": 111, "token_estimator": "heuristic-v1", "text": "## How Native Assets Work\n\nNative assets on Polkadot Hub are created and managed via the Assets pallet from the Polkadot SDK. This pallet defines the runtime logic for issuing, configuring, and administering fungible assets with customizable permissions.\n\nIt supports both permissioned and permissionless asset creation, enabling everything from simple user-issued tokens to governed assets controlled by teams or DAOs.\n\nFor implementation details, see the [Assets Pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\\_blank}."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 5, "depth": 3, "title": "Asset Operations", "anchor": "asset-operations", "start_char": 3094, "end_char": 4151, "estimated_token_count": 243, "token_estimator": "heuristic-v1", "text": "### Asset Operations\n\nThe Assets pallet provides both state-changing operations and read-only queries for full lifecycle management of assets.\n\nCore operations include:\n\n- **Asset issuance**: Create new assets and assign initial supply.\n- **Transfers**: Move assets between accounts with balance tracking.\n- **Burning**: Reduce total supply by destroying tokens.\n- **Delegated transfers**: Approve transfers on behalf of another account without giving up custody.\n- **Freezing and thawing**: Temporarily lock and unlock an account's balance.\n\nFor a complete list of extrinsics, see the [`pallet-assets` dispatchable functions reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/enum.Call.html){target=\\_blank}.\n\nData queries make it possible to:\n\n- Check account balances and total supply.\n- Retrieve asset metadata and configuration details.\n- Inspect account and asset status on-chain.\n\nFor a full list of queries, see the [Pallet reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/struct.Pallet.html){target=\\_blank}."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 6, "depth": 3, "title": "Roles and Permissions", "anchor": "roles-and-permissions", "start_char": 4151, "end_char": 4947, "estimated_token_count": 159, "token_estimator": "heuristic-v1", "text": "### Roles and Permissions\n\nThe Assets pallet uses role-based permissions to control who can manage different parts of an asset’s lifecycle:\n\n- **Owner**: Overarching control, including destroying an asset class; can set or update Issuer, Freezer, and Admin roles.\n- **Admin**: Can freeze assets and forcibly transfer balances between accounts. Admins can also reduce the balance of an asset class across arbitrary accounts.\n- **Issuer**: Responsible for minting new tokens. When new assets are created, the Issuer is the account that controls their distribution to other accounts.\n- **Freezer**: Can lock the transfer of assets from an account, preventing the account holder from moving their balance.\n\nThese roles allow projects to enforce governance and security policies around their assets."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 7, "depth": 3, "title": "Freezing Assets", "anchor": "freezing-assets", "start_char": 4947, "end_char": 5469, "estimated_token_count": 106, "token_estimator": "heuristic-v1", "text": "### Freezing Assets\n\nAssets can be temporarily locked to prevent transfers from specific accounts. This is useful for dispute resolution, fraud prevention, or compliance controls.\n\n**How it works**:\n\n- Only authorized parties can freeze or unfreeze (thaw) assets.\n- Freezing pauses the movement of the asset without burning or removing it.\n- Once thawed, the asset can be transferred normally.\n\nFreezing provides a safe way to control asset flow while maintaining full ownership.\n\n**Key functions**: `freeze` and `thaw`."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 8, "depth": 3, "title": "Delegated Transfers", "anchor": "delegated-transfers", "start_char": 5469, "end_char": 6204, "estimated_token_count": 138, "token_estimator": "heuristic-v1", "text": "### Delegated Transfers\n\nPolkadot Hub supports delegated asset transfers, allowing one account to authorize another to move a limited amount of its assets—without giving up full control. This is useful for escrow logic, automated payments, and multi-party applications.\n\n**How it works**:\n\n- An account can grant permission to another account to transfer a specific amount of its assets.\n- Permissions can be revoked at any time, preventing further transfers.\n- Authorized accounts can execute transfers on behalf of the original owner within the approved limits.\n\nDelegated transfers simplify multi-step transactions and enable complex asset flows.\n\n**Key functions**: `approve_transfer`, `cancel_approval`, and `transfer_approved`."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 9, "depth": 2, "title": "How Foreign Assets Work", "anchor": "how-foreign-assets-work", "start_char": 6204, "end_char": 7066, "estimated_token_count": 157, "token_estimator": "heuristic-v1", "text": "## How Foreign Assets Work\n\nForeign assets are assets originating from other chains and are managed on Polkadot Hub via an instance of the Assets pallet that is configured specifically for foreign assets. It enables transfers, balance checks, and other standard asset operations, while handling foreign-asset specifics such as:\n\n- **Asset identifiers**: Foreign assets use an XCM multilocation as their identifier, rather than a numeric AssetId. This ensures assets from different chains can be referenced and moved safely across parachains.\n\n- **Transfers**: Once registered on Polkadot Hub, foreign assets can be transferred between accounts just like native assets. If supported, they can also be returned to their original blockchain using cross-chain messaging.\n\nThis unified interface makes it easy for dApps to handle both native and cross-chain assets."} +{"page_id": "reference-polkadot-hub-assets", "page_title": "Polkadot Hub Assets", "index": 10, "depth": 2, "title": "Moving Assets Across Chains", "anchor": "moving-assets-across-chains", "start_char": 7066, "end_char": 7453, "estimated_token_count": 72, "token_estimator": "heuristic-v1", "text": "## Moving Assets Across Chains\n\nPolkadot Hub enables assets to move safely between parachains and the relay chain using XCM (Cross-Consensus Messaging). XCM ensures assets can move securely between chains while preserving ownership and traceability\n\nTo learn more about asset transfers with XCM, please refer to the [Introduction to XCM](/parachains/interoperability/get-started/) page."} {"page_id": "reference-polkadot-hub-bridging", "page_title": "Bridge Hub", "index": 0, "depth": 2, "title": "Introduction", "anchor": "introduction", "start_char": 14, "end_char": 1065, "estimated_token_count": 184, "token_estimator": "heuristic-v1", "text": "## Introduction\n\nThe Bridge Hub system parachain plays a crucial role in facilitating trustless interactions between Polkadot, Kusama, Ethereum, and other blockchain ecosystems. By implementing on-chain light clients and supporting protocols like BEEFY and GRANDPA, Bridge Hub ensures seamless message transmission and state verification across chains. It also provides essential [pallets](/reference/glossary/#pallet){target=\\_blank} for sending and receiving messages, making it a cornerstone of Polkadot’s interoperability framework. With built-in support for XCM (Cross-Consensus Messaging), Bridge Hub enables secure, efficient communication between diverse blockchain networks.\n\nThis guide covers the architecture, components, and deployment of the Bridge Hub system. You'll explore its trustless bridging mechanisms, key pallets for various blockchains, and specific implementations like Snowbridge and the Polkadot <> Kusama bridge. By the end, you'll understand how Bridge Hub enhances connectivity within the Polkadot ecosystem and beyond."} {"page_id": "reference-polkadot-hub-bridging", "page_title": "Bridge Hub", "index": 1, "depth": 2, "title": "Trustless Bridging", "anchor": "trustless-bridging", "start_char": 1065, "end_char": 2671, "estimated_token_count": 313, "token_estimator": "heuristic-v1", "text": "## Trustless Bridging\n\nBridge Hub provides a mode of trustless bridging through its implementation of on-chain light clients and trustless relayers. Trustless bridges are essentially two one-way bridges, where each chain has a method of verifying the state of the other in a trustless manner through consensus proofs. In this context, \"trustless\" refers to the lack of need to trust a human when interacting with various system components. Trustless systems are based instead on trusting mathematics, cryptography, and code. The target chain and source chain both provide ways of verifying one another's state and actions (such as a transfer) based on the consensus and finality of both chains rather than an external mechanism controlled by a third party.\n\n[BEEFY (Bridge Efficiency Enabling Finality Yielder)](/reference/polkadot-hub/consensus-and-security/pos-consensus/#bridging-beefy){target=\\_blank} is instrumental in this solution. It provides a more efficient way to verify the consensus on the relay chain. It allows the participants in a network to verify finality proofs, meaning a remote chain like Ethereum can verify the state of Polkadot at a given block height. \n\nFor example, the Ethereum and Polkadot bridging solution that [Snowbridge](https://docs.snowbridge.network/){target=\\_blank} implements involves two light clients: one which verifies the state of Polkadot and the other which verifies the state of Ethereum. The light client for Polkadot is implemented in the runtime as a pallet, whereas the light client for Ethereum is implemented as a smart contract on the beacon chain."} {"page_id": "reference-polkadot-hub-bridging", "page_title": "Bridge Hub", "index": 2, "depth": 2, "title": "Bridging Components", "anchor": "bridging-components", "start_char": 2671, "end_char": 3623, "estimated_token_count": 242, "token_estimator": "heuristic-v1", "text": "## Bridging Components\n\nIn any given Bridge Hub implementation (Kusama, Polkadot, or other relay chains), there are a few primary pallets that are utilized:\n\n- **[Pallet Bridge GRANDPA](https://paritytech.github.io/polkadot-sdk/master/pallet_bridge_grandpa/index.html){target=\\_blank}**: An on-chain GRANDPA light client for Substrate based chains.\n- **[Pallet Bridge Parachains](https://paritytech.github.io/polkadot-sdk/master/pallet_bridge_parachains/index.html){target=\\_blank}**: A finality module for parachains.\n- **[Pallet Bridge Messages](https://paritytech.github.io/polkadot-sdk/master/pallet_bridge_messages/index.html){target=\\_blank}**: A pallet which allows sending, receiving, and tracking of inbound and outbound messages.\n- **[Pallet XCM Bridge](https://paritytech.github.io/polkadot-sdk/master/pallet_xcm_bridge_hub/index.html){target=\\_blank}**: A pallet which, with the Bridge Messages pallet, adds XCM support to bridge pallets."} @@ -752,6 +742,10 @@ {"page_id": "reference-polkadot-hub-people-and-identity", "page_title": "People Chain", "index": 5, "depth": 3, "title": "Judgment Classifications", "anchor": "judgment-classifications", "start_char": 1598, "end_char": 2385, "estimated_token_count": 150, "token_estimator": "heuristic-v1", "text": "### Judgment Classifications\n\nRegistrars can assign the following confidence levels to identity information:\n\n- **Unknown**: Default status; no judgment rendered yet.\n- **Reasonable**: Data appears valid but without formal verification (standard for most verified identities).\n- **Known good**: Information certified correct through formal verification (requires documentation; limited to registrars).\n- **Out of date**: Previously verified information that requires updating.\n- **Low quality**: Imprecise information requiring correction.\n- **Erroneous**: Incorrect information, potentially indicating fraudulent intent.\n\nA temporary \"Fee Paid\" status indicates judgment in progress. Both \"Fee Paid\" and \"Erroneous\" statuses lock identity information from modification until resolved."} {"page_id": "reference-polkadot-hub-people-and-identity", "page_title": "People Chain", "index": 6, "depth": 3, "title": "Registrars", "anchor": "registrars", "start_char": 2385, "end_char": 3680, "estimated_token_count": 198, "token_estimator": "heuristic-v1", "text": "### Registrars\n\nRegistrars serve as trusted verification authorities within the People chain ecosystem. These entities validate user identities and provide attestations that build trust in the network.\n\n- Registrars set specific fees for their verification services.\n- They can specialize in verifying particular identity fields.\n- Verification costs vary based on complexity and thoroughness.\n\nWhen requesting verification, users specify their maximum acceptable fee. Only registrars whose fees fall below this threshold can provide judgment. Upon completing the verification process, the user pays the registrar's fee, and the registrar issues an appropriate confidence level classification based on their assessment.\n\nMultiple registrars operate across the Polkadot and People chain ecosystems, each with unique specializations and fee structures. To request verification:\n\n1. Research available registrars and their verification requirements.\n2. Contact your chosen registrar directly through their specified channels.\n3. Submit required documentation according to their verification process.\n4. Pay the associated verification fee.\n\nYou must contact specific registrars individually to request judgment. Each registrar maintains its own verification procedures and communication channels."} {"page_id": "reference-polkadot-hub-people-and-identity", "page_title": "People Chain", "index": 7, "depth": 2, "title": "Where to Go Next", "anchor": "where-to-go-next", "start_char": 3680, "end_char": 4750, "estimated_token_count": 257, "token_estimator": "heuristic-v1", "text": "## Where to Go Next\n\n
\n\n- External __Polkadot.js Guides about Identity__\n\n ---\n\n Step-by-step instructions for managing identities through the Polkadot.js interface, with practical examples and visual guides.\n\n [:octicons-arrow-right-24: Reference](https://wiki.polkadot.com/learn/learn-guides-identity/)\n\n- External __How to Set and Clear an Identity__\n\n ---\n\n Practical walkthrough covering identity setup and removal process on People chain.\n\n [:octicons-arrow-right-24: Reference](https://support.polkadot.network/support/solutions/articles/65000181981-how-to-set-and-clear-an-identity)\n\n- External __People Chain Runtime Implementation__\n\n ---\n\n Source code for the People chain runtime, detailing the technical architecture of decentralized identity management.\n\n [:octicons-arrow-right-24: Reference](https://github.com/polkadot-fellows/runtimes/tree/main/system-parachains/people)\n\n
"} +{"page_id": "reference-polkadot-hub-smart-contracts", "page_title": "Polkadot Hub Smart Contracts", "index": 0, "depth": 2, "title": "Introduction", "anchor": "introduction", "start_char": 35, "end_char": 674, "estimated_token_count": 109, "token_estimator": "heuristic-v1", "text": "## Introduction\n\nPolkadot Hub enables developers to deploy and interact with Solidity contracts through REVM, a high-performance, Rust-based Ethereum Virtual Machine implementation. Polkadot-native precompiles bring Ethereum compatibility to Polkadot Hub, letting teams use familiar Solidity tooling, integrate with on-chain features like governance and XCM, and take advantage of cross-chain interoperability.\n\nFor projects that require maximum computational performance, Polkadot Hub also supports PolkaVM (PVM), a native RISC-V execution engine. PVM is optional and designed for high-throughput, performance-intensive smart contracts."} +{"page_id": "reference-polkadot-hub-smart-contracts", "page_title": "Polkadot Hub Smart Contracts", "index": 1, "depth": 3, "title": "REVM Smart Contracts", "anchor": "revm-smart-contracts", "start_char": 674, "end_char": 1692, "estimated_token_count": 189, "token_estimator": "heuristic-v1", "text": "### REVM Smart Contracts\n\n[REVM](https://github.com/bluealloy/revm){target=_blank} brings full EVM compatibility to Polkadot Hub through a fast, memory-safe Rust implementation of the Ethereum Virtual Machine. Unlike PolkaVM, which compiles contracts to RISC-V for native execution, REVM executes standard Ethereum bytecode directly—making it ideal for teams who want to migrate existing Solidity projects to Polkadot with minimal changes.\n\nWith REVM, developers can:\n\n- Deploy existing Solidity contracts without rewriting them.\n- Use familiar Ethereum tooling like Hardhat, Foundry, Remix, and MetaMask.\n- Interact with other parachains and on-chain assets using XCM and Polkadot Hub features.\n\nREVM builds on Rust’s safety guarantees and performance optimizations while retaining full opcode compatibility with the EVM. \n\nEthereum-native developers can use Polkadot-native precompiles to access Polkadot features—such as governance, treasury, multisig, and XCM—within a unified, interoperable runtime environment."} +{"page_id": "reference-polkadot-hub-smart-contracts", "page_title": "Polkadot Hub Smart Contracts", "index": 2, "depth": 3, "title": "PVM Smart Contracts", "anchor": "pvm-smart-contracts", "start_char": 1692, "end_char": 2678, "estimated_token_count": 191, "token_estimator": "heuristic-v1", "text": "### PVM Smart Contracts\n\nPVM is Polkadot Hub’s native, high-performance smart contract engine. Instead of emulating EVM bytecode, it runs contracts compiled to a [RISC-V](https://en.wikipedia.org/wiki/RISC-V){target=_blank} instruction set, unlocking higher performance and parallel execution while staying friendly to Ethereum-style development.\n\nWith PVM, developers can:\n\n- Write Solidity contracts and use familiar tooling (e.g., Hardhat, Foundry) targeting PVM\n- Benefit from fast, predictable execution with carefully metered gas/weight.\n- Access detailed observability through Substrate events and contract logs for indexing and debugging.\n\nPolkaVM delivers maximum performance for computationally intensive contracts, offering a native, high-throughput option for Ethereum-style developers on Polkadot Hub.\n\n!!! smartcontract \"PolkaVM Preview Release\"\n PolkaVM smart contracts with Ethereum compatibility are in **early-stage development and may be unstable or incomplete**."} +{"page_id": "reference-polkadot-hub-smart-contracts", "page_title": "Polkadot Hub Smart Contracts", "index": 3, "depth": 2, "title": "Where to Go Next", "anchor": "where-to-go-next", "start_char": 2678, "end_char": 3309, "estimated_token_count": 163, "token_estimator": "heuristic-v1", "text": "## Where to Go Next\n\n
\n\n- Guide __Deploy a Basic Contract__\n\n ---\n\n Learn step-by-step how to deploy a basic Solidity smart contract to Polkadot Hub.\n\n [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/smart-contracts/deploy-basic/basic-remix/)\n\n- Guide __Explore Development Environments__\n\n ---\n\n Check out the development environments you can use to build, test, and deploy smart contracts.\n\n [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/local-dev-node/)\n\n
"} {"page_id": "reference-polkadot-hub", "page_title": "Polkadot Hub Overview", "index": 0, "depth": 2, "title": "Introduction", "anchor": "introduction", "start_char": 0, "end_char": 710, "estimated_token_count": 116, "token_estimator": "heuristic-v1", "text": "## Introduction\n\nPolkadot 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.\n\nThe 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."} {"page_id": "reference-polkadot-hub", "page_title": "Polkadot Hub Overview", "index": 1, "depth": 2, "title": "Polkadot Hub Capabilities", "anchor": "polkadot-hub-capabilities", "start_char": 710, "end_char": 1822, "estimated_token_count": 197, "token_estimator": "heuristic-v1", "text": "## Polkadot Hub Capabilities\n\nWhether you're just getting started or building complex applications, the Hub supports the ability to:\n \n- Hold, send, and receive DOT and other assets across the network.\n- Stake DOT to participate in network security and earn rewards.\n- Vote in governance referendums and shape Polkadot's future.\n- Create both fungible and non-fungible tokens and assets for your projects.\n- Pay transaction fees in any asset, not just DOT.\n- Register as an individual and establish your on-chain identity.\n\nFor more sophisticated development use cases, the Hub enables you to:\n\n- Deploy Ethereum-compatible smart contracts using Solidity or other EVM languages.\n- Build decentralized applications that leverage Polkadot's security and interoperability.\n- Create and manage fungible tokens and NFTs with low fees and flexible operations.\n- Manage cross-chain interactions through XCM messaging with other parachains.\n- Set verified identities and apply for network opportunities like the Ambassador Program.\n- Join collectives and participate in governance organizations with specialized roles."} {"page_id": "reference-polkadot-hub", "page_title": "Polkadot Hub Overview", "index": 2, "depth": 2, "title": "Core Components", "anchor": "core-components", "start_char": 1822, "end_char": 1981, "estimated_token_count": 24, "token_estimator": "heuristic-v1", "text": "## Core Components\n\nThe Polkadot Hub consists of several specialized system parachains and services working together as described in the following sections."} diff --git a/llms.txt b/llms.txt index 406aa87c1..54ad1258d 100644 --- a/llms.txt +++ b/llms.txt @@ -6,7 +6,7 @@ This directory lists URLs for raw Markdown pages that complement the rendered pages on the documentation site. Use these Markdown files to retain semantic context when prompting models while avoiding passing HTML elements. ## Metadata -- Documentation pages: 127 +- Documentation pages: 128 - Categories: 13 ## Docs @@ -131,13 +131,14 @@ Docs: Polkadot Protocol - [Networks](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-parachains-networks.md): Explore Polkadot's testing and production networks, including Westend, Kusama, and Paseo, for efficient development, deployment, and testing. - [Node and Runtime](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-parachains-node-and-runtime.md): Learn how Polkadot SDK-based nodes function, how the client and runtime are separated, and how they communicate using SCALE-encoded data. - [Randomness](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-parachains-randomness.md): Explore the importance of randomness in PoS blockchains, focusing on Polkadot’s VRF-based approach to ensure fairness and security in validator selection. -- [Asset Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-assets-and-smart-contracts.md): Learn about Asset Hub in Polkadot, managing on-chain assets, foreign asset integration, and using XCM for cross-chain asset transfers. +- [Polkadot Hub Assets](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-assets.md): Learn about asset management on Polkadot Hub, including on-chain assets, foreign asset integration, and XCM for cross-chain asset transfers. - [Bridge Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-bridging.md): Learn about the Bridge Hub system parachain, a parachain that facilitates the interactions from Polkadot to the rest of Web3. - [Collectives Chain](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-collectives-and-daos.md): Learn how the Collectives chain provides infrastructure for governance organizations, enabling decentralized network stewardship and decision-making. - [Agile Coretime](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-consensus-and-security-agile-coretime.md): Explore the efficient scheduling mechanisms to access Polkadot cores to produce blockspace continuously or on-demand. - [Proof of Stake Consensus](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-consensus-and-security-pos-consensus.md): Explore Polkadot's consensus protocols for secure, scalable, and decentralized network operation, including NPoS, BABE, GRANDPA, and BEEFY. - [Overview of the Polkadot Relay Chain](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-consensus-and-security-relay-chain.md): Explore Polkadot's core architecture, including its multi-chain vision, shared security, and the DOT token's governance and staking roles. - [People Chain](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-people-and-identity.md): Learn how People chain secures decentralized identity management, empowering users to control and verify digital identities without central authorities. +- [Polkadot Hub Smart Contracts](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-smart-contracts.md): Learn how Polkadot Hub supports smart contracts through the REVM, a Rust-based Ethereum Virtual Machine compatible runtime. - [Polkadot Hub Overview](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub.md): Learn how Polkadot Hub serves as the entry point to Polkadot, providing access to smart contracts, staking, governance, identity management, and cross-ecosystem interoperability. - [Technical Reference Overview](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference.md): Learn about Polkadot's technical architecture, governance framework, parachain ecosystem, and the tools you need to build and interact with the network. - [Accounts in Asset Hub Smart Contracts](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-for-eth-devs-accounts.md): Bridges Ethereum's 20-byte addresses with Polkadot's 32-byte accounts, enabling seamless interaction while maintaining compatibility with Ethereum tooling. diff --git a/reference/polkadot-hub/.nav.yml b/reference/polkadot-hub/.nav.yml index 51b83e908..61dfe09e4 100644 --- a/reference/polkadot-hub/.nav.yml +++ b/reference/polkadot-hub/.nav.yml @@ -1,7 +1,8 @@ nav: - 'Overview': index.md + - 'Smart Contracts': smart-contracts.md - 'Consensus and Security': consensus-and-security - - 'Assets and Smart Contracts': assets-and-smart-contracts + - 'Asset Management': assets.md - 'Bridging': bridging.md - 'People and Identity': people-and-identity.md - 'Collectives and DAOs': collectives-and-daos.md diff --git a/reference/polkadot-hub/assets-and-smart-contracts.md b/reference/polkadot-hub/assets-and-smart-contracts.md deleted file mode 100644 index eab4c1bfa..000000000 --- a/reference/polkadot-hub/assets-and-smart-contracts.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: Asset Hub -description: Learn about Asset Hub in Polkadot, managing on-chain assets, foreign asset integration, and using XCM for cross-chain asset transfers. -categories: Polkadot Protocol ---- - -# Asset Hub - -## Introduction - -The Asset Hub is a critical component in the Polkadot ecosystem, enabling the management of fungible and non-fungible assets across the network. Since the relay chain focuses on maintaining security and consensus without direct asset management, Asset Hub provides a streamlined platform for creating, managing, and using on-chain assets in a fee-efficient manner. This guide outlines the core features of Asset Hub, including how it handles asset operations, cross-chain transfers, and asset integration using XCM, as well as essential tools like [API Sidecar](#api-sidecar) and [`TxWrapper`](#txwrapper) for developers working with on-chain assets. - -## Assets Basics - -In the Polkadot ecosystem, the relay chain does not natively support additional assets beyond its native token (DOT for Polkadot, KSM for Kusama). The Asset Hub parachain on Polkadot and Kusama provides a fungible and non-fungible assets framework. Asset Hub allows developers and users to create, manage, and use assets across the ecosystem. - -Asset creators can use Asset Hub to track their asset issuance across multiple parachains and manage assets through operations such as minting, burning, and transferring. Projects that need a standardized method of handling on-chain assets will find this particularly useful. The fungible asset interface provided by Asset Hub closely resembles Ethereum's ERC-20 standard but is directly integrated into Polkadot's runtime, making it more efficient in terms of speed and transaction fees. - -Integrating with Asset Hub offers several key benefits, particularly for infrastructure providers and users: - -- **Support for non-native on-chain assets**: Asset Hub enables seamless asset creation and management, allowing projects to develop tokens or assets that can interact with the broader ecosystem. -- **Lower transaction fees**: Asset Hub offers significantly lower transaction costs—approximately one-tenth of the fees on the relay chain, providing cost-efficiency for regular operations. -- **Reduced deposit requirements**: Depositing assets in Asset Hub is more accessible, with deposit requirements that are around one one-hundredth of those on the relay chain. -- **Payment of transaction fees with non-native assets**: Users can pay transaction fees in assets other than the native token (DOT or KSM), offering more flexibility for developers and users. - -Assets created on the Asset Hub are stored as part of a map, where each asset has a unique ID that links to information about the asset, including details like: - -- The management team. -- The total supply. -- The number of accounts holding the asset. -- **Sufficiency for account existence**: Whether the asset alone is enough to maintain an account without a native token balance. -- The metadata of the asset, including its name, symbol, and the number of decimals for representation. - -Some assets can be regarded as sufficient to maintain an account's existence, meaning that users can create accounts on the network without needing a native token balance (i.e., no existential deposit required). Developers can also set minimum balances for their assets. If an account's balance drops below the minimum, the balance is considered dust and may be cleared. - -## Assets Pallet - -The Polkadot SDK's Assets pallet is a powerful module designated for creating and managing fungible asset classes with a fixed supply. It offers a secure and flexible way to issue, transfer, freeze, and destroy assets. The pallet supports various operations and includes permissioned and non-permissioned functions to cater to simple and advanced use cases. - -Visit the [Assets Pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank} for more in-depth information. - -### Key Features - -Key features of the Assets pallet include: - -- **Asset issuance**: Allows the creation of a new asset, where the total supply is assigned to the creator's account. -- **Asset transfer**: Enables transferring assets between accounts while maintaining a balance in both accounts. -- **Asset freezing**: Prevents transfers of a specific asset from one account, locking it from further transactions. -- **Asset destruction**: Allows accounts to burn or destroy their holdings, removing those assets from circulation. -- **Non-custodial transfers**: A non-custodial mechanism to enable one account to approve a transfer of assets on behalf of another. - -### Main Functions - -The Assets pallet provides a broad interface for managing fungible assets. Some of the main dispatchable functions include: - -- **`create()`**: Create a new asset class by placing a deposit, applicable when asset creation is permissionless. -- **`issue()`**: Mint a fixed supply of a new asset and assign it to the creator's account. -- **`transfer()`**: Transfer a specified amount of an asset between two accounts. -- **`approve_transfer()`**: Approve a non-custodial transfer, allowing a third party to move assets between accounts. -- **`destroy()`**: Destroy an entire asset class, removing it permanently from the chain. -- **`freeze()` and `thaw()`**: Administrators or privileged users can lock or unlock assets from being transferred. - -For a full list of dispatchable and privileged functions, see the [dispatchables Rust docs](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/enum.Call.html){target=\_blank}. - -### Querying Functions - -The Assets pallet exposes several key querying functions that developers can interact with programmatically. These functions allow you to query asset information and perform operations essential for managing assets across accounts. The two main querying functions are: - -- **`balance(asset_id, account)`**: Retrieves the balance of a given asset for a specified account. Useful for checking the holdings of an asset class across different accounts. - -- **`total_supply(asset_id)`**: Returns the total supply of the asset identified by `asset_id`. Allows users to verify how much of the asset exists on-chain. - -In addition to these basic functions, other utility functions are available for querying asset metadata and performing asset transfers. You can view the complete list of querying functions in the [Struct Pallet Rust docs](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/struct.Pallet.html){target=\_blank}. - -### Permission Models and Roles - -The Assets pallet incorporates a robust permission model, enabling control over who can perform specific operations like minting, transferring, or freezing assets. The key roles within the permission model are: - -- **Admin**: Can freeze (preventing transfers) and forcibly transfer assets between accounts. Admins also have the power to reduce the balance of an asset class across arbitrary accounts. They manage the more sensitive and administrative aspects of the asset class. -- **Issuer**: Responsible for minting new tokens. When new assets are created, the Issuer is the account that controls their distribution to other accounts. -- **Freezer**: Can lock the transfer of assets from an account, preventing the account holder from moving their balance. This function is useful for freezing accounts involved in disputes or fraud. -- **Owner**: Has overarching control, including destroying an entire asset class. Owners can also set or update the Issuer, Freezer, and Admin roles. - -These permissions provide fine-grained control over assets, enabling developers and asset managers to ensure secure, controlled operations. Each of these roles is crucial for managing asset lifecycles and ensuring that assets are used appropriately across the network. - -### Asset Freezing - -The Assets pallet allows you to freeze assets. This feature prevents transfers or spending from a specific account, effectively locking the balance of an asset class until it is explicitly unfrozen. Asset freezing is beneficial when assets are restricted due to security concerns or disputes. - -Freezing assets is controlled by the Freezer role, as mentioned earlier. Only the account with the Freezer privilege can perform these operations. Here are the key freezing functions: - -- **`freeze(asset_id, account)`**: Locks the specified asset of the account. While the asset is frozen, no transfers can be made from the frozen account. -- **`thaw(asset_id, account)`**: Corresponding function for unfreezing, allowing the asset to be transferred again. - -This approach enables secure and flexible asset management, providing administrators the tools to control asset movement in special circumstances. - -### Non-Custodial Transfers (Approval API) - -The Assets pallet also supports non-custodial transfers through the Approval API. This feature allows one account to approve another account to transfer a specific amount of its assets to a third-party recipient without granting full control over the account's balance. Non-custodial transfers enable secure transactions where trust is required between multiple parties. - -Here's a brief overview of the key functions for non-custodial asset transfers: - -- **`approve_transfer(asset_id, delegate, amount)`**: Approves a delegate to transfer up to a certain amount of the asset on behalf of the original account holder. -- **`cancel_approval(asset_id, delegate)`**: Cancels a previous approval for the delegate. Once canceled, the delegate no longer has permission to transfer the approved amount. -- **`transfer_approved(asset_id, owner, recipient, amount)`**: Executes the approved asset transfer from the owner’s account to the recipient. The delegate account can call this function once approval is granted. - -These delegated operations make it easier to manage multi-step transactions and dApps that require complex asset flows between participants. - -## Foreign Assets - -Foreign assets in Asset Hub refer to assets originating from external blockchains or parachains that are registered in the Asset Hub. These assets are typically native tokens from other parachains within the Polkadot ecosystem or bridged tokens from external blockchains such as Ethereum. - -Once a foreign asset is registered in the Asset Hub by its originating blockchain's root origin, users are able to send these tokens to the Asset Hub and interact with them as they would any other asset within the Polkadot ecosystem. - -### Handling Foreign Assets - -The Foreign Assets pallet, an instance of the Assets pallet, manages these assets. Since foreign assets are integrated into the same interface as native assets, developers can use the same functionalities, such as transferring and querying balances. However, there are important distinctions when dealing with foreign assets. - -- **Asset identifier**: Unlike native assets, foreign assets are identified using an XCM Multilocation rather than a simple numeric `AssetId`. This multilocation identifier represents the cross-chain location of the asset and provides a standardized way to reference it across different parachains and relay chains. - -- **Transfers**: Once registered in the Asset Hub, foreign assets can be transferred between accounts, just like native assets. Users can also send these assets back to their originating blockchain if supported by the relevant cross-chain messaging mechanisms. - -## Integration - -Asset Hub supports a variety of integration tools that make it easy for developers to manage assets and interact with the blockchain in their applications. The tools and libraries provided by Parity Technologies enable streamlined operations, such as querying asset information, building transactions, and monitoring cross-chain asset transfers. - -Developers can integrate Asset Hub into their projects using these core tools: - -### API Sidecar - -[API Sidecar](https://github.com/paritytech/substrate-api-sidecar){target=\_blank} is a RESTful service that can be deployed alongside Polkadot and Kusama nodes. It provides endpoints to retrieve real-time blockchain data, including asset information. When used with Asset Hub, Sidecar allows querying: - -- **Asset look-ups**: Retrieve specific assets using `AssetId`. -- **Asset balances**: View the balance of a particular asset on Asset Hub. - -Public instances of API Sidecar connected to Asset Hub are available, such as: - -- [Polkadot Asset Hub Sidecar](https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/){target=\_blank} -- [Kusama Asset Hub Sidecar](https://kusama-asset-hub-public-sidecar.parity-chains.parity.io/){target=\_blank} - -These public instances are primarily for ad-hoc testing and quick checks. - -### TxWrapper - -[`TxWrapper`](https://github.com/paritytech/txwrapper-core){target=\_blank} is a library that simplifies constructing and signing transactions for Polkadot SDK-based chains, including Polkadot and Kusama. This tool includes support for working with Asset Hub, enabling developers to: - -- Construct offline transactions. -- Leverage asset-specific functions such as minting, burning, and transferring assets. - -`TxWrapper` provides the flexibility needed to integrate asset operations into custom applications while maintaining the security and efficiency of Polkadot's transaction model. - - -### Parachain Node - -To fully leverage the Asset Hub's functionality, developers will need to run a system parachain node. Setting up an Asset Hub node allows users to interact with the parachain in real time, syncing data and participating in the broader Polkadot ecosystem. Guidelines for setting up an [Asset Hub node](https://github.com/paritytech/polkadot-sdk/tree/{{dependencies.repositories.polkadot_sdk.version}}/cumulus#asset-hub-){target=\_blank} are available in the Parity documentation. - -Using these integration tools, developers can manage assets seamlessly and integrate Asset Hub functionality into their applications, leveraging Polkadot's powerful infrastructure. - -## XCM Transfer Monitoring - -Since Asset Hub facilitates cross-chain asset transfers across the Polkadot ecosystem, XCM transfer monitoring becomes an essential practice for developers and infrastructure providers. This section outlines how to monitor the cross-chain movement of assets between parachains, the relay chain, and other systems. - -### Monitor XCM Deposits - -As assets move between chains, tracking the cross-chain transfers in real time is crucial. Whether assets are transferred via a teleport from system parachains or through a reserve-backed transfer from any other parachain, each transfer emits a relevant event (such as the `balances.minted` event). - -To ensure accurate monitoring of these events: - -- **Track XCM deposits**: Query every new block created in the relay chain or Asset Hub, loop through the events array, and filter for any `balances.minted` events which confirm the asset was successfully transferred to the account. -- **Track event origins**: Each `balances.minted` event points to a specific address. By monitoring this, service providers can verify that assets have arrived in the correct account. - -### Track XCM Information Back to the Source - -While the `balances.minted` event confirms the arrival of assets, there may be instances where you need to trace the origin of the cross-chain message that triggered the event. In such cases, you can: - -1. Query the relevant chain at the block where the `balances.minted` event was emitted. -2. Look for a `messageQueue(Processed)` event within that block's initialization. This event contains a parameter (`Id`) that identifies the cross-chain message received by the relay chain or Asset Hub. You can use this `Id` to trace the message back to its origin chain, offering full visibility of the asset transfer's journey. - -### Practical Monitoring Examples - -The preceding sections outline the process of monitoring XCM deposits to specific accounts and then tracing back the origin of these deposits. The process of tracking an XCM transfer and the specific events to monitor may vary based on the direction of the XCM message. Here are some examples to showcase the slight differences: - -- **Transfer from parachain to relay chain**: Track `parachainsystem(UpwardMessageSent)` on the parachain and `messagequeue(Processed)` on the relay chain. -- **Transfer from relay chain to parachain**: Track `xcmPallet(sent)` on the relay chain and `dmpqueue(ExecutedDownward)` on the parachain. -- **Transfer between parachains**: Track `xcmpqueue(XcmpMessageSent)` on the system parachain and `xcmpqueue(Success)` on the destination parachain. - -### Monitor for Failed XCM Transfers - -Sometimes, XCM transfers may fail due to liquidity or other errors. Failed transfers emit specific error events, which are key to resolving issues in asset transfers. Monitoring for these failure events helps catch issues before they affect asset balances. - -- **Relay chain to system parachain**: Look for the `dmpqueue(ExecutedDownward)` event on the parachain with an `Incomplete` outcome and an error type such as `UntrustedReserveLocation`. -- **Parachain to parachain**: Monitor for `xcmpqueue(Fail)` on the destination parachain with error types like `TooExpensive`. - -For detailed error management in XCM, see Gavin Wood's blog post on [XCM Execution and Error Management](https://polkadot.com/blog/xcm-part-three-execution-and-error-management/){target=\_blank}. - -## Where to Go Next - -
- -- Tutorial __Register a Local Asset__ - - --- - - Comprehensive guide to registering a local asset on the Asset Hub system parachain, including step-by-step instructions. - - [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/register-local-asset/) - -- Tutorial __Register a Foreign Asset__ - - --- - - An in-depth guide to registering a foreign asset on the Asset Hub parachain, providing clear, step-by-step instructions. - - [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/register-foreign-asset/) - -- Tutorial __Convert Assets__ - - --- - - A guide detailing the step-by-step process of converting assets on Asset Hub, helping users efficiently navigate asset management on the platform. - - [:octicons-arrow-right-24: Reference](/chain-interactions/token-operations/convert-assets/) - -
\ No newline at end of file diff --git a/reference/polkadot-hub/assets.md b/reference/polkadot-hub/assets.md new file mode 100644 index 000000000..c3d35f350 --- /dev/null +++ b/reference/polkadot-hub/assets.md @@ -0,0 +1,163 @@ +--- +title: Polkadot Hub Assets +description: Learn about asset management on Polkadot Hub, including on-chain assets, foreign asset integration, and XCM for cross-chain asset transfers. +categories: Polkadot Protocol +--- + +# Assets on Polkadot Hub + +## Introduction + +Polkadot Hub is Polkadot’s system parachain that provides core functionality for the network, including issuing and managing on-chain assets. While the relay chain provides security, Polkadot Hub handles asset logic—minting, burning, transfers, and metadata—efficiently and cost-effectively. + +Polkadot Hub supports native assets issued on the parachain and foreign assets from other chains, both of which can move seamlessly across the network via XCM. + +This guide explains how assets are created, managed, and moved across chains, including key operations, roles, and the differences between native and foreign assets. + +## Why Use Polkadot Hub? + +Polkadot Hub provides a standardized framework for creating and managing fungible and non-fungible assets. Projects can issue tokens, manage supply, and transfer assets across parachains, extending the functionality of the Polkadot relay chain, which only supports its native token (DOT). + +**Key features**: + +- **Built-in asset operations**: Mint, burn, and transfer like ERC-20 on Ethereum, but native to Polkadot's runtime. +- **Custom asset creation**: Issue tokens or NFTs with configurable permissions and metadata. +- **Low fees**: Transactions cost roughly one-tenth of relay chain fees. +- **Lower deposits**: Minimal on-chain storage costs for asset data. +- **Pay fees in any asset**: Users don’t need DOT to transact; supported assets can cover fees. +- **Cross-chain ready**: Assets can be transferred to other parachains using XCM. + +## Types of Assets + +Polkadot Hub supports two types of assets: + +- **Native assets**: Tokens and NFTs issued directly on Polkadot Hub using the Assets pallet. These assets benefit from the platform's custom features, such as configurable permissions and low fees +- **Foreign assets**: Tokens originating from other Polkadot parachains or external networks (like Ethereum, via bridges). Once registered on Polkadot Hub, they are treated similarly to native assets. + +## Asset Structure + +Each asset is identified by a unique ID and stores: + +- Asset administrators +- Total supply and holder count +- Minimum balance configuration +- Sufficiency–whether the asset can keep an account alive without DOT +- Metadata (name, symbol, decimals) + +If a balance falls below the configured minimum, called the [existential deposit](/reference/glossary/#existential-deposit){target=\_blank}, it may be removed as “dust.” This ensures efficient storage while giving developers control over asset economics. + +## How Native Assets Work + +Native assets on Polkadot Hub are created and managed via the Assets pallet from the Polkadot SDK. This pallet defines the runtime logic for issuing, configuring, and administering fungible assets with customizable permissions. + +It supports both permissioned and permissionless asset creation, enabling everything from simple user-issued tokens to governed assets controlled by teams or DAOs. + +For implementation details, see the [Assets Pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank}. + +### Asset Operations + +The Assets pallet provides both state-changing operations and read-only queries for full lifecycle management of assets. + +Core operations include: + +- **Asset issuance**: Create new assets and assign initial supply. +- **Transfers**: Move assets between accounts with balance tracking. +- **Burning**: Reduce total supply by destroying tokens. +- **Delegated transfers**: Approve transfers on behalf of another account without giving up custody. +- **Freezing and thawing**: Temporarily lock and unlock an account's balance. + +For a complete list of extrinsics, see the [`pallet-assets` dispatchable functions reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/enum.Call.html){target=\_blank}. + +Data queries make it possible to: + +- Check account balances and total supply. +- Retrieve asset metadata and configuration details. +- Inspect account and asset status on-chain. + +For a full list of queries, see the [Pallet reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/struct.Pallet.html){target=\_blank}. + +### Roles and Permissions + +The Assets pallet uses role-based permissions to control who can manage different parts of an asset’s lifecycle: + +- **Owner**: Overarching control, including destroying an asset class; can set or update Issuer, Freezer, and Admin roles. +- **Admin**: Can freeze assets and forcibly transfer balances between accounts. Admins can also reduce the balance of an asset class across arbitrary accounts. +- **Issuer**: Responsible for minting new tokens. When new assets are created, the Issuer is the account that controls their distribution to other accounts. +- **Freezer**: Can lock the transfer of assets from an account, preventing the account holder from moving their balance. + +These roles allow projects to enforce governance and security policies around their assets. + +### Freezing Assets + +Assets can be temporarily locked to prevent transfers from specific accounts. This is useful for dispute resolution, fraud prevention, or compliance controls. + +**How it works**: + +- Only authorized parties can freeze or unfreeze (thaw) assets. +- Freezing pauses the movement of the asset without burning or removing it. +- Once thawed, the asset can be transferred normally. + +Freezing provides a safe way to control asset flow while maintaining full ownership. + +**Key functions**: `freeze` and `thaw`. + +### Delegated Transfers + +Polkadot Hub supports delegated asset transfers, allowing one account to authorize another to move a limited amount of its assets—without giving up full control. This is useful for escrow logic, automated payments, and multi-party applications. + +**How it works**: + +- An account can grant permission to another account to transfer a specific amount of its assets. +- Permissions can be revoked at any time, preventing further transfers. +- Authorized accounts can execute transfers on behalf of the original owner within the approved limits. + +Delegated transfers simplify multi-step transactions and enable complex asset flows. + +**Key functions**: `approve_transfer`, `cancel_approval`, and `transfer_approved`. + +## How Foreign Assets Work + +Foreign assets are assets originating from other chains and are managed on Polkadot Hub via an instance of the Assets pallet that is configured specifically for foreign assets. It enables transfers, balance checks, and other standard asset operations, while handling foreign-asset specifics such as: + +- **Asset identifiers**: Foreign assets use an XCM multilocation as their identifier, rather than a numeric AssetId. This ensures assets from different chains can be referenced and moved safely across parachains. + +- **Transfers**: Once registered on Polkadot Hub, foreign assets can be transferred between accounts just like native assets. If supported, they can also be returned to their original blockchain using cross-chain messaging. + +This unified interface makes it easy for dApps to handle both native and cross-chain assets. + +## Moving Assets Across Chains + +Polkadot Hub enables assets to move safely between parachains and the relay chain using XCM (Cross-Consensus Messaging). XCM ensures assets can move securely between chains while preserving ownership and traceability + +To learn more about asset transfers with XCM, please refer to the [Introduction to XCM](/parachains/interoperability/get-started/) page. + + + \ No newline at end of file diff --git a/reference/polkadot-hub/smart-contracts.md b/reference/polkadot-hub/smart-contracts.md new file mode 100644 index 000000000..0976d47e6 --- /dev/null +++ b/reference/polkadot-hub/smart-contracts.md @@ -0,0 +1,63 @@ +--- +title: Polkadot Hub Smart Contracts +description: Learn how Polkadot Hub supports smart contracts through the REVM, a Rust-based Ethereum Virtual Machine compatible runtime. +categories: Polkadot Protocol +--- + +# Smart Contracts on Polkadot Hub + +## Introduction + +Polkadot Hub enables developers to deploy and interact with Solidity contracts through REVM, a high-performance, Rust-based Ethereum Virtual Machine implementation. Polkadot-native precompiles bring Ethereum compatibility to Polkadot Hub, letting teams use familiar Solidity tooling, integrate with on-chain features like governance and XCM, and take advantage of cross-chain interoperability. + +For projects that require maximum computational performance, Polkadot Hub also supports PolkaVM (PVM), a native RISC-V execution engine. PVM is optional and designed for high-throughput, performance-intensive smart contracts. + +### REVM Smart Contracts + +[REVM](https://github.com/bluealloy/revm){target=_blank} brings full EVM compatibility to Polkadot Hub through a fast, memory-safe Rust implementation of the Ethereum Virtual Machine. Unlike PolkaVM, which compiles contracts to RISC-V for native execution, REVM executes standard Ethereum bytecode directly—making it ideal for teams who want to migrate existing Solidity projects to Polkadot with minimal changes. + +With REVM, developers can: + +- Deploy existing Solidity contracts without rewriting them. +- Use familiar Ethereum tooling like Hardhat, Foundry, Remix, and MetaMask. +- Interact with other parachains and on-chain assets using XCM and Polkadot Hub features. + +REVM builds on Rust’s safety guarantees and performance optimizations while retaining full opcode compatibility with the EVM. + +Ethereum-native developers can use Polkadot-native precompiles to access Polkadot features—such as governance, treasury, multisig, and XCM—within a unified, interoperable runtime environment. + +### PVM Smart Contracts + +PVM is Polkadot Hub’s native, high-performance smart contract engine. Instead of emulating EVM bytecode, it runs contracts compiled to a [RISC-V](https://en.wikipedia.org/wiki/RISC-V){target=_blank} instruction set, unlocking higher performance and parallel execution while staying friendly to Ethereum-style development. + +With PVM, developers can: + +- Write Solidity contracts and use familiar tooling (e.g., Hardhat, Foundry) targeting PVM +- Benefit from fast, predictable execution with carefully metered gas/weight. +- Access detailed observability through Substrate events and contract logs for indexing and debugging. + +PolkaVM delivers maximum performance for computationally intensive contracts, offering a native, high-throughput option for Ethereum-style developers on Polkadot Hub. + +--8<-- 'text/smart-contracts/polkaVM-warning.md' + +## Where to Go Next + +
+ +- Guide __Deploy a Basic Contract__ + + --- + + Learn step-by-step how to deploy a basic Solidity smart contract to Polkadot Hub. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/cookbook/smart-contracts/deploy-basic/basic-remix/) + +- Guide __Explore Development Environments__ + + --- + + Check out the development environments you can use to build, test, and deploy smart contracts. + + [:octicons-arrow-right-24: Get Started](/smart-contracts/dev-environments/local-dev-node/) + +
\ No newline at end of file