Merge pull request #4908 from ethereum/chriseth-patch-5

Blockchain basics part 2

docs/assembly.rst

@@ -141,6 +141,8 @@ these curly braces, the following can be used (see the later sections for more d
  - assignments in functional style, e.g. ``x := add(y, 3)``
  - blocks where local variables are scoped inside, e.g. ``{ let x := 3 { let y := add(x, 1) } }``
 
+.. _opcodes:
+
 Opcodes
 -------
 

docs/introduction-to-smart-contracts.rst

@@ -359,36 +359,38 @@ Gas
 
 Upon creation, each transaction is charged with a certain amount of **gas**,
 whose purpose is to limit the amount of work that is needed to execute
-the transaction and to pay for this execution. While the EVM executes the
+the transaction and to pay for this execution at the same time. While the EVM executes the
 transaction, the gas is gradually depleted according to specific rules.
 
 The **gas price** is a value set by the creator of the transaction, who
 has to pay ``gas_price * gas`` up front from the sending account.
-If some gas is left after the execution, it is refunded in the same way.
+If some gas is left after the execution, it is refunded to the creator in the same way.
 
-If the gas is used up at any point (i.e. it is negative),
+If the gas is used up at any point (i.e. it would be negative),
 an out-of-gas exception is triggered, which reverts all modifications
 made to the state in the current call frame.
 
-Any unused gas is refunded at the end of the transaction.
-
 .. index:: ! storage, ! memory, ! stack
 
 Storage, Memory and the Stack
 =============================
 
-The Ethereum Virtual Machine has three areas where it can store data.
+The Ethereum Virtual Machine has three areas where it can store data,
+storage, memory and the stack, which are explained in the following
+paragraphs.
 
-Each account has a data area called **storage**, which is persistent between function calls.
+Each account has a data area called **storage**, which is persistent between function calls
+and transactions.
 Storage is a key-value store that maps 256-bit words to 256-bit words.
-It is not possible to enumerate storage from within a contract and it is comparatively costly to read, and even more to modify storage.
+It is not possible to enumerate storage from within a contract and it is
+comparatively costly to read, and even more to modify storage.
 A contract can neither read nor write to any storage apart from its own.
 
 The second data area is called **memory**, of which a contract obtains
 a freshly cleared instance for each message call. Memory is linear and can be
 addressed at byte level, but reads are limited to a width of 256 bits, while writes
 can be either 8 bits or 256 bits wide. Memory is expanded by a word (256-bit), when
-accessing (either reading or writing) a previously untouched memory word (ie. any offset
+accessing (either reading or writing) a previously untouched memory word (i.e. any offset
 within a word). At the time of expansion, the cost in gas must be paid. Memory is more
 costly the larger it grows (it scales quadratically).
 
@@ -401,7 +403,8 @@ the topmost 16 elements to the top of the stack or swap the
 topmost element with one of the 16 elements below it.
 All other operations take the topmost two (or one, or more, depending on
 the operation) elements from the stack and push the result onto the stack.
-Of course it is possible to move stack elements to storage or memory,
+Of course it is possible to move stack elements to storage or memory
+in order to get deeper access to the stack,
 but it is not possible to just access arbitrary elements deeper in the stack
 without first removing the top of the stack.
 
@@ -411,13 +414,17 @@ Instruction Set
 ===============
 
 The instruction set of the EVM is kept minimal in order to avoid
-incorrect implementations which could cause consensus problems.
-All instructions operate on the basic data type, 256-bit words.
+incorrect or inconsistent implementations which could cause consensus problems.
+All instructions operate on the basic data type, 256-bit words or on slices of memory
+(or other byte arrays).
 The usual arithmetic, bit, logical and comparison operations are present.
 Conditional and unconditional jumps are possible. Furthermore,
 contracts can access relevant properties of the current block
 like its number and timestamp.
 
+For a complete list, please see the :ref:`list of opcodes <opcodes>` as part of the inline
+assembly documentation.
+
 .. index:: ! message call, function;call
 
 Message Calls
@@ -442,9 +449,12 @@ will receive a freshly cleared instance of memory and has access to the
 call payload - which will be provided in a separate area called the **calldata**.
 After it has finished execution, it can return data which will be stored at
 a location in the caller's memory preallocated by the caller.
+All such calls are fully synchronous.
 
 Calls are **limited** to a depth of 1024, which means that for more complex
-operations, loops should be preferred over recursive calls.
+operations, loops should be preferred over recursive calls. Furthermore,
+only 63/64th of the gas can be forwarded in a message call, which causes a
+depth limit of a little less than 1000 in practice.
 
 .. index:: delegatecall, callcode, library
 
@@ -462,7 +472,7 @@ refer to the calling contract, only the code is taken from the called address.
 
 This makes it possible to implement the "library" feature in Solidity:
 Reusable library code that can be applied to a contract's storage, e.g. in
-order to  implement a complex data structure.
+order to implement a complex data structure.
 
 .. index:: log
 
@@ -471,13 +481,13 @@ Logs
 
 It is possible to store data in a specially indexed data structure
 that maps all the way up to the block level. This feature called **logs**
-is used by Solidity in order to implement **events**.
+is used by Solidity in order to implement :ref:`events <events>`.
 Contracts cannot access log data after it has been created, but they
 can be efficiently accessed from outside the blockchain.
 Since some part of the log data is stored in `bloom filters <https://en.wikipedia.org/wiki/Bloom_filter>`_, it is
 possible to search for this data in an efficient and cryptographically
 secure way, so network peers that do not download the whole blockchain
-("light clients") can still find these logs.
+(so-called "light clients") can still find these logs.
 
 .. index:: contract creation
 
@@ -485,7 +495,7 @@ Create
 ======
 
 Contracts can even create other contracts using a special opcode (i.e.
-they do not simply call the zero address). The only difference between
+they do not simply call the zero address as a transaction would). The only difference between
 these **create calls** and normal message calls is that the payload data is
 executed and the result stored as code and the caller / creator
 receives the address of the new contract on the stack.