An external call can fail, and returns a value

Graduate · enrolled learners

This lesson opens with The King of the Ether Throne, 2016.

What happened

King of the Ether Throne was a game in which each new monarch paid to take the throne and the previous monarch was sent compensation, and the contract sent that compensation with Solidity's send, a low-level value transfer that forwards only a small fixed amount of gas, about 2,300, and returns a boolean saying whether it succeeded. When a monarch was itself a contract whose code needed more than that small gas allowance to receive the payment, the send failed and returned false, but the game did not check the returned value and carried on as though the compensation had been paid, so a contract-monarch's compensation was not delivered. The developer published a detailed postmortem describing exactly this. Nothing was stolen and no key was compromised: the failure was assuming an external call always succeeds, when in fact a call carries a limited gas budget, can fail for reasons outside the sender's control, and reports its success in a return value the contract is responsible for checking. The machine did what the code said, which was to ignore whether the payment had actually gone through.

The decision point

An external call, sending value to or calling another address, is not a guaranteed action: it forwards a limited amount of gas, it can fail for reasons the caller does not control, such as the recipient being a contract that needs more gas or that reverts, and it reports whether it succeeded in a return value that the calling code must check and handle. King of the Ether is the case: it sent compensation with a low-level send that forwards only about 2,300 gas and returns false on failure, and because the game did not check that return value, a contract recipient's failed payment was treated as successful and the compensation was lost. This follows directly from the prior lesson's gas model: because every call carries a gas budget and the recipient's code runs within it, a call can run out and fail, so a call is a request that may or may not succeed, not a command that always does. The mental-model error is to write and read an external call as if it were a local, infallible statement, when it is a boundary crossing into code you do not control, bounded by gas, and fallible. So the discipline is to treat every external call as fallible: check its return value and handle failure explicitly, be aware that a low-level send forwards little gas and that the recipient may be a contract, and prefer designs where recipients pull their own funds rather than the contract pushing to many recipients, so one failing transfer cannot corrupt the whole operation. King of the Ether is what an unchecked external call does: it lets the contract believe an action happened that did not, and then continue as if it had.

Orientation and Year One are open: anyone can read them without an account. From Year Two onward the lessons are for enrolled learners, because progress through the later years only means anything if it is tracked against a record.

It is free. We do not sell the list and there is nothing to buy at the end of it.