Polkadot-js New Ledger Support Completion

[Tarik]

Ledger Support In Polkadot-JS

I’m excited to announce that support for the new Ledger app in Polkadot-JS has been fully implemented across Common, UI, Apps, and Extension. While some components were completed earlier, others have only recently been merged and released, such as the Extension. In this blog post, I’ll cover:

1. The Ledger Settings
2. Technical Overview
3. Final Thoughts and To Do’s

The Ledger Settings

Both the Extension and Apps share a similar approach: as a user, you’ll need to toggle a specific setting to use the Migration app. By default, the new Generic App is always enabled.

Polkadot-JS Apps

For a step-by-step guide on adding your Ledger account to Polkadot-JS Apps using the updated interface, please refer to this well-written article: Polkadot-JS UI: How to Add a Ledger Account.

Accessing Ledger Settings: Navigate to the “Settings” tab in the top header of the page. Under the “General” section, you’ll find the “Account Options” area, which includes dropdowns for “Manage Hardware Connections” and “Manage Ledger App.”

Manage hardware connections: This dropdown has been available since the legacy Ledger support and functions the same way. It is important to note that it only works with Chrome browsers, as there is no Ledger support for Firefox.

Manage ledger app: This dropdown provides options to either “Use the Ledger Generic App” or “Use the Ledger Migration App.” If you plan to use or add an account from the Migration App, you’ll need to toggle this setting accordingly.

Polkadot-JS Extension

For a step-by-step guide on adding your Ledger account to Polkadot-JS Apps using the updated interface, please refer to this well-written article: Polkadot Extension: How to Add Your Ledger Account.

Accessing Ledger Settings: In the top right corner of the Extension, click on the “Gear” icon. Under the “Ledger App” section, you’ll find a dropdown menu.

Ledger App: This dropdown provides two options: “Use the Ledger Polkadot Generic App” and “Use the Ledger Migration App.” To use any Migration App account, you must select the Migration App option.

Metadata: The latest metadata is required in the Extension to retrieve the necessary proof for Ledger. In Apps, you can manually trigger the upload by navigating to the “Settings” tab and then selecting the “Metadata” tab.

Technical Overview

For those interested, I wanted to highlight a quick overview of the libraries involved, and some changes in each.

1. Polkadot-js/common

   • @polkadot/hw-ledger-transports
     This library exports the necessary transports for Ledger, depending on your environment (browser or Node.js).
   • @polkadot/hw-ledger
     This library provides a general wrapper around the Ledger App, which is exposed by @zondax/ledger-substrate. In Polkadot-JS, the older class Ledger has been deprecated in favor of the new class LedgerGeneric.

2. Polkadot-js/ui

   • @polkadot/ui-settings
     This library allows for shared settings across the Polkadot-js repositories, including Apps and the Extension. We’ve added settings for Ledger to enable toggling between the Generic and Migration Apps.

3. Polakdot-api/merkleize-metadata

   • @polkadot-api/merkleize-metadata
     This TypeScript utility library facilitates the merkleization of frame metadata. It’s used in both Apps and the Extension to retrieve the necessary proof for Ledger.

4. Polkadot-js/extension

   • @polkadot/extension-inject
     This library serves as a basic extension injector. We’ve added the rawMetadata field to the MetadataDef interface, allowing the transfer of raw metadata to the Extension.
   • @polkadot/extension-chains
     This library defines the supported chains for the Extension. The metadataExpand function now processes and digests the necessary rawMetadata.
   • @polkadot/extension-base
     This library includes functions, classes, and utilities used within @polkadot/extension. The Extension.signingApproveSignature method now includes the signedTransaction from the signer when applicable.

Final Thoughts and To Do’s

I want to extend my gratitude to everyone in the community and all those involved for their patience throughout this process. A special thanks to Iker, Alberto, and Santiago for their help in getting this over the finish line, as well as to the Polkadot-api team for developing the @polkadot-api/merkleize-metadata package. As always, the most challenging aspect was integrating all the pieces across the Polkadot-js repositories. With so many moving parts and technical decisions to navigate—often without clear documentation or buried in years of old GitHub issues—this process was anything but straightforward. However, I ended up learning far more than I expected, which has further solidified my understanding of previously unfamiliar parts of Polkadot-JS.

To Do’s

There is one remaining UX issue in the Extension, which you can track here: #1439.