diff --git a/docs/contracts.rst b/docs/contracts.rst index aa3f8fa6c..a1a446658 100644 --- a/docs/contracts.rst +++ b/docs/contracts.rst @@ -543,9 +543,12 @@ functions match the given function identifier (or if no data was supplied at all). Furthermore, this function is executed whenever the contract receives plain -Ether (without data). In such a context, there is usually very little gas available to -the function call (to be precise, 2300 gas), so it is important to make fallback functions as cheap as -possible. +Ether (without data). Additionally, in order to receive Ether, the fallback function +must be marked ``payable``. If no such function exists, the contract cannot receive +Ether through regular transactions. + +In such a context, there is usually very little gas available to the function call (to be precise, 2300 gas), +so it is important to make fallback functions as cheap as possible. In particular, the following operations will consume more gas than the stipend provided to a fallback function: @@ -556,6 +559,10 @@ In particular, the following operations will consume more gas than the stipend p Please ensure you test your fallback function thoroughly to ensure the execution cost is less than 2300 gas before deploying a contract. +.. note:: + Even though the fallback function cannot have arguments, one can still use ``msg.data`` to retrieve + any payload supplied with the call. + .. warning:: Contracts that receive Ether directly (without a function call, i.e. using ``send`` or ``transfer``) but do not define a fallback function @@ -563,6 +570,14 @@ Please ensure you test your fallback function thoroughly to ensure the execution before Solidity v0.4.0). So if you want your contract to receive Ether, you have to implement a fallback function. +.. warning:: + 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``. + + 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 ``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). + :: pragma solidity ^0.4.0; diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst index c4de60cd9..9edfb4fb9 100644 --- a/docs/frequently-asked-questions.rst +++ b/docs/frequently-asked-questions.rst @@ -137,37 +137,6 @@ Enums are not supported by the ABI, they are just supported by Solidity. You have to do the mapping yourself for now, we might provide some help later. -What is the deal with ``function () { ... }`` inside Solidity contracts? How can a function not have a name? -============================================================================================================ - -This function is called "fallback function" and it -is called when someone just sent Ether to the contract without -providing any data or if someone messed up the types so that they tried to -call a function that does not exist. - -The default behaviour (if no fallback function is explicitly given) in -these situations is to throw an exception. - -If the contract is meant to receive Ether with simple transfers, you -should implement the fallback function as - -``function() payable { }`` - -Another use of the fallback function is to e.g. register that your -contract received ether by using an event. - -*Attention*: If you implement the fallback function take care that it uses as -little gas as possible, because ``send()`` will only supply a limited amount. - -Is it possible to pass arguments to the fallback function? -========================================================== - -The fallback function cannot take parameters. - -Under special circumstances, you can send data. If you take care -that none of the other functions is invoked, you can access the data -by ``msg.data``. - Can state variables be initialized in-line? ===========================================