DISCLAIMER

⚠️	THIS IS AN EXPERIMENTAL PROJECT. IT IS INSECURE AT THIS STAGE Please don't start depending on it, and do not use it in production. Large parts of this project are subject to change.	⚠️

---

Vanadium

Vanadium is a Risc-V Virtual Machine that runs in an embedded Secure Element.

By outsourcing encrypted, authenticated pages to an untrusted client, it allows you to run applications (V-Apps) in the secure element without worrying about the limitations of the embedded platform.

• No memory constraints: Only the code and data actually used at runtime is sent to the device. Page swapping happens transparently.
• Native Development: Write and test code natively on your machine before deploying to the embedded device.
• Secure: Execution happens in the Secure Element. Page authentication and encryption prevents the host from tampering.

Developer Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

1. Rust & Risc-V Target:

   rustup target add riscv32imc-unknown-none-elf

2. just (Command runner):

   • Ubuntu/Debian: sudo apt install just
   • macOS: brew install just
   • Other: See just installation guide.

   We recommend to also install its autocomplete for the shell you are using.

3. Dependencies:

   • Ubuntu/Debian: sudo apt install libssl-dev pkg-config libudev-dev
   • macOS: brew install openssl pkg-config libusb hidapi eudev

4. cargo-vnd (Vanadium companion tool):

   cargo install --git https://github.com/LedgerHQ/vanadium cargo-vnd

Setup

Clone this repository to get access to the build scripts and emulator tools:

git clone https://github.com/LedgerHQ/vanadium.git
cd vanadium

Hello World

Create a new project named hello. You can do this in the root of the repo or a separate workspace.

cargo vnd new --name hello

This creates:

• hello/app: The V-App (runs on device)
• hello/client: The client and CLI interface (runs on computer)

If you use Visual Studio Code, you can open the multi-root workspace:

code hello/vapp.code-workspace

Building and Running

1. Build the V-App

Go to the app directory and build:

cd hello/app
just build

This builds the app for both the native and the Risc-V targets.

You can also run its tests:

cargo test

2. Run Natively

You can test your app logic without any hardware or emulator by running both the app and the client on your computer, in two different terminals. The two programs will communicate over a socket.

Terminal 1 (The App):

cd hello/app
cargo run

You can interact with the app (when needed) via the terminal.

Terminal 2 (The Client/CLI interface):

cd hello/client
cargo run

3. Run on Speculos Emulator

This section requires the installation of the speculos emulator. On Ubuntu/Debian:

# install speculos dependencies
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 libxcb-cursor0

# install pipx (if you don't already have it)
sudo apt install pipx  # if you don't already have it
pipx ensurepath

pipx install speculos  # alternatively, use a python virtual environment

To run on the device emulator, you first need the Vanadium VM binary.

1. Download the precompiled VM binary:

   cd vm
   bash download_vanadium.sh

   Alternatively, find the instructions to compile the app in the vm folder.

2. Launch the Emulator (in the vm folder):

   just run-nanosplus  # Options: run-nanox, run-flex, run-stax, run-apex_p

3. Run your Client/CLI interface (in hello/client):

   cargo run

4. Run on Ledger Device

On all devices except Nano X, you can sideload the Vanadium app.

First, make sure that your device's firmware is up to date. You can use Ledger Wallet to install the latest firmware OS.

One option is to use the Ledger VSCode Extension.

Alternatively, install the following dependencies:

sudo apt install libudev-dev libusb-1.0-0-dev python3-venv

Then, connect and unlock the device, and run:

cd vm
bash download_vanadium.sh
bash load_vanadium.sh    

Once Vanadium is installed:

1. Connect your device and open the Vanadium App.
2. Run the Client/CLI interfacce:

   cd hello/client
   cargo run

Next Steps

Congratulations, you built and ran your first V-App!

Here are a few ways to continue your journey:

• Explore Examples: Check out the Rock Paper Scissors and Bitcoin V-Apps to see more complex implementations.
• Dive into Documentation: Read about the Architecture, Security Considerations, and available System Calls.
• Start Building: Modify your hello app or create a new one to build your own secure application.

We look forward to seeing what you will build!

Repository Structure

This repository is organized in a monorepo structure.

• docs - Architecture and technical documentation
• VM [arm], no-std - The Vanadium Ledger app. It contains the actual Virtual Machine.
• app-sdk [riscv], no_std - Vanadium V-App SDK. It is used by V-Apps to access all the system services.
• client-sdk [native] - Vanadium V-App client SDK. V-App Clients use it as a base for their own client crates.
• common [arm|riscv|native], no_std - Any code that is shared among two or more of the above crates.
• apps - Complete V-Apps, and their clients.
  • template - A minimal boilerplate app used as a template by cargo vnd new.
  • rps - Play Rock-Paper-Scissors against your hardware signer.
  • bitcoin - A work-in-progess app for signing bitcoin transactions.
  • test - Simple V-App to test the Vanadium VM, implementing various computational tasks.
  • sadik - A V-App specifically designed to test the various functionality of the Vanadium V-App SDK, and particularly the ECALLs.
• libs - General purpose libraries that can be used by V-Apps.
  • bitcoin - A custom clone of the rust-bitcoin library.
• cargo-vnd - A tool to create and package V-Apps.

Vanadium Developers

If you want to contribute to Vanadium itself (the VM or SDKs), open the vanadium.code-workspace in VSCode. This workspace is configured for multi-crate development.

Find more information on how to install the necessary tools to develop the Vanadium VM Ledger app in the vm folder.

License

This project is licensed under the Apache Licence v2.0.

Individual crates inside this repository might be release under a different license - that will be specified in the corresponding LICENSE file.