# New Ledger App on Polkadot

The time has come! The v1.2.5 release contains all the needed 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 here started with a discussion together with the Zondax back at Parachain Summit in Coppenaghen. This then became Referenda #62, backed by the Polkadot Community. This project is a true testament of an issue brought up by the Polkadot Community, organized and solved by the Polkadot Community, and funded via OpenGov.

We will be discussing on this post how is this possible, how to use the new app, and what do teams need to do to be compatible with this.

## 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 on [RFC 78: Merkelized Metadata](https://github.com/polkadot-fellows/RFCs/pull/78). 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. 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 metata provider.

This system design allows Polkadot to take a leap further into having a more secure enviroment 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](https://kusama.subsquare.io/referenda/406)) and is going live on Polkadot and the Polkadot System Chains around July 1st ([Ref 841](https://polkadot.subsquare.io/referenda/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 wallets compatibe with this list are to be added here too._

It is also very important to mention that this change requires new input parameters in the transaction body, the SignedExtension, therefore breaking compatibility with non-updated wallets. Make sure you use a compatible wallet with the LedgerApp.

### 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 set up for you to be able to migrate from your existing account, to a new account that uses the new App. This is needed as every account will be using Polkadot's derivation path.

Al wallets mentioned above already support the migration, and you can follow the steps there to do so.

#### New Ledger App
Once you are done with the migration or if you are setting an account for the first time, then make sure you download the latest Polkadot App, and that will already be compatible with all the compatible parachains.

## Adding support to your parachain runtime

As explained [before](https://forum.polkadot.network/t/polkadot-generic-ledger-app/4295/27?u=santi), the changes for compatibility with the new Polkadot App have been merged in [#4619](https://github.com/paritytech/polkadot-sdk/pull/4619). As part of that development, Basti also created [a guide](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/guides/enable_metadata_hash/index.html) 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](https://github.com/paritytech/polkadot-sdk/pulls?q=is%3Apr+CheckMetadataHash+is%3Aclosed+) 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.

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.1](https://github.com/polkadot-js/api/releases/tag/v12.0.1) that includes [#5914](https://github.com/polkadot-js/api/pull/5914), now all wallets can add the needed extra information to the payload to make the transaction have the extra information needed tu 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.
Therefore, if your dApp is compatible with the v12.0.1 release of PJS API that has this change in it, then nothing else is needed from your end.
If this is not the case, then you need to make sure you add to the payload of your transactions the added information compatible with the new SignedExtension, `CheckMetadataHash`.

{
    ...
    mode: 1,
    metadataHash: metadataHash
}

In order to get this `metadataHash`, the options are:
1. Implementing your own logic in accordance to [RFC 78](https://github.com/polkadot-fellows/RFCs/pull/78). This RFC details how to calculate this value.
2. Leverage [this library](https://www.npmjs.com/package/merkleized-metadata) created by James, as announced [here](https://forum.polkadot.network/t/announcing-the-merkleized-metadata-typescript-bindings/8724).
3. Use the work being done by Carlo of the PAPI Team, that can be found [here](https://github.com/polkadot-api/polkadot-api/pull/541).

## 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, 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, 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.