Ledger Internet Computer App

https://github.com/zondax/ledger-icp
Admin
This project provides the Internet Computer (ICP) application for Ledger Nano S, S+, Nano X, Flex,...
Tokens:8,798
Snippets:39
Trust Score:9.6
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Ledger ICP App Script

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

This snippet shows how to make the installer script executable and then load the Internet Computer app onto a Ledger device. It's a direct way to get the app onto your hardware.

```shell
chmod +x ./installer_s.sh
./installer_s.sh load
```

--------------------------------

### Install Zemu for Testing

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Installs the Zemu testing framework, which is used for emulating Ledger devices and running integration tests. This command fetches the necessary npm packages.

```shell
make zemu_install
```

--------------------------------

### Run All Project Tests

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Performs a comprehensive test suite, including unit tests, integration tests, Zemu setup, application builds, and Zemu test execution. Requires Rust to be installed.

```shell
make test_all
```

--------------------------------

### Install Ubuntu Development Dependencies

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Installs essential build tools and libraries required for developing the Ledger ICP app on Ubuntu systems. This includes compilers, git, wget, cmake, and OpenSSL development files.

```shell
sudo apt update && apt-get -y install build-essential git wget cmake \
    libssl-dev libgmp-dev autoconf libtool
```

--------------------------------

### CMake: Basic Project Setup and Dependency Management

Source: https://github.com/zondax/ledger-icp/blob/main/CMakeLists.txt

Initializes the CMake project, sets the C++ standard, and configures dependencies using Hunter and FetchContent for fmt, nlohmann_json, and GTest. It also includes options for fuzzing, coverage, and sanitizers.

```cmake
cmake_minimum_required(VERSION 3.28)
include("cmake/HunterGate.cmake")
HunterGate(
    URL "https://github.com/cpp-pm/hunter/archive/v0.26.1.tar.gz"
    SHA1 "e41ac7a18c49b35ebac99ff2b5244317b2638a65"
    LOCAL
)

project(ledger-internet-computer VERSION 0.0.0)
enable_testing()

cmake_policy(SET CMP0025 NEW)
set(CMAKE_CXX_STANDARD 11)

set(HUNTER_STATUS_DEBUG ON)
set(HUNTER_TLS_VERIFY OFF)

option(ENABLE_FUZZING "Build with fuzzing instrumentation and build fuzz targets" OFF)
option(ENABLE_COVERAGE "Build with source code coverage instrumentation" OFF)
option(ENABLE_SANITIZERS "Build with ASAN and UBSAN" OFF)

hunter_add_package(fmt)
find_package(fmt CONFIG REQUIRED)

# Use FetchContent to get nlohmann_json 3.12.0 since Hunter doesn't support this version
include(FetchContent)
FetchContent_Declare(
    nlohmann_json
    URL https://github.com/nlohmann/json/releases/download/v3.12.0/json.tar.xz
    URL_HASH SHA256=42f6e95cad6ec532fd372391373363b62a14af6d771056dbfc86160e6dfff7aa
)
FetchContent_MakeAvailable(nlohmann_json)

hunter_add_package(GTest)
find_package(GTest CONFIG REQUIRED)
```

--------------------------------

### Build Ledger ICP App

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Compiles the Internet Computer application for Ledger devices. This command assumes all necessary build dependencies are already installed.

```shell
make
```

--------------------------------

### Get Token Information by Index

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

This endpoint retrieves information about a specific token using its index.

```APIDOC
## GET /api/token_at_idx

### Description
Retrieves information for a token at a specific index.

### Method
GET

### Endpoint
/api/token_at_idx/{token_index}

### Parameters
#### Path Parameters
- **token_index** (byte) - Required - The index of the token to retrieve (0-255).

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```json
{} 
```

### Response
#### Success Response (200)
- **TOKEN_INFO** (TokenInfo[]) - An array of TokenInfo structures.
  - **TOKEN_SYMBOL** (byte[]) - Token symbol string.
  - **TOKEN_NAME** (byte[]) - Token name string.
  - **DECIMALS** (byte) - Number of decimals.
- **SW1-SW2** (byte[2]) - Return code

#### Response Example
```json
{
  "TOKEN_INFO": [
    {
      "TOKEN_SYMBOL": "ICP",
      "TOKEN_NAME": "Internet Computer",
      "DECIMALS": 8
    }
  ],
  "SW1-SW2": "9000"
}
```
```

--------------------------------

### Get Supported Tokens Length

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

This endpoint retrieves the number of supported tokens registered in the Ledger ICP application.

```APIDOC
## GET /api/supported_tokens_len

### Description
Retrieves the number of supported tokens.

### Method
GET

### Endpoint
/api/supported_tokens_len

### Parameters
#### Query Parameters
- None

#### Request Body
- None

### Request Example
```json
{} 
```

### Response
#### Success Response (200)
- **LEN** (byte) - Number of supported tokens
- **SW1-SW2** (byte[2]) - Return code

#### Response Example
```json
{
  "LEN": 5,
  "SW1-SW2": "9000"
}
```
```

--------------------------------

### Initialize Project Dependencies

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Initializes project dependencies using either 'just' or 'make'. This command fetches and sets up necessary tools and libraries for the project's development environment.

```shell
just init
```

```shell
make init
```

--------------------------------

### Initialize Ledger Device for Development

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Initializes the Ledger device with a predefined test mnemonic and PIN. This is crucial for reproducible integration tests.

```shell
make dev_init
```

--------------------------------

### Load Ledger App onto Device

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Uploads the built application to the Ledger device. The existing application will be deleted before the new one is loaded.

```shell
make load
```

--------------------------------

### CMake: Static Library Source Discovery

Source: https://github.com/zondax/ledger-icp/blob/main/CMakeLists.txt

Uses the `file(GLOB_RECURSE ...)` command to find all C source files within the `deps/tinycbor/src` directory for building the tinycbor static library.

```cmake
##############################################################
##############################################################
#  static libs
file(GLOB_RECURSE TINYCBOR_SRC
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/tinycbor/src/cborparser.c
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/tinycbor/src/cborvalidation.c
        )
```

--------------------------------

### GDB Configuration for CLion

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Provides the necessary configuration for GDB (GNU Debugger) to work correctly with CLion when debugging the Ledger app. This file should be placed in your home directory.

```text
set auto-load local-gdbinit on
add-auto-load-safe-path /
```

--------------------------------

### Define Application Static Library (app_lib)

Source: https://github.com/zondax/ledger-icp/blob/main/CMakeLists.txt

This snippet defines a static library named 'app_lib'. It compiles C source files from the nanopb_tiny, ledger-zxlib, and various application directories. The library is configured to be publicly accessible in terms of include directories.

```cmake
file(GLOB_RECURSE TINYPB_SRC
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/nanopb_tiny/pb_common.c
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/nanopb_tiny/pb_decode.c
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/nanopb_tiny/pb_encode.c
        )

file(GLOB_RECURSE LIB_SRC
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/ledger-zxlib/src/hexutils.c
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/ledger-zxlib/src/app_mode.c
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/ledger-zxlib/src/bignum.c
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/ledger-zxlib/src/timeutils.c
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/ledger-zxlib/src/hexutils.c
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/ledger-zxlib/src/zxmacros.c
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/ledger-zxlib/src/zxformat.c
        ####
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/candid/*.c
        ####
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/parser.c
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/formatting.c
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/parser_impl.c
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/crypto.c
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/base32.c
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/protobuf/*.c
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/parser_print_*.c
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/token_info.c
        )

add_library(app_lib STATIC
        ${LIB_SRC}
        ${TINYCBOR_SRC}
        ${TINYPB_SRC}
        )

target_include_directories(app_lib PUBLIC
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/BLAKE2/ref
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/ledger-zxlib/include
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/tinycbor/src
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/picohash/
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/nanopb_tiny/
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/candid
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/lib
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/common
        )
```

--------------------------------

### Define Unit Test Executable (unittests)

Source: https://github.com/zondax/ledger-icp/blob/main/CMakeLists.txt

This snippet defines an executable target named 'unittests' for running unit tests. It includes C++ source files from the tests directory and links against the application library ('app_lib'), Google Test ('GTest::gtest_main'), and formatting libraries ('fmt::fmt', 'nlohmann_json::nlohmann_json').

```cmake
file(GLOB_RECURSE TESTS_SRC
        ${CMAKE_CURRENT_SOURCE_DIR}/tests/*.cpp)

add_executable(unittests ${TESTS_SRC})
target_include_directories(unittests PRIVATE
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src
        ${CMAKE_CURRENT_SOURCE_DIR}/app/src/lib
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/tinycbor/src
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/picohash/
        ${CMAKE_CURRENT_SOURCE_DIR}/deps/nanopb_tiny/
        )


target_link_libraries(unittests PRIVATE
        GTest::gtest_main
        app_lib
        fmt::fmt
        nlohmann_json::nlohmann_json)

add_compile_definitions(TESTVECTORS_DIR="${CMAKE_CURRENT_SOURCE_DIR}/tests/")
add_test(NAME unittests COMMAND unittests)
set_tests_properties(unittests PROPERTIES WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/tests)
```

--------------------------------

### Run Zemu Integration Tests

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Executes the Typescript-based integration tests using the Zemu framework. This command verifies the app's behavior in an emulated environment.

```shell
make zemu_test
```

--------------------------------

### Run C/C++ Unit Tests

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Executes the C/C++ unit tests for the Ledger ICP application on an x64 architecture. This verifies the core logic of the app.

```bash
make cpp_test
```

--------------------------------

### Run Specific Zemu Test

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Allows running a single, specific test case within the Zemu framework by name. Ensure the app is built (`make build`) if changes were made.

```shell
cd zemu
yarn test -t 'test name'
```

--------------------------------

### CMake: Fuzzing and Sanitizer Configuration

Source: https://github.com/zondax/ledger-icp/blob/main/CMakeLists.txt

Configures the build for fuzzing, enabling necessary definitions, setting the C++ compiler to Clang 11, and appending sanitizer flags. It also includes checks for compiler compatibility and enforces specific build types.

```cmake
if (ENABLE_FUZZING)
    add_definitions(-DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION=1)
    SET(ENABLE_SANITIZERS ON CACHE BOOL "Sanitizer automatically enabled" FORCE)
    SET(CMAKE_BUILD_TYPE Debug)

    if (DEFINED ENV{FUZZ_LOGGING})
        add_definitions(-DFUZZING_LOGGING)
        message(FATAL_ERROR "Fuzz logging enabled")
    endif ()

    set(CMAKE_CXX_CLANG_TIDY clang-tidy -checks=-*,bugprone-*,cert-*,clang-analyzer-*,-cert-err58-cpp,misc-*,-bugprone-suspicious-include)

    if ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
        # require at least clang 11
        if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS 11.0)
            message(FATAL_ERROR "Clang version must be at least 11.0!")
        endif ()
    else ()
        message(FATAL_ERROR
                "You are using an unsupported compiler! Fuzzing only works with Clang 11.\n"
                "1. Install clang-12 \n"
                "2. Pass -DCMAKE_C_COMPILER=clang-11 -DCMAKE_CXX_COMPILER=clang++-11")
    endif ()

    string(APPEND CMAKE_C_FLAGS " -fsanitize=fuzzer-no-link")
    string(APPEND CMAKE_CXX_FLAGS " -fsanitize=fuzzer-no-link")
    string(APPEND CMAKE_LINKER_FLAGS " -fsanitize=fuzzer-no-link")
endif ()

if (ENABLE_COVERAGE)
    string(APPEND CMAKE_C_FLAGS " -fprofile-instr-generate -fcoverage-mapping")
    string(APPEND CMAKE_CXX_FLAGS " -fprofile-instr-generate -fcoverage-mapping")
    string(APPEND CMAKE_LINKER_FLAGS " -fprofile-instr-generate -fcoverage-mapping")
endif ()

if (ENABLE_SANITIZERS)
    string(APPEND CMAKE_C_FLAGS " -fsanitize=address,undefined -fsanitize-recover=address,undefined")
    string(APPEND CMAKE_CXX_FLAGS " -fsanitize=address,undefined -fsanitize-recover=address,undefined")
    string(APPEND CMAKE_LINKER_FLAGS " -fsanitize=address,undefined -fsanitize-recover=address,undefined")
endif ()

string(APPEND CMAKE_CXX_FLAGS " -fsanitize=address -fno-omit-frame-pointer")
string(APPEND CMAKE_LINKER_FLAGS " -fsanitize=address -fno-omit-frame-pointer")
```

--------------------------------

### Define Fuzzing Targets

Source: https://github.com/zondax/ledger-icp/blob/main/CMakeLists.txt

This section conditionally defines fuzzing targets if 'ENABLE_FUZZING' is enabled. It creates separate executables for each fuzz target (e.g., 'fuzz-parser_parse') and links them with the 'app_lib'. It also applies the '-fsanitize=fuzzer' flag for fuzzing instrumentation.

```cmake
if (ENABLE_FUZZING)
    set(FUZZ_TARGETS
            parser_parse
            parser_protobuf
            )

    foreach (target ${FUZZ_TARGETS})
        add_executable(fuzz-${target} ${CMAKE_CURRENT_SOURCE_DIR}/fuzz/${target}.cpp)
        target_link_libraries(fuzz-${target} PRIVATE app_lib)
        target_link_options(fuzz-${target} PRIVATE "-fsanitize=fuzzer")
    endforeach ()
endif ()
```

--------------------------------

### General Command Structure

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Details the general structure of commands and responses for the Internet Computer App, including CLA, INS, P1, P2, L, and PAYLOAD for commands, and ANSWER, SW1-SW2 for responses.

```APIDOC
## General Command Structure

### Command Format:
- **CLA**: byte (1) - Application Identifier (0x11)
- **INS**: byte (1) - Instruction ID
- **P1**: byte (1) - Parameter 1
- **P2**: byte (1) - Parameter 2
- **L**: byte (1) - Bytes in payload
- **PAYLOAD**: byte (L) - Payload

### Response Format:
- **ANSWER**: byte (?) - Answer (depends on the command)
- **SW1-SW2**: byte (2) - Return code
```

--------------------------------

### Launch Zemu Emulator in Debug Mode

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Launches the Zemu emulator in debug mode, allowing the application to be debugged. The emulator will stop immediately upon launch, waiting for debugger attachment.

```shell
make zemu_debug
```

--------------------------------

### INS_GET_ADDR Response Structure

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Describes the response structure for the INS_GET_ADDR command, including the public key, address length and data (both in bytes and string format), and the return code.

```protobuf
message GetAddressResponse {
  // PK: Public Key (65 bytes)
  bytes pk = 1;
  // ADDR_B_LEN: Address as Bytes Length
  uint32 addr_b_len = 2;
  // ADDR_B: Address as Bytes
  bytes addr_b = 3;
  // ADDR_S_LEN: Address as String Length
  uint32 addr_s_len = 4;
  // ADDR_S: Address as String
  string addr_s = 5;
  // SW1-SW2: Return code
  uint32 sw1_sw2 = 6;
}
```

--------------------------------

### INS_GET_ADDR Command Specification

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Outlines the INS_GET_ADDR command used to request a user's address. It specifies the command fields (CLA, INS, P1, P2, L) and the derivation path parameters required for address generation.

```protobuf
message GetAddress {
  // CLA: Application Identifier (0x11)
  // INS: Instruction ID (0x01)
  // P1: Request User confirmation (0 = No)
  uint32 p1 = 1;
  // P2: Ignored
  uint32 p2 = 2;
  // L: Bytes in payload (depends)
  uint32 l = 3;
  // Path: Derivation Path Data
  repeated uint32 path = 4;
}
```

--------------------------------

### INS_GET_ADDR Command

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Details the INS_GET_ADDR command, including its parameters for derivation path and user confirmation, and the structure of its response containing public key and address information.

```APIDOC
## INS_GET_ADDR Command

### Command:
- **CLA**: byte (1) - Application Identifier: 0x11
- **INS**: byte (1) - Instruction ID: 0x01
- **P1**: byte (1) - Request User confirmation (No = 0)
- **P2**: byte (1) - Ignored
- **L**: byte (1) - Bytes in payload (depends)
- **Path**: byte (4) - Derivation Path Data (e.g., 0x80000000 | 44, 0x80000000 | 461')

### Response:
- **PK**: byte (65) - Public Key
- **ADDR_B_LEN**: byte (1) - Address as Bytes Length
- **ADDR_B**: byte (??) - Address as Bytes
- **ADDR_S_LEN**: byte (1) - Address as String Length
- **ADDR_S**: byte (??) - Address as String
- **SW1-SW2**: byte (2) - Return code (see list of return codes)
```

--------------------------------

### GET_VERSION Command Specification

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Defines the structure of the GET_VERSION command, including CLA, INS, P1, P2, and payload length. It also specifies the expected values for the command to retrieve version information from the Ledger device.

```protobuf
message GetVersion {
  // CLA: Application Identifier (0x11)
  // INS: Instruction ID (0x00)
  // P1: Ignored
  // P2: Ignored
  // L: Bytes in payload (0)
}
```

--------------------------------

### INS_CERTIFICATE_AND_SIGN

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Generates a certificate and signs it. This command also supports chunked data and requires derivation path information.

```APIDOC
## INS_CERTIFICATE_AND_SIGN

### Description
Generates a certificate and signs it. This command also supports chunked data and requires derivation path information.

### Method
Not Applicable (This describes a command structure, not an HTTP endpoint)

### Endpoint
Not Applicable

### Parameters
#### Command Parameters
- **CLA** (byte (1)) - Required - Application Identifier (0x11)
- **INS** (byte (1)) - Required - Instruction ID (0x06)
- **P1** (byte (1)) - Required - Payload descriptor: 0 = init, 1 = add, 2 = last
- **P2** (byte (1)) - Required - Ignored
- **L** (byte (1)) - Required - Bytes in payload (depends on payload size)

#### First Packet Data
- **Path[0]** (byte (4)) - Required - Derivation Path Data (Expected: 44)
- **Path[1]** (byte (4)) - Required - Derivation Path Data (Expected: 461)
- **Path[2]** (byte (4)) - Required - Derivation Path Data
- **Path[3]** (byte (4)) - Required - Derivation Path Data
- **Path[4]** (byte (4)) - Required - Derivation Path Data

#### Other Chunks/Packets Data
- **Data** (bytes...) - Required - Certificate Data

### Response
#### Success Response
- **secp256k1 R** (byte (32)) - Signature component R
- **secp256k1 S** (byte (32)) - Signature component S
- **secp256k1 V** (byte (1)) - Signature component V
- **SIG** (byte (variable)) - Signature in DER format
- **SW1-SW2** (byte (2)) - Return code (see list of return codes)

#### Response Example
```json
{
  "secp256k1 R": "...",
  "secp256k1 S": "...",
  "secp256k1 V": "...",
  "SIG": "...",
  "SW1-SW2": "9000"
}
```
```

--------------------------------

### GET_VERSION Command

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Defines the GET_VERSION command and its corresponding response, including expected values for CLA and INS, and the fields returned in the response.

```APIDOC
## GET_VERSION Command

### Command:
- **CLA**: byte (1) - Expected: 0x11
- **INS**: byte (1) - Expected: 0x00
- **P1**: byte (1) - Ignored
- **P2**: byte (1) - Ignored
- **L**: byte (1) - Expected: 0

### Response:
- **TEST**: byte (1) - Test Mode (0xFF means test mode is enabled)
- **MAJOR**: byte (1) - Version Major
- **MINOR**: byte (1) - Version Minor
- **PATCH**: byte (1) - Version Patch
- **LOCKED**: byte (1) - Device is locked
- **SW1-SW2**: byte (2) - Return code (see list of return codes)
```

--------------------------------

### TinyCBOR Constants and Types

Source: https://github.com/zondax/ledger-icp/blob/main/deps/tinycbor/src/cbor.dox

Defines global constants and enumerations for CBOR data types and known tags used within the TinyCBOR library. These are essential for understanding and manipulating CBOR data structures.

```c
/****************************************************************************
**
** Copyright (C) 2016 Intel Corporation
**
** Permission is hereby granted, free of charge, to any person obtaining a copy
** of this software and associated documentation files (the "Software"), to deal
** in the Software without restriction, including without limitation the rights
** to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
** copies of the Software, and to permit persons to whom the Software is
** furnished to do so, subject to the following conditions:
**
** The above copyright notice and this permission notice shall be included in
** all copies or substantial portions of the Software.
**
** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
** IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
** FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
** AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
** LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
** OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
** THE SOFTWARE.
**
****************************************************************************/

/**
 * \mainpage
 * The TinyCBOR $(VERSION) library is a small CBOR encoder and decoder library,
 * optimized for very fast operation with very small footprint. The main encoder
 * and decoder functions do not allocate memory.
 *
 * TinyCBOR is divided into the following groups of functions and structures:
 *  - \ref CborGlobals
 *  - \ref CborEncoding
 *  - \ref CborParsing
 *  - \ref CborPretty
 *  - \ref CborToJson
 */

/**
 * \file <cbor.h>
 * The <cbor.h> is the main header in TinyCBOR and defines the constants used by most functions
 * as well as the structures for encoding (CborEncoder) and decoding (CborValue).
 *
 * \sa <cborjson.h>
 */

/**
 * \file <cborjson.h>
 * The <cborjson.h> file contains the routines that are used to convert a CBOR
 * data stream into JSON.
 *
 * \sa <cbor.h>
 */

/**
 * \defgroup CborGlobals Global constants
 * \brief Constants used by all TinyCBOR function groups.
 */

/**
 * \addtogroup CborGlobals
 * @{
 */

/**
 * \var size_t CborIndefiniteLength
 *
 * This variable is a constant used to indicate that the length of the map or
 * array is not yet determined. It is used in functions
 * cbor_encoder_create_map() and cbor_encoder_create_array()
 */

/**
 * \enum CborType
 * The CborType enum contains the types known to TinyCBOR.
 *
 * \value CborIntegerType           Type is an integer value, positive, negative or zero
 * \value CborByteStringType        Type is a string of arbitrary raw bytes
 * \value CborTextStringType        Type is a text string encoded in UTF-8
 * \value CborArrayType             Type is a CBOR array
 * \value CborMapType               Type is a CBOR map (an associative container with key and value pairs)
 * \value CborTagType               Type is a CBOR tag (a 64-bit integer describing the item that follows, see CborKnownTags)
 * \value CborSimpleType            Type is one of the CBOR Simple Types
 * \value CborBooleanType           Type is a boolean (true or false)
 * \value CborNullType              Type encodes a null
 * \value CborUndefinedType         Type encodes an undefined value
 * \value CborHalfFloatType         Type is an IEEE 754 half precision (16-bit) floating point type
 * \value CborFloatType             Type is an IEEE 754 single precision (32-bit) floating point type
 * \value CborDoubleType            Type is an IEEE 754 double precision (64-bit) floating point type
 * \value CborInvalidType           Type is not valid (this value is used to indicate error conditions)
 */

/**
 * \enum CborKnownTags
 * The CborKnownTags enum contains known tags specified in RFC 7049, for use by the application.
 * TinyCBOR does not usually interpret the meaning of these tags and does not add them to the
 * output stream, unless specifically instructed to do so in functions for that effect.
 *
 * \value CborDateTimeStringTag     Text string contains a date-time encoded in RFC 3339 format, "YYYY-MM-DD hh:mm:ss+zzzz"
 * \value CborUnixTime_tTag         Number is a Unix time_t quantity, the number of seconds since 1970-01-01 midnight UTC
 * \value CborPositiveBignumTag     Item is a CBOR byte string encoding a positive integer of arbitrary precision
 * \value CborNegativeBignumTag     Item is a CBOR byte string encoding a negative integer of arbitrary precision
 * \value CborDecimalTag            Item is a CBOR array of two integers encoding a fixed-point decimal
 * \value CborBigfloatTag           Item is a bigfloat
 * \value CborExpectedBase64urlTag  Item is a CBOR byte string that is expected to be encoded as Base64Url
 * \value CborExpectedBase64Tag     Item is a CBOR byte string that is expected to be encoded as Base64
 */

```

--------------------------------

### Common Return Codes

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Lists and describes the common return codes encountered during operations with the Internet Computer App.

```APIDOC
## Common Return Codes

| Return Code | Description |
| ----------- | ----------- |
| 0x6400      | Execution Error |
| 0x6700      | Wrong buffer length |
| 0x6982      | Empty buffer |
| 0x6983      | Output buffer too small |
| 0x6984      | Data is invalid |
| 0x6985      | Conditions not satisfied |
| 0x6986      | Command not allowed |
| 0x6987      | Tx is not initialized |
| 0x6A80      | Bad key handle |
| 0x6B00      | P1/P2 are invalid |
| 0x6D00      | INS not supported |
| 0x6E00      | CLA not supported |
| 0x6F00      | Unknown |
| 0x6F01      | Sign / verify error |
| 0x9000      | Success |
| 0x9001      | Busy |
```

--------------------------------

### GET_VERSION Response Structure

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Details the structure of the response received after executing the GET_VERSION command. It includes fields for test mode, version numbers (major, minor, patch), device lock status, and return codes.

```protobuf
message GetVersionResponse {
  // TEST: Test Mode (0xFF if enabled)
  uint32 test = 1;
  // MAJOR: Version Major
  uint32 major = 2;
  // MINOR: Version Minor
  uint32 minor = 3;
  // PATCH: Version Patch
  uint32 patch = 4;
  // LOCKED: Device is locked
  uint32 locked = 5;
  // SW1-SW2: Return code
  uint32 sw1_sw2 = 6;
}
```

--------------------------------

### Add Development Certificate to Ledger Device

Source: https://github.com/zondax/ledger-icp/blob/main/README.md

Adds a development certificate to the Ledger device. This bypasses the need for manual confirmation during development workflows.

```shell
make dev_ca
```

--------------------------------

### INS_SIGN

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Handles the signing of transactions by receiving command parameters and data chunks.

```APIDOC
## POST /sign

### Description
This endpoint is used to sign transactions or data payloads using the Ledger ICP. It accepts a series of commands and data packets to construct and sign the final output.

### Method
POST

### Endpoint
/sign

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**Command:**
- CLA (byte, 1) - Application Identifier (Expected: 0x11)
- INS (byte, 1) - Instruction ID (Expected: 0x02)
- P1 (byte, 1) - Payload descriptor (0 = init, 1 = add, 2 = last)
- P2 (byte, 1) - Additional flags (e.g., is_stake_tx)
- L (byte, 1) - Length of the payload in bytes

**First Packet/Chunk:**
- Path (byte[4]) - Derivation Path Data (e.g., [44, 461, ?, ?, ?])

**Other Chunks/Packets:**
- Data (bytes...) - CBOR data to sign

### Request Example
```json
{
  "command": {
    "CLA": "0x11",
    "INS": "0x02",
    "P1": "0x00",
    "P2": "0x00",
    "L": "32"
  },
  "data_chunks": [
    {
      "path": ["0x2c", "0x01","0xcd", "0x00", "0x00"],
      "payload": ""
    },
    {
      "payload": "a10101a26361616163626262636363"
    }
  ]
}
```

### Response
#### Success Response (200)
- secp256k1 R (byte[32]) - Signature R component
- secp256k1 S (byte[32]) - Signature S component
- secp256k1 V (byte[1]) - Signature V component
- SIG (byte[variable]) - Signature in DER format
- SW1-SW2 (byte[2]) - Return code

#### Response Example
```json
{
  "secp256k1_R": "...",
  "secp256k1_S": "...",
  "secp256k1_V": "...",
  "SIG": "...",
  "SW1_SW2": "9000"
}
```
```

--------------------------------

### INS_SIGN_COMBINED

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Executes a combined signing operation, processing both state read and request data.

```APIDOC
## POST /sign_combined

### Description
This endpoint performs a combined signing operation. It handles both state read data and request data, returning hashes and signatures for both.

### Method
POST

### Endpoint
/sign_combined

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**Command:**
- CLA (byte, 1) - Application Identifier (Expected: 0x11)
- INS (byte, 1) - Instruction ID (Expected: 0x03)
- P1 (byte, 1) - Payload descriptor (0 = init, 1 = add, 2 = last)
- P2 (byte, 1) - Additional flags (e.g., is_stake_tx)
- L (byte, 1) - Length of the payload in bytes

**First Packet/Chunk:**
- Path (byte[4]) - Derivation Path Data (e.g., [44, 461, ?, ?, ?])

**Other Chunks/Packets:**
- State Read Length (byte[4]) - Length of state read data
- State Read Data (bytes..) - State read CBOR data
- Request Length (byte[4]) - Length of request data
- Request Data (bytes..) - Request CBOR data

### Request Example
```json
{
  "command": {
    "CLA": "0x11",
    "INS": "0x03",
    "P1": "0x00",
    "P2": "0x00",
    "L": "64"
  },
  "data_chunks": [
    {
      "path": ["0x2c", "0x01","0xcd", "0x00", "0x00"],
      "state_read_length": "32",
      "state_read_data": "...",
      "request_length": "32",
      "request_data": "..."
    }
  ]
}
```

### Response
#### Success Response (200)
- Request Hash (byte[32]) - Hash of the request data
- Request Signature (byte[64]) - Signature of the request hash
- State Read Hash (byte[32]) - Hash of the state read data
- State Read Signature (byte[64]) - Signature of the state read hash
- SW1-SW2 (byte[2]) - Return code

#### Response Example
```json
{
  "request_hash": "...",
  "request_signature": "...",
  "state_read_hash": "...",
  "state_read_signature": "...",
  "SW1_SW2": "9000"
}
```
```

--------------------------------

### INS_SUPPORTED_TOKENS_LEN

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Retrieves the length of supported tokens. This is a read-only command.

```APIDOC
## INS_SUPPORTED_TOKENS_LEN

### Description
Retrieves the length of supported tokens. This is a read-only command.

### Method
Not Applicable (This describes a command structure, not an HTTP endpoint)

### Endpoint
Not Applicable

### Parameters
#### Command Parameters
- **CLA** (byte (1)) - Required - Application Identifier
- **INS** (byte (1)) - Required - Instruction ID
- **P1** (byte (1)) - Required - Payload descriptor
- **P2** (byte (1)) - Required - Ignored
- **L** (byte (1)) - Required - Bytes in payload

### Response
#### Success Response
- **SW1-SW2** (byte (2)) - Return code (see list of return codes)

#### Response Example
```json
{
  "SW1-SW2": "9000"
}
```
```

--------------------------------

### INS_TRANSACTION_SIGN

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Signs an ICP transaction. This command supports chunked data transfer for large payloads and includes derivation path information in the first packet.

```APIDOC
## INS_TRANSACTION_SIGN

### Description
Signs an ICP transaction. This command supports chunked data transfer for large payloads and includes derivation path information in the first packet.

### Method
Not Applicable (This describes a command structure, not an HTTP endpoint)

### Endpoint
Not Applicable

### Parameters
#### Command Parameters
- **CLA** (byte (1)) - Required - Application Identifier (0x11)
- **INS** (byte (1)) - Required - Instruction ID (0x04)
- **P1** (byte (1)) - Required - Payload descriptor: 0 = init, 1 = add, 2 = last
- **P2** (byte (1)) - Required - Ignored
- **L** (byte (1)) - Required - Bytes in payload (depends on payload size)

#### First Packet Data
- **Path[0]** (byte (4)) - Required - Derivation Path Data (Expected: 44)
- **Path[1]** (byte (4)) - Required - Derivation Path Data (Expected: 461)
- **Path[2]** (byte (4)) - Required - Derivation Path Data
- **Path[3]** (byte (4)) - Required - Derivation Path Data
- **Path[4]** (byte (4)) - Required - Derivation Path Data

#### Other Chunks/Packets Data
- **Data** (bytes...) - Required - Consent Request

### Response
#### Success Response
- **SW1-SW2** (byte (2)) - Return code (see list of return codes)

#### Response Example
```json
{
  "SW1-SW2": "9000"
}
```
```

--------------------------------

### INS_CANISTER_CALL_TX

Source: https://github.com/zondax/ledger-icp/blob/main/docs/APDUSPEC.md

Executes a canister call transaction. Similar to transaction signing, it supports chunked data and derivation path specification.

```APIDOC
## INS_CANISTER_CALL_TX

### Description
Executes a canister call transaction. Similar to transaction signing, it supports chunked data and derivation path specification.

### Method
Not Applicable (This describes a command structure, not an HTTP endpoint)

### Endpoint
Not Applicable

### Parameters
#### Command Parameters
- **CLA** (byte (1)) - Required - Application Identifier (0x11)
- **INS** (byte (1)) - Required - Instruction ID (0x05)
- **P1** (byte (1)) - Required - Payload descriptor: 0 = init, 1 = add, 2 = last
- **P2** (byte (1)) - Required - Ignored
- **L** (byte (1)) - Required - Bytes in payload (depends on payload size)

#### First Packet Data
- **Path[0]** (byte (4)) - Required - Derivation Path Data (Expected: 44)
- **Path[1]** (byte (4)) - Required - Derivation Path Data (Expected: 461)
- **Path[2]** (byte (4)) - Required - Derivation Path Data
- **Path[3]** (byte (4)) - Required - Derivation Path Data
- **Path[4]** (byte (4)) - Required - Derivation Path Data

#### Other Chunks/Packets Data
- **Data** (bytes...) - Required - Canister Call

### Response
#### Success Response
- **SW1-SW2** (byte (2)) - Return code (see list of return codes)

#### Response Example
```json
{
  "SW1-SW2": "9000"
}
```
```
Tokens:
Raw