Merge pull request #4907 from ethereum/chriseth-patch-4-1

Blockchain basics part 1

1 files changed, 16 insertions, 13 deletions

diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst
index bd30a8fd..5ba7ed12 100644
--- a/docs/introduction-to-smart-contracts.rst
+++ b/docs/introduction-to-smart-contracts.rst
@@ -220,7 +220,7 @@ Blockchain Basics
 
 Blockchains as a concept are not too hard to understand for programmers. The reason is that
 most of the complications (mining, `hashing <https://en.wikipedia.org/wiki/Cryptographic_hash_function>`_, `elliptic-curve cryptography <https://en.wikipedia.org/wiki/Elliptic_curve_cryptography>`_, `peer-to-peer networks <https://en.wikipedia.org/wiki/Peer-to-peer>`_, etc.)
-are just there to provide a certain set of features and promises. Once you accept these
+are just there to provide a certain set of features and promises for the platform. Once you accept these
 features as given, you do not have to worry about the underlying technology - or do you have
 to know how Amazon's AWS works internally in order to use it?
 
@@ -235,7 +235,7 @@ If you want to change something in the database, you have to create a so-called
 which has to be accepted by all others.
 The word transaction implies that the change you want to make (assume you want to change
 two values at the same time) is either not done at all or completely applied. Furthermore,
-while your transaction is applied to the database, no other transaction can alter it.
+while your transaction is being applied to the database, no other transaction can alter it.
 
 As an example, imagine a table that lists the balances of all accounts in an
 electronic currency. If a transfer from one account to another is requested,
@@ -254,12 +254,13 @@ only the person holding the keys to the account can transfer money from it.
 Blocks
 ======
 
-One major obstacle to overcome is what, in Bitcoin terms, is called a "double-spend attack":
-What happens if two transactions exist in the network that both want to empty an account,
-a so-called conflict?
+One major obstacle to overcome is what (in Bitcoin terms) is called a "double-spend attack":
+What happens if two transactions exist in the network that both want to empty an account?
+Only one of the transactions can be valid, typically the one that is accepted first.
+The problem is that "first" is not an objective term in a peer-to-peer network.
 
-The abstract answer to this is that you do not have to care. An order of the transactions
-will be selected for you, the transactions will be bundled into what is called a "block"
+The abstract answer to this is that you do not have to care. A globally accepted order of the transactions
+will be selected for you, solving the conflict. The transactions will be bundled into what is called a "block"
 and then they will be executed and distributed among all participating nodes.
 If two transactions contradict each other, the one that ends up being second will
 be rejected and not become part of the block.
@@ -270,14 +271,16 @@ Ethereum this is roughly every 17 seconds.
 
 As part of the "order selection mechanism" (which is called "mining") it may happen that
 blocks are reverted from time to time, but only at the "tip" of the chain. The more
-blocks that are added on top, the less likely it is. So it might be that your transactions
+blocks are added on top of a particular block, the less likely this block will be reverted. So it might be that your transactions
 are reverted and even removed from the blockchain, but the longer you wait, the less
 likely it will be.
 
 .. note::
-    Transactions are not guaranteed to happen on the next block or any future specific block, since it is up to the miners to include transactions and not the submitter of the transaction. This applies to function calls and contract creation transactions alike.
+    Transactions are not guaranteed to be included in the next block or any specific future block,
+    since it is not up to the submitter of a transaction, but up to the miners to determine in which block the transaction is included.
 
-    If you want to schedule future calls of your contract, you can use the `alarm clock <http://www.ethereum-alarm-clock.com/>`_ service.
+    If you want to schedule future calls of your contract, you can use
+    the `alarm clock <http://www.ethereum-alarm-clock.com/>`_ or a similar oracle service.
 
 .. _the-ethereum-virtual-machine:
 
@@ -319,7 +322,7 @@ Every account has a persistent key-value store mapping 256-bit words to 256-bit
 words called **storage**.
 
 Furthermore, every account has a **balance** in
-Ether (in "Wei" to be exact) which can be modified by sending transactions that
+Ether (in "Wei" to be exact, `1 ether` is `10**18 wei`) which can be modified by sending transactions that
 include Ether.
 
 .. index:: ! transaction
@@ -329,7 +332,7 @@ Transactions
 
 A transaction is a message that is sent from one account to another
 account (which might be the same or the special zero-account, see below).
-It can include binary data (its payload) and Ether.
+It can include binary data (which is called "payload") and Ether.
 
 If the target account contains code, that code is executed and
 the payload is provided as input data.
@@ -340,7 +343,7 @@ As already mentioned, the address of that contract is not
 the zero address but an address derived from the sender and
 its number of transactions sent (the "nonce"). The payload
 of such a contract creation transaction is taken to be
-EVM bytecode and executed. The output of this execution is
+EVM bytecode and executed. The output data of this execution is
 permanently stored as the code of the contract.
 This means that in order to create a contract, you do not
 send the actual code of the contract, but in fact code that