cardano-foundation/ledgerjs-hw-app-cardano

Cardano bindings for Ledger Nano S JavaScript APIs for Node.js and browsers

@cardano-foundation/ledgerjs-hw-app-cardano

JS Library for communication with Ledger Hardware Wallets. This library is compatible with the Cardano ADA Ledger Application.

Note: this project comes with both Typescript and Flow type definitions, but only the Typescript ones are checked for correctness.

Example code

Example code interacting with hw-app-cardano is provided in example-node directory. You can execute it with the yarn run-example command.

Tests

Automated tests are provided. There are two types of tests

1. yarn test-integration. Tests JS API and integration with the physical Ledger device.

   • yarn test-speculos. Runs the test-integration test against the Speculos emulator.

2. yarn device-self-test. Runs tests defined in the application code of the Ledger application, requires development build of the application.

   • yarn device-self-test-speculos. Runs yarn device-self-test on Speculos (useful because the full app in debug mode with self-tests does not fit on Nano S).

Note that for these tests it is advisable to install the developer build of the Cardano app with headless mode enabled unless you want to verify the UI flows, otherwise you will need a significant amount of time to manually confirm all prompts on the device.

Speculos

To run the Speculos emulator, you first need to install it. The Speculos documentation should take you through the installation process. After installing you can start the emulator with the correct seed: speculos /path/to/your/ledger-app-cardano-shelley/bin/app.elf --seed "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about" --display headless Note: replace /path/to/your/ledger-app-cardano-shelley/bin/app.elf with a path to the app.elf file of the Cardano ledger app. This will start the emulator with a TCP server listening on port 9999 for APDU messages and a web interface running on port 5000 (http://localhost:5000) which can be used to interact with the app. The --display headless option just hides any window UI.

Documentation

• you can build the docs by running yarn gen-docs and then navigate to docs_generated/index.html
• generated docs can also be found at (https://vacuumlabs.github.io/ledgerjs-cardano-shelley)
• CHANGELOG

ledgerjs-hw-app-cardano's Issues

removing asset ordering

we're running into the OUTPUT_INVALID_ASSET_GROUP_ORDERING from version 3.2.0
are there any concerns with upgrading to the latest version?

Raise minimum version recommended

Hello,

we are having an issue with a new version of the cardano app that's currently on our staging env.

DeviceVersionUnsupported: Device app version 6.0.1 unsupported, recommended version is 5.0.

https://github.com/cardano-foundation/ledgerjs-hw-app-cardano/blob/49e66c11e15830e9112e5ba1d63b73af748f4d88/src/interactions/getVersion.ts

Is it possible to change the maxMajor ?
also is there a way for not depending on recommended version for the future or all version can bring some major breaking change on this package ?

Thank you !

Error: Action rejected by Ledger's security policy

Hi! for our integration we have been testing Ledger with special transactions we use a lot on our wallet, some big datums are causing reboots (i guess it's expected due to device ram size?) but in this case this multisig transactions are throwing errors in both brands, Ledger and Trezor T, maybe im doing something wrong?

{
    "type": "Tx Babbage",
    "description":  "Error:Action rejected by Ledger's security policy",
    "cborHex": "84a500818258205e9dc0151a873fa30cd274d7193ca878b7b1611219335b5f811ad31a0dc092b100018f82583900feff70b08356d72c571ade218c7e2933235d2cdc37259646013a27d961d11bcf82ebd0ca2afdaf96e11ec71e43ab4e454cbe1495b42a4e861a000f424082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a001e848082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a002dc6c082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a004c4b4082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a0089544082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a0103664082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a01f78a4082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a03dfd24082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a07b0624082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a0f51824082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a1e93c24082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a3d18424082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a7a21424082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651af433424082583930873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae02651a6afa27b3021a00035f0d075820b62580f736e309a2223c33eec1340aa53cee3a699aa9e301c622e3a4951186c40f00a200828258206a05c84e3737155a73752b61ae2d9cd51b988580b3d337483f120d359cd8b232584025e77819718c8de4e0469a3c8c0d884b7e9b8a28397c93b4cca97092d84f0fe000610520a22ab1282c72916b83b06531af651ad3f5b42cd3021b2fc5eda617028258202f741927cd922187d9483e2538337506a5ddb67c09531585c6900cef1ed2ef2e58408fec50e3e89d9de963b2741fee4d8965a8b29c52b801a4c5c6c64240fab3b10849e7f0095c2e0315170a35f337db598adfd84f3d88c680a5196214fb0748cd0c01818201828200581c63fb909c87c671faa052d3ce28366eee21fde5d47d9389d35ea5b8868200581c45176f9a063a6c4b49523f569d39860e5879bc943ca12a0d034702caf5a11849a66362696478403837356239333830383636653964353665373131306230656533313039363263313664396434616531303366383239643632626466666432636265376336316468726566657272657275687474703a2f2f6c6f63616c686f73743a333030306474616773816a736d6172742d73656e64657469746c656a536d6172742053656e646474797065627478617663312e30"
}

Payload for transport:

{
   "signingMode": "multisig_transaction",
   "tx": {
       "network": {
           "protocolMagic": 1,
           "networkId": 0
       },
       "inputs": [
           {
               "txHashHex": "5e9dc0151a873fa30cd274d7193ca878b7b1611219335b5f811ad31a0dc092b1",
               "outputIndex": 0,
               "path": null
           }
       ],
       "outputs": [
           {
               "amount": "1000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "00feff70b08356d72c571ade218c7e2933235d2cdc37259646013a27d961d11bcf82ebd0ca2afdaf96e11ec71e43ab4e454cbe1495b42a4e86"
                   }
               }
           },
           {
               "amount": "2000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "3000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "5000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "9000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "17000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "33000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "65000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "129000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "257000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "513000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "1025000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "2049000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "4097000000",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           },
           {
               "amount": "1794779059",
               "destination": {
                   "type": "third_party",
                   "params": {
                       "addressHex": "30873cb3e56843747eafc707c70048fd54b56ce1717fe7af8fede8414bc748fc7883f3a64a12170ab6dcfd6b30879a3339d74afdae5cae0265"
                   }
               }
           }
       ],
       "fee": "220941",
       "auxiliaryData": {
           "type": "arbitrary_hash",
           "params": {
               "hashHex": "b62580f736e309a2223c33eec1340aa53cee3a699aa9e301c622e3a4951186c4"
           }
       },
       "includeNetworkId": true
   },
   "additionalWitnessPaths": [
       [
           2147485500,
           2147485463,
           2147483648,
           0,
           0
       ]
   ]
}

Using
"@cardano-foundation/ledgerjs-hw-app-cardano": "^5.1.0",
"LedgerCardanoAppVer":"5.1.0",
Ledger Nano S

Related to:
# vacuumlabs/cardano-hw-cli#136

Add compatibility with version 6 of the Cardano app

The Cardano app version 6.0.0 was released 8 Dec 2022 since then if a user is updated the Cardano App on the ledger to the version 6.x.x he is not able to use his wallet with apps that use your library.
The error is returned:

Device app version 6.0.2 unsupported, recommended version is 5.0.

Please add the version 6.x.x into compatible versions.

Error with utils/dist not being accessible

Hello,

We are trying to make ledger-live work with version 6.0.0 but it's seems that we have some issues with some function that we are using in 5.x

error TS2614: Module '"@cardano-foundation/ledgerjs-hw-app-cardano/dist/utils"' has no exported member 'str_to_path'. Did you mean to use 'import str_to_path from "@cardano-foundation/ledgerjs-hw-app-cardano/dist/utils"' instead?

We can't use for some reason str_to_path from utils.

Example :

import { str_to_path } from "@cardano-foundation/ledgerjs-hw-app-cardano/dist/utils";

const path = "" //well it will not working but it's just to illustrate that we can't import str_to_path anymore
str_to_path(path)

Thank you very much !

how to use on testnet?

Description:
adaApp.signTransaction on testnet throws error
Action rejected by Ledger's security policy

Expected behavior:
sign/submit transaction

Actual behavior:
throws error
Action rejected by Ledger's security policy

Context:
device: google pixel 6
OS: android 12
connectiont: BLE

this appears to be the desired behavior
if so, are there plans to enable testing on testnet?

ledgerjs-hw-app-cardano/test/integration/__fixtures__/signTxRejects.ts

Line 111 in 2b04905

testname: "Non-mainnet protocol magic",

TypeError: data.readUIntBE is not a function

Hi, we are currently hitting TypeError: data.readUIntBE is not a function error when calling basic methods like ledgerAppAda.getSerial() and ledgerAppAda.getVersion(), testing on a Nano S.

Aparently on this too lines:

ledgerjs-hw-app-cardano/src/utils/serialize.ts

Line 43 in 5e83052

return data.readUIntBE(0, 2) as Uint16_t

and

ledgerjs-hw-app-cardano/src/utils/serialize.ts

Line 57 in 5e83052

return data.readUIntBE(0, 4) as Uint32_t

We are using version @cardano-foundation/[email protected]
and because of too many dependencies to keep we are stuck in an old react-scripts 4 and node, npm versions old as well.

Is there any workaround to this posible rather than updating everything on our side please?
Big project, small community team here!

Downgrading to @cardano-foundation/[email protected] is incompatible with latest Ledger Cardano App

Wen Ledger Live integration?

Hello,

I can't use the Nami or Eternl wallet with my Ledger, as Ledger Live only has the version 3.0.0, when can we expect an update?

regards

[BUG] Outputless transaction causes error

Actual behavior
If there is a transaction without outputs, app still tries to "parse" it and trows "OUTPUTS_NOT_ARRAY" error.

Expected behavior
App should ignore it.

How did you get an outputless tx???!?!?!

1. Account has 2 utxo: 2ada and 1ada;
2. Trying to delegate it;
3. 2ada utxo acts as a deposit, 1ada utxo acts as fee, because you can't use only 0.18ada and send 0.82ada back when the min utxo equals 0.96ada;
4. So tx contains: 2 inputs, 2 certs, fee and no outputs

P.S. Yes, I can pass an empty array, but would be better if library can handle it by itself :)