0xMowgli.

/ Writing · · Updated · 5 min read

receive vs fallback in Solidity: which one runs, and when

By Oussama Allamou · Solidity · Ether Transfers · Smart Contracts

receive() runs when a contract is sent ether with no calldata. fallback() runs when the calldata does not match any function, and it also catches plain ether transfers if the contract has no receive. If neither applies, or the one that applies is not payable, the call reverts and the sender keeps the ether.

Build a call, change the contract, and see what runs.

The call

target.call{value: 1 ether}("");

The contract

contract Target {

function deposit() external payable { }

receive() external payable { }

fallback() external payable { }

}

→ ok

Try it · receive or fallback
receive() runs

The calldata is empty and the contract defines receive(), so receive runs.

CalldataCallContract

What is the receive function?

receive is the function a contract runs when it gets ether and nothing else. It has no function keyword, no arguments and no return value, and it has to be external payable. It was added in Solidity 0.6.0.

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

contract Donations {
    event Received(address from, uint256 amount);

    receive() external payable {
        emit Received(msg.sender, msg.value);
    }
}

A wallet sending ether to this contract's address, with the data field left empty, triggers it.

What is the fallback function?

fallback is the catch-all. It runs when the first four bytes of the calldata, the function selector, do not match any function in the contract. It also runs for empty calldata when there is no receive.

contract Catcher {
    event Unknown(address from, uint256 value, bytes data);

    fallback() external payable {
        emit Unknown(msg.sender, msg.value, msg.data);
    }
}

Without payable, a fallback still catches unknown calls, but reverts if ether is attached. A fallback can also be declared as fallback(bytes calldata input) external returns (bytes memory) when it needs to return data.

The most common real use is a proxy. The proxy contract has almost no functions of its own, so nearly every call lands in fallback, which forwards it to an implementation contract with delegatecall.

Which one runs for a given call?

The dispatcher asks its questions in a fixed order. Step through the tree, or tap a box.

INCOMING CALLmsg.value + msg.dataIS msg.data EMPTY?receive()SELECTOR MATCH?fallback()YOUR FUNCTIONREVERTYESNONO receive()MATCHNO HANDLER, OR NOT PAYABLE
Explainer · receive or fallback: which one runs
  1. Step 01A call arrives

    Every call to a contract carries two things: msg.value, the ether attached, and msg.data, the calldata. The contract looks at the calldata first to decide which code runs.

  2. Step 02The data names a function

    The first four bytes of the calldata are a function selector. If they match one of your functions, that function runs. This is the normal path and neither special function is involved.

  3. Step 03No data at all: receive

    A plain ether transfer has empty calldata. If the contract defines receive() external payable, it runs. That is the only job receive has.

  4. Step 04No data, no receive: fallback

    If there is no receive function, an empty call goes to fallback instead. It has to be marked payable to accept the ether.

  5. Step 05Data that matches nothing: fallback

    Calldata that does not match any function selector goes to fallback, even when a receive function exists. This is how proxies work: the fallback forwards the unknown call to another contract.

  6. Step 06Nowhere to go: revert

    If no function fits, or the one that fits is not payable while ether is attached, the call reverts and the ether stays with the sender.

msg.dataThe contract hasWhat runs
Matches a functionAnythingThat function
Emptyreceivereceive
EmptyNo receive, payable fallbackfallback
Empty, with etherNo receive, non-payable fallbackRevert
EmptyNeitherRevert
Matches nothingfallbackfallback (must be payable if ether is attached)
Matches nothingNo fallbackRevert

One contract can define both, and for anything that should accept ether and also handle unknown calls, it should:

contract Both {
    receive() external payable {
        // plain ether transfers
    }

    fallback() external payable {
        // everything that matched no function
    }
}

If you write a payable fallback without a receive, the compiler warns you. The contract works, but a plain transfer and a mistyped function call become impossible to tell apart.

What about the 2300 gas stipend?

It is often listed as a property of receive and fallback. It is a property of how the ether was sent.

  • recipient.transfer(amount) and recipient.send(amount) forward only 2300 gas. That is enough to emit an event and not enough to write to storage.
  • recipient.call{value: amount}("") forwards all the remaining gas unless you set a limit. Check the returned success value with a require.

So the same receive function can run with 2300 gas or with millions, depending on the caller. If your contract may be paid by transfer, keep receive to an event at most. If it writes storage there, those senders will see their payment revert.

When your own contract sends ether, call with a check on the returned success value is the current recommendation, combined with protection against reentrancy, since the recipient now has gas to call you back.

Can a contract receive ether without either function running?

Yes, in two ways. A contract that calls selfdestruct sends its balance to a target address without running any code there. And an address named as the recipient of block rewards or validator withdrawals is credited directly.

The consequence is practical: do not write logic that assumes the contract's balance equals the sum of deposits you recorded. Track deposits in your own state variable and treat the raw balance as something others can push up.

What do the terms mean?

  • Calldata (msg.data): the bytes sent with a call. For a normal function call it starts with a selector, followed by the encoded arguments.
  • Function selector: the first four bytes of the hash of a function's signature. The contract uses it to pick the function.
  • payable: a modifier that lets a function accept ether. Without it, a call carrying ether reverts.
  • Gas stipend: the 2300 gas forwarded by transfer and send.
  • Proxy: a contract that forwards calls to another contract through its fallback, usually with delegatecall.

FAQ

Do I need both receive and fallback?

Only if the contract should accept plain ether transfers and also react to calls that match no function. A contract that just needs to receive ether needs only receive. A contract that should never be sent ether directly needs neither.

What happens if I send ether to a contract with neither function?

A plain transfer reverts and the ether stays with the sender. Ether can still be attached to a call to one of the contract's payable functions.

Why does my receive function fail when another contract pays it?

Most likely the sender uses transfer or send, which forward only 2300 gas, and your receive function does more than that allows, such as writing to storage.

Is fallback called when a function exists but the arguments are wrong?

No. Dispatch only looks at the four-byte selector. If the selector matches, that function is chosen, and badly encoded arguments make the call revert during decoding.

Can receive or fallback take arguments?

receive cannot take arguments or return anything. fallback can optionally take a single bytes calldata argument and return bytes memory, which is mostly used in proxies.

Further reading