Merge pull request #721 from lukso-network/docs/qa-141-l01

docs: add LSP17 Natspec about `msg.value` not forwarded to extension

contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol

@@ -711,11 +711,22 @@ abstract contract LSP0ERC725AccountCore is
     /**
      * @dev Forwards the call to an extension mapped to a function selector.
      *
-     * Calls {_getExtension} to get the address of the extension mapped to the function selector being called on the account. If there is no extension, the `address(0)` will be returned.
+     * Calls {_getExtension} to get the address of the extension mapped to the function selector being
+     * called on the account. If there is no extension, the `address(0)` will be returned.
      *
-     * Reverts if there is no extension for the function being called, except for the bytes4(0) function selector, which passes even if there is no extension for it.
+     * Reverts if there is no extension for the function being called, except for the `bytes4(0)` function selector, which passes even if there is no extension for it.
      *
-     * If there is an extension for the function selector being called, it calls the extension with the CALL opcode, passing the `msg.data` appended with the 20 bytes of the `msg.sender` and 32 bytes of the `msg.value`
+     * If there is an extension for the function selector being called, it calls the extension with the
+     * `CALL` opcode, passing the `msg.data` appended with the 20 bytes of the {msg.sender} and 32 bytes of the `msg.value`.
+     *
+     * @custom:hint This function does not forward to the extension contract the `msg.value` received by the contract that inherits `LSP17Extendable`.
+     * If you would like to forward the `msg.value` to the extension contract, you can override the code of this internal function as follow:
+     *
+     * ```solidity
+     * (bool success, bytes memory result) = extension.call{value: msg.value}(
+     *     abi.encodePacked(callData, msg.sender, msg.value)
+     * );
+     * ```
      */
     function _fallbackLSP17Extendable(
         bytes calldata callData

contracts/LSP17ContractExtension/LSP17Extendable.sol

@@ -70,18 +70,21 @@ abstract contract LSP17Extendable is ERC165 {
      * @dev Forwards the call to an extension mapped to a function selector.
      *
      * Calls {_getExtension} to get the address of the extension mapped to the function selector being
-     * called on the account. If there is no extension, the address(0) will be returned.
+     * called on the account. If there is no extension, the `address(0)` will be returned.
      *
      * Reverts if there is no extension for the function being called.
      *
      * If there is an extension for the function selector being called, it calls the extension with the
-     * CALL opcode, passing the {msg.data} appended with the 20 bytes of the {msg.sender} and
-     * 32 bytes of the {msg.value}
+     * `CALL` opcode, passing the `msg.data` appended with the 20 bytes of the {msg.sender} and 32 bytes of the `msg.value`.
      *
-     * Because the function uses assembly {return()/revert()} to terminate the call, it cannot be
-     * called before other codes in fallback().
+     * @custom:hint This function does not forward to the extension contract the `msg.value` received by the contract that inherits `LSP17Extendable`.
+     * If you would like to forward the `msg.value` to the extension contract, you can override the code of this internal function as follow:
      *
-     * Otherwise, the codes after _fallbackLSP17Extendable() may never be reached.
+     * ```solidity
+     * (bool success, bytes memory result) = extension.call{value: msg.value}(
+     *     abi.encodePacked(callData, msg.sender, msg.value)
+     * );
+     * ```
      */
     function _fallbackLSP17Extendable(
         bytes calldata callData

contracts/LSP17ContractExtension/LSP17Extension.sol

@@ -26,8 +26,8 @@ abstract contract LSP17Extension is ERC165 {
     }
 
     /**
-     * @dev Returns the original msg.data passed to the extendable contract
-     * without the appended msg.sender and msg.value
+     * @dev Returns the original `msg.data` passed to the extendable contract
+     * without the appended `msg.sender` and `msg.value`.
      */
     function _extendableMsgData()
         internal
@@ -39,7 +39,7 @@ abstract contract LSP17Extension is ERC165 {
     }
 
     /**
-     * @dev Returns the original msg.sender calling the extendable contract
+     * @dev Returns the original `msg.sender` calling the extendable contract.
      */
     function _extendableMsgSender() internal view virtual returns (address) {
         return
@@ -49,7 +49,7 @@ abstract contract LSP17Extension is ERC165 {
     }
 
     /**
-     * @dev Returns the original msg.value sent to the extendable contract
+     * @dev Returns the original `msg.value` sent to the extendable contract.
      */
     function _extendableMsgValue() internal view virtual returns (uint256) {
         return uint256(bytes32(msg.data[msg.data.length - 32:]));

contracts/LSP7DigitalAsset/LSP7DigitalAsset.sol

@@ -103,10 +103,8 @@ abstract contract LSP7DigitalAsset is
      * CALL opcode, passing the {msg.data} appended with the 20 bytes of the {msg.sender} and
      * 32 bytes of the {msg.value}
      *
-     * Because the function uses assembly {return()/revert()} to terminate the call, it cannot be
-     * called before other codes in fallback().
-     *
-     * Otherwise, the codes after _fallbackLSP17Extendable() may never be reached.
+     * @custom:info The LSP7 Token contract should not hold any native tokens. Any native tokens received by the contract
+     * will be forwarded to the extension address mapped to the selector from `msg.sig`.
      */
     function _fallbackLSP17Extendable(
         bytes calldata callData

contracts/LSP7DigitalAsset/LSP7DigitalAssetInitAbstract.sol

@@ -98,10 +98,8 @@ abstract contract LSP7DigitalAssetInitAbstract is
      * CALL opcode, passing the {msg.data} appended with the 20 bytes of the {msg.sender} and
      * 32 bytes of the {msg.value}
      *
-     * Because the function uses assembly {return()/revert()} to terminate the call, it cannot be
-     * called before other codes in fallback().
-     *
-     * Otherwise, the codes after _fallbackLSP17Extendable() may never be reached.
+     * @custom:info The LSP7 Token contract should not hold any native tokens. Any native tokens received by the contract
+     * will be forwarded to the extension address mapped to the selector from `msg.sig`.
      */
     function _fallbackLSP17Extendable(
         bytes calldata callData

contracts/LSP8IdentifiableDigitalAsset/LSP8IdentifiableDigitalAsset.sol

@@ -104,10 +104,8 @@ abstract contract LSP8IdentifiableDigitalAsset is
      * CALL opcode, passing the {msg.data} appended with the 20 bytes of the {msg.sender} and
      * 32 bytes of the {msg.value}
      *
-     * Because the function uses assembly {return()/revert()} to terminate the call, it cannot be
-     * called before other codes in fallback().
-     *
-     * Otherwise, the codes after _fallbackLSP17Extendable() may never be reached.
+     * @custom:info The LSP8 Token contract should not hold any native tokens. Any native tokens received by the contract
+     * will be forwarded to the extension address mapped to the selector from `msg.sig`.
      */
     function _fallbackLSP17Extendable(
         bytes calldata callData

contracts/LSP8IdentifiableDigitalAsset/LSP8IdentifiableDigitalAssetInitAbstract.sol

@@ -104,10 +104,8 @@ abstract contract LSP8IdentifiableDigitalAssetInitAbstract is
      * CALL opcode, passing the {msg.data} appended with the 20 bytes of the {msg.sender} and
      * 32 bytes of the {msg.value}
      *
-     * Because the function uses assembly {return()/revert()} to terminate the call, it cannot be
-     * called before other codes in fallback().
-     *
-     * Otherwise, the codes after _fallbackLSP17Extendable() may never be reached.
+     * @custom:info The LSP8 Token contract should not hold any native tokens. Any native tokens received by the contract
+     * will be forwarded to the extension address mapped to the selector from `msg.sig`.
      */
     function _fallbackLSP17Extendable(
         bytes calldata callData

contracts/LSP9Vault/LSP9VaultCore.sol

@@ -505,11 +505,22 @@ contract LSP9VaultCore is
     /**
      * @dev Forwards the call to an extension mapped to a function selector.
      *
-     * Calls {_getExtension} to get the address of the extension mapped to the function selector being called on the account. If there is no extension, the `address(0)` will be returned.
+     * Calls {_getExtension} to get the address of the extension mapped to the function selector being
+     * called on the account. If there is no extension, the `address(0)` will be returned.
      *
-     * Reverts if there is no extension for the function being called, except for the bytes4(0) function selector, which passes even if there is no extension for it.
+     * Reverts if there is no extension for the function being called, except for the `bytes4(0)` function selector, which passes even if there is no extension for it.
      *
-     * If there is an extension for the function selector being called, it calls the extension with the CALL opcode, passing the `msg.data` appended with the 20 bytes of the `msg.sender` and 32 bytes of the `msg.value`
+     * If there is an extension for the function selector being called, it calls the extension with the
+     * `CALL` opcode, passing the `msg.data` appended with the 20 bytes of the {msg.sender} and 32 bytes of the `msg.value`.
+     *
+     * @custom:hint This function does not forward to the extension contract the `msg.value` received by the contract that inherits `LSP17Extendable`.
+     * If you would like to forward the `msg.value` to the extension contract, you can override the code of this internal function as follow:
+     *
+     * ```solidity
+     * (bool success, bytes memory result) = extension.call{value: msg.value}(
+     *     abi.encodePacked(callData, msg.sender, msg.value)
+     * );
+     * ```
      */
     function _fallbackLSP17Extendable(
         bytes calldata callData

docs/contracts/LSP0ERC725Account/LSP0ERC725Account.md

@@ -1149,16 +1149,31 @@ Returns the extension address stored under the following data key:
 
 ### \_fallbackLSP17Extendable
 
+:::tip Hint
+
+This function does not forward to the extension contract the `msg.value` received by the contract that inherits `LSP17Extendable`.
+If you would like to forward the `msg.value` to the extension contract, you can override the code of this internal function as follow:
+
+```solidity
+(bool success, bytes memory result) = extension.call{value: msg.value}(
+    abi.encodePacked(callData, msg.sender, msg.value)
+);
+```
+
+:::
+
 ```solidity
 function _fallbackLSP17Extendable(
   bytes callData
 ) internal nonpayable returns (bytes);
 ```
 
 Forwards the call to an extension mapped to a function selector.
-Calls [`_getExtension`](#_getextension) to get the address of the extension mapped to the function selector being called on the account. If there is no extension, the `address(0)` will be returned.
-Reverts if there is no extension for the function being called, except for the bytes4(0) function selector, which passes even if there is no extension for it.
-If there is an extension for the function selector being called, it calls the extension with the CALL opcode, passing the `msg.data` appended with the 20 bytes of the `msg.sender` and 32 bytes of the `msg.value`
+Calls [`_getExtension`](#_getextension) to get the address of the extension mapped to the function selector being
+called on the account. If there is no extension, the `address(0)` will be returned.
+Reverts if there is no extension for the function being called, except for the `bytes4(0)` function selector, which passes even if there is no extension for it.
+If there is an extension for the function selector being called, it calls the extension with the
+`CALL` opcode, passing the `msg.data` appended with the 20 bytes of the [`msg.sender`](#msg.sender) and 32 bytes of the `msg.value`.
 
 <br/>
 

docs/contracts/LSP17ContractExtension/LSP17Extendable.md

@@ -93,6 +93,19 @@ Up to the implementor contract to return an extension based on a function select
 
 ### \_fallbackLSP17Extendable
 
+:::tip Hint
+
+This function does not forward to the extension contract the `msg.value` received by the contract that inherits `LSP17Extendable`.
+If you would like to forward the `msg.value` to the extension contract, you can override the code of this internal function as follow:
+
+```solidity
+(bool success, bytes memory result) = extension.call{value: msg.value}(
+    abi.encodePacked(callData, msg.sender, msg.value)
+);
+```
+
+:::
+
 ```solidity
 function _fallbackLSP17Extendable(
   bytes callData
@@ -101,13 +114,9 @@ function _fallbackLSP17Extendable(
 
 Forwards the call to an extension mapped to a function selector.
 Calls [`_getExtension`](#_getextension) to get the address of the extension mapped to the function selector being
-called on the account. If there is no extension, the address(0) will be returned.
+called on the account. If there is no extension, the `address(0)` will be returned.
 Reverts if there is no extension for the function being called.
 If there is an extension for the function selector being called, it calls the extension with the
-CALL opcode, passing the [`msg.data`](#msg.data) appended with the 20 bytes of the [`msg.sender`](#msg.sender) and
-32 bytes of the [`msg.value`](#msg.value)
-Because the function uses assembly [`return()/revert()`](#return) to terminate the call, it cannot be
-called before other codes in fallback().
-Otherwise, the codes after \_fallbackLSP17Extendable() may never be reached.
+`CALL` opcode, passing the `msg.data` appended with the 20 bytes of the [`msg.sender`](#msg.sender) and 32 bytes of the `msg.value`.
 
 <br/>

docs/contracts/LSP17ContractExtension/LSP17Extension.md

@@ -66,8 +66,8 @@ Internal functions cannot be called externally, whether from other smart contrac
 function _extendableMsgData() internal view returns (bytes);
 ```
 
-Returns the original msg.data passed to the extendable contract
-without the appended msg.sender and msg.value
+Returns the original `msg.data` passed to the extendable contract
+without the appended `msg.sender` and `msg.value`.
 
 <br/>
 
@@ -77,7 +77,7 @@ without the appended msg.sender and msg.value
 function _extendableMsgSender() internal view returns (address);
 ```
 
-Returns the original msg.sender calling the extendable contract
+Returns the original `msg.sender` calling the extendable contract.
 
 <br/>
 
@@ -87,6 +87,6 @@ Returns the original msg.sender calling the extendable contract
 function _extendableMsgValue() internal view returns (uint256);
 ```
 
-Returns the original msg.value sent to the extendable contract
+Returns the original `msg.value` sent to the extendable contract.
 
 <br/>

docs/contracts/LSP7DigitalAsset/LSP7DigitalAsset.md

@@ -1034,6 +1034,13 @@ Returns the extension address stored under the following data key:
 
 ### \_fallbackLSP17Extendable
 
+:::info
+
+The LSP7 Token contract should not hold any native tokens. Any native tokens received by the contract
+will be forwarded to the extension address mapped to the selector from `msg.sig`.
+
+:::
+
 ```solidity
 function _fallbackLSP17Extendable(
   bytes callData
@@ -1047,9 +1054,6 @@ Reverts if there is no extension for the function being called.
 If there is an extension for the function selector being called, it calls the extension with the
 CALL opcode, passing the [`msg.data`](#msg.data) appended with the 20 bytes of the [`msg.sender`](#msg.sender) and
 32 bytes of the [`msg.value`](#msg.value)
-Because the function uses assembly [`return()/revert()`](#return) to terminate the call, it cannot be
-called before other codes in fallback().
-Otherwise, the codes after \_fallbackLSP17Extendable() may never be reached.
 
 <br/>
 

docs/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.md

@@ -1059,6 +1059,13 @@ Returns the extension address stored under the following data key:
 
 ### \_fallbackLSP17Extendable
 
+:::info
+
+The LSP7 Token contract should not hold any native tokens. Any native tokens received by the contract
+will be forwarded to the extension address mapped to the selector from `msg.sig`.
+
+:::
+
 ```solidity
 function _fallbackLSP17Extendable(
   bytes callData
@@ -1072,9 +1079,6 @@ Reverts if there is no extension for the function being called.
 If there is an extension for the function selector being called, it calls the extension with the
 CALL opcode, passing the [`msg.data`](#msg.data) appended with the 20 bytes of the [`msg.sender`](#msg.sender) and
 32 bytes of the [`msg.value`](#msg.value)
-Because the function uses assembly [`return()/revert()`](#return) to terminate the call, it cannot be
-called before other codes in fallback().
-Otherwise, the codes after \_fallbackLSP17Extendable() may never be reached.
 
 <br/>
 

docs/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.md

@@ -1043,6 +1043,13 @@ Returns the extension address stored under the following data key:
 
 ### \_fallbackLSP17Extendable
 
+:::info
+
+The LSP7 Token contract should not hold any native tokens. Any native tokens received by the contract
+will be forwarded to the extension address mapped to the selector from `msg.sig`.
+
+:::
+
 ```solidity
 function _fallbackLSP17Extendable(
   bytes callData
@@ -1056,9 +1063,6 @@ Reverts if there is no extension for the function being called.
 If there is an extension for the function selector being called, it calls the extension with the
 CALL opcode, passing the [`msg.data`](#msg.data) appended with the 20 bytes of the [`msg.sender`](#msg.sender) and
 32 bytes of the [`msg.value`](#msg.value)
-Because the function uses assembly [`return()/revert()`](#return) to terminate the call, it cannot be
-called before other codes in fallback().
-Otherwise, the codes after \_fallbackLSP17Extendable() may never be reached.
 
 <br/>
 

docs/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.md

@@ -1150,6 +1150,13 @@ Returns the extension address stored under the following data key:
 
 ### \_fallbackLSP17Extendable
 
+:::info
+
+The LSP7 Token contract should not hold any native tokens. Any native tokens received by the contract
+will be forwarded to the extension address mapped to the selector from `msg.sig`.
+
+:::
+
 ```solidity
 function _fallbackLSP17Extendable(
   bytes callData
@@ -1163,9 +1170,6 @@ Reverts if there is no extension for the function being called.
 If there is an extension for the function selector being called, it calls the extension with the
 CALL opcode, passing the [`msg.data`](#msg.data) appended with the 20 bytes of the [`msg.sender`](#msg.sender) and
 32 bytes of the [`msg.value`](#msg.value)
-Because the function uses assembly [`return()/revert()`](#return) to terminate the call, it cannot be
-called before other codes in fallback().
-Otherwise, the codes after \_fallbackLSP17Extendable() may never be reached.
 
 <br/>
 

docs/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.md

@@ -1188,6 +1188,13 @@ Returns the extension address stored under the following data key:
 
 ### \_fallbackLSP17Extendable
 
+:::info
+
+The LSP7 Token contract should not hold any native tokens. Any native tokens received by the contract
+will be forwarded to the extension address mapped to the selector from `msg.sig`.
+
+:::
+
 ```solidity
 function _fallbackLSP17Extendable(
   bytes callData
@@ -1201,9 +1208,6 @@ Reverts if there is no extension for the function being called.
 If there is an extension for the function selector being called, it calls the extension with the
 CALL opcode, passing the [`msg.data`](#msg.data) appended with the 20 bytes of the [`msg.sender`](#msg.sender) and
 32 bytes of the [`msg.value`](#msg.value)
-Because the function uses assembly [`return()/revert()`](#return) to terminate the call, it cannot be
-called before other codes in fallback().
-Otherwise, the codes after \_fallbackLSP17Extendable() may never be reached.
 
 <br/>