Update docs

Author: matheusaaguiar

docs/assembly.rst

@@ -381,8 +381,9 @@ of Solidity, you can use a special comment to annotate an assembly block as memo
         ...
     }
 
-Note that we will disallow the annotation via comment in a future breaking release; so, if you are not concerned with
-backward-compatibility with older compiler versions, prefer using the dialect string.
+.. warning::
+    The ``memory-safe-assembly`` special comment will be deprecated in the next breaking version (0.9).
+    So, if you are not concerned with backward-compatibility with older compiler versions, prefer using the dialect string.
 
 Advanced Safe Use of Memory
 ---------------------------

docs/common-patterns.rst

@@ -57,7 +57,8 @@ you receive the funds of the person who is now the richest.
             // Remember to zero the pending refund before
             // sending to prevent reentrancy attacks
             pendingWithdrawals[msg.sender] = 0;
-            payable(msg.sender).transfer(amount);
+            (bool success, ) = payable(msg.sender).call{value: amount}("");
+            require(success);
         }
     }
 
@@ -84,7 +85,8 @@ This is as opposed to the more intuitive sending pattern:
         function becomeRichest() public payable {
             if (msg.value <= mostSent) revert NotEnoughEther();
             // This line can cause problems (explained below).
-            richest.transfer(msg.value);
+            (bool success, ) = richest.call{value: msg.value}("");
+            require(success);
             richest = payable(msg.sender);
             mostSent = msg.value;
         }
@@ -210,8 +212,10 @@ restrictions highly readable.
                 revert NotEnoughEther();
 
             _;
-            if (msg.value > amount)
-                payable(msg.sender).transfer(msg.value - amount);
+            if (msg.value > amount) {
+                (bool success, ) = payable(msg.sender).call{value: msg.value - amount}("");
+                require(success);
+            }
         }
 
         function forceOwnerChange(address newOwner)

docs/contracts/functions.rst

@@ -319,6 +319,11 @@ will consume more gas than the 2300 gas stipend:
     not recommended, since the fallback is invoked and would not fail for interface confusions
     on the part of the sender).
 
+.. warning::
+    Note that ``send`` and ``transfer`` are scheduled to be deprecated in the next breaking version (0.9).
+    You are encouraged to use the function ``call`` with and optional desired amount of gas and
+    an empty parameter, e.g, ``call{value: amount}("")``.
+
 
 .. warning::
     A contract without a receive Ether function can receive Ether as a
@@ -440,6 +445,7 @@ operations as long as there is enough gas passed on to it.
 
             // If someone sends Ether to that contract,
             // the transfer will fail, i.e. this returns false here.
+            // This will report a warning (deprecation)
             return testPayable.send(2 ether);
         }
 

docs/contracts/inheritance.rst

@@ -377,8 +377,8 @@ of the variable:
 
 .. _modifier-overriding:
 
-Modifier Overriding
-===================
+Modifier Overriding (deprecated)
+================================
 
 Function modifiers can override each other. This works in the same way as
 :ref:`function overriding <function-overriding>` (except that there is no overloading for modifiers). The
@@ -392,6 +392,7 @@ and the ``override`` keyword must be used in the overriding modifier:
 
     contract Base
     {
+        // This will report a warning (deprecation)
         modifier foo() virtual {_;}
     }
 
@@ -411,11 +412,13 @@ explicitly:
 
     contract Base1
     {
+        // This will report a warning (deprecation)
         modifier foo() virtual {_;}
     }
 
     contract Base2
     {
+        // This will report a warning (deprecation)
         modifier foo() virtual {_;}
     }
 
@@ -424,6 +427,8 @@ explicitly:
         modifier foo() override(Base1, Base2) {_;}
     }
 
+.. warning::
+    ``virtual`` modifiers are deprecated and scheduled for removal in the next breaking version (0.9).
 
 
 .. index:: ! constructor

docs/control-structures.rst

@@ -692,17 +692,19 @@ and ``assert`` for internal error checking.
     :force:
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >=0.5.0 <0.9.0;
+    pragma solidity >=0.6.2 <0.9.0;
 
     contract Sharer {
         function sendHalf(address payable addr) public payable returns (uint balance) {
             require(msg.value % 2 == 0, "Even value required.");
             uint balanceBeforeTransfer = address(this).balance;
-            addr.transfer(msg.value / 2);
-            // Since transfer throws an exception on failure and
-            // cannot call back here, there should be no way for us to
-            // still have half of the Ether.
-            assert(address(this).balance == balanceBeforeTransfer - msg.value / 2);
+            (bool success, ) = addr.call{value: msg.value / 2}("");
+            // call returns false on failure, so either success is false
+            // or the balance still is half of the Ether.
+            assert(
+                !success ||
+                address(this).balance == balanceBeforeTransfer - msg.value / 2
+            );
             return address(this).balance;
         }
     }
@@ -775,7 +777,8 @@ together with ``revert`` and the equivalent ``require``:
             if (msg.sender != owner)
                 revert Unauthorized();
 
-            payable(msg.sender).transfer(address(this).balance);
+            (bool success, ) = payable(msg.sender).call{value: address(this).balance}("");
+            require(success);
         }
     }
 
@@ -914,4 +917,4 @@ in scope in the block that follows.
     out-of-gas situation and not a deliberate error condition:
     The caller always retains at least 1/64th of the gas in a call and thus
     even if the called contract goes out of gas, the caller still
-    has some gas left.
+    has some gas left.

docs/examples/blind-auction.rst

@@ -123,8 +123,9 @@ to receive their Ether - contracts cannot activate themselves.
 
                 // msg.sender is not of type `address payable` and must be
                 // explicitly converted using `payable(msg.sender)` in order
-                // use the member function `send()`.
-                if (!payable(msg.sender).send(amount)) {
+                // use the member function `call()`.
+                (bool success, ) = payable(msg.sender).call{value: amount}("");
+                if (!success) {
                     // No need to call throw here, just reset the amount owing
                     pendingReturns[msg.sender] = amount;
                     return false;
@@ -160,7 +161,8 @@ to receive their Ether - contracts cannot activate themselves.
             emit AuctionEnded(highestBidder, highestBid);
 
             // 3. Interaction
-            beneficiary.transfer(highestBid);
+            (bool success, ) = beneficiary.call{value: highestBid}("");
+            require(success);
         }
     }
 
@@ -310,7 +312,8 @@ invalid bids.
                 // the same deposit.
                 bidToCheck.blindedBid = bytes32(0);
             }
-            payable(msg.sender).transfer(refund);
+            (bool success, ) = payable(msg.sender).call{value: refund}("");
+            require(success);
         }
 
         /// Withdraw a bid that was overbid.
@@ -323,7 +326,8 @@ invalid bids.
                 // conditions -> effects -> interaction).
                 pendingReturns[msg.sender] = 0;
 
-                payable(msg.sender).transfer(amount);
+                (bool success, ) = payable(msg.sender).call{value: amount}("");
+                require(success);
             }
         }
 
@@ -336,7 +340,8 @@ invalid bids.
             if (ended) revert AuctionEndAlreadyCalled();
             emit AuctionEnded(highestBidder, highestBid);
             ended = true;
-            beneficiary.transfer(highestBid);
+            (bool success, ) = beneficiary.call{value: highestBid}("");
+            require(success);
         }
 
         // This is an "internal" function which means that it

docs/examples/micropayment.rst

@@ -185,7 +185,8 @@ The full contract
             // this recreates the message that was signed on the client
             bytes32 message = prefixed(keccak256(abi.encodePacked(msg.sender, amount, nonce, this)));
             require(recoverSigner(message, signature) == owner);
-            payable(msg.sender).transfer(amount);
+            (bool success, ) = payable(msg.sender).call{value: amount}("");
+            require(success);
         }
 
         /// freeze the contract and reclaim the leftover funds.
@@ -195,7 +196,8 @@ The full contract
         {
             require(msg.sender == owner);
             freeze();
-            payable(msg.sender).transfer(address(this).balance);
+            (bool success, ) = payable(msg.sender).call{value: address(this).balance}("");
+            require(success);
         }
 
         /// signature methods.
@@ -406,9 +408,11 @@ The full contract
             require(msg.sender == recipient);
             require(isValidSignature(amount, signature));
 
-            recipient.transfer(amount);
+            (bool success, ) = recipient.call{value: amount}("");
+            require(success);
             freeze();
-            sender.transfer(address(this).balance);
+            (success, ) = sender.call{value: address(this).balance}("");
+            require(success);
         }
 
         /// the sender can extend the expiration at any time
@@ -430,7 +434,8 @@ The full contract
         {
             require(block.timestamp >= expiration);
             freeze();
-            sender.transfer(address(this).balance);
+            (bool success, ) = sender.call{value: address(this).balance}("");
+            require(success);
         }
 
         function isValidSignature(uint256 amount, bytes memory signature)

docs/examples/safe-remote.rst

@@ -97,7 +97,8 @@ you can use state machine-like constructs inside a contract.
             // reentrancy-safe, because it is the
             // last call in this function and we
             // already changed the state.
-            seller.transfer(address(this).balance);
+            (bool success, ) = seller.call{value: address(this).balance}("");
+            require(success);
         }
 
         /// Confirm the purchase as buyer.
@@ -128,7 +129,8 @@ you can use state machine-like constructs inside a contract.
             // can call in again here.
             state = State.Release;
 
-            buyer.transfer(value);
+            (bool success, ) = buyer.call{value: value}("");
+            require(success);
         }
 
         /// This function refunds the seller, i.e.
@@ -144,6 +146,7 @@ you can use state machine-like constructs inside a contract.
             // can call in again here.
             state = State.Inactive;
 
-            seller.transfer(3 * value);
+            (bool success, ) = seller.call{value: 3 * value}("");
+            require(success);
         }
     }

docs/layout-of-source-files.rst

@@ -103,10 +103,13 @@ select between the two implementations of the ABI encoder and decoder.
 The new ABI coder (v2) is able to encode and decode arbitrarily nested
 arrays and structs. Apart from supporting more types, it involves more extensive
 validation and safety checks, which may result in higher gas costs, but also heightened
-security. It is considered
-non-experimental as of Solidity 0.6.0 and it is enabled by default starting
+security.
+It is considered non-experimental as of Solidity 0.6.0 and it is enabled by default starting
 with Solidity 0.8.0. The old ABI coder can still be selected using ``pragma abicoder v1;``.
 
+.. warning::
+  The ABI coder v1 is deprecated and scheduled for removal in the next breaking version (0.9).
+
 The set of types supported by the new encoder is a strict superset of
 the ones supported by the old one. Contracts that use it can interact with ones
 that do not without limitations. The reverse is possible only as long as the

docs/security-considerations.rst

@@ -65,6 +65,7 @@ To give an example, the following code contains a bug (it is just a snippet and
         mapping(address => uint) shares;
         /// Withdraw your share.
         function withdraw() public {
+        // This will report a warning (deprecation)
             if (payable(msg.sender).send(shares[msg.sender]))
                 shares[msg.sender] = 0;
         }
@@ -109,6 +110,7 @@ To avoid reentrancy, you can use the Checks-Effects-Interactions pattern as demo
         function withdraw() public {
             uint share = shares[msg.sender];
             shares[msg.sender] = 0;
+            // This will report a warning (deprecation)
             payable(msg.sender).transfer(share);
         }
     }
@@ -255,6 +257,7 @@ Let's say you have a wallet contract like this:
         function transferTo(address payable dest, uint amount) public {
             // THE BUG IS RIGHT HERE, you must use msg.sender instead of tx.origin
             require(tx.origin == owner);
+            // This will report a warning (deprecation)
             dest.transfer(amount);
         }
     }