Skip to content

Accounts on Asset Hub Smart Contracts

PolkaVM Preview Release

PolkaVM smart contracts with Ethereum compatibility are in early-stage development and may be unstable or incomplete.

Introduction

Asset Hub natively utilizes Polkadot's 32-byte account system while providing interoperability with Ethereum's 20-byte addresses through an automatic conversion system. When interacting with smart contracts:

  • Ethereum-compatible wallets (like MetaMask) can use their familiar 20-byte addresses.
  • Polkadot accounts continue using their native 32-byte format.

  • The Asset Hub chain automatically handles conversion between the two formats behind the scenes:

    • 20-byte Ethereum addresses are padded with 0xEE bytes to create valid 32-byte Polkadot accounts.
    • 32-byte Polkadot accounts can optionally register a mapping to a 20-byte address for Ethereum compatibility.

This dual-format approach enables Asset Hub to maintain compatibility with Ethereum tooling while fully integrating with the Polkadot ecosystem.

Address Types and Mappings

The platform handles two distinct address formats:

Ethereum to Polkadot Mapping

The AccountId32Mapper implementation in pallet_revive handles the core address conversion logic. For converting a 20-byte Ethereum address to a 32-byte Polkadot address, the pallet uses a simple concatenation approach:

  • Core mechanism: Takes a 20-byte Ethereum address and extends it to 32 bytes by adding twelve 0xEE bytes at the end. The key benefits of this approach are:
    • Able to fully revert, allowing a smooth transition back to the Ethereum format.
    • Provides clear identification of Ethereum-controlled accounts through the 0xEE suffix pattern.
    • Maintains cryptographic security with a 2^96 difficulty for pattern reproduction.

Polkadot to Ethereum Mapping

The conversion from 32-byte Polkadot accounts to 20-byte Ethereum addresses is more complex than the reverse direction due to the lossy nature of the conversion. The AccountId32Mapper handles this through two distinct approaches:

  • For Ethereum-derived accounts: The system uses the is_eth_derived function to detect accounts that were originally Ethereum addresses (identified by the 0xEE suffix pattern). For these accounts, the conversion strips the last 12 bytes to recover the original 20-byte Ethereum address.

  • For native Polkadot accounts: Since these accounts utilize the whole 32-byte space and weren't derived from Ethereum addresses, direct truncation would result in lost information. Instead, the system:

    1. Hashes the entire 32-byte account using Keccak-256.
    2. Takes the last 20 bytes of the hash to create the Ethereum address.
    3. This ensures a deterministic mapping while avoiding simple truncation.

The conversion process is implemented through the to_address function, which automatically detects the account type and applies the appropriate conversion method.

Stateful Mapping for Reversibility : Since the conversion from 32-byte to 20-byte addresses is inherently lossy, the system provides an optional stateful mapping through the OriginalAccount storage. When a Polkadot account registers a mapping (via the map function), the system stores the original 32-byte account ID, enabling the to_account_id function to recover the exact original account rather than falling back to a default conversion.

Account Mapping for Native Polkadot Accounts

If you have a native Polkadot account (32-byte format) that was created with a Polkadot/Substrate keypair (Ed25519/Sr25519) rather than an Ethereum-compatible keypair (secp256k1), you'll need to map your account to enable Ethereum compatibility.

To map your account, call the map_account extrinsic of the pallet_revive pallet using your original Substrate account. This creates a stateful mapping that allows your 32-byte account to interact with the Ethereum-compatible smart contract system.

Once mapped, you'll be able to:

  • Transfer funds between 20-byte format addresses.
  • Interact with smart contracts using Ethereum-compatible tools like MetaMask.
  • Maintain full reversibility to your original 32-byte account format.

Mapping Requirement

Without this mapping, native Polkadot accounts cannot transfer funds or interact with the Ethereum-compatible layer on the Hub.

Account Registration

The registration process is implemented through the map function. This process involves:

  • Checking if the account is already mapped.
  • Calculating and collecting required deposits based on data size.
  • Storing the address suffix for future reference.
  • Managing the currency holds for security.

Fallback Accounts

The fallback mechanism is integrated into the to_account_id function. It provides a safety net for address conversion by:

  • First, attempting to retrieve stored mapping data.
  • Falling back to the default conversion method if no mapping exists.
  • Maintaining consistency in address representation.

Contract Address Generation

The system supports two methods for generating contract addresses:

  • CREATE1 method:

    • Uses the deployer address and nonce.
    • Generates deterministic addresses for standard contract deployment.

  • CREATE2 method:

    • Uses the deployer address, initialization code, input data, and salt.
    • Enables predictable address generation for advanced use cases.

Security Considerations

The address mapping system maintains security through several design choices evident in the implementation:

  • The stateless mapping requires no privileged operations, as shown in the to_fallback_account_id implementation.
  • The stateful mapping requires a deposit managed through the Currency trait.
  • Mapping operations are protected against common errors through explicit checks.
  • The system prevents double-mapping through the ensure!(!Self::is_mapped(account_id)) check.

All source code references are from the address.rs file in the Revive pallet of the Polkadot SDK repository.

Last update: October 3, 2025
| Created: June 11, 2025