Update docs

matheusaaguiar · matheusaaguiar · commit dbeb8762388e · 2025-12-02T20:11:59.000-03:00
diff --git a/docs/assembly.rst b/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 is deprecated and scheduled for removal.
+    In new code targeting recent compilers, use the assembly block annotation.
 
 Advanced Safe Use of Memory
 ---------------------------
diff --git a/docs/cheatsheet.rst b/docs/cheatsheet.rst
@@ -53,8 +53,8 @@ Members of ``address``
 - ``<address>.staticcall(bytes memory) returns (bool, bytes memory)``: issue low-level ``STATICCALL`` with the given payload,
   returns success condition and return data
 - ``<address payable>.send(uint256 amount) returns (bool)``: send given amount of Wei to :ref:`address`,
-  returns ``false`` on failure
-- ``<address payable>.transfer(uint256 amount)``: send given amount of Wei to :ref:`address`, throws on failure
+  returns ``false`` on failure (deprecated)
+- ``<address payable>.transfer(uint256 amount)``: send given amount of Wei to :ref:`address`, throws on failure (deprecated)
 
 .. index:: blockhash, blobhash, block, block;basefee, block;blobbasefee, block;chainid, block;coinbase, block;difficulty, block;gaslimit, block;number, block;prevrandao, block;timestamp
 .. index:: gasleft, msg;data, msg;sender, msg;sig, msg;value, tx;gasprice, tx;origin
diff --git a/docs/common-patterns.rst b/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)
diff --git a/docs/contracts/functions.rst b/docs/contracts/functions.rst
@@ -310,6 +310,10 @@ will consume more gas than the 2300 gas stipend:
 - Calling an external function which consumes a large amount of gas
 - Sending Ether
 
+.. warning::
+    ``send()`` and ``transfer()`` are deprecated and scheduled for removal.
+    See the section on :ref:`send <send-address-member>` and :ref:`transfer <balance-transfer-address-members>` for more information.
+
 .. warning::
     When Ether is sent directly to a contract (without a function call, i.e. sender uses ``send`` or ``transfer``)
     but the receiving contract does not define a receive Ether function or a payable fallback function,
@@ -319,7 +323,6 @@ 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::
     A contract without a receive Ether function can receive Ether as a
     recipient of a *coinbase transaction* (aka *miner block reward*)
@@ -440,6 +443,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);
         }
 
diff --git a/docs/contracts/inheritance.rst b/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.
 
 
 .. index:: ! constructor
diff --git a/docs/control-structures.rst b/docs/control-structures.rst
@@ -692,16 +692,16 @@ 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.
+            (bool success, ) = addr.call{value: msg.value / 2}("");
+            require(success);
+            // Since require will stop execution and revert if success is false,
+            // there should be no way for us to still have half of the Ether.
             assert(address(this).balance == balanceBeforeTransfer - msg.value / 2);
             return address(this).balance;
         }
@@ -775,7 +775,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 +915,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.
diff --git a/docs/examples/blind-auction.rst b/docs/examples/blind-auction.rst
@@ -118,13 +118,14 @@ to receive their Ether - contracts cannot activate themselves.
             if (amount > 0) {
                 // It is important to set this to zero because the recipient
                 // can call this function again as part of the receiving call
-                // before `send` returns.
+                // before `call` returns.
                 pendingReturns[msg.sender] = 0;
 
                 // 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.
@@ -319,11 +322,12 @@ invalid bids.
             if (amount > 0) {
                 // It is important to set this to zero because the recipient
                 // can call this function again as part of the receiving call
-                // before `transfer` returns (see the remark above about
+                // before `call` returns (see the remark above about
                 // 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
diff --git a/docs/examples/micropayment.rst b/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)
diff --git a/docs/examples/safe-remote.rst b/docs/examples/safe-remote.rst
@@ -93,11 +93,12 @@ you can use state machine-like constructs inside a contract.
         {
             emit Aborted();
             state = State.Inactive;
-            // We use transfer here directly. It is
+            // We use call here directly. It is
             // 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.
@@ -124,11 +125,12 @@ you can use state machine-like constructs inside a contract.
         {
             emit ItemReceived();
             // It is important to change the state first because
-            // otherwise, the contracts called using `send` below
+            // otherwise, the contracts called using `call` below
             // 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.
@@ -140,10 +142,11 @@ you can use state machine-like constructs inside a contract.
         {
             emit SellerRefunded();
             // It is important to change the state first because
-            // otherwise, the contracts called using `send` below
+            // otherwise, the contracts called using `call` below
             // can call in again here.
             state = State.Inactive;
 
-            seller.transfer(3 * value);
+            (bool success, ) = seller.call{value: 3 * value}("");
+            require(success);
         }
     }
diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst
@@ -103,10 +103,14 @@ 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.
+  Use ABI coder v2 instead.
+
 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
diff --git a/docs/security-considerations.rst b/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;
         }
@@ -76,7 +77,7 @@ Ether transfer can always include code execution,
 so the recipient could be a contract that calls back into ``withdraw``.
 This would let it get multiple refunds and, basically, retrieve all the Ether in the contract.
 In particular, the following contract will allow an attacker to refund multiple times
-as it uses ``call`` which forwards all remaining gas by default:
+as it uses ``call`` which does not limit the amount of gas that is forwarded by default:
 
 .. code-block:: solidity
 
@@ -100,7 +101,7 @@ To avoid reentrancy, you can use the Checks-Effects-Interactions pattern as demo
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >=0.6.0 <0.9.0;
+    pragma solidity >=0.6.2 <0.9.0;
 
     contract Fund {
         /// @dev Mapping of ether shares of the contract.
@@ -109,7 +110,8 @@ 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;
-            payable(msg.sender).transfer(share);
+            (bool success, ) = payable(msg.sender).call{value: share}("");
+            require(success);
         }
     }
 
@@ -158,8 +160,9 @@ Sending and Receiving Ether
   (for example in the "details" section in Remix).
 
 - There is a way to forward more gas to the receiving contract using ``addr.call{value: x}("")``.
-  This is essentially the same as ``addr.transfer(x)``, only that it forwards all remaining gas
-  and opens up the ability for the recipient to perform more expensive actions
+  This is essentially the same as ``addr.transfer(x)``, only that it forwards all remaining gas,
+  subject to additional limits imposed by some EVM versions (such as the `63/64th rule <https://eips.ethereum.org/EIPS/eip-150>`_
+  introduced by ``tangerineWhistle``), and opens up the ability for the recipient to perform more expensive actions
   (and it returns a failure code instead of automatically propagating the error).
   This might include calling back into the sending contract or other state changes you might not have thought of.
   So it allows for great flexibility for honest users but also for malicious actors.
@@ -255,6 +258,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);
         }
     }
diff --git a/docs/types/reference-types.rst b/docs/types/reference-types.rst
diff --git a/docs/types/value-types.rst b/docs/types/value-types.rst
diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst

Original file line number	Diff line number	Diff line change
`@@ -377,8 +377,8 @@ of the variable:`
`377`	`377`
`378`	`378`	`.. _modifier-overriding:`
`379`	`379`
`380`		`-Modifier Overriding`
`381`		`-===================`
	`380`	`+Modifier Overriding (deprecated)`
	`381`	`+================================`
`382`	`382`
`383`	`383`	`Function modifiers can override each other. This works in the same way as`
`384`	`384`	: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:
`392`	`392`
`393`	`393`	`contract Base`
`394`	`394`	`{`
	`395`	`+ // This will report a warning (deprecation)`
`395`	`396`	`modifier foo() virtual {_;}`
`396`	`397`	`}`
`397`	`398`
`@@ -411,11 +412,13 @@ explicitly:`
`411`	`412`
`412`	`413`	`contract Base1`
`413`	`414`	`{`
	`415`	`+ // This will report a warning (deprecation)`
`414`	`416`	`modifier foo() virtual {_;}`
`415`	`417`	`}`
`416`	`418`
`417`	`419`	`contract Base2`
`418`	`420`	`{`
	`421`	`+ // This will report a warning (deprecation)`
`419`	`422`	`modifier foo() virtual {_;}`
`420`	`423`	`}`
`421`	`424`
`@@ -424,6 +427,8 @@ explicitly:`
`424`	`427`	`modifier foo() override(Base1, Base2) {_;}`
`425`	`428`	`}`
`426`	`429`
	`430`	`+.. warning::`
	`431`	+ ``virtual`` modifiers are deprecated and scheduled for removal.
`427`	`432`
`428`	`433`
`429`	`434`	`.. index:: ! constructor`
Original file line number	Diff line number	Diff line change
`@@ -93,11 +93,12 @@ you can use state machine-like constructs inside a contract.`
`93`	`93`	`{`
`94`	`94`	`emit Aborted();`
`95`	`95`	`state = State.Inactive;`
`96`		`- // We use transfer here directly. It is`
	`96`	`+ // We use call here directly. It is`
`97`	`97`	`// reentrancy-safe, because it is the`
`98`	`98`	`// last call in this function and we`
`99`	`99`	`// already changed the state.`
`100`		`- seller.transfer(address(this).balance);`
	`100`	`+ (bool success, ) = seller.call{value: address(this).balance}("");`
	`101`	`+ require(success);`
`101`	`102`	`}`
`102`	`103`
`103`	`104`	`/// Confirm the purchase as buyer.`
`@@ -124,11 +125,12 @@ you can use state machine-like constructs inside a contract.`
`124`	`125`	`{`
`125`	`126`	`emit ItemReceived();`
`126`	`127`	`// It is important to change the state first because`
`127`		- // otherwise, the contracts called using `send` below
	`128`	+ // otherwise, the contracts called using `call` below
`128`	`129`	`// can call in again here.`
`129`	`130`	`state = State.Release;`
`130`	`131`
`131`		`- buyer.transfer(value);`
	`132`	`+ (bool success, ) = buyer.call{value: value}("");`
	`133`	`+ require(success);`
`132`	`134`	`}`
`133`	`135`
`134`	`136`	`/// This function refunds the seller, i.e.`
`@@ -140,10 +142,11 @@ you can use state machine-like constructs inside a contract.`
`140`	`142`	`{`
`141`	`143`	`emit SellerRefunded();`
`142`	`144`	`// It is important to change the state first because`
`143`		- // otherwise, the contracts called using `send` below
	`145`	+ // otherwise, the contracts called using `call` below
`144`	`146`	`// can call in again here.`
`145`	`147`	`state = State.Inactive;`
`146`	`148`
`147`		`- seller.transfer(3 * value);`
	`149`	`+ (bool success, ) = seller.call{value: 3 * value}("");`
	`150`	`+ require(success);`
`148`	`151`	`}`
`149`	`152`	`}`