From 19da9ad1e0ce52eb08934da99373307eeb6fa297 Mon Sep 17 00:00:00 2001 From: Jeremy Bokobza Date: Tue, 5 Dec 2017 00:57:03 +0000 Subject: [PATCH] Small documentation improvements (#418) --- doc/grin4bitcoiners.md | 12 ++++++------ doc/merkle.md | 13 +++++-------- doc/style.md | 4 ++-- 3 files changed, 13 insertions(+), 16 deletions(-) diff --git a/doc/grin4bitcoiners.md b/doc/grin4bitcoiners.md index 22e8ea958..28164c8c7 100644 --- a/doc/grin4bitcoiners.md +++ b/doc/grin4bitcoiners.md @@ -8,7 +8,7 @@ There are 3 main properties of Grin transactions that make them private: 2. There are no amounts. 3. 2 transactions, one spending the other, can be merged in a block to form only one, removing all intermediary information. -The 2 first properties mean that all transactions look the same. Unless you directly participated in the transaction, all inputs and outputs look like random pieces of data (in lingo, they're all random curve points). +The 2 first properties mean that all transactions are indistinguishable from one another. Unless you directly participated in the transaction, all inputs and outputs look like random pieces of data (in lingo, they're all random curve points). Moreover, there are no more transactions in a block. A Grin block looks just like one giant transaction and all original association between inputs and outputs is lost. @@ -18,20 +18,20 @@ As explained in the previous section, thanks to the MimbleWimble transaction and Pushing that further, between blocks, most outputs end up being spent sooner or later by another input. So *all spent outputs can be safely removed*. And the whole blockchain can be stored, downloaded and fully verified in just a few gigabytes or less (assuming a number of transactions similar to bitcoin). -What this all means is the Grin blockchain scales with the number of users (unspent outputs), not the number of transactions. At the moment, there is one caveat to that: a small piece of data (called a kernel, over about 100 bytes) needs to stay around for each transaction. But we're working on optimizing that as well. +This means that the Grin blockchain scales with the number of users (unspent outputs), not the number of transactions. At the moment, there is one caveat to that: a small piece of data (called a *kernel*, over about 100 bytes) needs to stay around for each transaction. But we're working on optimizing that as well. ## Scripting -Maybe you've heard that MimbleWimble doesn't support scripts. And in some way, that's true. But thanks to cryptographic trickery, many contracts that in bitcoin would require a script can be achieved with Grin using properties of Elliptic Curve Cryptography. So far, we know how to do: +Maybe you've heard that MimbleWimble doesn't support scripts. And in some way, that's true. But thanks to cryptographic trickery, many contracts that in Bitcoin would require a script can be achieved with Grin using properties of Elliptic Curve Cryptography. So far, we know how to do: * Multi-signature transactions. * Atomic swaps. -* Time-locked transaction and outputs. +* Time-locked transactions and outputs. * Lightning Network ## Emmission Rate -Bitcoin's 10 minute block time has its intitial 50 btc reward cut in half every 4 years until there are 21 million Bitcoin in circulation. Grin's emission rate is linear, meaning it never drops. The block reward is currently set at 50 grin with a block goal of 60 seconds. +Bitcoin's 10 minute block time has its intitial 50 btc reward cut in half every 4 years until there are 21 million bitcoin in circulation. Grin's emission rate is linear, meaning it never drops. The block reward is currently set at 50 grin with a block goal of 60 seconds. ## FAQ @@ -47,7 +47,7 @@ No, and this is where MimbleWimble and Grin shine. Confidential transactions are You can figure out which outputs are being spent by which transaction. But the trail of data stops here. All inputs and outputs look like random pieces of data, so you can't tell if the money was transferred, still belongs to the same person, which output is the actual transfer and which is the change, etc. Grin transactions are built with *no identifiable piece of information*. -### What about the quantum computaggedon +### What about the quantum computaggedon? In every Grin output, we also include a bit of hashed data, which is quantum safe. If quantum computing was to become a reality, we can safely introduce additional verification that would protect existing coins from being hacked. diff --git a/doc/merkle.md b/doc/merkle.md index 6489c2dab..52f3da4d5 100644 --- a/doc/merkle.md +++ b/doc/merkle.md @@ -37,8 +37,7 @@ Design requirements: 4. Efficient tree storage even with missing data, even with millions of entries. 5. If a node commits to NULL, it has no unspent children and its data should eventually be able to be dropped forever. -6. Support serializating and efficient merging of pruned trees from partial - archival nodes. +6. Support for serialization and efficient merging of pruned trees from partial archival nodes. ### Output witnesses @@ -49,8 +48,7 @@ than deleting it. Design requirements: -1. Support serializating and efficient merging of pruned trees from partial - archival nodes. +1. Support for serialization and efficient merging of pruned trees from partial archival nodes. ### Inputs and Outputs @@ -60,7 +58,7 @@ a sum-tree over the commitments of outputs, and the negatives of the commitments of inputs. Input references are hashes of old commitments. It is a consensus rule that -there are never two identical unspent outputs. +all unspent outputs must be unique. The root sum should be equal to the sum of excesses for this block. See the next section. @@ -81,8 +79,7 @@ archival nodes in the future we want to support efficient pruning. Design requirements: -1. Support serializating and efficient merging of pruned trees from partial - archival nodes. +1. Support for serialization and efficient merging of pruned trees from partial archival nodes. ## Proposed Merkle Structure @@ -160,7 +157,7 @@ not this sum on a pruned node is zero. The sum tree data structure allows the efficient storage of the output set and output witnesses while allowing immediate retrieval of a root hash or root sum (when applicable). However, the tree must contain every output commitment and -witness hash in the system. This data too big to be permanently stored in +witness hash in the system. This data is too big to be permanently stored in memory and too costly to be rebuilt from scratch at every restart, even if we consider pruning (at this time, Bitcoin has over 50M UTXOs which would require at least 3.2GB, assuming a couple hashes per UTXO). So we need an efficient way diff --git a/doc/style.md b/doc/style.md index 18f8a23c3..6f73a5dc6 100644 --- a/doc/style.md +++ b/doc/style.md @@ -1,6 +1,6 @@ # Grin Style Guide -Grin uses [rustfmt](https://github.com/rust-lang-nursery/rustfmt) to maintain consist formatting. +Grin uses [rustfmt](https://github.com/rust-lang-nursery/rustfmt) to maintain consistent formatting. ## Install rustfmt (nightly) @@ -22,7 +22,7 @@ There is a basic git [pre-commit](../.hooks/pre-commit) hook in the repo. The pre-commit hook will not prevent commits if style issues are present but it will indicate any files that need formatting. -To enable this create a symlink in `.git/hooks` (note the relative path) - +To enable this, create a symlink in `.git/hooks` (note the relative path) - ``` cd .git/hooks