New Polkadot Ledger App

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 :white_check_mark:
Talisman :white_check_mark:
Subwallet :white_check_mark:
PolkadotJS Extension :soon:

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:

  1. 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.
  2. 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.
  3. 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:

  1. Implementing your own logic in accordance to RFC 78. This RFC details how to calculate this value.
  2. Leverage this library created by James, as announced here.
  3. Use the work being done by Carlo of the PAPI Team, that can be found here.
  4. 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

32 Likes

How to upgrade to v15? I see that Kusama and Polkadot are still v14.

Hey! Both Polkadot and Kusama are actually on v15

The Data team at Parity is preparing a dashboard that shows which chains are already using metadata V15 and also which ones have support for the new CheckMetadataHash SignedExtension, which will look something like this:

3 Likes

Yes, thank you for your answer. What I mean is that the api.runtimeMetadata obtained using polkadot.js returns v14 by default. This may be the reason why we can not sign successfully when we try to integrate ledger.

I don’t think that’s the issue, it’s most probably that PJS Apps still needs to finish some last checks to be compatible with the new Ledger App → Enable `withSignedTransaction` for signing and sending payloads by TarikGul · Pull Request #10714 · polkadot-js/apps · GitHub. You can try running that branch locally and testing out again. Also please remember that compatible wallets for now are Nova Wallet, SubWallet and Talisman.

Dashboard is available here - Parity Data Dashboards - Parachain Metadata

4 Likes

Indeed the documentation/instructions on the migration is nowhere to be found. After upgrading to 100.0.5 signing on pdot.js is not possible with 28160 error message. Who is offering support here? I see a lot of such support by the Novasama team, but is it their job really?

1 Like

Instructions on how to re-attach the Polkadot new account with SubWallet: FAQs | SubWallet - Polkadot Wallet

2 Likes

As to this error: using supported wallets detailed on the post is the solution. Thanks Joern for reaching out!

Hi Santi, thanks for your suggestion earlier today. I replaced the setup to talisman wallet accessing polkadot/substrate portal, now it’s working :+1:

1 Like

Hi everyone,

Talisman docs were updated for the generic and migration Ledger apps :

4 Likes

On Centrifuge, we have just updated to Polkadot SDK v1.7.2 including the metadata hash check. Unfortunately, I was not able to sign any transaction using my Ledger Nano S with the “Polkadot (DOT)” app v100.0.5 due to error 1011: Unknown Transaction Validity: UnknownTransaction::CannotLookup. On Polkadot it works.

We have followed the instructions [1] to enable the metadata hash support. However, we did not adjust our WASM building CI because we are using srtool which uses the on-chain-release-build feature per default [2]. Our current srtool version is v0.14.0.

I wonder if any other parachain had similar issues? Would highly appreciate any advice to enable Ledger support for Centrifuge users ASAP.

The problem being that srtool only enables the on-chain-release-build feature when the name of the runtime is {kusama/polkadot}-runtime as you see here

In the fellowship repo we use the srtool-action and enable the feature explicitly. If you do this as well in your release pipeline, it should work.

2 Likes

BTW, the way I have proposed it in the guide with using an extra feature in the runtime, is just a proposal. This means you could also enable the metadata-hash feature always in substrate-wasm-builder. Then you would always compile with metadata hash generation enabled. The downside of this is that the compile time goes up significantly.

Hi there!
Thank you for this realease.
Can you please provide an estimated ETA for enabling PolkadotJS Extension to work with the app?
Thank you.
Best.

The needed changes have already been made by @Tarik, so release is quite imminent. The team had to prioritize the release of the migration to manifest v3 which was done yesterday, as it is required by chrome.

1 Like

Support for the new generic ledger app in the extension is getting close to being finished. We were required to change and update the interface to send the extension the raw metadata since it is required for the proof when signing. All that being said it should be done soon (hoping for next week).

4 Likes

Thank you both @santi @Tarik
Amazing news!

1 Like

:innocent:is there any update Devs?