WiP ed25519

docs/cryptography/asymmetric/ed25519.md

@@ -0,0 +1,72 @@
+# Ed25519 curve
+
+!!! danger
+    Article author is nowhere close to being a cryptographer. Be sceptical on accuracy.
+
+!!! note
+    This article is only about the underlying curve. Public key derivation and signing algorithm will be treated separately. 
+
+!!! note
+    Before we get to Monero, a little bit of context. We are talking asymmetric cryptography here.
+    The "asymmetric" simply means the are two keys:
+    
+    * the private key (used primarily for signing data and for decrypting data)
+    * the public key (used primarily for signature verification and encrypting data)
+    
+    This is in contrast to symmetric cryptography which uses a single (secret) key.
+    
+    Historically, asymmetric cryptography was based on the problem of factorization of a very large integers
+    back into prime numbers (which is practically impossible for large enough integers).
+    
+    Recently, asymmetric cryptography is based on a mathematical notion of elliptic curves.
+    Ed25519 is a specific, well researched and standardized elliptic curve.      
+
+Monero employs Ed25519 elliptic curve as a basis for its key pair generation.
+ 
+However, Monero does not exactly follow EdDSA reference signature scheme.
+
+## Definition
+
+This is the standard Ed25519 curve definition, no Monero specific stuff here.
+
+Curve equation:
+
+    −x^2 + y^2 = 1 − (121665/121666) * x^2 * y^2
+
+Base point:
+ 
+    # The base point is the specific point on the curve. It is used
+    # as a basis for further calculations. It is an arbitrary choice
+    # by the curve authors, just to standarize the scheme.
+    # 
+    # Note that it is enough to specify the y value and the sign of the x value.
+    # That's because the specific x can be calculated from the curve equation.    
+    G = (x, 4/5)  # take the point with the positive x
+    
+    # The hex representation of the base point
+    5866666666666666666666666666666666666666666666666666666666666666    
+
+Prime order of the base point:
+
+    # In layment terms, the "canvas" where the curve is drawn is assumed
+    # to have a finite "resolution", so point coordinates must "wrap around"
+    # at some point. This is achieved by modulo the "l" value.
+    # In other words, the "l" defines the maximum scalar we can use.
+    l = 2^252 + 27742317777372353535851937790883648493
+
+The total number of points on the curve, a prime number:
+
+    q = 2^255 - 19
+
+## Implementation
+
+Monero uses (apparently modified) Ref10 implementation by Daniel J. Bernstein.
+
+## Reference
+
+* [Understanding Monero Cryptography](https://steemit.com/monero/@luigi1111/understanding-monero-cryptography-privacy-introduction) - excellent writeup by Luigi
+* [StackOverflow answer](https://monero.stackexchange.com/questions/2290/why-how-does-monero-generate-public-ed25519-keys-without-using-the-standard-publ)
+* [Python implementation](https://github.com/monero-project/mininero/blob/master/ed25519.py) - not the reference one but easier to understand
+* [Encoding point to hex](https://monero.stackexchange.com/questions/6050/what-is-the-base-point-g-from-the-whitepaper-and-how-is-it-represented-as-a)
+* [Ed25519 on Wikipedia](https://en.wikipedia.org/wiki/EdDSA#Ed25519)
+* [A (Relatively Easy To Understand) Primer on Elliptic Curve Cryptography](https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/)

docs/cryptography/asymmetric/intro.md

@@ -0,0 +1,30 @@
+# Asymmetric cryptography used in Monero
+
+!!! danger
+    Article author is nowhere close to being a cryptographer. Be sceptical on accuracy.
+
+Before we get to Monero, a little bit of context. We are talking asymmetric cryptography here.
+The "asymmetric" simply means the are two keys:
+
+* the private key (used primarily for signing data and for decrypting data)
+* the public key (used primarily for signature verification and encrypting data)
+
+This is in contrast to symmetric cryptography which uses a single (secret) key.
+
+Historically, asymmetric cryptography was based on the problem of factorization of a very large integers
+back into prime numbers (which is practically impossible for large enough integers).
+
+Recently, asymmetric cryptography is based on a mathematical notion of elliptic curves.
+Ed25519 is a specific, well researched and standardized elliptic curve used in Monero.      
+
+## Private key
+
+Private key is a **large integer**, like:
+`115792089237316195423570985008687907853269984665640564039457584007913129639930`
+
+Private key is a **scalar**, meaning it is a single value.
+
+In equations scalars are represented by **lowercase letters**. 
+
+In user-facing contexts, private keys are encoded in little-endian hexadecimal form, like:
+`35187c5096d10db8a57be93885f28694ac9dcaa09d6b1fb1903aec07e168430a`

docs/cryptography/ed25519.md

@@ -1,27 +0,0 @@
-# Ed25519 curve
-
-**!! Work in progress - be sceptical on accuracy !!**
-
-Monero employs Ed25519 curve as a basis for its signature scheme.
- 
-However, Monero does not follow EdDSA reference signature scheme.
-
-## Public key derivation
-
-In relation to EdDSA, Monero derives public keys differently:
-
-* Monero uses Keccak instead of SHA-512
-* Monero uses private keys as scalars, not as seeds
-
-## Signature scheme
-
-In relation to EdDSA, Monero uses a different signature scheme.
-
-## Implementation
-
-For the curve itself, Monero uses Ref10 implementation by Daniel J. Bernstein.
-
-## Reference
-
-* [Understanding Monero Cryptography](https://medium.com/@luigi1111w/understanding-monero-cryptography-privacy-introduction-9baf073e970c) - excellent writeup by Luigi
-* [StackOverflow answer](https://monero.stackexchange.com/questions/2290/why-how-does-monero-generate-public-ed25519-keys-without-using-the-standard-publ)

docs/multisignature.md

@@ -1,6 +1,7 @@
 # Multisignature
 
-**!! This is unreleased feature !!**
+!!! warning
+    This is unreleased feature.
 
 In cryptocurrencies, multisig feature allows to sign transaction with more than one private key. Funds protected with multisig can only be spent by signing with M-of-N keys.
 

docs/public-address/subaddress.md

@@ -1,6 +1,7 @@
 # Subaddress
 
-**!! This is unreleased feature !!**
+!!! warning
+    This is unreleased feature.
 
 Subaddresses serve two purposes described below.
 

docs/technical-specs.md

@@ -4,7 +4,7 @@
 
 * Monero blockchain is live since 18 April 2014
 
-## No premine, no instamine, no ICO/token
+## No premine, no instamine, no ICO, no token
 
 * Monero had no premine or instamine
 * Monero did not sell any token
@@ -27,46 +27,46 @@
 
 ## Block reward
 
-* ~6 XMR as of Dec 2017, see the [latest block](https://moneroblocks.info/) coinbase transaction amount for current reward
 * smoothly decreasing and subject to penalties for blocks greater then median size of the last 100 blocks (M100)
+* ~6 XMR as of Dec 2017; for the current reward check the coinbase transaction of the [latest block](https://moneroblocks.info/)
 
 ## Block size
 
-* dynamic, maximum of two times median size of the last 100 blocks (2 * M100)
+* dynamic
+* maximum of two times the median size of the last 100 blocks (2 * M100)
+* ~150KB as of Dec 2017; check [the latest block size](https://bitinfocharts.com/comparison/monero-size.html#3m)
 
 ## Emission curve
 
-**Main emission**
+### Main emission
 
-First, the main emission is about to produce ~18.132 million coins by the end of May 2022.
+* first, the main emission is about to produce ~18.132 million coins by the end of May 2022
+* as of Dec 2017 the emission is about 30 XMR per 10 minutes
+* see [charts and details](https://www.reddit.com/r/Monero/comments/512kwh/useful_for_learning_about_monero_coin_emission/)
 
-As of Dec 2017 the emission is about 30 XMR per 10 minutes.
+### Tail emission
 
-See [charts and details](https://www.reddit.com/r/Monero/comments/512kwh/useful_for_learning_about_monero_coin_emission/).
+* the tail emission kicks in once main emission is done
-
+* it will produce 0.6 XMR per 2-minute block
-**Tail emission**
+* this translates to <1% inflation decreasing over time
-
-The tail emission kicks in once main emission is done.
-
-It will produce 0.6 XMR per 2-minute block.
-
-This translates to <1% inflation decreasing over time.
 
 ## Max supply
 
-* infinite
+* ~18.132 million XMR + 0.6 XMR per 2 minutes
+* technically infinite
+* practically might be deflationary if accounted for lost coins
 
 ## Sender privacy
 
-* Ring signatures
+* ring signatures
 
 ## Recipient privacy
 
-* Stealth addresses
+* stealth addresses
 
 ## Amount privacy
 
-* Ring confidential transactions
+* ring confidential transactions
 
 ## IP address privacy
 

mkdocs.yml

@@ -7,12 +7,14 @@ site_url: 'https://monerodocs.org/'
 pages:
 - Home: 'index.md'
 - Interacting: 'interacting/overview.md'
-- Technical Specs: 'technical-specs.md'
+- Technical specs: 'technical-specs.md'
 - Cryptography:
     - Overview: 'cryptography/overview.md'
     - PRNG: 'cryptography/prng.md'
     - 'Keccak-256': 'cryptography/keccak-256.md'
-    - Ed25519: 'cryptography/ed25519.md'
+    - Asymmetric:
+#      - Overview: 'cryptography/asymmetric/intro.md'
+      - 'Ed25519 curve': 'cryptography/asymmetric/ed25519.md'
 #    - CryptoNight PoW: 'cryptography/cryptonight.md'
     - Base58: 'cryptography/base58.md'
 - Address:
@@ -36,3 +38,11 @@ extra_css: ['extra.css']
 
 repo_name: 'monerodocs/md'
 repo_url: 'https://github.com/monerodocs/md'
+
+markdown_extensions:
+  # https://squidfunk.github.io/mkdocs-material/extensions/admonition/
+  - admonition
+  - codehilite:
+      guess_lang: false
+  - toc:
+      permalink: true