= Emerald HWKey
image:https://github.com/emeraldpay/emerald-hwkey/workflows/Test/badge.svg["Test"]
image:https://coveralls.io/repos/github/emeraldpay/emerald-hwkey/badge.svg["Coveralls",link=https://coveralls.io/github/emeraldpay/emerald-hwkey]
image:https://codecov.io/gh/emeraldpay/emerald-hwkey/branch/master/graph/badge.svg[Codecov,link=https://codecov.io/gh/emeraldpay/emerald-hwkey]
image:https://img.shields.io/crates/v/emerald-hwkey.svg?style=flat-square["Crates",link="https://crates.io/crates/emerald-hwkey"]
image:https://img.shields.io/badge/License-Apache%202.0-blue.svg["License"]
Rust library to access Hardware Keys for Cryptocurrency.
.Supports:
- Ledger Nano S
- Ledger Nano X
== Development
=== Integration Testing with Speculos emulator
NOTE: The tests use `testcontainers-rs` to automatically manage Speculos Docker containers.
.For manual Docker (i.e., for a feature development):
----
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
----
.Run tests:
----
EMRLD_HWKEY_TEST=true cargo test --test "speculos_*" --features "speculos"
----
=== 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
The license below is applied only to the source code of this project. The docs for 3rd party components (in `./reference/`) are under their own licenses, which are not affected by this license.
Copyright 2025 EmeraldPay, Ltd
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.