@aladas-org/cryptocalc
Version:
Cryptocurrency wallet generator
621 lines (587 loc) • 49 kB
Markdown
## CryptoCalc 0.5.19
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 is 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_ informations being stolen.
NB: Since its first release _CryptoCalc_ has been downloaded 16792 times on [npm](https://www.npmjs.com/).
You can support this project by testing and reporting bugs (or asking for enhancements) with [`Issues`](https://github.com/ALADAS-org/Cryptocalc/issues)
or provide localization files (see 5.1.19).
Cryptocalc is developed by [Aladas](https://aladas.org/?page_id=61), a non profit organization whose primary goal is to protect Wild bees](https://sites.google.com/view/aladas/accueil).
2. Features
2.0. Recently added features
- Added `Entropy Converter Tool`: `Entropy Converter` is in the `Tool menu` and provides multiple conversions (among `Raw text`, `Hexadecimal`, `Base64`, `Base58`, `Bip39 mnemonics` and `Binary`)
- 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](https://jestjs.io/fr/) 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](https://playwright.dev/)
- `Wallets Database`: you can now populate a `SQLite` database byb ilporting the _Wallet informations_ (`.wits` files in timestamped subfolders under `_output` folder)
- Added support support of `Bip84` purpose in the `Bip32 derivation path`
2.1. Support of HD / Bip32 (multiple wallets)
Added support 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` (currenly 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](https://sqlite.org/)Database is populated by importing `.wits` files (_Wallet informations_ in a `JSON` format file).
Then the SQLite Database can be explored with [DBeaver](https://dbeaver.io/).
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](https://www.blockchain.com/fr/explorer))
- Informations in `Coinmarketcap.com` for the wallet's cryptocurrency
- 3D representation of the `Secret phrase` (see an example here: [Cryptoshape](https://aladas-org.github.io/aladas.github.io/))
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](https://sourceforge.net/projects/aladas-cryptocalc/)) 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](https://linuxmint.com/) (NB: tested on a virtual machine within [VirtualBox](https://www.virtualbox.org/))
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 fist column a 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 langage 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](https://www.electronjs.org/)
_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](https://en.wikipedia.org/wiki/List_of_software_using_Electron)
(e.g. [Visual Studio Code](https://code.visualstudio.com/), [Discord](https://discord.com/), [WhatsApp](https://www.whatsapp.com/),
[Notion](https://www.notion.com/), [Obsidian](https://obsidian.md/), etc..).
3. Setup
- 3.1. _Fast and Furious_ (advised for end users)
- 3.1.1. Download [CryptoCalc installer](https://sourceforge.net/projects/aladas-cryptocalc/files/latest/download)
from _SourceForge_ (NB: the installer was generated with [electron packager](https://www.npmjs.com/package/@electron/packager)
and [Inno Setup](https://jrsoftware.org/isinfo.php).
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](https://nodejs.org/en/)
- Install [Git](https://git-scm.com/)
- 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](https://github.com/ALADAS-org/cryptocalc)
- Use the [<> Code v] green button
- Copy the displayed [.git URL](https://github.com/ALADAS-org/cryptocalc.git)
- In the _command line interpreter_, type `git clone ` followed by the `.git` URL:
- e.g. `git clone https://github.com/ALADAS-org/cryptocalc.git`
- Type `cd cryptocalc`
- Type `npm install`
- You can launch _CryptoCalc_ with a double clik 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](https://linuxmint.com/)
and tested as a virtual machine within [VirtualBox](https://www.virtualbox.org/).
Notice that the _Cinnamon_ desktop was chosed.
- 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](https://github.com/) projects, I suggest that you name it `github`:
- `mkdir gihub`
- Change _current directory_ to this new _subdirectory_:
- `cd github`
- Prerequisites
- Install [NodeJS](https://nodejs.org/en/):
- `sudo apt-get install nodejs`
- Install [Git](https://git-scm.com/)
- `sudo apt update; apt install git`
- Install [npm](https://www.npmjs.com/)
- `sudo apt update; apt install npm`
- Install `xdg-utils` ([X Desktop Group](https://www.freedesktop.org/wiki/))
- `sudo apt-get install xdg-utils`
- Import _CryptoCalc_ from [Github](https://github.com/)
- `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.19`: This version
- Update of [Cryptocalc installer](https://sourceforge.net/projects/aladas-cryptocalc/) on [SourceForge](https://sourceforge.net)
- `0.5.18`
- Bug Fix (in `Entropy Converter Tool`): In the `Secret Phrase` field, you can now change any mnemonic by selecting it then move the
mouse cursor over the _checkerboard_ image and left click to validate the new mnemonic chosen at the selected position within the secret phrase.
- `0.5.17`
- Upgrade for `Raw Text` field in `Entropy Converter Tool`. This field now uses a custom `Base256U` alphabet to ensure isomorphism with other fields like `Hexadecimal`
when ine of the bytes has a value which is a non displayable code in ASCII.
- `0.5.13`
- Added `Entropy Converter Tool`: `Entropy Converter` is in the `Tool menu` and provides multiple conversions (raw text, hexadecimal, base64, base58, mnemonics and binary)
- `0.5.12`
- New Feature:
- `Tools/Private Key Converter`:
- `0.5.11`
- Ergonomy Enhancements of `Bip39 Passphrase` input field:
- Added Generate Passphrase button (a 'Circular arrow' icon)
- Added Clear button (displayed as a `X` icon)
- `0.5.10`
- 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](https://jestjs.io/fr/):
Updates in `Unit tests`: 694 tests
- Added "e2e" tests (Real user scenario testing) running on [Playwright](https://playwright.dev/):
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](https://jestjs.io/fr/) 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, iut has been replaced by `Bip39 passphrase`
- New Feature:
Added support 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 ad 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 explicity ask "Use the Bip39 passphrase and recompute the Bip32 Hierarchy") or [Cancel] (to explicity 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](https://dbeaver.io/).
- `0.5.0`
- New Feature:
- `Tools/Database Management`: A [SQLite](https://sqlite.org/) Database is populated by importing the `.wits` files
(in `_output` generated subfolder). Then the Database can be explored by [Adminer](https://www.adminer.org/en/)
(a [PHP](https://www.php.net/) application, successor of [phpMyAdmin](https://www.phpmyadmin.net/)).
The `Http server/SQLite/PHP` stack is supported by [phpdesktop](https://github.com/cztomczak/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](https://dbeaver.io/), 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 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_ in 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`](https://www.npmjs.com/package/zxcvbn),
a popular and much more reliable solution (it is provided by [_DropBox_](https://www.dropbox.com/)).
- `0.4.21`
- Bug Fix:
- `Bip39` and `Bip38` changing to same color when `pasphrase 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](https://sourceforge.net/projects/aladas-cryptocalc/) on [SourceForge](https://sourceforge.net)
- `0.4.6`
- Update of [Cryptocalc installer](https://sourceforge.net/projects/aladas-cryptocalc/) on [SourceForge](https://sourceforge.net)
- `0.4.5`
- Updates of images:
- Update of screnshots
- 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](https://sourceforge.net/projects/aladas-cryptocalc/)
- `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
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: Downloadl [CryptoCalc installer](https://sourceforge.net/projects/aladas-cryptocalc/)
- 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 pointe
- `Images`
- You can _Drag'n'Drop_ images (`png`, `jpg` or `svg`) from you 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 a 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 you firstname, city/birth year etc.... Indeed its will be vulnerable
to [_dictionary attacks_](https://en.wikipedia.org/wiki/Dictionary_attack) )
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 9 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 an 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
It's [URL](https://iancoleman.io/bip39/) 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 the 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 in as a QR code), but notice it is your responsability
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`. It 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](https://iancoleman.io/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 addressess`.
- 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`](https://www.npmjs.com/package/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
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`](https://play.google.com/store/apps/details?id=com.arara.q&hl=en)
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 launchlc `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` (dont 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) than the original one.
- 5.1.14. Import a wallet in [Guarda](https://guarda.com/)
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 you local computer so keep in mind
that you are responsible to take care and make basckups 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 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_, _Deutsh_, 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_.
Thats'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. Entropy Converter
- This dedicated tool (`Tools/Entropy Converter`) provides multiple conversions (among `Raw text`, `Hexadecimal`, `Base64`, `Base58`, `Bip39 mnemonics` and `Binary`)
Usage: you can either characters for each `Base` (eg: `Base64`) field or select a mnemonics for the `Secret Phrase` field by moving
the mouse cursor over the _checkerboard_ image (this returns an index between 0 and 2047 which is converted to a `Bip39 mnemonic` of the selected language).
Use case: if you select the _special language_ called `[..] (Word Indexes` then you will get the `Word Indexes` (instead of `Bip39 mnemonics`).
This is the _Language-independent_ encoding of the Secret Phrase.
- 5.1.20. Wallets Database
A [SQLite](https://sqlite.org/) Database is populated by importing `.wits` files (_Wallet informations_ in a `JSON` format file).
Then the SQLite Database can be explored with [DBeaver](https://dbeaver.io/)
- 5.1.21. Dynamic Links
- Address wallet in the appropriate `Blockchain Explorer` (e.g. [blockchain.com](https://www.blockchain.com/fr/explorer))
- Informations in `Coinmarketcap.com` for the wallet's cryptocurrency
- 3D representation of the `Secret phrase` ([Cryptoshape](https://aladas-org.github.io/aladas.github.io/))
The whitepaper The description of this 3D representation is in this [whitepaper](https://zenodo.org/records/14579720)
- 5.1.22. 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.23. _Localization_
_Localization_ (`l10n`) feature is the translation of _GUI Labels_ to adapt to the user's language, it' called the _locale_ (eg. `en`).
A _locale_ name can be composed of a base language, country (territory) of use and optionnally 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 it 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](https://jestjs.io/fr/) unit test framework.
- Howto run the tests: double click on `_open_cmd_window.bat` then input `npm test`
- Status: 142 unit tests covering:
- "Simple Wallet" (`www/js/crypto/SimpleWallet/simple_wallet.js`)
- "HD Wallet" (`www/js/crypto/HDWallet/hd_wallet.js`)
- 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`](https://https://guarda.com/) 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`,`AVX`,`TRON`,`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 useable 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_](https://pgptool.github.io) 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 a their unique
4 starting characters (or 3 if the mnemonic is 3 characters long). This dictionary exists also in other languages
(e.g. _French_, _Deutsh_, _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 segements 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 tne _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](https://medium.com/@sundar.sat84/bip39-mnemonic-generation-with-detailed-explanation-84abde9da4c1)
- 6.2. `BIP32`: Hierarchic Deterministic wallets
`BIP32` specifies how to generate wallets with 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 is 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](https://getcoinplate.com/blog/derivation-paths-guide/#:~:text=A%20derivation%20path%20is%20simply,a%20particular%20branch%20(address))
- 6.3.2. [Hierarchical key generation](https://alexey-shepelev.medium.com/hierarchical-key-generation-fc27560f786)
- 6.3.3. [BIP32 Key Derivation with HD Wallets](https://docs.bsvblockchain.org/guides/sdks/ts/examples/example_hd_wallets)
- 6.3.4. [The evolution of the Binance Smart Chain](https://cointelegraph.com/learn/articles/a-beginners-guide-to-the-bnb-chain-the-evolution-of-the-binance-smart-chain)
- 6.3.5. [BIP38: Passphrase-protected private key](https://github.com/bitcoin/bips/blob/master/bip-0038.mediawiki)