New Ledger App on Polkadot
The time has come! The v1.2.5 release includes all the necessary changes for the relay chain and the system chains to be compatible with the new Ledger App for Polkadot, an app that works on every single parachain.
The journey to this point began with a discussion with the Zondax team at the Parachain Summit in Copenhagen. This then evolved into Referenda #62, backed by the Polkadot Community. This project is a true testament to an issue brought up, organized, and solved by the Polkadot Community, and funded via OpenGov.
In this post, we will discuss how this is possible, how to use the new app, and what teams need to do to be compatible with it.
An App that works everywhere? How?
In short: Metadata.
Every Polkadot-SDK chain exposes a Metadata, which describes how to interact with it. The metadata describes how to encode different transactions, and how to properly read the state of the chain. It is a key piece in the development of all the wallets and UIs, amongst others, being used in the ecosystem.
The issue with the metadata is that it is large, and Ledger devices are small. Therefore one can’t simply push all the metadata on a payload to the device, as it will not have enough memory to handle it. Another way would be to consume the metadata from somewhere and just sent the needed pieces to the device, however the issue with this is that is not secure: users would be trusting the metadata provider.
The solution to this problem was presented in RFC 78: Merkelized Metadata. The idea is that the Metadata can be separated into pieces (chunks) and then use this pieces to create a Merkle Tree. This tree would have a Root Hash, which will represent the metadata. To decode a given transaction, only a part of this tree would be needed. So every time a user wants to send a transaction, there would be a new SignedExtension present at the runtime that would check if the hash of the metadata used at the time of signing matches that present in the blockchain. If this weren’t the case, then the transaction will be rejected, hence avoid any need of trust to the metadata provider.
This system design allows Polkadot to take a leap forward in having a more secure environment for users. Not only blind signing will not be present, but also the actual metadata used to decode the transaction at the time of signing will be part of the transaction as well. Users will have clear signing, and will sign how they got that clarity too.
Using the App, recommendations
This new functionality is already live on Kusama and the Kusama System Chains (Ref 406) and is going live on Polkadot and the Polkadot System Chains around July 1st (Ref 841). The new Polkadot Ledger App will be available the moment Polkadot’s runtime is upgraded to this functionality.
Expected Wallet Support by Launch
It is recommended to use this functionality with the wallets provided below.
| Wallet | Support |
|---|---|
| NovaWallet |  |
| Talisman | |
| Subwallet | |
| PolkadotJS Extension |  |
The PolkadotJS Extension is being updated, and we’ll be sharing more news soon. Other compatible wallets will be added to this list…
It is also very important to mention that this change requires new input parameters in the transaction body, the SignedExtension, thereby breaking compatibility with non-updated wallets. Make sure you use a compatible wallet with the new Ledger App.
New Ledger App
As said before, there will be one Ledger App that will be used across all the Polkadot ecosystem. This means Kusama and it’s parachains as well. If you have an existing account already, you will need to migrate this account to the new Ledger App.
Migration App
This app is designed to help you migrate from your existing account to a new account that uses the new app. This is necessary as every account will be using Polkadot’s derivation path. This needs to be done for all accounts that don’t use Polkadot Relay Chain’s derivation path (i.e.: all Parachain ledger accounts, Kusama ledger accounts).
All wallets mentioned above already support the migration, and you can follow the steps provided by them to do so. Here’s documentation for Nova Wallet.
New Ledger App
Once you are done with the migration or if you are setting up an account for the first time, ensure you download the latest Polkadot App, which will already be compatible with all the supported parachains.
The Ledger team has put together an FAQ to help with questions from users.
Adding support to your parachain runtime
As explained before, the changes for compatibility with the new Polkadot App have been merged in #4619. As part of that development, Basti also created a guide detailing the implementation. In essence, every parachain team that wants to support this functionality has to do three things:
- Be compatible at least with Polkadot-SDK v1.1.0 which is the first version of the Polkadot-SDK monorepo. This is because a new crate has been backported to that version that you will need.
- You need to add a new SignedExtension to your runtimes. The guide and PR linked above provide the needed details to see what changes are needed.
- You need to make sure your runtime supports metadata v15.
The instructions shared above require a change on the main fn on the build.rs file, as showed here on Polkadot. This means that now for building the runtime the feature metadata-hash has to be enabled. Some CI process across the ecosystem don’t have this, so make sure to include it.
Shortly we will be making a dashboard public where users can track which parachain is compatible with the above requirements to make the new Ledger App compatible with their systems.
Adding support to your dApp
With the new release of PJS API v12.0.2 that includes both #5914 and #5920, now all wallets can add the needed extra information to the payload to make the transaction have the extra information needed to support the new CheckMetadata SignedExtension . This is crucial, because it is in the wallet that the user ends up signing, and that’s where they need the last assurance of visibility on what it is that they are signing.
However, to remain backwards compatible with all ecosystem dApps, dApps also need to add to their payloads to be signed, a new optional value withSignedTransaction. Setting this to true will allow the wallets to add the needed information as stated before.
Therefore, if your dApp aims to be compatible with ledger, it must use the v12.0.2 release of PJS API that has these change in it, and has to set withSignedTransaction within the payload to true. Here you can see the new interface for SignerOptions.
#5914 and #5920 explain this interface in detail, so it’s recommended to look into them.
Adding support of the new Ledger App to your Wallet
The new Polkadot Ledger App created by Zondax will be available for users to download as usual. Yet the code for the App can be found here.
As to how to integrate a wallet to this new app, wallet builders will need to: (1) calculate the new MetadataHash to add to the payload if the dApp allows for it (by setting {...withSignedTransaction : true }); (2) send this information to the Polkadot Ledger App.
In order to get this metadataHash, the options are:
- Implementing your own logic in accordance to RFC 78. This RFC details how to calculate this value.
- Leverage this library created by James, as announced here.
- Use the work being done by Carlo of the PAPI Team, that can be found here.
- Leverage this API built by Zondax that you can run on your own servers to get the needed response of the hash.
And for point (2), here’s a reference implementation used by the Zondax team on their integration tests.
As said before, there will also exist a Migration App for users. If wallets desire too (highly recommended), they can also add an interface to allow users to use the Migration App as well.
Thanks
The release of this App and functionality has been an inmense journey, that leaves Polkadot on a more secure standpoint. A lot of people have been part of this development, to note:
- Zondax. From crafting the idea back in the Parachain Summit at Coppenaghe to delivering the App and a lot of utitilies so that developers can make the most of it.
- Alzymologist. Paving the way for the very first implementation on RFC 46.
- Basti. Who crafted RFC 78, wrote the metadata-shortener crate, and then implemented all this functionality on the Polkadot-SDK and on the different runtimes.
- Nova Wallet, Talisman, SubWallet. For working closely on this, making sure that they could adapt to the changes and provide users with a clear working product.
- Iker, Tarik and James, from the Product Engineering team at Parity. Who acted and reacted promtply to making things work across this entire workflow, from changes in the PJS API, to actually building a specific library. A key milestone being releasing a new PJS Extension version after 2 years!
- PAPI Team. For their knowledge and experience to design and provide solutions that solve problems in the most effective way.
- Ledger Team. For all the release management between the old apps and the new apps, plus the development happening to allow every parachain to be on Ledger Live.
- Infra and Data Team at Parity. Who have been responsible of the release of PJS Extension to Google Chrome and Mozilla, and have also put together a dashboard to track which chains are compatible with this new system.
Edits have been made to the original post
is there any update Devs?