5 - Solidity II.

payable: the only way in

A call can carry ETH, but only a payable function accepts it. Inside it, msg.value says how much came, in wei. Send ETH to any other function and the whole call reverts, so the ETH stays with the sender. The compiler even refuses to let a public function read msg.value unless it is payable:

function contribute() external payable {      // payable: may receive ETH
    totals[msg.sender] += msg.value;          // msg.value: how much came, in wei
}

function rename(string calldata n) external { // not payable
    uint256 v = msg.value;                    // doesn't compile
}

Error (5887): "msg.value" and "callvalue()" can only be used in payable public functions.

callvalue() in the message is the same value as msg.value, under the name it has in inline assembly.

Keep ETH and gas apart: the ETH you attach is not used up by running the code, only gas is, and gas is paid separately. If the call succeeds, the contract keeps all the ETH, even if its code never looks at msg.value. If the call reverts, all of it goes back to the sender, who only loses the gas fee. And a contract that has no function sending ETH out keeps it forever. An example, with fees made large so you can see them: your wallet has 5 ETH and you attach 1 ETH.

The fee never goes to the contract; it is burned and tipped to the validator, as in the Gas section. Real fees are far smaller: borrowing in LabLending costs about 0.000145 ETH.

Whatever came in becomes part of the contract’s own balance, address(this).balance, and only the contract’s own code can send it out again.

Sending ETH, and receive()

There are three ways for a contract to send ETH:

Two different things travel with a payment. The ETH, amount, is the money: the receiver gets all of it, or nothing if the payment fails. The gas is not money for the receiver: it is a budget for running the receiver’s code while it accepts the money, and whatever isn’t used goes back to the caller. A normal wallet has no code, so nothing runs and it always gets the ETH.

transfer and send are older, work only on an address payable, and allow the receiving contract’s receive() at most 2,300 gas. That is enough to accept the ETH and do nothing else. The receive() of ClassFund records the contribution, which writes to storage, and one new storage write alone costs 20,000 gas. So transfer to ClassFund runs out of gas and reverts, the ETH stays with the sender, and send returns false. Use call: it lets the receiver’s code use as much gas as it needs, and the unused rest goes back. It doesn’t revert on failure, so always check what it returns.

receive() is a special function, written without the function keyword. It does not run every time the contract gets ETH: it runs only when ETH arrives without a function call.

receive() external payable {      // no "function" keyword, no name
    _contribute();                // ClassFund: count it as a contribution
}

A contract without receive() rejects plain ETH. A second special function, fallback(), runs for calls to functions the contract doesn’t have; it is explained under the hood below.

When you send ETH to a contract, its receive() runs in the middle of your function, and it can call you back. That’s why the order matters: update your records first, send the ETH last.

function withdraw() external {
    uint256 amount = owed[msg.sender];
    if (amount == 0) revert NothingToWithdraw();

    owed[msg.sender] = 0;                                 // 1. update the records
    totalOwed -= amount;

    (bool ok, ) = msg.sender.call{value: amount}("");     // 2. send the ETH last
    if (!ok) revert TransferFailed();                     //    and check it worked
}

Had withdraw sent first and set owed to zero afterwards, the receiver’s receive() could call withdraw again and be paid twice. The lock modifier from the last tutorial is the other guard against this.

Notice also that ClassFund never sends money on its own. Imagine it paid 30 classmates their share in one loop: if just one of them is a contract that refuses ETH, the whole transaction reverts and nobody is paid. So approveExpense only writes down how much each person is owed, and each person calls withdraw for their own money. A broken receiver then blocks only their own withdrawal.

Inheritance

ClassFund didn’t write its owner check from scratch. is Owned gives it everything Owned has: the owner variable and the onlyOwner modifier. The constructor of Owned needs to know the owner, so ClassFund passes it in its own constructor: the deployer.

abstract contract Owned {                          // the parent
    address public owner;
    modifier onlyOwner() {
        if (msg.sender != owner) revert NotOwner();
        _;
    }
    constructor(address initialOwner) { owner = initialOwner; }
}

contract ClassFund is Owned {                      // the child gets owner and onlyOwner
    constructor() Owned(msg.sender) {}             // and passes the parent its argument
    function approveExpense(address to, uint256 amount) external onlyOwner { ... }
}

Only ClassFund is deployed, with the code of Owned copied inside it.

A parent marks a function virtual to let children change it. The child writes its own version marked override, and with super it can still call the parent’s version, so it only adds what’s new:

// Owned.sol: virtual means children may change it
function transferOwnership(address newOwner) public virtual onlyOwner { ... }

// ClassFund.sol: override replaces it, super calls the parent's version
function transferOwnership(address newOwner) public override onlyOwner {
    if (newOwner == address(0)) revert ZeroAddress();   // the extra check
    super.transferOwnership(newOwner);                  // then the parent's code
}

A contract can have several parents. Solidity puts them all in one line, and the parent written rightmost is the closest to the child. super always means the next contract in that line:

contract A      { function who() ... virtual returns (string memory) { return "A"; } }
contract B is A { function who() ... override ... { return string.concat("B", super.who()); } }
contract C is A { function who() ... override ... { return string.concat("C", super.who()); } }

contract D is B, C {
    function who() public pure override(B, C) returns (string memory) {
        return string.concat("D", super.who());
    }
}

new D().who()   →   "DCBA"

The line is D → C → B → A, so inside D, the super of C is B, even though C never mentions B. List the parents from the most basic to the most specific. If two parents have the same function, the child must override it and name both: override(B, C).

Interfaces and libraries

In our example, Owned is abstract: a parent that’s never deployed alone. IClassFund is an interface: it lists functions, events and structs, without any code.

interface IClassFund {
    struct Contributor { address account; uint256 total; }

    event Contributed(address indexed from, uint256 amount);

    function contribute() external payable;
    function withdraw() external;
    function getTopContributors() external view returns (Contributor[] memory);
}

An interface has two uses. A contract that says is IClassFund promises to implement all of it, and the compiler refuses to build ClassFund until every function is there. And other contracts use the interface to call ClassFund; they refer to its struct as IClassFund.Contributor. Your semestral task gives you interfaces like this one: implement them exactly.

Inheriting an interface also brings in everything it declares besides functions: ClassFund uses the struct Contributor and emits Contributed without declaring either, because they come from IClassFund.

The indexed on an event parameter means apps can search the log by that value, for example every Contributed event where from is Alice. An event can have up to 3 indexed parameters.

A library is a set of helper functions with no storage of its own. Write one in its own file and import it wherever you need it, or import one somebody else wrote. OpenZeppelin’s are the standard; install them with npm install @openzeppelin/contracts.

// Percent.sol: our own library
library Percent {
    function percentOf(uint256 amount, uint256 pct) internal pure returns (uint256) {
        return amount * pct / 100;
    }
}

// Shop.sol
import {Percent} from "./Percent.sol";                              // a file next to this one
import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";  // an installed package

contract Shop {
    function fee(uint256 price) external pure returns (uint256) {
        uint256 cut = Percent.percentOf(price, 5);               // library name, then the function
        return Math.max(cut, 1);                                 // at least 1
    }
}

You call a library function with the library’s name in front: Percent.percentOf(price, 5), Math.max(cut, 1). In other code you’ll also see using Percent for uint256; followed by price.percentOf(5): a shorthand for exactly the same call. internal library functions are simply copied into your contract when it compiles.

To sum up, the compiler enforces these differences:

The ABI

When you call approveExpense from VS Code, these are the bytes that are sent:

approveExpense(0x70997970C51812dc3A010C7d01b50e0d17dc79C8, 1 ether)

0x20bcab01                                                          // which function
00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8    // to
0000000000000000000000000000000000000000000000000de0b6b3a7640000    // amount: 1 ether in wei

The first 4 bytes, the selector, pick the function: they are the start of keccak256("approveExpense(address,uint256)"). Then each argument is padded to one 32-byte word. This encoding is the Application Binary Interface (ABI), and it is the same whether a wallet calls a contract or one contract calls another: when Donor calls ClassFund, the compiler builds these bytes from the interface. In code, IClassFund.approveExpense.selector gives you the 4 bytes.

call sends exactly such bytes to another contract, and you can build them yourself:

// call a function: the function from the interface, then its arguments in ( )
(bool ok, ) = address(fund).call(abi.encodeCall(IClassFund.approveExpense, (carol, 1 ether)));

// call a function and attach ETH
(ok, ) = address(fund).call{value: 1 ether}(abi.encodeCall(IClassFund.contribute, ()));

// no bytes at all: it only sends ETH, and the receiver's receive() runs
(ok, ) = to.call{value: 0.5 ether}("");

// what you normally write instead: the compiler builds the same bytes
fund.contribute{value: 1 ether}();

abi.encodeCall takes the function from the interface and its arguments in a second pair of brackets, in order; () means none. The compiler checks the argument types. Older code uses abi.encodeWithSignature("approveExpense(address,uint256)", carol, 1 ether), which builds the same bytes from the name written as text, without any type check.

The ETH comes from the calling contract’s own balance, not automatically from msg.value. To pass on exactly what your caller sent, write {value: msg.value}, like Donor does.

For the first line, abi.encodeCall builds exactly the bytes shown above, with Carol at 0x7099…​79C8.

Every contract looks at what you sent and picks one piece of code. If none fits, the call reverts:

Calling a function the contract doesn’t have usually means you called the wrong contract, for example through the wrong interface: the selector is a hash of the name and types, so it doesn’t match anything. A proxy uses this on purpose, as the next section shows: it has almost no functions, so every call ends up in its fallback().

Calls and upgrades

There are three kinds of call from one contract to another:

A normal call is what you’ve done all along: calling a function of another contract, with or without ETH. fund.contribute() in Donor is one, and sending plain ETH is a call that names no function. staticcall is a call that may only read: Solidity uses it by itself whenever you call a view function of another contract, like fund.getOwed(me), and if that code tries to write anything, the call reverts.

delegatecall is the unusual one: it runs the other contract’s code as if it were mine, on my storage. The same function, called both ways:

contract Counter { uint256 public count; function increment() external { count += 1; } }

contract Caller {
    uint256 public count;                                     // same variable, same place
    function viaCall(address counter) external {
        (bool ok, ) = counter.call(abi.encodeCall(Counter.increment, ()));
        require(ok);                                          // Counter's count + 1
    }
    function viaDelegatecall(address counter) external {
        (bool ok, ) = counter.delegatecall(abi.encodeCall(Counter.increment, ()));
        require(ok);                                          // Caller's own count + 1
    }
}

After viaCall, Counter’s count is 1. After viaDelegatecall, Counter’s code ran, but it was Caller’s own count that became 1; Counter wasn’t changed. That’s what makes upgrades possible.

delegatecall matches variables by position, not by name. Storage has no names or types, only numbered 32-byte slots. count is in slot 0 of Counter, so increment() adds 1 to slot 0, and under delegatecall that is the caller’s slot 0, whatever it holds:

Nothing checks the types and nothing reverts: the code that runs simply decides what the bytes mean. That’s why a new version of an upgradeable contract must keep the old variables in exactly the same order and types, and add new ones only after them.

Deployed code can never change, bugs included. There are two ways to ship a fix:

Either way you deploy new code. A proxy saves you from moving the address and the data, thanks to delegatecall:

Donor  --call-->          ClassFund   (ClassFund's code, ClassFund's storage)
Proxy  --delegatecall-->  CounterV1   (V1's code, the Proxy's storage)

When the proxy delegatecalls CounterV1, V1’s count += 1 runs, but the count it changes lives in the proxy. So the data lives in one place, the proxy, and the code can live somewhere else. These are the two versions of the code in Upgrade.sol:

contract CounterV1 is ProxyStorage {          // ProxyStorage: implementation, admin
    uint256 public count;
    function increment() external { count += 1; }
}

contract CounterV2 is ProxyStorage {
    uint256 public count;                     // same variables, same order
    function increment() external { count += 10; }    // changed
    function reset() external { count = 0; }           // new
}

Nobody calls V1 or V2 directly; their own count stays 0. The proxy isn’t a website or a server: it’s an ordinary contract, Proxy in Upgrade.sol, sitting between the users and the code. It never declares count: V1’s code simply writes slot 2 of the proxy. The proxy’s own two variables, implementation and admin, sit in slots 0 and 1, so every version starts with is ProxyStorage to keep count out of their way. A version that forgets it puts count in slot 0, and the first increment adds 1 to implementation: the proxy then points at an address with no code, and every later call silently does nothing. (Real proxies keep implementation in a far-away slot, defined by the standard EIP-1967, so it can’t collide.) The proxy has only two functions: upgradeTo for the admin, and a fallback() that delegatecalls whichever version it points at. An upgrade, step by step:

Nothing moves to a new address, and no data is copied: it was in the proxy all along. upgradeTo only overwrites one variable inside the proxy. Follow the storage of all three contracts:

V1 and V2 only lend their code; their own count is never used, so there is nothing to transfer. It works like an app update on your phone: same number, same contacts, new app.

You use proxies all the time without noticing. USDC on Ethereum is one: open it on Etherscan and the Contract tab shows "Read as Proxy" and "Write as Proxy", along with the list of its past upgrades.

It comes at a price:

Most large protocols are upgradeable, so always check who can upgrade a contract before you trust it.

Play with the examples

The upgrade in Upgrade.sol is shown in class as a demo; you don’t have to deploy it. It follows the storage table in the Calls and upgrades section above: the count survives the upgrade, and count() on V1 and V2 themselves stays 0.

Then click through ClassFund and Donor yourself:

Build: the canteen

MealCredits is a small token: it keeps every student’s credits, and students buy them with ETH, one credit for CREDIT_PRICE = 0.001 ether. Canteen is the shop: it sells meals for 10 credits each and sends the credits to the kitchen. Fill in the functions marked TODO, one at a time. Each is one to six lines. Do them in order: a later check tells you if an earlier one is missing.

After each TODO, open 2-exercise/checks/CanteenChecks.sol, deploy the check with the TODO’s number and call run(). If the call goes through, the TODO works; if it reverts, the message says what to fix. Check5BuyCredits needs 0.01 ether sent with run(); it sends back whatever it doesn’t spend. Check6Together deploys both contracts itself and runs whole purchases. These are real runs after TODO 1 and 2:

Check1Allow.run()       →  "TODO 1 works."
Check2SpendFrom.run()   →  "TODO 2 works. Look for Spent in the log when you try it by hand."
Check3Kitchen.run()     →  revert "TODO 3: setKitchen should store the kitchen"
Check4BuyMeal.run()     →  revert "Finish TODO 3 first"
Check5BuyCredits.run()  →  revert "TODO 5: buyCredits(3) should add 3 credits to the caller"
Check6Together.run()    →  revert "Finish TODO 3 first"

Finally, wire it by hand:

Finished early? Break it on purpose: