<aside> <img src="/icons/help-alternate_red.svg" alt="/icons/help-alternate_red.svg" width="40px" /> First things first

Why is this needed?
What are the risks? How can they be mitigated?
What happens if I don’t upgrade to the new format?
How much effort is required to upgrade? </aside>

gm 👋

This guide addresses the integration challenges that may arise when chains and respective dApps switch to the universal address format, as proposed in this WFC proposal.

This initiative falls under the UX Bounty scope and the necessary resources will be covered by its budget. You can find all relevant materials here.

</aside>

This guide was created to comprehensively address the needs of all teams that may be affected. If your parachain doesn’t have interfaces, some sections may not apply to you.

</aside>

Table of Content

Upgrade your Parachain Address Format

To initiate the change, you need to update a parameter in the runtime configuration of the parachain. Although this is a simple configuration adjustment, it typically requires a runtime upgrade.

The change is essential because dApps and wallets rely on this parameter to correctly display the address format.

This includes Polkadot Vault and Ledger hardware devices. It is also the recommended method for dApps to trigger and communicate the change to users.

impl frame_system::Config for Runtime {
	...
	--- type SS58Prefix = SS58Prefix;
	+++ type SS58Prefix = 0u16;
	...
}

Wallets and dApps are encouraged to use this change to “flip the switch” for parachains that have upgraded from the old address prefix to the new one.

It’s recommended to wait until wallets have implemented the necessary changes before proceeding with this update.

</aside>

Update your dApp UI

You need to make several changes to your dApp(s) to prevent user confusion and ensure users do not accidentally send funds to centralized exchanges on the wrong chain. Let’s walk through a real example.

Whenever working with an account in the UI or the backend data layer, use the raw AccountId, not SS58.

SS58 encoded address should only be used for presenting the address to the user and for the input validation.

</aside>