Solidity

Special Functions for Receiving Calls and Ether

A contract can declare two special functions that have no name (they are not called by name) and are triggered automatically: receive() for plain Ether transfers and fallback() for calls that do not match any function. Since Solidity 0.6.0 these replace the old unnamed function() payable syntax.

receive()

receive() external payable {
    // runs when Ether is sent with EMPTY calldata
}

• Called for plain Ether transfers – calls with empty calldata, such as .send(), .transfer() or sending Ether from a wallet.
• Must be external payable, takes no arguments and returns nothing.
• A contract can have at most one receive function.

fallback()

fallback() external [payable] {
    // runs when no function matches the call
}
// or, to read the input and return data:
fallback(bytes calldata input) external [payable] returns (bytes memory output) { }

• Executed when a call does not match any function signature, or when Ether is sent with empty calldata and no receive() exists.
• Must be external; it is declared with fallback(), either with no parameters or with (bytes calldata) and returning (bytes memory).
• Must be marked payable if it should accept Ether; otherwise Ether sent to it is rejected.
• Can be defined only once per contract.

Which Function Runs?

Key Points

• 2300 gas stipend: when Ether is sent with transfer() or send(), only 2300 gas is forwarded – enough to emit a log, but not to write storage. Keep receive/fallback logic very small, or have senders use call.
• If a contract has neither receive nor a payable fallback, it cannot receive Ether through normal transactions or calls; such transfers revert.
• A contract can still receive Ether without running code in rare cases – as the recipient of block rewards/fees or of selfdestruct – so never assume address(this).balance equals what your functions recorded.
• A fallback function is also used by proxy contracts, which forward every unknown call to an implementation contract.

Example : receive and fallback

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract Receiver {
    event Received(address from, uint amount);
    event FallbackCalled(address from, uint amount, bytes data);

    receive() external payable {                       // plain Ether, empty calldata
        emit Received(msg.sender, msg.value);
    }

    fallback() external payable {                      // unknown function or data
        emit FallbackCalled(msg.sender, msg.value, msg.data);
    }

    function balance() external view returns (uint) {
        return address(this).balance;
    }
}

contract Sender {
    function sendPlain(address payable to) external payable {
        (bool ok, ) = to.call{value: msg.value}("");               // triggers receive()
        require(ok, "Failed");
    }

    function callUnknown(address payable to) external payable {
        (bool ok, ) = to.call{value: msg.value}(abi.encodeWithSignature("doesNotExist()"));
        require(ok, "Failed");                                      // triggers fallback()
    }
}

Key Takeaways

The PDF E-Notes are the earlier printable version of this chapter. The notes on this page are the latest, revised version.

Question / Answer (15 questions)

MCQ Test : Check Your Understanding (5 questions)

Select an option and press Check Answer, or answer all questions and press Submit Test to see your score. Each answer comes with an explanation.

Bibliography/References

The notes, questions and MCQs on this page are original explanations written for this course. The works listed below were consulted and are cited for attribution and further reading. Product names, logos and trademarks belong to their respective owners. Short quotations, where used, are marked and attributed.

1. Solidity Team. (n.d.). Contracts (creating contracts, visibility and getters, function modifiers, constant and immutable, functions, events, custom errors, inheritance, abstract contracts, interfaces, libraries). Solidity Documentation. https://docs.soliditylang.org/en/latest/contracts.html
2. Solidity Team. (n.d.). Security Considerations. Solidity Documentation. https://docs.soliditylang.org/en/latest/security-considerations.html
3. GeeksforGeeks. (n.d.). Solidity – Fall Back Function. https://www.geeksforgeeks.org/solidity-fall-back-function/
4. Modi, R. (2018). Solidity Programming Essentials: A beginner’s guide to build smart contracts for Ethereum and blockchain. Packt Publishing. ISBN 978-1-78883-138-3.