Speculos
The goal of this project is to emulate Ledger Apps on standard desktop computers, without any hardware device. More information can be found here in the documentation website (or in the docs/ folder directly).
Usage example:
./speculos.py apps/boil.elf
# ... and open a browser on http://127.0.0.1:5000
New to Speculos? The Quickstart guide walks you through installation and running an app on Linux, macOS and Windows.
Installation
From Python pypi packages
The easiest, stable way to install Speculos is with pip:
pip install speculos
It is advised to use Python virtualenv, otherwise admin rights will probably be necessary.
From sources
Installing Speculos from sources is a bit heavier and, depending on the platform, complex, due to all the dependency needed for compiling the emulator.
On Debian (10 or later) or Ubuntu (18.04 or later):
sudo apt install \
git cmake gcc-arm-linux-gnueabihf libc6-dev-armhf-cross gdb-multiarch \
python3-pyqt6 python3-construct python3-flask-restful python3-jsonschema \
python3-mnemonic python3-pil python3-pyelftools python3-requests \
qemu-user-static libvncserver-dev
# from the root directory of the source repository
pip install .
Dependency management will vary on other platforms; using Docker images and/or WSL should facilitate the installation.
Bugs and contributions
Feel free to open issues and create pull requests on this GitHub repository.
The master branch is protected to disable force pushing. Contributions should
be made through pull requests, which are reviewed by @LedgerHQ members before
being merged to master:
- @LedgerHQ members can create branches directly on the repository (if member of a team with write access to the repository)
- External contributors should fork the repository
Limitations
There is absolutely no guarantee that apps will have the same behavior on hardware devices and Speculos, though the differences are limited.
Syscalls
The emulator handles only a few syscalls made by common apps. For instance, syscalls related to app install, firmware update or OS info can't be implemented.
Memory alignment
Attempts to perform unaligned accesses when not allowed (eg. dereferencing a misaligned pointer) will cause an alignment fault on a Ledger Nano S+ device but not on Speculos. Note that such unaligned accesses are supported by other Ledger devices.
Following code crashes on LNS device, but not on Speculos nor on other devices.
uint8_t buffer[20];
for (int i = 0; i < 20; i++) {
buffer[i] = i;
}
uint32_t display_value = *((uint32_t*) (buffer + 1));
PRINTF("display_value: %d\n", display_value);
Watchdog
NanoX, Flex, Apex+ and Stax devices use an internal watchdog enforcing usage of regular
calls to io_seproxyhal_io_heartbeat();. This watchdog is not emulated on
Speculos.
Security
Apps can make arbitrary Linux system calls (and use QEMU semihosting features), thus don't run Speculos on untrusted apps.
It's worth noting that the syscall implementation (src/) doesn't expect
malicious input. By the way, in Speculos, there is no privilege separation
between the app and the syscalls. This doesn't reflect the security of the
firmware on hardware devices where app and OS isolation is enforced.
Speculos is not part of Ledger bug bounty program.
Are you developing a Nano App as an external developer?
For a smooth and quick integration:
- Follow the developers documentation on the Developer Portal and
- Go on Discord to chat with developer support and the developer community.
Metadata
Release files for speculos 0.27.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| speculos-0.27.1.tar.gz | 15.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| speculos-0.27.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 22.5 MB
Release files / speculos-0.27.1.tar.gz
| Download URL | speculos-0.27.1.tar.gz |
|---|---|
| Size | 15.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7059bff0e2bda4cf3bbf765d197b76ff4fb75353ba8081863fbe86c7304fc3c5
|
|
BLAKE2b-256 checksum How to use checksums |
aa34fa89594c6aaebb503cc2cf323fd717f504c021d89d742277e4e11b22bfd2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Release files / speculos-0.27.1-py3-none-any.whl
| Download URL | speculos-0.27.1-py3-none-any.whl |
|---|---|
| Size | 6.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2633b8067862957af88a9f97885d38cbbf45c6f6d9cc96dc52d62e69b03e5cf9
|
|
BLAKE2b-256 checksum How to use checksums |
07e7a392bcc8d3a8b3ed5040937bd59395382767cf835dd23e6c1fbaae054403
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
