Merge pull request ethereum#14803 from ethereum/mehtavishwa30-patch-1

Clean up docs to with regards to changes in SELFDESTRUCT opcode

Author: cameel

docs/cheatsheet.rst

@@ -118,7 +118,7 @@ Contract-related
 
 - ``this`` (current contract's type): the current contract, explicitly convertible to ``address`` or ``address payable``
 - ``super``: a contract one level higher in the inheritance hierarchy
-- ``selfdestruct(address payable recipient)``: destroy the current contract, sending its funds to the given address
+- ``selfdestruct(address payable recipient)``: send all funds to the given address and (only on EVMs before Cancun or when invoked within the transaction creating the contract) destroy the contract.
 
 .. index:: type;name, type;creationCode, type;runtimeCode, type;interfaceId, type;min, type;max
 

docs/contracts/function-modifiers.rst

@@ -19,7 +19,6 @@ if they are marked ``virtual``. For details, please see
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.1 <0.9.0;
-    // This will report a warning due to deprecated selfdestruct
 
     contract owned {
         constructor() { owner = payable(msg.sender); }
@@ -41,16 +40,6 @@ if they are marked ``virtual``. For details, please see
         }
     }
 
-    contract destructible is owned {
-        // This contract inherits the `onlyOwner` modifier from
-        // `owned` and applies it to the `destroy` function, which
-        // causes that calls to `destroy` only have an effect if
-        // they are made by the stored owner.
-        function destroy() public onlyOwner {
-            selfdestruct(owner);
-        }
-    }
-
     contract priced {
         // Modifiers can receive arguments:
         modifier costs(uint price) {
@@ -60,7 +49,7 @@ if they are marked ``virtual``. For details, please see
         }
     }
 
-    contract Register is priced, destructible {
+    contract Register is priced, owned {
         mapping(address => bool) registeredAddresses;
         uint price;
 
@@ -73,6 +62,9 @@ if they are marked ``virtual``. For details, please see
             registeredAddresses[msg.sender] = true;
         }
 
+        // This contract inherits the `onlyOwner` modifier from
+        // the `owned` contract. As a result, calls to `changePrice` will
+        // only take effect if they are made by the stored owner.
         function changePrice(uint price_) public onlyOwner {
             price = price_;
         }

docs/contracts/inheritance.rst

@@ -40,27 +40,27 @@ Details are given in the following example.
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.0 <0.9.0;
-    // This will report a warning due to deprecated selfdestruct
 
     contract Owned {
-        constructor() { owner = payable(msg.sender); }
         address payable owner;
+        constructor() { owner = payable(msg.sender); }
     }
 
-
     // Use `is` to derive from another contract. Derived
     // contracts can access all non-private members including
     // internal functions and state variables. These cannot be
     // accessed externally via `this`, though.
-    contract Destructible is Owned {
+    contract Emittable is Owned {
+        event Emitted();
+
         // The keyword `virtual` means that the function can change
         // its behavior in derived classes ("overriding").
-        function destroy() virtual public {
-            if (msg.sender == owner) selfdestruct(owner);
+        function emitEvent() virtual public {
+            if (msg.sender == owner)
+                emit Emitted();
         }
     }
 
-
     // These abstract contracts are only provided to make the
     // interface known to the compiler. Note the function
     // without body. If a contract does not implement all
@@ -69,37 +69,35 @@ Details are given in the following example.
         function lookup(uint id) public virtual returns (address adr);
     }
 
-
     abstract contract NameReg {
         function register(bytes32 name) public virtual;
         function unregister() public virtual;
     }
 
-
     // Multiple inheritance is possible. Note that `Owned` is
-    // also a base class of `Destructible`, yet there is only a single
+    // also a base class of `Emittable`, yet there is only a single
     // instance of `Owned` (as for virtual inheritance in C++).
-    contract Named is Owned, Destructible {
+    contract Named is Owned, Emittable {
         constructor(bytes32 name) {
             Config config = Config(0xD5f9D8D94886E70b06E474c3fB14Fd43E2f23970);
             NameReg(config.lookup(1)).register(name);
         }
 
         // Functions can be overridden by another function with the same name and
-        // the same number/types of inputs.  If the overriding function has different
+        // the same number/types of inputs. If the overriding function has different
         // types of output parameters, that causes an error.
         // Both local and message-based function calls take these overrides
         // into account.
         // If you want the function to override, you need to use the
         // `override` keyword. You need to specify the `virtual` keyword again
         // if you want this function to be overridden again.
-        function destroy() public virtual override {
+        function emitEvent() public virtual override {
             if (msg.sender == owner) {
                 Config config = Config(0xD5f9D8D94886E70b06E474c3fB14Fd43E2f23970);
                 NameReg(config.lookup(1)).unregister();
                 // It is still possible to call a specific
                 // overridden function.
-                Destructible.destroy();
+                Emittable.emitEvent();
             }
         }
     }
@@ -108,93 +106,132 @@ Details are given in the following example.
     // If a constructor takes an argument, it needs to be
     // provided in the header or modifier-invocation-style at
     // the constructor of the derived contract (see below).
-    contract PriceFeed is Owned, Destructible, Named("GoldFeed") {
+    contract PriceFeed is Owned, Emittable, Named("GoldFeed") {
+        uint info;
+
         function updateInfo(uint newInfo) public {
             if (msg.sender == owner) info = newInfo;
         }
 
         // Here, we only specify `override` and not `virtual`.
         // This means that contracts deriving from `PriceFeed`
-        // cannot change the behavior of `destroy` anymore.
-        function destroy() public override(Destructible, Named) { Named.destroy(); }
+        // cannot change the behavior of `emitEvent` anymore.
+        function emitEvent() public override(Emittable, Named) { Named.emitEvent(); }
         function get() public view returns(uint r) { return info; }
-
-        uint info;
     }
 
-Note that above, we call ``Destructible.destroy()`` to "forward" the
-destruction request. The way this is done is problematic, as
+Note that above, we call ``Emittable.emitEvent()`` to "forward" the
+emit event request. The way this is done is problematic, as
 seen in the following example:
 
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.0 <0.9.0;
-    // This will report a warning due to deprecated selfdestruct
 
-    contract owned {
-        constructor() { owner = payable(msg.sender); }
+    contract Owned {
         address payable owner;
+        constructor() { owner = payable(msg.sender); }
     }
 
-    contract Destructible is owned {
-        function destroy() public virtual {
-            if (msg.sender == owner) selfdestruct(owner);
+    contract Emittable is Owned {
+        event Emitted();
+
+        function emitEvent() virtual public {
+            if (msg.sender == owner) {
+                emit Emitted();
+            }
         }
     }
 
-    contract Base1 is Destructible {
-        function destroy() public virtual override { /* do cleanup 1 */ Destructible.destroy(); }
+    contract Base1 is Emittable {
+        event Base1Emitted();
+        function emitEvent() public virtual override {
+            /* Here, we emit an event to simulate some Base1 logic */
+            emit Base1Emitted();
+            Emittable.emitEvent();
+        }
     }
 
-    contract Base2 is Destructible {
-        function destroy() public virtual override { /* do cleanup 2 */ Destructible.destroy(); }
+    contract Base2 is Emittable {
+        event Base2Emitted();
+        function emitEvent() public virtual override {
+            /* Here, we emit an event to simulate some Base2 logic */
+            emit Base2Emitted();
+            Emittable.emitEvent();
+        }
     }
 
     contract Final is Base1, Base2 {
-        function destroy() public override(Base1, Base2) { Base2.destroy(); }
+        event FinalEmitted();
+        function emitEvent() public override(Base1, Base2) {
+            /* Here, we emit an event to simulate some Final logic */
+            emit FinalEmitted();
+            Base2.emitEvent();
+        }
     }
 
-A call to ``Final.destroy()`` will call ``Base2.destroy`` because we specify it
+A call to ``Final.emitEvent()`` will call ``Base2.emitEvent`` because we specify it
 explicitly in the final override, but this function will bypass
-``Base1.destroy``. The way around this is to use ``super``:
+``Base1.emitEvent``, resulting in the following sequence of events:
+``FinalEmitted -> Base2Emitted -> Emitted``, instead of the expected sequence:
+``FinalEmitted -> Base2Emitted -> Base1Emitted -> Emitted``.
+The way around this is to use ``super``:
 
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.0 <0.9.0;
-    // This will report a warning due to deprecated selfdestruct
 
-    contract owned {
-        constructor() { owner = payable(msg.sender); }
+    contract Owned {
         address payable owner;
+        constructor() { owner = payable(msg.sender); }
     }
 
-    contract Destructible is owned {
-        function destroy() virtual public {
-            if (msg.sender == owner) selfdestruct(owner);
+    contract Emittable is Owned {
+        event Emitted();
+
+        function emitEvent() virtual public {
+            if (msg.sender == owner) {
+                emit Emitted();
+            }
         }
     }
 
-    contract Base1 is Destructible {
-        function destroy() public virtual override { /* do cleanup 1 */ super.destroy(); }
+    contract Base1 is Emittable {
+        event Base1Emitted();
+        function emitEvent() public virtual override {
+            /* Here, we emit an event to simulate some Base1 logic */
+            emit Base1Emitted();
+            super.emitEvent();
+        }
     }
 
 
-    contract Base2 is Destructible {
-        function destroy() public virtual override { /* do cleanup 2 */ super.destroy(); }
+    contract Base2 is Emittable {
+        event Base2Emitted();
+        function emitEvent() public virtual override {
+            /* Here, we emit an event to simulate some Base2 logic */
+            emit Base2Emitted();
+            super.emitEvent();
+        }
     }
 
     contract Final is Base1, Base2 {
-        function destroy() public override(Base1, Base2) { super.destroy(); }
+        event FinalEmitted();
+        function emitEvent() public override(Base1, Base2) {
+            /* Here, we emit an event to simulate some Final logic */
+            emit FinalEmitted();
+            super.emitEvent();
+        }
     }
 
-If ``Base2`` calls a function of ``super``, it does not simply
+If ``Final`` calls a function of ``super``, it does not simply
 call this function on one of its base contracts.  Rather, it
 calls this function on the next base contract in the final
-inheritance graph, so it will call ``Base1.destroy()`` (note that
+inheritance graph, so it will call ``Base1.emitEvent()`` (note that
 the final inheritance sequence is -- starting with the most
-derived contract: Final, Base2, Base1, Destructible, owned).
+derived contract: Final, Base2, Base1, Emittable, Owned).
 The actual function that is called when using super is
 not known in the context of the class where it is used,
 although its type is known. This is similar for ordinary