Merge pull request #612 from Denton-L/global-variables

Cleaned up and modified global variables documentation

4 files changed, 83 insertions, 37 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 178f34d9..61081e1c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -45,19 +45,19 @@ Available Solidity Integrations
     Solidity syntax highlighting for SublimeText editor.
 
 * `Atom Solidity package <https://github.com/gmtcreators/atom-solidity/>`_
-    Plugin for the atom editor that features syntax highlighting, compilation and a runtime environment (requires backend node).
+    Plugin for the Atom editor that features syntax highlighting, compilation and a runtime environment (requires backend node).
 
 * `Atom Solidity Linter <https://atom.io/packages/linter-solidity>`_
-    Plugin for the atom editor that provides solidity linting
+    Plugin for the Atom editor that provides Solidity linting.
 
 * `Visual Studio Code extension <http://juan.blanco.ws/solidity-contracts-in-visual-studio-code/>`_
     Solidity plugin for Microsoft Visual Studio Code that includes syntax highlighting and the Solidity compiler.
 
 * `Emacs Solidity <https://github.com/ethereum/emacs-solidity/>`_
-    Plugin for the emacs editor providing syntax highlighting and compilation error reporting.
+    Plugin for the Emacs editor providing syntax highlighting and compilation error reporting.
 
-* `VIM Solidity <https://github.com/tomlion/vim-solidity/>`_
-    Plugin for the VIM editor providing syntax highlighting.
+* `Vim Solidity <https://github.com/tomlion/vim-solidity/>`_
+    Plugin for the Vim editor providing syntax highlighting.
 
 Language Documentation
 ----------------------
diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst
index 6b327c56..4e61b283 100644
--- a/docs/miscellaneous.rst
+++ b/docs/miscellaneous.rst
@@ -148,6 +148,26 @@ Pitfalls
 Unfortunately, there are some subtleties the compiler does not yet warn you about.
 
 - In ``for (var i = 0; i < arrayName.length; i++) { ... }``, the type of ``i`` will be ``uint8``, because this is the smallest type that is required to hold the value ``0``. If the array has more than 255 elements, the loop will not terminate.
+- If a contract receives Ether (without a function being called), the fallback function is executed. The contract can only rely
+  on the "gas stipend" (2300 gas) being available to it at that time. This stipend is not enough to access storage in any way.
+  To be sure that your contract can receive Ether in that way, check the gas requirements of the fallback function.
+- If you want to send ether using ``address.send``, there are certain details to be aware of:
+
+  1. If the recipient is a contract, it causes its fallback function to be executed which can in turn call back into the sending contract
+  2. Sending Ether can fail due to the call depth going above 1024. Since the caller is in total control of the call
+     depth, they can force the transfer to fail, so make sure to always check the return value of ``send``. Better yet,
+     write your contract using a pattern where the recipient can withdraw Ether instead.
+  3. Sending Ether can also fail because the recipient goes out of gas (either explicitly by using ``throw`` or
+     because the operation is just too expensive). If the return value of ``send`` is checked, this might provide a
+     means for the recipient to block progress in the sending contract. Again, the best practise here is to use
+     a "withdraw" pattern instead of a "send" pattern.
+
+- Loops that do not have a fixed number of iterations, e.g. loops that depends on storage values, have to be used carefully:
+  Due to the block gas limit, transactions can only consume a certain amount of gas. Either explicitly or just due to
+  normal operation, the number of iterations in a loop can grow beyond the block gas limit, which can cause the complete
+  contract to be stalled at a certain point. This does not apply at full extent to ``constant`` functions that are only executed
+  to read data from the blockchain. Still, such functions may be called by other contracts as part of on-chain operations
+  and stall those. Please be explicit about such cases in the documentation of your contracts.
 
 **********
 Cheatsheet
@@ -158,11 +178,11 @@ Cheatsheet
 Global Variables
 ================
 
+- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks
 - ``block.coinbase`` (``address``): current block miner's address
 - ``block.difficulty`` (``uint``): current block difficulty
 - ``block.gaslimit`` (``uint``): current block gaslimit
 - ``block.number`` (``uint``): current block number
-- ``block.blockhash`` (``function(uint) returns (bytes32)``): hash of the given block - only works for 256 most recent blocks
 - ``block.timestamp`` (``uint``): current block timestamp
 - ``msg.data`` (``bytes``): complete calldata
 - ``msg.gas`` (``uint``): remaining gas
@@ -171,17 +191,17 @@ Global Variables
 - ``now`` (``uint``): current block timestamp (alias for ``block.timestamp``)
 - ``tx.gasprice`` (``uint``): gas price of the transaction
 - ``tx.origin`` (``address``): sender of the transaction (full call chain)
-- ``sha3(...) returns (bytes32)``: compute the Ethereum-SHA3 hash of the (tightly packed) arguments
-- ``sha256(...) returns (bytes32)``: compute the SHA256 hash of the (tightly packed) arguments
-- ``ripemd160(...) returns (bytes20)``: compute RIPEMD of 256 the (tightly packed) arguments
-- ``ecrecover(bytes32, uint8, bytes32, bytes32) returns (address)``: recover address associated with the public key from elliptic curve signature
-- ``addmod(uint x, uint y, uint k) returns (uint)``: compute ``(x + y) % k`` where the addition is performed with arbitrary precision and does not wrap around at ``2**256``.
-- ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256``.
+- ``sha3(...) returns (bytes32)``: compute the Ethereum-SHA-3 (KECCAK-256) hash of the (tightly packed) arguments
+- ``sha256(...) returns (bytes32)``: compute the SHA-256 hash of the (tightly packed) arguments
+- ``ripemd160(...) returns (bytes20)``: compute the RIPEMD-160 hash of the (tightly packed) arguments
+- ``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``: recover address associated with the public key from elliptic curve signature
+- ``addmod(uint x, uint y, uint k) returns (uint)``: compute ``(x + y) % k`` where the addition is performed with arbitrary precision and does not wrap around at ``2**256``
+- ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256``
 - ``this`` (current contract's type): the current contract, explicitly convertible to ``address``
 - ``super``: the contract one level higher in the inheritance hierarchy
-- ``selfdestruct(address)``: destroy the current contract, sending its funds to the given address
-- ``<address>.balance``: balance of the address in Wei
-- ``<address>.send(uint256) returns (bool)``: send given amount of Wei to address, returns ``false`` on failure.
+- ``selfdestruct(address recipient)``: destroy the current contract, sending its funds to the given address
+- ``<address>.balance`` (``uint256``): balance of the address in Wei
+- ``<address>.send(uint256 amount) returns (bool)``: send given amount of Wei to address, returns ``false`` on failure
 
 .. index:: visibility, public, private, external, internal
 
diff --git a/docs/types.rst b/docs/types.rst
index 1d027d23..6a69f5be 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -72,6 +72,8 @@ Members of Addresses
 
 * ``balance`` and ``send``
 
+For a quick reference, see :ref:`address_related`.
+
 It is possible to query the balance of an address using the property ``balance``
 and to send Ether (in units of wei) to an address using the ``send`` function:
 
@@ -84,6 +86,12 @@ and to send Ether (in units of wei) to an address using the ``send`` function:
 .. note::
     If ``x`` is a contract address, its code (more specifically: its fallback function, if present) will be executed together with the ``send`` call (this is a limitation of the EVM and cannot be prevented). If that execution runs out of gas or fails in any way, the Ether transfer will be reverted. In this case, ``send`` returns ``false``.
 
+.. warning::
+    There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1024
+    (this can always be forced by the caller) and it also fails if the recipient runs out of gas. So in order
+    to make safe Ether transfers, always check the return value of ``send`` or even better:
+    Use a pattern where the recipient withdraws the money.
+
 * ``call``, ``callcode`` and ``delegatecall``
 
 Furthermore, to interface with contracts that do not adhere to the ABI,
@@ -95,7 +103,7 @@ the function ``call`` is provided which takes an arbitrary number of arguments o
     nameReg.call("register", "MyName");
     nameReg.call(bytes4(sha3("fun(uint256)")), a);
 
-``call`` returns a boolean indicating whether the invoked function terminated (``true``) or caused an EVM exception (`false:code:`). It is not possible to access the actual data returned (for this we would need to know the encoding and size in advance).
+``call`` returns a boolean indicating whether the invoked function terminated (``true``) or caused an EVM exception (``false``). It is not possible to access the actual data returned (for this we would need to know the encoding and size in advance).
 
 In a similar way, the function ``delegatecall`` can be used: The difference is that only the code of the given address is used, all other aspects (storage, balance, ...) are taken from the current contract. The purpose of ``delegatecall`` is to use library code which is stored in another contract. The user has to ensure that the layout of storage in both contracts is suitable for delegatecall to be used. Prior to homestead, only a limited variant called ``callcode`` was available that did not provide access to the original ``msg.sender`` and ``msg.value`` values.
 
@@ -616,10 +624,10 @@ For convenience, it is not always necessary to explicitly specify the type of a
 variable, the compiler automatically infers it from the type of the first
 expression that is assigned to the variable::
 
-    uint20 x = 0x123;
+    uint24 x = 0x123;
     var y = x;
 
-Here, the type of ``y`` will be ``uint20``. Using ``var`` is not possible for function
+Here, the type of ``y`` will be ``uint24``. Using ``var`` is not possible for function
 parameters or return parameters.
 
 .. warning::
diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst
index 8f910c80..167c694d 100644
--- a/docs/units-and-global-variables.rst
+++ b/docs/units-and-global-variables.rst
@@ -48,22 +48,22 @@ namespace and are mainly used to provide information about the blockchain.
 
 
 Block and Transaction Properties
-------------------------------------
-
- - ``block.coinbase`` (``address``): current block miner's address
- - ``block.difficulty`` (``uint``): current block difficulty
- - ``block.gaslimit`` (``uint``): current block gaslimit
- - ``block.number`` (``uint``): current block number
- - ``block.blockhash`` (``function(uint) returns (bytes32)``): hash of the given block - only for 256 most recent blocks
- - ``block.timestamp`` (``uint``): current block timestamp
- - ``msg.data`` (``bytes``): complete calldata
- - ``msg.gas`` (``uint``): remaining gas
- - ``msg.sender`` (``address``): sender of the message (current call)
- - ``msg.sig`` (``bytes4``): first four bytes of the calldata (i.e. function identifier)
- - ``msg.value`` (``uint``): number of wei sent with the message
- - ``now`` (``uint``): current block timestamp (alias for ``block.timestamp``)
- - ``tx.gasprice`` (``uint``): gas price of the transaction
- - ``tx.origin`` (``address``): sender of the transaction (full call chain)
+--------------------------------
+
+- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks
+- ``block.coinbase`` (``address``): current block miner's address
+- ``block.difficulty`` (``uint``): current block difficulty
+- ``block.gaslimit`` (``uint``): current block gaslimit
+- ``block.number`` (``uint``): current block number
+- ``block.timestamp`` (``uint``): current block timestamp
+- ``msg.data`` (``bytes``): complete calldata
+- ``msg.gas`` (``uint``): remaining gas
+- ``msg.sender`` (``address``): sender of the message (current call)
+- ``msg.sig`` (``bytes4``): first four bytes of the calldata (i.e. function identifier)
+- ``msg.value`` (``uint``): number of wei sent with the message
+- ``now`` (``uint``): current block timestamp (alias for ``block.timestamp``)
+- ``tx.gasprice`` (``uint``): gas price of the transaction
+- ``tx.origin`` (``address``): sender of the transaction (full call chain)
 
 .. note::
     The values of all members of ``msg``, including ``msg.sender`` and
@@ -89,12 +89,12 @@ Mathematical and Cryptographic Functions
 ``mulmod(uint x, uint y, uint k) returns (uint)``:
     compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256``.
 ``sha3(...) returns (bytes32)``:
-    compute the Ethereum-SHA-3 hash of the (tightly packed) arguments
+    compute the Ethereum-SHA-3 (KECCAK-256) hash of the (tightly packed) arguments
 ``sha256(...) returns (bytes32)``:
     compute the SHA-256 hash of the (tightly packed) arguments
 ``ripemd160(...) returns (bytes20)``:
     compute RIPEMD-160 hash of the (tightly packed) arguments
-``ecrecover(bytes32 data, uint8 v, bytes32 r, bytes32 s) returns (address)``:
+``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``:
     recover the address associated with the public key from elliptic curve signature
 
 In the above, "tightly packed" means that the arguments are concatenated without padding.
@@ -111,6 +111,24 @@ same as ``sha3(uint16(0x12))``.
 
 It might be that you run into Out-of-Gas for ``sha256``, ``ripemd160`` or ``ecrecover`` on a *private blockchain*. The reason for this is that those are implemented as so-called precompiled contracts and these contracts only really exist after they received the first message (although their contract code is hardcoded). Messages to non-existing contracts are more expensive and thus the execution runs into an Out-of-Gas error. A workaround for this problem is to first send e.g. 1 Wei to each of the contracts before you use them in your actual contracts. This is not an issue on the official or test net.
 
+.. _address_related:
+
+Address Related
+---------------
+
+``<address>.balance`` (``uint256``):
+    balance of the :ref:`address` in Wei
+``<address>.send(uint256 amount) returns (bool)``:
+    send given amount of Wei to :ref:`address`, returns ``false`` on failure
+
+For more information, see the section on :ref:`address`.
+
+.. warning::
+    There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1024
+    (this can always be forced by the caller) and it also fails if the recipient runs out of gas. So in order
+    to make safe Ether transfers, always check the return value of ``send`` or even better:
+    Use a pattern where the recipient withdraws the money.
+
 .. index:: this, selfdestruct
 
 Contract Related
@@ -119,7 +137,7 @@ Contract Related
 ``this`` (current contract's type):
     the current contract, explicitly convertible to :ref:`address`
 
-``selfdestruct(address)``:
+``selfdestruct(address recipient)``:
     destroy the current contract, sending its funds to the given :ref:`address`
 
 Furthermore, all functions of the current contract are callable directly including the current function.