Emerald HWKey

Rust library to access Hardware Keys for Cryptocurrency.

Supports:

• Ledger Nano S

• Ledger Nano X

Development

Integration Testing with Speculos app

Get App Ledger App emulator from: https://github.com/LedgerHQ/speculos

For Docker:

docker pull ghcr.io/ledgerhq/speculos
docker image tag ghcr.io/ledgerhq/speculos speculos

The Speculos app is initialized with the following seed by default:

glory   promote mansion idle        axis    finger   extra   february
uncover one     trip    resource    lawn    turtle  enact   monster
seven   myth    punch   hobby       comfort wild    raise   skin

Test against a Bitcoin App

Run it in docker as:

docker run --rm -it -p 8080:5000  speculos --display headless apps/btc.elf

Run tests:

EMRLD_HWKEY_TEST=bitcoin cargo test --test speculos_bitcoin --features "speculos" -- --test-threads=1

Test against an Ethereum App

Run Speculos Docker with NanoX app:

docker run --rm -it -v $(pwd)/testdata/ledger-elf:/speculos/apps -p 8080:5000  speculos --model nanox --display headless apps/ethereum-nanox-2.0.2-1.9.18.elf

Run tests:

EMRLD_HWKEY_TEST=ethereum cargo test --test speculos_ethereum --features "speculos" -- --test-threads=1

Integration Testing with Real Hardware

For all the test the following Mnemonic Phrase is used:

blanket large   trumpet mandate call  great unhappy skull
special assist  draw    right   quote stone under   legend
invite  morning hub     believe pulp  piano tuition fruit

You can also verify addresses and get the actual Private Key by using https://iancoleman.io/bip39/#english with that Mnemonic. At least for the Ledger Nano products.

Warning

Never transfer real money to the Test Ledger or any wallet created from the Mnemonic Phrase above. Since the Phrase is public all the money would be stolen immediately.

Ledger + No App

No App must be open on Ledger

EMRLD_HWKEY_TEST=noapp cargo test --test ledger_noapp -- --test-threads=1

Ledger + Bitcoin App

Bitcoin App must be open on Ledger

EMRLD_HWKEY_TEST=bitcoin cargo test --test ledger_bitcoin -- --test-threads=1

Ledger + Bitcoin Test App

Bitcoin Test App must be open on Ledger

EMRLD_HWKEY_TEST=bitcoin_testnet cargo test --test ledger_bitcoin -- --test-threads=1

Ledger + Ethereum App

Ethereum App must be open on Ledger

EMRLD_HWKEY_TEST=ethereum cargo test --test ledger_ethereum -- --test-threads=1

Ledger + Ethereum Classic App

Ethereum Classic App must be open on Ledger

EMRLD_HWKEY_TEST=ethereum_classic cargo test --test ledger_ethereum -- --test-threads=1

Test Configuration

To run integration tests, like above, you cannot run them without connecting Ledger and opening right app on it before running the tess. Which also means you cannot run them all at the same time, or from CI, etc. To enable a particular test you set the environment variable EMRLD_HWKEY_TEST to the name of the test you want to run, which is handled by build.rs script to set the corresponding cfg(…​) option.

The following tests are available (note test_ prefix is optional in environment variable): - integration_test - test_noapp - test_ethereum - test_ethereum_classic - test_bitcoin - test_bitcoin_testnet

And on top of them there is integration_test.

By default, it uses a single instance of HID connection shared between different threads (because re-opening it right after closing is prone to panics), but it can be reset by adding hid to that environment variable, which enabled direct HID connection in tests.

License

Copyright 2025 EmeraldPay

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.