[doc/src/spec/{crypto,payment}] edit fmt

doc/src/spec/crypto/commitment.md

@@ -1,9 +1,12 @@
-# commitment
+# Commitment
 
-darkfi contract uses computationally binding, perfectly hiding pedersen commitment function in both money, and consensus contracts.
+Darkfi contract uses computationally binding, perfectly hiding pedersen commitment function in both money, and consensus contracts.
 
-cm = comm(m, r), m is data encrypted as curve field element, r a random curve scalar is blinding factor, is a computationally hiding, computationally binding commitment.
+cm = comm(m, r), m is data encrypted as curve field element, r is a random curve scalar blinding factor, `comm` is a computationally hiding, computationally binding commitment.
 
-## curve point commitment
-commitment to a curve point pt after convertion to affine coordinates $pt = (pt_x, pt_y)$
-$$cm_x, cm_y = comm(pt) = comm(pt_x, r_x), comm(pt_y, r_y)$$
+## Curve point commitment
+
+Commitment to a curve point pt is tuple $(cm_x,cm_y)$, after conversion to affine coordinates of pt: $(pt_x, pt_y)$
+
+$$cm_x = comm(pt_x, r_x)$$
+$$cm_y = comm(pt_y, r_x)$$

doc/src/spec/crypto/hash.md

@@ -1,5 +1,6 @@
-# hash
+# Hash
+
+Required by the signature scheme to be:
 
-required by signature scheme to be:
 - random-prefix preimage resistant.
 - random-prefix second-preimage resistant

doc/src/spec/crypto/keypair.md

@@ -1,11 +1,11 @@
-# keypair
+# Keypair
 
-key pair over the elliptic curve finite field with generator `g`
+Key pair over the elliptic curve finite field with generator `g`
 
-## secret key
+## Secret key
 
-secret key `sk` is a finite field element over the elliptic curve.
+Secret key `sk` is a finite field element over the elliptic curve.
 
-## public key
+## Public key
 
-public key `pk` is a finite field element over the elliptic curve $g*sk$
+Public key `pk` is a finite field element over the elliptic curve: $g*sk$

doc/src/spec/crypto/merkletree.md

@@ -1,23 +1,23 @@
-# merkle-tree
+# Merkle-tree
 
-append only merkle-tree `tree`
+Append only merkle-tree `tree`
 
-## merkle-node
+## Merkle-node
 
-a node `node` is a field element on the elliptic curve
+A node `node` is a field element on the elliptic curve
 
-## merkle root
+## Merkle root
 
-hash of leaf up to certain depth root(tree, depth), hash the leafs including the empty nodes up to given `depth`,
+Hash of leaf up to certain depth root(tree, depth), hash the leafs including the empty nodes up to given `depth`,
 
-## witness
+## Witness
 
-authentication path to given `depth`, and bridge frontier, or position.
+Authentication path to given `depth`, and bridge frontier, or position.
 
-## sparse merkle tree
+## Sparse merkle tree
 
-is a merkle-tree with leafs stored in a search tree, has advantage over merkle-tree that is a allow non-inclusion proof, through membership proof to index of data in the search tree.
+Is a merkle-tree with leafs stored in a search tree, has advantage over merkle-tree that is a allow non-inclusion proof, through membership proof to index of data in the search tree.
 
-### membership proof
+### Membership proof
 
-given `index` the proof is a `path` from the leaf at `index` to the root.
+Given `index` the proof is a `path` from the leaf at `index` to the root.

doc/src/spec/crypto/note.md

@@ -1,12 +1,14 @@
-# note
-coin is stream cipher encrypted with symmetric key `key` derived from shared key[^1].
+# Note
+
+note is stream cipher encrypted with symmetric key `key`, derived from shared key[^1].
 `key` = hash(sharedSecret, ephemeralKey)
-$sharedSecret = ephemeralSecret \mul publicKey$ where `publicKey` is recipient public key. based off diffie-hellman shared secret.
+$sharedSecret = ephemeralSecret * publicKey$ where `publicKey` is recipient public key. based off diffie-hellman shared secret.
+
+## Payment Note
 
-## payment note
-Note = (sn, value, tokenId, spendHook, data, blind^{value}, blind^{token}, memo)
+Note = (sn, value, tokenId, spendHook, data, $blind^{value}$, $blind^{token}$, memo)
 
-| note            | description                    |
+| Note            | Description                    |
 |-----------------|--------------------------------|
 | sn              | serial number sampled at random|
 | value           | payment value                  |

doc/src/spec/crypto/signature.md

@@ -1,9 +1,8 @@
-# signature
-signature for keypair over the elliptic curve, with security hinged on the security of hash random oracle.
+# Signature
+Signature for keypair over the elliptic curve, it's security hinged on the security of hash random oracle.
 
-# signature protocol
-signature = sign(sk, msg), `sk` private key used for message signature generation, `msg` message to be signed, signature as response, and challenge pair
-verify(pk, msg, signature) `pk` public key corresponding to message signing private key,  validate signature is valid for given msg with signature public key.
+# Signature protocol
+Signature = sign(sk, msg), `sk` private key used for message signature generation, `msg` message to be signed, signature as response, and challenge pair. to verify call verify(pk, msg, signature) with `pk` public key corresponding to message signing private key,  validate signature is valid for given msg and signature public key.
 
-# nonce leakage
-make sure the nonce, or source of randomness is true random every time call to signature sign is called with the same keypair, otherwise the secret key be leaked given just two signatures, $response_1 - response_2  = mask - sk * challenge_1 - mask + sk * challenge_2 = sk * (challenge_2 - challenge_1)$
+# Nonce leakage
+Make sure the nonce or source of randomness is true random every time call to signature sign is called with the same keypair, otherwise the secret key can be leaked given just two signatures, $response_1 - response_2  = mask - sk * challenge_1 - mask + sk * challenge_2 = sk * (challenge_2 - challenge_1)$

doc/src/spec/crypto/vrf.md

@@ -1,18 +1,19 @@
-# ecvrf
-ecvrf[^1] is elliptic curve Verifiable Random Function satisfies:
+# ECVRF
+
+ecvrf[^1] is elliptic curve verifiable random function that satisfies:
 
 - trusted uniqueness [^2]
 - trusted collision resistance [^3]
 - full pseudo-randomness [^4]
 
-## ecvrf protocol
+## ECVRF protocol
 
-### proof generation
+### Proof generation
 
 $proof = prove(sk, data)$, `sk` is VRF private key, `data` is input data as stream of bytes, proof is the vrf output.
 generate a vrf proof, that can be publicly verified.
 
-### proof verification
+### Proof verification
 $verify(pk, proof, data)$, `pk` is VRF public key, validate that the proof is correct.
 
 [^1]: https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-vrf-04#section-5

doc/src/spec/payment/burn.md

@@ -1,40 +1,49 @@
-# burn contract
+# Burn contract
 
 $$ X = (nullifier, cm^{value}_x, cm^{value}_y, cm^{token}, root, data, spendHook, signature^{public}_x, signature^{public}_y) $$
 
 $$ W = (value, token, blind^{value}, blind^{token}, sn, spendHook, data, blind^{data}, sk, pos, path, signature^{secret}) $$
 
-$$ \mathcal{L} = \{X:W\in \mathcal{R}\} $$
-
-
-| Public Input         | Description                                             |
-|----------------------|---------------------------------------------------------|
-| nullifier            | hash of (sk||sn)                                        |
-| $cm^{value}_x$       | x coordinate of value point commitment                  |
-| $cm^{value}_y$       | y coordinate of value point commitment                  |
-| $cm^{token}$         | commitment of tokenId as field element                  |
-| root                 | root of commitments tree                                |
-| data                 | data read during execution of burn spendHook contract   |
-| spendHook            | burn related contract                                   |
-|$signature^{public}_x$| signature public x coordinate                           |
-|$signature^{public}_y$| signature public y coordinate                           |
-
-
-| witnesses            | Description                                         |
-|----------------------|-----------------------------------------------------|
-| value                | burn value                                          |
-| token                | token id                                            |
-| $blind^{value}$      | blinding term for burn value commitment             |
-| $blind^{token}$      | blinding term for token id commitment               |
-| sn                   | serial number for burn coin                         |
-| spendHook            | contract related contract                           |
-| data                 | data read during spendHook execution                |
-| $blind^{data}$       | blinding term for data commitment                   |
-| sk                   | coin private key                                    |
-| pos                  | coin commitment leaf position in the merkle tree    |
-| path                 | coin commitment merkle tree path                    |
-| $signature^{secret}$ | signature secret key                                |
-
-# circuit checks
-
-- if the `coin` has `value` zero, then coin is set to zero, with leaf position 0 in the sparse-merkle-tree, the aim is prevent burning zero coins.
+$$ \mathcal{L} = \{X: (W,W) \in \mathcal{R}\} $$
+
+## Burning a coin
+
+- Publish [coin](coin.md)'s `nullifier` to avoid double-spending.
+- [Commit](../crypto/commitment.md] to [coin](coin.md)'s `value` $(cm^{value}_x, cm^{value}_y)$
+- [Commit](../crypto/commitment.md] to [tokenId](token_id.md)
+- Add [coin](coin.md) to [merkle tree](../crypto/merkletree.md), and set it's root `root` it as instance.
+- Set spendHook as instance
+- Calculate [$Signature^{public}$](../crypto/signature.md), and set it as instance.
+
+
+| Public Input         | Description                                                                                           |
+|----------------------|-------------------------------------------------------------------------------------------------------|
+| nullifier            | hash of $(sk||sn)$                                                                                    |
+| $cm^{value}_x$       | x coordinate of value point [commitment](../crypto/commitment.md]                                     |
+| $cm^{value}_y$       | y coordinate of value point [commitment](../crypto/commitment.md]                                     |
+| $cm^{token}$         | [commitment](../crypto/commitment.md] of [tokenId](token_id.md) as field element                      |
+| root                 | root of [coin](coin.md) [commitment](../crypto/commitment.md]s [merkle tree](../crypto/merkletree.md) |
+| data                 | data read during execution of burn spendHook contract                                                 |
+| spendHook            | burn related contract                                                                                 |
+|$signature^{public}_x$| [signature](../crypto/signature.md) public x coordinate                                               |
+|$signature^{public}_y$| [signature](../crypto/signature.md) public y coordinate                                               |
+
+
+| Witnesses            | Description                                                                                                       |
+|----------------------|-------------------------------------------------------------------------------------------------------------------|
+| value                | burn value                                                                                                        |
+| token                | [tokenId](token_id.md)                                                                                            |
+| $blind^{value}$      | blinding term for burn value [commitment](../crypto/commitment.md]                                                |
+| $blind^{token}$      | blinding term for [tokenId](token_id.md) [commitment](../crypto/commitment.md]                                    |
+| sn                   | serial number for burn [coin](coin.md)                                                                            |
+| spendHook            | contract related contract                                                                                         |
+| data                 | data read during spendHook execution                                                                              |
+| $blind^{data}$       | blinding term for data [commitment](../crypto/commitment.md]                                                      |
+| sk                   | [coin](coin.md) [private key](../crypto/keypair.md)                                                                                       |
+| pos                  | [coin](coin.md) [commitment](../crypto/commitment.md) leaf position in the [merkle tree](../crypto/merkletree.md) |
+| path                 | [coin](coin.md) [commitment](../crypto/commitment.md) path in the [merkle tree](../crypto/merkletree.md)          |
+| $signature^{secret}$ | [signature](../crypto/signature.md) [secret key](../crypto/keypair.md)                                                                    |
+
+# Circuit checks
+
+- If the [coin](coin.md) has `value` zero, then [coin](coin.md) is set to zero, with leaf position 0 in the [sparse merkle tree](../crypto/merkletree.md), the aim is prevent burning zero value [coin](coin.md)s.

doc/src/spec/payment/freeze_token.md

@@ -1,6 +1,6 @@
-# freeze token
+# Freeze contract
 
-burn minted coins
+Burn minted [coin](coin.md)s
 
 $$ X = (authority^{public}_x, authority^{public}_y, token) $$
 
@@ -8,12 +8,17 @@ $$ W = (authority^{secret}) $$
 
 $$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
 
+## Freeze token
+- Derive mint authority [public key](../crypto/keypair.md) from witness $authority^{secret}$, and set it as instance.
+- Calculate, and reveal tokenId of the tokens.
+
+
 | Public Input         | Description                                             |
 |----------------------|---------------------------------------------------------|
-|$authority^{public}_y$| minting authority public key y-coordinate               |
-|$authority^{public}_x$| minting authority public key x-coordinate               |
+|$authority^{public}_y$| minting authority [public key](../crypto/keypair.md) y-coordinate               |
+|$authority^{public}_x$| minting authority [public key](../crypto/keypair.md) x-coordinate               |
 | token                | derived token id                                        |
 
-| witnesses            | Description                                         |
+| Witnesses            | Description                                         |
 |----------------------|-----------------------------------------------------|
-| $authority^{secret}$ | minting authority secret key                        |
+| $authority^{secret}$ | minting authority [secret key](../crypto/keypair.md)|

doc/src/spec/payment/mint.md

@@ -1,26 +1,33 @@
-# mint contract
+# Mint contract
 
 $$ X = (cm^{coin}, cm^{value}_x, cm^{value}_y, cm^{token} $$
 
 $$ W = (pk_x, pk_y, value, token, sn, spendHook, data, blind^{value}, blind^{token}) $$
 
-$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
-
-| Public Input         | Description                                             |
-|----------------------|---------------------------------------------------------|
-| $cm^{coin}$          | coin commitment as field element                        |
-| $cm^{value}_x$       | x coordinate of value point commitment                  |
-| $cm^{value}_y$       | y coordinate of value point commitment                  |
-| $cm^{token}$         | commitment of tokenId as field element                  |
-
-| witnesses            | Description                                         |
-|----------------------|-----------------------------------------------------|
-| $pk_x$               | coin public key x coordinate                        |
-| $pk_y$               | coin public key y coordinate                        |
-| value                | burn value                                          |
-| token                | token id                                            |
-| sn                   | serial number for burn coin                         |
-| spendHook            | contract related contract                           |
-| data                 | data read during spendHook execution                |
-| $blind^{value}$      | blinding term for burn value commitment             |
-| $blind^{token}$      | blinding term for token id commitment               |
+$$ \mathcal{L}= \{X:(X,W)\in \mathcal{R}\} $$
+
+## Minting a coin
+
+- Calculate, and set [coin](coin.md) as instance.
+- Calculate [coin](coin.md)'s value [commitment](../crypto/commitment.md), and set it as instance.
+- Calculate [coin](coin.md)'s [tokenId](token_id.md) [commitment](../crypto/commitment.md), and set is as instance.
+
+
+| Public Input         | Description                                                                       |
+|----------------------|-----------------------------------------------------------------------------------|
+| $cm^{coin}$          | [coin](coin.md) [commitment](../crypto/commitment.md) as field element            |
+| $cm^{value}_x$       | x coordinate of value point [commitment](../crypto/commitment.md)                 |
+| $cm^{value}_y$       | y coordinate of value point [commitment](../crypto/commitment.md)                 |
+| $cm^{token}$         | [commitment](../crypto/commitment.md) of [tokenId](token_id.md) as field element  |
+
+| Witnesses            | Description                                                                    |
+|----------------------|--------------------------------------------------------------------------------|
+| $pk_x$               | [coin](coin.md) [public key](../crypto/keypair.md) x coordinate                                        |
+| $pk_y$               | [coin](coin.md) [public key](../crypto/keypair.md) y coordinate                                        |
+| value                | burn value                                                                     |
+| token                | [tokenId](token_id.md)                                                         |
+| sn                   | [coin](coin.md) serial number                                                  |
+| spendHook            | contract related contract                                                      |
+| data                 | data read during spendHook execution                                           |
+| $blind^{value}$      | blinding term for burn value [commitment](../crypto/commitment.md)             |
+| $blind^{token}$      | blinding term for [tokenId](token_id.md) [commitment](../crypto/commitment.md) |

doc/src/spec/payment/payment.md

@@ -1,5 +1,5 @@
-# payment
+# Payment
 
-implements zcash sapling payment scheme [^1], payment involve burning old sender's coin, and mint new recipient coin.
+Implements zcash sapling payment scheme [^1], payment involve burning old sender's coin, and minting new recipient's coin.
 
 [^1]: https://zips.z.cash/protocol/protocol.pdf

doc/src/spec/payment/token_mint.md

@@ -1,8 +1,7 @@
-# arbitrary token mint
+# Arbitrary token mint
 
 mint new tokens with arbitrary supply to given recipient.
 
-# new token mint
 
 $$ X = (authority^{public}_x, authority^{public}_y, token, cm^{coin}, cm^{value}_x, cm^{value}_y, cm^{token}) $$
 
@@ -10,24 +9,32 @@ $$ W = (authority^{secret}, value, rcpt_x, rcpt_y, sn, spendHook, data, blind^{v
 
 $$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
 
-| Public Input         | Description                                             |
-|----------------------|---------------------------------------------------------|
-|$authority^{public}_y$| minting authority public key y-coordinate               |
-|$authority^{public}_x$| minting authority public key x-coordinate               |
-| token                | derived token id                                        |
-| $cm^{coin}$          | coin commitment as field element                        |
-| $cm^{value}_x$       | x coordinate of supply point commitment                 |
-| $cm^{value}_y$       | y coordinate of supply point commitment                 |
-| $cm^{token}$         | commitment of tokenId as field element                  |
-
-| witnesses            | Description                                         |
-|----------------------|-----------------------------------------------------|
-| $authority^{secret}$ | minting authority secret key                        |
-| value                | token minted supply value                           |
-| $rcpt_x$             | token recipient public key x coordinate             |
-| $rcpt_y$             | token recipient public key y coordinate             |
-| sn                   | serial number for burn coin                         |
-| spendHook            | contract related contract                           |
-| data                 | data read during spendHook execution                |
-| $blind^{value}$      | blinding term for burn value commitment             |
-| $blind^{token}$      | blinding term for token id commitment               |
+## New token mint
+
+- Derive, and reveal mint authority [public key](../crypto/keypair.md).
+- Derive, and reveal new tokenId.
+- Calculate, and reveal new token's [coin](coin.md).
+- Calculate, and reveal [coin](coin.md)'s token [commitment](../crypto/commitment.md).
+
+
+| Public Input         | Description                                                            |
+|----------------------|------------------------------------------------------------------------|
+|$authority^{public}_y$| minting authority [public key](../crypto/keypair.md) y-coordinate                              |
+|$authority^{public}_x$| minting authority [public key](../crypto/keypair.md) x-coordinate                              |
+| token                | derived token id                                                       |
+| $cm^{coin}$          | [coin](coin.md) [commitment](../crypto/commitment.md) as field element |
+| $cm^{value}_x$       | x coordinate of supply point [commitment](../crypto/commitment.md)     |
+| $cm^{value}_y$       | y coordinate of supply point [commitment](../crypto/commitment.md)     |
+| $cm^{token}$         | [commitment](../crypto/commitment.md) of tokenId as field element      |
+
+| Witnesses            | Description                                                        |
+|----------------------|--------------------------------------------------------------------|
+| $authority^{secret}$ | minting authority [secret key](../crypto/keypair.md)                                       |
+| value                | token minted supply value                                          |
+| $rcpt_x$             | token recipient [public key](../crypto/keypair.md) x coordinate                            |
+| $rcpt_y$             | token recipient [public key](../crypto/keypair.md) y coordinate                            |
+| sn                   | [coin](coin.md) serial number                                      |
+| spendHook            | contract related contract                                          |
+| data                 | data read during spendHook execution                               |
+| $blind^{value}$      | blinding term for burn value [commitment](../crypto/commitment.md) |
+| $blind^{token}$      | blinding term for token id [commitment](../crypto/commitment.md)   |