README.md

Web Device Management Kit

Ledger Developer Portal · Report Bug · Request Feature

Introduction

The purpose of the Ledger Device Management Kit(LDMK in short) is to provide a library in TypeScript to easily handle Ledger devices:

• Device enumeration, identification and connection management
• Device actions, with full status and error report
• In the future: Firmware and Applications installation/update.

⚠️ The current version of this Device Management Kit is in alpha stage and is subject to significant changes!!! ⚠️

How does it works

The Device Management Kit features an interface for applications to handle any Ledger device (a.k. hardware wallets). It convert intention into

  flowchart LR;
      application(Application) <--API--> LDMK(LedgerDeviceManagementKit) <--USB/BLE--> device(Device);

Loading

The Device Management Kit is available in 3 different environments (web, Android & iOS).

This repository is dedicated to web environment and is written in TypeScript.

Structure

Repository

The Device Management Kit is structured as a monorepository whose prupose is to centralise all the TypeScript code related to the Device Management Kit in one place.

This project uses turbo monorepo to build and release different packages on NPM registry and a sample demo application on Vercel.

Modules

A brief description of this project packages:

Name	Path	Description
@ledgerhq/device-management-kit-sample	apps/sample	React Next web app used to test & demonstrate the Web Device Management Kit
@ledgerhq/eslint-config-dsdk	packages/config/eslint	internal package which contains eslint shared config. Used by extends: ["@ledgerhq/dsdk"] in .eslintrc.
@ledgerhq/jest-config-dsdk	packages/config/jest	internal package which contains jest shared config. Used by preset: "@ledgerhq/jest-config-dsdk" in jest.config.ts
@ledgerhq/tsconfig-dsdk	packages/config/typescript	internal package which contains typescript shared config. Used by "extends": "@ledgerhq/tsconfig-dsdk/tsconfig.sdk" in tsconfig.json
@ledgerhq/device-management-kit	packages/device-management-kit	external package that contains the core of the Web Device Management Kit
@ledgerhq/device-signer-kit-ethereum	packages/signer/signer-eth	external package that contains device ethereum coin application dedicated handlers
@ledgerhq/device-signer-kit-solana	packages/signer/signer-solana	external package that contains device solana coin application dedicated handlers
@ledgerhq/device-management-kit-flipper-plugin-client	packages/flipper-plugin-client	external package that contains flipper logger for Device Management Kit
@ledgerhq/device-transport-kit-web-hid	packages/transport/web-hid	external package that contains the Web Hid transport implementation
@ledgerhq/device-transport-kit-web-ble	packages/transport/web-ble	external package that contains the Web Ble transport implementation
@ledgerhq/device-mockserver-client	packages/mockserver-client	external package that contains the client to interact with the mock-server

Getting started

💡 The following steps described only a minimal setup. You will need to perform additional installation steps depending on the package you want to work on, please refer to its nested readme file.

Prerequisites

Shell

Install your favorite shell or use your computer built in one (e.g. bash, zsh or fish )

Git

Please install git.

Environment Setup

Proto

proto is used as the toolchain manager to install the right version of every tools.

⚠️ Important: Please follow the instructions on the proto website to install it.

Dependencies management

pnpm is used as the package manager to install all the dependencies. It is normally provided by Proto (see below).

Installation

1- Clone the repository

git clone [email protected]:LedgerHQ/device-sdk-ts.git
cd device-sdk-ts

Important: All the commands should be run at the root of the monorepo.

2- Configure using proto

proto use

3- Install dependencies

pnpm i

Alternatively, if you want to bypass the postinstall scripts which can be long to run.

pnpm i --ignore-scripts

4- Check the shell configuration file

In you shell configuration file (e.g. .bashrc or .zshrc ) verify the path for proto is correctly set. Update it if needed according to the description below.

# proto
export PROTO_HOME="$HOME/.proto"
export PATH="$PROTO_HOME/shims:$PROTO_HOME/bin:$PATH"

Unit Test

Jest is used for unit testing purpose.

Each package is tested using the following command (at the root of the monorepo).

pnpm <package> test

VSCode user

For VSCode user, this monorepo is a multi-root workspace. Please configure JEST extention accordingly.

Build

Each package is built using the following command (at the root of the monorepo).

Device Management Kit

Device Management Kit main module.

pnpm dmk build

Signer

Transaction and message signer module.

pnpm signer build

Trusted Apps

Security dedicated application interface module.

pnpm trusted-apps build

UI

Reference UI module

pnpm ui build

Sample application

Sample application module.

pnpm sample build

Processes & usage

Continuous integration

This project uses Github CI. Please have a look to the following link for more details: GitHub

Scripting

In order to avoid task repetition, we can add some scripts the corresponding package's script folder, on in a root script folder if it concerns multiple packages. A script is a .mjs file interpreted by zx.

Templates

To kickly scaffold part of our code, we use hygen to help us kickstart our development process faster. Each project can have it's own _templates folder, so generators are scoped. The _templates folder contains the basic generators to create new ones.

Hygen documentation

Process for adding a new generator

The easiest way would be to use hygen from the root folder as so:

Options:

• new: creates a generator that take no input during creation (but can still access metadata)
• with-prompt: creates a generator that can take some input during creation (with access to metadata)

Important: All the commands should be run at the root of the monorepo.

pnpm hygen generator with-prompt|new name

This command will create a new generator folder in the root _templates with the given name. It's there so that we can modify this new generator. When done, move the new generator to it's correct project _templates folder (again, so we can keep scope). Finally, we should add a script in the correct package.json as a shortcut to trigger the new generator. eg:

pnpm dmk module:create

Under the hood, the script looks like this:

pnpm hygen <name> with-prompt

• name is the name given during the creation of the generator.
• with-prompt to call the prompted version of the generator (there can be multiple targets, like new)

Available templates

workspace	script	description
📦 dmk	module:create	scaffolds a new src/internal module

Play with the sample app ?

To build the required dependencies and start a dev server for the sample app, please execute the following command at the root of the repository.

pnpm dev

Documentation

Each project folder has a README.md file which contains basic documentation. It includes background information about the project and how to setup, run and build it.

Reference API

Please refer to the core package readme.

Contributing

Please check the general guidelines for contributing to Ledger Live projects: CONTRIBUTING.md.

Each individual project may include its own specific guidelines, located within its respective folder.

License

Please check each project LICENSE file, most of them are under the Apache-2.0 license.