wownero-seed/README.md

109 lines
4.5 KiB
Markdown
Raw Permalink Normal View History

2020-06-13 19:00:39 +00:00
## Build
```
2022-05-20 15:25:47 +00:00
git clone https://git.wownero.com/wowlet/wownero-seed.git
cd wownero-seed
2020-06-13 20:15:03 +00:00
mkdir build && cd build
2020-06-13 19:00:39 +00:00
cmake ..
make
```
2020-06-15 20:26:29 +00:00
## Features
* embedded wallet birthday to optimize restoring from the seed (only blocks after the wallet birthday have to be scanned for transactions)
* 5 bits reserved for future updates
2020-06-15 20:26:29 +00:00
* advanced checksum based on Reed-Solomon linear code, which allows certain types of errors to be detected without false positives and provides limited error correction capability
* built-in way to make seeds incompatible between different coins, e.g. a seed for Aeon cannot be accidentally used to restore a Monero wallet
2020-06-13 19:00:39 +00:00
## Usage
### Create a new seed
```
2022-05-20 15:25:47 +00:00
> ./wownero-seed --create [--date <yyyy-MM-dd>] [--coin <monero|aeon>]
2020-06-15 20:26:29 +00:00
```
Example:
```
2022-05-20 15:25:47 +00:00
> ./wownero-seed --create --date 2100/03/14 --coin monero
2020-06-15 20:26:29 +00:00
Mnemonic phrase: test park taste security oxygen decorate essence ridge ship fish vehicle dream fluid pattern
2022-05-20 15:25:47 +00:00
- coin: wownero
2020-06-15 20:26:29 +00:00
- private key: 7b816d8134e29393b0333eed4b6ed6edf97c156ad139055a706a6fb9599dcf8c
2020-06-13 19:00:39 +00:00
- created on or after: 02/Mar/2100
```
### Restore seed
2020-06-15 20:26:29 +00:00
```
2022-05-20 15:25:47 +00:00
./wownero-seed --restore "<14-word seed>" [--coin <monero|aeon>]
2020-06-15 20:26:29 +00:00
```
Example:
2020-06-13 19:00:39 +00:00
```
2022-05-20 15:25:47 +00:00
> ./wownero-seed --restore "test park taste security oxygen decorate essence ridge ship fish vehicle dream fluid pattern" --coin monero
- coin: wownero
2020-06-15 20:26:29 +00:00
- private key: 7b816d8134e29393b0333eed4b6ed6edf97c156ad139055a706a6fb9599dcf8c
2020-06-13 19:00:39 +00:00
- created on or after: 02/Mar/2100
```
2020-06-15 20:26:29 +00:00
Attempting to restore the same seed under a different coin will fail:
```
2022-05-20 15:25:47 +00:00
> ./wownero-seed --restore "test park taste security oxygen decorate essence ridge ship fish vehicle dream fluid pattern" --coin aeon
2020-06-15 20:26:29 +00:00
ERROR: phrase is invalid (checksum mismatch)
```
Restore has limited error correction capability, namely it can correct a single erasure (illegible word with a known location).
2020-06-13 19:00:39 +00:00
This can be tested by replacing a word with `xxxx`:
```
2022-05-20 15:25:47 +00:00
> ./wownero-seed --restore "test park xxxx security oxygen decorate essence ridge ship fish vehicle dream fluid pattern" --coin monero
2020-06-15 20:26:29 +00:00
Warning: corrected erasure: xxxx -> taste
2022-05-20 15:25:47 +00:00
- coin: wownero
2020-06-15 20:26:29 +00:00
- private key: 7b816d8134e29393b0333eed4b6ed6edf97c156ad139055a706a6fb9599dcf8c
2020-06-13 19:00:39 +00:00
- created on or after: 02/Mar/2100
```
## Implementation details
The mnemonic phrase contains 154 bits of data, which are used as follows:
* 5 bits reserved for future use
2020-06-15 20:26:29 +00:00
* 10 bits for approximate wallet birthday
2020-06-13 19:00:39 +00:00
* 128 bits for the private key seed
2020-06-15 20:26:29 +00:00
* 11 bits for checksum
2020-06-13 19:00:39 +00:00
### Wordlist
2020-06-15 20:26:29 +00:00
The mnemonic phrase uses the BIP-39 wordlist, which has 2048 words, allowing 11 bits to be stored in each word. It has some additional useful properties,
for example each word can be uniquly identified by its first 4 characters. The wordlist is available for 9 languages (this repository only uses the English list).
2020-06-13 19:00:39 +00:00
2020-06-14 19:54:15 +00:00
### Reserved bits
There are 5 reserved bits for future use. Possible use cases for the reserved bits include:
2020-06-14 19:54:15 +00:00
* a flag to differentiate between normal and "short" address format (with view key equal to the spend key)
* different KDF algorithms for generating the private key
2020-06-15 20:26:29 +00:00
* seed encrypted with a passphrase
Backwards compatibility is achieved under these two conditions:
1. Reserved (unused) bits are required to be 0. The software should return an error otherwise.
2. When defining a new feature bit, 0 should be the previous behavior.
2020-06-15 20:26:29 +00:00
### Wallet birthday
The mnemonic phrase stores the approximate date when the wallet was created. This allows the seed to be generated offline without access to the blockchain. Wallet software can easily convert a date to the corresponding block height when restoring a seed.
2020-06-15 20:26:29 +00:00
The wallet birthday has a resolution of 2629746 seconds (1/12 of the average Gregorian year). All dates between June 2020 and September 2105 can be represented.
2020-06-15 20:26:29 +00:00
### Private key seed
The private key is derived from the 128-bit seed using PBKDF2-HMAC-SHA256 with 4096 iterations.The wallet birthday and the 5 reserved/feature bits are used as a salt. 128-bit seed provides the same level of security as the elliptic curve used by Monero.
2020-06-15 20:26:29 +00:00
Future extensions may define other KDFs.
### Checksum
2020-06-13 19:00:39 +00:00
2020-06-15 20:26:29 +00:00
The mnemonic phrase can be treated as a polynomial over GF(2048), which allows us to use an efficient Reed-Solomon error correction code with one check word. All single-word errors can be detected and all single-word erasures can be corrected without false positives.
2020-06-13 19:00:39 +00:00
2020-06-15 20:26:29 +00:00
To prevent the seed from being accidentally used with a different cryptocurrency, a coin-specific value is subtracted from the first data-word after the checksum is calculated. Checksum validation will fail unless the wallet software adds the same value back to the first data-word when restoring.