Skip to content

Commit c3bd29a

Browse files
kapetan3sidkapetan3sid
committed
add smart contract page
1 parent 265ec38 commit c3bd29a

File tree

1 file changed

+39
-117
lines changed

1 file changed

+39
-117
lines changed

‎reference/polkadot-hub/smart-contracts.md‎

Lines changed: 39 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,150 +1,72 @@
11
---
2-
title: Smart Contracts
3-
description: Learn how developers can build smart contracts on Polkadot by leveraging either Wasm/ink! or EVM contracts across many parachains.
2+
title: Asset Hub Smart Contracts
3+
description: Learn how developers can build smart contracts on Asset Hub by leveraging either Wasm/ink! or EVM contracts across many parachains.
44
categories: Basics, Polkadot Protocol
55
---
66

7-
# An Overview of the Smart Contract Landscape on Polkadot
7+
# Smart Contracts on Asset Hub
88

99
--8<-- 'text/smart-contracts/polkaVM-warning.md'
1010

1111
## Introduction
1212

13-
Polkadot is designed to support an ecosystem of parachains, rather than hosting smart contracts directly. Developers aiming to build smart contract applications on Polkadot rely on parachains within the ecosystem that provide smart contract functionality.
14-
15-
This guide outlines the primary approaches to developing smart contracts in the Polkadot ecosystem:
16-
17-
- **PolkaVM-compatible contracts**: Support Solidity and any language that compiles down to RISC-V while maintaining compatibility with Ethereum based tools.
18-
- **EVM-compatible contracts**: Support languages like [Solidity](https://soliditylang.org/){target=\_blank} and [Vyper](https://vyperlang.org/){target=\_blank}, offering compatibility with popular Ethereum tools and wallets.
19-
- **Wasm-based smart contracts**: Using [ink!](https://use.ink/){target=\_blank}, a Rust-based embedded domain-specific language (eDSL), enabling developers to leverage Rust’s safety and tooling.
20-
21-
You'll explore the key differences between these development paths, along with considerations for parachain developers integrating smart contract functionality.
22-
23-
One of the
24-
25-
!!!note "Parachain Developer?"
26-
If you are a parachain developer looking to add smart contract functionality to your chain, please refer to the [Add Smart Contract Functionality](/parachains/customize-runtime/add-smart-contract-functionality){target=\_blank} page, which covers both Wasm and EVM-based contract implementations.
27-
28-
## Smart Contracts Versus Parachains
29-
30-
A smart contract is a program that executes specific logic isolated to the chain on which it is being executed. All the logic executed is bound to the same state transition rules determined by the underlying virtual machine (VM). Consequently, smart contracts are more streamlined to develop, and programs can easily interact with each other through similar interfaces.
31-
32-
``` mermaid
33-
flowchart LR
34-
subgraph A[Chain State]
35-
direction LR
36-
B["Program Logic and Storage<br/>(Smart Contract)"]
37-
C["Tx Relevant Storage"]
38-
end
39-
A --> D[[Virtual Machine]]
40-
E[Transaction] --> D
41-
D --> F[(New State)]
42-
D --> G[Execution Logs]
43-
style A stroke:#000000,stroke-width:1px
44-
```
45-
46-
In addition, because smart contracts are programs that execute on top of existing chains, teams don't have to think about the underlying consensus they are built on.
47-
48-
These strengths do come with certain limitations. Some smart contracts environments, like EVM, tend to be immutable by default. Developers have developed different [proxy strategies](https://www.openzeppelin.com/news/proxy-patterns){target=\_blank} to be able to upgrade smart contracts over time. The typical pattern relies on a proxy contract which holds the program storage forwarding a call to an implementation contract where the execution logic resides. Smart contract upgrades require changing the implementation contract while retaining the same storage structure, necessitating careful planning.
49-
50-
Another downside is that smart contracts often follow a gas metering model, where program execution is associated with a given unit and a marketplace is set up to pay for such an execution unit. This fee system is often very rigid, and some complex flows, like account abstraction, have been developed to circumvent this problem.
51-
52-
In contrast, parachains can create their own custom logics (known as pallets or modules), and combine them as the state transition function (STF or runtime) thanks to the modularity provided by the [Polkadot-SDK](https://github.com/paritytech/polkadot-sdk/){target=\_blank}. The different pallets within the parachain runtime can give developers a lot of flexibility when building applications on top of it.
53-
54-
``` mermaid
55-
flowchart LR
56-
A[(Chain State)] --> B[["STF<br/>[Pallet 1]<br/>[Pallet 2]<br/>...<br/>[Pallet N]"]]
57-
C[Transaction<br/>Targeting Pallet 2] --> B
58-
B --> E[(New State)]
59-
B --> F[Execution Logs]
60-
```
61-
62-
Parachains inherently offer features such as logic upgradeability, flexible transaction fee mechanisms, and chain abstraction logic. More so, by using Polkadot, parachains can benefit from robust consensus guarantees with little engineering overhead.
63-
64-
To read more about the differences between smart contracts and parachain runtimes, see the [Runtime vs. Smart Contracts](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/runtime_vs_smart_contract/index.html){target=\_blank} section of the Polkadot SDK Rust docs. For a more in-depth discussion about choosing between runtime development and smart contract development, see the Stack Overflow post on [building a Polkadot SDK runtime versus a smart contract](https://stackoverflow.com/a/56041305){target=\_blank}.
13+
Polkadot’s Relay Chain does not support smart contracts directly, so developers build contract-based applications on parachains that provide execution environments. Asset Hub is one of those parachains, offering flexible smart contract capabilities alongside native asset management.
6514

6615
## Building a Smart Contract
6716

68-
The Polkadot SDK supports multiple smart contract execution environments:
69-
70-
- **PolkaVM**: A cutting-edge virtual machine tailored to optimize smart contract execution on Polkadot. Unlike traditional EVMs, PolkaVM is built with a [RISC-V-based register architecture](https://en.wikipedia.org/wiki/RISC-V){target=\_blank} for increased performance and scalability.
71-
- **EVM**: Through [Frontier](https://github.com/polkadot-evm/frontier){target=\_blank}. It consists of a full Ethereum JSON RPC compatible client, an Ethereum emulation layer, and a [Rust-based EVM](https://github.com/rust-ethereum/evm){target=\_blank}. This is used by chains like [Acala](https://acala.network/){target=\_blank}, [Astar](https://astar.network/){target=\_blank}, [Moonbeam](https://moonbeam.network){target=\_blank} and more.
72-
- **Wasm**: [ink!](https://use.ink/){target=\_blank} is a domain-specific language (DSL) for Rust smart contract development that uses the [Contracts pallet](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/contracts/){target=\_blank} with [`cargo-contract`](https://github.com/use-ink/cargo-contract){target=\_blank} serving as the compiler to WebAssembly. Wasm contracts can be used by chains like [Astar](https://astar.network/){target=\_blank}.
17+
Asset Hub supports multiple smart contract environments, giving developers the freedom to choose the workflow and tooling that best fits their project:
7318

74-
### PolkaVM Contracts
19+
- **PolkaVM**: A next-generation virtual machine designed specifically for Polkadot. Built on a high-performance [RISC-V-based register architecture](https://en.wikipedia.org/wiki/RISC-V){target=_blank}, PolkaVM enables fast, scalable execution and is optimized for modern smart contract development.
20+
- **REVM**: The [REVM backend](https://github.com/bluealloy/revm){target=_blank} brings a full Rust implementation of the EVM to Asset Hub. This allows developers to deploy existing Solidity contracts without modification, preserving compatibility with Ethereum tools and libraries.
7521

76-
A component of the Asset Hub parachain, PolkaVM helps enable the deployment of Solidity-based smart contracts directly on Asset Hub. Learn more about how this cutting edge virtual machine facilitates using familiar Ethereum-compatible contracts and tools with Asset Hub by visiting the [Native Smart Contracts](/develop/smart-contracts/overview#native-smart-contracts){target=\_blank} guide.
22+
Each of these environments is fully compatible with Asset Hub, giving teams the option to reuse Ethereum code, build with Rust security guarantees, or explore high-performance innovation with PolkaVM.
7723

78-
### EVM Contracts
79-
80-
The [Frontier](https://github.com/polkadot-evm/frontier){target=\_blank} project provides a set of modules that enables a Polkadot SDK-based chain to run an Ethereum emulation layer that allows the execution of EVM smart contracts natively with the same API/RPC interface.
81-
82-
[Ethereum addresses (ECDSA)](https://ethereum.org/en/glossary/#address){target=\_blank} can also be mapped directly to and from the Polkadot SDK's SS58 scheme from existing accounts. Moreover, you can modify Polkadot SDK to use the ECDSA signature scheme directly to avoid any mapping.
83-
84-
At a high level, [Frontier](https://github.com/polkadot-evm/frontier){target=\_blank} is composed of three main components:
24+
### PolkaVM Contracts
8525

86-
- **[Ethereum Client](https://github.com/polkadot-evm/frontier/tree/master/client){target=\_blank}**: An Ethereum JSON RPC compliant client that allows any request coming from an Ethereum tool, such as [Remix](https://remix.ethereum.org/){target=\_blank}, [Hardhat](https://hardhat.org/){target=\_blank} or [Foundry](https://getfoundry.sh/){target=\_blank}, to be admitted by the network.
87-
- **[Pallet Ethereum](https://docs.rs/pallet-ethereum/latest/pallet_ethereum/){target=\_blank}**: A block emulation and Ethereum transaction validation layer that works jointly with the Ethereum client to ensure compatibility with Ethereum tools.
88-
- **[Pallet EVM](https://docs.rs/pallet-evm/latest/pallet_evm/){target=\_blank}**: Access layer to the [Rust-based EVM](https://github.com/rust-ethereum/evm){target=\_blank}, enabling the execution of EVM smart contract logic natively.
26+
PolkaVM is Asset Hub’s native execution environment for smart contracts, designed to go beyond the limitations of the traditional EVM. Instead of emulating Ethereum bytecode, PolkaVM uses a high-performance RISC-V instruction set to natively execute smart contracts.
8927

90-
The following diagram illustrates a high-level overview of the path an EVM transaction follows when using this configuration:
28+
This architecture enables faster execution, better parallelization, and lower resource consumption while still maintaining compatibility with Solidity tooling.
9129

92-
``` mermaid
93-
flowchart TD
94-
A[Users and Devs] -->|Send Tx| B[Frontier RPC Ext]
95-
subgraph C[Pallet Ethereum]
96-
D[Validate Tx]
97-
E[Send<br/>Valid Tx]
98-
end
99-
B -->|Interact with| C
100-
D --> E
101-
subgraph F[Pallet EVM]
102-
G[Rust EVM]
103-
end
104-
I[(Current EVM<br/>Emulated State)]
30+
Smart contracts written for PolkaVM compile down to a RISC-V bytecode format, which is optimized for verification and execution within Polkadot’s Wasm-based runtime. Developers can interact with PolkaVM using familiar Ethereum developer tools.
10531

106-
H[Smart Contract<br/>Solidity, Vyper...] <-->|Compiled to EVM<br/>Bytecode| I
32+
### REVM Contracts
10733

108-
C --> F
109-
I --> F
110-
F --> J[(New Ethereum<br/>Emulated State)]
111-
F --> K[Execution Logs]
34+
### PolkaVM Contracts
11235

113-
style C stroke:#000000,stroke-width:1px
114-
style F stroke:#000000,stroke-width:1px
115-
```
36+
PolkaVM is Asset Hub’s native, high-performance smart contract engine. Instead of emulating EVM bytecode, it executes contracts compiled to a RISC-V instruction set, giving tighter control over execution, metering, and parallelization while staying friendly to Ethereum-style development.
11637

117-
Although it seems complex, users and developers are abstracted of that complexity, and tools can easily interact with the parachain as they would with any other Ethereum-compatible environment.
38+
**What it enables for developers**
39+
- **Ethereum-compatible development** – Write contracts in Solidity and use familiar tooling (e.g., Hardhat/Foundry workflows) with PolkaVM targets.
40+
- **Fast, predictable execution** – RISC-V bytecode is designed for efficient interpretation and careful gas/weight metering within the Substrate runtime.
41+
- **Seamless Asset Hub integration** – Call into native pallets (Assets / Foreign Assets), use fee payment options, and compose with XCM for cross-chain flows.
42+
- **Better observability** – Substrate events + contract logs for clean indexing and debugging.
11843

119-
The Rust EVM is capable of executing regular [EVM bytecode](https://www.ethervm.io/){target=\_blank}. Consequently, any language that compiles to EVM bytecode can be used to create programs that the parachain can execute.
44+
**How it works (at a glance)**
12045

121-
### Wasm Contracts
46+
1. **Author & compile** – Your Solidity contract is compiled for PolkaVM (RISC-V target), producing bytecode plus ABI.
47+
2. **Deploy** – Submit a signed extrinsic to Asset Hub; collators include it in a parachain block.
48+
3. **Execute** – PolkaVM runs the contract code, mapping gas ↔ weight and persisting state via Substrate storage.
49+
4. **Integrate** – Contracts can interact with Asset Hub pallets and send/receive XCM messages for cross-chain actions.
50+
5. **Finalize & index** – The Relay Chain finalizes the block; events/logs are available to indexers and UIs.
12251

123-
The [`pallet_contracts`](https://docs.rs/pallet-contracts/latest/pallet_contracts/index.html#contracts-pallet){target=\_blank} provides the execution environment for Wasm-based smart contracts. Consequently, any smart contract language that compiles to Wasm can be executed in a parachain that enables this module.
52+
**When to choose PolkaVM**
12453

125-
At the time of writing there are two main languages that can be used for Wasm programs:
54+
- You want **max performance** and tighter execution control than a traditional EVM.
55+
- You plan to **compose with Substrate pallets** (assets, governance) and **XCM** frequently.
56+
- You prefer a path that’s **Solidity-friendly** but optimized for Polkadot’s architecture.
12657

127-
- **[ink!](https://use.ink/){target=\_blank}**: A Rust-based language that compiles to Wasm. It allows developers to inherit all its safety guarantees and use normal Rust tooling, being the dedicated domain-specific language.
128-
- **Solidity**: Can be compiled to Wasm via the [Solang](https://github.com/hyperledger-solang/solang/){target=\_blank} compiler. Consequently, developers can write Solidity 0.8 smart contracts that can be executed as Wasm programs in parachains.
58+
### REVM Contracts
12959

130-
The following diagram illustrates a high-level overview of the path a transaction follows when using [`pallet_contracts`](https://docs.rs/pallet-contracts/latest/pallet_contracts/index.html#contracts-pallet){target=\_blank}:
60+
REVM brings full EVM compatibility to Asset 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.
13161

132-
``` mermaid
133-
flowchart TD
134-
135-
subgraph A[Wasm Bytecode API]
136-
C[Pallet Contracts]
137-
end
62+
With REVM, developers can:
13863

139-
B[Users and Devs] -- Interact with ---> A
140-
141-
D[(Current State)]
64+
- Deploy existing Solidity contracts without rewriting them.
65+
- Use familiar Ethereum tooling like Hardhat, Foundry, Remix, and MetaMask.
66+
- Interact with other parachains and on-chain assets using XCM and Asset Hub features.
14267

143-
E[Smart Contract<br/>ink!, Solidity...] <-->|Compiled to Wasm<br/>Bytecode| D
68+
REVM builds on Rust’s safety guarantees and performance optimizations while retaining full opcode compatibility with the EVM. This provides a reliable path for Ethereum-native developers to access Polkadot’s cross-chain ecosystem.
14469

145-
D --> A
146-
A --> F[(New State)]
147-
A --> G[Execution Logs]
70+
For more details, explore the REVM integration in the Asset Hub smart contract documentation.
14871

149-
style A stroke:#000000,stroke-width:1px
150-
```
72+
If you want to learn more about the dual virtual stack please go to the [DualVM Stack](polkadot-docs/smart-contracts/for-eth-devs/dual-vm-stack.md){target=_blank}.

0 commit comments

Comments
 (0)