diff --git a/.gitignore b/.gitignore index 5bd6d22..95f43b3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,6 @@ .idea *.iml public - +.monero-docs-venv +.cache +__pycache__ diff --git a/docs/en/cryptography/asymmetric/introduction.md b/docs/en/cryptography/asymmetric/introduction.md index 9d0bbef..2d94b21 100644 --- a/docs/en/cryptography/asymmetric/introduction.md +++ b/docs/en/cryptography/asymmetric/introduction.md @@ -1,5 +1,5 @@ --- -title: Asymmetric Cryptography in Moner +title: Asymmetric Cryptography in Monero --- # Asymmetric Cryptography in Monero diff --git a/docs/en/mnemonics/index.md b/docs/en/mnemonics/index.md new file mode 100644 index 0000000..25d2392 --- /dev/null +++ b/docs/en/mnemonics/index.md @@ -0,0 +1,11 @@ +--- +title: Mnemonics in Monero +--- +# Mnemonics in Monero + +Mnemonics are a way to represent a private key in a human-readable form. They are used to backup and restore wallets in a secure and easy way. +Here are the list of mnemonics that the community uses in Monero: + +- [Legacy (25 Word)](./legacy.md) +- [MyMonero (13 Word)](./mymonero.md) +- [Polyseed (16 Word)](./polyseed.md) diff --git a/docs/en/mnemonics/legacy.md b/docs/en/mnemonics/legacy.md new file mode 100644 index 0000000..03f0df1 --- /dev/null +++ b/docs/en/mnemonics/legacy.md @@ -0,0 +1,15 @@ +--- +title: Legacy Mnemonic Scheme +--- + +The legacy mnemonic scheme is the oldest and most widely-used mnemonic scheme in the Monero ecosystem. It comprises a total of 25 words, where the first 24 words are for the seed and the last word is for the checksum. The checksum word is used to verify the correctness of the seed. + +The first 24 words are randomly selected from a list of 1626 words described in [`src/mnemonics/english.h`](https://github.com/monero-project/monero/blob/master/src/mnemonics/english.h) (Wordlists available for other languages can be found in [`src/mnemonics`](https://github.com/monero-project/monero/tree/master/src/mnemonics)). The checksum word is selected by calculating the [CRC32 checksum index](https://en.wikipedia.org/wiki/Cyclic_redundancy_check) of a string that is made by concatenating the first `prefix_length`ed characters of each selected word. The `prefix_length` is the number of characters to be used from each word to calculate the checksum. [In the case of English wordlist, the `prefix_length` is 3](https://github.com/monero-project/monero/blob/master/src/mnemonics/english.h#L52C47-L52C48). + +Example of calculating the checksum word: + +1. Randomly select (don't forget that randomness should be [cryptographically secure](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator)) 24 words from the wordlist. For example, let's say the chosen words are `lush bagpipe stacking mice imitate village gang efficient strained different together vain puck roped pancakes shocking liar moisture memoir sorry syndrome kettle swept dehydrate`. +2. Take the first 3 characters of each word and concatenate them. In this case, it will be `lusbagstamicimivilganeffstrdiftogvaipucroppansholiamoimemsorsynketswedeh`. +3. Calculate the CRC32 checksum of the concatenated string. In this case, the checksum gives us the decimal number `2248614488`. +4. Take the checksum index modulo 24. In this case, the modulo gives us `8`. +5. The 8th index of the wordlist is `strained` (don't forget that the wordlist is 0-indexed). So, the checksum word is `strained`. diff --git a/docs/en/mnemonics/mymonero.md b/docs/en/mnemonics/mymonero.md new file mode 100644 index 0000000..fd3c511 --- /dev/null +++ b/docs/en/mnemonics/mymonero.md @@ -0,0 +1,13 @@ +--- +title: MyMonero Mnemonic Scheme +--- + +The MyMonero scheme can be thought of as the 13-word version of the [Legacy Mnemonic Scheme](./legacy.md). Most processes remain the same in both schemes, but of course there are things that are different. For example, the method for deriving the checksum and the method for deriving the hexadecimal seed are the same, but since MyMonero generates a shorter hexadecimal seed, deriving private keys from that hexadecimal seed is different than in Legacy. + +For users looking to convert a MyMonero seed into a legacy one, an offline converter can be found at [xmr.llcoins.net](https://github.com/luigi1111/xmr.llcoins.net/). + +The MyMonero scheme was initially used by MyMonero web and mobile wallet, but other projects also adopted this scheme. The scheme is designed to be more user-friendly and easier to remember than the legacy scheme. + +The MyMonero scheme comprises a total of 13 words, where the first 12 words are for the seed and the last word is for the checksum. The checksum word is used to verify the correctness of the seed. + +Deriving checksum process is the same as the [Legacy Mnemonic Scheme](./legacy.md), you can check out the details from that page. diff --git a/docs/en/mnemonics/polyseed.md b/docs/en/mnemonics/polyseed.md new file mode 100644 index 0000000..e114e7f --- /dev/null +++ b/docs/en/mnemonics/polyseed.md @@ -0,0 +1,33 @@ +--- +title: Polyseed Mnemonic Scheme +--- + +> **Note**: Adapted for monero-docs. The expanded original README is available on Tevador's [Polyseed repository](https://github.com/tevador/polyseed) + +The polyseed mnemonic scheme was initally intended for implementation alongside Seraphis and Jamtis, though it was adopted by the community ahead of schedule due to its efficiency, simplicity and security. One such UX improvement is the embedding of the [wallet birthday (restore height)](#wallet-birthday-restore-height), which removes the need for users to store the info manually. + +Unlike the legacy mnemonic scheme, the polyseed mechanism does not allow you to choose the words from a wordlist. Instead, the words are generated from the [secret seed](#secret-seed), feature bits and birthday bits. The feature bits are used to determine the wallet features and the birthday bits are used to determine the [wallet birthday](#wallet-birthday-restore-height). + +### Encoding + +Each word contains 11 bits of information that is the index of the word from the polyseed, which is a list of 2048 words (Notice that 2^11 is 2048). The words are determined by the following formula: + +| Word | Contents | +|----|----------| +|1 | Checksum (11 bits) | +|2-6 | Secret seed (10 bits) + Features (1 bit) | +|7-16| Secret seed (10 bits) + Birthday (1 bit) | + +In total, there are 11 bits for the checksum, 150 bits for the secret seed, 5 feature bits and 10 birthday bits. + +### Wallet birthday (Restore height) + +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. + +The wallet birthday has a resolution of 2629746 seconds (1/12 of the average Gregorian year). All dates between November 2021 and February 2107 can be represented (Total of 1024 months, as we have 10 bits for it, 2^10 = 1024). + +### Secret seed + +Polyseed was designed for the 128-bit security level. This corresponds to the security of the ed25519 elliptic curve, which requires [about 2^126 operations](https://safecurves.cr.yp.to/rho.html) to break a key. + +The private key is derived from the 150-bit secret seed using PBKDF2-HMAC-SHA256 with 10000 iterations. The KDF parameters were selected to allow for the key to be derived by hardware wallets. diff --git a/mkdocs.yml b/mkdocs.yml index 890903f..eb8048d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -55,6 +55,11 @@ nav: - Standard: 'public-address/standard-address.md' - Subaddress: 'public-address/subaddress.md' - Integrated: 'public-address/integrated-address.md' + - Mnemonics: + - 'mnemonics/index.md' + - Legacy: 'mnemonics/legacy.md' + - MyMonero: 'mnemonics/mymonero.md' + - Polyseed: 'mnemonics/polyseed.md' - Proof of Work: # This section needs improvement - What is PoW?: 'proof-of-work/what-is-pow.md' - PoW in Cryptocurrencies: 'proof-of-work/pow-in-cryptocurrencies.md'