ledger-substrate (JS Integration)

This package provides a basic client library to communicate with Substrate Apps running in a Ledger Nano S/S+/X devices Additionally, it provides a hd_key_derivation function to retrieve the keys that Ledger apps generate with BIP32-ED25519. Warning: the hd_key_derivation function is not audited and depends on external packages. We recommend using the official Substrate Ledger apps in recovery mode.

Available commands

Operation	Response	Command
getVersion	app version	---------------
getAddress	pubkey + address	path + ( showInDevice )
sign	signed message	path + message

getAddress command requires that you set the derivation path (account, change, index) and has an option parameter to display the address on the device. By default, it will retrieve the information without confirmation from the user.

Migrating to the Generic App

Steps to Migrate

1. Update the Package: Ensure you are using the latest version of the package (version 0.44.0 or higher).
2. Create a Generic App:

• Import the PolkadotGenericAppLegacy class.
• Provide the following new arguments:
  • txMetadataChainId: This is the id of the chain where you intend to sign transactions. This should match the chain id configured at the generic app API service.
  • txMetadataSrvUrl: This is the URL for the generic app API service, which generates the transaction metadata needed for signing transactions on the device. Zondax provides a live demo of this service. The url is:
    • https://api.zondax.ch/polkadot/transaction/metadata

3. Configure Address Retrieval:

• When using the getAddress method, include the new required argument:
  • ss58prefix: This is the ss58 prefix for the chain for which you want to retrieve or display addresses.

Additional Resources

• The generic app API service repository is available on Github.

Add new chain

If you want to add support for your chain, you just need to create a PR in this repository adding the parameters that belong to the chain. Go to supported APPs and add a new entry at the end of the file.

{
  name: 'ChainName',
  cla: 0xFF,
  slip0044: 0x80000162,
  ss58_addr_type: 7391,
},

Take the last used CLA and pick the following number. This is just an ID for the app that is used in APDU protocol. This is probably the easiest way to get a free CLA.

For Slip0044 parameter, you might want to register here as well.

SS58 prefix have no limitation whatsoever, you just have to set an uint16 number that is used in your chain.

Testing with real devices

It is possible to test this package with a real Ledger Nano device. To accomplish that, you will need to follow these steps:

• Install the application in the Ledger device
• Install the dependencies from this project
• Run tests

yarn install
yarn test

Example:

Visit and download the latest release from repository (in this case Kusama).

Download the installer script for your device but bear in mind that NanoX does not allow side loading applications. Give execution permission and run the script.

chmod +x installer_nano_device.sh
./installer_nano_device.sh load

Modify these values from testing script before running the tests:

const CHAIN = 'Kusama'
const YOUR_PUBKEY = 'd280b24dface41f31006e5a2783971fc5a66c862dd7d08f97603d2902b75e47a'
const YOUR_ADDRESS = 'HLKocKgeGjpXkGJU6VACtTYJK4ApTCfcGRw51E5jWntcsXv'
const YOUR_BLOB = '0400ffbc10f71d63e0da1b9e7ee2eb4037466551dc32b9d4641aafd73a65970fae4202286beed502000022040000b0a8d493285c2df73290dfb7e61f870f17b41801197a149ca93654499ea3dafe280b332587f46c556aa806781884284f50d90b8c1b02488a059700673c93f41c'

Run tests and you will see how this module communicates with your device.

Who we are?

We are Zondax, a company pioneering blockchain services. If you want to know more about us, please visit us at zondax.ch