Merge pull request #6889 from Meshugah/develop

Brought warning to higher priority than note, etc.

docs/assembly.rst

@@ -415,7 +415,8 @@ Local Solidity variables are available for assignments, for example:
     To be safe, always clear the data properly before you use it
     in a context where this is important:
     ``uint32 x = f(); assembly { x := and(x, 0xffffffff) /* now use x */ }``
-    To clean signed types, you can use the ``signextend`` opcode.
+    To clean signed types, you can use the ``signextend`` opcode:
+    ``assembly { signextend(<bit_width_of_x>, x) }``
 
 Labels
 ------

docs/contracts/functions.rst

@@ -252,10 +252,6 @@ will consume more gas than the 2300 gas stipend:
 
 Like any function, the fallback function can execute complex operations as long as there is enough gas passed on to it.
 
-.. note::
-    Even though the fallback function cannot have arguments, one can still use ``msg.data`` to retrieve
-    any payload supplied with the call.
-
 .. warning::
     The fallback function is also executed if the caller meant to call
     a function that is not available. If you want to implement the fallback
@@ -273,6 +269,10 @@ Like any function, the fallback function can execute complex operations as long
     A contract without a payable fallback function can receive Ether as a recipient of a `coinbase transaction` (aka `miner block reward`)
     or as a destination of a ``selfdestruct``.
 
+.. note::
+    Even though the fallback function cannot have arguments, one can still use ``msg.data`` to retrieve
+    any payload supplied with the call.
+
     A contract cannot react to such Ether transfers and thus also cannot reject them. This is a design choice of the EVM and Solidity cannot work around it.
 
     It also means that ``address(this).balance`` can be higher than the sum of some manual accounting implemented in a contract (i.e. having a counter updated in the fallback function).

docs/control-structures.rst

@@ -66,6 +66,28 @@ as the actual contract has not been created yet.
 Functions of other contracts have to be called externally. For an external call,
 all function arguments have to be copied to memory.
 
+.. warning::
+  Be careful that ``feed.info.value(10).gas(800)`` only locally sets the ``value`` and amount of ``gas`` sent with the function call, and the parentheses at the end perform the actual call. So in this case, the function is not called and the ``value`` and ``gas`` settings are lost.
+
+Function calls cause exceptions if the called contract does not exist (in the
+sense that the account does not contain code) or if the called contract itself
+throws an exception or goes out of gas.
+
+.. warning::
+    Any interaction with another contract imposes a potential danger, especially
+    if the source code of the contract is not known in advance. The
+    current contract hands over control to the called contract and that may potentially
+    do just about anything. Even if the called contract inherits from a known parent contract,
+    the inheriting contract is only required to have a correct interface. The
+    implementation of the contract, however, can be completely arbitrary and thus,
+    pose a danger. In addition, be prepared in case it calls into other contracts of
+    your system or even back into the calling contract before the first
+    call returns. This means
+    that the called contract can change state variables of the calling contract
+    via its functions. Write your functions in a way that, for example, calls to
+    external functions happen after any changes to state variables in your contract
+    so your contract is not vulnerable to a reentrancy exploit.
+
 .. note::
     A function call from one contract to another does not create its own transaction,
     it is a message call as part of the overall transaction.
@@ -89,28 +111,6 @@ When calling functions of other contracts, you can specify the amount of Wei or
 You need to use the modifier ``payable`` with the ``info`` function because
 otherwise, the ``.value()`` option would not be available.
 
-.. warning::
-  Be careful that ``feed.info.value(10).gas(800)`` only locally sets the ``value`` and amount of ``gas`` sent with the function call, and the parentheses at the end perform the actual call. So in this case, the function is not called and the ``value`` and ``gas`` settings are lost.
-
-Function calls cause exceptions if the called contract does not exist (in the
-sense that the account does not contain code) or if the called contract itself
-throws an exception or goes out of gas.
-
-.. warning::
-    Any interaction with another contract imposes a potential danger, especially
-    if the source code of the contract is not known in advance. The
-    current contract hands over control to the called contract and that may potentially
-    do just about anything. Even if the called contract inherits from a known parent contract,
-    the inheriting contract is only required to have a correct interface. The
-    implementation of the contract, however, can be completely arbitrary and thus,
-    pose a danger. In addition, be prepared in case it calls into other contracts of
-    your system or even back into the calling contract before the first
-    call returns. This means
-    that the called contract can change state variables of the calling contract
-    via its functions. Write your functions in a way that, for example, calls to
-    external functions happen after any changes to state variables in your contract
-    so your contract is not vulnerable to a reentrancy exploit.
-
 Named Calls and Anonymous Function Parameters
 ---------------------------------------------
 
@@ -247,16 +247,16 @@ groupings of expressions.
 It is not possible to mix variable declarations and non-declaration assignments,
 i.e. the following is not valid: ``(x, uint y) = (1, 2);``
 
-.. note::
-    Prior to version 0.5.0 it was possible to assign to tuples of smaller size, either
-    filling up on the left or on the right side (which ever was empty). This is
-    now disallowed, so both sides have to have the same number of components.
-
 .. warning::
     Be careful when assigning to multiple variables at the same time when
     reference types are involved, because it could lead to unexpected
     copying behaviour.
 
+.. note::
+    Prior to version 0.5.0 it was possible to assign to tuples of smaller size, either
+    filling up on the left or on the right side (which ever was empty). This is
+    now disallowed, so both sides have to have the same number of components.
+
 Complications for Arrays and Structs
 ------------------------------------
 
@@ -385,6 +385,9 @@ There are two other ways to trigger exceptions: The ``revert`` function can be u
 revert the current call. It is possible to provide a string message containing details about the error
 that will be passed back to the caller.
 
+.. warning::
+    The low-level functions ``call``, ``delegatecall`` and ``staticcall`` return ``true`` as their first return value if the called account is non-existent, as part of the design of EVM. Existence must be checked prior to calling if desired.
+
 .. note::
     There used to be a keyword called ``throw`` with the same semantics as ``revert()`` which
     was deprecated in version 0.4.13 and removed in version 0.5.0.
@@ -393,9 +396,6 @@ When exceptions happen in a sub-call, they "bubble up" (i.e. exceptions are reth
 and the low-level functions ``call``, ``delegatecall`` and ``staticcall`` -- those return ``false`` as their first return value in case
 of an exception instead of "bubbling up".
 
-.. warning::
-    The low-level functions ``call``, ``delegatecall`` and ``staticcall`` return ``true`` as their first return value if the called account is non-existent, as part of the design of EVM. Existence must be checked prior to calling if desired.
-
 Catching exceptions is not yet possible.
 
 In the following example, you can see how ``require`` can be used to easily check conditions on inputs

docs/installing-solidity.rst

@@ -298,16 +298,16 @@ You might want to install ccache to speed up repeated builds.
 CMake will pick it up automatically.
 Building Solidity is quite similar on Linux, macOS and other Unices:
 
+.. warning::
+
+    BSD builds should work, but are untested by the Solidity team.
+
 .. code-block:: bash
 
     mkdir build
     cd build
     cmake .. && make
 
-.. warning::
-
-    BSD builds should work, but are untested by the Solidity team.
-
 or even easier on Linux and macOS, you can run:
 
 .. code-block:: bash

docs/introduction-to-smart-contracts.rst

@@ -57,14 +57,14 @@ and overwrite your number, but the number is still stored in the history
 of the blockchain. Later, you will see how you can impose access restrictions
 so that only you can alter the number.
 
-.. note::
-    All identifiers (contract names, function names and variable names) are restricted to
-    the ASCII character set. It is possible to store UTF-8 encoded data in string variables.
-
 .. warning::
     Be careful with using Unicode text, as similar looking (or even identical) characters can
     have different code points and as such are encoded as a different byte array.
 
+.. note::
+    All identifiers (contract names, function names and variable names) are restricted to
+    the ASCII character set. It is possible to store UTF-8 encoded data in string variables.
+
 .. index:: ! subcurrency
 
 Subcurrency Example
@@ -513,10 +513,10 @@ Deactivate and Self-destruct
 
 The only way to remove code from the blockchain is when a contract at that address performs the ``selfdestruct`` operation. The remaining Ether stored at that address is sent to a designated target and then the storage and code is removed from the state. Removing the contract in theory sounds like a good idea, but it is potentially dangerous, as if someone sends Ether to removed contracts, the Ether is forever lost.
 
+.. warning::
+    Even if a contract is removed by "selfdestruct", it is still part of the history of the blockchain and probably retained by most Ethereum nodes. So using "selfdestruct" is not the same as deleting data from a hard disk.
+
 .. note::
     Even if a contract's code does not contain a call to ``selfdestruct``, it can still perform that operation using ``delegatecall`` or ``callcode``.
 
 If you want to deactivate your contracts, you should instead **disable** them by changing some internal state which causes all functions to revert. This makes it impossible to use the contract, as it returns Ether immediately.
-
-.. warning::
-    Even if a contract is removed by "selfdestruct", it is still part of the history of the blockchain and probably retained by most Ethereum nodes. So using "selfdestruct" is not the same as deleting data from a hard disk.

docs/types/value-types.rst

@@ -427,6 +427,9 @@ long as the operands are integers. If any of the two is fractional, bit operatio
 and exponentiation is disallowed if the exponent is fractional (because that might result in
 a non-rational number).
 
+.. warning::
+    Division on integer literals used to truncate in Solidity prior to version 0.4.0, but it now converts into a rational number, i.e. ``5 / 2`` is not equal to ``2``, but to ``2.5``.
+
 .. note::
     Solidity has a number literal type for each rational number.
     Integer literals and rational number literals belong to number literal types.
@@ -435,8 +438,6 @@ a non-rational number).
     types.  So the number literal expressions ``1 + 2`` and ``2 + 1`` both
     belong to the same number literal type for the rational number three.
 
-.. warning::
-    Division on integer literals used to truncate in Solidity prior to version 0.4.0, but it now converts into a rational number, i.e. ``5 / 2`` is not equal to ``2``, but to ``2.5``.
 
 .. note::
     Number literal expressions are converted into a non-literal type as soon as they are used with non-literal

docs/units-and-global-variables.rst

@@ -163,6 +163,16 @@ Mathematical and Cryptographic Functions
 ``keccak256(bytes memory) returns (bytes32)``:
     compute the Keccak-256 hash of the input
 
+.. warning::
+
+    If you use ``ecrecover``, be aware that a valid signature can be turned into a different valid signature without
+    requiring knowledge of the corresponding private key. In the Homestead hard fork, this issue was fixed
+    for _transaction_ signatures (see `EIP-2 <http://eips.ethereum.org/EIPS/eip-2#specification>`_), but
+    the ecrecover function remained unchanged.
+
+    This is usually not a problem unless you require signatures to be unique or
+    use them to identify items. OpenZeppelin have a `ECDSA helper library <https://docs.openzeppelin.org/v2.3.0/api/cryptography#ecdsa>`_ that you can use as a wrapper for ``ecrecover`` without this issue.
+
 .. note::
 
     There used to be an alias for ``keccak256`` called ``sha3``, which was removed in version 0.5.0.
@@ -186,16 +196,6 @@ Mathematical and Cryptographic Functions
 
     For further details, read `example usage <https://ethereum.stackexchange.com/q/1777/222>`_.
 
-.. warning::
-
-    If you use ``ecrecover``, be aware that a valid signature can be turned into a different valid signature without
-    requiring knowledge of the corresponding private key. In the Homestead hard fork, this issue was fixed
-    for _transaction_ signatures (see `EIP-2 <http://eips.ethereum.org/EIPS/eip-2#specification>`_), but
-    the ecrecover function remained unchanged.
-
-    This is usually not a problem unless you require signatures to be unique or
-    use them to identify items. OpenZeppelin have a `ECDSA helper library <https://docs.openzeppelin.org/v2.3.0/api/cryptography#ecdsa>`_ that you can use as a wrapper for ``ecrecover`` without this issue.
-
 .. note::
 
     When running ``sha256``, ``ripemd160`` or ``ecrecover`` on a *private blockchain*, you might encounter Out-of-Gas. This is because these functions are implemented as "precompiled contracts" and only really exist after they receive the first message (although their contract code is hardcoded). Messages to non-existing contracts are more expensive and thus the execution might run into an Out-of-Gas error. A workaround for this problem is to first send Wei (1 for example) to each of the contracts before you use them in your actual contracts. This is not an issue on the main or test net.