## 1. Purpose

CryptoCalc is a Cryptocurrency wallet generator provided as a standalone non custodial desktop application. These wallets can be Non Deterministic (Simple Wallet) or Hierarchical Deterministic (`BIP32`). Even though there are already similar tools online, the purpose is to provide these features locally on your computer (non custodial) in order to reduce the risk of your Private Key / WIF or Secret phrase information being stolen.

NB: Since its first release CryptoCalc has been downloaded 16792 times on npm.

You can support this project by testing and reporting bugs (or asking for enhancements) with Issues, provide localization files (see 5.1.19).

Cryptocalc is developed by Aladas, a non profit organization whose primary goal is to protect Wild bees.

## 2. Features

### 2.0. Recently added features

- Help Enhancement: the `Help menu` provides now an HTML version of `README.md` and a documentation of test protocols.
- Added `Unit tests`: these tests use Jest unit test framework. It is an ongoing work (694 tests ATM). Use `npm test` to run the unit tests (to open a CLI console, double click on `_open_cmd_window.bat`).
- Added `e2e tests` (Real user scenario testing): these tests use Playwright.
- `Wallets Database`: you can now populate a `SQLite` database by importing the Wallet informations (`.wits` files in timestamped subfolders under `_output` folder).
- Added support of `Bip84` purpose in the `Bip32 derivation path`.

### 2.1. Support of HD / Bip32 (multiple wallets)

Added support of `Bip84` purpose in the `Bip32 derivation path` (HD Wallet). Notice that it is usable only with `Bitcoin` and `Litecoin`.

### 2.2. Selection of `Entropy size` (between 128 and 256 bits)

### 2.3. Dynamic conversion between `Entropy` and `Secret phrase`

### 2.4. `File/Save/Open..` commands

These commands allow edition of Wallet informations after saving (these informations are saved as a `.wits`, a `JSON` format file).

### 2.5. Salted Entropy source

`Entropy` value is indeed computed by combining the `Salt` (currently a dynamically generated `UUID`) with the value provided by the `Entropy source`.

- `SHA256` hash function is applied to this: `Salt + Entropy source`.

### 2.6. Security Layers

- `Bip38` support (first method 'Non-EC').

### 2.7. Multiple Entropy sources

`100 d6 dices`, `Mouse moves`, `Images` and `Fortune cookies`.

### 2.8. QR code generation

For Wallet address, Private Key (also WIF if applicable) and Mnemonics. There is also an `xtras` folder with the SVG versions of these QR codes as well as more experimental QR code formats (rectangular Micro QR code and Ultracode which has colored modules).

### 2.9. Customizable options

Options includes `Blockchain`, `Wallet mode` (eg: Simple / HD / SWORD) and `Entropy size`.

### 2.10. Wallets Database

A SQLite Database is populated by importing `.wits` files (Wallet informations in a `JSON` format file). Then the SQLite Database can be explored with DBeaver.

### 2.11. Visual feedback of the `Passphrase Strength` (`Bip32/Bip38`)

### 2.12. List of `Word indexes`

The crucial data in the `Secret phrase` is indeed the list of `Word indexes` (indexes in the `BIP39` wordlist), is explicitly displayed so if the language is changed these word indexes are the same.

### 2.13. Internet connection status

Because of the Cold wallet / Non custodial purpose of Cryptocalc, it is not recommended to generate cryptocurrency wallets while being online. The status is displayed on the right of the main horizontal toolbar, it's a red "connected" icon when online and a green "disconnected" icon when offline (the highly recommended way to use Cryptocalc).

### 2.14. Localization

Translations of GUI labels in the user's language (only English and French files provided currently but the localization feature allows translations in other languages as well, they are in `JSON` format eg. `gui-msg-en.json`).

### 2.15. Dynamic links

- Address wallet in the appropriate `Blockchain Explorer` (e.g. blockchain.com).
- Informations in `Coinmarketcap.com` for the wallet's cryptocurrency.
- 3D representation of the `Secret phrase` (see an example here: Cryptoshape).

### 2.16. Dedicated Tools

- The first dedicated tool is `Secret phrase Translator`, it allows to import a generated wallet with a Secret phrase in a non `Bip39` official language (eg. `Russian`) and translate it to its equivalent in `English` (because Wallet Managers support only English).

### 2.17. Standalone installer

It is published on SourceForge. Once downloaded the installer will install Cryptocalc as a `.exe` local standalone desktop application (see 3.1.1) with all its prerequisites. This allows users to install Cryptocalc without installing `NodeJS`, `git` and `npm` and using command line instructions (described in 3.2).

### 2.18. Tested on `Windows` and `Linux`

- `Windows`: tested on `Windows 10`.
- `Linux`: tested on Linux Mint 22.2 (NB: tested on a virtual machine within VirtualBox).

### 2.19. Cryptocurrencies: 23 supported Cryptocurrencies

`BTC` (Bitcoin), `ETH` (Ethereum), `XRP` (Ripple), `BNB` (Binance Smart Chain), `SOL` (Solana), `DOGE` (Dogecoin), `TRX` (TRON), `ADA` (Cardano), `XLM` (Stellar), `SUI` (Sui), `BCH` (Bitcoin Cash), `AVAX` (Avalanche), `TON` (Toncoin), `LTC` (Litecoin), `ETC` (Ethereum Classic), `POL` (Polygon), `VET` (VeChain), `BSV` (Bitcoin SV), `DASH` (Dash), `RVN` (Ravencoin), `ZEN` (Horizen), `LUNA` (Terra) and `FIRO` (Firo).

- A list of the Top 50 market cap cryptocurrencies is provided (`_doc/top_50_marketcap_coins.txt`), the first column indicates (with `*`) if it is supported in CryptoCalc.
- Note 1: `BNB` support is on Binance Smart Chain (in this blockchain `BNB` is a `BEP-20` token, see 6.3.4).
- Note 2: it's `LUNA 2.O` (on Terra blockchain) not `LUNA Classic`.
- Note 3: `SUI` support was validated with 'Suiet' (Sui wallet), a Chrome extension.

### 2.20. Languages: 18 supported languages

- Officially supported in `Bip39`:
  English, French, Spanish, Italian, Czech, Portuguese, Simplified Chinese, Traditional Chinese, Japanese and Korean.
  Notice that English is the only supported language by electronic cold wallets (eg. Ledger or Trezor).
- Non official languages:
  Deutsch, Russian, Esperanto, Latin, Greek, Hindi, Gujarati and Bengali.

Notice that English has around 1.5 billion speakers, Mandarin has around 1.1 billion speakers while the India triad (Hindi, Bengali and Gujarati) has around 1 billion speakers.

### 2.21. Developed with `Javascript` and ElectronJS

CryptoCalc is written in `Javascript` (both client side and server side) and is built on top of ElectronJS. ElectronJS is used in many modern and popular Desktop applications (e.g. Visual Studio Code, Discord, WhatsApp, Notion, Obsidian, etc.).

## 3. Setup

### 3.1. Fast and Furious (advised for end users)

- 3.1.1. Download CryptoCalc installer from SourceForge (NB: the installer was generated with electron packager and Inno Setup). Notice that the installer is not signed so Windows Defender Smartscreen will require that you validate yourself the application source. If you don't trust the installer (because it is not signed as this is a 350$ cost per year), you can either:
  - 3.1.1.a. Rebuild yourself the Installer by downloading `Inno Setup` and following the Howto provided in the `_inno_setup` subfolder (`Howto build cryptocalc_setup.txt`).
  - 3.1.1.b. Else you can proceed to Wizard's Lair setup (see 3.2).
- 3.1.2. Default setup folder is `C:\Users\$CURRENT_USER\AppData\Local\Programs\Cryptocalc`.
- 3.1.3. Default subfolder where Wallet informations are saved: `$DEFAULT_SETUP_FOLDER\resources\app\_output`.

### 3.2. Wizard's Lair (more advised for custom local setup and/or geeks or software developers)

#### 3.2.a. On `Windows` Operating system

- Prerequisites
  - Install NodeJS.
  - Install Git.
- Open a command line interpreter
  - Use Windows Menu Start then input `cmd`.
  - Change current disk to where you plan to install (eg. if its `D` then type `D:`).
  - Change current directory to where you to install (eg. `md tools` then `cd tools`).
- Import CryptoCalc from github
  - Open the GitHub CryptoCalc repository.
  - Use the [<> Code v] green button.
  - Copy the displayed .git URL.
  - In the command line interpreter, type `git clone` followed by the `.git` URL: `git clone https://github.com/ALADAS-org/cryptocalc.git`.
  - Type `cd cryptocalc`.
  - Type `npm install`.
  - You can launch CryptoCalc with a double click on `_run_Cryptocalc_W.bat` (`W` means Windows).

#### 3.2.b. On `Linux` Operating system

- Linux distribution
  - CryptoCalc was tested on Linux Mint 22.2 and tested as a virtual machine within VirtualBox. Notice that the Cinnamon desktop was chosen.
- Open a command shell
  - This will open a window where you can input commands (eg. `sudo apt-get install nodejs`).
  - Create a subdirectory to use it as a workspace, I suggest that you name it `dev`: `mkdir dev`.
  - Change current directory to this new subdirectory: `cd dev`.
  - Create a subdirectory for Github projects, I suggest that you name it `github`: `mkdir github`.
  - Change current directory to this new subdirectory: `cd github`.
- Prerequisites
  - Install NodeJS: `sudo apt-get install nodejs`.
  - Install Git: `sudo apt update; sudo apt install git`.
  - Install npm: `sudo apt update; sudo apt install npm`.
  - Install `xdg-utils` (X Desktop Group): `sudo apt-get install xdg-utils`.
- Import CryptoCalc from Github
  - `cd; cd dev/github`.
  - `git clone https://github.com/ALADAS-org/Cryptocalc.git`.
  - `cd Cryptocalc`.
  - `npm install`.
  - `chmod 777 ./_run_Cryptocalc_X.sh`.
  - You can launch CryptoCalc with either:
    - `npm start`.
    - `./_run_Cryptocalc_X.sh` (`X` is a reference to LinuX and the family of uniX like Operating Systems).

## 4. Release notes

- `0.5.10`: This version
  - Help Enhancement: the `Help menu` provides now an HTML version of `README.md` and a documentation of test protocols.
  - Updates in Unit tests running on Jest: Updates in `Unit tests`: 694 tests.
  - Added "e2e" tests (Real user scenario testing) running on Playwright: Two "e2e" tests added.
- `0.5.9`:
  - Enhancement in Unit tests: Updates in `Unit tests`: 344 tests (`Simple Wallet`, `HD Wallet`, `Bip32_utils`, `Bip39_utils`, `Bip38_utils`) passed.
- `0.5.8`:
  - Enhancement in Unit tests: Updates in `Unit tests`: 291 tests (`Simple Wallet`, `HD Wallet`, `Bip32_utils`, `Bip39_utils`) passed.
- `0.5.7`:
  - Enhancement in Unit tests: Updates in `Unit tests`: 177 tests (`Simple Wallet`, `HD Wallet` and `BI32`) passed.
- `0.5.6`:
  - Enhancement in Unit tests: Updates in `Unit tests`: 142 tests ("Simple Wallet" and "HD Wallet") passed.
- `0.5.5`:
  - Enhancement in Unit tests: Updates in `Unit tests`: use `npm test` to run the unit tests (to open a CLI console, double click on `_open_cmd_window.bat`).
- `0.5.4`:
  - New Feature: Added `Unit tests` (these tests use Jest unit test framework), it is an ongoing work (ATM only a test for `Simple Wallet`).
- `0.5.1`:
  - Terminology Fix: Terminology `Bip32 passphrase` is the wrong terminology, it has been replaced by `Bip39 passphrase`.
  - New Feature: Added support of `Bip84` purpose in the `Bip32 derivation path` (HD Wallet). Notice that it is usable only with `Bitcoin` and `Litecoin`.
  - Ergonomy Fix: Previously: When you wanted to define a `Bip39 passphrase`, you had to explicitly use the [Apply] button to recompute the Bip32 Hierarchy. Thus the [Apply] button was often overlooked and the `Bip39 passphrase` was not taken into account. This situation can be qualified as an `Ergonomy Bug`. Now: With the `Ergonomy fix`, the `Bip39 passphrase` is a `readonly` field so to enter a value you must use the [Edit] button (a button with a 'Pen' icon) then you either use [Apply] (to explicitly ask "Use the Bip39 passphrase and recompute the Bip32 Hierarchy") or [Cancel] (to explicitly ask "Don't Change the Bip39 passphrase").
  - Small Ergonomy upgrade: The [Clear] button (for the input of `Bip39 passphrase` or `Bip38 passphrase`) is now an icon (a 'Cross' shape).
  - Documentation: There is now only the most straightforward way to explore the `SQLite Database` which is with DBeaver.
- `0.5.0`:
  - New Feature: `Tools/Database Management`: A SQLite Database is populated by importing the `.wits` files (in `_output` generated subfolder). Then the Database can be explored by Adminer (a PHP application, successor of phpMyAdmin). The `Http server/SQLite/PHP` stack is supported by phpdesktop. See `document _00_README_PhPDesktop-AdMiner-SQLite.txt` (in `www\js\_main\db\Howto AdMiner`) for the setup guide. Note: you can also use DBeaver, which provides much more features like the visualization of the DB Schema.
  - Bug Fixes: `.wits` files (in `_output` generated subfolder) were missing fields of `wallet_info.txt`: namely `Bip38 Encrypted PK` and `Derivation Path`. Event Handlers were added multiple times in Dialog Boxes. Now fixed in `Tools/Bip38 Encrypt/Decrypt`, `Tools/Bip38 Secret phrase Translator` and the more recent `Tools/Database Management`. Updated `SUI` required module (`@mysten/sui` instead of `@mysten/sui.js`).
- `0.4.25`:
  - Enhancement: in `Tools/Secret phrase Translator`: a special language (`Word Indexes`) is now provided to get the indexes of the words in the Secret phrase (they are independent from the language).
  - Bug Fix: When you provide a Bip32 passphrase, `File/Save As...` was not disabled (it should be disabled until you use the [Apply] button to recompute the wallet addresses in the Bip32 hierarchy).
- `0.4.24`:
  - Bug Fix: in `Tools/Bip38 Encrypt/Decrypt`: the `Encrypt/Decrypt` state value was not get/set properly.
- `0.4.23`:
  - A dedicated tool in `Tools/Secret phrase Translator` eases importation of a generated wallet in a Wallet Manager. Use case: You can use a Secret phrase in a non `Bip39` official language (eg. `Russian`) and translate it to its equivalent in `English` which allows to import the generated wallet in a Wallet Manager (because Wallet Managers support only English).
  - Changes in Tools/Bip38 Encrypt/Decrypt dialog: Progress bar is now displayed again (when pushing [Compute] button). Length of Dialog window is shorter.
  - Changes in Passphrase strength (`Bip39/Bip38`): Adjectives changed to Very Weak, Weak, Good, Strong, Very Strong. Minimum bar length is now 5% (for a score of 0 / Very Weak).
- `0.4.22`:
  - Enhancement: `Strength` evaluation of `Bip39/Bip38 Passphrase` (see 5.1.7) was not enough reliable, because it was a computation of Entropy (in bits) and not taking into account the guessable cases (eg. `aaaaaa`, `123456789`, frequently used words used in passwords and even usage of Leetspeak). It has been replaced by `zxcvbn`, a popular and much more reliable solution (it is provided by DropBox).
- `0.4.21`:
  - Bug Fix: `Bip39` and `Bip38` changing to same color when `passphrase strength` is different.
  - Documentation Fix: Update see in 5.1.7 because this sub feature was not documented: When hovering on `strength adjective`, the strength (in bits) is displayed in an info bubble.
- `0.4.20`:
  - New Feature: `Passphrase Strength` for `Bip39/Bip38` (see 5.1.7).
  - Bug Fix: it was possible to input a 9 digits value in `account` and `address index` fields, which was a range of 1 billion (`10^9`) possible values for each field. Now the range is 1.000.000 ([0..999999]).
  - Documentation Fix: in 5.1.4.b. number of possible values for `account` and `address index` is now 1 million ([0..999999]).
- `0.4.10`:
  - Ergonomy: A Progress Bar is also displayed when saving a wallet with a `BIP38 Passphrase`. This is also to give a feedback to the user why it takes more time.
  - Documentation Fixes: Changes in 'BIP38' instructions (see 5.1.5). Instructions to install and run on `Linux`.
  - Icon Fix: Mirror on `Cryptocalc_ico.ico`.
  - Refactoring: `html_components` (folder for Html modules like MenuBar, ToolBar, StatusBar and Dialog boxes) renamed to `vizjets`. `js/renderer/const_renderer.js` moved to `js/view/const_gui.js`.
- `0.4.7`:
  - Bug Fix: regression in `Bip38` feature (since implementation of 'Progress Bar' as a feedback for encrypt/decrypt time). Update of Cryptocalc installer on SourceForge.
- `0.4.6`:
  - Update of Cryptocalc installer on SourceForge.
- `0.4.5`:
  - Updates of images: Update of screenshots. Logo images mirrored to be like a `Z` because it is the new version. This new version of the logo is also published on the SourceForge installer.
- `0.4.4`:
  - Enhancements in `Bip38` feature: Default difficulty set to 16384 (the recommended default). A Progress bar now shows a better feedback on the time needed to encrypt / decrypt.
- `0.4.0`:
  - Minor Version number changed to `4` to reflect the fact that `Bip38` support is a taller "step forward". Documentation Fixes: in this document (`README.md`).
- `0.3.65`:
  - New Feature: Support of `BIP38` (passphrase encrypted private key, see 6.3.5) for an additional security layer by Encrypting the Private Key. NB: Please notice that only the first encryption method ('NON-EC') is supported (see also 5.2.2).
  - Bug Fixes: `Save` command (in Main menu and Main Toolbar) is disabled while it should be enabled. This was identified in some use cases with `File/New` followed by `File/Open`.
  - Documentation Fixes: Update, fixes and some rewrites of this document (`README.md`).
  - Refactoring: In `html_utils.js`: `Node` replaced by `Element` in all functions because it is a better terminology for HTML entities (eg. `INPUT`,'TEXTAREA', etc...). Move of Model related code to `www/js/model` and View related code to `www/js/view` (cf. `MVC` Design Pattern) also as `MVC` may be recursive, `wallet_info.js` (which is a is Model) has been moved to `www/js/view/model`.
  - Usability: `password` (Bip32 / HD Wallet mode) replaced by `Passphrase` because it is a better terminology. In `wallet_info.txt`: `WIF` always provided. Order of "fields" is now predefined (see `js/model/wallet_inf_tmpl.js`). Changed Label for `Help/About...` dialog to a more consistent text ("A cryptocurrency wallet generator").
- `0.3.63`:
  - Fixed bug found on `Linux`: when saving, the [Show] button does nothing. Fixed a Bug found when testing the [Show] button because the output folder is showed not the latest wallet subfolder. Note that on `Linux`, you must also now install `xdg-utils` (see 3.2.b).
- `0.3.62`:
  - GUI Updates: A Label Online/Offline is now at the left of the Internet connection status icon. Seed phrase renamed to Secret phrase because it seems it is the more user friendly terminology (among Mnemonics, Seed phrase, Secret, Passphrase and Secret Recovery Passphrase). Added a link (see 5.1.18) to the whitepaper of the 3D representation of a Secret phrase.

## 5. User's Guide

You can launch CryptoCalc either by first installing it with the CryptoCalc Standalone installer (see 3.1) or by using the `Wizard's Lair` path (see 3.2): install `NodeJs`, `git` then install the CryptoCalc project and launch it with a double click on `_run_Cryptocalc_W.bat` (`W` means Windows) or `_run_Cryptocalc_X.sh` (`X` means Linux).

### 5.1. Features

#### 5.1.1. Cryptocalc Standalone installer

- 5.1.1.a: Download CryptoCalc installer.
- 5.1.1.b. Default subfolder where Wallet informations are saved: `$DEFAULT_SETUP_FOLDER\resources\app\_output`: Notice that this folder won't be automatically deleted if you uninstall CryptoCalc.

#### 5.1.2. Generate Entropy from Entropy Source

Use [Generate] button to draw a random image (cf. 5.1.3) which then will be used as the Entropy (with the Salt) to generate a new Secret phrase (between 12 and 24 words) which is derived to get the Private Key from which the Wallet Address is obtained (NB: Private Key and Wallet Address are in the Wallet Tab). There is also a conversion to the Shortened secret phrase: as only the 4 first characters of each mnemonic are meaningful (cf. `BIP39` specification) then in the Shortened secret phrase each mnemonic is represented only by its 4 first characters (with the first character in Uppercase as a mean to separate mnemonics). NB: As some mnemonics are only 3 characters long, the abbreviation will of course only be whole mnemonic. Here is an example below:

Secret phrase
rent expand super sea summer pull catalog mobile proud solve oven goose
Shortened secret phrase
RentExpaSupeSeaSummPullCataMobiProuSolvOvenGoos
NB: Please notice that the Shortened Secret phrase is not meant to be used to import a wallet in a Wallet Manager, it's only a trick to compress the Secret phrase and make it easier to store on a device with limited memory like a `NTAG213 NFC` (see 5.2.3).

#### 5.1.3. Entropy Source : `D6 Dices`, `Mouse moves`, `Image` or `Fortunes`

- `D6 Dices`: default source, the number of rolls depends on Entropy size (e.g. 100 rolls for 256 bits).
- `Mouse moves`: entropy bytes are generated when the user moves the mouse pointer.
- `Images`: You can Drag'n'Drop images (`png`, `jpg` or `svg`) from your local folders. Image samples are provided in `www/img` folder. When using [Generate], Cryptocurrency logos are drawn from `www/img/CryptoCurrency`.
- `Fortunes`: Fortune cookies are drawn from a compilation of 12803 quotes.

#### 5.1.4. Choose Wallet Mode: Simple Wallet, HD Wallet or SWORD Wallet (choice is in the `Wallet` tab page)

- 5.1.4.a. Simple Wallet
  This is the default Wallet Mode. In this mode, each wallet is separated. (no need to understand the principles of the HD Wallet Wallet Tree and the purpose of the `Derivation Path` used by HD Wallets). So it's a good fit to Give it a Try and start creating your Cryptocurrency Wallets with minimum knowledge. On the other hand it's less secure than HD Wallets (especially if you use low security entropy text like your firstname, city/birth year etc.... Indeed it will be vulnerable to dictionary attacks) and it becomes clumsy if you need to split your assets between many wallets.
- 5.1.4.b. HD Wallet
  This Wallet Mode allows to create / manage a whole hierarchy of Wallets (HD is the acronym for Hierarchical Deterministic) in the same BIP32 tree.

  > Please notice that the `Derivation Path` is now `Hardened` by default and mandatory (since `0.3.18`). This is for Security purpose (see 5.2.3).

  The `BIP32` HD wallet tree is fully determined by the Entropy (or Secret phrase which is equivalent) and an optional Password. The Entropy may be represented by a more human friendly representation: the Mnemonics Sequence which may also be called a Secret phrase, Mnemonics, Seed phrase, Secret or even SRP (Secret Recovery Passphrase).

  > How to Generate a new wallet with a given Entropy:
  > Paste a new Entropy (or Secret phrase) in the `Entropy` wallet tab. Notice that this will hide the Entropy Source and Salt fields (meaningless in this situation).
  > You can then change either the Account or Address Index fields (the maximum number of digits is 6 so you can input a decimal value between 0 and 999999, 1.000.000 possible values for each field) in the Wallet tab page. This will show a [Refresh] button to recompute the wallet once you have finished.
  > Pushing the [Refresh] button (or hitting either [Return] or [Enter] keys while the cursor is in either Account or Address Index field) will recompute the wallet address (and Private key or WIF) accordingly.

- 5.1.4.c. SWORD Wallet
  `SWORD` is an acronym which means `Simple Wallet Over Randomized Deterministic`, it's a hybrid between `Simple Wallet` and `HD Wallet` because it hides the `Derivation Path` logic (which contains `Account` and `Address Index`), thus you don't need to care or understand the principles of Hierarchical Deterministic wallets, but it allows to generate all the cryptocurrencies provided by `HD Wallet`.
- 5.1.4.d. Please notice that for `Cardano` HD wallets, the `Account` and `Address Index` parameters are not taken into account by the Wallet Managers which I have tested (namely `Guarda` and `Yoroi`) because they ask for the `Mnemonics` (`Secret phrase` in CryptoCalc). This is why in CryptoCalc, these parameters are hard-coded to Zero (for `Cardano` HD wallets only).
- 5.1.4.e. You can check generated HD Wallets with Ian Coleman BIP39 homepage. Its URL is provided as an item in the `Help menu` (`Help/Resources/Ian Coleman BIP39`).

#### 5.1.5. 'BIP38' Encryption of the Private Key

- `BIP38` (passphrase encrypted private key, see 6.3.5) is supported for an added security layer by Encrypting the Private Key.
- How to: just input a value in `Bip38 passphrase` field then use the [Save] button (or `File/Save` menu item, cf 5.1.12). This generates a `Bip38 Encrypted PK`.
- Note 1: Notice that only the first method ('NON-EC': encrypt the private Key with the passphrase) is supported.
- Note 2: Notice that the level of security is proportional to the length and complexity (diversity of characters like [A..Z][a..z][0..9] and special characters) of the `passphrase` (like with a password).
- Note 3: A new QR code is generated (`Bip38 Encrypted PK`) as both a `PNG` file and an `SVG` file (in `xtras` subfolder of the generated wallet folder under `_output`).
- Note 4: The Private Key is still provided (both in `wallet_info.txt` and as a QR code), but notice it is your responsibility to not disclose the Private Key (the `Bip38 Encrypted PK` may be disclosed in some use cases cf. 5.3.2).
- Note 5: A new Tool (in Main menu : `Tool/Bip38 Encrypt/Decrypt`) is provided to decrypt the Private Key from the Bip38 Encrypted PK (or conversely encrypt the Private Key to the Bip38 Encrypted PK).

#### 5.1.6. Bip39 Passphrase feature (HD Wallet only)

The `Bip39 passphrase` is like an optional `password`. If you decide to define it, then it will generate a completely different `Bip32 hierarchy` (HD Wallet). The ergonomy has been fixed so now to input a `Bip39 passphrase` you must use the [Edit] button (a 'Pen' shape) and use the [Apply] button in order to recompute the `Bip32 Hierarchy` (which is parameterized by the `Bip39 passphrase`).

Note 1: Notice that you can still use the [Generate] button (a 'Circular arrow' icon) to generate the `Bip39 passphrase` and the [Clear] button (a 'Cross' shape) but they are now in the Bip39 passphrase Input Dialog Box.

Note 2: You can check that the computed `Wallet address` and `Private Key` (or `WIF`) are correct by using Ian Coleman Bip39, just take care to provide `Entropy` then provide the `BIP39 Passphrase (optional)` (as well as `Account` and `Address Index` if different from 0) then don't forget to check `Use hardened addresses`.

#### 5.1.7. Passphrase Strength (`Bip39/Bip38`)

This is a visual feedback of the `Passphrase Strength` (`Bip39/Bip38`). The measure of the passphrase's strength is a score (an integer between 0 and 4) computed with the help of `zxcvbn` library. This score is displayed as a colored line (whose length is proportional to the score) as well as an adjective (i.e: Weak, Moderate, Strong, etc..).

- 0 `Very Weak` (Red)
- 1 `Weak` (Orange)
- 2 `Fair` (Yellow)
- 3 `Good` (Green)
- 4 `Strong` (Violet)

NB: It is strongly advised to use the [Random] button (a circular arrow icon) because it would probably be much less predictable (and thus more secure) than a Passphrase that you provide because (even unconsciously) there is a higher probability that it will be predictable (even with Tricks like Acronyms, Abbreviations and even usage of `L33+5p34|<`).

#### 5.1.8. Salted Entropy

Entropy is generated from Entropy Source then a Salt (a generated `UUID` currently, this is 128 bits of Entropy) is added to provide the `Salted Entropy`. This is a way to make sure the Entropy is unique at each Generation even if the Entropy Source value is the same (e.g. reusing the same Image or Fortune cookie). Thus the Entropy value will be unique at each press of [Generate] button.

#### 5.1.9. Choose Entropy Size

The Entropy Size is between 128 to 256 bits (32 to 64 hexadecimal digits). This is equivalent to the size of the Secret phrase (between 12 and 24 words). Changing Entropy Size impacts the size of the Secret phrase and conversely.

#### 5.1.10. Wallet Address

Wallet Address is displayed in the `Wallet` tab page. There's also an [Explorer...] button which allows to check the generated address in the appropriate Blockchain Explorer.

#### 5.1.11. Internet Connection Status

This is to secure Offline wallet creation (non custodial). An icon at the right of the Main Toolbar shows if the Internet is connected (`Wifi ON` red icon) or not connected (`Wifi OFF` green icon).

#### 5.1.12. `Save` Wallet Informations

With `File/Save` (or the Save icon in the main toolbar), you can save the Wallet Informations in a timestamped subfolder (eg. `2024_10_07_21h-4m-4s-3_BTC_EN`) under `_output` folder. This subfolder contains `wallet_info.txt` and a `wallet.json` with the informations displayed in Entropy and Wallet tab pages.

- 5.1.12.a. When you save the current generated wallet a Popup dialog confirms the saving and allows to show where it is saved.
- 5.1.12.b. The Wallet Informations subfolder contains QR Codes (`png` images) for `Address`, `Private Key`, `Secret phrase`, `Entropy` and `WIF` (if applicable). Notice that there is a `xtras` subfolder where these QR codes are provided in the `svg` format. There is also a Rectangular Micro QR code (`rMQR`) of the `Entropy` (Rectangular Micro QR Code, `R15x59` or `R15x77` version depending on `Entropy size`) and an experimental `Ultracode` color QR code of the `Entropy`.
- 5.1.12.c: How to retrieve a Wallet Address from the Rectangular Micro QR Code
  - 5.1.12.c.I: Notice that most Android QR Code reader apps will not be compatible with Rectangular Micro QR Code but it works with `QRQR`, an Android QR Code reader published by Arara on the Google Play Store.
  - 5.1.12.c.II: Then convert the Entropy to the matching Secret phrase by doing a copy/paste in the `Entropy` field of CryptoCalc. Caution: Take care to set CryptoCalc with the same `Entropy Size` and `Derivation path` (if applicable, don't forget to use the [Refresh] button) than those used when the wallet was created (these informations are provided either in the `wallet_info.txt` or in `wallet_info.wits`).

#### 5.1.13. `Open` Wallet Informations of a previously saved wallet

- 5.1.13.a. Wallet informations are saved both as a `.txt` but also as a `.wits` file (`JSON` format).
- 5.1.13.b. A `.wits` file can be opened either with `File.Open...` menu item or 'Open...' icon in the toolbar. It can be also be opened in `Cryptocalc.exe` by double clicking on the `.wits` (File extension to Application feature): this will launch `Cryptocalc.exe` (cf. 3.1 for installing `Cryptocalc.exe` with the CryptoCalc Standalone installer).
- 5.1.13.c. Once opened, a wallet can't be saved on itself (it is to prevent accidental overwrite of the original wallet), but you can use `File.Save As...` which will save the wallet with a different timestamp than the original one.
- 5.1.13.d. Notice that for a HD Wallet you can change the `Account` and/or the `Address Index` (don't forget to push the [Refresh] button). Now you can save the new wallet with `File.Save As...` and if you didn't change the `Entropy` then this new wallet will belong to the same `Bip32 HD Wallet Tree` (see A.2) as the original one.

#### 5.1.14. Import a wallet in Guarda

An item in the menu (Help / Resources / Guarda) eases importing a wallet in a Wallet Manager application.

- Notes on `Guarda`
  - It is a Non custodial wallet because the Private Keys are stored on your local computer so keep in mind that you are responsible to take care and make backups by yourself (eg. if you reinstall the Operating system without having made a security backup then your Private Keys and then your assets will be lost).
  - It is a Hot wallet because it is also a web service which allows to send funds to another wallet and also to change a cryptocurrency in another (eg ETH to SOL).
  - `Guarda` was chosen mainly to validate that a generated wallet by CryptoCalc is accepted and thus validated.

#### 5.1.15. Select Secret phrase Language

You can select the Wordlist Language (eg. English, French, Deutsch, etc...). Please notice that only English is accepted for most Wallet Manager applications. Changing Wordlist Language is indeed a mean to add an "obfuscation/information hiding" step in order to make it harder to steal your Secret Recovery Passphrase because it should be translated to English to be used with a Wallet Manager. NB: it is important to highlight that indeed the crucial information is the list of Word Indexes. That's why translation between languages is easy in CryptoCalc because the reference is the Word Indexes (see 6.1.14) not the words.

#### 5.1.16. Display of Word Indexes

The Word Indexes are between 0 and 2047, it is the index of each of the Secret phrase words in the `BIP39` wordlist (see also 6.1.1). You can choose to display these indexes in Decimal or Binary (in Binary you can check that the computed Checksum bits are added at the end of the converted Entropy to determine the index of the last word).

#### 5.1.17. Display of the BIP32 Derivation Path

The BIP32 Derivation Path is displayed in the Wallet tab page. You can edit the Account or Address Index fields to generate new wallets which belong to the same `BIP32` hierarchy that is determined by the Secret phrase (also called the Secret Recovery Passphrase).

#### 5.1.18. Secret phrase Translator

- This dedicated tool (`Tools/Secret phrase Translator`) is meant to import a generated wallet in a Wallet Manager. Usage: Paste a Secret phrase, choose an output language (with the `Output` dropdown list) then use [Translate] button (the Green arrow button) to get the translated Secret phrase.
- Use case: You can use a Secret phrase in a non `Bip39` official language (eg. `Russian`) and translate it to its equivalent in `English` (because Wallet Managers support only English).
- Note 1: A special language (`Word Indexes`) is provided to get the indexes of the words in the Secret phrase (they are independent from the language).
- Note 2: Once a first translation has been performed, you can change the Output language and translate at the same time by selecting the new Output language in the `Output` dropdown list.

#### 5.1.19. Wallets Database

A SQLite Database is populated by importing `.wits` files (Wallet informations in a `JSON` format file). Then the SQLite Database can be explored with DBeaver.

#### 5.1.20. Dynamic Links

- Address wallet in the appropriate `Blockchain Explorer` (e.g. blockchain.com).
- Informations in `Coinmarketcap.com` for the wallet's cryptocurrency.
- 3D representation of the `Secret phrase` (Cryptoshape). The description of this 3D representation is in this whitepaper.

#### 5.1.21. Change/Reset of Options (`Tools/Options`)

Currently it allows to set default values for `Default Blockchain`, `Wallet Mode` and `Entropy Size`. These values are defined in `www/config/options.json` file. It is also possible to reset Options to Default Options (defined in `www/config/defaults/options.json`).

#### 5.1.22. Localization

Localization (`l10n`) feature is the translation of GUI Labels to adapt to the user's language, it's called the locale (eg. `en`). A locale name can be composed of a base language, country (territory) of use and optionally a codeset (eg. `de_CH.UTF-8`). The locale is provided as part of your machine's environment. CryptoCalc only uses the 2 letter language part (eg. `en`). Localization is enabled by a `JSON` file in the `www/js/L10n` folder (eg. `gui-msg-en.json`). Notice that currently only `en` and `fr` are provided.

### 5.2. Security Issues

- Notice that you should never disclose the Private Key.
- NB: In the case of Bip38 Encryption, you may share the Bip38 Encrypted PK but never neither the Private Key nor the Bip38 Passphrase.

### 5.3. Unit Tests

- Unit tests is an ongoing work (since 0.5.4) it uses Jest unit test framework.
- How to run the tests: double click on `_open_cmd_window.bat` then input `npm test`.
- Status: 694 unit tests covering:
  - "Simple Wallet" (`www/js/crypto/SimpleWallet/simple_wallet.js`)
  - "HD Wallet" (`www/js/crypto/HDWallet/hd_wallet.js`)
  - And other utility modules.
- The code for unitary tests for Jest is in `tests/jest/unit/wallet`.

### 5.4. Use cases

- 5.4.1. Generate a new Wallet and import it in a Wallet manager
  With a Wallet Manager like `Guarda` you can import a wallet generated by CryptoCalc:
  - Choose Wallet Mode: Simple Wallet, HD Wallet or SWORD.
  - Choose a coin: `BTC`, `ETH`, `XRP`, `ADA`, `DOGE`, `LTC`, `SOL`, `AVAX`, `TRX`, `BCH`, `DASH`, `FIRO`.
  - Enter Private Key (NB: or WIF for `BTC` wallets).
- 5.4.2. `BIP38` Encryption of the Private Key
  The first method (NON-EC) of `BIP38` adds a security layer by encrypting the Private Key with a Passphrase. The Bip38 Encrypted Private Key allows to subcontract the printing of a Paper Wallet with premium features (eg. Watermark, Embossing, Hologram, Custom Credit card, etc..) without disclosing the Private Key to the subcontractor (and providing the Passphrase to your customer via a different channel than the delivery of the Printed paper wallet).
- 5.4.3. Store Shortened Secret phrase in a NFC SmartRing
  The entry level SmartRings (price range: 7..15$) contains a `NTAG213 NFC` with 144 bytes usable capacity. This is enough to store the Shortened Secret phrase, with a 24 words Shortened Secret phrase the maximum required capacity is 96 bytes/characters (24*4, cf. 5.1.2) or even less (as some mnemonics have only three characters).
- 5.4.4. Store Master password
  This is similar to the previous case, but the Shortened Secret phrase can be used as a Master password for a Password Manager or for tools like PGP Tool which provides encryption/decryption of your documents.

## 6. Appendix

### 6.1. `BIP39`: a Dictionary of 2048 words

`BIP39` (`BIP` is the acronym for Bitcoin Improvement Proposal) is a specification regarding:

- 6.1.1. A Dictionary of 2048 mnemonics
  The Dictionary (also called a wordlist) contains 2048 English mnemonics (words) each with their unique 4 starting characters (or 3 if the mnemonic is 3 characters long). This dictionary exists also in other languages (e.g. French, Deutsch, Spanish, Italian, Portuguese, etc...) but Wallet Managers (e.g. Guarda, Metamask, Atomic Wallet, etc...) and Hardware Wallets (eg. Ledger, Trezor, Tangem, etc...) will only accept English words.
- 6.1.2. Conversion of Secret phrase from and to Entropy
  The Secret phrase is obtained by drawing words (also called mnemonics) from the dictionary. Drawing a word is indeed choosing an index between 0 and 2047. This index can be represented by 11 bits in Binary (because 2^11 = 2048).
  - Conversion from Entropy to Secret phrase: The Entropy is represented in Binary and divided in 11 bits segments but the entropy is a multiple of 8 bits (128, 160, 192, 224, 256) there are "missing bits" for choosing the last word. These "missing bits" are provided by computing the Entropy Checksum. e.g. For an Entropy Size of 128 bits (converted to a 12 words Secret phrase), 132 bits are needed (11 * 12), so the Entropy Checksum provides the missing 4 bits.
  - Conversion from Secret phrase to Entropy: For each word its index is retrieved from the Dictionary, its value is represented as a 11 bits segment and a number of bits corresponding to the Entropy Checksum are removed at the end of the concatenation of 11 bits segments. e.g. For a Secret phrase of 12 words (converted to a 128 bits Entropy), 132 bits are obtained from the Word Indexes (11 * 12), and because the Entropy Checksum is 4 bits long (in the case of a 128 bits Entropy) then the 4 bits at the end are removed.
- Reference: BIP39 — Mnemonic Generation with detailed explanation

### 6.2. `BIP32`: Hierarchic Deterministic wallets

`BIP32` specifies how to generate wallets which are all derived from the same Entropy or Secret phrase (also called the Secret Recovery Passphrase). A Secret phrase of only 12 words is enough in most Wallet Managers but it is much more secure to use a 24 words Secret phrase if possible (e.g. Ledger hardware wallet manager).

Example: meaning of each part for `m/44'/60'/0'/0/0'` (a Hardened Derivation Path):

- Start at the master key (m)
- Follow the `BIP44` specification (44')
- Derive the key for Ethereum (for which Coin type is 60) (60')
- Access the first account (0')
- Choose the external chain, used for public addresses (0)
- And finally, generate the first address in this sequence (0')

### 6.3. References

- 6.3.1. Understanding Derivation Paths in Cryptocurrency: Easy-To-Follow Guide
- 6.3.2. Hierarchical key generation
- 6.3.3. BIP32 Key Derivation with HD Wallets
- 6.3.4. The evolution of the Binance Smart Chain
- 6.3.5. BIP38: Passphrase-protected private key