Polkadot dApp development: from contract to front end

A Polkadot dApp is a web front end plus logic that runs somewhere in the Polkadot network. This guide shows where that logic can run in 2026, which client libraries and wallets the front end uses, and how XCM and indexers fit into the build.

The logic can be a smart contract on Polkadot Hub, a contract on a parachain such as Moonbeam, or a pallet in a runtime you control. The first decision is where the logic runs, and the client library, wallet connection and indexer follow from that choice.

Where a Polkadot dApp's logic can run

Most new dApps should deploy contracts rather than launch a chain. A custom pallet makes sense only when a contract cannot express the logic, or when the economics of a separate chain work for the product.

Smart contracts on Polkadot Hub

Polkadot Hub is the chain that holds DOT balances, staking and governance in the Polkadot ecosystem. It runs contracts through pallet_revive, which offers two backends:

• REVM is a Rust implementation of the Ethereum Virtual Machine. Solidity contracts run without changes, and the docs recommend REVM for most projects.
• PVM is a RISC-V based backend for heavy computation. Solidity compiles to PVM bytecode with the resolc compiler, and the tooling is more limited.

The Polkadot docs list Polkadot Hub mainnet with chain ID 420420419 and DOT as the currency. Polkadot Hub TestNet uses chain ID 420420417 and the PAS test token. REVM and PVM share precompiles, including ERC-20 and XCM precompiles, so contracts can reach native assets and cross-chain messages.

Ethereum developers should note three differences that the docs list:

• A 20-byte Ethereum address maps to a 32-byte Polkadot account.
• Fees combine gas with weight, proof size and storage deposits.
• Local test runs use the tool's own EVM, so helpers such as evm_increaseTime and loadFixture often fail against a Polkadot node.

The status of ink!

ink! is the Rust language for Polkadot contracts. The ink! maintainers state that since January 2026 they cannot actively maintain or develop ink! further, and the repository no longer accepts new issues or pull requests. A new project should pick Solidity on Polkadot Hub, or Rust in a runtime pallet, unless it accepts an unmaintained toolchain.

Front end libraries for Polkadot dApps

A front end for an EVM contract works like any Ethereum dApp, using viem, ethers.js or Wagmi with an EVM wallet. A front end that touches native Polkadot features, such as balances, staking, governance, XCM and your own pallet, needs a Substrate client.

The older Substrate client is @polkadot/api, also called polkadot.js. Many new projects use polkadot-api (PAPI). PAPI generates TypeScript types from chain metadata, is built around a light client, and produces smaller bundles. Dedot is another modern option. Four Polkadot details shape the code with any library:

• Metadata-driven types. Runtime metadata describes calls and storage, and a chain upgrade can change these types, so generate descriptors and test against upcoming runtimes.
• Light clients. smoldot runs in the browser and checks chain data without trusting an RPC provider, though the first load takes a short sync.
• Several chains at once. A user's DOT and stablecoins sit on Polkadot Hub, while identity sits on the People chain, so the app may need connections to several chains at once.
• Planck units. DOT uses 10 decimals, so a dApp must not hardcode 18.

Connecting wallets

Polkadot browser wallets such as the Polkadot.js extension, Talisman and SubWallet inject accounts into the page through a shared extension interface. Mobile wallets such as Nova support WalletConnect and in-app browsers. React projects can use LunoKit, a library listed in the Polkadot docs that connects the main Polkadot wallets and works with PAPI, Dedot or polkadot.js.

A connect flow lists the available extensions, lets the user pick accounts, and passes a signer to the client library, and the app should show SS58 addresses with the correct network prefix. If the dApp mixes EVM contracts with native Substrate calls, decide early whether users hold one account type or two, because that choice affects every screen that shows an address or asks for a signature. For the wallet side, see Polkadot wallet development.

Cross-chain features with XCM

XCM (Cross-Consensus Messaging) lets a dApp move assets between chains or trigger actions on another chain. Most dApps use XCM for deposits, such as bringing USDT from Polkadot Hub to their own chain, and for withdrawals. Some use it for remote execution. The difficult parts are estimating fees on the destination chain and handling failed messages. Test XCM flows on forked networks before launch.

Indexing and data

Chain storage does not answer queries such as "all trades by this user", so most Polkadot dApps add an indexer. SubQuery and SQD (formerly Subsquid) both index events from Substrate pallets and EVM contracts. Run the indexer as a production service with its own monitoring.

Polkadot ecosystem fit

A dApp on Polkadot can use assets and users from several chains through XCM, and a team can later move heavy logic into its own pallet on a separate chain. The trade-off is fewer tools, auditors and liquidity than on Ethereum. The IDO launchpads on Polkadot page covers token sales in the Polkadot ecosystem.

Build sequence

1. Pick the execution environment, and confirm that the token standards, wallets and liquidity you need exist there.
2. Write and test contracts with Foundry or Hardhat on a local development node or Polkadot Hub TestNet.
3. Build the front end with PAPI or an EVM library, plus wallet connection and network switching.
4. Add an indexer and any backend services, such as notifications.
5. Audit the contracts, then launch with low limits on deposits and withdrawals.

As a rough estimate, a focused dApp with a few contracts, one front end and an indexer needs a team of two to four people for three to five months, plus an external audit. Cross-chain features add months, and so does a custom pallet. For dApp architecture beyond Polkadot, see dApp development.

Frequently asked questions