CoolWallet Pro Firmware

July 24, 2026 · View on GitHub

CoolWallet Pro Firmware Logo

Official Website｜Discord | Twitter Follow

Introduction

CoolWallet Pro Firmware is a Javacard firmware designed specifically for the CoolWallet Pro. It offers advanced features for private key management, signing, and transaction data composition. The firmware focuses on developing a secure element solution using Java Card technology to ensure a high level of security for cryptographic operations and the protection of sensitive data.

Key Features

  • Private key management: Safely store and manage private keys within the secure element of the CoolWallet Pro.
  • Signing: Perform secure and verifiable digital signatures for transactions and authentication purposes.
  • Transaction data composition: Generate and compose transaction data in a secure manner, ensuring data integrity and confidentiality.

Security and Privacy

The CoolWallet Pro Firmware prioritizes security and privacy to protect users' digital assets. It leverages the advanced security features of Java Card technology, providing a robust and tamper-resistant environment for cryptographic operations. With the CoolWallet Pro Firmware, users can have confidence in the confidentiality, integrity, and authenticity of their transactions and sensitive data.

Supported Algorithms

Hash:

  • Blake2b
  • HmacSha
  • Sha2
  • Sha3
  • Ripemd

Signature:

  • Ed25519
  • Secp256k1
  • Curve25519
  • Bip32-Ed25519 (Cardano Signature)

Project Installation (Common)

To install the project, please follow the steps below:

Step 1: Cloning the Repository

Clone the repository by running the following command in your terminal or command prompt:

git clone git@github.com:CoolBitX-Technology/coolwallet-pro-se.git

Step 2: Initialize and Update Submodule

Initialize and update the submodule by running the following commands:

$ git submodule init
$ git submodule update

Step 3: Run the Installation Script

Run the installation script by executing the following command:

$ cd coolwallet-pro-se-crypto
$ javac Installation.java
$ java Installation

Note: The Crypto Library is an internal library provided by CoolBitX, offering a range of encoding and digital signature algorithms.

Windows Note: This script creates symbolic links from src/coolbitx/ to the files in coolwallet-pro-se-crypto/src/. Creating a symbolic link on Windows requires the SeCreateSymbolicLinkPrivilege, which a standard user account does not have by default. If you run the commands above from a normal (non-elevated) terminal, symlink creation will fail with an AccessDeniedException and Eclipse will show the crypto classes (Sha2, Ed25519, etc.) as missing/unresolved. To fix this, do one of the following before running java Installation:

  • Enable Developer Mode (Settings → Update & Security → For developers → Developer Mode), or
  • Run your terminal/command prompt as Administrator.

You only need elevated privileges at the moment the links are created — once the symlinks exist, opening and building the project in Eclipse afterwards works normally with a regular user account. If you ever re-run java Installation (e.g. after new files are added to the crypto library), repeat this with an elevated/Developer Mode session.

Environment Setup

This project supports two development workflows:

  1. Windows (Eclipse): Official NXP JCOP Tools workflow for CAP file generation.
  2. Cross-Platform (CLI / VS Code): Script-based workflow for macOS, Linux, and Windows (WSL), supporting local simulation.

1. Windows Environment Setup (Eclipse)

To successfully build and set up the development environment for this project on Windows using Eclipse, please follow the instructions below:

Prerequisites

Setting Up Environment Variables

After installing Java, it is essential to set up environment variables on your Windows computer.

System Variables
  • JAVA_HOME: Set the path to the JDK installation directory.
  • PATH: Add the following paths to the system's PATH variable:
    • %JAVA_HOME%\bin

Required Tools Installation

To ensure a smooth compilation process, it is recommended to have the following programs and versions installed:

JCOP Tools Installation

  1. Download the JCOP Tools installation package and save it to a directory of your choice.
  2. Launch Eclipse IDE.
  3. From the menu bar, go to Help > Install New Software.
  4. In the Install dialog, click on Add to add new features.
  5. In the Add Site dialog:
    • Provide a descriptive name, such as 'NXP JCOP Tools'.
    • If you have unpacked the JCOP Tools package, select Local... and navigate to the root folder of JCOP Tools.
    • If JCOP Tools is a ZIP file, select Archive... and navigate to the ZIP file.
  6. Restart Eclipse to complete the installation.

Activating JCOP Tools

  1. Open Eclipse and navigate to File > New > Java Card Project.
  2. Choose the appropriate wizard:
    • Create a Java Card project.
    • Select the licensed JCOP: JCOP_Tools_activation_workspace.

Library Setup (Required)

Before opening the project in Eclipse, you must place the following library files into local_lib/javacard-libs/:

FileSource
api_classic.jarExtracted from NXP_JCOP_Plugin_5.32.0.4.zip
JCOPx_API-R1.1.4.jarExtracted from NXP_JCOP_Plugin_5.32.0.4.zip
bcprov-jdk15on-1.70.jarMaven Central

These files are referenced by the project's .classpath and are required for Eclipse to compile the source successfully.

If you are on macOS/Linux, you can run scripts/setup-libs.sh to extract these automatically. On Windows, you can obtain the first two jars by extracting NXP_JCOP_Plugin_5.32.0.4.zip and locating them inside the plugin bundle, or request a pre-packaged zip from a teammate who has already run the setup script.

2. Cross-Platform Environment Setup (CLI / VS Code)

This workflow is recommended for users on macOS, Linux, or Windows (WSL) who prefer using command-line tools or VS Code/Cursor. It supports compiling, simulating (without a physical card), and generating CAP files.

Prerequisites

  • A JDK on JAVA_HOME (or PATH) — any version works (verified on 8, 11, 17)
  • Gradle (for downloading simulator dependencies)

Configuration

1. VS Code Configuration (Optional)

This tells the VS Code Java extension where a JDK 8 is so that IDE features (code completion, error highlighting, etc.) work correctly. It has no effect on the build scripts.

The project's .vscode/settings.json already configures VS Code to auto-detect Java 8, so no manual changes are needed in most cases.

If auto-detection fails (e.g., multiple JDKs installed and the wrong one is picked), you can pin the path explicitly in .vscode/settings.json:

{
    "java.configuration.runtimes": [
        {
            "name": "JavaSE-1.8",
            "path": "/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home", // Set your Java 8 path here
            "default": true
        }
    ]
}

Workflow

Step 1: Initial Setup (One-time)

Before running the setup script, you must obtain the NXP JCOP Plugin (version 5.32.0.4) and place it in the local_lib directory.

  1. Obtain NXP_JCOP_Plugin_5.32.0.4.zip.
  2. Ensure the local_lib directory exists (create it if needed): 
    mkdir -p local_lib
  3. Place the file at: local_lib/NXP_JCOP_Plugin_5.32.0.4.zip.

Run the setup script to extract dependencies:

chmod +x scripts/setup-libs.sh
scripts/setup-libs.sh

Step 2: Build the Project

To compile the JavaCard applet:

chmod +x scripts/build.sh
scripts/build.sh

scripts/build.sh will:

  • Compile all .java files under src/ to JavaCard-compatible bytecode
  • Use the JavaCard / JCOP jars in local_lib/javacard-libs as the classpath
  • Output .class files into the bin/ directory

Step 3: Run the Simulator (Web Service)

To start the APDU simulation web service on port 9527:

chmod +x scripts/run-web-server.sh
scripts/run-web-server.sh

This service allows you to send APDUs via HTTP POST to http://localhost:9527/apdu. Example:

curl -X POST http://localhost:9527/apdu -d '00A404000D436F6F6C57616C6C657450524F'

Step 4: Generate CAP files

chmod +x scripts/cap-build.sh
scripts/cap-build.sh

Produces two CAP packages:

  • Main applet: coolbitx (AID CoolWalletPRO) → bin/coolbitx/javacard/coolbitx.cap
  • SIO applet: coolbitx.sio (AID BackupApplet) → bin/coolbitx/sio/javacard/sio.cap

To install onto a physical card via GlobalPlatformPro:

chmod +x scripts/main-cap-install.sh
scripts/main-cap-install.sh

License

This project is licensed under the CoolBitX Limited Use License.

Security Vulnerability Disclosure

If you discover any security vulnerabilities, please contact bounty@cbx.io For more details, refer to the Bounty Project. Do not disclose the content directly on public forums.

Feel free to contact us for any inquiries or support.