Program the Blockchain

Introduction to Ethereum Payment Channels Video

Mon, 10 Dec 2018 00:00:00 +0000

We’ve created a short (32-minute) video to help explain Ethereum payment channels—what they are and how they work. This video complements two of our previous posts: Writing a Simple Payment Channel and Building Long-lived Payment Channels.

Implementing Harberger Tax Deeds

Wed, 19 Sep 2018 00:00:00 +0000

This post will demonstrate how to implement deeds that collect a “Harberger tax”. The recently published book, Radical Markets: Uprooting Capitalism and Democracy for a Just Society, proposed Harberger taxes for a number of applications. Since then Vitalik Buterin (here) and Simon de la Rouviere (here) have speculated on smart contract applicability.

A Harberger tax is a property tax that depends on an owner-determined, enforceable sales price. For instance, suppose that there is a 5%/year Harberger tax on real estate, and Alice owns a parcel subject to this tax. A Harberger tax regime requires Alice to state a price at which she is obligated to sell her parcel. As a consequence, Alice will owe 5% of that sales price every year as a property tax, and her parcel will be for sale at her stated price.

Obviously, Alice faces a tradeoff: higher prices create higher taxes but with less uncertainty about a future sale while lower prices create lower taxes with greater uncertainty about a future sale. This tension provides incentives for Alice to set her taxes (by setting her sales price) reasonably.

Deed Tokens

ERC20 token contracts create a supply of many fungible tokens—tokens are indistinguishable from each other. “Deed” tokens represent non-fungible tokens—each token represents some right or privilege different from those of other deed tokens. A popular example of deed tokens are the tokens that represent “CryptoKitties”.

ERC721 defines a standard for non-fungible tokens, but this post will not implement to that standard. Not only are Harberger-taxed deed tokens not a good fit for ERC721, but ERC721 presents lots of details that will distract from the essence of this post (i.e., how to implement Harberger taxes correctly and efficiently).

Our contract will track the account that receives tax payments, and the tax rate. This contract has a daily tax rate given as a rational number.

pragma solidity ^0.4.24;

contract HarbergerTax {
    address public taxRecipient;

    // Per day tax rate
    uint32 public taxNumerator;
    uint32 public taxDenominator;

    // more to come...
}

The contract tracks who owns each token, and the sales price the owner has set for that token. Tokens are identified by integers, which are indexes into the tokens array below.

struct Token {
    address owner;
    uint96 price;
}

Token[] public tokens;

constructor(
    uint48 numberOfTokens,
    uint32 _taxNumerator,
    uint32 _taxDenominator
) public {
    taxRecipient = msg.sender;
    tokens.length = numberOfTokens;
    taxNumerator = _taxNumerator;
    taxDenominator = _taxDenominator;
}

Accounting for Harberger Taxes

Harberger taxes are conceptually simple: taxes are proportional to the selling price and the duration that the deed is held. The contract will collect taxes on demand from prepaid balances maintained by deed holders.

This contract will maintain per-account ether balances from which taxes will be collected for all deeds owned by each account. This per-account balance design is in contrast to having per-deed balances. Because a single account may potentially own many deeds, a per-account balance is simpler for deed owners to manage because they only need to deposit into one balance rather than one balance per deed.

To collect taxes from an account, the contract must know the total of the sales prices of all deeds owned by each account and the time the taxes were paid through for that account.

struct Account {
    uint256 balance;
    uint144 sumOfPrices;
    uint112 paidThru;
}

mapping(address => Account) public accounts;

The taxes due will be proportional to that total and the time that’s passed. The contract also tracks each contract’s ether balance.

function taxesDue(address addr) public view returns (uint256) {
    Account storage a = accounts[addr];

    return a.sumOfPrices * (now - a.paidThru) * taxNumerator
        / taxDenominator / 1 days;
}

Because the Ethereum VM does not check for overflows, a smart contract must guard against them. Because sumOfPrices is a uint144, taxRateNumerator is a uint32, and now is the number of seconds since a recent time, there’s no chance the multiplication above will overflow when computing a uint256.

Maintaining an Ether Balance

Taxes are collected in arrears, which means that they are collected for time that has passed since the last collection. If adequate ether is not available when taxes are collected for an account, all that account’s tokens are at risk of being immediately foreclosed. A simple function enables direct deposits.

function deposit() public payable {
    accounts[msg.sender].balance += msg.value;
}

In addition, most functions are payable, which enables simultaneous deposits.

Foreclosure

When an account has no ether balance and is behind on taxes, the contract can foreclose on its tokens. Foreclosure reverts ownership to address(0) and sets the price to zero.

event Change(uint256 indexed id, address indexed to, address indexed from);

// Possibly foreclose on token[id]
function forecloseIfPossible(uint256 id) public {
    Token storage t = tokens[id];
    Account storage a = accounts[t.owner];

    // Owner must be broke and behind on taxes to foreclose
    if (a.balance == 0 && a.paidThru < now && a.sumOfPrices > 0) {
        a.sumOfPrices -= t.price;
        emit Change(id, 0, t.owner);
        delete(tokens[id]);
    }
}

Collecting Taxes

Collecting taxes from an account with an adequate ether balance is straightforward. The ether is transferred to the taxRecipient, and the timestamp (paidThru) is updated.

// Collect taxes due from account.
// Return true if taxes fully paid, false otherwise
function collectTaxes(address addr) public returns (bool) {
    Account storage a = accounts[addr];

    uint256 taxes = taxesDue(addr);
    if (taxes <= a.balance) {
        a.paidThru = uint112(now);
        accounts[taxRecipient].balance += taxes;
        a.balance -= taxes;
        return true;
    } else {
        ... // see below
    }
}

When there’s an inadequate balance, the contract collects the entire balance and adjusts the paidThru timestamp proportionally. For instance, if the account owes three days of taxes, but the balance only covers two days worth, then the timestamp is adjusted forward by two days.

// Collect taxes due from account.
// Return true if taxes fully paid, false otherwise
function collectTaxes(address addr) public returns (bool) {
    Account storage a = accounts[addr];

    uint256 taxes = taxesDue(addr);
    if (taxes <= a.balance) {
        ... // see above
    } else {
        // Adjust paidThru proportionally (overflow check unnecessary)
        a.paidThru += uint112((now - a.paidThru) * a.balance / taxes);

        // Collect entire balance for partially-paid taxes
        accounts[taxRecipient].balance += a.balance;
        a.balance = 0;
        return false;
    }
}

The routine also returns a bool value that is true if and only if the taxes were collected in full.

Buying a Token

Buying tokens is parameterized by the token to be bought, the maximum price the sender is willing to pay, and the sales price the buyer will accept in the future for the token.

Before executing the sale, the contract first collects any taxes due from the seller and the buyer. If the seller’s balance was insufficient to cover the seller’s taxes, then it is possible to foreclose on this token, which would make its price zero for the buyer.

function buy(
    uint256 id,
    uint256 max,
    uint96 price
)
    public
    payable
{
    accounts[msg.sender].balance += msg.value;

    Token storage t = tokens[id];

    // Collect taxes from token's owner and possibly foreclose on token[id].
    collectTaxes(t.owner);

    // Foreclosure may change price and seller.
    forecloseIfPossible(id);
    address seller = t.owner;

    if (seller != msg.sender) {
        require(max >= t.price, "price is too high");

        // Collect taxes due from buyer before checking their balance
        collectTaxes(msg.sender);
        require(accounts[msg.sender].balance >= t.price,
            "insufficient funds");

        // Transfer purchase price
        accounts[seller].balance += t.price;
        accounts[msg.sender].balance -= t.price;

        t.owner = msg.sender;
    }
    // Adjust buyer's and seller's sumOfPrices
    accounts[seller].sumOfPrices -= t.price;
    accounts[msg.sender].sumOfPrices += price;

    t.price = price;

    emit Change(id, msg.sender, seller);
}

Notes on the code above:

The maximum price is specified to guard against a buyer inadvertently buying a token whose price has increased between the time the buyer learned the (old) price and the time the transaction is actually accepted.
Buying a property requires adjusting the buyer’s and the seller’s sumOfPrices.

Changing the Price

A token owner may want to change the token’s price, which will have the effect of changing future taxes. The owner can do this by simply buying the token (from their self) while specifying the new price.

Withdrawing Ether

Accounts can withdraw ether, but only after paying any past taxes.

function withdraw(uint256 amount) public {
    collectTaxes(msg.sender);

    require(accounts[msg.sender].balance >= amount, "insufficient funds");

    accounts[msg.sender].balance -= amount;
    msg.sender.transfer(amount);
}

Changing the Tax Recipient

This contract adopts the approve/transfer pattern for changing the tax recipient. The current recipient designates the new recipient, and the new recipient transfers the role to itself.

address public newRecipient;

function approveRecipient(address _newRecipient) public {
    require(msg.sender == taxRecipient, "must be taxRecipient");
    newRecipient = _newRecipient;
}

function transferRecipient() public {
    require(msg.sender == newRecipient, "must be approved");
    taxRecipient = msg.sender;
    newRecipient = 0;
}

The current recipient can change approvals prior to a transfer with a subsequent call to approveRecipient.

Summary

Deed tokens represent non-fungible rights/privileges.
Harberger-taxed tokens can be implemented simply with a smart contract, which manages tax collection and token sales.
This implementation relies on per-account bookkeeping to compute and collect taxes.

The Complete Contract

harberger.sol

pragma solidity ^0.4.24;

contract HarbergerTax {
    address public taxRecipient;

    // Per day tax rate
    uint32 public taxNumerator;
    uint32 public taxDenominator;

    struct Token {
        address owner;
        uint96 price;
    }

    Token[] public tokens;

    constructor(
        uint48 numberOfTokens,
        uint32 _taxNumerator,
        uint32 _taxDenominator
    ) public {
        taxRecipient = msg.sender;
        tokens.length = numberOfTokens;
        taxNumerator = _taxNumerator;
        taxDenominator = _taxDenominator;
    }

    struct Account {
        uint256 balance;
        uint144 sumOfPrices;
        uint112 paidThru;
    }

    mapping(address => Account) public accounts;

    function taxesDue(address addr) public view returns (uint256) {
        Account storage a = accounts[addr];

        return a.sumOfPrices * (now - a.paidThru) * taxNumerator
            / taxDenominator / 1 days;
    }

    event Change(uint256 indexed id, address indexed to, address indexed from);

    // Possibly foreclose on token[id]
    function forecloseIfPossible(uint256 id) public {
        Token storage t = tokens[id];
        Account storage a = accounts[t.owner];

        // Owner must be broke and behind on taxes to foreclose
        if (a.balance == 0 && a.paidThru < now && a.sumOfPrices > 0) {
            a.sumOfPrices -= t.price;
            emit Change(id, 0, t.owner);
            delete(tokens[id]);
        }
    }

    // Collect taxes due from account.
    // Return true if taxes fully paid, false otherwise
    function collectTaxes(address addr) public returns (bool) {
        Account storage a = accounts[addr];

        uint256 taxes = taxesDue(addr);
        if (taxes <= a.balance) {
            a.paidThru = uint112(now);
            accounts[taxRecipient].balance += taxes;
            a.balance -= taxes;
            return true;
        } else {
            // Adjust paidThru proportionally (overflow check unnecessary)
            a.paidThru += uint112((now - a.paidThru) * a.balance / taxes);

            // Collect entire balance for partially-paid taxes
            accounts[taxRecipient].balance += a.balance;
            a.balance = 0;
            return false;
        }
    }

    // Try to buy token for no more than 'max'
    function buy(
        uint256 id,
        uint256 max,
        uint96 price
    )
        public
        payable
    {
        accounts[msg.sender].balance += msg.value;

        Token storage t = tokens[id];

        // Collect taxes from token's owner and possibly foreclose on token[id].
        collectTaxes(t.owner);

        // Foreclosure may change price and seller.
        forecloseIfPossible(id);
        address seller = t.owner;

        if (seller != msg.sender) {
            require(max >= t.price, "price is too high");

            // Collect taxes due from buyer before checking their balance
            collectTaxes(msg.sender);
            require(accounts[msg.sender].balance >= t.price,
                "insufficient funds");

            // Transfer purchase price
            accounts[seller].balance += t.price;
            accounts[msg.sender].balance -= t.price;

            t.owner = msg.sender;
        }
        // Adjust buyer's and seller's sumOfPrices
        accounts[seller].sumOfPrices -= t.price;
        accounts[msg.sender].sumOfPrices += price;

        t.price = price;

        emit Change(id, msg.sender, seller);
    }

    function deposit() public payable {
        accounts[msg.sender].balance += msg.value;
    }

    function withdraw(uint256 amount) public {
        collectTaxes(msg.sender);

        require(accounts[msg.sender].balance >= amount, "insufficient funds");

        accounts[msg.sender].balance -= amount;
        msg.sender.transfer(amount);
    }

    function tokenCount() public view returns (uint256) {
        return tokens.length;
    }

    address public newRecipient;

    function approveRecipient(address _newRecipient) public {
        require(msg.sender == taxRecipient, "must be taxRecipient");
        newRecipient = _newRecipient;
    }

    function transferRecipient() public {
        require(msg.sender == newRecipient, "must be approved");
        taxRecipient = msg.sender;
        newRecipient = 0;
    }
}

Writing a Dollar Auction Contract

Thu, 16 Aug 2018 00:00:00 +0000

This post will implement a “dollar auction” contract for ERC20 tokens. It will be a modest change to the English auction contract.

A dollar auction requires that the highest and second-highest bidders each pay their bid amounts, although only the highest bidder receives the bid-for prize. (Originally, dollar auctions were so-named because it was a dollar bill that was being auctioned. Their fundamental characteristic, however, is the risk of being the second-highest bidder and getting nothing for your bid.)

Dollar auctions are not really practical for anything other than demonstrating how irrational people can be. They are, however, well-defined and relatively simple, so they make a good subject for implementation as a smart contract.

Auction State

Like our English Auction contract, the penny auction contract will auction off tokens, and the auction ends after no bids have been received for a given timeout period.

Unlike the English auction, the dollar auction keeps track of the top two highest bids. This dollar auction does not have a reserve price.

contract DollarAuction {
    address public seller;

    IERC20Token public token;
    uint256 public minIncrement;
    uint256 public timeoutPeriod;

    uint256 public auctionEnd;

    address public highBidder;
    uint256 public highBid;

    address public secondBidder;
    uint256 public secondBid;

    constructor(
        IERC20Token _token,
        uint256 _minIncrement,
        uint256 _timeoutPeriod
    )
        public
    {
        token = _token;
        minIncrement = _minIncrement;
        timeoutPeriod = _timeoutPeriod;

        seller = msg.sender;
        auctionEnd = now + timeoutPeriod;
        highBidder = seller;
    }

    // more to come
}

The constructor initializes highBidder to the seller’s account to simplify handling the case where there are no bids.

Ether Balances

Like the English Auction contract, this contract will keep track of every account’s available ether balance:

mapping(address => uint256) public balanceOf;

function withdraw() public {
    uint256 amount = balanceOf[msg.sender];
    balanceOf[msg.sender] = 0;
    msg.sender.transfer(amount);
}

Bidding

Bidding in a dollar auction requires tracking the top two highest bids and adjusting all of the ether balances appropriately.

event Bid(address highBidder, uint256 highBid);

function bid(uint256 amount) public payable {
    require(now < auctionEnd);
    require(amount >= highBid+minIncrement);
    require(msg.sender != highBidder);

    balanceOf[msg.sender] += msg.value;

    uint256 increase = amount - secondBid;
    balanceOf[seller] += increase;
    balanceOf[secondBidder] += secondBid;
    require(balanceOf[msg.sender] >= amount);
    balanceOf[msg.sender] -= amount;
    secondBid = highBid;
    secondBidder = highBidder;

    highBidder = msg.sender;
    highBid = amount;
    auctionEnd = now + timeoutPeriod;
    emit Bid(highBidder, amount);
}

The code above merits some explanation:

The initial require statements make sure that a bid is acceptable.
The bulk of the code adjusts the ether balances to account for the previous high bidder now being the second-highest bidder. It’s worth noting that all of the adjustments to balanceOf offset each other.
The seller’s balance is updated by the increase of the current bid over the second-highest bid.
The require(balanceOf[msg.sender] >= amount); statement could not have been placed with the earlier require statements because it’s possible that msg.sender was the previous second-highest bidder. In that case, the sender’s ether balance wouldn’t be accurate until after secondBidder’s balance is updated.

Claiming Tokens

The winning bidder claims their tokens with resolve.

function resolve() public {
    require(now >= auctionEnd);

    uint256 t = token.balanceOf(this);
    require(token.transfer(highBidder, t));
}

Summary

Smart contracts can easily implement “dollar auctions”.
Dollar auctions are similar to English auctions, with the added complication of tracking the second-highest bidder.

The Complete Contract

dollar.sol

pragma solidity ^0.4.24;

import "../common/ierc20token.sol";

contract DollarAuction {
    address public seller;

    IERC20Token public token;
    uint256 public minIncrement;
    uint256 public timeoutPeriod;

    uint256 public auctionEnd;

    address public highBidder;
    uint256 public highBid;

    address public secondBidder;
    uint256 public secondBid;

    constructor(
        IERC20Token _token,
        uint256 _minIncrement,
        uint256 _timeoutPeriod
    )
        public
    {
        token = _token;
        minIncrement = _minIncrement;
        timeoutPeriod = _timeoutPeriod;

        seller = msg.sender;
        auctionEnd = now + timeoutPeriod;
        highBidder = seller;
    }

    mapping(address => uint256) public balanceOf;

    function withdraw() public {
        uint256 amount = balanceOf[msg.sender];
        balanceOf[msg.sender] = 0;
        msg.sender.transfer(amount);
    }

    event Bid(address highBidder, uint256 highBid);

    function bid(uint256 amount) public payable {
        require(now < auctionEnd);
        require(amount >= highBid+minIncrement);
        require(msg.sender != highBidder);

        balanceOf[msg.sender] += msg.value;

        uint256 increase = amount - secondBid;
        balanceOf[seller] += increase;
        balanceOf[secondBidder] += secondBid;
        require(balanceOf[msg.sender] >= amount);
        balanceOf[msg.sender] -= amount;
        secondBid = highBid;
        secondBidder = highBidder;

        highBidder = msg.sender;
        highBid = amount;
        auctionEnd = now + timeoutPeriod;
        emit Bid(highBidder, amount);
    }

    function resolve() public {
        require(now >= auctionEnd);

        uint256 t = token.balanceOf(this);
        require(token.transfer(highBidder, t));
    }
}

Writing a Penny Auction Contract

Wed, 08 Aug 2018 00:00:00 +0000

This post will implement a bidding fee auction (aka “penny auction”) contract for ERC20 tokens. It will be a modest change to the English auction contract.

Penny auctions are an interesting twist on typical English auctions. In an English auction, bidders can bid any amount greater than the last high bid subject to some minimum increment. And, there is no fee to bid.

In a penny auction, bids are restricted to a fixed increment over the current high bid, and there is a fee to bid. Typically, the increments are small relative to the fee. For instance, the increment might be a penny and the fee a dollar.

Auction State

Like our English Auction contract, the penny auction contract will auction off tokens, and the auction ends after no bids have been received for a given timeout period.

Unlike the English auction, the penny auction collects a fee for each bid and enforces a fixed bid increment. This penny auction does not have a reserve price.

contract PennyAuction {
    address seller;

    IERC20Token public token;
    uint256 public bidIncrement;
    uint256 public timeoutPeriod;
    uint256 public bidFee;

    uint256 public auctionEnd;

    address public highBidder;
    uint256 public highBid;

    constructor(
        IERC20Token _token,
        uint256 _bidIncrement,
        uint256 _bidFee,
        uint256 _timeoutPeriod
    )
        public
    {
        token = _token;
        bidIncrement = _bidIncrement;
        bidFee = _bidFee;
        timeoutPeriod = _timeoutPeriod;

        seller = msg.sender;
        auctionEnd = now + timeoutPeriod;
        highBidder = seller;
    }

    // more to come
}

The constructor initializes highBidder to the seller’s account to simplify handling the case where there are no bids.

Ether Balances

Like the English Auction contract, this contract will keep track of every account’s available ether balance:

mapping(address => uint256) public balanceOf;

function withdraw() public {
    uint256 amount = balanceOf[msg.sender];
    balanceOf[msg.sender] = 0;
    msg.sender.transfer(amount);
}

Bidding

Processing penny auction bids is straightforward:

event Bid(address highBidder, uint256 highBid);

function bid() public payable {
    require(now < auctionEnd);
    require(msg.sender != highBidder);

    balanceOf[msg.sender] += msg.value;

    require(balanceOf[msg.sender] >= highBid + bidIncrement + bidFee);

    balanceOf[seller] += bidIncrement + bidFee;
    balanceOf[highBidder] += highBid;
    balanceOf[msg.sender] -= highBid + bidIncrement + bidFee;

    highBid += bidIncrement;
    highBidder = msg.sender;
    auctionEnd = now + timeoutPeriod;
    emit Bid(highBidder, highBid);
}

A few notable things about the code above:

The bulk of the work is in adjusting the ether balances for the seller, the previous high bidder and the sender (new high bidder).
The ether adjustments transfer the increment and the fee to the seller, which means that ether is available for withdrawal immediately.
The contract doesn’t allow a bidder to bid against themselves.

Claiming Tokens

The winning bidder claims their tokens with resolve.

function resolve() public {
    require(now >= auctionEnd);

    uint256 t = token.balanceOf(this);
    require(token.transfer(highBidder, t));
}

Summary

Penny auctions are similar to English auctions with the addition of a bid fee and a fixed bid increment.
The English auction contract requires only slight modification to support a penny auction.

The Complete Contract

penny.sol

pragma solidity ^0.4.24;

import "./ierc20token.sol";

contract PennyAuction {
    address seller;

    IERC20Token public token;
    uint256 public bidIncrement;
    uint256 public timeoutPeriod;
    uint256 public bidFee;

    uint256 public auctionEnd;

    address public highBidder;
    uint256 public highBid;

    constructor(
        IERC20Token _token,
        uint256 _bidIncrement,
        uint256 _bidFee,
        uint256 _timeoutPeriod
    )
        public
    {
        token = _token;
        bidIncrement = _bidIncrement;
        bidFee = _bidFee;
        timeoutPeriod = _timeoutPeriod;

        seller = msg.sender;
        auctionEnd = now + timeoutPeriod;
        highBidder = seller;
    }

    mapping(address => uint256) public balanceOf;

    function withdraw() public {
        uint256 amount = balanceOf[msg.sender];
        balanceOf[msg.sender] = 0;
        msg.sender.transfer(amount);
    }

    event Bid(address highBidder, uint256 highBid);

    function bid() public payable {
        require(now < auctionEnd);
        require(msg.sender != highBidder);

        balanceOf[msg.sender] += msg.value;

        require(balanceOf[msg.sender] >= highBid + bidIncrement + bidFee);

        balanceOf[seller] += bidIncrement + bidFee;
        balanceOf[highBidder] += highBid;
        balanceOf[msg.sender] -= highBid + bidIncrement + bidFee;

        highBid += bidIncrement;
        highBidder = msg.sender;
        auctionEnd = now + timeoutPeriod;
        emit Bid(highBidder, highBid);
    }

    function resolve() public {
        require(now >= auctionEnd);

        uint256 t = token.balanceOf(this);
        require(token.transfer(highBidder, t));
    }
}

Contracts Calling Arbitrary Functions

Thu, 02 Aug 2018 08:58:52 -0400

Solidity offers convenient high-level syntax for calling functions in other contracts, but this high-level syntax is only available when the target contract’s interface is known at compile time.

In this post, I’ll show how smart contracts can use low-level message passing to make arbitrary calls into other contracts. I’ll use this mechanism to enhance our trivial multisig wallet so that it can make function calls in addition to transferring ether.

High-Level Function Call Syntax

Before diving into the low-level mechanism, it’s worth reviewing Solidity’s high-level syntax for calling out to another contract. We’ve used this mechanism many times on this blog already. Here’s a very abridged example from our post Performing Multiple Actions Transactionally:

interface ITokenShop {
    function sell(uint256 amount) external;
}

contract Arbitrage {
    constructor (ITokenShop sellShop, uint256 amount) public {
        sellShop.sell(amount);
    }
}

The line sellShop.sell(amount) is where the external call happens. The Solidity compiler translates this high-level function call into low-level message passing. This is possible because the interface for ITokenShop is known at compile time, so the appropriate encoding logic can be emitted by the compiler.

The Low-Level `call()` Function

When the interface of the target contract is not known at compile time, Solidity’s high-level syntax is unavailable. For these scenarios, the address type includes a call() function.

call() accepts the raw message that is passed to the target contract¹. I showed how message data is constructed in my post Anatomy of Transaction Data. For now, I’ll assume that the data already exists:

address target = ...;
bytes memory data = ...;

bool result = target.call(data);

Note that call() returns a bool indicating whether the call succeeded. If the call reverts, this return value will be false. Otherwise, it will be true.

It’s possible to specify how much gas and how much ether are attached to the call:

target.call.gas(50000).value(1 ether)(data);

Using `call()` to Execute Arbitrary Function Calls

Our trivial multisig wallet uses the transfer() function to transfer ether to another address. To enable making arbitrary function calls, I’m going to use call() instead.

I need to add a new parameter for the message data, and this new parameter needs to be part of the signatures from the wallet owners:

function execute(
    ...
    bytes data,
    ...
)
    external
{
    bytes32 hash = prefixed(keccak256(abi.encodePacked(
        address(this), destination, value, data, nonce
    )));

Finally, I need to use call() to perform the function call, including transferring the specified amount of ether:

require(destination.call.value(value)(data));

Remember that if call() reverts, it returns false. I’m using require() to bubble that error up and revert the entire transaction if the call fails.

Summary

When the interface is known at compile time, Solidity provides nice high-level syntax for making external function calls.
When the interface is not known at compile time, the low-level call() function can be used to pass messages to other contracts.
A multisig wallet can be easily generalized to proxy arbitrary function calls using call() and encoded message data.

Full Source Code

multisig-execute.sol

pragma solidity ^0.4.24;

contract MultisigExecute {
    uint256 public nonce;     // (only) mutable state
    address[] public owners;  // immutable state

    constructor(address[] owners_) {
        owners = owners_;
    }

    function execute(
        address destination,
        uint256 value,
        bytes data,
        bytes32[] sigR,
        bytes32[] sigS,
        uint8[] sigV
    )
        external
    {
        bytes32 hash = prefixed(keccak256(abi.encodePacked(
            address(this), destination, value, data, nonce
        )));

        for (uint256 i = 0; i < owners.length; i++) {
            address recovered = ecrecover(hash, sigV[i], sigR[i], sigS[i]);
            require(recovered == owners[i]);
        }

        // If we make it here, all signatures are accounted for.
        nonce += 1;
        require(destination.call.value(value)(data));
    }

    function () payable {}

    // Builds a prefixed hash to mimic the behavior of eth_sign.
    function prefixed(bytes32 hash) internal pure returns (bytes32) {
        return keccak256(abi.encodePacked(
            "\x19Ethereum Signed Message:\n32", hash));
    }
}

call() can actually accept multiple parameters and do minimal ABI encoding at runtime. See the Solidity documentation for details. ↩

Anatomy of Transaction Data

Wed, 25 Jul 2018 12:46:04 -0400

[This blog post explains how transaction data is used to invoke smart contracts in Ethereum, but it is not necessary for learning Solidity programming. We write it for those of you who would like a deeper understanding of what is going on when a transaction is sent to a smart contract.]

In our previous post How Ethereum Transactions Work, we mentioned that the data field of a transaction encodes what (if any) smart contract function should be invoked. In this post, I’ll dive deeper into the specifics of the data field.

Smart Contracts Use Message Passing

Ethereum itself has no concept of a “function.” When a transaction is sent with a smart contract as the to address, the smart contract’s code is executed, and any data included in the transaction is made available to that code.

This technique is known as message passing. In a sense, every smart contract can be thought of as a single function that receives a single argument: a sequence of bytes. In Solidity, you can examine that raw sequence of bytes by accessing msg.data.

Solidity (and other languages) add the concept of “functions” on top of low-level message passing. This is essentially implemented as a big switch statement that invokes the right function based on the message data that was sent.

Function Selectors

Solidity uses the first four bytes of the message data to indicate which function to call. Specifically, the function selector is the first four bytes of the Keccak-256 hash of the function’s signature.

An example will help. The following is a standard function present in ERC20 token contracts:

function transfer(address to, uint256 value) public returns (bool success) {
    // ...
}

The canonical form of the function’s signature is the string transfer(address,uint256). (Note that parameter names and the return type are ignored when constructing the signature.)

The Keccak-256 hash of transfer(address,uint256) is, in hexadecimal, 0xa9059cbb2ab09eb219583f4a59a5d0623ade346d962bcd4e46b11da047c9049b.

The function selector is just the first four bytes of that hash: 0xa9059cbb.

Argument Encoding

After the four-byte function selector, Solidity treats the rest of the sent data as function arguments. The arguments are encoded according to the Application Binary Interface specification.

To ABI encode simple, statically-sized types, just pad with zeroes until each value is 32 bytes long:

The address 0x123456789a123456789a123456789a123456789a becomes 0x000000000000000000000000123456789a123456789a123456789a123456789a.
The number 5 becomes 0x0000000000000000000000000000000000000000000000000000000000000005.

For the full details of ABI encoding, I recommend the Solidity documentation.

Putting It All Together

The transaction data for the call transfer(0x123456789a123456789a123456789a123456789a, 5) is the concatenation of the following:

the function selector: 0xa9059cbb,
the padded address: 0x000000000000000000000000123456789a123456789a123456789a123456789a,
and the padded amount: 0x0000000000000000000000000000000000000000000000000000000000000005.

The full transaction data is then:

0xa9059cbb000000000000000000000000123456789a123456789a123456789a123456789a
0000000000000000000000000000000000000000000000000000000000000005

Using web3.js to Encode Transaction Data

Typically, there’s no need to manually encode transaction data. For most use cases, the encoding step is a transparent part of sending a transaction. For example, using web3.js:

contract.transfer("0x123456789a123456789a123456789a123456789a", 5);

For cases where the encoded transaction data is required, web3.js 0.2x.x provides the getData() function:

> contract.transfer.getData("0x123456789a123456789a123456789a123456789a", 5);
"0xa9059cbb000000000000000000000000123456789a123456789a123456789a123456789a0000000000000000000000000000000000000000000000000000000000000005"

(web3.js 1.0 beta has a similar function called encodeABI().)

Summary

Ethereum smart contracts work via message passing.
Function selectors tell Solidity code what function to execute.
Function arguments are ABI encoded and appended to message data.
Client libraries typically take care of the details of ABI encoding for you.

State Channels with Signing Keys

Wed, 18 Jul 2018 12:38:49 -0700

In this post, I’ll show how a temporary signing key can be used to improve the user experience of working with state channels.

State channels involve two parties exchanging off-chain signed messages. Those messages are typically signed with the participants’ Ethereum private keys. For security reasons, a DApp such as the one presented in Working with State Channels in JavaScript does not usually have have direct access to a user’s private key. Instead, it asks a web3 provider such as MetaMask to sign a message, and the user is presented with UI to approve the signature.

This flow can be cumbersome, requiring extra interactions from the user. This interaction with MetaMask for each signature can be avoided by signing messages directly in JavaScript with a temporary signing key.

You can try out the new version of the 21 game DApp to see the result.

Signing Key

State channels replace on-chain calls to smart contracts with digital signatures exchanged off-chain. The same Ethereum account is usually used for on-chain interactions and for off-chain signatures, but there’s no reason this has to be the case. All that matters is that the smart contract recognize the validity of the signature. Each participant can instead designate a different account that they will use to sign messages. The advantage of using a second account is that its private key can be known to JavaScript and thus used directly to sign messages without the help of something like MetaMask.

To support signing with a different key, I’ll need to make a few changes to the smart contract and to the JavaScript front end:

The JavaScript front end needs to generate a new private key and corresponding account to use for signing.
The smart contract needs to keep track of each participant’s signing account.
When signing messages, the front end needs to use the signing key to directly sign messages rather than invoking MetaMask.
When verifying a message, the signature must be checked against the expected signing account.

The rest of this post will go over the code changes in detail. The result is a new version of the 21 game DApp which doesn’t require the user to interact with MetaMask for each off-chain move.

Contract Changes

The smart contract needs to keep track of which accounts are being used for signatures:

mapping(address => address) signerFor;

Each participant’s signing account is passed to the smart contract as a parameter. The first player passes their account to the constructor, and the second player passes it to the join() function:

constructor(uint256 _timeoutInterval, address signer) public payable {
    // ...
    signerFor[player1] = signer;
}

function join(address signer) public payable {
    // ...
    signerFor[player2] = signer;
}

Finally, signatures need to be checked against the appropriate signing accounts in moveFromState():

// Old code:
// require(recoverSigner(message, sig) == opponentOf(msg.sender));

require(recoverSigner(message, sig) == signerFor[opponentOf(msg.sender)]);

Signing Keys in JavaScript

To support using separate signing accounts, the JavaScript front end needs to track two new pieces of state: signingKey and opponentSigner.

The signingKey is a private key generated locally in JavaScript ¹:

this.signingKey = ethereumjs.Wallet.generate().getPrivateKeyString();

From the generated private key, a public address is computed and passed to the smart contract when starting or joining a game:

start: function () {
  // ...
  var signer = '0x' +
    ethereumjs.Util.privateToAddress(this.signingKey).toString("hex");
  TwentyOneContract.new(600, signer, // ...
},

join: function () {
  // ...
  var signer = '0x' +
    ethereumjs.Util.privateToAddress(that.signingKey).toString("hex");
  contract.join(signer, // ...
}

The opponent’s signing account is fetched from the smart contract with a call to signerFor. For example:

contract.signerFor(player2, function (err, player2Signer) {
  // ...
  that.opponentSigner = player2Signer;
}

Signing and Verifying Messages in JavaScript

Instead of using web3.personal.sign() to prompt the user to sign with MetaMask, the new DApp signs directly with the signing key:

var sig = ethereumjs.Util.ecsign(prefixed(message),
  ethereumjs.Util.toBuffer(this.signingKey));
var rpcSig = "0x" +
   ethereumjs.Util.setLengthLeft(sig.r, 32).toString("hex") +
   ethereumjs.Util.setLengthLeft(sig.s, 32).toString("hex") +
   ethereumjs.Util.toBuffer(sig.v).toString("hex");

When receiving a message, its signature must be checked against the opponent’s signing account in updateIfValid():

// Old code:
// if (signer !== this.opponent.toLowerCase()) return;

if (signer !== this.opponentSigner.toLowerCase()) return;

Security Trade-Off

By using a separate signing key, users of the DApp no longer have to approve each signature. This is a significant usability improvement, but it presents a tradeoff between usability and security. In the original version of the DApp, the user was always responsible for the final approval of any signature. Although only a hash of the data was presented to the user, they could theoretically recreate the message and verify that they were signing the move they actually wanted to make.

When using a separate signing key that is directly handled in JavaScript, the user no longer has the ability to see and approve each message that is being signed. In the example of betting on a game, this means malicious JavaScript code could quietly sign and transmit very bad moves, causing the player to lose the game and therefore their wager.

I believe that in the case of the original DApp, this tradeoff is clearly worth it. Seeing a binary hash doesn’t really allow users to make an informed decision about what to sign, so users already needed to trust the JavaScript code in practice. It’s arguably more secure to allow the app to sign arbitrary messages but only with a one-off account limited in scope to a single game.

Summary

Although state channels typically use the same account for on-chain transactions and off-chain signatures, this is not a requirement.
Using a separate signing key can improve a state channel’s user experience.
This usability improvement comes with a security tradeoff.

Full Source Code

The full updated smart contract is below. You can view the source code for the updated DApp in your browser.

twentyone-signing-keys.sol

pragma solidity ^0.4.23;

contract TwentyOneGame {
    address public player1;
    address public player2;
    uint256 public betAmount;
    bool public gameOver;

    mapping(address => address) public signerFor;

    struct GameState {
        uint8 seq;
        uint8 num;
        address whoseTurn;
    }
    GameState public state;

    uint256 public timeoutInterval;
    uint256 public timeout = 2**256 - 1;

    event GameStarted();
    event TimeoutStarted();
    event MoveMade(address player, uint8 seq, uint8 value);


    // Setup methods

    constructor(uint256 _timeoutInterval, address signer) public payable {
        player1 = msg.sender;
        signerFor[player1] = signer;
        betAmount = msg.value;
        timeoutInterval = _timeoutInterval;
    }

    function join(address signer) public payable {
        require(player2 == 0, "Game has already started.");
        require(!gameOver, "Game was canceled.");
        require(msg.value == betAmount, "Wrong bet amount.");

        player2 = msg.sender;
        signerFor[player2] = signer;
        state.whoseTurn = player1;

        emit GameStarted();
    }

    function cancel() public {
        require(msg.sender == player1, "Only first player may cancel.");
        require(player2 == 0, "Game has already started.");

        gameOver = true;
        msg.sender.transfer(address(this).balance);
    }


    // Play methods

    function move(uint8 seq, uint8 value) public {
        require(!gameOver, "Game has ended.");
        require(msg.sender == state.whoseTurn, "Not your turn.");
        require(value >= 1 && value <= 3,
            "Move out of range. Must be between 1 and 3.");
        require(state.num + value <= 21, "Move would exceed 21.");
        require(state.seq == seq, "Incorrect sequence number.");

        state.num += value;
        state.whoseTurn = opponentOf(msg.sender);
        state.seq += 1;

        // Clear timeout
        timeout = 2**256 - 1;

        if (state.num == 21) {
            gameOver = true;
            msg.sender.transfer(address(this).balance);
        }

        emit MoveMade(msg.sender, seq, value);
    }

    function moveFromState(uint8 seq, uint8 num, bytes sig, uint8 value) public {
        require(seq >= state.seq, "Sequence number cannot go backwards.");

        bytes32 message = prefixed(keccak256(address(this), seq, num));
        require(recoverSigner(message, sig) ==
            signerFor[opponentOf(msg.sender)]);

        state.seq = seq;
        state.num = num;
        state.whoseTurn = msg.sender;

        move(seq, value);
    }

    function opponentOf(address player) internal view returns (address) {
        require(player2 != 0, "Game has not started.");

        if (player == player1) {
            return player2;
        } else if (player == player2) {
            return player1;
        } else {
            revert("Invalid player.");
        }
    }


    // Timeout methods

    function startTimeout() public {
        require(!gameOver, "Game has ended.");
        require(state.whoseTurn == opponentOf(msg.sender),
            "Cannot start a timeout on yourself.");

        timeout = now + timeoutInterval;
        emit TimeoutStarted();
    }

    function claimTimeout() public {
        require(!gameOver, "Game has ended.");
        require(now >= timeout);

        gameOver = true;
        opponentOf(state.whoseTurn).transfer(address(this).balance);
    }


    // Signature methods

    function splitSignature(bytes sig)
        internal
        pure
        returns (uint8, bytes32, bytes32)
    {
        require(sig.length == 65);

        bytes32 r;
        bytes32 s;
        uint8 v;

        assembly {
            // first 32 bytes, after the length prefix
            r := mload(add(sig, 32))
            // second 32 bytes
            s := mload(add(sig, 64))
            // final byte (first byte of the next 32 bytes)
            v := byte(0, mload(add(sig, 96)))
        }

        return (v, r, s);
    }

    function recoverSigner(bytes32 message, bytes sig)
        internal
        pure
        returns (address)
    {
        uint8 v;
        bytes32 r;
        bytes32 s;

        (v, r, s) = splitSignature(sig);

        return ecrecover(message, v, r, s);
    }

    // Builds a prefixed hash to mimic the behavior of eth_sign.
    function prefixed(bytes32 hash) internal pure returns (bytes32) {
        return keccak256("\x19Ethereum Signed Message:\n32", hash);
    }
}

In the full source code, the signing key is also persisted to the browser’s local storage. This prevents the key from being lost if the user refreshes the page or closes the browser. ↩

Writing a Trivial Multisig Wallet

Wed, 11 Jul 2018 10:15:50 -0700

This post will demonstrate a very simple multisig wallet. This multisig wallet requires unanimous consent for the transfer of funds, and the consent is collected off-chain via signed messages.

Multisig wallets can include lots of complexity including many of the following capabilities:

Supporting N-of-M voting
Supporting delegation of votes
Supporting transferring of votes
Supporting arbitrary actions
Supporting multiple outstanding votes via on-chain bookkeeping

This post goes to the other extreme:

Votes must be unanimous
No delegation or transferring of votes
The only action is transferring ether
Voting is done off-chain with a single on-chain validation

This post borrows some techniques and inspiration from Exploring Simpler Ethereum Multisig Contracts. The code here is, however, even simpler.

Immutable List of Owners

This multisig wallet has multiple owners, who must all agree before funds are transferred from the wallet to a destination account. The owners are stored in an array:

contract UnanimousMultiSig {
    address[] public owners;  // immutable state

    constructor(address[] owners_) {
        owners = owners_;
    }

    // more to come
}

Off-Chain Consensus

Agreement is done off-chain via signed messages. The signed messages include four components:

The destination account that should receive the ether.
The ether value that should be transferred.
The message’s (R,S,V) signature.
The sequential nonce of the message. The nonce prevents a message replay vulnerability. Each successful transfer increments the nonce by one.

To cause a transfer, all of the owners must produce signed messages that agree on the destination, the value, and the nonce. (The nonce must be the expected nonce.)

Once messages are collected from all owners, anybody can present them to the wallet to invoke the transfer:

uint256 public nonce;     // (only) mutable state

function transfer(
    address destination,
    uint256 value,
    bytes32[] sigR,
    bytes32[] sigS,
    uint8[] sigV
)
    external
{
    bytes32 hash = prefixed(keccak256(abi.encodePacked(
        address(this), destination, value, nonce
    )));

    for (uint256 i = 0; i < owners.length; i++) {
        address recovered = ecrecover(hash, sigV[i], sigR[i], sigS[i]);
        require(recovered == owners[i]);
    }

    // If we make it here, all signatures are accounted for.
    nonce += 1;
    destination.transfer(value);
}

The code above includes one subtlety: the messages must be presented to the wallet in the same order as the owners were originally presented to the contract’s constructor.

The prefixed function is borrowed from Signing and Verifying Messages in Ethereum and can be found in the full source code below.

Summary

Simple multisig wallets can have straightforward implementations.
Collecting signed messages off-chain helps simplify on-chain work.

The Complete Contract

unanimous.sol

pragma solidity ^0.4.24;

contract UnanimousMultiSig {
    uint256 public nonce;     // (only) mutable state
    address[] public owners;  // immutable state

    constructor(address[] owners_) {
        owners = owners_;
    }

    function transfer(
        address destination,
        uint256 value,
        bytes32[] sigR,
        bytes32[] sigS,
        uint8[] sigV
    )
        external
    {
        bytes32 hash = prefixed(keccak256(abi.encodePacked(
            address(this), destination, value, nonce
        )));

        for (uint256 i = 0; i < owners.length; i++) {
            address recovered = ecrecover(hash, sigV[i], sigR[i], sigS[i]);
            require(recovered == owners[i]);
        }

        // If we make it here, all signatures are accounted for.
        nonce += 1;
        destination.transfer(value);
    }

    function () payable {}

    // Builds a prefixed hash to mimic the behavior of eth_sign.
    function prefixed(bytes32 hash) internal pure returns (bytes32) {
        return keccak256(abi.encodePacked(
            "\x19Ethereum Signed Message:\n32", hash));
    }
}

Performing Multiple Actions Transactionally

Fri, 06 Jul 2018 08:41:23 -0700

This post will demonstrate a simple technique for combining multiple actions into a single transaction. This will enable you to be certain that you get “all or nothing” execution of the combined actions. It builds on Ensuring the Effects of a Transaction.

Suppose that you want to execute two or more actions as a unit such that either all of them or none of them execute. How would you do that? The simplest way is to combine all of them into a single transaction. Like in the previous post, this can be done in the constructor of a contract:

contract CombineTransactions {

    constructor (
        // parameters needed to execute and check transaction
    )
        public
        payable  // if needed
    {
        // record initial state

        // perform action 1
        // perform action 2
        // ...
        // perform action N

        // validate final state

        selfdestruct(msg.sender)
    }
}

If any of those actions fail, or if the final state isn’t correct, then the whole transaction will fail, which will revert the effects of all preceding actions.

Example: Arbitrage

A classic situation where all-or-nothing execution is desirable is arbitrage. Arbitrage opportunities present themselves when you can buy something for less than you can sell it for—typically from different entities. Without all-or-nothing execution, you would run the risk of buying something and then no longer being able to sell it at an advantageous price.

For this example, I will reuse the ITokenShop interface from Ensuring the Effects of a Transaction:

interface ITokenShop {
    function token() external returns (IERC20Token);
    function buy() external payable;
    function sell(uint256 amount) external;
}

Suppose that you found two token shops, with one selling tokens for less than the other is paying for them. You have found an arbitrage opportunity that you’d probably like to exploit by buying tokens and then immediately selling them for a profit. Doing that in an all-or-nothing fashion makes the transaction risk free (except for gas costs):

contract Arbitrage {
    constructor (
        ITokenShop buyShop,
        ITokenShop sellShop,
        uint256 amount
    )
        public
        payable
    {
        // First buy tokens from the shop with the lower price.
        buyShop.buy.value(msg.value)();

        // Then sell tokens to the shop with the higher price.
        sellShop.token().approve(sellShop, amount);
        sellShop.sell(amount);

        // Make sure we made a profit.
        require(address(this).balance > msg.value);

        selfdestruct(msg.sender);
    }
}

The code above follows the pattern of performing multiple actions in a single transaction.

The require at the end makes sure that the transaction was profitable. This check is necessary because the buyShop or sellShop might have changed prices between when you checked the price and when this transaction is executed.

The Complete Contract

arbitrage.sol

pragma solidity ^0.4.24;

import "../common/ierc20token.sol";

interface ITokenShop {
    function token() external returns (IERC20Token);
    function buy() external payable;
    function sell(uint256 amount) external;
}

contract Arbitrage {
    constructor (
        ITokenShop buyShop,
        ITokenShop sellShop,
        uint256 amount
    )
        public
        payable
    {
        // First buy tokens from the shop with the lower price.
        buyShop.buy.value(msg.value)();

        // Then sell tokens to the shop with the higher price.
        sellShop.token().approve(sellShop, amount);
        sellShop.sell(amount);

        // Make sure we made a profit.
        require(address(this).balance > msg.value);

        selfdestruct(msg.sender);
    }
}

Ensuring the Effects of a Transaction

Thu, 28 Jun 2018 11:35:44 -0700

This post will demonstrate a simple technique for ensuring that a transaction had the desired effects.

The Challenge

Suppose that you learn of a contract that purports to do something desirable, but you’re just not sure that it actually does what it is supposed to. What can you do to protect yourself?

Obviously, you can (and should) examine the contract’s code. You might find trusted auditors who can vouch for the code’s effect. But you may still be left with some concerns because the contract’s promises seem just too good to be true. Fortunately, it’s pretty easy to validate that a transaction had the desired effect before committing to it.

The technique is simple: create a special-purpose contract that performs the desired action and then revert if the desired effects did not take place.

An Example

Suppose that you want to buy a quantity of an ERC20 token. You find a contract that sell those tokens at a good price. You want to buy the tokens and be certain that the contract actually sells them at the correct price. This example will show you how to do that.

I’m going to assume this interface for the token seller:

interface ITokenShop {
    function token() external returns (IERC20Token);
    function buy() external payable;
    function sell(uint256 amount) external;
}

To execute a checked token purchase, the validating contract needs to know the address of the token seller, the token type, and the expected amount of tokens to be purchased. The ether to purchase the tokens will be attached to the deployment transaction.

contract Validator {

    constructor (
        ITokenShop ts,
        IERC20Token token,
        uint256 expectedAmount
    )
        public
        payable
    {
        // record the sender's beginning token balance
        uint256 before = token.balanceOf(msg.sender);

        // this contract buys the tokens
        ts.buy.value(msg.value)();

        // transfer the tokens to the sender
        token.transfer(msg.sender, expectedAmount);

        // check that the sender's final balance has increased
        // by expectedAmount
        require(token.balanceOf(msg.sender) == before+expectedAmount);

        selfdestruct(msg.sender);
    }
}

Note that this is a single-use contract. It has no functions other than the constructor, so everything happens at the time of deployment.

The constructor executes the purchase and checks that the number of tokens the sender owns increases appropriately. If not, the require fails and the transaction reverts. If it reverts, the sender only loses the gas needed to execute this transaction.

There is one subtlety above regarding the purchase of the tokens. This contract buys the tokens for itself using the buy function of the token seller. Because the purpose of the contract is to buy tokens for the sender, this contract must also transfer those tokens to the sender.

The contract self-destructs to save gas.

Simple Pattern

The contract above is a specific example of a very simple pattern that can be used for situations where you want to be certain of the effects of a given contract:

contract Validator {

    constructor (
        // parameters needed to execute and check transaction
    )
        public
        payable  // if needed
    {
        // record initial state

        // perform action

        // validate final state

        selfdestruct(msg.sender)
    }
}

A couple notes about this pattern:

The initial and final states are not typically the final states of this contract. More commonly, they are the initial and final states of the sender.
This transaction may include code after the desired action to transfer assets from the contract to the sender.

The Complete Contract

validator.sol

pragma solidity ^0.4.24;

import "../common/ierc20token.sol";

interface ITokenShop {
    function token() external returns (IERC20Token);
    function buy() external payable;
    function sell(uint256 amount) external;
}

contract Validator {

    constructor (
        ITokenShop ts,
        IERC20Token token,
        uint256 expectedAmount
    )
        public
        payable
    {
        // record the sender's beginning token balance
        uint256 before = token.balanceOf(msg.sender);

        // this contract buys the tokens
        ts.buy.value(msg.value)();

        // transfer the tokens to the sender
        token.transfer(msg.sender, expectedAmount);

        // check that the sender's final balance has increased
        // by expectedAmount
        require(token.balanceOf(msg.sender) == before+expectedAmount);

        selfdestruct(msg.sender);
    }
}

Working with State Channels in JavaScript

Sat, 23 Jun 2018 08:26:13 -0700

In this post, I’ll show how to build a JavaScript front end for a two-player game based on state channels.

This post is a continuation of my previous posts “Two-Player Games in Ethereum” and “State Channels for Two-Player Games.” This post assumes that you’ve read and understood those.

Overview

In a typical DApp, the role of the front end is to provide a friendly user interface for a smart contract. Data displayed comes directly from the smart contract’s state, and interactive UI elements result in function calls to the smart contract.

For a DApp based on state channels, the front end is more involved. In addition to interacting with the smart contract, it must handle off-chain interactions with another user. The state displayed is an aggregate of off-chain and on-chain information, and most interactions are peer-to-peer with an untrusted adversary.

The JavaScript front end in this post will do the following:

Deploy a new game contract or join an existing game as a second player.
Communicate moves to the other player via signed messages.
Track the current game state, including off-chain progress as well as the smart contract’s state.
Send transactions to the smart contract when necessary: either to end the game or to deal with timeouts.

Technology Used

The 21 game DApp uses web3.js version 0.2x.x. At the time of this writing, 1.0 is still in beta and not very compatible with MetaMask.

The DApp uses Vue.js to handle displaying data and responding to HTML events. I’m going to omit most of that plumbing in this post and focus on the Ethereum-specific concepts. In the code below, the this variable points to a Vue instance, and updates to its members result in updates to the HTML.

For exchanging messages between opponents, the DApp uses PubNub, a simple realtime communication platform. In particular, I’m using pub/sub over Websockets to exchange messages in the game. Again, I’m going to omit some details about PubNub in the code in this post.

If you want to see the details I’m omitting, the full source code for the DApp can be seen by using the “view source” feature in your browser.

Starting a New Game

The first player starts a new game by pressing the “Deploy contract” button. This has the effect of deploying the contract and setting up some event handlers:

var bytecode = "...";
var abi = [...];

TwentyOneContract = web3.eth.contract(abi);

...

start: function () {
  var that = this;

  // Deploy the contract, using a 10-minute timeout interval and a 0.01
  // ether wager.
  TwentyOneContract.new(600, {
    data: bytecode,
    gas: 2000000,
    value: web3.toWei(0.01, "ether"),
  }, function (err, contract) {

    if (err) return error(err);
    that.contract = contract;

    // Once the contract has been deployed...
    if (contract.address) {
      // Subscribe to messages and events.
      that.subscribe();

      log("Deployment succeeded. Contract address: " + contract.address);

      // Listen for when the game is started.
      that.contract.GameStarted(function () {
        that.contract.player2(function (err, opponent) {
          // Update our local state to reflect our opponent's address and
          // the fact that it's our turn.
          that.opponent = opponent;
          that.whoseTurn = that.account;
        });
      });
    } else {
      log("Deploying contract. Transaction hash: " + contract.transactionHash);
    }
  });
},

subscribe: function () {
  var that = this;
  this.contract.allEvents(function (err, event) {
    that.fetchContractState();
  });

  pubnub.subscribe({
    channels: ['21-' + this.contract.address],
  });
},

Here are a few notes about the above code:

A new contract is deployed for each game.
The bytecode and ABI come from the Solidity compiler. (I used Remix.)
The code listens for a GameStarted event, which happens when a second player joins the game.
The subscribe() function starts listening to a PubNub channel named after the contract’s address. PubNub channels do not require explicit creation. This function also listens for any changes from the contract and calls fetchContractState(), which will be described later in this post.
The callback for TwentyOneContract.new is called twice: first when the transaction is sent, and second when the transaction has been mined. The if (contract.address) conditional makes use of the contract only after it’s been deployed.

When the contract is deployed, its address is displayed to the user. They need to share this address with another user so that user can join the game. This can be done by email, text message, etc.

Joining an Existing Game

A player can join an existing game if they know the game contract’s address. The following code invokes the smart contract’s join() function:

join: function () {
  var address = this.$refs.address.value;

  var that = this;
  var contract = TwentyOneContract.at(address);

  contract.join({ value: web3.toWei(0.01, "ether") }, function (err, hash) {
    if (err) return error(err);

    waitForReceipt(hash, function (receipt) {
      if (receipt.status === "0x01") {
        log("Game joined.");
        that.contract = contract;
        that.opponent = player1;
        that.whoseTurn = player1;
        that.subscribe();
      }
    });
  });
},

Note that the code in the DApp is a bit more sophisticated than this. It also handles the case of resuming a game when the player is already participating. It checks the state of the contract to detect this case and then updates the local state to match the latest contract state.

Tracking Smart Contract State

For a state-channel based DApp, state changes can come from two places: the smart contract or messages received off-chain. The front end needs to handle both.

The local state includes the following:

account is the player’s address.
opponent is the opponent’s address.
contract is the deployed game contract.
seq is the last valid sequence number known to this client.
num is the game’s “number” associated with seq.
whoseTurn indicates whose turn is next.
pendingMove is the unacknowledged last move by account. It is null if no move is pending.
signature is the signature from the opponent’s last message.
timeout is when the current timeout, if any, expires. If there is no current timeout, this has the value of maxuint (2²⁵⁶ - 1).
latePlayer indicates which account must respond to the timeout.
gameOver indicates whether the game is over.

The fetchContractState() function reads the current state from the smart contract and updates the local state accordingly. Note that because state changes come from two places, there can be conflicts. These conflicts are resolved by using the game’s sequence number. A state change can be ignored if it has a lower sequence number than the local state:

fetchContractState: function () {
  var that = this;

  // Fetch the state from the contract.
  this.contract.state(function (err, state) {
    if (err) return error(err);

    var seq = state[0].toNumber();
    var num = state[1].toNumber();
    var whoseTurn = state[2];

    // Only update if the sequence number has increased.
    if (seq > that.seq) {
      that.seq = seq;
      that.num = num;
      that.whoseTurn = whoseTurn;
      that.pendingMove = null;
      that.signature = null;
    }

    // Fetch the timeout status from the contract.
    that.contract.timeout(function (err, timeout) {
      if (err) return error(err);

      if (timeout.equals(maxuint)) {
        // A value of 2^256-1 indicates no timeout.
        that.timeout = null;
        that.latePlayer = null;
      } else {
        that.timeout = timeout.toNumber();
        that.latePlayer = whoseTurn;
      }
    });

    // Check whether the game is over.
    that.contract.gameOver(function (err, gameOver) {
      if (err) return error(err);

      that.gameOver = gameOver;
    });
  });
},

Tracking Off-Chain State

When a player makes a move, it is sent via a PubNub message. The message includes the move that was made as well as a signature of the resulting state. If a received move and its signature are valid, the local state must be updated to reflect the move:

updateIfValid: function (move, signature) {
  if (this.whoseTurn !== this.opponent) return;
  if (move < 1 || move > 3) return;

  var num = this.num;
  var seq = this.seq;

  // First apply our pending move.
  if (this.pendingMove) {
    seq += 1;
    num += this.pendingMove;
  }

  seq += 1;
  num += move;

  if (num > 21) return;
  var message = prefixed(this.stateHash(seq, num));
  var signer = recoverSigner(message, signature);
  if (signer !== this.opponent.toLowerCase()) return;

  this.seq = seq;
  this.num = num;
  this.whoseTurn = this.account;
  this.pendingMove = null;
  this.signature = signature;
},

prefixed() and recoverSigner() are borrowed from our post “Writing a Simple Payment Channel.”

stateHash() computes the hash for a given game state:

stateHash: function (seq, number) {
  return "0x" + ethereumjs.ABI.soliditySHA3(
    ["address", "uint8", "uint8"],
    [this.contract.address, seq, number],
  ).toString("hex");
},

Here’s a brief explanation of the above code:

A move is only valid if it’s that player’s turn, the move is between 1 and 3, the resulting number does not exceed 21, and the signature is valid.
Invalid moves are silently ignored.
All moves are based on the latest state, including any pending move.

The idea of a “pending move” requires some explanation. It’s most easily understood in the context of an in-progress game:

The off-chain game state is: { seq: 3, num: 7, signature: ... }. (The signature is from my opponent and matches that state.)
I send my opponent a message with the move 3.
Due to a networking error, my opponent never sees that message and eventually starts a timeout via the smart contract.

To avoid forfeiting the game, I must respond to the timeout by calling moveFromState() on the smart contract. That function requires three things: the state I’m moving from, a signature from my opponent matching that state, and the move I would like to make.

If after step 2, I updated my local state to { seq: 4, num: 10 }, then I no longer have the information I need to call moveFromState(). Instead, I use the concept of a pending move and update the state to { seq: 3, num: 7, signature: ..., pendingMove: 3 }.

With that information, I can successfully call moveFromState() and resume the game.

If my opponent had seen my move and made their own move in response, I would just need to apply the pending move before processing theirs. This is exactly what updateIfValid() does.

Making Moves

A move can be made either on-chain, by sending a transaction, or off-chain, by sending a signed message to the opponent. By default, messages are sent off-chain to avoid transaction delays and expense. A message is sent on-chain in only two cases:

It’s the winning move. Sending a transaction is necessary here to claim the ether prize.
There’s a timeout running against this player. Calling move() on the smart contract clears the timeout and avoids forfeiting the game.

The JavaScript move() function checks for those cases and either sends an on-chain transaction or transmits a signed message via PubNub:

move: function (n) {
  var that = this;

  var message = this.stateHash(this.seq + 1, this.num + n);

  if (this.num + n === 21 || this.latePlayer === this.account) {
    // Send move to the contract if it's the winning move or there's a
    // timer running against us.
    this.contractMove(n);
  } else {
    // Otherwise send a signed message to our opponent.
    web3.personal.sign(
      message,
      web3.eth.defaultAccount,
      function (err, signature) {
        if (err) return error(err);

        pubnub.publish({
          channel: '21-' + that.contract.address,
          message: {
            move: n,
            signature: signature,
          },
        });

        that.whoseTurn = that.opponent;
        that.pendingMove = n;
      });
  }
},

Note that off-chain messages require updating pendingMove, as described in the previous section.

The contractMove() function handles sending a move to the smart contract with a transaction. The contract supports two different functions for submitting a move:

move() makes a move based on the current state known to the contract.
moveFromState() updates the contract with the latest signed state from the opponent and then makes a move on top of that.

The following code uses the appropriate contract method by checking whether the local state contains a signature or not. If there’s a signature, moveFromState() is called. If there is no signature, it means the most recent local state from the smart contract, so move() can be called directly:

contractMove: function (n, cb) {
  var that = this;

  function callback(err, hash) {
    if (err) return error(err);

    waitForReceipt(hash, function (receipt) {
      if (receipt.status === "0x01") {
        log("Move made.");
        if (cb) {
          cb();
        }
        that.fetchContractState();
      } else {
        error("Failed to submit move.");
      }
    });
  }

  if (this.signature) {
    this.contract.moveFromState(this.seq, this.num, this.signature, n,
      callback);
  } else {
    this.contract.move(this.seq, n, callback);
  }
},

Dealing with Timeouts

If a player stops making moves when it’s their turn, this is considered a forfeit. A timer is used to enforce this rule.

Three operations deal with timeouts:

A player can start a timeout when it’s their opponent’s turn.
A player can claim a timeout once it’s expired.
A player can stop a timeout by making a move.

To start a timeout, the player must first ensure that the contract knows it’s their opponent’s turn. To do that, they need to send their pending move (if any) to the smart contract before invoking startTimeout():

moveAndStartTimeout: function () {
  var that = this;

  function startTimeout() {
    that.contract.startTimeout(function (err, hash) {
      if (err) return error(err);

      waitForReceipt(hash, function (receipt) {
        if (receipt.status === "0x01") {
          log("Timeout started.");
        } else {
          log("Transaction failed.");
        }
      });

      that.fetchContractState();
    });
  }

  if (this.pendingMove) {
    log("Making latest move on-chain...");
    this.contractMove(this.pendingMove, startTimeout);
  } else {
    startTimeout();
  }
},

Once the timeout has expired, the winning player can call claimTimeout() to collect their winnings:

claimTimeout: function () {
  var that = this;

  this.contract.claimTimeout(function (err, hash) {
    if (err) return error(err);

    waitForReceipt(hash, function (receipt) {
      if (receipt.status === "0x01") {
        log("Timeout claimed.");
      } else {
        log("Transaction failed.");
      }
      that.fetchContractState();
    });
  });
},

No special code is required to stop a timeout, because this is already dealt with in the move() function from the previous section.

Canceling a Game

While waiting for an opponent to join, the player who started the game is allowed to cancel it:

cancelGame: function () {
  var that = this;

  this.contract.cancel(function (err, hash) {
    if (err) return error(err);

    waitForReceipt(hash, function (receipt) {
      if (receipt.status === "0x01") {
        log("Game canceled.");
        that.fetchContractState();
      }
    });
  });
},

Full Source Code

You can use “view source” in your browser to see the full code for the 21 game DApp.

To play the game by yourself, I recommend using two different browsers (e.g. Chrome and Firefox), rather than just two windows or tabs. This is because MetaMask’s account selection is per browser, so you’ll find yourself having to switch back and forth between accounts with each move. Using two different browsers means you can easily use a separate account with each.

Future Work

This code works, but there are a couple areas for improvement:

Retry logic: Right now, if a networking issue interrupts communication, the players have no choice but to make at least one on-chain transaction to resume the game. A simple fix would be to resend messages periodically until they’re acknowledged by the opponent.
Signature confirmation: Every move requires additional user interaction to sign a message. In the case of MetaMask, this is a popup that the user must click on. If the user is willing to trust the DApp code to a limited extent, it’s possible to avoid this by signing with a temporary generated account instead. I will explore this idea in a future post.

Supporting an Off-Chain Market Maker

Sat, 16 Jun 2018 06:33:49 -0700

This post will implement a token-trading “market maker” that will fulfill multiple signed prediction market wagers simultaneously. It will be a modest change to the clearinghouse contract presented earlier, and it will exploit the token-based prediction market contract unchanged.

Market makers (often known as “bookmakers”) strive to take many bets that will offset each other while collecting a percentage of the bets as their compensation. Typically, bookmakers take bets sequentially, ever mindful of whether the bets are offsetting each other. If the bets begin to represent a risk due to imbalance, the bookmaker may need to adjust their actions. For instance, they can change the odds to try to bring the booked bets into balance.

A bookmaker acts as a market maker by participating in bets themselves, typically in anticipation of future bets that will offset the current bets. By taking many bets concurrently, there is more opportunity to keep the books in balance (by rejecting bets if they clearly would skew the betting).

This contract will support an off-chain market maker for prediction markets. Exactly like the clearinghouse contract, trade offers (bets) will be proposed off-chain with signed messages.

Why Not Just Use the Clearinghouse Contract?

Given that the token-based prediction markets simply exchange tokens, and the clearinghouse contract handles off-chain token trading, why would a prediction market bookmaker need anything more? It’s because prediction market tokens can be bought and sold in bundles for a fixed price. A market maker can exploit this special property to accept bets that would otherwise have been impossible. An example will help.

Assume the following two independent prediction markets exist, with each winning token worth 1 (wrapped) ETH:

The NFC Championship, with two securities/tokens: COWBOYS and PACKERS.
The AFC Championship, with two securities: PATRIOTS and STEELERS.

Further, assume that the following two trades are proposed:

Alice would like to trade 1,000 COWBOYS tokens for 1,000 PATRIOTS tokens.
Bob would like to trade 1,000 PACKERS tokens for 1,000 STEELERS tokens.

A market maker contract can exploit the ability to buy and refund complete bundles of tokens to satisfy these exchanges by doing the following:

The market maker takes possession of the 1,000 COWBOYS and PACKERS tokens from Alice and Bob.
The market maker uses refundBundle on the NFC prediction market to exchange those for 1,000 wrapped ETH tokens.
The market maker uses buyBundle on the AFC prediction market to buy 1,000 AFC bundles (both PATRIOTS and STEELERS tokens) for those 1,000 wrapped ETH tokens.
The market maker distributes the 1,000 PATRIOTS tokens to Alice, and the 1,000 STEELERS tokens to Bob.

Without the contract’s ability to buy and refund bundles, it would have been impossible for the market maker to have orchestrated those trades directly.

Executing Trades

In the clearinghouse contract, multiple trades are executed in three steps:

All trades are validated.
Traded tokens are gathered.
Tokens are distributed.

The market maker contract for prediction markets will augment that with bundle buying and bundle refunding steps:

All trades are validated.
Traded tokens are gathered.
Bundles are refunded and bought.
Tokens are distributed.

The code for executeWagers below is the same as the clearinghouse’s executeOffers with the additional bundle buying/refunding step (and the corresponding parameters):

function executeWagers(
    address[] sellers,
    IERC20Token[] sellTokens,
    uint256[] sellAmounts,
    IERC20Token[] receiveTokens,
    uint256[] receiveAmounts,
    uint256[] timeLimits,
    uint256[] nonces,
    bytes32[] rs,
    bytes32[] ss,
    uint8[] vs,
    TokenPredictionMarket[] pms,
    int256[] bundleAmounts
)
    public
{
    require(msg.sender == owner);

    acceptOffers(
        sellers,
        sellTokens,
        sellAmounts,
        receiveTokens,
        receiveAmounts,
        timeLimits,
        nonces,
        rs,
        ss,
        vs
    );

    gatherOffers(sellers, sellTokens, sellAmounts);

    buyOrRefundBundles(pms, bundleAmounts);

    distributeOffers(sellers, receiveTokens, receiveAmounts);
}

The parameters for buying/refunding tokens use signed integers to represent amounts. Positive values represent buying bundles, and negative values represent refunds.

function buyOrRefundBundles(
    TokenPredictionMarket[] pms,
    int256[] amounts
)
    internal
{
    for (uint256 i = 0; i < pms.length; i++) {
        if (amounts[i] > 0) {
            buyBundle(pms[i], uint256(amounts[i]));
        } else {
            refundBundle(pms[i], uint256(-amounts[i]));
        }
    }
}

Buying Bundles

Buying bundles is straightforward. The contract approves transfer of payment tokens to the prediction market, it buys the bundle with those tokens, and then it puts all the bought tokens into the contract owner’s escrow accounts:

function buyBundle(
    TokenPredictionMarket pm,
    uint256 amount
)
    internal
{
    // approve transfer of payment tokens
    IERC20Token wt = pm.wagertoken();
    wt.approve(pm, amount);
    escrowBalance[owner][wt] -= amount;

    // buy the bundle
    pm.buyBundle(amount);

    // transfer bundle from this to owner and adjust escrow
    uint256 length = pm.outcomeCount();
    for (uint256 i = 0; i < length; i++) {
        IERC20Token t = IERC20Token(pm.tokens(i));
        escrowBalance[owner][t] += amount;
    }
}

Refunding Bundles

Similar logic holds for the refunding of bundles:

function refundBundle(
    TokenPredictionMarket pm,
    uint256 amount
)
    internal
{
    // approve transfer of bundle and adjust escrow
    uint256 length = pm.outcomeCount();
    for (uint256 i = 0; i < length; i++) {
        IERC20Token t = IERC20Token(pm.tokens(i));
        t.approve(pm, amount);
        escrowBalance[owner][t] -= amount;
    }

    // refund the bundle
    pm.refundBundle(amount);

    // account for the received tokens in owner's escrow account
    IERC20Token wt = pm.wagertoken();
    escrowBalance[owner][wt] += amount;
}

Summary

An off-chain market maker for prediction markets can be supported with a smart contract.
The smart contract is a simple adaptation of the clearinghouse contract.
The market maker can exploit the buying and refunding of bundles to accept more bets.

The Complete Contract

bookmaker.sol

pragma solidity ^0.4.24;

import "clearinghouse.sol";
import "wagertokenpredictionmarket.sol";

contract Bookmaker is Clearinghouse {

    constructor (uint256 _escrowTime)
        Clearinghouse(_escrowTime)
        public
    {
    }

    function buyBundle(
        TokenPredictionMarket pm,
        uint256 amount
    )
        internal
    {
        // approve transfer of payment tokens
        IERC20Token wt = pm.wagertoken();
        wt.approve(pm, amount);
        escrowBalance[owner][wt] -= amount;

        // buy the bundle
        pm.buyBundle(amount);

        // transfer bundle from this to owner and adjust escrow
        uint256 length = pm.outcomeCount();
        for (uint256 i = 0; i < length; i++) {
            IERC20Token t = IERC20Token(pm.tokens(i));
            escrowBalance[owner][t] += amount;
        }
    }

    function refundBundle(
        TokenPredictionMarket pm,
        uint256 amount
    )
        internal
    {
        // approve transfer of bundle and adjust escrow
        uint256 length = pm.outcomeCount();
        for (uint256 i = 0; i < length; i++) {
            IERC20Token t = IERC20Token(pm.tokens(i));
            t.approve(pm, amount);
            escrowBalance[owner][t] -= amount;
        }

        // refund the bundle
        pm.refundBundle(amount);

        // transfer the received tokens to owner
        IERC20Token wt = pm.wagertoken();
        escrowBalance[owner][wt] += amount;
    }

    function buyOrRefundBundles(
        TokenPredictionMarket[] pms,
        int256[] amounts
    )
        internal
    {
        for (uint256 i = 0; i < pms.length; i++) {
            if (amounts[i] > 0) {
                buyBundle(pms[i], uint256(amounts[i]));
            } else {
                refundBundle(pms[i], uint256(-amounts[i]));
            }
        }
    }

    function executeWagers(
        address[] sellers,
        IERC20Token[] sellTokens,
        uint256[] sellAmounts,
        IERC20Token[] receiveTokens,
        uint256[] receiveAmounts,
        uint256[] timeLimits,
        uint256[] nonces,
        bytes32[] rs,
        bytes32[] ss,
        uint8[] vs,
        TokenPredictionMarket[] pms,
        int256[] bundleAmounts
    )
        public
    {
        require(msg.sender == owner);

        acceptOffers(
            sellers,
            sellTokens,
            sellAmounts,
            receiveTokens,
            receiveAmounts,
            timeLimits,
            nonces,
            rs,
            ss,
            vs
        );

        gatherOffers(sellers, sellTokens, sellAmounts);

        buyOrRefundBundles(pms, bundleAmounts);

        distributeOffers(sellers, receiveTokens, receiveAmounts);
    }
}

Betting Tokens In A Prediction Market

Tue, 12 Jun 2018 07:37:58 -0700

This post will describe how to implement a prediction market where bets are for ERC20 tokens rather than ether.

My previous post on prediction markets supported betting ether. For some applications, it’s important to have the betting currency be ERC20 tokens, so I’m going to alter that previous implementation to accept tokens rather than ether. Note that it’s possible to wrap ether in a token, so this new contract will be strictly more general than the previous one.

Just like the previous prediction market contract, this contract will inherit the routines of the WagerBase contract, so all I need to do is to create the appropriate constructor and routines that accept and pay off bets. It’s a good idea to be familiar with that post before going further here.

Token-Based Prediction Market

Like the ether-based prediction market contract, this contract requires a proposition and possible outcomes. This contract also requires which ERC20 token will be the wagered token (as opposed to ether).

pragma solidity ^0.4.24;

import "wagerbase.sol";
import "ierc20token.sol";

contract TokenPredictionMarket is WagerBase {
    IERC20Token public wagertoken;

    constructor(
        string _proposition,
        bytes32[] _outcomes,
        bytes32[] _symbols,
        uint256 timeoutDelay,
        IERC20Token _wagertoken
    )
        // Just forward the parameters to the base constructor.
        WagerBase(_proposition, _outcomes, _symbols, timeoutDelay)
        public
    {
        wagertoken = _wagertoken;
    }

Buying Bundles

Outcome tokens are now bought in exchange for wagered tokens. The bettor must have approved the transfer of those wagered tokens prior to calling buyBundle:

function buyBundle(uint256 amount) public {
    require(wagertoken.transferFrom(msg.sender, address(this), amount),
        "failed wagertoken transfer");

    for (uint256 i = 0; i < outcomes.length; i++) {
        tokens[i].mint(msg.sender, amount);
    }
}

The bundle to tokens are minted for the purchase.

Refunding Bundles

Complete bundles of outcome tokens can be exchanged for wagered tokens. The bettor must approve the outcome tokens for transfer before calling refundBundle. Tokens representing each outcome are burned. The wagered tokens are transferred directly back to msg.sender.

function refundBundle(uint256 amount) public {
    for (uint256 i = 0; i < outcomes.length; i++) {
        tokens[i].burnFrom(msg.sender, amount);
    }

    require(wagertoken.transfer(msg.sender, amount),
        "failed wagertoken transfer");
}

Claiming Winnings

Once the contract is in the Resolved state, the winning tokens can be redeemed for wagered tokens. The bettor must have approved the transfer of the winning tokens prior to calling claim.

function claim() public {
    require(state == States.Resolved);

    uint256 amount = tokens[winningOutcome].balanceOf(msg.sender);
    tokens[winningOutcome].burnFrom(msg.sender, amount);

    require(wagertoken.transfer(msg.sender, amount),
        "failed wagertoken transfer");
}

Winning tokens are burned so that they may not be redeemed again.

Summary

Accepting a token is more general than accepting ether, because ether can be wrapped in an ERC20 token.
WagerBase is the basis for this token-wagering prediction market contract.
The bet-handling routines are nearly identical to their ether-handling cousins.

Full Source

wagertokenpredictionmarket.sol

pragma solidity ^0.4.24;

import "wagerbase.sol";
import "ierc20token.sol";

contract TokenPredictionMarket is WagerBase {
    IERC20Token public wagertoken;

    constructor(
        string _proposition,
        bytes32[] _outcomes,
        bytes32[] _symbols,
        uint256 timeoutDelay,
        IERC20Token _wagertoken
    )
        // Just forward the parameters to the base constructor.
        WagerBase(_proposition, _outcomes, _symbols, timeoutDelay)
        public
    {
        wagertoken = _wagertoken;
    }

    function buyBundle(uint256 amount) public {
        require(wagertoken.transferFrom(msg.sender, address(this), amount),
            "failed wagertoken transfer");

        for (uint256 i = 0; i < outcomes.length; i++) {
            tokens[i].mint(msg.sender, amount);
        }
    }

    function refundBundle(uint256 amount) public {
        for (uint256 i = 0; i < outcomes.length; i++) {
            tokens[i].burnFrom(msg.sender, amount);
        }

        require(wagertoken.transfer(msg.sender, amount),
            "failed wagertoken transfer");
    }

    function claim() public {
        require(state == States.Resolved);

        uint256 amount = tokens[winningOutcome].balanceOf(msg.sender);
        tokens[winningOutcome].burnFrom(msg.sender, amount);

        require(wagertoken.transfer(msg.sender, amount),
            "failed wagertoken transfer");
    }
}

Reversible Ether

Sat, 09 Jun 2018 09:13:25 -0700

In this post, I’ll develop an ERC20 token that acts as “reversible ether” as described by Ethereum’s creator, Vitalik Buterin:

Someone should come along and issue an ERC20 called "Reversible Ether" that is 1:1 backed by ether but has a DAO that can revert transfers within N days.

–Vitalik Buterin, April 2018

This idea is intriguing. In the world of credit cards and banks, it’s often possible to reverse transactions in the case of mistakes or fraud. In the world of cryptocurrencies, every transaction is final and irreversible. Vitalik’s tweet about “reversible ether” suggests doing two things:

Wrap ether in a token that allows for reversals.
Use a decentralized autonomous organization (DAO) to decide by group consensus what transactions should be reversed.

In this post, I’ll focus on just the first challenge. I’ll show how an ERC20 token can keep track of pending transfers and allow a trusted third party to reverse them. My “reversible ether” implementation will be based on the EtherToken contract we introduced in our post about wrapping ether in an ERC20 token.

Parameterization

Like EtherToken, ReversibleEther accepts a name and symbol for the token. It also accepts an escrowDuration, which specifies how long a transfer stays “pending.”

During that escrow period, a transfer can be reversed by a trusted arbiter account. (Keep in mind that the arbiter account could very well be a smart contract that implements some sort of group consensus protocol.)

contract ReversibleEther is EtherToken {
    address arbiter;
    uint256 escrowDuration;

    constructor(string _name, string _symbol, uint256 _escrowDuration)
        EtherToken(_name, _symbol)
        public
    {
        arbiter = msg.sender;
        escrowDuration = _escrowDuration;
    }

Two Balances and ERC20 Compatibility

Most ERC20 tokens have a straightforward notion of account balances: when a token is transferred to an account, that account’s balance increases by one token. That token can immediately be spent by transferring it to another account.

A reversible ether token can’t work that way. When a token is transferred, it is not immediately available to be spent. The transfer might be reversed until some escrow period has passed, e.g. 30 days.

My reversible ether implementation will keep track of two balances for each account. The first balance is just the typical ERC20 balanceOf. It is immediately updated for each token transfer.

The second balance is called availableBalanceOf, and it tracks what portion of an account’s balanceOf is currently available to be spent:

// balanceOf is inherited from EtherToken

mapping(address => uint256) public availableBalanceOf;

There are a number of ways to keep track of these balances, but using a balanceOf that is immediately updated on each transfer maximizes compatibility with the ERC20 token standard.

Buying and Selling Reversible Ether

ReversibleEther inherits buy() and sell() functions from EtherToken, but those functions need to be overridden to adjust availableBalanceOf correctly:

function buy() public payable {
    super.buy();
    availableBalanceOf[msg.sender] += msg.value;
}

function sell(uint256 amount) public {
    require(availableBalanceOf[msg.sender] >= amount, "Insufficient funds.");

    super.sell(amount);
    availableBalanceOf[msg.sender] -= amount;
}

Keeping Track of Pending Transfers

A token transfer immediately updates balanceOf, as in a typical ERC20 transfer, but it does not update availableBalanceOf. Instead, pending transfers are tracked in a global array and a per-recipient set:

struct PendingTransfer {
    address from;
    address to;
    uint256 amount;
    uint256 finalTimestamp;
    uint256 setIndex;  // index into pendingTransferSet[to]
}

// global array of pending transfers
PendingTransfer[] public pendingTransfers;

// per-recipient set of pending transfer (for ease of enumeration)
mapping(address => uint256[]) public pendingTransferSet;

Here’s a brief explanation of the code above:

The finalTimestamp keeps track of when the transfer can be considered final. After this time, it cannot be reversed.
pendingTransfers is a global array of all pending transfers. As pending transfers are deleted, the array will become sparse. Slots are never reused, so this array gives each transfer a unique and unchanging ID.
setIndex and pendingTransferSet are used together to implement a set, as described in my recent post “Storage Patterns: Set.” This makes it easy for a recipient to enumerate their pending transfers.

The internal helper function startTransfer() updates the appropriate data structures with the incoming transfer:

event Pending(address indexed from, address indexed to, uint256 index);

function startTransfer(address from, address to, uint256 value) internal {
    require(availableBalanceOf[from] >= value, "Insufficient funds.");
    availableBalanceOf[from] -= value;

    // Add to set of pending transfers for the recipient.
    uint256 newIndex = pendingTransfers.length;
    pendingTransferSet[to].push(newIndex);

    // Add to global array of pending transfers.
    pendingTransfers.push(PendingTransfer({
        from: from,
        to: to,
        amount: value,
        finalTimestamp: now + escrowDuration,
        setIndex: pendingTransferSet[to].length - 1
    }));

    emit Pending(from, to, newIndex);
}

Here’s a brief explanation of the above code:

The sender’s availableBalanceOf is checked and updated to reflect the transfer. (balanceOf is updated through the typical ERC20 transfer functions.)
The recipient’s pendingTransferSet is updated to include the ID of the new pending transfer.
The new pending transfer is appended to pendingTransfers.
finalTimestamp is set to escrowDuration in the future.
An event is emitted to make it easy for clients to know that the transfer is now pending.

The standard transfer() and transferFrom() inherited from EtherToken need to be overridden to call startTransfer():

function transfer(address to, uint256 value) public returns (bool) {
    startTransfer(msg.sender, to, value);
    return super.transfer(to, value);
}

function transferFrom(address from, address to, uint256 value)
    public
    returns (bool)
{
    startTransfer(from, to, value);
    return super.transferFrom(from, to, value);
}

Note that EtherToken’s implementations of transfer() and transferFrom() are guaranteed to either revert or return true. Otherwise, I would need to check their return values.

Finalizing Transfers

Once the escrow period has elapsed, a pending transfer can be considered final. The finalizeTransfer() function updates the recipient’s availableBalanceOf and removes the transfer from the pending transfer data structures:

event Finalized(address indexed from, address indexed to, uint256 index);
function finalizeTransfer(uint256 index) public {
    PendingTransfer storage pending = pendingTransfers[index];

    require(now >= pending.finalTimestamp);

    availableBalanceOf[pending.to] += pending.amount;
    emit Finalized(pending.from, pending.to, index);

    deletePendingTransfer(index);
}

Note that anyone can call this function, but it will likely be called by the recipient of the transfer. The pendingTransferSet makes it easy for a recipient to enumerate all their pending transfers and finalize those that are ready.

deletePendingTransfer() is a helper function that is responsible for cleaning up the data structures. Notably, it implements the swapping algorithm from “Storage Patterns: Set.”

function deletePendingTransfer(uint256 index) internal {
    PendingTransfer storage pending = pendingTransfers[index];

    uint256 setIndex = pending.setIndex;
    uint256[] storage set = pendingTransferSet[pending.to];

    // Swap with last element.
    uint256 lastValue = set[set.length - 1];
    set[setIndex] = lastValue;
    pendingTransfers[lastValue].setIndex = setIndex;

    // Shrink the set and delete the pending transfer.
    set.length -= 1;
    delete pendingTransfers[index];
}

Reversing Transfers

During the escrow period, it’s possible for the trusted third-party arbiter to reverse the transfer:

event Reversed(address indexed from, address indexed to, uint256 index);
function reversePendingTransfer(uint256 index) public {
    require(msg.sender == arbiter);

    PendingTransfer storage pending = pendingTransfers[index];

    require(now < pending.finalTimestamp);

    balanceOf[pending.to] -= pending.amount;
    balanceOf[pending.from] += pending.amount;
    // All changes to balanceOf should emit ERC20 Transfer events.
    emit Transfer(pending.to, pending.from, pending.amount);

    availableBalanceOf[pending.from] += pending.amount;
    emit Reversed(pending.from, pending.to, index);

    deletePendingTransfer(index);
}

Here’s a brief explanation of that code:

Only the arbiter is allowed to reverse transfers.
Transfers can only be reversed during the escrow period.
Reversing a transfer updates balanceOf for both accounts.
An ERC20 Transfer event is emitted to reflect the change in balances.
The recipient’s availableBalanceOf increases, because those funds are immediately available for spending.
The Reversed event makes it easy for clients to observe the reversal.
deletePendingTransfer() is used again here to clean up the pending transfer data structures.

Summary

Reversible ether is a “wrapped ether” token that allows transfers to be reversed within a given escrow period.
To support reversals, the token must keep track of two balances: the total amount of tokens owned and the amount currently available for spending.
When building a token with new semantics, it’s important to consider compatibility with existing standards and tools.

Full Source Code

reversibleether.sol

pragma solidity ^0.4.24;

import "ethertoken.sol";

contract ReversibleEther is EtherToken {
    address arbiter;
    uint256 escrowDuration;

    constructor(string _name, string _symbol, uint256 _escrowDuration)
        EtherToken(_name, _symbol)
        public
    {
        arbiter = msg.sender;
        escrowDuration = _escrowDuration;
    }

    // balanceOf is inherited from EtherToken

    mapping(address => uint256) public availableBalanceOf;

    function buy() public payable {
        super.buy();
        availableBalanceOf[msg.sender] += msg.value;
    }

    function sell(uint256 amount) public {
        require(availableBalanceOf[msg.sender] >= amount, "Insufficient funds.");

        super.sell(amount);
        availableBalanceOf[msg.sender] -= amount;
    }

    struct PendingTransfer {
        address from;
        address to;
        uint256 amount;
        uint256 finalTimestamp;
        uint256 setIndex;  // index into pendingTransferSet[to]
    }

    // global array of pending transfers
    PendingTransfer[] public pendingTransfers;

    // per-recipient set of pending transfer (for ease of enumeration)
    mapping(address => uint256[]) public pendingTransferSet;

    event Pending(address indexed from, address indexed to, uint256 index);

    function startTransfer(address from, address to, uint256 value) internal {
        require(availableBalanceOf[from] >= value, "Insufficient funds.");
        availableBalanceOf[from] -= value;

        // Add to set of pending transfers for the recipient.
        uint256 newIndex = pendingTransfers.length;
        pendingTransferSet[to].push(newIndex);

        // Add to global array of pending transfers.
        pendingTransfers.push(PendingTransfer({
            from: from,
            to: to,
            amount: value,
            finalTimestamp: now + escrowDuration,
            setIndex: pendingTransferSet[to].length - 1
        }));

        emit Pending(from, to, newIndex);
    }

    function transfer(address to, uint256 value) public returns (bool) {
        startTransfer(msg.sender, to, value);
        return super.transfer(to, value);
    }

    function transferFrom(address from, address to, uint256 value)
        public
        returns (bool)
    {
        startTransfer(from, to, value);
        return super.transferFrom(from, to, value);
    }

    event Finalized(address indexed from, address indexed to, uint256 index);
    function finalizeTransfer(uint256 index) public {
        PendingTransfer storage pending = pendingTransfers[index];

        require(now >= pending.finalTimestamp);

        availableBalanceOf[pending.to] += pending.amount;
        emit Finalized(pending.from, pending.to, index);

        deletePendingTransfer(index);
    }

    function deletePendingTransfer(uint256 index) internal {
        PendingTransfer storage pending = pendingTransfers[index];

        uint256 setIndex = pending.setIndex;
        uint256[] storage set = pendingTransferSet[pending.to];

        // Swap with last element.
        uint256 lastValue = set[set.length - 1];
        set[setIndex] = lastValue;
        pendingTransfers[lastValue].setIndex = setIndex;

        // Shrink the set and delete the pending transfer.
        set.length -= 1;
        delete pendingTransfers[index];
    }

    event Reversed(address indexed from, address indexed to, uint256 index);
    function reversePendingTransfer(uint256 index) public {
        require(msg.sender == arbiter);

        PendingTransfer storage pending = pendingTransfers[index];

        require(now < pending.finalTimestamp);

        balanceOf[pending.to] -= pending.amount;
        balanceOf[pending.from] += pending.amount;
        // All changes to balanceOf should emit ERC20 Transfer events.
        emit Transfer(pending.to, pending.from, pending.amount);

        availableBalanceOf[pending.from] += pending.amount;
        emit Reversed(pending.from, pending.to, index);

        deletePendingTransfer(index);
    }

    function pendingTransferCount(address addr)
        public
        view
        returns (uint256)
    {
        return pendingTransferSet[addr].length;
    }
}

Supporting Off-Chain Token Trading

Wed, 06 Jun 2018 07:56:25 -0700

This post will implement a token trading “clearinghouse” that will execute multiple signed trade offers simultaneously.

A clearinghouse accepts trade offers from multiple parties and works to execute transactions among those parties. A clearinghouse may also act as a market maker and directly trade with those parties. In this post, the trades will be exchanges of ERC20 tokens for other ERC20 tokens.

For example, the clearinghouse could execute a pair of perfectly matched trades like the following:

X wants to trade 1 P for 1 Q (where P and Q are different tokens)
Y wants to trade 1 Q for 1 P

A more interesting example would be the following:

X wants to trade 3 P’s for 3 Q’s
Y wants to trade 2 Q’s for 2 P’s
Z wants to trade 1 Q for 1 P

In that case, a clearinghouse could orchestrate a simultaneous three-way trade.

While the supported trades will only involve two tokens each, that doesn’t mean that an orchestrated trade could not be for many different tokens. For instance, the following three trades could be supported:

X wants to trade 1 R for 1 S
Y wants to trade 1 S for 1 T
Z wants to trade 1 T for 1 R

Trade Offers

Traders will send signed trade offers to the off-chain clearinghouse. Periodically, the clearinghouse will send some of those signed offers to the smart contract, which will then execute the proposed trades.

Signed trade offers have many components:

The token and amount of that token being offered.
The token and amount of that token expected to be received.
The expiration time after which this offer is no longer valid.
A unique nonce to prevent replay vulnerabilities.
The signature that proves the seller’s identity.

The mechanism for signing a message and subsequently validating it within a contract were described in our post on signed messages.

There are two components in this system: an off-chain clearinghouse that puts trades together and a smart contract that executes those trades. In this post, I’ll focus on just the smart contract.

Escrowed Tokens

This system will rely on escrowed tokens from sellers to back their trade offers. I use our escrow contract to manage the escrow mechanics. The Escrow contract handles token deposits and withdrawals for traders as well as for the clearinghouse’s owner.

pragma solidity ^0.4.24;

import "ierc20token.sol";
import "signature.sol";
import "escrow.sol";

contract Clearinghouse is Escrow, Signature {
    address owner;

    constructor (uint256 _escrowTime)
        Escrow(_escrowTime)
        public
    {
        owner = msg.sender;
    }

In addition to configuring escrow duration, the constructor also records the owner of the contract. Only the owner can submit signed trades to be executed.

Clearinghouse inherits from Signature, which provides routines for handling signed messages. Its source code is provided at the end of this post.

Validating a Sale Offer

The only difference between validating a signed message in this contract and the technique we described previously is the encoding of the signature. Previously, we used a single byte sequence containing the r, s, and v components, but now I’m going to keep those values separate. (I’m doing so to overcome a Solidity limitation, which I’ll point out when it’s relevant.)

mapping(address => mapping(uint256 => bool)) public usedNonces;

function validateOffer(
    address seller,
    IERC20Token sellToken,
    uint256 sellAmount,
    IERC20Token receiveToken,
    uint256 receiveAmount,
    uint256 timeLimit,
    uint256 nonce,
    bytes32 r,
    bytes32 s,
    uint8 v
)
    public
    view
{
    require(now < timeLimit, "Offer has expired.");
    require(!usedNonces[seller][nonce], "Duplicate nonce.");

    bytes32 message = prefixed(
        keccak256(abi.encodePacked(
            address(this),
            sellToken,
            sellAmount,
            receiveToken,
            receiveAmount,
            timeLimit,
            nonce
        ))
    );
    require(ecrecover(message, v, r, s) == seller, "Invalid signature.");
}

A valid message meets three criteria:

The trade must not have expired.
The trade must have an unused nonce.
The trade offer’s signature must be validated.

Single Sale

A clearinghouse typically executes many trades simultaneously, and this contract will support that. But first I want to show how to execute a single signed trade offer. A single trade is between the seller and the clearinghouse:

function executeOffer(
    address seller,
    IERC20Token sellToken,
    uint256 sellAmount,
    IERC20Token receiveToken,
    uint256 receiveAmount,
    uint256 timeLimit,
    uint256 nonce,
    bytes32 r,
    bytes32 s,
    uint8 v

)
    public
{
    require(msg.sender == owner, "Only the owner can execute offers.");

    validateOffer(
        seller,
        sellToken,
        sellAmount,
        receiveToken,
        receiveAmount,
        timeLimit,
        nonce,
        r,
        s,
        v
    );

    usedNonces[seller][nonce] = true;

    transfer(seller, owner, sellToken, sellAmount);
    transfer(owner, seller, receiveToken, receiveAmount);
}

A few things to note about the single trade:

Only owner can submit a signed trade.
The offer must be validated.
The transfer function, which is inherited from Escrow, checks that there are sufficient tokens available and then transfers them.

Simultaneous Sales

The examples at the beginning of the post demonstrated the power of submitting simultaneous trades. This contract will support simultaneous trades in a single transaction. Interestingly, processing multiple trades is not as simple as just iterating over the trades and executing them sequentially.

An example will make it clear why sequential trading won’t work. Recall the example where X wants to trade 1 P for 1 Q and Y wants to do the reverse. A clearinghouse could broker such a trade because X can provide 1 P to Y, and Y can provide 1 Q to X. But, it would be impossible for the clearinghouse to complete either trade fully before starting the other trade because the clearinghouse might not own any P or Q tokens.

How would a real world clearinghouse execute this trade between X and Y? It would first get 1 P from X and then it would get 1 Q from Y. After that, it would distribute the Q to X and the P to Y. That is, it would execute the trades in two phases, first accumulating all the tokens being offered, and then distributing all the tokens being received.

This contract will validate all the offers, then gather all the tokens before distributing them:

function executeOffers(
    address[] sellers,
    IERC20Token[] sellTokens,
    uint256[] sellAmounts,
    IERC20Token[] receiveTokens,
    uint256[] receiveAmounts,
    uint256[] timeLimits,
    uint256[] nonces,
    bytes32[] rs,
    bytes32[] ss,
    uint8[] vs
)
    public
{
    require(msg.sender == owner, "Only the owner can execute offers.");

    acceptOffers(
        sellers,
        sellTokens,
        sellAmounts,
        receiveTokens,
        receiveAmounts,
        timeLimits,
        nonces,
        rs,
        ss,
        vs
    );
    gatherOffers(sellers, sellTokens, sellAmounts);
    distributeOffers(sellers, receiveTokens, receiveAmounts);
}

Note that the function takes many arrays of simple values, including the r, s, and v values. It would be more convenient to pass those all in arrays of structs or packed values, but Solidity doesn’t yet support that. That’s why they are unpacked.

The first phase validates all the offers and marks their nonces as used:

function acceptOffers(
    address[] sellers,
    IERC20Token[] sellTokens,
    uint256[] sellAmounts,
    IERC20Token[] receiveTokens,
    uint256[] receiveAmounts,
    uint256[] timeLimits,
    uint256[] nonces,
    bytes32[] rs,
    bytes32[] ss,
    uint8[] vs
)
    internal
{
    for (uint256 i = 0; i < sellers.length; i++) {
        validateOffer(
            sellers[i],
            sellTokens[i],
            sellAmounts[i],
            receiveTokens[i],
            receiveAmounts[i],
            timeLimits[i],
            nonces[i],
            rs[i],
            ss[i],
            vs[i]
        );

        usedNonces[sellers[i]][nonces[i]] = true;
    }
}

Gathering all the offered tokens is a simple loop over the offers, transferring them to owner:

function gatherOffers(
    address[] sellers,
    IERC20Token[] sellTokens,
    uint256[] sellAmounts
)
    internal
{
    for (uint256 i = 0; i < sellers.length; i++) {
        transfer(sellers[i], owner, sellTokens[i], sellAmounts[i]);
    }
}

Distributing tokens to the sellers is also a simple loop, this time transferring from owner:

function distributeOffers(
    address[] sellers,
    IERC20Token[] receiveTokens,
    uint256[] receiveAmounts
)
    internal
{
    for (uint256 i = 0; i < sellers.length; i++) {
        transfer(owner, sellers[i], receiveTokens[i], receiveAmounts[i]);
    }
}

Clearinghouse Participation

The clearinghouse can participate in trading implicitly. If the accepted trades do not fully offset each other, it’s the clearinghouse contract that must make up the difference. This is what happens in the single-trade function above, but it can just as easily happen in the multiple-trade function as well.

Sometimes, accepted trades will work out in the clearinghouse’s favor. Suppose the following trades are offered to the clearinghouse:

X offers to trade 1 P for 1 Q
Y offers to trade 2 Q’s for 1 P

If the clearinghouse presents these two trades to the contract, both X and Y will get their respective tokens, but the clearinghouse will own the extra Q afterwards!

Why Escrow?

This contract could have been written without escrowed tokens. It could have relied instead on ERC20’s approve and transferFrom functions for transferring tokens between parties. This would have presented a vulnerability that I wanted to avoid: a transferFrom might fail if tokens became unavailable. If a transferFrom failed in a multiple-trade transaction, then all the trades would fail, and I wanted to avoid this possibility.

Summary

A “clearinghouse” combines 3rd-party trades, which may not have been acceptable individually.
A clearinghouse may act as a market maker and participate in trading.
Signed messages enable the clearinghouse to operate off-chain except for the final simultaneous trading.
Escrowed tokens enable the clearinghouse to be certain that trading will succeed.

The Complete Contract

clearinghouse.sol

pragma solidity ^0.4.24;

import "ierc20token.sol";
import "signature.sol";
import "escrow.sol";

contract Clearinghouse is Escrow, Signature {
    address owner;

    constructor (uint256 _escrowTime)
        Escrow(_escrowTime)
        public
    {
        owner = msg.sender;
    }

    mapping(address => mapping(uint256 => bool)) public usedNonces;

    function validateOffer(
        address seller,
        IERC20Token sellToken,
        uint256 sellAmount,
        IERC20Token receiveToken,
        uint256 receiveAmount,
        uint256 timeLimit,
        uint256 nonce,
        bytes32 r,
        bytes32 s,
        uint8 v
    )
        public
        view
    {
        require(now < timeLimit, "Offer has expired.");
        require(!usedNonces[seller][nonce], "Duplicate nonce.");

        bytes32 message = prefixed(
            keccak256(abi.encodePacked(
                address(this),
                sellToken,
                sellAmount,
                receiveToken,
                receiveAmount,
                timeLimit,
                nonce
            ))
        );
        require(ecrecover(message, v, r, s) == seller, "Invalid signature.");
    }

    function executeOffer(
        address seller,
        IERC20Token sellToken,
        uint256 sellAmount,
        IERC20Token receiveToken,
        uint256 receiveAmount,
        uint256 timeLimit,
        uint256 nonce,
        bytes32 r,
        bytes32 s,
        uint8 v

    )
        public
    {
        require(msg.sender == owner, "Only the owner can execute offers.");

        validateOffer(
            seller,
            sellToken,
            sellAmount,
            receiveToken,
            receiveAmount,
            timeLimit,
            nonce,
            r,
            s,
            v
        );

        usedNonces[seller][nonce] = true;

        transfer(seller, owner, sellToken, sellAmount);
        transfer(owner, seller, receiveToken, receiveAmount);
    }


    function acceptOffers(
        address[] sellers,
        IERC20Token[] sellTokens,
        uint256[] sellAmounts,
        IERC20Token[] receiveTokens,
        uint256[] receiveAmounts,
        uint256[] timeLimits,
        uint256[] nonces,
        bytes32[] rs,
        bytes32[] ss,
        uint8[] vs
    )
        internal
    {
        for (uint256 i = 0; i < sellers.length; i++) {
            validateOffer(
                sellers[i],
                sellTokens[i],
                sellAmounts[i],
                receiveTokens[i],
                receiveAmounts[i],
                timeLimits[i],
                nonces[i],
                rs[i],
                ss[i],
                vs[i]
            );

            usedNonces[sellers[i]][nonces[i]] = true;
        }
    }

    function gatherOffers(
        address[] sellers,
        IERC20Token[] sellTokens,
        uint256[] sellAmounts
    )
        internal
    {
        for (uint256 i = 0; i < sellers.length; i++) {
            transfer(sellers[i], owner, sellTokens[i], sellAmounts[i]);
        }
    }

    function distributeOffers(
        address[] sellers,
        IERC20Token[] receiveTokens,
        uint256[] receiveAmounts
    )
        internal
    {
        for (uint256 i = 0; i < sellers.length; i++) {
            transfer(owner, sellers[i], receiveTokens[i], receiveAmounts[i]);
        }
    }

    function executeOffers(
        address[] sellers,
        IERC20Token[] sellTokens,
        uint256[] sellAmounts,
        IERC20Token[] receiveTokens,
        uint256[] receiveAmounts,
        uint256[] timeLimits,
        uint256[] nonces,
        bytes32[] rs,
        bytes32[] ss,
        uint8[] vs
    )
        public
    {
        require(msg.sender == owner, "Only the owner can execute offers.");

        acceptOffers(
            sellers,
            sellTokens,
            sellAmounts,
            receiveTokens,
            receiveAmounts,
            timeLimits,
            nonces,
            rs,
            ss,
            vs
        );
        gatherOffers(sellers, sellTokens, sellAmounts);
        distributeOffers(sellers, receiveTokens, receiveAmounts);
    }
}

signature.sol

pragma solidity ^0.4.24;

contract Signature {    
    function splitSignature(bytes sig)
    internal
    pure
    returns (uint8, bytes32, bytes32)
    {
        require(sig.length == 65);

        bytes32 r;
        bytes32 s;
        uint8 v;

        assembly {
            // first 32 bytes, after the length prefix
            r := mload(add(sig, 32))
            // second 32 bytes
            s := mload(add(sig, 64))
            // final byte (first byte of the next 32 bytes)
            v := byte(0, mload(add(sig, 96)))
        }

        return (v, r, s);
    }

    function recoverSigner(bytes32 message, bytes sig)
    internal
    pure
    returns (address)
    {
        uint8 v;
        bytes32 r;
        bytes32 s;

        (v, r, s) = splitSignature(sig);

        return ecrecover(message, v, r, s);
    }

    // Builds a prefixed hash to mimic the behavior of eth_sign.
    function prefixed(bytes32 hash) internal pure returns (bytes32) {
        return keccak256(abi.encodePacked(
            "\x19Ethereum Signed Message:\n32", hash));
    }
}

Storage Patterns: Set

Sun, 03 Jun 2018 07:14:02 -0700

In this post, I’ll build a minimal enumerable set in Solidity. A set stores unordered values without repetition.

Set Functionality

The implementation in this post will support the following primitive set operations:

Add a value to the set.
Remove a value from the set.
Test whether the set contains a given value.
Enumerate all values in the set.

Many implementations additionally implement set-theoretical operations:

Find the union of two sets.
Find the intersection of two sets.
Find the difference between two sets.

I won’t write those higher level functions here, but note that they can be easily implemented using the primitive operations.

Combining Data Structures

A mapping from value types to booleans provides much of a set’s functionality. It efficiently supports adding and removing items as well as testing for membership. What it doesn’t support is enumeration.

An array works well for enumeration, but it doesn’t support efficiently finding an existing item.

To support all the primitive operations efficiently, I will combine the two data structures. In this example code, I’ve chosen bytes32 as the data type being stored in the set, but the pattern generalizes to any data type:

contract Set {
    bytes32[] public items;

    // 1-based indexing into the array. 0 represents non-existence.
    mapping(bytes32 => uint256) indexOf;

The items array is where the values are stored, in no particular order. This allows for efficient enumeration.

The indexOf mapping keeps track of which values are contained within the set and where they can be found in the items array.

In Solidity, mappings do not have a notion of existence. Every key maps to something, and the default value is 0. This is a bit of a problem, because 0 is also the first index into the items array. To resolve this ambiguity, indexOf will hold 1-based indexes:

If indexOf[value] == 0, then the value does not exist in the set.
If indexOf[value] == n, where n > 0, then items[n - 1] == value.

Adding Items

To add an item to the set, it must be appended to the items array, and it’s new (1-based) index must be stored in indexOf:

function add(bytes32 value) public {
    if (indexOf[value] == 0) {
        items.push(value);
        indexOf[value] = items.length;
    }
}

Recall that sets do not allow repeated elements. The if statement ensures that an item is not added multiple times.

Testing for Membership

The indexOf mapping makes it easy to efficiently test for set membership:

function contains(bytes32 value) public view returns (bool) {
    return indexOf[value] > 0;
}

Removing Items

Removing an item involves updating both the indexOf mapping and the items array. Updating the mapping is straightforward, but it’s less obvious how an item can be efficiently deleted from the middle of an array.

The key to implementing this operation efficiently is to recall that items in a set are unordered. Because we don’t need to preserve order, we can shuffle items around to make our lives easier. To remove the item from the array, we first swap it to the end of the array and then shrink the array:

function remove(bytes32 value) public {
    uint256 index = indexOf[value];

    require(index > 0);

    // move the last item into the index being vacated
    bytes32 lastValue = items[items.length - 1];
    items[index - 1] = lastValue;  // adjust for 1-based indexing
    indexOf[lastValue] = index;

    items.length -= 1;
    indexOf[value] = 0;
}

Enumeration

Because it’s a public state variable, the Solidity compiler generates a getter for the items array. A client can call items(n) to retrieve the n^th item from the array.

To enumerate the entire list, the client also needs to know how many items there are. The count() function provides this:

function count() public view returns (uint256) {
    return items.length;
}

Summary

A set stores values, unordered and without repetition.
An enumerable set can be efficiently implemented with a mapping and an array.

Full Source Code

set.sol

pragma solidity ^0.4.24;

contract Set {
    bytes32[] public items;

    // 1-based indexing into the array. 0 represents non-existence.
    mapping(bytes32 => uint256) indexOf;

    function add(bytes32 value) public {
        if (indexOf[value] == 0) {
            items.push(value);
            indexOf[value] = items.length;
        }
    }

    function remove(bytes32 value) public {
        uint256 index = indexOf[value];

        require(index > 0);

        // move the last item into the index being vacated
        bytes32 lastValue = items[items.length - 1];
        items[index - 1] = lastValue;  // adjust for 1-based indexing
        indexOf[lastValue] = index;

        items.length -= 1;
        indexOf[value] = 0;
    }

    function contains(bytes32 value) public view returns (bool) {
        return indexOf[value] > 0;
    }

    function count() public view returns (uint256) {
        return items.length;
    }
}

Escrowing ERC20 Tokens

Wed, 30 May 2018 08:56:35 -0700

[EDIT 2018-06-05] This post has been edited to introduce a transfer function.

This post describes a simple contract to escrow ERC20 tokens for a period of time. Keeping tokens (or ether) in escrow is a common pattern in smart contracts.

Escrow is particularly important for off-chain components that work with signed messages. Such a component often needs certainty that a token transfer promised via a signature can be fulfilled.

A simple procedure for escrowing tokens is as follows:

An account approves a token transfer to the trusted smart contract.
The smart contract transfers those tokens to itself, holding them in escrow.
An account cannot withdraw escrowed tokens without first signaling the desire to end escrow.
The escrow period ends a fixed amount of time after the signal to end escrow.
Once the escrow period ends, the account may withdraw any remaining tokens.

The pattern above was exploited in the payment channel post, for instance, where ether was kept in escrow rather than ERC20 tokens.

Cancellation Period

This contract is parameterized with the escrow duration. When an account wishes to withdraw its tokens, this is how long it must wait before the withdrawal is allowed.

contract Escrow {
    uint256 public escrowTime;

    constructor(uint256 _escrowTime) public {
        escrowTime = _escrowTime;
    }

    // more to come
}

Tracking Per-Token Balances and Expirations

To make the escrow fully general, the contract does not assume a specific ERC20 token, so a single account may escrow different tokens at the same time. For each (account, token) pair, the contract tracks its balance and the time when escrow expires:

mapping(address => mapping(address => uint256)) public escrowBalance;
mapping(address => mapping(address => uint256)) public escrowExpiration;

Deposit

Depositing tokens works with the familiar ERC20 pattern of approve()/transferFrom(). Once the depositor has approved the transfer, they can call deposit() to move the tokens into the escrow contract. The escrow expiration time is initialized to the maximum allowed time, making it effectively infinite.

function deposit(IERC20Token token, uint256 amount) public {
    require(token.transferFrom(msg.sender, this, amount));
    escrowBalance[msg.sender][token] += amount;
    escrowExpiration[msg.sender][token] = 2**256-1;
}

Withdrawal

Withdrawing tokens is a two-step process. First, the withdrawal is started. This sets the escrowExpiration time to escrowTime in the future and emits an event announcing the updating expiration time:

event StartWithdrawal(address indexed account, address token, uint256 time);

function startWithdrawal(IERC20Token token) public {
    uint256 expiration = now + escrowTime;
    escrowExpiration[msg.sender][token] = expiration;
    emit StartWithdrawal(msg.sender, token, expiration);
}

After the escrow time has expired, all of the (remaining) escrowed tokens can be transferred back to their original owner:

function withdraw(IERC20Token token) public {
    require(now > escrowExpiration[msg.sender][token],
        "Funds still in escrow.");

    uint256 amount = escrowBalance[msg.sender][token];
    escrowBalance[msg.sender][token] = 0;
    require(token.transfer(msg.sender, amount));
}

Transferring Tokens

Contracts require escrowed tokens to assure the ability to transfer those tokens. Therefore, the contract supports a transfer function that enables transferring tokens between accounts. This routine would only be called by a subcontract of Escrow.

function transfer(
    address from,
    address to,
    IERC20Token token,
    uint256 tokens
)
    internal
{
    require(escrowBalance[from][token] >= tokens, "Insufficient balance.");

    escrowBalance[from][token] -= tokens;
    escrowBalance[to][token] += tokens;
}

Escrowing Ether

This contract supports escrowing any ERC20 tokens, but it does not directly help escrow ether. One can, however, wrap ether in an ERC20 token to effectively escrow ether with this contract.

Summary

Escrow is a common pattern in smart contracts, especially those with off-chain components.
This contract can escrow any tokens of all ERC20 types for any account.
This contract doesn’t do anything other than escrow tokens—its value is in being incorporated in a contract that needs escrow functionality.

The Complete Contract

escrow.sol

pragma solidity ^0.4.24;

import "./ierc20token.sol";

contract Escrow {
    uint256 public escrowTime;

    constructor(uint256 _escrowTime) public {
        escrowTime = _escrowTime;
    }

    mapping(address => mapping(address => uint256)) public escrowBalance;
    mapping(address => mapping(address => uint256)) public escrowExpiration;

    function deposit(IERC20Token token, uint256 amount) public {
        require(token.transferFrom(msg.sender, this, amount));
        escrowBalance[msg.sender][token] += amount;
        escrowExpiration[msg.sender][token] = 2**256-1;
    }

    event StartWithdrawal(address indexed account, address token, uint256 time);

    function startWithdrawal(IERC20Token token) public {
        uint256 expiration = now + escrowTime;
        escrowExpiration[msg.sender][token] = expiration;
        emit StartWithdrawal(msg.sender, token, expiration);
    }

    function withdraw(IERC20Token token) public {
        require(now > escrowExpiration[msg.sender][token],
            "Funds still in escrow.");

        uint256 amount = escrowBalance[msg.sender][token];
        escrowBalance[msg.sender][token] = 0;
        require(token.transfer(msg.sender, amount));
    }

    function transfer(
        address from,
        address to,
        IERC20Token token,
        uint256 tokens
    )
        internal
    {
        require(escrowBalance[from][token] >= tokens, "Insufficient balance.");

        escrowBalance[from][token] -= tokens;
        escrowBalance[to][token] += tokens;
    }
}

Wrapping Ether in an ERC20 Token

Sat, 26 May 2018 07:58:51 -0700

In this short post, I’ll show how ether can be “wrapped” in an ERC20-compatible token. This means ether can be used anywhere that an ERC20 token is expected.

Why Wrap Ether?

Ether is the native currency of Ethereum. It predates ERC20 and other token standards, so it doesn’t have the same interface. This can be the source of complexity in smart contracts. If a smart contract is to accept all types of currency, it must implement two interfaces: one for ether and one for ERC20 tokens.

“Wrapping” ether solves this problem by introducing a layer of indirection. Users can purchase ERC20-compatible “ether tokens” for native ether, at a 1:1 exchange rate. Then they can use those tokens with any smart contract that understands ERC20. Finally, the tokens can be exchanged back for ether, again at a 1:1 exchange rate.

The term “wrapping” comes from a token called W-ETH. That implementation is very similar to the contract presented in this post.

EtherToken

EtherToken inherits from BaseERC20Token, which can be found in our post on changing the total supply of ERC20 tokens.

The number of decimals is fixed at 18 to match ether. (One ether is 10¹⁸ wei.) The totalSupply begins at 0. This will be increased when users buy tokens for ether.

pragma solidity ^0.4.24;

import "baseerc20token.sol";

contract EtherToken is BaseERC20Token {
    constructor(string _name, string _symbol)
        BaseERC20Token(0, 18, _name, _symbol) public
    {
    }

Buying Tokens

Tokens can be purchased for ether at a 1:1 exchange rate:

function buy() public payable {
    balanceOf[msg.sender] += msg.value;
    totalSupply += msg.value;

    emit Transfer(address(0), msg.sender, msg.value);
}

The purchaser’s balance is increased, as is the total supply of tokens. Like in our MintableToken contract, a Transfer event from address 0 indicates that new tokens were created.

Selling Tokens

Tokens can be sold back to the contract in exchange for ether, again at a 1:1 rate:

function sell(uint256 amount) public {
    require(balanceOf[msg.sender] >= amount, "Insufficient balance.");

    balanceOf[msg.sender] -= amount;
    totalSupply -= amount;
    msg.sender.transfer(amount);

    emit Transfer(msg.sender, address(0), amount);
}

The Transfer event to address 0x0 indicates that tokens were destroyed.

Summary

Wrapping ether in an ERC20 token is convenient for handling both ether and ERC20 tokens in the same contract.
W-ETH is an existing implementation that you can use.
Building such a token yourself requires only adding buy() and sell() functions to a typical ERC20 token implementation.

Full Source Code

ethertoken.sol

pragma solidity ^0.4.24;

import "baseerc20token.sol";

contract EtherToken is BaseERC20Token {
    constructor(string _name, string _symbol)
        BaseERC20Token(0, 18, _name, _symbol) public
    {
    }

    function buy() public payable {
        balanceOf[msg.sender] += msg.value;
        totalSupply += msg.value;

        emit Transfer(address(0), msg.sender, msg.value);
    }

    function sell(uint256 amount) public {
        require(balanceOf[msg.sender] >= amount, "Insufficient balance.");

        balanceOf[msg.sender] -= amount;
        totalSupply -= amount;
        msg.sender.transfer(amount);

        emit Transfer(msg.sender, address(0), amount);
    }
}

Writing a Prediction Market Contract

Tue, 22 May 2018 05:33:00 -0700

This post will demonstrate how to write a smart contract that implements a prediction market. The contract will leverage much of the logic in my token-based parimutuel betting contract.

Token-Based Design

A prediction market is a way to bet on a future event by creating “contingent securities” that represent the possible outcomes. Once the outcome is determined, shares of the correct security have a predetermined value and the rest of the securities are worthless. An example will help.

A prediction market could be set up to forecast which NFL football team will win the Super Bowl. For this, there would be be 32 different securities, with each NFL team associated with shares of its own security. Bettors would buy and sell shares of these securities knowing that only the shares of a single security will have value. For all of my examples, I will assume that a winning share is worth 1 ETH.

The simplest prediction markets rely on three ideas:

Bettors can buy a “bundle” that consists of an equal number of shares of every security. If a winning share is worth 1 ETH, then a bundle containing one share of every security costs 1 ETH. Note that this exchange is perfect in the sense that the prediction market collects 1 ETH per bundle and will ultimately owe exactly 1 ETH for the share of the winning security/outcome.
Bettors can buy and sell individual shares at mutually agreed upon prices.
Once the outcome is known, bettors can redeem winning shares for 1 ETH.

Similarities to Token-Based Parimutuel Wagering

Prediction markets and parimutuel wagering have a lot in common and only a few differences:

Both are parameterized by the same values: a proposition and a number of possible outcomes.
Both can be in the same Open, Closed, Resolved or Cancelled states.
Both can have outcomes represented by ERC20 tokens.
Both ultimately reward only one token.
In parimutuel betting, outcome tokens are bought individually from the contract. In prediction markets, complete bundles are bought from the contract.
In parimutuel betting, payoffs have a modestly complex computation based on proportional ownership of tokens. In prediction markets, the payoff is 1:1 (ether to tokens).

Basically, everything from the token-based parimutuel post can be reused for a prediction market contract except for the routines that handle ether: bet, claim, and refund. I have put all the common code in a base contract called WagerBase, which is included at the end of this post. I will describe the new ether-handling routines for a prediction market fully.

Buying Bundles

Bettors buy complete bundles, 1:1 for the ether provided:

function buyBundle() public payable {
    for (uint256 i = 0; i < outcomes.length; i++) {
        tokens[i].mint(msg.sender, msg.value);
    }
}

Note that buyBundle does not need to be limited to the Open state. This is because every outcome is being purchased, and the winning token will only pay 1:1, so there’s no way to gain an advantage by buying late.

Refunding Bundles

Bettors can also sell complete bundles back to the contract:

function refundBundle(uint256 amount) public {
    for (uint256 i = 0; i < outcomes.length; i++) {
        tokens[i].burnFrom(msg.sender, amount);
    }
    msg.sender.transfer(amount);
}

Note that refundBundle is also not limited to any particular contract state (e.g., Open, Closed, etc.).

The ability to refund complete bundles is helpful to bettors who might bet on different outcomes as the prices of the underlying tokens change. In the process of doing that, they might find themselves with complete bundles and not want to wait until the market is resolved to cash in on those complete bundles.

Claiming Winnings

After the proposition has been resolved, winning tokens can be redeemed 1:1 for ether:

function claim() public {
    require(state == States.Resolved);

    uint256 amount = tokens[winningOutcome].balanceOf(msg.sender);
    tokens[winningOutcome].burnFrom(msg.sender, amount);
    msg.sender.transfer(amount);
}

Cancellations

If a prediction market is cancelled, participants should be able to get a refund for their purchased tokens. A complete bundle always has a clear value, but what about individual tokens that aren’t part of a bundle? I see three options for how to handle this:

Don’t do anything special. Complete bundles can already be refunded. Bettors can always cooperate to create complete bundles that can be refunded, and they will have an incentive to do so.
Refund proportionally. A simple scheme would be to provide refunds based on an equal division. If there are N outcomes, then each token can be refunded for 1/N ETH.
Designate a Cancellation Outcome. The contract creator could designate particular token as the “Cancellation Token” and resolve the contract in favor of that token. This means that cancellation would simply be another outcome that bettors could choose to bet on.

I’ve chosen to do nothing special. Bettors can still get refunds with a little cooperation, and this option is the easiest to implement correctly.

Summary

Prediction markets can be implemented with ERC20 tokens.
Prediction markets and token-based parimutuel wagering are very similar and can share a great deal of code.

The Complete Contracts

prediction.sol

pragma solidity ^0.4.23;

import "wagerbase.sol";

contract PredictionMarket is WagerBase {
    constructor(
        string _proposition,
        bytes32[] _outcomes,
        bytes32[] _symbols,
        uint256 timeoutDelay
    )
        // Just forward the parameters to the base constructor.
        WagerBase(_proposition, _outcomes, _symbols, timeoutDelay)
        public
    {
    }

    function buyBundle() public payable {
        for (uint256 i = 0; i < outcomes.length; i++) {
            tokens[i].mint(msg.sender, msg.value);
        }
    }

    function refundBundle(uint256 amount) public {
        for (uint256 i = 0; i < outcomes.length; i++) {
            tokens[i].burnFrom(msg.sender, amount);
        }
        msg.sender.transfer(amount);
    }

    function claim() public {
        require(state == States.Resolved);

        uint256 amount = tokens[winningOutcome].balanceOf(msg.sender);
        tokens[winningOutcome].burnFrom(msg.sender, amount);
        msg.sender.transfer(amount);
    }
}

wagerbase.sol

pragma solidity ^0.4.23;

import "mintabletoken.sol";

contract WagerBase {
    address public owner;

    string public proposition;
    bytes32[] public outcomes;
    bytes32[] public symbols;
    uint256 public timeout;
    MintableToken[] public tokens;

    constructor(
        string _proposition,
        bytes32[] _outcomes,
        bytes32[] _symbols,
        uint256 timeoutDelay
    )
        public
    {
        owner = msg.sender;
        proposition = _proposition;
        outcomes = _outcomes;
        symbols = _symbols;
        timeout = now + timeoutDelay;

        for (uint256 i = 0; i < _outcomes.length; i++) {
            tokens.push(new MintableToken(0, 18, toString(_outcomes[i]),
                toString(_symbols[i])));
        }
    }

    function toString(bytes32 b) internal pure returns (string) {
        // Convert a null-terminated bytes32 to a string.

        uint256 length = 0;
        while (length < 32 && b[length] != 0) {
            length += 1;
        }

        bytes memory bytesString = new bytes(length);
        for (uint256 j = 0; j < length; j++) {
            bytesString[j] = b[j];
        }

        return string(bytesString);
    }

    enum States { Open, Closed, Resolved, Cancelled }
    States state = States.Open;

    uint256 winningOutcome;

    function close() public {
        require(state == States.Open);
        require(msg.sender == owner);

        state = States.Closed;
    }

    function resolve(uint256 _winningOutcome) public {
        require(state == States.Closed);
        require(msg.sender == owner);

        winningOutcome = _winningOutcome;
        state = States.Resolved;
    }

    function cancel() public {
        require(state != States.Resolved);
        require(msg.sender == owner || now > timeout);

        state = States.Cancelled;
    }

    function outcomeCount() public view returns (uint256) {
        return outcomes.length;
    }
}

Using Tokens for Parimutuel Wagers

Fri, 18 May 2018 05:21:04 -0700

This post describes an alternative implementation of parimutuel wagering to my original post. This implementation will use ERC20 tokens to represent wagers.

Tokens for Outcomes

The original contract used a mapping to keep track of how much each account had wagered on each outcome. The new contract will delegate that bookkeeping to mintable ERC20 token contracts that represent the outcomes.

For each outcome, there will be a different token. To bet on an outcome, a bettor buys tokens representing that outcome from the parimutuel contract. These tokens are minted on demand. To claim their winnings once the bet is settled, a bettor sells tokens back to the parimutuel contract. These tokens are then burned.

Parameterization

The token-based parimutuel contract is very similar to the original. It’s parameterized in the same way, with descriptions of the proposition and outcomes. The constructor also accepts an array of “symbols” that are used for ERC20 tokens. The constructor’s significant difference is that it must deploy token contracts for each of the possible outcomes:

contract TokenizedParimutuelContract {
    address public owner;

    string public proposition;
    bytes32[] public outcomes;
    bytes32[] public symbols;
    uint256 public timeout;
    MintableToken[] public tokens;

    constructor(
        string _proposition,
        bytes32[] _outcomes,
        bytes32[] _symbols,
        uint256 timeoutDelay
    )
        public
    {
        owner = msg.sender;
        proposition = _proposition;
        outcomes = _outcomes;
        symbols = _symbols;
        timeout = now + timeoutDelay;

        for (uint256 i = 0; i < _outcomes.length; i++) {
            tokens.push(new MintableToken(0, 18, toString(_outcomes[i]),
                toString(_symbols[i])));
        }
    }

See the full source code at the end of the post for the implementation of toString.

Betting

Betting is nearly identical to the previous contract. The difference is that wagers are tracked by minting tokens for the bettor:

function bet(uint256 outcome) public payable {
    require(state == States.Open);

    tokens[outcome].mint(msg.sender, msg.value);
    totalPerOutcome[outcome] += msg.value;
    total += msg.value;
    require(total < 2 ** 128);   // avoid overflow possibility
}

Claiming Winnings

Once a winning outcome has been declared, anyone can exchange winning tokens for ether. First, the token holder must approve a transfer of the tokens to the parimutuel contract. Then the bettor can call claim which burns the redeemed tokens so that they can never be redeemed again.

function claim() public {
    require(state == States.Resolved);

    uint256 amount = tokens[winningOutcome].balanceOf(msg.sender);
    uint256 value = amount * total / totalPerOutcome[winningOutcome];
    tokens[winningOutcome].burnFrom(msg.sender, amount);
    msg.sender.transfer(value);
}

Note that we can be certain that the multiplication cannot overflow because of the limit on total enforced in bet.

Refunding a Cancelled Bet

If a bet is cancelled, token holders can claim a refund. Ether is returned and tokens are burned:

function refund(uint256 outcome) public {
    require(state == States.Cancelled);

    uint256 amount = tokens[outcome].balanceOf(msg.sender);
    tokens[outcome].burnFrom(msg.sender, amount);
    msg.sender.transfer(amount);
}

Other Functions

The other functions of the original contract (close, resolve, and cancel) are unchanged in this new contract.

Token Comparison

Using mintable ERC20 tokens provides one advantage over the previous contract—it allows wagers to be bought and sold without any needed support from the parimutuel contract itself. This is useful to people who would like to hedge their bets after the proposition has closed but before it has been resolved.

This token-based implementation has one disadvantage compared to the original—it limits the number of outcomes to the number of tokens that can be deployed by the constructor. The original contract could conceivably have supported 2²⁵⁶-1 different outcomes. (To avoid running out of gas, the outcomes array would have to be ignored.)

The Complete Contract

tokenizedparimutuel.sol

pragma solidity ^0.4.23;

import "mintabletoken.sol";

contract TokenizedParimutuelContract {
    address public owner;

    string public proposition;
    bytes32[] public outcomes;
    bytes32[] public symbols;
    uint256 public timeout;
    MintableToken[] public tokens;

    constructor(
        string _proposition,
        bytes32[] _outcomes,
        bytes32[] _symbols,
        uint256 timeoutDelay
    )
        public
    {
        owner = msg.sender;
        proposition = _proposition;
        outcomes = _outcomes;
        symbols = _symbols;
        timeout = now + timeoutDelay;

        for (uint256 i = 0; i < _outcomes.length; i++) {
            tokens.push(new MintableToken(0, 18, toString(_outcomes[i]),
                toString(_symbols[i])));
        }
    }

    function toString(bytes32 b) internal pure returns (string) {
        // Convert a null-terminated bytes32 to a string.

        uint256 length = 0;
        while (length < 32 && b[length] != 0) {
            length += 1;
        }

        bytes memory bytesString = new bytes(length);
        for (uint256 j = 0; j < length; j++) {
            bytesString[j] = b[j];
        }

        return string(bytesString);
    }

    enum States { Open, Closed, Resolved, Cancelled }
    States state = States.Open;

    mapping(uint256 => uint256) public totalPerOutcome;
    uint256 public total;

    uint256 winningOutcome;

    function bet(uint256 outcome) public payable {
        require(state == States.Open);

        tokens[outcome].mint(msg.sender, msg.value);
        totalPerOutcome[outcome] += msg.value;
        total += msg.value;
        require(total < 2 ** 128);   // avoid overflow possibility
    }

    function close() public {
        require(state == States.Open);
        require(msg.sender == owner);

        state = States.Closed;
    }

    function resolve(uint256 _winningOutcome) public {
        require(state == States.Closed);
        require(msg.sender == owner);

        winningOutcome = _winningOutcome;
        state = States.Resolved;
    }

    function claim() public {
        require(state == States.Resolved);

        uint256 amount = tokens[winningOutcome].balanceOf(msg.sender);
        uint256 value = amount * total / totalPerOutcome[winningOutcome];
        tokens[winningOutcome].burnFrom(msg.sender, amount);
        msg.sender.transfer(value);
    }

    function cancel() public {
        require(state != States.Resolved);
        require(msg.sender == owner || now > timeout);

        state = States.Cancelled;
    }

    function refund(uint256 outcome) public {
        require(state == States.Cancelled);

        uint256 amount = tokens[outcome].balanceOf(msg.sender);
        tokens[outcome].burnFrom(msg.sender, amount);
        msg.sender.transfer(amount);
    }
}

Changing the Supply of ERC20 Tokens

Wed, 16 May 2018 05:15:24 -0700

[EDIT 2018-05-25] This post has been edited to introduce a BaseERC20Token contract.

This short post will add dynamic control of the total supply of tokens to the previously introduced simple ERC20 tokens.

Our previous ERC20 tokens made the simplifying assumption that the token’s total supply did not change. I’m going to relax that assumption in this post by allowing the owner to increase the token supply with a “mint” function. Similarly, “burn” and “burnFrom” functions can decrease the total supply.

Future posts will make use of the ability to dynamically create and destroy tokens.

Setting the Initial Token Supply

The new MintableToken contract will inherit from a BaseERC20Token contract and augment that with functions to mint and burn tokens. BaseERC20Token is a fully parameterized version of the SimpleERC20Token contract. The full source code can be found at the end of this post.

pragma solidity ^0.4.23;

import "baseerc20token.sol";

contract MintableToken is BaseERC20Token {
    address public owner = msg.sender;

    constructor(
        uint256 _totalSupply,
        uint8 _decimals,
        string _name,
        string _symbol
    ) BaseERC20Token(_totalSupply, _decimals, _name, _symbol) public
    {
    }

    // more to come
}

Minting Tokens

The contract’s owner can create new tokens by calling mint. This increases the total token supply and grants ownership of the new tokens to the specified recipient:

function mint(address recipient, uint256 amount) public {
    require(msg.sender == owner);
    require(totalSupply + amount >= totalSupply); // Overflow check

    totalSupply += amount;
    balanceOf[recipient] += amount;
    emit Transfer(address(0), recipient, amount);
}

Burning Tokens

Anyone can destroy a portion or all of the tokens they own by calling burn. The specified amount is removed not only from the caller’s token balance but also from the token’s total supply:

function burn(uint256 amount) public {
    require(amount <= balanceOf[msg.sender]);

    totalSupply -= amount;
    balanceOf[msg.sender] -= amount;
    emit Transfer(msg.sender, address(0), amount);
}

By convention, burning tokens emits a Transfer event with the address 0x0 as the recipient.

It’s often useful to be able to burn tokens on behalf of another account. The burnFrom function borrows logic from ERC20’s transferFrom:

function burnFrom(address from, uint256 amount) public {
    require(amount <= balanceOf[from]);
    require(amount <= allowance[from][msg.sender]);

    totalSupply -= amount;
    balanceOf[from] -= amount;
    allowance[from][msg.sender] -= amount;
    emit Transfer(from, address(0), amount);
}

Summary

This contract supports dynamic changes to the total supply of tokens.
This contract exploits inheritance to extend the BaseERC20Token contract.

Full Source Code

baseerc20token.sol

pragma solidity ^0.4.23;

contract BaseERC20Token {
    mapping (address => uint256) public balanceOf;

    string public name;
    string public symbol;
    uint8 public decimals;
    uint256 public totalSupply;

    event Transfer(address indexed from, address indexed to, uint256 value);

    constructor (
        uint256 _totalSupply,
        uint8 _decimals,
        string _name,
        string _symbol
    )
        public
    {
        name = _name;
        symbol = _symbol;
        decimals = _decimals;

        totalSupply = _totalSupply;
        balanceOf[msg.sender] = _totalSupply;
        emit Transfer(address(0), msg.sender, _totalSupply);
    }

    function transfer(address to, uint256 value) public returns (bool success) {
        require(balanceOf[msg.sender] >= value);

        balanceOf[msg.sender] -= value;
        balanceOf[to] += value;
        emit Transfer(msg.sender, to, value);
        return true;
    }

    event Approval(address indexed owner, address indexed spender, uint256 value);

    mapping(address => mapping(address => uint256)) public allowance;

    function approve(address spender, uint256 value)
        public
        returns (bool success)
    {
        allowance[msg.sender][spender] = value;
        emit Approval(msg.sender, spender, value);
        return true;
    }

    function transferFrom(address from, address to, uint256 value)
        public
        returns (bool success)
    {
        require(value <= balanceOf[from]);
        require(value <= allowance[from][msg.sender]);

        balanceOf[from] -= value;
        balanceOf[to] += value;
        allowance[from][msg.sender] -= value;
        emit Transfer(from, to, value);
        return true;
    }
}

mintable.sol

pragma solidity ^0.4.23;

import "baseerc20token.sol";

contract MintableToken is BaseERC20Token {
    address public owner = msg.sender;

    constructor(
        uint256 _totalSupply,
        uint8 _decimals,
        string _name,
        string _symbol
    ) BaseERC20Token(_totalSupply, _decimals, _name, _symbol) public
    {
    }

    function mint(address recipient, uint256 amount) public {
        require(msg.sender == owner);
        require(totalSupply + amount >= totalSupply); // Overflow check

        totalSupply += amount;
        balanceOf[recipient] += amount;
        emit Transfer(address(0), recipient, amount);
    }

    function burn(uint256 amount) public {
        require(amount <= balanceOf[msg.sender]);

        totalSupply -= amount;
        balanceOf[msg.sender] -= amount;
        emit Transfer(msg.sender, address(0), amount);
    }

    function burnFrom(address from, uint256 amount) public {
        require(amount <= balanceOf[from]);
        require(amount <= allowance[from][msg.sender]);

        totalSupply -= amount;
        balanceOf[from] -= amount;
        allowance[from][msg.sender] -= amount;
        emit Transfer(from, address(0), amount);
    }
}

State Channels for Two-Player Games

Fri, 11 May 2018 13:31:35 -0400

This post will introduce the concept of state channels in the context of a two-player game. I’ll enhance the contract from Two-Player Games in Ethereum to support making moves in the game without sending transactions. By avoiding on-chain transactions, the new game will be faster and less expensive.

What is a State Channel?

State channels are a very broad and simple way to think about blockchain interactions which could occur on the blockchain, but instead get conducted off of the blockchain, without significantly increasing the risk of any participant.

–Jeff Coleman, 2015

The preceding quote is from Jeff Coleman’s excellent post State Channels, which is the best introduction to state channels that I’ve seen. I encourage you to take a few minutes to read it in its entirety.

The technology behind state channels should be familiar to readers of this blog. We’ve previously covered digital signatures, which allow participants to commit to state updates, and payment channels, which are a specific form of state channel. As with a payment channel, using a state channel consists of three steps:

Opening the channel, often including some sort of escrow.
Exchanging state updates off-chain using digital signatures.
Closing the channel by providing the latest agreed upon state.

Applying State Channels to a Two-Player Game

The previous “21 game” contract used only on-chain transactions. This has the desirable property of making the game trustless. The contract enforces the rules of the game and guarantees the fairness of the outcome. However, transactions have downsides. Each transaction requires gas, and each transaction needs to be mined into a block, which takes time.

By using a state channel, we can avoid some of the transactions without sacrificing the trustlessness. Without a state channel, most of the transactions are players taking turns calling move(). With a state channel, each player will instead send signed messages indicating their moves directly to their opponent.

As long as the smart contract accepts such signed messages and updates the game state accordingly, the signed message is just as good as a transaction sent directly to the contract.

The typical steps using the state channel version of the contract are as follows:

Player 1 deploys the contract (on chain).
Player 2 joins the game (on chain).
Players make moves by exchanging signed states (off chain).
The winning player makes their final move based on a signed message from their opponent (on chain).

As compared to the previous version of the contract, calls to move() can be replaced with signed messages exchanged off chain, and a new moveFromState() function allows a player to make an on-chain move based on a signed message from their opponent.

Adding a Sequence Number

At any time, either player can send a recent signed message from their opponent to the smart contract. The opponent signed the state explicitly in a message, and the sender signed it implicitly by sending it in a transaction. Because both players have signed the message, it represents an agreement between the two players. This does not, however, mean that it is a new state.

To know if a state is new, state updates will include a sequence number that always increases. A state with a higher sequence number always takes precedence over a state with a lower sequence number. This makes it impossible for a player to cheat by trying to submit an old game state to the smart contract.

The previous contract already includes a GameState struct. I’ve added a sequence number called seq:

struct GameState {
    uint8 seq;
    uint8 num;
    address whoseTurn;
}

When both players are cooperating and communicating directly, there’s no need to call move(), but the function still needs to be there to handle the case where one player stops sending signed messages. In that case, the fallback is for players to use on-chain transactions to move the game forward.

The move() function must increment the sequence number each time a move is made. I’ve also added the expected current sequence number as a parameter. This prevents a race condition where one player sends a move() transaction but by the time it arrives at the smart contract, the contract’s state has changed:

event MoveMade(address player, uint8 seq, uint8 value);

function move(uint8 seq, uint8 value) public {
    require(state.seq == seq, "Incorrect sequence number.");

    // ...

    state.seq += 1;

    // ...

    emit MoveMade(msg.sender, seq, value);
}

Using a Signed State

The move() function allows a player to move based on the last state registered with the smart contract. With a state channel, though, the latest (off-chain) state is probably not known to the smart contract. To make an on-chain move from an off-chain state, the player must present that state to the smart contract, signed by their opponent:

function moveFromState(uint8 seq, uint8 num, bytes sig, uint8 value) public {
    require(seq >= state.seq, "Sequence number cannot go backwards.");

    bytes32 message = prefixed(keccak256(address(this), seq, num));
    require(recoverSigner(message, sig) == opponentOf(msg.sender));

    state.seq = seq;
    state.num = num;
    state.whoseTurn = msg.sender;

    move(seq, value);
}

A brief explanation of the code above:

The parameters seq and num represent the state signed by the opponent. The whoseTurn value is implicit; if player 1 signs a state, it is by definition now player 2’s turn.
The signature is checked using prefixed() and recoverSigner(), which are borrowed from my post Signing and Verifying Messages in Ethereum.
The address of the contract is included in signed message to prevent cross-contract replay attacks as described in Signing and Verifying Messages in Ethereum.
The contract’s game state is replaced with the signed state.
Finally, move() is called to apply the player’s move.

Although moveFromState() can be called at any time, it is usually only called once per game: to make the winning move and collect the wagered ether.

On-chain Fallback

Typically, game moves are made by exchanging signed messages rather than using on-chain transactions. However, in the case where one player stops sending signed messages—either as an attempt to stall the game or because of a communication problem—it’s important that players can fall back to using the smart contract.

Just as in the previous contract, if a player’s opponent has stopped making moves, the player needs to invoke a timeout by calling startTimeout(). For the smart contract to allow such a call, it must know the current game state—or at least whose turn it is. A player can first call moveFromState() to inform the smart contract of the latest agreed-upon state and to apply their latest move. This makes it their opponent’s turn and allows the timeout to be started.

In response to a timeout, the player whose turn it is must make a move by calling move(). This resets the timer and lets the game continue. Players can then resume the typical workflow of exchanging signed messages, or they can continue to make moves on chain.

Why Can the Sequence Number Stay the Same?

The requirement seq >= state.seq in moveFromState() may surprise you. Why doesn’t this read seq > state.seq?

Before answering the question, I’d like to establish two important invariants for the smart contract:

Once a player has committed to a move in a signed message, they cannot undo that move. Otherwise, the game is not trustless.
The sequence number increases with each move made. Otherwise, there’s no guarantee the game will end.

It seems at first that the combination of signed messages and the requirement seq > state.seq would take care of both invariants. However, consider the following scenario from a chess game:

In the middle of the game, Alice makes a threatening move. She does this by sending Bob a signed message with a sequence number 15 and a complete game state.
Bob responds by moving his queen. He signs a new message with the sequence number 16 and a new game state.
Alice notices she can capture Bob’s queen with her knight. She does so by sending a message to Bob with sequence number 17 and a new game state.
Bob, who is very unhappy to have lost his queen, does something tricky. He sends a transaction to the smart contract with Alice’s signed message at sequence number 15 and makes a different move (#16) than the one he previously sent to Alice.

After this, the sequence number the smart contract knows about is 16. Alice has a message from Bob indicating his original move, but she can’t use it, because its sequence number is also 16. This violates the first invariant, because Bob was able to undo a move he committed to.

Relaxing the requirement to seq >= state.seq takes care of this problem. Alice can submit Bob’s signed message with sequence number 16, forcing him to stick with his original move.

Even with the relaxed requirement, moveFromState() maintains the second invariant because the new move increments the sequence number.

Summary

State channels enable off-chain signed messages to replace expensive on-chain transactions.
Sequence numbers ensure that the smart contract will eventually know the latest state.
The nature of a turn-based game means that the smart contract must force forward progress to be made. This leads to subtlety in how sequence numbers are treated.
It’s important that an on-chain fallback exists for the case where off-chain communication breaks down.

Future Posts

I have not yet dealt with how end users would interact with a game based on a state channel. The next post in this series will show a JavaScript front end that takes care of the tricky business of signing and exchanging states and interacting with the smart contract as needed.

Full Source Code

twentyone-statechannels.sol

pragma solidity ^0.4.23;

contract TwentyOneGame {
    address public player1;
    address public player2;
    uint256 public betAmount;
    bool public gameOver;

    struct GameState {
        uint8 seq;
        uint8 num;
        address whoseTurn;
    }
    GameState public state;

    uint256 public timeoutInterval;
    uint256 public timeout = 2**256 - 1;

    event GameStarted();
    event TimeoutStarted();
    event MoveMade(address player, uint8 seq, uint8 value);


    // Setup methods

    constructor(uint256 _timeoutInterval) public payable {
        player1 = msg.sender;
        betAmount = msg.value;
        timeoutInterval = _timeoutInterval;
    }

    function join() public payable {
        require(player2 == 0, "Game has already started.");
        require(!gameOver, "Game was canceled.");
        require(msg.value == betAmount, "Wrong bet amount.");

        player2 = msg.sender;
        state.whoseTurn = player1;

        emit GameStarted();
    }

    function cancel() public {
        require(msg.sender == player1, "Only first player may cancel.");
        require(player2 == 0, "Game has already started.");

        gameOver = true;
        msg.sender.transfer(address(this).balance);
    }


    // Play methods

    function move(uint8 seq, uint8 value) public {
        require(!gameOver, "Game has ended.");
        require(msg.sender == state.whoseTurn, "Not your turn.");
        require(value >= 1 && value <= 3,
            "Move out of range. Must be between 1 and 3.");
        require(state.num + value <= 21, "Move would exceed 21.");
        require(state.seq == seq, "Incorrect sequence number.");

        state.num += value;
        state.whoseTurn = opponentOf(msg.sender);
        state.seq += 1;

        // Clear timeout
        timeout = 2**256 - 1;

        if (state.num == 21) {
            gameOver = true;
            msg.sender.transfer(address(this).balance);
        }

        emit MoveMade(msg.sender, seq, value);
    }

    function moveFromState(uint8 seq, uint8 num, bytes sig, uint8 value) public {
        require(seq >= state.seq, "Sequence number cannot go backwards.");

        bytes32 message = prefixed(keccak256(address(this), seq, num));
        require(recoverSigner(message, sig) == opponentOf(msg.sender));

        state.seq = seq;
        state.num = num;
        state.whoseTurn = msg.sender;

        move(seq, value);
    }

    function opponentOf(address player) internal view returns (address) {
        require(player2 != 0, "Game has not started.");

        if (player == player1) {
            return player2;
        } else if (player == player2) {
            return player1;
        } else {
            revert("Invalid player.");
        }
    }


    // Timeout methods

    function startTimeout() public {
        require(!gameOver, "Game has ended.");
        require(state.whoseTurn == opponentOf(msg.sender),
            "Cannot start a timeout on yourself.");

        timeout = now + timeoutInterval;
        emit TimeoutStarted();
    }

    function claimTimeout() public {
        require(!gameOver, "Game has ended.");
        require(now >= timeout);

        gameOver = true;
        opponentOf(state.whoseTurn).transfer(address(this).balance);
    }


    // Signature methods

    function splitSignature(bytes sig)
        internal
        pure
        returns (uint8, bytes32, bytes32)
    {
        require(sig.length == 65);

        bytes32 r;
        bytes32 s;
        uint8 v;

        assembly {
            // first 32 bytes, after the length prefix
            r := mload(add(sig, 32))
            // second 32 bytes
            s := mload(add(sig, 64))
            // final byte (first byte of the next 32 bytes)
            v := byte(0, mload(add(sig, 96)))
        }

        return (v, r, s);
    }

    function recoverSigner(bytes32 message, bytes sig)
        internal
        pure
        returns (address)
    {
        uint8 v;
        bytes32 r;
        bytes32 s;

        (v, r, s) = splitSignature(sig);

        return ecrecover(message, v, r, s);
    }

    // Builds a prefixed hash to mimic the behavior of eth_sign.
    function prefixed(bytes32 hash) internal pure returns (bytes32) {
        return keccak256("\x19Ethereum Signed Message:\n32", hash);
    }
}

Writing a Parimutuel Wager Contract

Tue, 08 May 2018 05:37:16 -0700

This post will demonstrate how to write a smart contract that implements parimutuel betting. The contract will accept and pay off bets on the outcome of a single proposition.

Parimutuel betting is a simple way of managing bets and paying off winners. For a given proposition, there are multiple mutually-exclusive outcomes to bet on, only one of which will win. For each possible outcome, a separate tally of bets is maintained. After determining the winning outcome, all of the wagered money is divided amongst those who bet correctly. The money awarded to a bettor is proportional to the fraction of the winning wagers that bettor represents. An example will help.

Suppose $1000 total is bet on the horses in a race, with $200 of that being bet on the winner. Furthermore, suppose that you bet $30 on the winner. Your bet represents 15% ($30/$200) of the winning bets, so you are entitled to 15% of all the money bet ($1000). Therefore, you would receive $150.

A Trusted “Oracle”

Unlike most of our smart contracts, this contract will require some off-blockchain information to pay off bets. Specifically, I am assuming that the bets are about off-chain events like political elections or sporting events.

One motivation for blockchains and smart contracts is distrust of non-chain entities. To resolve a bet about an external event, we must trust some off-chain entity to present the winning outcome. Such an entity is called an “oracle”.

Creating an independent, distributed, trusted oracle is beyond the scope of this post, so I’m going to just assume that bettors trust the contract’s owner to resolve bets correctly.

Parameterization

Bets are parameterized by a description of the proposition and a list of the possible outcomes. I use bytes32 rather than string for each outcome due to a Solidity limitation. (Solidity does not support an array of strings as a parameter to the constructor.)

contract ParimutuelContract {
    address public owner;

    string public proposition;
    bytes32[] public outcomes;
    uint256 public timeout;

    constructor(string _proposition, bytes32[] _outcomes, uint256 timeoutDelay)
        public
    {
        owner = msg.sender;
        proposition = _proposition;
        outcomes = _outcomes;
        timeout = now + timeoutDelay;
    }

    // more to come...
}

The proposition and outcomes values are purely descriptive. They are used by external entities to understand what proposition the contract represents. They are not used in the rest of the contract.

The timeout is used to safeguard bettors from the possibility that the owner never resolves the proposition and bets are never paid off. It is used in cancel below.

Bet Tracking

The contract can be in one of four states:

Open: the state when bets are accepted
Closed: the state after bets are accepted but before the winner is known
Resolved: the state after the winner is known during which bets are paid off
Cancelled: the state of having been cancelled. Any unresolved bet can be cancelled.

enum States { Open, Closed, Resolved, Cancelled }
States state = States.Open;

Betting

Bet outcomes are indicated using the index into the outcomes array corresponding to the desired outcome.

Tracking bets requires updating three running tallies:

betAmounts tracks per-bettor bets on individual outcomes.
totalPerOutcome tracks the total amount bet on each specific outcome.
total tracks the total amount bet.

mapping(address => mapping(uint256 => uint256)) public betAmounts;
mapping(uint256 => uint256) public totalPerOutcome;
uint256 public total;

function bet(uint256 outcome) public payable {
    require(state == States.Open);

    betAmounts[msg.sender][outcome] += msg.value;
    totalPerOutcome[outcome] += msg.value;
    total += msg.value;
    require(total < 2 ** 128);   // avoid overflow possibility
}

Note that the code limits the total amount bet. It does so to avoid a potential overflow in the computation of bet payoffs. The limit is conservative.

Closing Betting

Only the owner can close betting, which is simply a change to the state from Open to Closed.

function close() public {
    require(state == States.Open);
    require(msg.sender == owner);

    state = States.Closed;
}

Resolving the Bet

The owner resolves the bet by indicating the winning outcome. This also changes the state of the bet from Closed to Resolved. I could have allowed a direct transition from Open to Resolved, but this is simpler.

uint256 winningOutcome;

function resolve(uint256 _winningOutcome) public {
    require(state == States.Closed);
    require(msg.sender == owner);

    winningOutcome = _winningOutcome;
    state = States.Resolved;
}

Claiming Winnings

Once a winning outcome has been declared, claiming winnings is straightforward.

function claim() public {
    require(state == States.Resolved);

    uint256 amount = betAmounts[msg.sender][winningOutcome] * total
        / totalPerOutcome[winningOutcome];
    betAmounts[msg.sender][winningOutcome] = 0;
    msg.sender.transfer(amount);
}

Note that we can be certain that the multiplication cannot overflow because of the limit on total enforced in bet.

Cancelling the Bet

An unresolved bet can be cancelled under either of two conditions:

The owner can cancel an unresolved bet at any time.
Anybody can cancel an unresolved bet after the timeout.

function cancel() public {
    require(state != States.Resolved);
    require(msg.sender == owner || now > timeout);

    state = States.Cancelled;
}

Bettors must be able to reclaim bets made prior to cancellation. To keep things simple, the contract does not keep track of the total amount bet by each bettor. Therefore, refunds must be requested on a per-outcome basis.

function refund(uint256 outcome) public {
    require(state == States.Cancelled);

    uint256 amount = betAmounts[msg.sender][outcome];
    betAmounts[msg.sender][outcome] = 0;
    msg.sender.transfer(amount);
}

Incentives

I ignored the fact that gambling establishments typically keep a portion of the bets for themselves. Such a vig would not introduce significant complexity to this contract. The claim function would need to scale down payments, and the remainder would need to be paid to the owner.

While a vig-less contract may seem desirable, it has one significant drawback: the owner has no tangible incentive to actually resolve the proposition. Compensating the owner only after they resolve the proposition would give them incentive to do so. It would also give them incentive to resolve the proposition truthfully. Someone who regularly creates propositions needs to maintain an honest reputation to encourage future participation.

Summary

The smart contract supports parimutuel betting.
The contract goes through multiple states, which are tracked explicitly with enum values.
The contract relies on its owner to transition between states and to resolve the proposition.
The contract employs a timeout to guard against a perpetually unresolved proposition.

The Complete Contract

parimutuel.sol

pragma solidity ^0.4.23;

contract ParimutuelContract {
    address public owner;

    string public proposition;
    bytes32[] public outcomes;
    uint256 public timeout;

    constructor(string _proposition, bytes32[] _outcomes, uint256 timeoutDelay)
        public
    {
        owner = msg.sender;
        proposition = _proposition;
        outcomes = _outcomes;
        timeout = now + timeoutDelay;
    }

    enum States { Open, Closed, Resolved, Cancelled }
    States state = States.Open;

    mapping(address => mapping(uint256 => uint256)) public betAmounts;
    mapping(uint256 => uint256) public totalPerOutcome;
    uint256 public total;

    uint256 winningOutcome;

    function bet(uint256 outcome) public payable {
        require(state == States.Open);

        betAmounts[msg.sender][outcome] += msg.value;
        totalPerOutcome[outcome] += msg.value;
        total += msg.value;
        require(total < 2 ** 128);   // avoid overflow possibility
    }

    function close() public {
        require(state == States.Open);
        require(msg.sender == owner);

        state = States.Closed;
    }

    function resolve(uint256 _winningOutcome) public {
        require(state == States.Closed);
        require(msg.sender == owner);

        winningOutcome = _winningOutcome;
        state = States.Resolved;
    }

    function claim() public {
        require(state == States.Resolved);

        uint256 amount = betAmounts[msg.sender][winningOutcome] * total
            / totalPerOutcome[winningOutcome];
        betAmounts[msg.sender][winningOutcome] = 0;
        msg.sender.transfer(amount);
    }

    function cancel() public {
        require(state != States.Resolved);
        require(msg.sender == owner || now > timeout);

        state = States.Cancelled;
    }

    function refund(uint256 outcome) public {
        require(state == States.Cancelled);

        uint256 amount = betAmounts[msg.sender][outcome];
        betAmounts[msg.sender][outcome] = 0;
        msg.sender.transfer(amount);
    }
}

Two-Player Games in Ethereum

Fri, 04 May 2018 09:57:46 -0400

This is the first post in a series about building efficient two-player games in Ethereum. This post will demonstrate a simple, but complete, smart contract that implements a variant of “the 21 game.”

The Game

For this first contract, I wanted to keep the game logic as simple as possible, so I chose the 21 game. I made up a slight variant:

The number starts at 0.
Two players take turns increasing the number by between 1 and 3 (inclusive).
The player who reaches 21 wins.

An example of a valid game might look like this: 0, 1, 5, 7, 9, 10, 13, 16, 17, 19, 21. ¹

For the smart contract version, the two players are going to wager on the outcome of the game. They must each contribute an equal amount of ether, and all of the ether goes to the winner.

Handling the Game State

The contract must track a small amount of game state. The state variables player1 and player2 track the two participants, betAmount tracks the amount of ether (in wei) wagered, state tracks the number being increased on the way to 21 and whose turn it is next.

I’ll describe timeout and timeoutInterval later in this post.

contract TwentyOneGame {
    address public player1;
    address public player2;
    uint256 public betAmount;
    bool public gameOver;

    struct GameState {
        uint8 num;
        address whoseTurn;
    }
    GameState public state;

    uint256 public timeoutInterval;
    uint256 public timeout = 2**256 - 1;

    constructor(uint256 _timeoutInterval) public payable {
        player1 = msg.sender;
        betAmount = msg.value;
        timeoutInterval = _timeoutInterval;
    }

Starting the Game

The account that deployed the contract is known as player1. To establish itself as player2, an account calls join() and matches player1’s wager. Any time before a second player has joined, player1 may call cancel() to cancel the game and recover their wager:

event GameStarted();

function join() public payable {
    require(player2 == 0, "Game has already started.");
    require(!gameOver, "Game was canceled.");
    require(msg.value == betAmount, "Wrong bet amount.");

    player2 = msg.sender;
    state.whoseTurn = player1;

    emit GameStarted();
}

function cancel() public {
    require(msg.sender == player1, "Only first player may cancel.");
    require(player2 == 0, "Game has already started.");

    gameOver = true;
    msg.sender.transfer(address(this).balance);
}

Moving the Game Forward

Players take turns by increasing num until 21 is reached. The smart contract is responsible for tracking the game state and enforcing the rules of the game:

Players must take turns.
Players must increase the number by between 1 and 3 (inclusive).
The number cannot exceed 21.
The first player to reach 21 wins.
A player who abandons the game forfeits.

To enforce that last rule, I’ll employ a timeout. Regular readers of this blog will note that we use timeouts a lot—e.g. in posts about auctions, coin flips, and payment channels.

Timeouts come up so often because smart contracts cannot force someone to act; they can only punish inaction. Without a timeout, a player who thought they were going to lose would have no incentive to continue playing, and the winning player would be unable to claim their ether.

The parameter timeoutInterval specifies how many seconds each player is allowed before they must make a move, and timeout tracks when that period expires. The timeout is only started when a player feels it’s needed.

The move() function is called by each player to take their turn:

event MoveMade(address player, uint8 value);

function move(uint8 value) public {
    require(!gameOver, "Game has ended.");
    require(msg.sender == state.whoseTurn, "Not your turn.");
    require(value >= 1 && value <= 3,
        "Move out of range. Must be between 1 and 3.");
    require(state.num + value <= 21, "Move would exceed 21.");

    state.num += value;
    state.whoseTurn = opponentOf(msg.sender);

    // Clear timeout
    timeout = 2**256 - 1;

    if (state.num == 21) {
        gameOver = true;
        msg.sender.transfer(address(this).balance);
    }

    emit MoveMade(msg.sender, value);
}

Here’s a brief explanation of move():

The require statements make sure the move is a valid one.
The game state is updated to reflect the new total and whose turn it is.
The timeout is reset.
If the game is over, the winning player receives their prize.
An event is emitted to help the players know when it’s their turn.

If a player feels their opponent is taking too long to make their move, they can start the timeout process. This sets timeout and emits an event:

function startTimeout() public {
    require(!gameOver, "Game has ended.");
    require(state.whoseTurn == opponentOf(msg.sender),
        "Cannot start a timeout on yourself.");

    timeout = now + timeoutInterval;
    emit TimeoutStarted();
}

If the timeout is reached, this indicates that the player whose turn it is has abandoned the game. They forfeit, making the other player the winner:

function claimTimeout() public {
    require(!gameOver, "Game has ended.");
    require(now >= timeout);

    gameOver = true;
    opponentOf(state.whoseTurn).transfer(address(this).balance);
}

Summary

A smart contract can enforce the rules of a two-player game.
Timeouts are needed to punish non-participation.

Future Posts

This post is the first in a series. The next post will use state channels to avoid having to make each move on the blockchain, and a subsequent post will show how to build a JavaScript front-end for the game.

Full Source Code

twentyone.sol

pragma solidity ^0.4.23;

contract TwentyOneGame {
    address public player1;
    address public player2;
    uint256 public betAmount;
    bool public gameOver;

    struct GameState {
        uint8 num;
        address whoseTurn;
    }
    GameState public state;

    uint256 public timeoutInterval;
    uint256 public timeout = 2**256 - 1;

    event GameStarted();
    event TimeoutStarted();
    event MoveMade(address player, uint8 value);


    // Setup methods

    constructor(uint256 _timeoutInterval) public payable {
        player1 = msg.sender;
        betAmount = msg.value;
        timeoutInterval = _timeoutInterval;
    }

    function join() public payable {
        require(player2 == 0, "Game has already started.");
        require(!gameOver, "Game was canceled.");
        require(msg.value == betAmount, "Wrong bet amount.");

        player2 = msg.sender;
        state.whoseTurn = player1;

        emit GameStarted();
    }

    function cancel() public {
        require(msg.sender == player1, "Only first player may cancel.");
        require(player2 == 0, "Game has already started.");

        gameOver = true;
        msg.sender.transfer(address(this).balance);
    }


    // Play methods

    function move(uint8 value) public {
        require(!gameOver, "Game has ended.");
        require(msg.sender == state.whoseTurn, "Not your turn.");
        require(value >= 1 && value <= 3,
            "Move out of range. Must be between 1 and 3.");
        require(state.num + value <= 21, "Move would exceed 21.");

        state.num += value;
        state.whoseTurn = opponentOf(msg.sender);

        // Clear timeout
        timeout = 2**256 - 1;

        if (state.num == 21) {
            gameOver = true;
            msg.sender.transfer(address(this).balance);
        }

        emit MoveMade(msg.sender, value);
    }

    function opponentOf(address player) internal view returns (address) {
        require(player2 != 0, "Game has not started.");

        if (player == player1) {
            return player2;
        } else if (player == player2) {
            return player1;
        } else {
            revert("Invalid player.");
        }
    }


    // Timeout methods

    function startTimeout() public {
        require(!gameOver, "Game has ended.");
        require(state.whoseTurn == opponentOf(msg.sender),
            "Cannot start a timeout on yourself.");

        timeout = now + timeoutInterval;
        emit TimeoutStarted();
    }

    function claimTimeout() public {
        require(!gameOver, "Game has ended.");
        require(now >= timeout);

        gameOver = true;
        opponentOf(state.whoseTurn).transfer(address(this).balance);
    }
}

Although this post does not address the strategy of the game, you might be interested to note that the first player (the one who kicked things off with “1”) played a perfect strategy. Played correctly, the first player should always win. ↩

Writing a Dominant Assurance Contract

Tue, 01 May 2018 06:15:04 -0700

This post will demonstrate how to write a smart contract that implements a “dominant assurance contract”. It assumes that you have read our previous post on vanilla assurance contracts.

Fundraising via assurance contracts like Kickstarter campaigns often suffer from low participation where people who value the proposed good don’t contribute funds because they anticipate the goal being met without their contribution, or because they doubt success and don’t want to participate in a failing effort. Nonparticipation raises the risk that a campaign will fail. Alex Tabarrok invented “dominant assurance contracts” to address this concern.

Dominant assurance contracts require a patron to stake money that is paid to participants of a failed campaign. This payoff is proportional to the original pledge. For instance, if a patron stakes a 10% payoff, then all participants of a failed campaign would be refunded 110% of their contributions. The motivation is that participants now benefit no matter what—either they get a bonus if the campaign fails, or the valued good is produced if the campaign succeeds.

Staking the Payoff

The previous assurance contract post demonstrated how simple it is to implement an assurance contract with a smart contract. Modifying that code to implement a dominant assurance contract requires just a modest amount more logic.

The contract will be parameterized by the length of the campaign in days, the goal amount, and the percentage payoff to participants if the goal is not attained.

contract DominantAssuranceContract {
    address public owner;
    uint256 public deadline;
    uint256 public goal;
    uint8 public percentagePayoff;
    mapping(address => uint256) public balanceOf;
    uint256 public totalPledges;

    constructor(uint256 numberOfDays, uint256 _goal, uint8 _percentagePayoff) public payable {
        owner = msg.sender;
        deadline = now + (numberOfDays * 1 days);
        goal = _goal;
        percentagePayoff = _percentagePayoff;
        balanceOf[msg.sender] = msg.value;
    }

    // more to come...
}

The smart contract will track a few simple values:

totalPledges will track the total amount pledged. In the previous simple assurance contract, I relied on address(this).balance for tracking pledges, but I can’t do that here because the owner must escrow ether for future payoffs, if needed.
The balanceOf mapping will track the amount of ether to be refunded to accounts in the case of a failed campaign. Initially, balanceOf[owner] will be set to all the escrowed ether transferred when the contract is deployed. That amount will be decreased as pledges are made.

Pledges

The contract accepts pledges and associated ether:

function pledge(uint256 amount) public payable {
    require(now < deadline, "The campaign is over.");
    require(msg.value == amount, "The amount is incorrect.");
    require(msg.sender != owner, "The owner cannot pledge.");

    uint256 payoff = amount * percentagePayoff / 100;
    if (payoff > balanceOf[owner]) {
        payoff = balanceOf[owner];
    }
    balanceOf[owner] -= payoff;
    balanceOf[msg.sender] += amount+payoff;
    totalPledges += amount;
}

The contract accounts for the pledged ether by updating both totalPledges and balanceOf[msg.sender]. It also accounts for the implied payoff amount by transferring ether balance from the owner to the sender.

I’ve disallowed pledges from the owner to avoid having to reason about the correctness of balanceOf[owner] with respect to funding payoffs. The owner can always pledge from another account if they choose.

It’s possible for the contract to run out of payoff funds, so the contract avoids an underflow risk by checking the available owner balance. This risk exists in two scenarios: when more than the expected amount is pledged, or when insufficient payoff is escrowed. The former is great news (but needs to be handled), and the latter may be by design as I discuss later.

Post-Campaign

The logic for handling post-campaign transfers is exactly the same as in the simple assurance contract:

function claimFunds() public {
    require(now >= deadline, "The campaign is not over.");
    require(totalPledges >= goal, "The funding goal was not met.");
    require(msg.sender == owner, "Only the owner may claim funds.");

    msg.sender.transfer(address(this).balance);
}

function getRefund() public {
    require(now >= deadline, "The campaign is still active.");
    require(totalPledges < goal, "Funding goal was met.");

    uint256 amount = balanceOf[msg.sender];
    balanceOf[msg.sender] = 0;
    msg.sender.transfer(amount);
}

While the logic is the same, it’s actually a bit more subtle with respect to the payoffs.

claimFunds is simple because all funds, whether pledged or escrowed payoffs, go to the owner when the campaign is successful.
getRefund is simple because the complicated work of keeping track of the pledges and payoffs is done in pledge. Similarly, any remaining/excess escrowed payoff funds will appear in balanceOf[owner], which means that the owner can also use getRefund to claim that excess.

Insufficient Payoff Escrow (Feature)

Note that the constructor did not require the owner to escrow ether sufficient to cover a failed campaign. Because the storage variables are public, it’s trivial to determine the sufficiency of the escrowed ether (in balanceOf[owner]).

This gives patrons the flexibility to deploy a contract with only a partially funded payoff. This would mean that early pledgers would be entitled to a failure payoff, but late pledgers would not. That may be an interesting design point for campaigns that want to encourage early pledges.

Summary

Dominant assurance contracts can easily be implemented with smart contracts.
The payoff feature presents little extra complexity.

The Complete Contract

dominant.sol

pragma solidity ^0.4.23;

contract DominantAssuranceContract {
    address owner;
    uint256 deadline;
    uint256 goal;
    uint8 percentagePayoff;
    mapping(address => uint256) public balanceOf;
    uint256 totalPledges;

    constructor(uint256 numberOfDays, uint256 _goal, uint8 _percentagePayoff) public payable {
        owner = msg.sender;
        deadline = now + (numberOfDays * 1 days);
        goal = _goal;
        percentagePayoff = _percentagePayoff;
        balanceOf[msg.sender] = msg.value;
    }

    function pledge(uint256 amount) public payable {
        require(now < deadline, "The campaign is over.");
        require(msg.value == amount, "The amount is incorrect.");
        require(msg.sender != owner, "The owner cannot pledge.");

        uint256 payoff = amount * percentagePayoff / 100;
        if (payoff > balanceOf[owner]) {
            payoff = balanceOf[owner];
        }
        balanceOf[owner] -= payoff;
        balanceOf[msg.sender] += amount+payoff;
        totalPledges += amount;
    }

    function claimFunds() public {
        require(now >= deadline, "The campaign is not over.");
        require(totalPledges >= goal, "The funding goal was not met.");
        require(msg.sender == owner, "Only the owner may claim funds.");

        msg.sender.transfer(address(this).balance);
    }

    function getRefund() public {
        require(now >= deadline, "The campaign is still active.");
        require(totalPledges < goal, "Funding goal was met.");

        uint256 amount = balanceOf[msg.sender];
        balanceOf[msg.sender] = 0;
        msg.sender.transfer(amount);
    }
}

Avoiding Integer Overflows: SafeMath Isn't Enough

Fri, 27 Apr 2018 12:20:05 -0400

This post describes what an integer overflow is and how to avoid them in smart contracts.

What is an Integer Overflow?

Fixed-size integers have a range of values they can represent. For example, an 8-bit unsigned integer can store values between 0 and 255 (2⁸-1). When the result of some arithmetic falls outside that supported range, an integer overflow occurs. ¹

On the Ethereum Virtual Machine (EVM), the consequence of an integer overflow is that the most significant bits of the result are lost. For example, when working with 8-bit unsigned integers, 255 + 1 = 0. This is easier to see in binary, where 1111 1111 + 0000 0001 should be 1 0000 0000, but because only 8 bits are available, the leftmost bit is lost, resulting in a value of 0000 0000.

Intuitively, the effect of an integer overflow can be thought of as the value “wrapping around.”

Examples of Integer Overflows

Solidity uses fixed-size integers of various sizes. In the examples below, I’ve used only 256-bit integers, the largest integer types Solidity supports. Integer overflow in the EVM can occur during addition, subtraction, multiplication, and exponentiation.

Unsigned Integer Overflows

256-bit unsigned integers can store a minimum value of 0 and a maximum value of 2²⁵⁶-1:

uint256 u;                    // range: [0, 2**256)

u = 2**256 - 1;
assert(u + 1 == 0);           // should be 2**256

u = 4;
assert(u - 5 == 2**256 - 1);  // should be -1

u = 2**255;
assert(u * 2 == 0);           // should be 2**256

u = 2**128;
assert(u**2 == 0);            // should be 2**256

Signed Integer Overflows

256-bit signed integers can store a minimum value of -2²⁵⁵ and a maximum value of 2²⁵⁵-1:

int256 s;                     // range: [-2**255, 2**255)

s = 2**255 - 1;
assert(s + 1 == -2**255);     // should be 2**255

s = -2**255;
assert(s - 1 == 2**255-1);    // should be -2**255-1

s = 2**254;
assert(s * 2 == -2**255);     // should be 2**255

Mitigating Integer Overflows

Unlike some computer architectures, the EVM provides no indication that an overflow has occurred. It’s up to you to write code that detects overflow conditions and handles them appropriately.

One approach to integer overflows is to perform the arithmetic, check the result, and revert the transaction if an overflow occurred. For example, here’s a safeAdd function:

function safeAdd(uint256 a, uint256 b) internal pure returns (uint256 c) {
    c = a + b;
    require(c >= a);
}

If an integer overflow occurred, then c will be less than a, and the require will revert the transaction.

This approach is taken by the widely-used SafeMath library from OpenZeppelin.

SafeMath Isn’t Enough

Using functions like those provided in the SafeMath library ensure that your contract doesn’t use the result of an integer overflow, but they might leave your contract unusable. Here’s a simple example:

using SafeMath for uint256;

uint256 price = 2 ether;
uint256 quantity = 2**200;

function purchase() public payable {
    require(msg.value < price.mul(quantity));
    // ...
}

Because 2 ether * 2²⁰⁰ overflows, the call to mul will always revert the transaction, so no purchase can be made.

We recently encountered this difficulty in our post about periodic loans. This code in calculateCollateral is roughly equivalent to SafeMath’s mul function:

uint256 product = collateralPerPayment * payment;
require(product / collateralPerPayment == payment, "payment causes overflow");

This is a good mitigation, but there’s still a problem. There’s a required minimum payment. If that payment causes an overflow, then there’s no way to pay off the loan. To avoid this situation, we added an overflow check to the constructor:

uint256 x = minimumPayment * collateralPerPayment;
require(x / collateralPerPayment == minimumPayment,
    "minimumPayment * collateralPerPayment overflows");

The result of the multiplication isn’t used. The check is purely there to ensure that the contract cannot be deployed with parameters that will render it unusable.

batchOverflow

Making its rounds this week is an integer overflow bug that has been dubbed “batchOverflow.” The following is a slight simplification of the erroneous code found in several ERC20 token contracts. This function allows a token holder to send tokens to multiple recipients:

// DO NOT USE!
function batchTransfer(address[] receivers, uint256 value) public {
    uint256 amount = receivers.length * value;
    require(balances[msg.sender] >= amount);

    balances[msg.sender] = balances[msg.sender].sub(amount);
    for (uint256 i = 0; i < receivers.length; i++) {
        balances[receivers[i]] = balances[receivers[i]].add(value);
    }
}

The require is meant to ensure the sender has a sufficient balance to cover the transfers, but note that amount is the product of two values controlled by the caller. If someone were to pass 2 addresses and a value of 2²⁵⁵, then amount would overflow to 0. The require would verify that the sender’s balance was at least 0, and the recipients’ token balances would be increased.

Note that the use of SafeMath’s sub to reduce the sender’s balance doesn’t help here because amount is 0, so that subtraction has no overflow.

Summary

Arithmetic using fixed-sized integers can cause overflows, resulting in mathematically incorrect results.
To abort overflows, use a library like SafeMath.
To avoid overflows altogether, do parameter validation up front.

Test Your Knowledge

Now that you understand integer overflows and how to spot them, test your knowledge in the Capture the Ether “math” category. More than one of those challenges requires exploiting an integer overflow.

Sometimes the term “integer underflow” is used when the result is specifically below the supported range. ↩

Writing a Periodic Loan Contract

Tue, 24 Apr 2018 05:28:18 -0700

This post will demonstrate how to write a smart contract that will administer an ether loan while holding ERC20 tokens as collateral. My previous post on a collateralized loan contract assumed that there would be just a single loan payment. This post will generalize that to a more typical structure where the loan requires equal payments at regularly-spaced intervals at a fixed interest rate.

Periodic loans are characterized by a few simple values:

The remaining principal balance amount, which represents the amount of borrowed ether that remains owed to the lender. This typically decreases with each loan payment. This begins as the original loan amount.
The period (or interval) between required loan payments. A typical period might be 30 days.
The minimum periodic payment amount, which is the amount of ether the borrower is required to transfer to the lender each pay period. (The last payment may be less than the minimum.)
The per-period interest rate, which is the fraction of the loan balance that is owed as interest each pay period.
Collateral tokens that will be forfeited for each missed payment.

pragma solidity ^0.4.23;

import "./ierc20token.sol";

contract PeriodicLoan {
    struct Rational {
        uint256 numerator;
        uint256 denominator;
    }

    address lender;
    address borrower;

    Rational public interestRate;

    uint256 public dueDate;
    uint256 paymentPeriod;

    uint256 public remainingBalance;
    uint256 minimumPayment;

    IERC20Token token;
    uint256 collateralPerPayment;

    constructor(
        address _lender,
        address _borrower,
        uint256 interestRateNumerator,
        uint256 interestRateDenominator,
        uint256 _paymentPeriod,
        uint256 _minimumPayment,
        uint256 principal,
        IERC20Token _token,
        uint256 units
    )
        public
    {
        lender = _lender;
        borrower = _borrower;
        interestRate = Rational(interestRateNumerator, interestRateDenominator);
        paymentPeriod = _paymentPeriod;
        minimumPayment = _minimumPayment;
        remainingBalance = principal;
        token = _token;
        collateralPerPayment = units;

        uint256 x = minimumPayment * collateralPerPayment;
        require(x / collateralPerPayment == minimumPayment,
            "minimumPayment * collateralPerPayment overflows");

        dueDate = now + paymentPeriod;
    }

    // more yet to come
}

The code above is very similar to the collateralized loan contract with the addition of the interest rate, payment amount, and payment period values.

Note also that the creation of this loan contract, the transfer of tokens to the loan contract, and the transfer of ether to the borrower will be done by a different smart contract. This contract will assume that those amounts were correctly transferred. (Here is the Wikipedia page with useful formulas for loan payments.)

Loan Payments

Loan payments consist of an interest component and a principal component, which can be computed simply:

interest = interest rate * balance
principal = payment – interest
new balance = old balance – principal

Collateral

Periodic loans in the physical world typically have one big indivisible chunk of collateral like a car or house. In that world, loans must be very complicated to deal with penalties for missed payments including the possibility of forfeiting the collateral for delinquency. Fortunately, we can avoid all of that complexity when tokens are used as collateral in a smart contract.

In the collateralized loan contract all the tokens were transferred at once. If the one loan payment was made, then all of the tokens were transferred back to the borrower, but they were all forfeited if the loan payment wasn’t made. I will generalize that idea.

In the periodic loan, each pay period will result in a transfer of a fraction of the collateral tokens. If the payment was made correctly, then some tokens will be returned to the borrower. Otherwise, they will be transferred to the lender.

The amount of collateral to transfer is easy to compute. The loan is parameterized with collateralPerPayment, which represents the amount of collateral that will be returned or forfeited based on a minimumPayment. If the borrower pays an amount different than the minimum, the amount of collateral returned is adjusted proportionally. For instance, paying twice the minimum will result in twice as many tokens returned.

function calculateComponents(uint256 amount)
    internal
    view
    returns (uint256 interest, uint256 principal)
{
    interest = multiply(remainingBalance, interestRate);
    require(amount >= interest);
    principal = amount - interest;
    return (interest, principal);
}

function calculateCollateral(uint256 payment)
    internal
    view
    returns (uint256 units)
{
    uint256 product = collateralPerPayment * payment;
    require(product / collateralPerPayment == payment, "payment causes overflow");
    units = product / minimumPayment;
    return units;
}

Payment Processing

There is a symmetry between accepting loan payments and handling missed payments. In both cases, there is an adjustment to the remaining principal balance and a corresponding transfer of tokens. The only difference is that the tokens are returned to the borrower after a payment, but they are forfeited to the lender after a missed payment. Both also advance the due date of the next payment:

function processPeriod(uint256 interest, uint256 principal, address recipient) internal {
    uint256 units = calculateCollateral(interest+principal);

    remainingBalance -= principal;

    dueDate += paymentPeriod;

    require(token.transfer(recipient, units));
}

Please note that the code above does the token transfer last, which follows the Checks-Effects-Interactions pattern to avoid potential reentrancy vulnerabilities.

Accepting Payments

Given the ability to compute interest, principal, and collateral amounts corresponding to any expected payment, we are most of the way to handling loan payments. The only additional consideration is the need to handle the final loan payment. While it’s possible to create loan terms where all payments will be identical, it’s sometimes convenient to have “round” payments—like exactly 1 ETH—and then have the final payment be some fractional amount.

function makePayment() public payable {
    require(now <= dueDate);

    uint256 interest;
    uint256 principal;
    (interest, principal) = calculatePrincipal(msg.value);

    require(principal <= remainingBalance);
    require(msg.value >= minimumPayment || principal == remainingBalance);

    processPeriod(interest, principal, borrower);
}


function withdraw() public {
    lender.transfer(address(this).balance);
}

The code above does just a few things:

It checks that the payment was made on time.
It computes the principal amount that corresponds to the payment.
It checks that the principal does not exceed the remaining balance because this would amount to a gift to the lender.
It does not special case the odd final payment amount other than relaxing the require statement.
processPeriod is called specifying that the borrower should receive the collateral tokens.
The code does not transfer the ether directly to avoid problems with a misbehaving lender. Instead, the lender can withdraw ether at any time.

Missed Payments

function missedPayment() public {
    require(now > dueDate);

    uint256 interest;
    uint256 principal;
    (interest, principal) = calculatePrincipal(minimumPayment);

    if (principal > remainingBalance) {
        principal = remainingBalance;
    }

    processPeriod(interest, principal, lender);
}

The code for handling a missed payment is straightforward:

The code computes the principal component of the missed payment. This assumes the payment was the minimum amount, which is true for all but, possibly, the last payment. The conditional handles the boundary condition when the principal remaining is less than the principal component of a minimum payment.
processPeriod is called specifying the lender as the recipient of the forfeited tokens.

missedPayment can be called by anybody. This is important to the borrower because they may need to call missedPayment in order to advance dueDate in order to make a subsequent payment.

Excess Collateral

This smart contract allows borrowers to pay more than the minimum, which will ultimately lead to less total paid because of avoided interest. If used, this feature will lead to excess collateral owned by the loan contract after it’s been fully paid off. This collateral belongs to the borrower. The simplest way to handle that is to allow excess tokens to be claimed when the remainingBalance is zero:

function returnCollateral() public {
    require(remainingBalance == 0);

    uint256 amount = token.balanceOf(this);
    require(token.transfer(borrower, amount));
}

Keeping It Simple

In the spirit of keeping it simple, this contract makes one huge simplifying assumption. Did you see it?

How does this contract handle the borrower missing multiple payments in a row? It does nothing special! If N payments are missed in a row, then missedPayment must be called N times before the contract will accept another payment. Sure, the astute reader could probably add a loop somewhere to handle this case, but then they’d have to think hard about the correctness of that loop. Loop correctness is hard, but I didn’t have to think (much) to be sure the current code works!

Interesting Variations

One of the nice things about smart contracts is that they enable interesting variations on traditional models by simply implementing the variation in the code of the contract. The contract above represents a pretty traditional multi-period loan with respect to payment structure and interest computations. (The only novel aspect is the returning of fractions of the collateral with each payment, which is enabled by the typical design of ERC20 tokens.)

Variations that would represent modest changes to this contract:

Rather than having a minimum payment, the contract could require a minimum amount of principal above the interest due.
The contract could add a penalty amount to the principal balance for each missed payment (in addition to forfeiting collateral tokens).
The contract could include a grace period during which a late payment is accepted with a small penalty, but no forfeited collateral.
The contract could disallow payments in excess of the payment amount, which would disallow pre-payment of principal balance.

Summary

Smart contracts can implement loans that require multiple payments.
ERC20 token collateral enable a flexible repayment and forfeiture policy.

The Full Contract

periodicloan.sol

pragma solidity ^0.4.23;

import "./ierc20token.sol";

contract PeriodicLoan {
    struct Rational {
        uint256 numerator;
        uint256 denominator;
    }

    address lender;
    address borrower;

    Rational public interestRate;

    uint256 public dueDate;
    uint256 paymentPeriod;

    uint256 public remainingBalance;
    uint256 minimumPayment;

    IERC20Token token;
    uint256 collateralPerPayment;

    constructor(
        address _lender,
        address _borrower,
        uint256 interestRateNumerator,
        uint256 interestRateDenominator,
        uint256 _paymentPeriod,
        uint256 _minimumPayment,
        uint256 principal,
        IERC20Token _token,
        uint256 units
    )
        public
    {
        lender = _lender;
        borrower = _borrower;
        interestRate = Rational(interestRateNumerator, interestRateDenominator);
        paymentPeriod = _paymentPeriod;
        minimumPayment = _minimumPayment;
        remainingBalance = principal;
        token = _token;
        collateralPerPayment = units;

        uint256 x = minimumPayment * collateralPerPayment;
        require(x / collateralPerPayment == minimumPayment,
            "minimumPayment * collateralPerPayment overflows");

        dueDate = now + paymentPeriod;
    }

    function multiply(uint256 x, Rational r) internal pure returns (uint256) {
        return x * r.numerator / r.denominator;
    }

    function calculateComponents(uint256 amount)
        internal
        view
        returns (uint256 interest, uint256 principal)
    {
        interest = multiply(remainingBalance, interestRate);
        require(amount >= interest);
        principal = amount - interest;
        return (interest, principal);
    }

    function calculateCollateral(uint256 payment)
        internal
        view
        returns (uint256 units)
    {
        uint256 product = collateralPerPayment * payment;
        require(product / collateralPerPayment == payment, "payment causes overflow");
        units = product / minimumPayment;
        return units;
    }

    function processPeriod(uint256 interest, uint256 principal, address recipient) internal {
        uint256 units = calculateCollateral(interest+principal);

        remainingBalance -= principal;

        dueDate += paymentPeriod;

        require(token.transfer(recipient, units));
    }

    function makePayment() public payable {
        require(now <= dueDate);

        uint256 interest;
        uint256 principal;
        (interest, principal) = calculateComponents(msg.value);

        require(principal <= remainingBalance);
        require(msg.value >= minimumPayment || principal == remainingBalance);

        processPeriod(interest, principal, borrower);
    }

    function withdraw() public {
        lender.transfer(address(this).balance);
    }

    function missedPayment() public {
        require(now > dueDate);

        uint256 interest;
        uint256 principal;
        (interest, principal) = calculateComponents(minimumPayment);

        if (principal > remainingBalance) {
            principal = remainingBalance;
        }

        processPeriod(interest, principal, lender);
    }

    function returnCollateral() public {
        require(remainingBalance == 0);

        uint256 amount = token.balanceOf(this);
        require(token.transfer(borrower, amount));
    }
}

Storage Patterns: Pagination

Fri, 20 Apr 2018 09:21:02 -0400

This post will show how to support pagination for returning large data sets from a smart contract. It builds on concepts introduced in my post on doubly-linked lists.

When to Paginate

When large amounts of data are involved, it may not be possible for a smart contract to return an entire data set at once. Pagination is a way for a caller to make multiple smaller requests to retrieve the data. Some callers may not need the entire data set, in which case it’s useful to be able to retrieve a subset.

There are two potential limits to how much data a smart contract can return at once: gas limits and execution time. For a function call that’s part of a transaction (e.g. from another smart contract), gas is often a limiting factor. Each byte of data returned from the call consumes gas, as does iterating through the data set. Even if the caller is willing to supply a huge amount of gas, there is a block gas limit, which is the maximum amount of gas a single block can consume. If a transaction exceeds this limit, it can never be mined into a block.

For view functions being called from outside the EVM (e.g. from JavaScript in a web app), gas is not a limiting factor because there is no transaction being executed. The node processing the call does the computation locally and returns the result. Each node gets to set its own processing limits—typically limiting execution time. If the call takes too long, it will fail.

When a data set may be large enough to approach either of these limits, use pagination.

Using Cursors

There are many valid API designs for pagination, but using a cursor is probably the most flexible. When a client requests a page of data, the server—in this case a smart contract—returns the requested data as well as a cursor. The cursor is an opaque value that the client needs to pass in its next request. This opaque value specifies where enumeration should continue.

Paging Through an Array

The following code supports appending to an array and enumerating that array using a very simple cursor: the index of the first item being requested.

arraypagination.sol

pragma solidity ^0.4.22;

contract ArrayPagination {
    bytes32[] arr;

    function add(bytes32 data) public {
        arr.push(data);
    }

    function fetchPage(uint256 cursor, uint256 howMany)
    public
    view
    returns (bytes32[] values, uint256 newCursor)
    {
        uint256 length = howMany;
        if (length > arr.length - cursor) {
            length = arr.length - cursor;
        }

        values = new bytes32[](length);
        for (uint256 i = 0; i < length; i++) {
            values[i] = arr[cursor + i];
        }

        return (values, cursor + length);
    }
}

Here’s a brief explanation of the fetchPage function:

howMany indicates how many items should be returned. If there aren’t enough remaining items in the array, the function will return fewer items.
cursor is the aforementioned cursor. It simply indicates the starting index for enumeration. The first call should pass 0, and subsequent calls should pass the returned newCursor.
If cursor is outside the bounds of the array, the array access will throw an error.

In the array example, the cursor is just an index into the array. The client could ignore the returned newCursor and simply calculate the right cursor by counting how many items it had already received. In the next section, I’ll show an example where this is not the case, and the cursor truly needs to be returned from the smart contract.

Paging Through a Linked List

In a linked list, each node stores a link to the next node in the list. There is no way to jump straight to the n^th item in the list. In my post about doubly-linked lists in Solidity, I built a doubly-linked list where nodes are stored in an array, and the node’s index in the array is its unique identifier. This means it’s possible to directly access a node by ID.

A node’s ID a good candidate for a cursor. When a page is requested, the returned cursor will be the ID of the next node in the list (the first node the client has not yet seen).

The following code is adapted from the doubly-linked list post but with one small change. Instead of using bytes as the payload type, I’ve used bytes32.¹ The last function, fetchPage, is new:

doublylinkedlistpagination.sol

pragma solidity ^0.4.22;

contract DoublyLinkedListPagination {
    struct Node {
        bytes32 data;
        uint256 prev;
        uint256 next;
    }

    // nodes[0].next is head, and nodes[0].prev is tail.
    Node[] public nodes;

    constructor () public {
        // sentinel
        nodes.push(Node(bytes32(0), 0, 0));
    }

    function insertAfter(uint256 id, bytes32 data)
    public
    returns (uint256 newID)
    {
        // 0 is allowed here to insert at the beginning.
        require(id == 0 || isValidNode(id));

        Node storage node = nodes[id];

        nodes.push(Node({
            data: data,
            prev: id,
            next: node.next
        }));

        newID = nodes.length - 1;

        nodes[node.next].prev = newID;
        node.next = newID;
    }

    function insertBefore(uint256 id, bytes32 data)
    public
    returns (uint256 newID)
    {
        return insertAfter(nodes[id].prev, data);
    }

    function remove(uint256 id) public {
        require(isValidNode(id));

        Node storage node = nodes[id];

        nodes[node.next].prev = node.prev;
        nodes[node.prev].next = node.next;

        delete nodes[id];
    }

    function isValidNode(uint256 id) internal view returns (bool) {
        // 0 is a sentinel and therefore invalid.
        // A valid node is the head or has a previous node.
        return id != 0 && (id == nodes[0].next || nodes[id].prev != 0);
    }

    function fetchPage(uint256 cursor, uint256 howMany)
    public
    view
    returns (bytes32[] values, uint256 length, uint256 newCursor)
    {
        require(cursor == 0 || isValidNode(cursor));

        uint256 currentIndex = cursor;
        if (currentIndex == 0) {
            // cursor == 0 means the start of the list
            currentIndex = nodes[0].next;
        }

        // The returned array will always have howMany items, but they may not
        // all be valid if more items were requested than are remaining in the
        // list. The length return value specifies how much of the returned
        // array is valid.
        values = new bytes32[](howMany);

        uint256 i = 0;
        while (i < howMany && currentIndex != 0) {
            Node storage node = nodes[currentIndex];

            values[i] = node.data;
            currentIndex = node.next;
            i += 1;
        }

        length = i;
        newCursor = currentIndex;

        return (values, length, newCursor);
    }
}

Here’s a brief explanation of the fetchPage function:

Like in the array example, fetchPage accepts parameters cursor and howMany.
A cursor of 0 indicates that the client wants to start at the beginning of the list. That means starting at nodes[0].next, which is the head of the doubly-linked list.
Arrays kept in memory cannot be resized, so it’s necessary to declare their length up front. Before enumeration, it’s impossible to know the correct length, so an array of size howMany is returned along with an extra return value length that indicates how much of the array is valid data.
The newCursor return value is the index of the next node in the list. A client passes that to resume enumeration.

Getting a Consistent Snapshot

Pagination often has a downside when it comes to concurrency. It can be difficult for clients to deal with data changing during the course of enumeration. For example, in the linked list case, the node indicated by the cursor could be deleted, making the next call to fetchPage fail.

Ethereum provides a nice workaround for these issues. When calling a view function from client software, it’s possible to specify a block number to execute the call in the context of that block. By making each call with the same block number, a client can work with a consistent snapshot of the data.

Summary

Pagination is necessary when gas or execution time limits prevent a client from reading the entirety of a large data set at once.
Cursors are a flexible way to support pagination.
Clients should treat cursors as opaque.
A cursor should allow enumeration to be resumed efficiently.
To guarantee a consistent snapshot, clients should consider specifying the same block number for all calls while paging through data.

Solidity doesn’t (without an experimental new encoder) support returning dynamically-sized arrays of dynamically-sized arrays, making a return type of bytes[] impossible. ↩

Keep Your Code Simple

Tue, 17 Apr 2018 08:43:38 -0400

This post will explain the importance of writing simple code in the context of smart contracts, where bugs can be very expensive.

Achieving Correctness

Perhaps it goes without saying, but a bug in a smart contract can have serious consequences. The Parity multisig wallet initialization bug alone is estimated to have frozen over $150 million dollars worth of ether. The DAO hack put $50 million dollars in jeopardy and led to the creation of the Ethereum Classic fork.

Anyone who has written code before knows that writing bug-free code is no small feat. One of my favorite quotes about this challenge comes from renowned computer scientist Tony Hoare:

There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult.

–Tony Hoare, 1980

The Withdraw Pattern: a Case Study

When transferring ether from a smart contract, a common pattern is “the withdraw pattern.” Rather than transfer ether immediately, the ether is made available for future withdrawal by the recipient.

The reason for this pattern is that transfers can fail, and it’s a good example of how to simplify your code to avoid bugs. Consider the bid function of an auction contract that doesn’t use the withdraw pattern:

// Don't do this!
function bid() public payable {
    require(msg.value > highBid);

    // Return bid to previous high bidder.
    highBidder.transfer(highBid);

    highBidder = msg.sender;
    highBid = msg.value;
}

This function is simple, but it has a well-known vulnerability. The high bidder can be a smart contract that refuses incoming ether. This means the transfer call will fail, and the bidder can never be beaten no matter how low their bid.

It’s tempting to fix this by using send, which returns a boolean status rather than reverting on failure. Replacing transfer with send in the previous code would mean a failure is ignored:

// Don't do this either!

// Return bid to previous high bidder, ignoring failures.
highBidder.send(highBid);

It seems at first like this takes care of the problem, because a high bidder causing a failure is only hurting themselves. However, this is heading down the path of “so complicated that there are no obvious deficiencies.” The code itself isn’t terribly complicated, but reasoning about it is. Someone reading the code needs to consider all the ways send can fail and what happens in those cases.

There’s a flaw in the send version of the code. The recipient of the send isn’t the only one who can cause the transfer to fail. The new bidder can, for example, create a deep call stack before calling bid. When the maximum stack depth is exceeded, the transfer will fail and the previous high bidder will not receive their ether.

Okay, things are getting a bit more complicated. This version detects a failed transfer and makes the funds available for explicit withdrawal by the recipient later:

// Maybe this works?

mapping(address => uint256) balances;

function bid() public payable {
    require(msg.value > highBid);

    // Return bid to previous high bidder.
    if (!highBidder.send(highBid)) {
        // If ether wasn't transferred, keep track of it.
        balances[highBidder] += highBid;
    }

    highBidder = msg.sender;
    highBid = msg.value;
}

// This is used to withdraw funds when a transfer fails.
function withdraw() public {
    // Follow the Checks-Effects-Interactions pattern.
    uint256 amount = balances[msg.sender];
    balances[msg.sender] = 0;
    msg.sender.transfer(amount);
}

At this point, I believe that the code is correct. Ether is either transferred during the bid process or it’s tracked in balances for later withdraw. I’ve corrected the code, but I’ve made the code more complicated. Not all corrections are equal, and it’s important not to settle for a complicated solution like this.

The following code is simpler. Rather than use two different code paths for success and failure, all transfers happen the same way in the same place:

// Withdraw pattern

mapping(address => uint256) balances;

function bid() public payable {
    require(msg.value > highBid);

    // Return bid to previous high bidder.
    balances[highBidder] += highBid;

    highBidder = msg.sender;
    highBid = msg.value;
}

function withdraw() public {
    // Follow the Checks-Effects-Interactions pattern.
    uint256 amount = balances[msg.sender];
    balances[msg.sender] = 0;
    msg.sender.transfer(amount);
}

All interaction with other contracts/accounts is in a single withdraw function, where I’m confident the Checks-Effects-Interactions pattern keeps me safe from reentrancy attacks.

Less Thinking

Making your code “so simple that there are obviously no deficiencies” is not just about making the code shorter or having fewer functions. Note that the final version of the code above is longer and has more functions than the original. The key is that it’s easier to reason about. I get to think less, which gives me a better chance of getting things right.

A place where we recently got this wrong was in our post on Flipping a Coin in Ethereum. I thought it was interesting that claimTimeout could be called by anyone after the expiration time passed, but an astute reader pointed out that because expiration (at the time) was initially 0, claimTimeout could be called as soon as the contract was created. This would result in the first player losing their ether. The code is now fixed, but it would have been better to just restrict who could call claimTimeout. Then I wouldn’t have to think about the various cases at all.

We did better in our recent post on Vickrey auctions, where we forbade bidding by the seller to avoid unnecessary complications.

Resources

The Solidity documentation covers two patterns used in this post:

The quote from Tony Hoare comes from his 1980 Turing Award Lecture The Emperor’s Old Clothes.

Writing a Pawnshop Bazaar Contract

Fri, 13 Apr 2018 05:44:23 -0700

In our pawnshop post, we built a contract that creates loans between a lender and multiple borrowers using ERC20 tokens as collateral.

This post will demonstrate a token bazaar contract which creates and tracks many pawnshops on behalf of many lenders.

Introduction

The PawnShop contract supports a single lender who accepts a single ERC20 token as collateral. Each lender who wants to do this needs to deploy their own PawnShop contract.

This works, but it makes it hard for potential borrowers to find a PawnShop. Further, a borrower who trusts the PawnShop contract code we presented will still need to check each PawnShop to make sure it’s running the same code.

To solve this problem, we can create a single token bazaar contract that does two things:

It creates new PawnShops using identical code for each.
It tracks all the created PawnShops and makes them discoverable to new borrowers.

The Pawnshop Bazaar Contract

The contract uses techniques from the marketplace post for creating, recording, and logging new pawnshops:

bazaar.sol

pragma solidity ^0.4.21;

import "./pawnshop.sol";

contract PawnShopBazaar {
    mapping(address => PawnShop[]) public pawnShops;

    event PawnShopCreated(PawnShop pawnshop, address indexed lender)

    function create(
        address token,
        uint256 loanNumerator,
        uint256 loanDenominator,
        uint256 payoffNumerator,
        uint256 payoffDenominator,
        uint256 loanDuration
    )
        public
    {
        PawnShop ps = new PawnShop(
            msg.sender,
            token,
            loanNumerator,
            loanDenominator,
            payoffNumerator,
            payoffDenominator,
            loanDuration
        );
        pawnShops[token].push(ps);
        emit PawnShopCreated(ps, msg.sender);
    }
}

This code does the following things:

create deploys a new PawnShop contract, which is owned by the lender/sender and is parameterized as they request.
The new pawnshop is added to a publicly accessible list of pawnshops, which is indexed by token for convenience.
The new pawnshop’s creation is announced with the PawnShopCreated event. The event is indexed by lender so that the lender can easily recognize the pawnshop’s creation and keep track of its address.

While that’s all the code that is needed, there are a few subtleties to note:

The lender needs to record the address of any pawnshops they create, and they should then monitor the LoanCreated events that it produces.
There is no way to delete a pawnshop from the bazaar contract. While this functionality could be trivially added, no pawnshop owner would have an incentive to pay the gas to do this.
While the bazaar contract can create pawnshops, it does not fund them, so the lender should deposit ether in the created pawnshop so that it can make loans.
Because the state variable pawnShops is marked public, a getter function is generated, allowing prospective borrowers to browse through the pawnshops accepting a specific ERC20 token.
The PawnShop contract’s state variables are all public. This is how potential borrowers can know the terms being offered.

Summary

By using the existing PawnShop contract and by leveraging the TokenMarketPlace techniques, a very short smart contract can create a bazaar that allows anybody to create a pawnshop to offer collateralized loans.

This example demonstrates the power of contracts that deploy contracts. The PawnShopBazaar contract does little more than create PawnShop contracts for lenders, and those PawnShop contracts deploy individual Loan contracts as needed when borrowers and lenders make a deal. Contracts that deploy contracts that deploy contracts—pretty cool.

Capture the Ether: the Game of Smart Contract Security

Tue, 10 Apr 2018 09:39:49 -0700

Capture the Ether is a game that tests your understanding of smart contract security by challenging you to hack a series of smart contracts.

Capture the Flag Games

In the context of computer security, a Capture the Flag (CTF) competition is a game about finding and exploiting software vulnerabilities.

Capture the Ether is an Ethereum-specific CTF game.

Learn By Doing

My first experience with Capture the Flag games was when I was working at Dropbox. Our security team ran an internal CTF, and I became quite obsessed with it.

I certainly learned new things about security by participating, but for me the most valuable part was putting into practice things I already knew in the abstract. By writing exploits myself, I gained a better understanding for how even a seemingly small vulnerability can be incredibly dangerous.

I built Capture the Ether to provide that same rewarding experience for smart contract developers. Each challenge is in the form of a smart contract, and players earn points by exploiting it. It’s a test of your knowledge of smart contract security but also your ability to turn that abstract knowledge into a concrete exploit.

Results So Far

I launched the game last week with a Reddit post. At the time of this writing, 80 people have completed at least one of the challenges, and only two people have completed all 18 challenges in the initial batch. You can see the current high scores on the leaderboard.

More to Come

I have a few more challenges almost ready to publish, and my plan is to regularly add new challenges as I think of them. If you have ideas for new challenges, let me know! You can reach me at smarx@smarx.com.

Writing a Vickrey Auction Contract

Tue, 03 Apr 2018 11:00:33 -0700

This post will demonstrate how to implement a Vickrey auction. The post assumes you are familiar with techniques introduced in my post on sealed-bid auctions.

Without going into a lot of detail, there are many advantages to auctions in which the amount paid by the winner is not their bid, but rather the next highest bid. Such auctions are often called “second-price auctions” or “Vickrey auctions” (after the person who studied them).

Initialization, Bidding and Claiming Tokens

With the exception of determining the final selling price, implementing a second-price auction is essentially the same as implementing a first-price sealed-bid auctions. The following are identical:

Both auctions are parameterized by the same values: the token, the reserve price, a bidding period, and a revealing period.
Both auctions accept secret bids that are hashes of the actual bid and a random nonce.
Both auctions require attached ether that is at least as great as the secret bid.

pragma solidity ^0.4.21;

import "./ierc20token.sol";

contract VickreyAuction {
    address seller;

    IERC20Token public token;
    uint256 public reservePrice;
    uint256 public endOfBidding;
    uint256 public endOfRevealing;

    address public highBidder;
    uint256 public highBid;
    uint256 public secondBid;

    mapping(address => bool) public revealed;

    function VickreyAuction(
        IERC20Token _token,
        uint256 _reservePrice,
        uint256 biddingPeriod,
        uint256 revealingPeriod
    )
        public
    {
        token = _token;
        reservePrice = _reservePrice;

        endOfBidding = now + biddingPeriod;
        endOfRevealing = endOfBidding + revealingPeriod;

        seller = msg.sender;

        highBidder = seller;
        highBid = reservePrice;
        secondBid = reservePrice;

        // the seller can't bid, but this simplifies withdrawal logic
        revealed[seller] = true;
    }

    // more code here
}

The storage variables and constructor above are straightforward and similar to the sealed bid auction with just a few additions:

Storage variables for the highest and second-highest bids are declared and initialized. They are both initialized to the reserve price. These phony starting values simplify maintaining these values correctly as bids are revealed.
The revealed mapping keeps track of which accounts have revealed their bids.
The code initializes revealed[seller] to true, which will be exploited later in the withdrawal code.

The code for accepting sealed bids and that for claiming tokens is nearly identical to the analogous code in the sealed-bid auction:

mapping(address => uint256) public balanceOf;
mapping(address => bytes32) public hashedBidOf;

function bid(bytes32 hash) public payable {
    require(now < endOfBidding);
    require(msg.sender != seller);

    hashedBidOf[msg.sender] = hash;
    balanceOf[msg.sender] += msg.value;
    require(balanceOf[msg.sender] >= reservePrice);
}

function claim() public {
    require(now >= endOfRevealing);

    uint256 t = token.balanceOf(this);
    require(token.transfer(highBidder, t));
}

The bid code rejects bids from the seller, which eliminates the possibility that the seller can make a strategic bid, not reveal the bid, and yet get the associated ether refunded. This possibility would have existed because the contract’s constructor initialized revealed[seller] to true despite no actual revelation taking place.

Revelation

Any contract that has a reveal phase must deal with failures to reveal, either implicitly or explicitly. It’s important that the contract enforce the desired policy.

In the sealed-bid auction, the ether attached to unrevealed bids was simply refunded to the bidder. For the Vickrey auction contract, I will implement a much stricter policy—only ether attached to revealed losing bids will be refunded. Ether attached to unrevealed bids will be forfeited forever. This gives bidders a strong incentive to reveal their bids. It also gives the seller a strong disincentive from submitting phony bids (via another account) to manipulate the final settling price.

During the revelation period, the Vickrey auction must track both the highest bid (and bidder) as well as the second highest bid. As each bid is processed, the contract will transfer ether balances (in balanceOf) to reflect the results of the bidding so far. Those transfers will be done with the transfer helper routine:

function transfer(address from, address to, uint256 amount) private {
    balanceOf[to] += amount;
    balanceOf[from] -= amount;
}

The contract tracks which accounts have revealed their bids in revealed. Bidders are only allowed to reveal their bid once. This restriction avoids having to reason about the correctness of the code in the event of repeated reveals. Forbidding something is easier than reasoning about it.

function reveal(uint256 amount, uint256 nonce) public {
    require(now >= endOfBidding && now < endOfRevealing);

    require(keccak256(amount, nonce) == hashedBidOf[msg.sender]);

    require(!revealed[msg.sender]);
    revealed[msg.sender] = true;

    if (amount > balanceOf[msg.sender]) {
        // insufficient funds to cover bid amount, so ignore it
        return;
    }

    if (amount >= highBid) {
        // undo the previous escrow
        transfer(seller, highBidder, secondBid);

        // update the highest and second highest bids
        secondBid = highBid;
        highBid = amount;
        highBidder = msg.sender;

        // escrow an amount equal to the second highest bid
        transfer(highBidder, seller, secondBid);
    } else if (amount > secondBid) {
        // undo the previous escrow
        transfer(seller, highBidder, secondBid);

        // update the second highest bid
        secondBid = amount;

        // escrow an amount equal to the second highest bid
        transfer(highBidder, seller, secondBid);
   }
}

After every call to reveal, the following invariants hold:

balanceOf[X] represents the ether amount account X will be able withdraw given the bids seen so far.
highBidder represents the account making the highest bid given the bids seen so far. (If there were no successful bids, then this has the default value, which is the seller’s account.)
highBid represents the highest amount bid given the bids seen so far. (If there have been no successful bids, then this represents its default value, which is the reserve price.)
secondBid represents the amount that the high bidder will pay given the bids seen so far. (If there have been no successful bids, then this represents its default value, which is the reserve price.)

The initialization of highBid and secondBid to the reserve price is a subtle technique, and it deserves some explanation for the possible cases:

If there are no revealed bids at or above the reserve price, then reveal has no effect. This means highBidder will still be the seller’s account, and therefore the seller can withdraw their tokens.
If there is exactly one revealed bid at or above the reserve price, then highBid will be equal to that amount, and the amount paid will be the reserve price. This is the correct behavior for a Vickrey auction. (Note that the “undo the previous escrow” has no effect here because highBidder was initialized to seller, so the secondBid amount is added and subtracted from the same entry in balanceOf.)
If there is more than one revealed bid at or above the reserve price, then highBid will be the highest bid, and secondBid will be the second highest bid. The amount paid will be the second highest, which is correct as well.

Withdrawal

Withdrawal is nearly identical to the sealed-bid auction. The only change is that we require that a bidder have revealed their bid.

function withdraw() public {
    require(now >= endOfRevealing);
    require(revealed[msg.sender]);

    uint256 amount = balanceOf[msg.sender];
    balanceOf[msg.sender] = 0;
    msg.sender.transfer(amount);
}

Note that the constructor initialized revealed[seller] to true in anticipation of the seller withdrawing their ether after the auction.

Summary

This Vickrey auction contract uses the previously demonstrated techniques of using hashes for secrets, and attaching ether to secret bids.
To encourage bid revelation, the contract causes non-revealers to forfeit their ether.
Maintaining the highest and second highest bids is straightforward, although initializing them to the reserve price is subtle.

The Complete Contracts

vickreyauction.sol

pragma solidity ^0.4.21;

import "./ierc20token.sol";

contract VickreyAuction {
    address seller;

    IERC20Token public token;
    uint256 public reservePrice;
    uint256 public endOfBidding;
    uint256 public endOfRevealing;

    address public highBidder;
    uint256 public highBid;
    uint256 public secondBid;

    mapping(address => bool) public revealed;

    function VickreyAuction(
        IERC20Token _token,
        uint256 _reservePrice,
        uint256 biddingPeriod,
        uint256 revealingPeriod
    )
        public
    {
        token = _token;
        reservePrice = _reservePrice;

        endOfBidding = now + biddingPeriod;
        endOfRevealing = endOfBidding + revealingPeriod;

        seller = msg.sender;

        highBidder = seller;
        highBid = reservePrice;
        secondBid = reservePrice;

        // the seller can't bid, but this simplifies withdrawal logic
        revealed[seller] = true;
    }

    mapping(address => uint256) public balanceOf;
    mapping(address => bytes32) public hashedBidOf;

    function bid(bytes32 hash) public payable {
        require(now < endOfBidding);
        require(msg.sender != seller);

        hashedBidOf[msg.sender] = hash;
        balanceOf[msg.sender] += msg.value;
        require(balanceOf[msg.sender] >= reservePrice);
    }

    function claim() public {
        require(now >= endOfRevealing);

        uint256 t = token.balanceOf(this);
        require(token.transfer(highBidder, t));
    }

    function transfer(address from, address to, uint256 amount) private {
        balanceOf[to] += amount;
        balanceOf[from] -= amount;
    }

    function reveal(uint256 amount, uint256 nonce) public {
        require(now >= endOfBidding && now < endOfRevealing);

        require(keccak256(amount, nonce) == hashedBidOf[msg.sender]);

        require(!revealed[msg.sender]);
        revealed[msg.sender] = true;

        if (amount > balanceOf[msg.sender]) {
            // insufficient funds to cover bid amount, so ignore it
            return;
        }

        if (amount >= highBid) {
            // undo the previous escrow
            transfer(seller, highBidder, secondBid);

            // update the highest and second highest bids
            secondBid = highBid;
            highBid = amount;
            highBidder = msg.sender;

            // escrow an amount equal to the second highest bid
            transfer(highBidder, seller, secondBid);
        } else if (amount > secondBid) {
            // undo the previous escrow
            transfer(seller, highBidder, secondBid);

            // update the second highest bid
            secondBid = amount;

            // escrow an amount equal to the second highest bid
            transfer(highBidder, seller, secondBid);
       }
    }

    function withdraw() public {
        require(now >= endOfRevealing);
        require(revealed[msg.sender]);

        uint256 amount = balanceOf[msg.sender];
        balanceOf[msg.sender] = 0;
        msg.sender.transfer(amount);
    }
}

Storage Patterns: Doubly Linked List

Fri, 30 Mar 2018 09:44:41 -0700

In this post, I’ll build a doubly linked list in Solidity. A doubly linked list supports efficient insertion and deletion of nodes anywhere within an ordered list. I’ll be building on concepts introduced in “Understanding Ethereum Smart Contract Storage” and “Storage Patterns: Stacks, Queues, and Deques”.

The Nodes

In addition to the data being stored, each node in a doubly linked list has pointers to the previous and next node in the list:

contract DoublyLinkedList {
    struct Node {
        bytes data;
        uint256 prev;
        uint256 next;
    }

Note that the prev and next fields are of type uint256. There are no pointer types in Solidity, so each node in the list is given a unique ID, and the prev and next fields refer to those IDs. I’m using a dynamically-sized array to keep track of nodes, and a node’s index in the array is its ID:

// nodes[0].next is head, and nodes[0].prev is tail.
Node[] public nodes;

function DoublyLinkedList() public {
    // sentinel
    nodes.push(Node(new bytes(0), 0, 0));
}

The first element of the array is reserved as a sentinel. Its next link points to the head of the list, and its prev link points to the tail. Technically, what I’m building here is a circular doubly linked list where one element is a sentinel. If you were to keep following next or prev links, you would pass through the sentinel and back to the other end of the list.

Inserting a Node

A doubly-linked list supports insertion at arbitrary points within the list. When inserting into the list, a new node needs to be created, and the prev and next links in the neighboring nodes need to be updated:

function insertAfter(uint256 id, bytes data) public returns (uint256 newID) {
    // 0 is allowed here to insert at the beginning.
    require(id == 0 || isValidNode(id));

    Node storage node = nodes[id];

    nodes.push(Node({
        data: data,
        prev: id,
        next: node.next
    }));

    newID = nodes.length - 1;

    nodes[node.next].prev = newID;
    node.next = newID;
}

A brief explanation of the above code:

Node storage node declares a reference to a Node in storage. This is used here to make reading and writing that node’s fields easier.
nodes.push is essentially an allocation. It adds a new node to the array and initializes its fields.
nodes.length - 1 is the index in the array where the new node was added. This is considered the node’s ID.
Finally, the prev and next links in the neighboring nodes are updated to point to the new node.

isValidNode checks if the node specified by the id parameter is a valid node in the list:

function isValidNode(uint256 id) internal view returns (bool) {
    // 0 is a sentinel and therefore invalid.
    // A valid node is the head or has a previous node.
    return id != 0 && (id == nodes[0].next || nodes[id].prev != 0);
}

Given insertAfter, it’s trivial to implement insertBefore:

function insertBefore(uint256 id, bytes data) public returns (uint256 newID) {
    return insertAfter(nodes[id].prev, data);
}

Note that because this is a circular linked list, no special care needs to be taken with the head and tail of the list. To insert a node at the beginning of the list, call insertAfter(0, data). To insert a node at the end of the list, call insertBefore(0, data).

Removing a Node

Removing a node means updating its neighbors’ prev and next links and deleting the removed node to reclaim its storage:

function remove(uint256 id) public {
    require(isValidNode(id));

    Node storage node = nodes[id];

    nodes[node.next].prev = node.prev;
    nodes[node.prev].next = node.next;

    delete nodes[id];
}

Executing delete nodes[id] results in a gas refund for reclaiming storage space. Recall from our post “Understanding Ethereum Smart Contract Storage” that zeros are not actually stored, so deleting the node reclaims storage even though the underlying array length is not changed.

Summary

A doubly linked list is a useful data structure when arbitrary insertion or deletion is required and order is important.
Using a circular doubly linked list avoids edge cases when inserting or deleting nodes at the ends of the list.

Full Code

doublylinkedlist.sol

pragma solidity ^0.4.21;

contract DoublyLinkedList {
    struct Node {
        bytes data;
        uint256 prev;
        uint256 next;
    }

    // nodes[0].next is head, and nodes[0].prev is tail.
    Node[] public nodes;

    function DoublyLinkedList() public {
        // sentinel
        nodes.push(Node(new bytes(0), 0, 0));
    }

    function insertAfter(uint256 id, bytes data) public returns (uint256 newID) {
        // 0 is allowed here to insert at the beginning.
        require(id == 0 || isValidNode(id));

        Node storage node = nodes[id];

        nodes.push(Node({
            data: data,
            prev: id,
            next: node.next
        }));

        newID = nodes.length - 1;

        nodes[node.next].prev = newID;
        node.next = newID;
    }

    function insertBefore(uint256 id, bytes data) public returns (uint256 newID) {
        return insertAfter(nodes[id].prev, data);
    }

    function remove(uint256 id) public {
        require(isValidNode(id));

        Node storage node = nodes[id];

        nodes[node.next].prev = node.prev;
        nodes[node.prev].next = node.next;

        delete nodes[id];
    }

    function isValidNode(uint256 id) internal view returns (bool) {
        // 0 is a sentinel and therefore invalid.
        // A valid node is the head or has a previous node.
        return id != 0 && (id == nodes[0].next || nodes[id].prev != 0);
    }
}

Writing a Sealed-Bid Auction Contract

Tue, 27 Mar 2018 09:32:58 -0700

This post will demonstrate how to implement a first-price sealed-bid auction of ERC20 tokens. The post assumes you are familiar with techniques introduced in our posts on English auctions and revealing secrets.

First-price sealed-bid auctions proceed in a three-step process:

During a bidding period, each bidder submits a secret bid.
After the bidding period, all of the previously-secret bids are revealed.
The high bidder wins the auction in exchange for their entire bid amount.

To implement this as a smart contract, the code will follow that process, employing techniques we’ve previously introduced. For instance, the contract will use cryptographic hashes to submit secret bids.

We also want bids to have ether attached to ensure that the winning bid will, in fact, follow through with the purchase. This presents a challenge, however, because the amount of ether attached is not a secret on the blockchain. Therefore, the contract will require that bids have ether attached that equals or exceeds their secret bid.

Starting the Auction

A first-price sealed-bid auction is parameterized by a few values:

The good being sold. For this contract, that will be a given ERC20 token.
The reserve price is the lowest acceptable bid.
The bidding period is the amount of time during which bidders may submit bids.

In a real-world auction, bidders submit bids in sealed envelopes, and those bids are revealed by opening envelopes, which doesn’t require any cooperation from the bidders. In Ethereum, a bidder submits a hash of their bid, and then they must present the actual bid, which is verified against the hash they previously provided. Hence, the contract needs to give them some time to do that. To implement this as a smart contract, we also need another parameter:

The reveal period is the amount of time after the bidding closes that bidders can reveal their bids.

These values are easily captured in code:

pragma solidity ^0.4.21;

import "./ierc20token.sol";

contract EnglishAuction {
    address seller;

    IERC20Token public token;
    uint256 public reservePrice;
    uint256 public endOfBidding;
    uint256 public endOfRevealing;

    function EnglishAuction(
        IERC20Token _token,
        uint256 _reservePrice,
        uint256 biddingPeriod,
        uint256 revealingPeriod
    )
        public
    {
        token = _token;
        reservePrice = _reservePrice;

        endOfBidding = now + biddingPeriod;
        endOfRevealing = endOfBidding + revealingPeriod;

        seller = msg.sender;
    }

    // more to come...
}

Just like the English auction, this contract will operate on the assumption that the seller will transfer the tokens to it. Bidders should verify the transfer before placing bids, of course.

Bids and Escrowed Funds

Bidding requires the contract to log both the sealed bid (hash) and the amount of ether attached to the bid.

mapping(address => uint256) public balanceOf;
mapping(address => bytes32) public hashedBidOf;

function bid(bytes32 hash) public payable {
    require(now < endOfBidding);

    hashedBidOf[msg.sender] = hash;
    balanceOf[msg.sender] += msg.value;
    require(balanceOf[msg.sender] >= reservePrice);
}

A real-world sealed-bid auction typically allows only one bid. I’ve generalized that above to allow new bids that overwrite previous bids. All attached ether to multiple bids is accumulated.

Revealing Bids

The hash of a bid is computed with a random nonce exactly as introduced in the coin-flipping post. Bidders reveal their bids by providing both their bid and their nonce.

As bids are revealed, the contract will keep track of the high bidder and their bid, and it will adjust the balanceOf amounts so that it tracks non-escrowed ether. The current winning bid will also be reflected as the balanceOf[seller] so that it will be available to the seller after the auction.

address public highBidder = msg.sender;
uint256 public highBid;

function reveal(uint256 amount, uint256 nonce) public {
    require(now >= endOfBidding && now < endOfRevealing);

    require(keccak256(amount, nonce) == hashedBidOf[msg.sender]);

    require(amount >= reservePrice);
    require(amount <= balanceOf[msg.sender]);

    if (amount > highBid) {
        // return escrowed bid to previous high bidder
        balanceOf[seller] -= highBid;
        balanceOf[highBidder] += highBid;

        highBid = amount;
        highBidder = msg.sender;

        // transfer new high bid from high bidder to seller
        balanceOf[highBidder] -= highBid;
        balanceOf[seller] += highBid;
    }
}

The code above maintains the following invariants upon exit, which make withdrawing funds and claiming tokens trivial:

balanceOf[seller] represents the amount the seller will be able to withdraw given the bids seen so far.
balanceOf[X] represents the ether amount account X will be able withdraw given the bids seen so far.
highBidder represents the account making the highest bid given the bids seen so far.

Given those invariants, when revealing completes, all accounts—seller and bidders—may withdraw their balanceOf amount.

The code also employs one (very?) subtle feature: highBidder is initialized to msg.sender, which is the account that creates the auction (i.e, the seller). This default value is overwritten by the first successful bid, so it’s only important if there are no successful bids on this auction. This will be exploited below in claim.

The bid code allows seller-initiated bids, and reveal handles them correctly. It’s generally considered bad for sellers to bid in their own auction, but I’ve chosen to allow them because forbidding them would be futile. (It would be trivial for the seller to transfer ether to another account and bid from there.)

Withdrawal

function withdraw() public {
    require(now >= endOfRevealing);

    uint256 amount = balanceOf[msg.sender];
    balanceOf[msg.sender] = 0;
    msg.sender.transfer(amount);
}

Claiming

After the reveal period, the high bidder can claim their tokens:

function claim() public {
    require(now >= endOfRevealing);

    uint256 t = token.balanceOf(this);
    token.transfer(highBidder, t);
}

This routine trivially handles any auction for which there was a successful bid. More subtly, it also handles returning the tokens to the seller when there are no successful bids because highBidder’s default value is, in fact, that of the seller.

The high bidder can also claim any excess ether—the difference between their bid and the amount attached to the bid(s)—using withdraw.

Failing to Reveal Policy

Any contract that has a reveal phase must deal with failures to reveal, either implicitly or explicitly. It’s important that the contract enforce the desired policy.

As written, this contract does nothing explicit with respect to accounts that fail to reveal their bids.

What happens to the ether that was attached to an unrevealed bids? Ether attached to an unrevealed bid can be withdrawn after the revealing period—just as if it were attached to a losing bid.
What if the unrevealed bid would have won the auction? This is bad for the seller, obviously, because they would receive less ether. The bidder, too, suffers because they don’t get to claim the tokens at a price that they presumably would have wanted.
Can this be exploited by strategic bidding? Yes—a bidder could make multiple bids at different prices and only reveal the lowest winning bid. This is not entirely bad because they would still have to beat the bids revealed by other bidders. This strategy has merits because it allows this auction to result in a winning bid approximating a second-price auction. (It does, however, require the strategic bidder to use multiple accounts and to escrow ether for each of those bids.)

Summary

A smart contract can conduct a first-price sealed-bid auction.
The auction uses cryptographic hashes to implement sealed bids.

The Complete Contract

sealedbidauction.sol

pragma solidity ^0.4.21;

import "./ierc20token.sol";

contract SealedBidAuction {
    address seller;

    IERC20Token public token;
    uint256 public reservePrice;
    uint256 public endOfBidding;
    uint256 public endOfRevealing;

    function SealedBidAuction(
        IERC20Token _token,
        uint256 _reservePrice,
        uint256 biddingPeriod,
        uint256 revealingPeriod
    )
        public
    {
        token = _token;
        reservePrice = _reservePrice;

        endOfBidding = now + biddingPeriod;
        endOfRevealing = endOfBidding + revealingPeriod;

        seller = msg.sender;
    }

    mapping(address => uint256) public balanceOf;
    mapping(address => bytes32) public hashedBidOf;

    function bid(bytes32 hash) public payable {
        require(now < endOfBidding);

        hashedBidOf[msg.sender] = hash;
        balanceOf[msg.sender] += msg.value;
        require(balanceOf[msg.sender] >= reservePrice);
    }

    address public highBidder = msg.sender;
    uint256 public highBid;

    function reveal(uint256 amount, uint256 nonce) public {
        require(now >= endOfBidding && now < endOfRevealing);

        require(keccak256(amount, nonce) == hashedBidOf[msg.sender]);

        require(amount >= reservePrice);
        require(amount <= balanceOf[msg.sender]);

        if (amount > highBid) {
            // return escrowed bid to previous high bidder
            balanceOf[seller] -= highBid;
            balanceOf[highBidder] += highBid;

            highBid = amount;
            highBidder = msg.sender;

            // transfer new high bid from high bidder to seller
            balanceOf[highBidder] -= highBid;
            balanceOf[seller] += highBid;
        }
    }

    function withdraw() public {
        require(now >= endOfRevealing);

        uint256 amount = balanceOf[msg.sender];
        balanceOf[msg.sender] = 0;
        msg.sender.transfer(amount);
    }

    function claim() public {
        require(now >= endOfRevealing);

        uint256 t = token.balanceOf(this);
        token.transfer(highBidder, t);
    }
}

Storage Patterns: Stacks Queues and Deques

Fri, 23 Mar 2018 07:58:57 -0700

In this post, I’ll show how a few common data structures can be implemented in Solidity. I recommend first reading our post “Understanding Ethereum Smart Contract Storage.”

Stack

A stack is a “last-in, first-out” (LIFO) data structure with the operations push and pop. This is a natural fit for Solidity’s dynamically-sized arrays, but note that Solidity does not (yet) provide a pop operation. The below is an implementation of a stack of bytes:

stack.sol

pragma solidity ^0.4.21;

contract Stack {
    bytes[] stack;

    function push(bytes data) public {
        stack.push(data);
    }

    function pop() public returns (bytes data) {
        data = stack[stack.length - 1];

        stack.length -= 1;
    }
}

A few things to note in the above code:

If the array is empty, bounds checking will cause pop to revert the transaction.
Decreasing the length of a dynamically-sized array has a side effect of zeroing the “removed” items. This is why there’s no need for a delete stack[stack.length - 1].

Queue

A queue is a “first-in, first-out” (FIFO) data structure with the operations enqueue and dequeue. It’s reasonable to implement this with a dynamically-sized array, but a mapping may be a better choice:

queue.sol

pragma solidity ^0.4.21;

contract Queue {
    mapping(uint256 => bytes) queue;
    uint256 first = 1;
    uint256 last = 0;

    function enqueue(bytes data) public {
        last += 1;
        queue[last] = data;
    }

    function dequeue() public returns (bytes data) {
        require(last >= first);  // non-empty queue

        data = queue[first];

        delete queue[first];
        first += 1;
    }
}

A brief explanation of the above code:

Items are stored at consecutive indices in the queue mapping. The first used index will be 1.
first indicates the first valid index in the queue. It starts at 1 so I can use 0 for last.
last indicates the last valid index in the queue. It starts at 0 because there are initially no valid indices.
Unlike in the stack contract, where decreasing the array size took care of it, this contract needs to call delete to clear storage when an element is dequeued.

Dynamically-sized arrays and mappings in Solidity are not very different. They both map keys to values. Arrays are limited to uint256 keys, and they do bounds checking. Dynamically-sized arrays also record their length and perform some automated cleanup when that length is adjusted.

In the stack implementation, I made use of the bounds checking and automatic cleanup. In the case of a queue, both of those things need to be done manually, at least on the “left” side of the queue. For that reason, a mapping seemed like a more natural fit to me.

Deque

A deque (sometimes “dequeue” or “double-ended queue”) is a generalization of a queue that allows insertion and deletion from both ends. It supports the operations pushLeft, pushRight, popLeft, and popRight:

deque.sol

pragma solidity ^0.4.21;

contract Deque {
    mapping(uint256 => bytes) deque;
    uint256 first = 2**255;
    uint256 last = first - 1;

    function pushLeft(bytes data) public {
        first -= 1;
        deque[first] = data;
    }

    function pushRight(bytes data) public {
        last += 1;
        deque[last] = data;
    }

    function popLeft() public returns (bytes data) {
        require(last >= first);  // non-empty deque

        data = deque[first];

        delete deque[first];
        first += 1;
    }

    function popRight() public returns (bytes data) {
        require(last >= first);  // non-empty deque

        data = deque[last];

        delete deque[last];
        last -= 1;
    }
}

This code is much like the queue implementation except that the queue can grow in both directions. To maximize how much room is available to grow, first is initialized to 2²⁵⁵, exactly half way through the 256-bit space available for indices.

Summary

With a basic understanding of Solidity storage, simple data structures can be implemented with very little code.
Dynamically-sized arrays and mappings are quite similar. In many cases, either can be used, and the decision comes down to what makes the code easier to read.

Writing a Token Auction Contract

Tue, 20 Mar 2018 10:39:42 -0700

This post will demonstrate how to write a smart contract that will auction off ERC20 tokens to the highest bidder. The post assumes you are familiar with techniques for how a contract deals with an ERC20 token contract, which we covered in our token sale post. The post will briefly touch on some of the challenges around conducting auctions on the blockchain.

There are many kinds of auctions, and this post will describe a contract that implements an English auction: bidders will alternate making higher and higher bids until there are no more bids, at which time the highest bid will be accepted in return for the good being sold.

Starting the Auction

An auction is typically parameterized by a few values:

The good being sold. For this contract, that will be a given ERC20 token.
The reserve price is the lowest acceptable bid.
The minimum increment is the smallest amount that each successive bid must increase by.
The timeout period is the amount of time that bidders have after a successful bid to make a new bid. If no successful bids are made during that period, then the auction terminates.

These values are easily captured in code:

pragma solidity ^0.4.21;

import "./ierc20token.sol";

contract EnglishAuction {
    address seller;

    IERC20Token public token;
    uint256 public reservePrice;
    uint256 public minIncrement;
    uint256 public timeoutPeriod;

    uint256 public auctionEnd;

    function EnglishAuction(
        IERC20Token _token,
        uint256 _reservePrice,
        uint256 _minIncrement,
        uint256 _timeoutPeriod
    )
        public
    {
        token = _token;
        reservePrice = _reservePrice;
        minIncrement = _minIncrement;
        timeoutPeriod = _timeoutPeriod;

        seller = msg.sender;
        auctionEnd = now + timeoutPeriod;
    }

    // more to come...
}

The contract must, of course, keep track of who the seller is, which the constructor sets.

For simplicity, I am assuming that the auction starts immediately upon creation, so the original auctionEnd is set timeoutPeriod in the future.

This contract will operate on the assumption that the seller will transfer the tokens to it. The seller’s transfer is not part of the contract itself, however, and must be done after contract deployment. Bidders can check that the transfer has been done by querying the token’s balanceOf value that corresponds to the contract’s address. It is essential that bidders check this value so that they know how many tokens are guaranteed to be transferred to the winner.

Escrowed Funds

In a real-world auction, bidders are typically trusted to actually buy the auctioned good if they win the auction. Smart contracts, on the other hand, don’t typically trust participants to make good on their promises. Therefore, my auction contract will demand that all bids come with ether attached that will be used if the bid wins.

Escrowed bids guarantee that the funds are available for the winner to pay, but they complicate the smart contract because now losing bidders must be able to recover their escrowed funds. I will implement this with the simple pattern introduced in the banking post.

address highBidder;

mapping(address => uint256) public balanceOf;

function withdraw() public {
    require(msg.sender != highBidder);

    uint256 amount = balanceOf[msg.sender];
    balanceOf[msg.sender] = 0;
    msg.sender.transfer(amount);
}

The balanceOf mapping tracks the ether available to be withdrawn by any account, and withdraw transfers that amount. The function does not allow withdrawals from the current high bidder because their funds are escrowed.

Note that the code does not check to see if the auction is over—losing bidders may withdraw their funds at any time.

Bids

A successful bid must meet the following requirements:

It must be made before the end of the auction.
It must be at least the reserve amount.
It must be at least the minimum increment over the current high bid. (Before any bids have been accepted, the high bid is considered to be zero.)

Bids must have ether attached. The bid function will assume that the bidder is bidding all the attached ether and any previously escrowed funds.

event Bid(address highBidder, uint256 highBid);

function bid(uint256 amount) public payable {
    require(now < auctionEnd);
    require(amount >= reservePrice);
    require(amount >= balanceOf[highBidder]+minIncrement);

    balanceOf[msg.sender] += msg.value;
    require(balanceOf[msg.sender] == amount);

    highBidder = msg.sender;

    auctionEnd = now + timeoutPeriod;

    emit Bid(highBidder, amount);
}

The amount parameter is not strictly necessary, but I’ve put it there to protect bidders from making mistakes regarding the sum of the attached ether and escrowed ether. The amount declares their intended bid.

One subtlety is that balanceOf[highBidder] is the amount of the high bid.

Auction End

An auction finishes in one of two states: with or without a winning bid. If the auction was unsuccessful, then the tokens need to be returned to the seller. Otherwise, the tokens need to be transferred to the winning bidder and the winning bid needs to be made available to the seller.

function resolve() public {
    require(now >= auctionEnd);

    uint256 t = token.balanceOf(this);
    if (highBidder == 0) {
        require(token.transfer(seller, t));
    } else {
        // transfer tokens to high bidder
        require(token.transfer(highBidder, t));

        // transfer ether balance to seller
        balanceOf[seller] += balanceOf[highBidder];
        balanceOf[highBidder] = 0;

        highBidder = 0;
    }
}

There are a few notable things about resolve:

The function did not try to transfer ether directly to the seller. That avoids potential problems if the seller is a badly behaving contract, which might prevent the high bidder from ever getting their tokens.
The function did not try to transfer ether to the seller via selfdestruct. This is because there may still be losing bidders who have not yet retrieved their funds.
Anybody can call resolve—it’s not limited to the seller or winning bidder.
The highBidder is set to zero to allow the seller to withdraw funds if they won their own auction. It also reduces gas costs.

If this contract used the indirect approve/transferFrom pattern, the resolve would have been more complicated because it would have required logic to refund ether to the winning bidder in the case where transferFrom fails due to lack of approval.

Summary

A smart contract can conduct an English auction.
To ensure payment, bids must include an advance payment, which can be refunded should the bid not prevail.

The Complete Contracts

englishauction.sol

pragma solidity ^0.4.21;

import "./ierc20token.sol";

contract EnglishAuction {
    address seller;

    IERC20Token public token;
    uint256 public reservePrice;
    uint256 public minIncrement;
    uint256 public timeoutPeriod;

    uint256 public auctionEnd;

    function EnglishAuction(
        IERC20Token _token,
        uint256 _reservePrice,
        uint256 _minIncrement,
        uint256 _timeoutPeriod
    )
        public
    {
        token = _token;
        reservePrice = _reservePrice;
        minIncrement = _minIncrement;
        timeoutPeriod = _timeoutPeriod;

        seller = msg.sender;
        auctionEnd = now + timeoutPeriod;
    }

    address highBidder;

    mapping(address => uint256) public balanceOf;

    function withdraw() public {
        require(msg.sender != highBidder);

        uint256 amount = balanceOf[msg.sender];
        balanceOf[msg.sender] = 0;
        msg.sender.transfer(amount);
    }

    event Bid(address highBidder, uint256 highBid);

    function bid(uint256 amount) public payable {
        require(now < auctionEnd);
        require(amount >= reservePrice);
        require(amount >= balanceOf[highBidder]+minIncrement);

        balanceOf[msg.sender] += msg.value;
        require(balanceOf[msg.sender] == amount);

        highBidder = msg.sender;

        auctionEnd = now + timeoutPeriod;

        emit Bid(highBidder, amount);
    }

    function resolve() public {
        require(now >= auctionEnd);

        uint256 t = token.balanceOf(this);
        if (highBidder == 0) {
            require(token.transfer(seller, t));
        } else {
            // transfer tokens to high bidder
            require(token.transfer(highBidder, t));

            // transfer ether balance to seller
            balanceOf[seller] += balanceOf[highBidder];
            balanceOf[highBidder] = 0;

            highBidder = 0;
        }
    }
}

Flipping a Coin in Ethereum

Fri, 16 Mar 2018 11:09:36 -0700

In this post, I’ll describe how two parties can bet on a coin flip in an Ethereum smart contract by using a simple commitment scheme.

Overview

In the real world, betting on a coin flip might happen like this:

Player 1 flips a coin and catches it on their arm, face down and covered. At this point, the outcome of the flip is already determined but kept secret.
Player 2 chooses “heads” or “tails.”
Player 1 reveals the outcome of the flip. If player 2 guessed it correctly, they win. Otherwise, player 1 wins.

I’ll model this interaction in Ethereum using a commitment scheme:

Player 1 will commit to a boolean value (representing “heads” or “tails”), keeping the chosen value secret.
Player 2 will guess at that boolean value.
Player 1 will reveal the original boolean value.

Committing with a Hash

There are many different commitment schemes, but the simplest and easiest to implement in an Ethereum smart contract uses a cryptographic hash function. To commit to a message, the committer just shares the hash of that message. When the message is later revealed, anyone can easily verify that its hash matches the hash shared earlier.

Cryptographic hash functions have a few important properties that make them suitable for commitment schemes:

They are deterministic, so a hash of a message can later be verified by hashing the message again.
It’s infeasible to find two different messages that hash to the same value, so a hash is truly a commitment to a single message.
It’s impossible to generate a message from its hash more efficiently than trying all possible messages.

That last point has a corollary: if the number of possible messages is small, it’s easy to reverse a hash. For the coin flip example, player 1 needs to commit to a boolean. Just hashing that boolean (hash(0) or hash(1)) would be trivial to reverse because there are only two possible inputs.

A simple way to make guessing infeasible is to add a large random nonce to the message being hashed. In the CoinFlip contract, I’ll hash a boolean along with a 32-byte nonce.

Offering a Bet

The first player offers a bet by deploying the CoinFlip contract.

contract CoinFlip {
    address public player1;
    bytes32 public player1Commitment;

    uint256 public betAmount;

    function CoinFlip(bytes32 commitment) public payable {
        player1 = msg.sender;
        player1Commitment = commitment;
        betAmount = msg.value;
    }

By deploying the contract, the first player escrows their bet and commits to a boolean value representing heads or tails. The commitment is the keccak-256 hash of the boolean value and a 32-byte nonce. The boolean and nonce are kept secret and used later in the reveal phase.

As an example, the commitment hash could be computed using Node.js and ethereumjs-abi as follows:

const abi = require('ethereumjs-abi');
const crypto = require('crypto');

// This could come from user input or be randomly generated.
const secretChoice = true;

const nonce = "0x" + crypto.randomBytes(32).toString('hex');

const hash = "0x" + abi.soliditySHA3(
  ["bool", "uint256"],
  [secretChoice, nonce]).toString('hex');

Taking a Bet

The second player takes the bet by calling takeBet.

address public player2;
bool public player2Choice;

uint256 public expiration = 2**256 - 1;  // effectively infinite

function takeBet(bool choice) public payable {
    require(player2 == 0);
    require(msg.value == betAmount);

    player2 = msg.sender;
    player2Choice = choice;

    expiration = now + 24 hours;
}

A brief explanation of the above code:

The expiration starts off at 2²⁵⁶-1, the maximum value for a uint256.
Only one account is allowed to take the bet. require(player2 == 0) ensures that no other account has already taken the bet.
The second player must match the first player’s bet.
The second player bets on either heads or tails by simply passing a boolean. There’s no need to keep this value a secret, as the first player has already committed to their choice.
When the second player takes the bet, a timeout is started. The first player has until the end of that timeout to reveal their secret, after which their bet is forfeit. Without this timeout, the first player could refuse to reveal a losing secret and prevent the second player from collecting their winnings.

Revealing the Flip

Once the second player has made their bet, the first player can settle the bet by revealing the original choice (heads or tails) and nonce. The two combined are the preimage of the commitment hash.

function reveal(bool choice, uint256 nonce) public {
    require(player2 != 0);
    require(now < expiration);

    require(keccak256(choice, nonce) == player1Commitment);

    if (player2Choice == choice) {
        player2.transfer(address(this).balance);
    } else {
        player1.transfer(address(this).balance);
    }
}

A brief explanation of the above code:

reveal can only be called once the bet is taken and only before the expiration has been reached.
The choice and nonce must satisfy the commitment made when the contract was deployed. This ensures that the first player cannot cheat.
player2 wins if they successfully chose the same value as player1. Otherwise, player1 wins.
All ether is immediately transferred to the winner.

You may be surprised to see that there are no restrictions on which account can call this function. Only the correct original choice will produce the commitment hash, so it doesn’t matter who supplies it.

Refusing to Reveal

If the first player refuses to reveal their choice, their bet is forfeit. The second player can claim their prize by calling claimTimeout.

function claimTimeout() public {
    require(now >= expiration);

    player2.transfer(address(this).balance);
}

As with reveal, it doesn’t matter who calls this function.

Canceling a Bet

If no one takes the bet, it should be possible for the first player to cancel the bet and reclaim their ether.

function cancel() public {
    require(msg.sender == player1);
    require(player2 == 0);

    betAmount = 0;
    msg.sender.transfer(address(this).balance);
}

A brief explanation of the above code:

The two requires ensure that only the first player can cancel the offered bet and that they can only do so if no one has taken the bet yet.
betAmount = 0 ensures that if someone sends ether to takeBet after the offer has been canceled, their bet will be rejected.

Why Not Use `selfdestruct`?

It’s tempting to use selfdestruct to distribute ether and clean up the contract when the bet is settled or canceled. However, this could lead to an unfortunate race condition.

When a contract calls selfdestruct, its code is deleted. This makes it work much like an externally owned account (EOA). Any transaction sent to it will be accepted, including those with attached ether.

The following scenario is an example of why this is a problem:

Player 1 deploys a new CoinFlip contract.
Player 2 submits a transaction to call takeBet.
While that transaction is still pending, player 1 calls cancel. (Imagine that cancel is implemented with selfdestruct.)
Player 2’s takeBet transaction arrives.

Because the contract has been destroyed, there’s no code to revert that late transaction. The ether attached is transferred to the contract and locked in there forever.

As a generalization, it’s a bad idea to use selfdestruct on a contract that accepts ether.

Summary

A commitment scheme is a way to commit to a secret choice and reveal it later without the possibility of changing it.
Hash functions can be reversed only by guessing the preimage.
A nonce is a good way to ensure that a hash preimage cannot be guessed.
It’s important to consider what happens if the committer refuses to reveal their secret.

Full Source Code

coinflip.sol

pragma solidity ^0.4.21;

contract CoinFlip {
    address public player1;
    bytes32 public player1Commitment;

    uint256 public betAmount;

    address public player2;
    bool public player2Choice;

    uint256 public expiration = 2**256-1;

    function CoinFlip(bytes32 commitment) public payable {
        player1 = msg.sender;
        player1Commitment = commitment;
        betAmount = msg.value;
    }

    function cancel() public {
        require(msg.sender == player1);
        require(player2 == 0);

        betAmount = 0;
        msg.sender.transfer(address(this).balance);
    }

    function takeBet(bool choice) public payable {
        require(player2 == 0);
        require(msg.value == betAmount);

        player2 = msg.sender;
        player2Choice = choice;

        expiration = now + 24 hours;
    }

    function reveal(bool choice, uint256 nonce) public {
        require(player2 != 0);
        require(now < expiration);

        require(keccak256(choice, nonce) == player1Commitment);

        if (player2Choice == choice) {
            player2.transfer(address(this).balance);
        } else {
            player1.transfer(address(this).balance);
        }
    }

    function claimTimeout() public {
        require(now >= expiration);

        player2.transfer(address(this).balance);
    }
}

Writing an ERC20 Pawnshop Contract

Tue, 13 Mar 2018 06:11:09 -0700

This post will demonstrate how to write a pawnshop-like smart contract that will lend ether to anybody willing to provide ERC20 tokens as collateral. The post adopts and generalizes techniques that we covered in our collateralized-loan post.

The collateralized loan post described a simple take-it-or-leave-it borrower-driven offer. The borrower offered a set token amount as collateral with given loan terms and waited for a lender to meet those exact terms. The contract in this post will be lender-driven instead, and it will allow multiple borrowers. Each borrower will choose how many tokens to use as collateral and will receive ether proportionally. By serving multiple borrowers, the contract acts like a blockchain-based pawnshop.

The Pawnshop Contract

The PawnShop contract will handle the creation of loans to any account that puts up tokens as collateral. This contract will be parameterized with the following values:

The ERC20 token that the pawnshop accepts as collateral. To keep things simple, I assume that a pawnshop contract only accepts one kind of token.
The loan amount, which is the amount of wei per token unit that the pawnshop is willing to lend in exchange for holding tokens as collateral. This is given as a rational number—see the token market post for details.
The payoff amount, which is the amount of wei per token unit that the borrower must pay the pawnshop to reclaim its tokens. This is also given as a rational number.
The loan’s duration during which the borrower can pay off its loan.

Keeping track of these in the pawnshop is straightforward:

contract PawnShop is Mortal {
    struct Rational {
        uint256 numerator;
        uint256 denominator;
    }

    IERC20Token public token;
    Rational public loanWeiPerUnit;
    Rational public payoffWeiPerUnit;
    uint256 public loanDuration;

    function PawnShop(
        address lender,
        IERC20Token _token,
        uint256 loanNumerator,
        uint256 loanDenominator,
        uint256 payoffNumerator,
        uint256 payoffDenominator,
        uint256 _loanDuration
    )
        public
        payable
    {
        owner = lender;
        token = _token;
        loanWeiPerUnit = Rational(loanNumerator, loanDenominator);
        payoffWeiPerUnit = Rational(payoffNumerator, payoffDenominator);
        loanDuration = _loanDuration;
    }

    function multiply(Rational r, uint256 x) internal pure returns (uint256) {
        if (x == 0) { return 0; }
        uint256 v = x * r.numerator;
        assert(v / x == r.numerator);  // avoid overflow
        return v / r.denominator;
    }

    // ...
}

A few things to note about the code above:

I’ve referenced an IERC20Token interface for storing the address of the token. This was discussed in token sale post.
PawnShop inherits from Mortal (introduced previously), which means that it will have an owner, and that the owner can kill the contract at will.
The Mortal inheritance hides the fact that owner will automatically be set upon creation to the account that deployed the contract.
The Rational struct holds wei/unit values for the loan and ultimate payoff.
The Rational wei/unit values cannot be passed as structs due to (temporary?) limitations of the Solidity compiler, so they are passed as individual values that are reconstituted in the constructor.
The multiply routine implements multiplying by a rational number. The code checks for overflow to avoid a potential vulnerability.

Creating a Loan Contract

I will use the Loan contract unchanged from the collateralized-loan post to keep track of individual loans created by the pawnshop.

The PawnShop contract will fulfill loan requests with the pawnTokens function:

event LoanCreated(
    address loan,
    address indexed borrower,
    IERC20Token token,
    uint256 tokenAmount,
    uint256 etherDue,
    uint256 dueDate
);

function pawnTokens(uint256 unitQuantity) public {
    uint256 totalLoan = multiply(loanWeiPerUnit, unitQuantity);
    uint256 totalPayoff = multiply(payoffWeiPerUnit, unitQuantity);
    address loan = new Loan(owner, msg.sender, token, unitQuantity,
        totalPayoff, loanDuration);
    require(token.transferFrom(msg.sender, loan, unitQuantity));
    msg.sender.transfer(totalLoan);

    emit LoanCreated(loan, msg.sender, token, unitQuantity, totalPayoff,
        now+loanDuration);
}

Explanation of the code above:

unitQuantity is the amount (in units) of tokens that the borrower wishes to use as collateral.
address loan = new Loan(...) deploys a new Loan contract for this loan.
token.transferFrom(...) transfers the tokens from the borrower to the loan contract.
The loaned ether is sent to the borrower.
The LoanCreated event signals to the borrower and lender that the loan has been created and lets them know the address of the deployed Loan contract. (The borrower needs the address to pay off the loan, and the lender may need it to repossess the tokens.)

The code above is deceptively simple, and it hides a few very important details, which must be noted:

How does the borrower know that the contract has enough ether to pay it? If the contract had insufficient funds, the msg.sender.transfer(totalLoan) would fail, which would cause the whole transaction to fail.
If the transaction fails, and the borrower doesn’t get ether, what happens to its tokens? Nothing happens to them. The borrower only approved a transfer, and the transfer didn’t happen.

Once the Loan contract has been deployed, it functions exactly as described in the collateralized-loan post, and it has no subsequent interactions with the PawnShop contract.

Note

I made PawnShop mortal so that the owner could choose to kill it and recoup any leftover ether. This is essential to protecting the owner’s ability to stop making loans if the value of the the tokens changes significantly.

An important concern whenever you see a contract that can be killed is whether or not that functionality creates unexpected consequences. In this scenario, the question is whether killing the pawnshop contract creates any problems with already-deployed loan contracts.

Inspecting the Loan contract code makes it clear that the Loan contracts do not depend in any way on the continued existence of the PawnShop contract.

Summary

The PawnShop contract allows a single lender to offer loans on fixed terms to potentially many borrowers.
Borrowers choose how many tokens to offer as collateral and receive ether proportionally.
Rational numbers support arbitrary rates in the loan terms.

The Complete Contract

The complete code for the PawnShop contract is below. I’ve used Solidity’s import directive to indicate that the code for IERC20Token and Loan will be loaded from separate files. (They were presented in the collateralized-loan post.)

pawnshop.sol

pragma solidity ^0.4.21;

import "./ierc20token.sol";
import "./loan.sol";

contract Ownable {
    address owner = msg.sender;
    modifier onlyOwner {
        require(msg.sender == owner);
        _;
    }
}

contract Mortal is Ownable {
    function kill() public onlyOwner {
        selfdestruct(msg.sender);
    }
}

contract PawnShop is Mortal {
    struct Rational {
        uint256 numerator;
        uint256 denominator;
    }

    IERC20Token public token;
    Rational public loanWeiPerUnit;
    Rational public payoffWeiPerUnit;
    uint256 public loanDuration;

    function PawnShop(
        address lender,
        IERC20Token _token,
        uint256 loanNumerator,
        uint256 loanDenominator,
        uint256 payoffNumerator,
        uint256 payoffDenominator,
        uint256 _loanDuration
    )
        public
        payable
    {
        owner = lender;
        token = _token;
        loanWeiPerUnit = Rational(loanNumerator, loanDenominator);
        payoffWeiPerUnit = Rational(payoffNumerator, payoffDenominator);
        loanDuration = _loanDuration;
    }

    function multiply(Rational r, uint256 x) internal pure returns (uint256) {
        if (x == 0) { return 0; }
        uint256 v = x * r.numerator;
        assert(v / x == r.numerator);  // avoid overflow
        return v / r.denominator;
    }

    event LoanCreated(
        address loan,
        address indexed borrower,
        IERC20Token token,
        uint256 tokenAmount,
        uint256 etherDue,
        uint256 dueDate
    );

    function pawnTokens(uint256 unitQuantity) public {
        uint256 totalLoan = multiply(loanWeiPerUnit, unitQuantity);
        uint256 totalPayoff = multiply(payoffWeiPerUnit, unitQuantity);
        address loan = new Loan(owner, msg.sender, token, unitQuantity,
            totalPayoff, loanDuration);
        require(token.transferFrom(msg.sender, loan, unitQuantity));
        msg.sender.transfer(totalLoan);

        emit LoanCreated(loan, msg.sender, token, unitQuantity, totalPayoff,
            now+loanDuration);
    }

    function deposit() public payable {}  // enable owner to add more ether
}

Understanding Ethereum Smart Contract Storage

Fri, 09 Mar 2018 06:45:17 -0800

Ethereum smart contracts use an uncommon storage model that often confuses new developers. In this post, I’ll describe that storage model and explain how the Solidity programming language makes use of it.

One Astronomically Large Array

Each smart contract running in the Ethereum Virtual Machine (EVM) maintains state in its own permanent storage. This storage can be thought of as a very large array, initially full of zeros. Each value in the array is 32-bytes wide, and there are 2²⁵⁶ such values. A smart contract can read from or write to a value at any location. That’s the extent of the storage interface.

I encourage you to stick with the “astronomically large array” mental model, but be aware that this is not how storage is implemented on the physical computers that make up the Ethereum network. Storage is extremely sparsely populated, and there’s no need to store the zeros. A key/value store mapping 32-byte keys to 32-byte values will do the job nicely. An absent key is simply defined as mapping to the value zero.

Because zeros don’t take up any space, storage can be reclaimed by setting a value to zero. This is incentivized in smart contracts with a gas refund when you change a value to zero.

Locating Fixed-Sized Values

In this storage model, where do things actually go? For known variables with fixed sizes, it makes sense to just give them reserved locations in storage. The Solidity programming language does just that.

contract StorageTest {
    uint256 a;
    uint256[2] b;

    struct Entry {
        uint256 id;
        uint256 value;
    }
    Entry c;
}

In the above code:

a is stored at slot 0. (Solidity’s term for a location within storage is a “slot.”)
b is stored at slots 1, and 2 (one for each element of the array).
c starts at slot 3 and consumes two slots, because the Entry struct stores two 32-byte values.

These slots are determined at compile time, strictly based on the order in which the variables appear in the contract code.

Locating Dynamically-Sized Values

Using reserved slots works well for fixed-size state variables, but it doesn’t work for dynamically-sized arrays and mappings because there’s no way of knowing how many slots to reserve.

If you’re thinking of computer RAM or hard drive as an analogy, you might expect that there’s an “allocation” step to find free space to use and then a “release” step to put that space back into the pool of available storage.

This is unnecessary due to the astronomical scale of smart contract storage. There are 2²⁵⁶ locations to choose from in storage, which is approximately the number of atoms in the known, observable universe. You could choose storage locations at random without ever experiencing a collision. The locations you chose would be so far apart that you could store as much data as you wanted at each location without running into the next one.

Of course, choosing locations at random wouldn’t be very helpful, because you would have no way to find the data again. Solidity instead uses a hash function to uniformly and repeatably compute locations for dynamically-sized values.

Dynamically-Sized Arrays

A dynamically-sized array needs a place to store its size as well as its elements.

contract StorageTest {
    uint256 a;     // slot 0
    uint256[2] b;  // slots 1-2

    struct Entry {
        uint256 id;
        uint256 value;
    }
    Entry c;       // slots 3-4
    Entry[] d;
}

In the above code, the dynamically-sized array d is at slot 5, but the only thing that’s stored there is the size of d. The values in the array are stored consecutively starting at the hash of the slot.

The following Solidity function computes the location of an element of a dynamically-sized array:

function arrLocation(uint256 slot, uint256 index, uint256 elementSize)
    public
    pure
    returns (uint256)
{
    return uint256(keccak256(slot)) + (index * elementSize);
}

Mappings

A mapping requires an efficient way to find the location corresponding to a given key. Hashing the key is a good start, but care must be taken to make sure different mappings generate different locations.

contract StorageTest {
    uint256 a;     // slot 0
    uint256[2] b;  // slots 1-2

    struct Entry {
        uint256 id;
        uint256 value;
    }
    Entry c;       // slots 3-4
    Entry[] d;     // slot 5 for length, keccak256(5)+ for data

    mapping(uint256 => uint256) e;
    mapping(uint256 => uint256) f;
}

In the above code, the “location” for e is slot 6, and the location for f is slot 7, but nothing is actually stored at those locations. (There’s no length to be stored, and individual values need to be located elsewhere.)

To find the location of a specific value within a mapping, the key and the mapping’s slot are hashed together.

The following Solidity function computes the location of a value:

function mapLocation(uint256 slot, uint256 key) public pure returns (uint256) {
    return uint256(keccak256(key, slot));
}

Note that when keccak256 is called with multiple parameters, the parameters are concatenated together before hashing. Because the slot and key are both inputs to the hash function, there aren’t collisions between different mappings.

Combinations of Complex Types

Dynamically-sized arrays and mappings can be nested within each other recursively. When that happens, the location of a value is found by recursively applying the calculations defined above. This sounds more complex than it is.

contract StorageTest {
    uint256 a;     // slot 0
    uint256[2] b;  // slots 1-2

    struct Entry {
        uint256 id;
        uint256 value;
    }
    Entry c;       // slots 3-4
    Entry[] d;     // slot 5 for length, keccak256(5)+ for data

    mapping(uint256 => uint256) e;    // slot 6, data at h(k . 6)
    mapping(uint256 => uint256) f;    // slot 7, data at h(k . 7)

    mapping(uint256 => uint256[]) g;  // slot 8
    mapping(uint256 => uint256)[] h;  // slot 9
}

To find items within these complex types, we can use the functions defined above. To find g[123][0]:

// first find arr = g[123]
arrLoc = mapLocation(8, 123);  // g is at slot 8

// then find arr[0]
itemLoc = arrLocation(arrLoc, 0, 1);

To find h[2][456]:

// first find map = h[2]
mapLoc = arrLocation(9, 2, 1);  // h is at slot 9

// then find map[456]
itemLoc = mapLocation(mapLoc, 456);

Summary

Each smart contract has storage in the form of an array of 2²⁵⁶ 32-byte values, all initialized to zero.
Zeros are not explicitly stored, so setting a value to zero reclaims that storage.
Solidity locates fixed-size values at reserved locations called slots, starting at slot 0.
Solidity exploits the sparseness of storage and the uniform distribution of hash outputs to safely locate dynamically-sized values.

The following table shows how storage locations are computed for different types. The “slot” refers to the next available slot when the state variable is encountered at compile time, and a dot indicates binary concatenation:

Kind	Declaration	Value	Location
Simple variable	`T v`	`v`	v's slot
Fixed-size array	`T[10] v`	`v[n]`	(v's slot) + n * (size of T)
Dynamic array	`T[] v`	`v[n]`	keccak256(v's slot) + n * (size of T)
		`v.length`	v's slot
Mapping	`mapping(T1 => T2) v`	`v[key]`	keccak256(key . (v's slot))

Writing a Collateralized Loan Contract

Tue, 06 Mar 2018 07:13:04 -0700

[EDIT 2018-03-13] This post has been updated to use Solidity 0.4.21 event syntax.

This post will demonstrate how to write a smart contract that will administer an ether loan while holding ERC20 tokens as collateral. The post assumes you are familiar with techniques for how a contract deals with an ERC20 token contract, which we covered in our token sale post. The post introduces the technique of having a smart contract deploy a second contract to carry out future work.

Borrowing ether using ERC20 tokens as collateral is an example transaction that a smart contract can broker easily. To keep payments really simple, I will assume that loans are paid off with a single ether payment that must be made before a given deadline.

For instance, at the time of this writing, one REP token is worth about 0.05 ETH, so a lender might be happy to lend 0.03 ETH for a couple weeks to a borrower willing to transfer 1.0 REP as collateral. The lender would do this because the collateral is worth substantially more than the amount of the loan, so the lender would expect to come out okay if forced to repossess the collateral upon default.

I am going to use two different contracts to orchestrate these financial transactions:

The borrower will deploy a loan request contract that will handle the tokens-for-ether exchange that represents the start of the loan. This contract represents the borrower’s request to borrow ether on specified terms.
When a lender accepts the terms, a loan contract will be created. This loan contract holds the collateral tokens and enforces the terms of the loan until the borrower either pays off the loan or defaults by missing the payment deadline.

Why Two Contracts?

This design is a little more complicated than strictly necessary—it’s possible to handle this loan with a single contract that both initiates the loan and that handles its ultimate disposition. I’ve chosen to use the two-contract design for two reasons:

I wanted to illustrate a contract being deployed by another contract, which is a very powerful technique for decomposing smart contract processing.
I will reuse the Loan contract again in a later post. In that post, the decomposition will make the solution less complicated overall. I just wanted to introduce the concept when solving a simpler problem.

Making the Request

To handle the creation of a loan, a borrower will deploy a smart contract that can create a loan between the borrower and a lender. This LoanRequest contract is parameterized with the following values, which represent the terms of the loan:

The ERC20 token that the lender accepts as collateral.
The collateral amount, which is the unit amount of the token collateral.
The loan amount, which is the amount of wei the borrower is borrowing.
The payoff amount, which is the amount of wei that the borrower must pay to reclaim its tokens.
The loan duration is the amount of time the borrower has pay off its loan after receiving the loan.

Keeping track of these in the smart contract is straightforward:

contract LoanRequest {
    address public borrower = msg.sender;
    IERC20Token public token;
    uint256 public collateralAmount;
    uint256 public loanAmount;
    uint256 public payoffAmount;
    uint256 public loanDuration;

    function LoanRequest(
        IERC20Token _token,
        uint256 _collateralAmount,
        uint256 _loanAmount,
        uint256 _payoffAmount,
        uint256 _loanDuration
    )
        public
    {
        token = _token;
        collateralAmount = _collateralAmount;
        loanAmount = _loanAmount;
        payoffAmount = _payoffAmount;
        loanDuration = _loanDuration;
    }

    // ...
}

I’ve referenced an IERC20Token interface for working with the token. This was discussed in token sale post.

Accepting the Request

If someone is willing to lend ether given the terms of the LoanRequest contract, they can call lendEther. This function transfers the ether to the borrower and transfers the collateral tokens to a new Loan contract, which will enforce the terms of the loan. Below, I will show the implementation of the Loan contract, but for now I will just assume it exists:

Loan public loan;

event LoanRequestAccepted(address loan);

function lendEther() public payable {
    require(msg.value == loanAmount);
    loan = new Loan(
        msg.sender,
        borrower,
        token,
        collateralAmount,
        payoffAmount,
        loanDuration
    );
    require(token.transferFrom(borrower, loan, collateralAmount));
    borrower.transfer(loanAmount);
    emit LoanRequestAccepted(loan);
}

Explanation of the code above:

loan = new Loan(...) deploys a new Loan contract to enforce the terms of the loan.
token.transferFrom(...) transfers the token collateral from the borrower to the loan contract.
The loaned ether is sent to the borrower.
The emit LoanRequestAccepted(loan) logs the transaction, which can alert the borrower that his request was fulfilled and let them know the address of the loan contract.

At the conclusion of this function, the borrower holds the loaned ether, and the Loan contract holds the collateral tokens. Both parties can easily find the Loan contract thanks to the public loan state variable.

The code above is deceptively simple, and it hides a few very important details, which must be noted:

What if the borrower failed to approve the token transfer? If the transfer wasn’t approved, then the transferFrom will fail, and the whole transaction will be aborted, which means the borrower will not lose their ether.
If the transaction fails, and the borrower doesn’t get ether, what happens to its tokens? Nothing happens to them. The borrower only approved a transfer, and the transfer didn’t happen.
What happens if a lender never arrives and the borrower no longer wants to get the loan? The borrower is free to cancel the token transfer approval at any time before a lender arrives.

Enforcing the Loan Terms

The Loan contract enforces the terms of the loan. Its constructor just stores the parameters of the loan:

contract Loan {
    address public lender;
    address public borrower;
    IERC20Token public token;
    uint256 public collateralAmount;
    uint256 public payoffAmount;
    uint256 dueDate;

    function Loan(
        address _lender,
        address _borrower,
        IERC20Token _token,
        uint256 _collateralAmount,
        uint256 _payoffAmount,
        uint256
        loanDuration
    )
        public
    {
        lender = _lender;
        borrower = _borrower;
        token = _token;
        collateralAmount = _collateralAmount;
        payoffAmount = _payoffAmount;
        dueDate = now + loanDuration;
    }

    // ...
}

The Loan contract allows the borrower to reclaim its tokens by paying off the loan during the loan period. Should the borrower fail to pay off the loan before the due date, it allows the lender to repossess the forfeited tokens:

event LoanPaid();

function payLoan() public payable {
    require(now <= dueDate);
    require(msg.value == payoffAmount);

    require(token.transfer(borrower, collateralAmount));
    emit LoanPaid();
    selfdestruct(lender);
}

function repossess() public {
    require(now > dueDate);

    require(token.transfer(lender, collateralAmount));
    selfdestruct(lender);
}

Both routines above use selfdestruct to terminate the contract, which has beneficial gas consequences and transfers any ether to the lender. The LoanPaid event is there to signal the lender that their ether is available.

Summary

A smart contract can exploit the ERC20 standard to facilitate using tokens as loan collateral.
A smart contract can itself deploy smart contracts, which is a powerful technique for decomposing a problem.

The Complete Contracts

loan.sol

pragma solidity ^0.4.21;

import "./ierc20token.sol";

contract Loan {
    address public lender;
    address public borrower;
    IERC20Token public token;
    uint256 public collateralAmount;
    uint256 public payoffAmount;
    uint256 public dueDate;

    function Loan(
        address _lender,
        address _borrower,
        IERC20Token _token,
        uint256 _collateralAmount,
        uint256 _payoffAmount,
        uint256 loanDuration
    )
        public
    {
        lender = _lender;
        borrower = _borrower;
        token = _token;
        collateralAmount = _collateralAmount;
        payoffAmount = _payoffAmount;
        dueDate = now + loanDuration;
    }

    event LoanPaid();

    function payLoan() public payable {
        require(now <= dueDate);
        require(msg.value == payoffAmount);

        require(token.transfer(borrower, collateralAmount));
        emit LoanPaid();
        selfdestruct(lender);
    }

    function repossess() public {
        require(now > dueDate);

        require(token.transfer(lender, collateralAmount));
        selfdestruct(lender);
    }
}

collateral.sol

pragma solidity ^0.4.21;

import "./ierc20token.sol";
import "./loan.sol";

contract LoanRequest {
    address public borrower = msg.sender;
    IERC20Token public token;
    uint256 public collateralAmount;
    uint256 public loanAmount;
    uint256 public payoffAmount;
    uint256 public loanDuration;

    function LoanRequest(
        IERC20Token _token,
        uint256 _collateralAmount,
        uint256 _loanAmount,
        uint256 _payoffAmount,
        uint256 _loanDuration
    )
        public
    {
        token = _token;
        collateralAmount = _collateralAmount;
        loanAmount = _loanAmount;
        payoffAmount = _payoffAmount;
        loanDuration = _loanDuration;
    }

    Loan public loan;

    event LoanRequestAccepted(address loan);

    function lendEther() public payable {
        require(msg.value == loanAmount);
        loan = new Loan(
            msg.sender,
            borrower,
            token,
            collateralAmount,
            payoffAmount,
            loanDuration
        );
        require(token.transferFrom(borrower, loan, collateralAmount));
        borrower.transfer(loanAmount);
        emit LoanRequestAccepted(loan);
    }
}

Building Long-Lived Payment Channels

Fri, 02 Mar 2018 04:56:33 -0800

[EDIT 2018-12-10] Since publishing this post, We’ve added a related video explanation of payment channels.

[EDIT 2018-03-13] This post has been updated to use Solidity 0.4.21 event syntax.

In Writing a Simple Payment Channel, I introduced payment channels as a way to reduce the number of Ethereum transactions required for repeated payments between the same two parties. This post will improve upon that post’s SimplePaymentChannel contract to make it suitable for long-lived payment channels, such as might be used to pay an employee an hourly wage over the course of their career.

Introduction

The SimplePaymentChannel from Writing a Simple Payment Channel works well for payments made over a short period of time, but it has three limitations in the context of long-lived channels:

The sender must escrow all ether up front.
The recipient can make only a single withdrawal.
The timing of the channel closure is fixed when the channel is created.

I’ll make three changes to the SimplePaymentChannel contract to address these shortcomings:

Allow the sender to escrow a minimal amount of ether up front and add more funds as needed.
Allow the recipient to withdraw ether as needed before closing the channel.
Allow the sender to initiate channel closure so they can recover unspent funds in a reasonable timeframe.

Minimizing the Escrowed Funds

Payment channels hold escrowed funds to guarantee that a valid, signed payment message will be honored. Recipients will accept a message saying “I owe you a total of n ether,” if and only if the channel contract has escrowed n ether.

Because it’s trivial to check the channel’s current balance, it’s reasonable to allow multiple deposits to the channel:

function deposit() public payable { }

With this addition, the sender no longer needs to escrow all funds up front. However, each deposit requires an Ethereum transaction—and thus a transaction fee—so the sender must make a tradeoff between smaller, more frequent deposits and larger, less frequent ones.

Allowing Early Withdrawals

In the SimplePaymentChannel, the recipient can only make a single withdrawal, which closes the channel. A little bookkeeping enables multiple withdrawals without closing the channel. Recall that a withdrawal is done by presenting a signed IOU from the sender to the channel contract:

uint256 public withdrawn;  // How much the recipient has already withdrawn.

function withdraw(uint256 amountAuthorized, bytes signature) public {
    require(msg.sender == recipient);

    require(isValidSignature(amountAuthorized, signature));

    // Make sure there's something to withdraw (guards against underflow)
    require(amountAuthorized > withdrawn);
    uint256 amountToWithdraw = amountAuthorized - withdrawn;

    withdrawn += amountToWithdraw;
    msg.sender.transfer(amountToWithdraw);
}

A brief explanation of the above code:

The withdrawn state variable tracks how much ether the recipient has already withdrawn.
The recipient withdraws the total amount that’s been authorized so far minus the amount already withdrawn.

Finally, I need to make a small change to the close function to take into account the amount already withdrawn:

function close(uint256 amount, bytes signature) public {
    require(msg.sender == recipient);
    require(isValidSignature(amount, signature));

    // Guard against underflow.
    require(amount >= withdrawn);
    recipient.transfer(amount - withdrawn);

    selfdestruct(sender);
}

As in the previous section, this new ability introduces a tradeoff. The recipient can now access funds early by using the withdraw function, but each withdrawal requires an Ethereum transaction.

Allowing the Sender to Close the Channel

The SimplePaymentChannel introduced in Writing a Simple Payment Channel has an expiration time built in, and only the recipient can close the channel earlier than that. This is a problem for long-lived payment channels because it means the sender has no way to recover escrowed, unspent funds without the recipient’s cooperation.

To support long-lived payment channels, I’ll allow the sender to initiate channel closure. The recipient will then have some time to claim any funds they’re owed, after which the sender can access whatever’s left. With this new mechanism, there’s no need to have a fixed expiration at all.

// How much time the recipient has to respond when the sender initiates
// channel closure.
uint256 public closeDuration;

// When the payment channel closes. Initially effectively infinite.
uint256 public expiration = 2**256-1;

function LongLivedPaymentChannel(address _recipient, uint256 _closeDuration)
    public
    payable
{
    sender = msg.sender;
    recipient = _recipient;
    closeDuration = _closeDuration;
}

The preceding code sets up the state variables that are used for sender-initiated channel closure:

The closeDuration specifies, in seconds, how long the recipient will have to claim their funds after the sender initiates a close. It is set in the contract’s constructor.
The expiration is when the sender is allowed to close the channel. Initially, there’s effectively no expiration.

To initiate channel closure, the sender calls startSenderClose:

event StartSenderClose();

function startSenderClose() public {
    require(msg.sender == sender);
    emit StartSenderClose();
    expiration = now + closeDuration;
}

Here’s a brief explanation of the above code:

The expiration is set to closeDuration seconds in the future.
The recipient can watch for the StartSenderClose event so they know when it’s time to collect what they’re owed by closing the channel.

If the timeout is reached before the recipient closes the channel, the sender can close it and claim all remaining funds:

// If the timeout is reached without the recipient closing the channel, then
// the ether is released back to the sender.
function claimTimeout() public {
    require(now >= expiration);
    selfdestruct(sender);
}

Summary

For long-lived payment channels, it’s desirable to maximize availability of funds for both the sender and the recipient.
At any given time, the sender only needs to have enough funds escrowed to cover the amount already committed to the recipient.
At any given time, the recipient can withdraw up to the amount they’re owed.
Sender-initiated channel closure ensures that the sender can recover unpaid funds in a reasonable timeframe.

Full Source Code

longLivedPaymentChannel.sol

pragma solidity ^0.4.21;

contract LongLivedPaymentChannel {
    address public sender;      // The account sending payments.
    address public recipient;   // The account receiving the payments.
    uint256 public withdrawn;   // How much the recipient has already withdrawn.

    // How much time the recipient has to respond when the sender initiates
    // channel closure.
    uint256 public closeDuration;
    // When the payment channel closes. Initially effectively infinite.
    uint256 public expiration = 2**256-1;

    function LongLivedPaymentChannel(address _recipient, uint256 _closeDuration)
        public
        payable
    {
        sender = msg.sender;
        recipient = _recipient;
        closeDuration = _closeDuration;
    }

    function isValidSignature(uint256 amount, bytes signature)
        internal
        view
        returns (bool)
    {
        bytes32 message = prefixed(keccak256(this, amount));

        // Check that the signature is from the payment sender.
        return recoverSigner(message, signature) == sender;
    }

    // The recipient can close the channel at any time by presenting a signed
    // amount from the sender. The recipient will be sent that amount, and the
    // remainder will go back to the sender.
    function close(uint256 amount, bytes signature) public {
        require(msg.sender == recipient);
        require(isValidSignature(amount, signature));

        require(amount >= withdrawn);
        recipient.transfer(amount - withdrawn);

        selfdestruct(sender);
    }

    event StartSenderClose();

    function startSenderClose() public {
        require(msg.sender == sender);
        emit StartSenderClose();
        expiration = now + closeDuration;
    }

    // If the timeout is reached without the recipient closing the channel, then
    // the ether is released back to the sender.
    function claimTimeout() public {
        require(now >= expiration);
        selfdestruct(sender);
    }

    function deposit() public payable {
        require(msg.sender == sender);
    }

    function withdraw(uint256 amountAuthorized, bytes signature) public {
        require(msg.sender == recipient);

        require(isValidSignature(amountAuthorized, signature));

        // Make sure there's something to withdraw (guards against underflow)
        require(amountAuthorized > withdrawn);
        uint256 amountToWithdraw = amountAuthorized - withdrawn;

        withdrawn += amountToWithdraw;
        msg.sender.transfer(amountToWithdraw);
    }

    function splitSignature(bytes sig)
        internal
        pure
        returns (uint8, bytes32, bytes32)
    {
        require(sig.length == 65);

        bytes32 r;
        bytes32 s;
        uint8 v;

        assembly {
            // first 32 bytes, after the length prefix
            r := mload(add(sig, 32))
            // second 32 bytes
            s := mload(add(sig, 64))
            // final byte (first byte of the next 32 bytes)
            v := byte(0, mload(add(sig, 96)))
        }

        return (v, r, s);
    }

    function recoverSigner(bytes32 message, bytes sig)
        internal
        pure
        returns (address)
    {
        uint8 v;
        bytes32 r;
        bytes32 s;

        (v, r, s) = splitSignature(sig);

        return ecrecover(message, v, r, s);
    }

    // Builds a prefixed hash to mimic the behavior of eth_sign.
    function prefixed(bytes32 hash) internal pure returns (bytes32) {
        return keccak256("\x19Ethereum Signed Message:\n32", hash);
    }
}

Writing a Token Market Contract

Tue, 27 Feb 2018 06:13:43 -0700

[EDIT 2018-03-13] This post has been updated to use Solidity 0.4.21 event syntax.

This post will demonstrate how to write a smart contract that creates a token marketplace, where people can buy and sell ERC20 tokens. The smart contract acts like eBay by enabling sellers to list tokens for sale, and then brokering sales to buyers. This post relies on concepts introduced in our post on ERC20 tokens.

ERC20 token owners may want to sell some of their tokens. Of course, it would be natural to sell the tokens for ether and to conduct that sale via a smart contract. To help buyers find sellers, a single marketplace contract allows sellers to list tokens for sale—in a given quantity and for a given price—and then brokers sales when approached by buyers.

My marketplace contract will support three essential transactions:

Sellers can list a token for sale. The listing will include the quantity available and the price/unit.
Buyers can buy a token advertised in a given listing. The purchase quantity can be any amount up to the total available in the listing, and the price will be computed based on the listing’s price/unit.
Sellers can cancel an existing listing. Cancellation doesn’t affect any previously made sales, but it will prevent any subsequent sales.

(More) Floating Point Woes

Solidity’s lack of support for floating point numbers presents challenges when pricing tokens. It’s natural to give prices in wei per token unit, but sometimes integer values are insufficient. For instance, it is impossible to express 1.5 wei/unit or 0.0001 wei/unit with a simple integer value.

In this contract, I’m going to use a very simple technique—the contract will use a rational number expressed as ^numerator/_denominator, where both numerator and denominator are 256-bit unsigned integers. This will give plenty of precision to express any reasonable price.

Solidity `struct`s

Each listing is composed of five related values: the seller’s address, the token’s address, the quantity available (in units), and the wei/unit price given as a rational number.

Solidity supports a struct datatype for grouping data together:

struct Listing {
    address seller;
    IERC20Token token;
    uint256 unitsAvailable;

    // wei/unit price as a rational number
    uint256 priceNumerator;
    uint256 priceDenominator;
}

Solidity’s structs are very similar to C’s and Go’s as a means for treating related data as a unit.

Solidity Arrays

The marketplace contract must keep track of all the sellers’ listings, and it will do so in a dynamically-sized array. Solidity arrays are indexed from 0:

Listing[] listings;

Once a listing is added to the array, it will be referenced by its location (index) in the listings array. Future purchase and cancellation transactions will refer to the listing’s index.

Listing Tokens for Sale

Adding a listing to the marketplace contract is very straightforward: the contract will create a new listing struct with the appropriate values and append it to the end of the listings array.

In addition to storing the listing, the contract will log an event to announce the listing change to the outside world. The event will include the seller’s address and the listing’s index. The seller’s address is indexed to help the seller determine the indices of its listing(s).

event ListingChanged(address indexed seller, uint256 indexed index);

function list(
    IERC20Token token,
    uint256 units,
    uint256 numerator,
    uint256 denominator
) public {
    Listing memory listing = Listing({
        seller: msg.sender,
        token: token,
        unitsAvailable: units,
        priceNumerator: numerator,
        priceDenominator: denominator
    });
    listings.push(listing);
    emit ListingChanged(msg.sender, listings.length-1);
}

The code above introduces three new Solidity features:

Listing memory x declares a Listing struct that will reside in memory, which is temporary, rather than having it reside in persistent storage.
Listing(...) creates a new Listing struct with named fields set to the argument values.
listings.push(x) adds an element to the end of the listing array.

This contract will use the ERC20 token approve/transferFrom pattern for delegating token transfers. So, the buyer must approve the marketplace contract to transfer the listed tokens prior to any buyers attempting to buy those tokens. The marketplace contract never checks that the appropriate approve has happened—it simply assumes it has.

Buying Tokens

Making a purchase is also straightforward: the buyer indicates the index of the listing to be used, and the quantity to purchase. The buyer must also attach the appropriate amount of ether to the transaction:

function buy(uint256 index, uint256 units) public payable {
    Listing storage listing = listings[index];

    require(listing.unitsAvailable >= units);
    listing.unitsAvailable -= units;
    require(listing.token.transferFrom(listing.seller, msg.sender, units));

    uint256 cost = (units * listing.priceNumerator) /
        listing.priceDenominator;
    require(msg.value == cost);
    listing.seller.transfer(cost);

    emit ListingChanged(listing.seller, index);
}

The code does three things:

The code checks that the tokens requested are available, updates the amount available, and transfers the tokens to the buyer.
The code computes the total cost of the transaction, checks that the buyer attached that amount of ether, and transfers the ether to the seller.
The code logs an event, which can alert the seller or a DApp to the purchase.

The statement, Listing storage listing = listings[index], exploits the fact that storage variables are references to persistent storage. This means that any changes to the fields of listing will actually be to the underlying listings[index] struct.

Note that while the marketplace contract never explicitly checked that the seller had approved the transfer, the buy transaction will fail if the transferFrom does not succeed.

Cancelling a Listing

A seller may cancel a listing at any time. Cancellation will simply delete—zero out—the fields of the listing struct.

function cancel(uint256 index) public {
    require(listings[index].seller == msg.sender);
    delete(listings[index]);
    emit ListingChanged(msg.sender, index);
}

Summary

The ERC20 token standard enables a marketplace contract to broker sales of many different tokens on behalf of many different sellers.
Solidity supports structs for grouping related values.
Solidity supports dynamically-sized arrays for 0-indexed lists of values.
To compensate for the Ethereum Virtual Machine’s lack of support for floating point numbers, a contract can use rational numbers with explicit numerators and denominators.

The Complete Contracts

The complete code for the TokenMarket contract is below. I’ve used Solidity’s import directive to indicate that the code for IERC20Token interface will be loaded from a separate file.

ierc20token.sol

pragma solidity ^0.4.21;

interface IERC20Token {
    function totalSupply() external constant returns (uint);
    function balanceOf(address tokenlender) external constant returns (uint balance);
    function allowance(address tokenlender, address spender) external constant returns (uint remaining);
    function transfer(address to, uint tokens) external returns (bool success);
    function approve(address spender, uint tokens) external returns (bool success);
    function transferFrom(address from, address to, uint tokens) external returns (bool success);

    event Transfer(address indexed from, address indexed to, uint tokens);
    event Approval(address indexed tokenlender, address indexed spender, uint tokens);
}

tokenmarket.sol

pragma solidity ^0.4.21;

import "./ierc20token.sol";

contract TokenMarket {
    struct Listing {
        address seller;
        IERC20Token token;
        uint256 unitsAvailable;

        // wei/unit price as a rational number
        uint256 priceNumerator;
        uint256 priceDenominator;
    }

    Listing[] public listings;

    event ListingChanged(address indexed seller, uint256 indexed index);

    function list(
        IERC20Token token,
        uint256 units,
        uint256 numerator,
        uint256 denominator
    ) public {
        Listing memory listing = Listing({
            seller: msg.sender,
            token: token,
            unitsAvailable: units,
            priceNumerator: numerator,
            priceDenominator: denominator
        });

        listings.push(listing);
        emit ListingChanged(msg.sender, listings.length-1);
    }

    function cancel(uint256 index) public {
        require(listings[index].seller == msg.sender);
        delete(listings[index]);
        emit ListingChanged(msg.sender, index);
    }

    function buy(uint256 index, uint256 units) public payable {
        Listing storage listing = listings[index];

        require(listing.unitsAvailable >= units);
        listing.unitsAvailable -= units;
        require(listing.token.transferFrom(listing.seller, msg.sender, units));

        uint256 cost = (units * listing.priceNumerator) /
            listing.priceDenominator;
        require(msg.value == cost);
        listing.seller.transfer(cost);

        emit ListingChanged(listing.seller, index);
    }
}

Writing a Simple Payment Channel

Fri, 23 Feb 2018 10:28:42 -0800

[EDIT 2018-12-10] Since publishing this post, We’ve added a related video explanation of payment channels.

In this post, I’ll build a simple, but complete, implementation of a payment channel. Payment channels use cryptographic signatures to make repeated transfers of ether securely, instantaneously, and without transaction fees. This post will rely heavily on the concepts and code from our post “Signing and Verifying Messages in Ethereum”.

What is a Payment Channel?

Ethereum transactions provide a secure way to transfer funds, but each transaction needs to be included in a block and mined. This means transactions take some time and require payment to compensate the miners for their work. In particular, transaction fees make micropayments a difficult use case for Ethereum and other blockchains like it.

Payment channels allow participants to make repeated transfers of ether without using transactions. This means that the delays and fees associated with transactions can be avoided. In this post, we’re going to explore a simple unidirectional payment channel between two parties. Using it involves three steps:

The sender funds a smart contract with ether. This “opens” the payment channel.
The sender signs messages that specify how much of that ether is owed to the recipient. This step is repeated for each payment.
The recipient “closes” the payment channel, withdrawing their portion of the ether and sending the remainder back to the sender.

Importantly, only steps 1 and 3 require Ethereum transactions. Step 2 is accomplished off-chain through cryptographic signatures and some sort of communication between the two parties, such as email. This means only two transactions are required to support any number of transfers.

The recipient is guaranteed to receive their funds because the smart contract escrows the ether and honors a valid signed message. The smart contract also enforces a timeout, so the sender is guaranteed to eventually recover their funds even if the recipient refuses to close the channel.

It’s up to the participants in a payment channel to decide how long to keep it open. For a short-lived interaction, such as paying an internet cafe for each minute of network access, it makes sense to use a payment channel that lasts only an hour or so. For a longer relationship, such as paying an employee an hourly wage, a payment channel could last for months or years. ¹

Opening the Payment Channel

To open the payment channel, the sender deploys the smart contract, attaching the ether to be escrowed and specifying the intended recipient and a maximum duration for the channel to exist.

contract SimplePaymentChannel {
    address public sender;     // The account sending payments.
    address public recipient;  // The account receiving the payments.
    uint256 public expiration; // Timeout in case the recipient never closes.

    function SimplePaymentChannel(address _recipient, uint256 duration)
        public
        payable
    {
        sender = msg.sender;
        recipient = _recipient;
        expiration = now + duration;
    }

Making Payments

The sender makes payments by sending messages to the recipient. This step is performed entirely outside of the Ethereum network. Messages are cryptographically signed by the sender and then transmitted directly to the recipient.

Each message includes the following information:

The smart contract’s address, used to prevent cross-contract replay attacks.
The total amount of ether that is owed the recipient so far.

A payment channel is closed just once, at the end of a series of transfers. Because of this, only one of the messages sent will be redeemed. This is why each message specifies a cumulative total amount of ether owed, rather than the amount of the individual micropayment. The recipient will naturally choose to redeem the most recent message because that’s the one with the highest total.

Note that because the smart contract will only honor a single message, no per-message nonce is required. The address of the smart contract is still used to prevent a message intended for one payment channel from being used for a different channel.

Payment messages can be constructed and signed in any language that supports cryptographic hashing and signing operations. The following code is written in JavaScript and uses ethereumjs-abi:

function constructPaymentMessage(contractAddress, amount) {
  return ethereumjs.ABI.soliditySHA3(
    ["address", "uint256"],
    [contractAddress, amount],
  );
}

function signMessage(message, callback) {
  web3.personal.sign("0x" + message.toString("hex"), web3.eth.defaultAccount,
    callback);
}

// contractAddress is used to prevent cross-contract replay attacks.
// amount, in wei, specifies how much ether should be sent.
function signPayment(contractAddress, amount, callback) {
    var message = constructPaymentMessage(contractAddress, amount);
    signMessage(message, callback);
}

Verifying Payments

Unlike in my last signature example, messages in a payment channel aren’t redeemed right away. The recipient keeps track of the latest message and redeems it when it’s time to close the payment channel. This means it’s critical that the recipient perform their own verification of each message. Otherwise there is no guarantee that the recipient will be able to get paid in the end.

The recipient should verify each message using the following process:

Verify that the contract address in the message matches the payment channel.
Verify that the new total is the expected amount.
Verify that the new total does not exceed the amount of ether escrowed.
Verify that the signature is valid and comes from the payment channel sender.

The first three steps are straightforward. The final step can be performed a number of ways, but if it’s being done in JavaScript, I recommend the ethereumjs-util library. The following code borrows the constructMessage function from the signing code above:

// This mimics the prefixing behavior of the eth_sign JSON-RPC method.
function prefixed(hash) {
  return ethereumjs.ABI.soliditySHA3(
    ["string", "bytes32"],
    ["\x19Ethereum Signed Message:\n32", hash]
  );
}

function recoverSigner(message, signature) {
  var split = ethereumjs.Util.fromRpcSig(signature);
  var publicKey = ethereumjs.Util.ecrecover(message, split.v, split.r, split.s);
  var signer = ethereumjs.Util.pubToAddress(publicKey).toString("hex");
  return signer;
}

function isValidSignature(contractAddress, amount, signature, expectedSigner) {
  var message = prefixed(constructPaymentMessage(contractAddress, amount));
  var signer = recoverSigner(message, signature);
  return signer.toLowerCase() ==
    ethereumjs.Util.stripHexPrefix(expectedSigner).toLowerCase();
}

Closing the Payment Channel

When the recipient is ready to receive their funds, it’s time to close the payment channel by calling a close function on the smart contract. Closing the channel pays the recipient the ether they’re owed and destroys the contract, sending any remaining ether back to the sender. To close the channel, the recipient needs to share a message signed by the sender.

The smart contract must verify that the message contains a valid signature from the sender. The process for doing this verification is the same as the process the recipient uses. The Solidity functions isValidSignature and recoverSigner work just like their JavaScript counterparts in the previous section. The latter is borrowed from the ReceiverPays contract in “Signing and Verifying Messages in Ethereum”.

function isValidSignature(uint256 amount, bytes signature)
    internal
    view
    returns (bool)
{
    bytes32 message = prefixed(keccak256(this, amount));

    // Check that the signature is from the payment sender.
    return recoverSigner(message, signature) == sender;
}

// The recipient can close the channel at any time by presenting a signed
// amount from the sender. The recipient will be sent that amount, and the
// remainder will go back to the sender.
function close(uint256 amount, bytes signature) public {
    require(msg.sender == recipient);
    require(isValidSignature(amount, signature));

    recipient.transfer(amount);
    selfdestruct(sender);
}

The close function can only be called by the payment channel recipient, who will naturally pass the most recent payment message because that message carries the highest total owed. If the sender were allowed to call this function, they could provide a message with a lower amount and cheat the recipient out of what they’re owed.

The function verifies the signed message matches the given parameters. If everything checks out, the recipient is sent their portion of the ether, and the sender is sent the rest via a selfdestruct.

Channel Expiration

The recipient can close the payment channel at any time, but if they fail to do so, the sender needs a way to recover their escrowed funds. An expiration time was set at the time of contract deployment. Once that time is reached, the sender can call claimTimeout to recover their funds.

// If the timeout is reached without the recipient closing the channel, then
// the ether is released back to the sender.
function claimTimeout() public {
    require(now >= expiration);
    selfdestruct(sender);
}

After this function is called, the recipient can no longer receive any ether, so it’s important that the recipient close the channel before the expiration is reached. ²

Summary

Payment channels support safe, off-chain fund transfers while avoiding per-transfer Ethereum transaction fees.
Payments are cumulative, and only one is redeemed when closing the channel.
Transfers are guaranteed via escrowed funds and cryptographic signatures.
A timeout protects the sender’s funds from an uncooperative recipient.

Full Source Code

simplePaymentChannel.sol

pragma solidity ^0.4.20;

contract SimplePaymentChannel {
    address public sender;     // The account sending payments.
    address public recipient;  // The account receiving the payments.
    uint256 public expiration; // Timeout in case the recipient never closes.

    function SimplePaymentChannel(address _recipient, uint256 duration)
        public
        payable
    {
        sender = msg.sender;
        recipient = _recipient;
        expiration = now + duration;
    }

    function isValidSignature(uint256 amount, bytes signature)
        internal
        view
        returns (bool)
    {
        bytes32 message = prefixed(keccak256(this, amount));

        // Check that the signature is from the payment sender.
        return recoverSigner(message, signature) == sender;
    }

    // The recipient can close the channel at any time by presenting a signed
    // amount from the sender. The recipient will be sent that amount, and the
    // remainder will go back to the sender.
    function close(uint256 amount, bytes signature) public {
        require(msg.sender == recipient);
        require(isValidSignature(amount, signature));

        recipient.transfer(amount);
        selfdestruct(sender);
    }

    // The sender can extend the expiration at any time.
    function extend(uint256 newExpiration) public {
        require(msg.sender == sender);
        require(newExpiration > expiration);

        expiration = newExpiration;
    }

    // If the timeout is reached without the recipient closing the channel, then
    // the ether is released back to the sender.
    function claimTimeout() public {
        require(now >= expiration);
        selfdestruct(sender);
    }

    function splitSignature(bytes sig)
        internal
        pure
        returns (uint8, bytes32, bytes32)
    {
        require(sig.length == 65);

        bytes32 r;
        bytes32 s;
        uint8 v;

        assembly {
            // first 32 bytes, after the length prefix
            r := mload(add(sig, 32))
            // second 32 bytes
            s := mload(add(sig, 64))
            // final byte (first byte of the next 32 bytes)
            v := byte(0, mload(add(sig, 96)))
        }

        return (v, r, s);
    }

    function recoverSigner(bytes32 message, bytes sig)
        internal
        pure
        returns (address)
    {
        uint8 v;
        bytes32 r;
        bytes32 s;

        (v, r, s) = splitSignature(sig);

        return ecrecover(message, v, r, s);
    }

    // Builds a prefixed hash to mimic the behavior of eth_sign.
    function prefixed(bytes32 hash) internal pure returns (bytes32) {
        return keccak256("\x19Ethereum Signed Message:\n32", hash);
    }
}

In the simple payment channel I introduce in this post, a long-lived channel is undesirable because all funds must be escrowed up front, and neither party can access the funds until the channel is closed. I will show how to overcome these limitations in a future post. ↩
There’s no reason not to allow the sender to extend expiration. I’ve included a function in the full source code that does this. ↩

Writing an Estate Planning Contract

Tue, 20 Feb 2018 13:05:14 -0800

[EDIT 2018-03-13] This post has been updated to use Solidity 0.4.21 event syntax.

This post will demonstrate how to write a smart contract that transfers your ether to a beneficiary after you die. It assumes that you have read our previous post on dealing with time on the blockchain.

Suppose that you want to bequeath your ether to a beneficiary after you die. How would you transfer access to your ether in a trustless fashion? The answer, of course, is with a smart contract! The smart contract will be responsible for many operations:

The contract will hold ether on your behalf while you are alive, allowing you to make deposits and withdrawals freely.
The contract will include a mechanism for determining (with some confidence) that you are dead.
The contract will allow your beneficiary access to the ether after you are deemed dead.

Contract Inheritance

I am going to use this opportunity to introduce a common Solidity programming practice called “inheritance”, which enables one contract to inherit functions, modifiers and variables from another contract. This is very similar to inheritance in many object-oriented languages.

There are many common patterns in Solidity programs that are typically expressed via inheritance. Two common patterns are contracts having owners (with special privileges), and contracts allowing their owners to kill the contract:

contract Ownable {
    address owner = msg.sender;
    modifier onlyOwner {
        require(msg.sender == owner);
        _;
    }
}

contract Mortal is Ownable {
    function kill() public onlyOwner {
        selfdestruct(msg.sender);
    }
}

contract Estate is Mortal {
    // ...
}

The code above uses inheritance to provide my Estate contract with the variables, modifiers, and functions of the Ownable and Mortal contracts (i.e., owner, onlyOwner, and kill.)

Beneficiary

In addition to having an owner account, the Estate contract has a beneficiary account. The beneficiary stands to inherit the contract from the owner after the owner has died. Just as some contract functionality is restricted to the owner, some will be restricted to the beneficiary:

contract Estate is Mortal {

    address beneficiary;
    modifier onlyBeneficiary {
        require(msg.sender == beneficiary);
        _;
    }

    // ...
}

Am I Dead Or Not?

The interesting challenge this contract must address is how to determine if its owner has died. This is difficult because death happens off the blockchain, so the contract needs a way to learn of an off-chain event. Rather than solving that problem, I am going to employ a proxy test for death—the lack of a “heartbeat” during a given period of time.

Specifically, the design will be one where the beneficiary asserts that the owner has died, and then the owner must provide a “heartbeat” transaction within a waiting period. If the owner makes the heartbeat before the period expires, then he hasn’t died. If not, then the contract considers him dead, and it will transfer ownership to the beneficiary upon request.

To monitor the state of the assertions of death and the period of the challenge, the contract will maintain two time values:

uint256 waitingPeriodLength;    // Duration of challenge period
uint256 endOfWaitingPeriod;     // End of challenge period

The waitingPeriodLength period is the length of time after the beneficiary asserts death that must be waited for the owner to possibly prove they are alive. endOfWaitingPeriod is the time of the end of that waiting period.

To keep things simple, I will use a sentinel value for endOfWaitingPeriod that is so far out in the future as to be unimaginable. This will be the value when the beneficiary has not asserted that the owner is dead.

I will define a heartbeat modifier that will reset the endOfWaitingPeriod value to that end-of-ages time. The modifier will be used on every routine where the owner proves he is alive:

modifier heartbeat {
    _;
    endOfWaitingPeriod = 10 ** 18;  // approximate age of the universe
}

The heartbeat modifier is a little unusual because it will add the code to the end of the function it modifies. This will allow heartbeat to be used later in the claimInheritance function that tests the (current) value of endOfWaitingPeriod upon entry.

Now that we have all the scaffolding in place, I can show the simple constructor:

function Estate(address _beneficiary, uint256 _waitingPeriodLength)
    public
    heartbeat
{
    beneficiary = _beneficiary;
    waitingPeriodLength = _waitingPeriodLength;
}

The constructor directly sets the beneficiary and waitingPeriodLength variables as well as setting endOfWaitingPeriod via the heartbeat modifier.

Asserting Death

The beneficiary can assert that the owner has died with the assertDeath function:

event Challenge(uint256 endOfWaitingPeriod);

function assertDeath() public onlyBeneficiary {
    endOfWaitingPeriod = now + waitingPeriodLength;
    emit Challenge(now);
}

assertDeath sets endOfWaitingPeriod out in the future by waitingPeriodLength seconds from now. If the owner doesn’t interact with the contract to reset endOfWaitingPeriod (via heartbeat), then the beneficiary can claim ownership.

As a convenience to the (possibly not dead) owner, assertDeath logs an event that the owner can monitor.

Claiming Ownership

The beneficiary can claim ownership and set his beneficiary with claimInheritance:

function claimInheritance(address newBeneficiary)
    public
    onlyBeneficiary
    heartbeat
{
    require(now >= endOfWaitingPeriod); // waiting period expired

    owner = beneficiary;
    beneficiary = newBeneficiary;
}

One subtlety to claimInheritance is its use the heartbeat modifier. That is needed to reset the endOfWaitingPeriod to its sentinel value for the new owner.

In deciding what the contract should do after the owner died, I had a design choice. I chose to have the smart contract’s ownership change, but I could just as easily have had the contract self-destruct and send the ether to the beneficiary. I chose changing ownership because it seemed elegant to me because the new owner may face the same estate planning challenge as the previous owner.

Holding Ether Balances

Of course, it’s important for the contract’s owner to be able to access his ether while alive. The contract has a simple mechanism for the owner to deposit and withdraw funds.

function deposit() public payable onlyOwner heartbeat {
    // nothing else to do
}

function withdraw(uint256 amount) public onlyOwner heartbeat {
    msg.sender.transfer(amount);
}

The deposit and withdraw routines do a few subtle things:

Both routines capture much of their functionality in the onlyOwner and heartbeat modifiers.
Because both routines are limited to the owner, it makes sense for both to serve as heartbeats (and update endOfWaitingPeriod to its sentinel value). In fact, a deposit of zero ether acts as a simple, low-gas heartbeat for the owner.
withdraw does not check whether the contract has sufficient ether because that check will be done by the transfer function.

The Complete Contract

estate.sol

pragma solidity ^0.4.21;

contract Ownable {
    address owner = msg.sender;
    modifier onlyOwner {
        require(msg.sender == owner);
        _;
    }
}

contract Mortal is Ownable {
    function kill() public onlyOwner {
        selfdestruct(msg.sender);
    }
}

contract Estate is Mortal {
    address beneficiary;
    modifier onlyBeneficiary {
        require(msg.sender == beneficiary);
        _;
    }

    uint256 waitingPeriodLength;
    uint256 endOfWaitingPeriod;
    modifier heartbeat {
        _;
        endOfWaitingPeriod = 10 ** 18;  // approximate age of universe
    }

    function Estate(address _beneficiary, uint256 _waitingPeriodLength)
        public
        heartbeat
    {
        beneficiary = _beneficiary;
        waitingPeriodLength = _waitingPeriodLength;
    }

    function deposit() public payable onlyOwner heartbeat { }

    function withdraw(uint256 amount) public onlyOwner heartbeat {
        msg.sender.transfer(amount);
    }

    event Challenge(uint256 timestamp);

    function assertDeath() public onlyBeneficiary {
        endOfWaitingPeriod = now + waitingPeriodLength;
        emit Challenge(now);
    }

    function claimInheritance(address newBeneficiary)
        public
        onlyBeneficiary
        heartbeat
    {
        require(now >= endOfWaitingPeriod);

        owner = msg.sender;
        beneficiary = newBeneficiary;
    }
}

Signing and Verifying Messages in Ethereum

Sat, 17 Feb 2018 06:47:55 -0800

Cryptographic signatures are a powerful primitive in Ethereum. Signatures are used to authorize transactions, but they’re a more general tool that’s available to smart contracts. Signatures can be used to prove to a smart contract that a certain account approved a certain message.

In this post, I’ll build a simple smart contract that lets me transmit ether in an unusual way. Instead of calling a function myself to initiate a payment, I’ll let the receiver of the payment do that—and therefore pay the transaction fee! Only authorized payments will be allowed, thanks to cryptographic signatures that I will make and send off-chain (e.g. via email).

Paying someone with the ReceiverPays contract works a lot like writing a check. The person receiving the payment gets to take money directly out of my bank account, but only if they have a valid check bearing my signature.

Overview

The ReceiverPays contract holds ether on behalf of its owner and allows that ether to be withdrawn when authorized by a cryptographic signature:

The owner deploys ReceiverPays, attaching enough ether to cover the payments that will be made.
The owner authorizes a payment by cryptographically signing a message with their private key.
The owner sends the signed message to the designated recipient. The message does not need to be kept secret, and the mechanism for sending it doesn’t matter. It can be sent via email, instant message, or even a public forum.
The recipient claims their payment by presenting the signed message to the smart contract. The smart contract verifies its authenticity and then releases the funds.

Creating the Signature

Signing a message with a private key does not require interacting with the Ethereum network. It can be done completely offline, and every major programming language has the necessary cryptographic libraries to do it. The signature algorithm Ethereum has built-in support for is the Elliptic Curve Digital Signature Algorithm (EDCSA)

For this post, I’ll focus on signing messages in the web browser using web3.js and MetaMask.

There are still a number of ways to sign messages using web3.js, and, unfortunately, different methods sign data in incompatible ways. Members of the community are actively working to standardize on a new way to sign messages (EIP-712) that has a number of other security benefits. For now, though, my advice is to stick with the most standard format of signing, as specified by the eth_sign JSON-RPC method:

The sign method calculates an Ethereum specific signature with: sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))).

By adding a prefix to the message makes the calculated signature recognisable as an Ethereum specific signature. This prevents misuse where a malicious DApp can sign arbitrary data (e.g. transaction) and use the signature to impersonate the victim.

At least in MetaMask, this algorithm is followed best by the web3.js function web3.personal.sign, so I recommend using that: ¹

// Hashing first makes a few things easier.
var hash = web3.sha3("message to sign");
web3.personal.sign(hash, web3.eth.defaultAccount, function () { ... });

Recall that the prefix includes the length of the message. Hashing first means the message will always be 32 bytes long, which means the prefix is always the same. This makes life easier, particularly on the Solidity side, as I’ll demonstrate later in this post.

What to Sign

For a signature to represent authorization to take some action, it’s important that the message specify exactly what’s being authorized. For a contract that fulfills payments, the signed message must include the address of the recipient and the amount that is to be transferred. In addition, the message should include data that protects against replay attacks.

Avoiding Replay Attacks

A replay attack is when a signature is used again (“replayed”) to claim authorization for a second action. For our example, it would be a serious security flaw if the recipient of a payment could submit the same signature again to receive a second payment. Just as in Ethereum transactions themselves, messages typically include a nonce to protect against replay attacks. The smart contract checks that no nonce is reused:

mapping(uint256 => bool) usedNonces;

function claimPayment(uint256 amount, uint256 nonce, bytes sig) public {
    require(!usedNonces[nonce]);
    usedNonces[nonce] = true;

    // ...
}

There’s another kind of replay attack that we need to protect against. Suppose I deploy the ReceiverPays smart contract, make some payments, and then destroy the contract. Later, I would like to make more payments, so I decide to deploy the RecipientPays smart contract again. The new deployed instance of the contract doesn’t know about the used nonces from the previous deployment, so it will happily pay in response to any of the old signatures again.

A simple way to protect against this type of replay attack is to make sure the message includes the contract’s address. The new contract will reject all signatures that reference the wrong (old) address.

Packing Arguments

Now that I’ve identified what information to include in the signed message, I’m ready to put the message together, hash it, and sign it. Solidity’s keccak256/sha3 function hashes multiple arguments by first concatenating them in a tightly packed form. For the hash generated on the client to match the one generated in the smart contract, the arguments must be concatenated in the same way.

The ethereumjs-abi library ² provides a function called soliditySHA3 that mimics the behavior of Solidity’s keccak256 function. It accepts an array of values as well as an array of their Solidity types so it can serialize the values accordingly.

Putting it all together, here’s a JavaScript function that creates the proper signature for the ReceiverPays example: ³

// recipient is the address that should be paid.
// amount, in wei, specifies how much ether should be sent.
// nonce can be any unique number, used to prevent replay attacks.
// contractAddress is used to prevent cross-contract replay attacks.
function signPayment(recipient, amount, nonce, contractAddress, callback) {
  var hash = "0x" + ethereumjs.ABI.soliditySHA3(
    ["address", "uint256", "uint256", "address"],
    [recipient, amount, nonce, contractAddress]
  ).toString("hex");

  web3.personal.sign(hash, web3.eth.defaultAccount, callback);
}

Recovering the Message Signer in Solidity

In general, ECDSA signatures consist of two parameters, r and s. Signatures in Ethereum include a third parameter, v, which provides additional information that can be used to recover which account’s private key was used to sign the message. This same mechanism is how Ethereum determines which account sent a given transaction.

Solidity provides a built-in function ecrecover that accepts a message along with the r, s, and v parameters and returns the address that was used to sign the message.

Extracting the Signature Parameters

Signatures produced by web3.js are the concatenation of r, s, and v, so a necessary first step is splitting those parameters back out. This process can be done on the client, but I find it more convenient to do it inside the smart contract. This means only one signature parameter needs to be sent rather than three.

Unfortunately, splitting apart a bytes array into component parts is a little messy. I’m making use of inline assembly to do the job:

function splitSignature(bytes sig)
    internal
    pure
    returns (uint8, bytes32, bytes32)
{
    require(sig.length == 65);

    bytes32 r;
    bytes32 s;
    uint8 v;

    assembly {
        // first 32 bytes, after the length prefix
        r := mload(add(sig, 32))
        // second 32 bytes
        s := mload(add(sig, 64))
        // final byte (first byte of the next 32 bytes)
        v := byte(0, mload(add(sig, 96)))
    }

    return (v, r, s);
}

Here’s a brief explanation of that code:

Dynamically-sized arrays (including bytes) are represented in memory by a 32-byte length followed by the actual data. The code here starts reading data at byte 32 to skip past that length. The require at the top of the function ensures the signature is the correct length.
r and s are 32 bytes each and together make up the first 64 bytes of the signature.
v is the 65th byte, which can be found at byte offset 96 (32 bytes for the length, 64 bytes for r and s). The mload opcode loads 32 bytes at a time, so the function then needs to extract just the first byte of the word that was read. This is what byte(0, ...) does.

Computing the Message Hash

In addition to the r, s, and v parameters from the signature, recovering the message signer requires knowledge of the message that was signed. The message hash needs to be recomputed from the sent parameters along with the known prefix.

It may seem tempting at first to just have the caller pass in the message that was signed, but that would only prove that some message was signed by the owner. The smart contract needs to know exactly what parameters were signed, and so it must recreate the message from the parameters and use that for signature verification:

// Builds a prefixed hash to mimic the behavior of eth_sign.
function prefixed(bytes32 hash) internal pure returns (bytes32) {
    return keccak256("\x19Ethereum Signed Message:\n32", hash);
}

function claimPayment(uint256 amount, uint256 nonce, bytes sig) public {
    require(!usedNonces[nonce]);
    usedNonces[nonce] = true;

    // This recreates the message that was signed on the client.
    bytes32 message = prefixed(keccak256(msg.sender, amount, nonce, this));

    require(recoverSigner(message, sig) == owner);

    msg.sender.transfer(amount);
}

Finally, the implementation of recoverSigner is straightforward:

function recoverSigner(bytes32 message, bytes sig)
        internal
        pure
        returns (address)
{
    uint8 v;
    bytes32 r;
    bytes32 s;

    (v, r, s) = splitSignature(sig);

    return ecrecover(message, v, r, s);
}

Summary

Signed messages provide a way to authenticate a message to a smart contract.
Signed messages may need a nonce to protect against replay attacks.
Signed messages may need to include the contracts’s address to protect against replay attacks.
Until a better signature standard is adopted, I recommend following the behavior of the eth_sign JSON-RPC method.

Full Source Code

receiverPays.sol

pragma solidity ^0.4.20;

contract ReceiverPays {
    address owner = msg.sender;

    mapping(uint256 => bool) usedNonces;

    // Funds are sent at deployment time.
    function ReceiverPays() public payable { }


    function claimPayment(uint256 amount, uint256 nonce, bytes sig) public {
        require(!usedNonces[nonce]);
        usedNonces[nonce] = true;

        // This recreates the message that was signed on the client.
        bytes32 message = prefixed(keccak256(msg.sender, amount, nonce, this));

        require(recoverSigner(message, sig) == owner);

        msg.sender.transfer(amount);
    }

    // Destroy contract and reclaim leftover funds.
    function kill() public {
        require(msg.sender == owner);
        selfdestruct(msg.sender);
    }


    // Signature methods

    function splitSignature(bytes sig)
        internal
        pure
        returns (uint8, bytes32, bytes32)
    {
        require(sig.length == 65);

        bytes32 r;
        bytes32 s;
        uint8 v;

        assembly {
            // first 32 bytes, after the length prefix
            r := mload(add(sig, 32))
            // second 32 bytes
            s := mload(add(sig, 64))
            // final byte (first byte of the next 32 bytes)
            v := byte(0, mload(add(sig, 96)))
        }

        return (v, r, s);
    }

    function recoverSigner(bytes32 message, bytes sig)
        internal
        pure
        returns (address)
    {
        uint8 v;
        bytes32 r;
        bytes32 s;

        (v, r, s) = splitSignature(sig);

        return ecrecover(message, v, r, s);
    }

    // Builds a prefixed hash to mimic the behavior of eth_sign.
    function prefixed(bytes32 hash) internal pure returns (bytes32) {
        return keccak256("\x19Ethereum Signed Message:\n32", hash);
    }
}

MetaMask’s UI shows the user the message they’re signing, but since here the message is a hash, it will never be meaningful to the user. This is one of the issues that EIP-712 is intended to solve. ↩
You can find browser builds of ethereumjs-abi in the ethereumjs/browser-builds repository. ↩
Web3.js 1.0.0-beta includes a similar function called soliditySha3, but at the time of this writing, that version is still unreleased and therefore lacking in compatibility with other tools, including MetaMask. ↩

Writing A Robust Dividend Token Contract

Tue, 13 Feb 2018 13:29:03 -0800

[EDIT 2018-03-13] This post has been updated to use Solidity 0.4.21 event syntax.

The simple dividend token post made one big simplifying assumption—it assumed that there were few token units compared to the number of wei in a typical dividend deposit. This assumption meant that the contract could ignore the fact that integer divisions could result in some wei being forever wasted. This post will demonstrate how to write an ERC20-compliant token contract that is robust to that problem.

Floating-point Scaling

Ether values are typically expressed in wei, which means they are really huge numbers. (Recall that there are 10¹⁸ wei/ether.) ERC20 contracts typically use similarly scaled representations of token amounts, with 10^decimals units/token. Operating on scaled values represents a challenge when doing division because all Solidity divisions are integer divisions. (Recall that the previous simple dividend token restricted decimals to zero to avoid significant problems due to integer division.)

If a contract needs to calculate the wei/unit of a particular dividend, it would be natural to just divide the dividend (in wei) by the total supply of tokens (in units). Unfortunately, this could create a problem if the division yielded a large remainder that would effectively be lost. For instance, suppose a dividend of 1 ether were to be divided amongst 1,000,000 tokens with decimals=18. Doing this directly would imply dividing 10¹⁸ wei by 10²⁴ token units. This integer division would result in 0 wei/unit. The division would yield a remainder of 1 ether that would be lost if precautions aren’t taken.

To avoid this lost remainder problem, my robust dividend contract will do two things:

The contract will scale the wei values up sufficiently to make division problems much less significant.
The contract will keep track of any remainders and add them back into subsequent computations whenever possible.

Scaling Values

Fortunately, 256-bit integers provide lots of room for scaling up wei values. 2²⁵⁶ is approximately 10⁷⁷. 18 of those 77 zeros are used to represent one ether, so we still have 59 zeros of scaling left.

To keep this contract simple, I will hardwire a scaling of 10⁸. I chose 10⁸ because there are 10⁶ tokens for a total of 10²⁴ token units. With a scaling factor of 10⁸, dividing the total supply of token units into 0.01 ether will result in 1 scaled wei/unit to be distributed.

uint256 public scaling = uint256(10) ** 8;

This contract will simply use scaled values in place of the unscaled values in the simple dividend token. So, I’ve changed variable names to include the scaled prefix as appropriate:

uint256 public scaledDividendPerToken;

mapping(address => uint256) public scaledDividendBalanceOf;

mapping(address => uint256) public scaledDividendCreditedPerToken;

Other than being scaled, those values are identical to the similarly-named values in the simple dividend token contract.

Deposit and Withdrawal

Deposits and withdrawals need to convert to and from scaled values. They also need to handle the fact that integer division can leave a remainder—the contract should track those remainders so that they are not lost.

Withdrawal simply needs to update the amount of dividend owed, retain any remainder from the scaling division, and then transfer the amount:

function withdraw() public {
    update(msg.sender);
    uint256 amount = scaledDividendBalanceOf[msg.sender] / scaling;
    scaledDividendBalanceOf[msg.sender] %= scaling;  // retain the remainder
    msg.sender.transfer(amount);
}

The deposit function computes the scaled wei/unit to distribute and add it to the global scaledDividendPerToken. That computation must take into account any previously undistributed (scaled) wei, and it must update that quantity as well.

uint256 public scaledRemainder = 0;

function deposit() public payable {
    // scale the deposit and add the previous remainder
    uint256 available = (msg.value * scaling) + scaledRemainder;

    scaledDividendPerToken += available / totalSupply;

    // compute the new remainder
    scaledRemainder = available % totalSupply;
}

Summary

Floating-point division requires careful planning to avoid too much loss of precision.
Floating-point division requires careful attention to any remainders that may get lost.

The Whole Contract

robustDividend.sol

pragma solidity ^0.4.21;

contract RobustDividendToken {

    string public name = "Robust Dividend Token";
    string public symbol = "DIV";
    uint8 public decimals = 18;

    uint256 public totalSupply = 1000000 * (uint256(10) ** decimals);

    mapping(address => uint256) public balanceOf;

    function RobustDividendToken() public {
        // Initially assign all tokens to the contract's creator.
        balanceOf[msg.sender] = totalSupply;
        emit Transfer(address(0), msg.sender, totalSupply);
    }

    uint256 public scaling = uint256(10) ** 8;

    mapping(address => uint256) public scaledDividendBalanceOf;

    uint256 public scaledDividendPerToken;

    mapping(address => uint256) public scaledDividendCreditedTo;

    function update(address account) internal {
        uint256 owed =
            scaledDividendPerToken - scaledDividendCreditedTo[account];
        scaledDividendBalanceOf[account] += balanceOf[account] * owed;
        scaledDividendCreditedTo[account] = scaledDividendPerToken;
    }

    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);

    mapping(address => mapping(address => uint256)) public allowance;

    function transfer(address to, uint256 value) public returns (bool success) {
        require(balanceOf[msg.sender] >= value);

        update(msg.sender);
        update(to);

        balanceOf[msg.sender] -= value;
        balanceOf[to] += value;

        emit Transfer(msg.sender, to, value);
        return true;
    }

    function transferFrom(address from, address to, uint256 value)
        public
        returns (bool success)
    {
        require(value <= balanceOf[from]);
        require(value <= allowance[from][msg.sender]);

        update(from);
        update(to);

        balanceOf[from] -= value;
        balanceOf[to] += value;
        allowance[from][msg.sender] -= value;
        emit Transfer(from, to, value);
        return true;
    }

    uint256 public scaledRemainder = 0;

    function deposit() public payable {
        // scale the deposit and add the previous remainder
        uint256 available = (msg.value * scaling) + scaledRemainder;

        scaledDividendPerToken += available / totalSupply;

        // compute the new remainder
        scaledRemainder = available % totalSupply;
    }

    function withdraw() public {
        update(msg.sender);
        uint256 amount = scaledDividendBalanceOf[msg.sender] / scaling;
        scaledDividendBalanceOf[msg.sender] %= scaling;  // retain the remainder
        msg.sender.transfer(amount);
    }

    function approve(address spender, uint256 value)
        public
        returns (bool success)
    {
        allowance[msg.sender][spender] = value;
        emit Approval(msg.sender, spender, value);
        return true;
    }

}

End to End: Initial Coin Offering

Fri, 09 Feb 2018 12:10:47 -0800

In this post, I’ll walk through the end-to-end process of deploying a new ERC20-compatible token, a token sale contract to sell it, and a website to help users buy the token.

This post will tie together many concepts from earlier posts. I will link to those posts throughout. If you would like to see the running ICO example, you can check it out here.

Architecture

An initial coin offering (ICO) can be structured in a number of ways. Here, I’ll focus on the common scenario of selling a limited supply of an Ethereum-based token via a website for a fixed price.

This kind of ICO can be decomposed into three components:

An ERC20-compatible token that is to be sold.
A token sale contract that will exchanges tokens for ether.
A front-end website that displays the progress of the ICO and allows users to make purchases.

Deploying the Smart Contracts

For the ERC20-compatible token, I’m using the SimpleERC20Token contract from our post “Writing an ERC20 Token Contract”. To sell the token, I’m using the TokenSale contract from our post “Writing a Token Sale Contract”.

As described in our post “Testing and Deploying Smart Contracts with Remix”, I used Remix and MetaMask to take the following steps on the Ropsten test network:

Deploy the SimpleERC20Token contract. At this point, my account owns the total supply of tokens.
Deploy the TokenSale contract, supplying the constructor arguments "0x<address of SimpleERCToken>", 100000000000000. The latter is the price of each token: 0.0001 ether expressed in wei.
Transfer tokens from my account to TokenSale by calling transfer with the arguments "0x<address of TokenSale>", 1000000000000000000000000. The latter is the total supply of tokens: 1,000,000 multiplied by 10¹⁸ because the token uses 18 decimal places.

Publishing the Contract Source Code

As described in our post “Verifying Contract Source Code”, it’s important to publish verifiable source code for smart contracts. Following this process, I published source code for both smart contracts on Etherscan:

Building the User Interface

With the two contracts deployed and the source code published, anyone can buy tokens by using a tool like MyEtherWallet or by writing code. This is, however, a very inconvenient way to interact with a smart contract. In our post “Building Decentralized Apps With Ethereum and JavaScript”, I described how web-based UI can help users work with smart contracts. If you haven’t already read that post, I strongly suggest doing so now, as the rest of this post will lean heavily on that material.

Buying Tokens

The most important piece of functionality in an ICO interface is the ability to buy tokens. In the UI I designed, this consists of a text box where the user can enter a number of tokens to buy and a button labeled “Buy Tokens.” When the button is pressed, the following code is executed:

$('#buyForm').submit(function (e) {
  // Prevent the browser from POSTing the form.
  e.preventDefault();

  var numberOfTokens = web3.toBigNumber($('#number').val());
  saleContract.buyTokens.sendTransaction(numberOfTokens, {
    value: numberOfTokens.mul(price),
  }, function () {
    // Nothing to do here. If the transaction is successful, it will trigger
    // events that we're already monitoring.
  });
});

There are two things to note in the above code:

As a best practice, I try to always represent numbers as BigNumbers. This is how values from the blockchain are returned, and it protects against JavaScript’s limitations around number values.
The result of sending the transaction is ignored. As I’ll explain later in this post, UI updates are triggered by events, and a successful transaction will log such an event. A failed transaction requires no UI update.

Displaying Information

In addition to purchasing tokens, a good ICO interface will also show information about the state of the token sale as well as the user’s token balance. My example interface displays the following information:

The user’s current balance. This is provided by the token contract’s balanceOf function, passing the user’s account as the sole argument.
The number of tokens remaining to be sold. This is again provided by the token contract’s balanceOf function, this time passing in the sale contract’s address.
The number of tokens that have already been sold. This is provided by the sale contract’s tokensSold function.

This function collects all the required data:

function loadData(blockNumber) {
  log("Loading data from contracts...")

  var balance, sold, remaining;

  // Callback that waits for all three pieces of data before proceeding
  function updateWhenDone() {
    if (balance !== undefined && sold !== undefined &&
        remaining !== undefined) {
      log("Updating UI.");
      updateUI(balance.div(10**decimals), sold, remaining.div(10**decimals));
    }
  }

  // Fetch in parallel
  // User's balance
  tokenContract.balanceOf.call(web3.eth.defaultAccount, {}, blockNumber,
    function (err, _balance) {
      if (err) return error(err);
      balance = _balance;
      updateWhenDone();
    });
  // Tokens sold so far
  saleContract.tokensSold.call({}, blockNumber,
    function (err, _sold) {
      if (err) return error(err);
      sold = _sold;
      updateWhenDone();
    });
  // Remaining inventory (sale contract's balance)
  tokenContract.balanceOf.call(saleAddress, {}, blockNumber,
    function (err, _remaining) {
      if (err) return error(err);
      remaining = _remaining;
      updateWhenDone();
    });
}

Here’s a brief explanation of the above code:

Each call specifies a block number. By default, a call uses state from the latest block. When fetching multiple pieces of data, specifying a particular block number ensures that all the data comes from the same point in time.
The calls to the blockchain are issued in parallel. All of them invoke the same callback, which waits until all of the data has been collected before it calls updateUI. Just as with the previous point, updating the UI all at once helps to make sure users never see mismatched data from multiple blocks.
Because token amounts are scaled according to the number of decimals a token uses, it’s important to divide by 10^decimals before displaying a number to a user.

Watching for Changes

The information displayed by the ICO can change for a number of reasons:

Transferring tokens into the token sale contract increases the number of available tokens for sale.
Someone buying tokens increases the number of tokens sold so far and decreases the number of tokens remaining for sale.
Unrelated transfers in and out of the user’s account change the account’s token balance.

The UI is kept up to date by watching events, as described in our post “Logging and Watching Solidity Events”.

function initialize() {
  web3.eth.getBlockNumber(function (err, lastSeenBlock) {
    // Load data for the initial block
    loadData(lastSeenBlock);

    // Handler for events that necessitate a UI update
    function changeHandler(err, data) {
      if (err) return error(err);

      // Only if we haven't already fetched data for this block
      if (data.blockNumber > lastSeenBlock) {
        lastSeenBlock = data.blockNumber;
        loadData(lastSeenBlock);
      }
    }

    // The Sold event tells us when the number of sold tokens changes.
    saleContract.Sold(changeHandler);

    // We display the user's balance as well as the sale contract's
    // balance, so we need to monitor transfers to both.
    tokenContract.Transfer({
      to: [ saleAddress, web3.eth.defaultAccount ]
    }, changeHandler);

    // To display an accurate balance, we also need to monitor transfers out
    // of the user's account.
    tokenContract.Transfer({
      from: web3.eth.defaultAccount
    }, changeHandler);
  });
}

Here’s a brief explanation of the above code:

This code is executed once on page load.
web3.eth.getBlockNumber is used to find the latest block number. Data is loaded from that block.
New data is only loaded if an event occurs in a block that hasn’t been seen yet. This is tracked in the lastSeenBlock variable.
Transfer events have indexed parameters, so they can be efficiently filtered. An array as a filter value means a logical “or,” so the first Transfer filter will match any Transfer event that has a to argument of the sale address or the user’s account.

Handling Account Switches

Neither MetaMask nor web3.js provide an easy way to respond to the user switching accounts, but it can be important to do so. In this ICO example, information on the page pertains to a specific account, and it is updated in response to events targeting that account. If the user switches to use a different account, the UI should update accordingly.

The following code handles this situation in the ICO example app:

var initialAccount = web3.eth.defaultAccount;
window.setInterval(function () {
  if (web3.eth.defaultAccount !== initialAccount) {
    window.location.reload();
  }
}, 500);

This code checks which account is active every 500 milliseconds. If the active account changes, it simply reloads the page. A more sophisticated approach would be to reset the UI and stop all event listeners, but here the simple approach suffices.

Try the Demo

You can try the demo here. You’ll need MetaMask (or something else that injects web3.js) and an account with funds on the Ropsten test network. If you’d like to see the full source code for the front end, view the source of that page.

Summary

An initial coin offering typically uses two smart contracts: an ERC20-compatible token and a token sale contract.
Like all DApps, an ICO app has a front end written in HTML and JavaScript that uses web3.js to make calls to the blockchain.
When displaying multiple, connected pieces of data, care should be taken to retrieve all data from the same block and to update the UI atomically.
To avoid repeated work, multiple events triggered in the same block can be consolidated into a single data fetch.

Writing A Simple Dividend Token Contract

Wed, 07 Feb 2018 05:49:29 -0700

[EDIT 2018-03-13] This post has been updated to use Solidity 0.4.21 event syntax.

Tokens can provide rights or privileges to their owners. One of the most natural is the right to share proportionally in an income stream. This post will demonstrate how to write an ERC20-compliant contract that can divide ether dividends proportionally amongst token owners. This post combines ideas from our ERC20 token post, and our banking post.

This post will ignore some complications that arise from the lack of support for fixed-point numbers in the Ethereum Virtual Machine. (Specifically, I will assume that decimals==0 in the token contract.) I will address those issues in a future post.

Smart Contract Limitations

A recurring challenge in smart contract development is the high gas cost of iteration. This challenge is apparent when it comes to paying dividends. When a dividend is deposited, it must be evenly distributed among all token owners. However, there may be millions of token owners, and iterating over all of them would be tremendously expensive. Because such iteration is infeasible, contracts often need to defer such computation until it can be done on a per-item basis.

To that end, the contract will track the status of dividends owed to each account. Dividends associated with a particular account will always be in one of three states:

Already paid/transferred to the account.
Already credited to the account, but not yet transferred.
Not yet credited to the account, but the contract has sufficient information to compute the credit when needed.

All new dividends owed to an account start in the “not yet credited” state. Once that account is part of a transfer or withdrawal, the contract will compute the amount owed and credit it to the account, which moves the amount to the “credited but not transferred” status. Actual withdrawals move those credits to the final “transferred” state.

The contract will use the following values to determine the remaining amount due to each token owner:

uint256 public dividendPerToken;

mapping(address => uint256) dividendBalanceOf;

mapping(address => uint256) dividendCreditedTo;

dividendPerToken is the cumulative amount of ether per token that has been deposited in this contract. For instance, if there are 100 tokens, and the contract had collected 200 ether since its creation, then dividendPerToken would represent 2 ether per token. Note that this value is never decreased and is completely independent of any withdrawals made by token owners.
dividendBalanceOf is a mapping that represents the amount of ether credited to each account but not yet transferred to that account. Withdrawals reduce this amount.
dividendCreditedPerToken is a mapping that represents the cumulative amount of ether per token that has been previously credited to the account (i.e. added to dividendBalanceOf).

These three values track the three states of dividend payments to each account, and all values are stored in wei.

Augmenting the Simple ERC20 Token Contract

The simple ERC20 token contract requires a few changes to support dividends:

The functions that transfer tokens must be augmented to update the amounts owed to each account. The contract will do this by updating the account’s dividendCreditedPerToken and dividendBalanceOf.
The contract must accept dividend deposits, and per-account withdrawals.

Transfer Functions

Any token transfer must update the per-account dividendCreditedTo and dividendBalanceOf values. The dividendCreditedTo will be adjusted to the current (global) dividendPerToken value. That change represents the value that needs to be credited to dividendBalanceOf.

function update(address account) internal {
    uint256 owed =
        dividendPerToken - dividendCreditedTo[account];
    dividendBalanceOf[account] += balanceOf[account] * owed;
    dividendCreditedTo[account] = dividendPerToken;
}

This update function gets an account’s values up to date with respect to any dividends that were received since the last time the account was accessed. After that, the contract simply needs to update both the sender and receiver’s per-account balances in the transfer functions:

function transfer(address to, uint256 value) public returns (bool success) {
    require(balanceOf[msg.sender] >= value);

    update(msg.sender);  // <-- added to simple ERC20 contract
    update(to);          // <-- added to simple ERC20 contract

    balanceOf[msg.sender] -= value;
    balanceOf[to] += value;

    emit Transfer(msg.sender, to, value);
    return true;
}

function transferFrom(address from, address to, uint256 value)
    public
    returns (bool success)
{
    require(value <= balanceOf[from]);
    require(value <= allowance[from][msg.sender]);

    update(from);        // <-- added to simple ERC20 contract
    update(to);          // <-- added to simple ERC20 contract

    balanceOf[from] -= value;
    balanceOf[to] += value;
    allowance[from][msg.sender] -= value;
    emit Transfer(from, to, value);
    return true;
}

Deposit and Withdrawal

The deposit function accepts ether and updates the global dividendPerToken:

function deposit() public payable {
    dividendPerToken += msg.value / totalSupply;  // ignoring the remainder
}

If msg.value / totalSupply produces a remainder, then ether is lost forever. We will address this deficiency in a future post.

Withdrawal simply needs to update the the dividend owed, and then transfer it:

function withdraw() public {
    update(msg.sender);
    uint256 amount = dividendBalanceOf[msg.sender];
    dividendBalanceOf[msg.sender] = 0;
    msg.sender.transfer(amount);
}

Two things to note above:

update(msg.sender) is responsible for making sure dividendBalanceOf is up to date with respect to any dividends collected since the last update to msg.sender’s balances.
As we’ve described before, it’s essential to zero out dividendBalanceOf before doing the transfer.

Summary

ERC20 token contracts can distribute dividends proportional to token ownership.
Smart contracts that need to update per-account values across all accounts need to do so in a deferred, as-needed way to avoid iterating over all accounts.

The Whole Contract

simpleDividend.sol

pragma solidity ^0.4.21;

contract SimpleDividendToken {

    string public name = "Simple Dividend Token";
    string public symbol = "SDIV";

    // This code assumes decimals is zero---do not change.
    uint8 public decimals = 0;   //  DO NOT CHANGE!

    uint256 public totalSupply = 1000000 * (uint256(10) ** decimals);

    mapping(address => uint256) public balanceOf;

    function SimpleDividendToken() public {
        // Initially assign all tokens to the contract's creator.
        balanceOf[msg.sender] = totalSupply;
        emit Transfer(address(0), msg.sender, totalSupply);
    }

    mapping(address => uint256) dividendBalanceOf;

    uint256 public dividendPerToken;

    mapping(address => uint256) dividendCreditedTo;

    function update(address account) internal {
        uint256 owed =
            dividendPerToken - dividendCreditedTo[account];
        dividendBalanceOf[account] += balanceOf[account] * owed;
        dividendCreditedTo[account] = dividendPerToken;
    }

    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);

    mapping(address => mapping(address => uint256)) public allowance;

    function transfer(address to, uint256 value) public returns (bool success) {
        require(balanceOf[msg.sender] >= value);

        update(msg.sender);  // <-- added to simple ERC20 contract
        update(to);          // <-- added to simple ERC20 contract

        balanceOf[msg.sender] -= value;
        balanceOf[to] += value;

        emit Transfer(msg.sender, to, value);
        return true;
    }

    function transferFrom(address from, address to, uint256 value)
        public
        returns (bool success)
    {
        require(value <= balanceOf[from]);
        require(value <= allowance[from][msg.sender]);

        update(from);        // <-- added to simple ERC20 contract
        update(to);          // <-- added to simple ERC20 contract

        balanceOf[from] -= value;
        balanceOf[to] += value;
        allowance[from][msg.sender] -= value;
        emit Transfer(from, to, value);
        return true;
    }

    function deposit() public payable {
        dividendPerToken += msg.value / totalSupply;  // ignoring remainder
    }

    function withdraw() public {
        update(msg.sender);
        uint256 amount = dividendBalanceOf[msg.sender];
        dividendBalanceOf[msg.sender] = 0;
        msg.sender.transfer(amount);
    }

    function approve(address spender, uint256 value)
        public
        returns (bool success)
    {
        allowance[msg.sender][spender] = value;
        emit Approval(msg.sender, spender, value);
        return true;
    }

}

Writing a Token Sale Contract

Fri, 02 Feb 2018 12:14:20 -0800

[EDIT 2018-03-13] This post has been updated to use Solidity 0.4.21 event syntax.

In this post, I’ll build a simple smart contract that sells a limited supply of an Ethereum-based token for a fixed price. To understand this post, you’ll need to be familiar with ERC20 Tokens.

Interacting with Other Smart Contracts

The token sale smart contract will accept ether as payment and transfer tokens to the buyer in exchange. The token that will be transferred is implemented in a separate smart contract. To support calling into the token contract, I need to first tell Solidity what functions that contract supports.

An interface in Solidity is similar to the same concept in other programming languages. It describes what functions are available in a contract. The following code defines a minimal interface for ERC20-compatible tokens. Note that I don’t have to declare all the functions an ERC20 token has—just the ones I’m going to use.

interface IERC20Token {
    function balanceOf(address owner) public returns (uint256);
    function transfer(address to, uint256 amount) public returns (bool);
    function decimals() public returns (uint256);
}

I can now cast any address to type IERC20Token and then call the above functions on it, like so:

IERC20Token tokenContract = IERC20Token(0x123abc...);
uint256 decimals = tokenContract.decimals();

In the sale contract, I’ll pass the address of the token contract as a constructor parameter rather than hard-code it.

Supply and Price

Although token sales come in many shapes and sizes, in this post I’m focusing on a simple fixed-price sale of a limited supply of tokens. The contract needs to know, then, how many tokens it has available for sale and the unit price of each token.

One of the simplest ways to keep track of the supply is to use the contract’s token balance. After deploying the sale contract, I’ll call transfer(contractAddress, amountToSell) on the token contract. Once I’ve transferred tokens to it, the sale contract can use tokenContract.balanceOf(this) to see how many tokens are available to be sold.

The price needs to be set at deployment time, so in addition to the address of the token contract, I’ll add a constructor parameter for the price:

contract TokenSale {
    IERC20Token public tokenContract;  // the token being sold
    uint256 public price;              // the price, in wei, per token
    address owner;

    function TokenSale(IERC20Token _tokenContract, uint256 _price) public {
        owner = msg.sender;
        tokenContract = _tokenContract;
        price = _price;
    }
}

Two things to notice in the above code:

When I deploy the contract, I’ll pass an address as the first argument, and Solidity will cast it for me to type IERC20Token.
I’m keeping track of the owner (the account that deployed the contract). The owner account is special in that it will be allowed to end the sale and retrieve the collected ether.

Selling Tokens

Now that the contract has tokens to sell and a price at which to sell them, it’s time to write the core logic of the contract. It may be helpful to read Writing a Contract That Handles Ether if you haven’t already:

uint256 public tokensSold;

event Sold(address buyer, uint256 amount);

function buyTokens(uint256 numberOfTokens) public payable {
    require(msg.value == safeMultiply(numberOfTokens, price));

    uint256 scaledAmount = safeMultiply(numberOfTokens,
            uint256(10) ** tokenContract.decimals());

    require(tokenContract.balanceOf(this) >= scaledAmount);

    emit Sold(msg.sender, numberOfTokens);
    tokensSold += numberOfTokens;

    require(tokenContract.transfer(msg.sender, scaledAmount));
}

Here’s a brief explanation of the above code:

To help prevent mistakes, the function accepts as a parameter how many tokens are being purchased and then checks that the correct amount of ether was sent.
Recall from Writing an ERC20 Token Contract that in order to support fixed point math on tokens, “1 token” is represented in the token contract as a value of 10^decimals, where decimals is how many decimal places after the zero the contract supports. I convert the number of tokens to this scaled number in scaledAmount.
safeMultiply (defined below) is used to guard against integer overflows if someone maliciously passes in a very high value for numberOfTokens.
The second require statement checks to make sure the contract has a sufficient number of tokens to complete the sale.
tokensSold and the Sold event are there for UI purposes. They make it easy for a front end application to monitor the progress of the sale.
Because the ERC20 token standard allows tokens to return false on failure, rather than reverting, the final require is necessary to ensure the buyer actually receives their tokens.

Ending the Sale

In this sale contract, the owner will be allowed to end the sale at any time. All unsold tokens will be transferred to the owner, as will all collected ether.

function endSale() public {
    require(msg.sender == owner);

    // Send unsold tokens to the owner.
    require(tokenContract.transfer(owner, tokenContract.balanceOf(this)));

    msg.sender.transfer(address(this).balance);
}

This function transfers all remaining tokens as well as all ether collected. Because the contract holds no more tokens, any subsequent calls to buyTokens will fail.

Summary

Contracts can call functions in other contracts, but to do so they must declare the target contract’s interface.
Care must be taken to scale ERC20 token amounts appropriately according to their number of decimals.

Full Source Code

tokenSale.sol

pragma solidity ^0.4.21;

interface IERC20Token {
    function balanceOf(address owner) public returns (uint256);
    function transfer(address to, uint256 amount) public returns (bool);
    function decimals() public returns (uint256);
}

contract TokenSale {
    IERC20Token public tokenContract;  // the token being sold
    uint256 public price;              // the price, in wei, per token
    address owner;

    uint256 public tokensSold;

    event Sold(address buyer, uint256 amount);

    function TokenSale(IERC20Token _tokenContract, uint256 _price) public {
        owner = msg.sender;
        tokenContract = _tokenContract;
        price = _price;
    }

    // Guards against integer overflows
    function safeMultiply(uint256 a, uint256 b) internal pure returns (uint256) {
        if (a == 0) {
            return 0;
        } else {
            uint256 c = a * b;
            assert(c / a == b);
            return c;
        }
    }

    function buyTokens(uint256 numberOfTokens) public payable {
        require(msg.value == safeMultiply(numberOfTokens, price));

        uint256 scaledAmount = safeMultiply(numberOfTokens,
            uint256(10) ** tokenContract.decimals());

        require(tokenContract.balanceOf(this) >= scaledAmount);

        emit Sold(msg.sender, numberOfTokens);
        tokensSold += numberOfTokens;

        require(tokenContract.transfer(msg.sender, scaledAmount));
    }

    function endSale() public {
        require(msg.sender == owner);

        // Send unsold tokens to the owner.
        require(tokenContract.transfer(owner, tokenContract.balanceOf(this)));

        msg.sender.transfer(address(this).balance);
    }
}

Writing an ERC20 Token Contract

Tue, 30 Jan 2018 13:33:39 -0800

[EDIT 2018-03-13] This post has been updated to use Solidity 0.4.21 event syntax.

This post will demonstrate how to write a simple, but complete, smart contract in Solidity that implements the ERC20 token standard. It assumes that you are familiar with concepts introduced in our post, What is an Ethereum Token?, which discussed how tokens are maintained as per-account balances and how those balances can be transferred between accounts.

The ERC20 token standard enables different tokens to be treated similarly in marketplaces and exchanges. It also enables contracts that handle tokens to be written once and used across many different tokens. For instance, the same contract might be able to handle the initial sale of different ERC20 tokens. This post is going to develop a very simple ERC20-compliant token contract, which (I hope) will help you understand the standard from a code-centric point of view.

You don’t need to be familiar with the standard to understand this post. Like most standards, some things are required and some are optional. The code below will implement everything, but we’ll point out the optional parts.

`name` and `symbol` (optional)

ERC20 token contracts may give their tokens a (string) name and a (string) symbol. Typically, the name is a short description of the token, and the symbol is a one word identifier. To be compliant, the name and symbol must be accessible via view functions with the following types:

// ERC20 optional functions
function name() view returns (string name)
function symbol() view returns (string symbol)

To implement those, I will use the Solidity shorthand of simply defining public variables by the same name with the same type (because Solidity will generate the corresponding getter automatically):

string public name;
string public symbol;

`totalSupply` (required)

ERC20 contracts must provide a similar view function that returns the current number of outstanding tokens. Again, I will use a public variable because Solidity will create the corresponding public getter:

uint256 public totalSupply;

Fixed-point Math: `decimals` (optional)

Neither the Ethereum Virtual Machine nor Solidity offer support for fixed-point numbers—they only support various flavors of integers. This presents a challenge when a contract would like to present others with the idea of a fractional unit. To do this, it is necessary to simulate fixed-point numbers explicitly.

This kind of simulation is already done with ether. When contracts pass around huge 256-bit integers to represent ether transfers, those numbers don’t actually directly represent ether—they represent wei. Recall that 1 ether equals 10^18 wei. This means that when a contract is given a uint256 value that represents a single ether, it is not passed the integer 1, it is passed the integer 1,000,000,000,000,000,000.

Many token contracts support fractional tokens, and they do so in precisely the same way by having a scaling factor. In ERC20 tokens, that scaling factor is denoted by the value of decimals, which indicates how many 0’s there are to the right of the decimal point the fixed-point representation of a token.

For instance, a contract that supports ¹⁄₁₀₀’s of tokens (e.g, 3.14, 2.72), would have decimals equal to 2. If decimals = 2, then the value stored to represent 3.14 would be 314.

ERC20 contracts support this with the optional view public function, decimals. Again, a public variable suffices:

uint8 public decimals;

Unlike the common use of 256-bit integers in Solidity programs, this only requires 8 bits because 8 bits worth of zeroes is a lot of zeroes.

For this contract, the fixed-point simulation requires only trivial additional code, which will appear below when the contract computes the totalSupply of tokens.

We should note that it appears that the accepted norm is to use decimals = 18.

`Transfer` Event (required)

Recall from our post that events are the convenient method the EVM provides for logging information for external consumers. ERC20 contracts are required to publish events whenever token transfer attempts succeed. The Transfer event publishes the from and to accounts as well as the token value transferred:

event Transfer(address indexed from, address indexed to, uint256 value);

Note that the from and to addresses are indexed to help event consumers efficiently monitor only those events they care about.

`balanceOf` (required)

ERC20 contracts maintain per-account token balances, which must be accessible via a public view function. Once again, Solidity makes this easy:

mapping (address => uint256) public balanceOf;

By now, this code should look familiar since we used it in our banking, crowdfunding, and simple token posts!

Finally, Some Code!

I’ll put the snippets above into a contract to make it more concrete. For this example, we’ll have the contract create 1,000,000 tokens and transfer all of those tokens to the contract’s creator account. I’ll add a small constructor that does that:

contract SimpleERC20Token {
    mapping (address => uint256) public balanceOf;

    string public name = "Simple ERC20 Token";
    string public symbol = "SET";
    uint8 public decimals = 18;

    uint256 public totalSupply = 1000000 * (uint256(10) ** decimals);

    event Transfer(address indexed from, address indexed to, uint256 value);

    function SimpleERC20Token() public {
        // Initially assign all tokens to the contract's creator.
        balanceOf[msg.sender] = totalSupply;
        emit Transfer(address(0), msg.sender, totalSupply);
    }

    // more stuff to come
}

The constructor above does a few notable things:

I hardcoded values for name, symbol, decimals, and totalSupply. Obviously, these could have been constructor parameters, or even computed values, but this example is intentionally simple.
The computation of totalSupply required scaling due to the use of fixed-point numbers.
Although the ERC20 standard doesn’t explicitly require it, it is considered a best practice to log a Transfer event indicating the “transfer” from address 0 of tokens to the creator’s account (msg.sender).

`transfer` (required)

ERC20 tokens can be transferred directly from their owner’s account to any other account with a public transfer function:

function transfer(address to, uint256 value) public returns (bool success) {
    require(balanceOf[msg.sender] >= value);

    balanceOf[msg.sender] -= value;           // deduct from sender's balance
    balanceOf[to] += value;                  // add to recipient's balance

    emit Transfer(msg.sender, to, value);
    return true;
}

This (required) transfer function includes some things demanded by the standard:

transfer requires that the sender/owner has enough tokens to fulfill the transfer. It will not do a partial transfer.
Successful transfers must log the appropriate Transfer event.
transfer must return a bool value representing a successful transfer.

Please note that the ERC20 token standard is actually silent on whether transfer should revert when msg.sender doesn’t have sufficient tokens, or if it should simply return false. (It must do one of the two.) I have chosen to have it revert, which seems like a safer choice.

Delegated Transfer Functionality

Up to now, the ERC20 standard operations are pretty much what you might expect: inspect balances, directly transfer balances, etc. In addition to these operations, the standard requires support for a delegated transfer. In this model, the owner account of tokens can delegate the authority to transfer some of its tokens to another account. This idea is a bit subtle: the owner isn’t transferring the tokens to another account, but rather allowing that other account to transfer tokens to whomever it wishes. This facilitates exchange-brokered token transfers.

Delegated transfers in ERC20 are orchestrated with the following required pieces:

a delegation function (approve)
the subsequent indirect transfer function (transferFrom)
some state to remember what’s been delegated to whom (allowance)
an event that logs when delegations succeed (Approval)

Approval Event (required)

ERC20 requires an event to log the successful approval of a delegated token transfer, which logs the owner, the delegated spender, and the amount:

event Approval(address indexed owner, address indexed spender, uint256 value);

Just like the Transfer event, the account addresses are indexed parameters to aid event consumers.

`allowance` (required)

Because separate transactions delegate token transfer approval and actually transfer those tokens, it’s necessary to keep track of which accounts have delegated how much token authority to which other accounts. Fortunately, this can be done trivially with a nested mapping:

mapping(address => mapping(address => uint256)) public allowance;

This declaration of allowance is more complicated that we’ve seen before. The declaration includes a mapping within a mapping, which simply means that every address in the outer mapping will map to a distinct mapping, which will then map addresses to integers. It’s easiest to think of this a two-dimensional mapping, which maps pairs of addresses to integers. This notion is clearer when you see the getter that the Solidity compiler creates for this:

function allowance(address owner, address spender)
    view
    returns (uint256 remaining)

(That’s the function required by the ERC20 standard. I’m exploiting the fact that Solidity will generate that automatically from my allowance declaration.)

`approve` (required)

The ERC20 delegation function, approve, can be quite short:

function approve(address spender, uint256 value) public returns (bool success) {
    allowance[msg.sender][spender] = value;
    emit Approval(msg.sender, spender, value);
    return true;
}

A few notes on the code above:

It’s msg.sender’s account that is delegating a transfer, as can be seen in the adjustment to allowance.
A sender can approve a delegated transfer that exceeds their actual token balance. Because the transfer wouldn’t happen until transferFrom is called, the check for adequate balance is deferred until then. Therefore, all approvals can succeed.
Even though all approvals can succeed, the function is still required to return true.
approve must log its parameters with an Approval event.

transferFrom

ERC20’s transferFrom function is the most complicated function in ERC20. transferFrom is called by the delegated-to account in order to transfer tokens to another account.

function transferFrom(address from, address to, uint256 value)
    public
    returns (bool success)
{
    require(value <= balanceOf[from]);
    require(value <= allowance[from][msg.sender]);

    balanceOf[from] -= value;
    balanceOf[to] += value;
    allowance[from][msg.sender] -= value;
    emit Transfer(from, to, value);
    return true;
}

There’s a lot going on above:

require(value <= balanceOf[from]) guarantees that the delegator actually owns enough tokens to satisfy the transfer request.
require(value <= allowance[from][msg.sender]) guarantees that the spender is actually authorized to transfer that many tokens from the delegator’s balance.
allowance[from][msg.sender] -= value; reduces the number of tokens the spender is allowed to transfer on behalf of the delegator.
Just like for the transfer function, a successful transfer must log a Transfer event.
As before, if an attempt is made to transfer too many tokens, I’ve chosen to revert the transaction rather than return false.

Summary

ERC20 token contracts must support direct and indirect token transfers.
ERC20 token contracts optionally support names, symbols, and decimal fixed-point scaling.

The Whole ERC20 Contract

erc20.sol

pragma solidity ^0.4.21;

contract SimpleERC20Token {
    // Track how many tokens are owned by each address.
    mapping (address => uint256) public balanceOf;

    string public name = "Simple ERC20 Token";
    string public symbol = "SET";
    uint8 public decimals = 18;

    uint256 public totalSupply = 1000000 * (uint256(10) ** decimals);

    event Transfer(address indexed from, address indexed to, uint256 value);

    function SimpleERC20Token() public {
        // Initially assign all tokens to the contract's creator.
        balanceOf[msg.sender] = totalSupply;
        emit Transfer(address(0), msg.sender, totalSupply);
    }

    function transfer(address to, uint256 value) public returns (bool success) {
        require(balanceOf[msg.sender] >= value);

        balanceOf[msg.sender] -= value;  // deduct from sender's balance
        balanceOf[to] += value;          // add to recipient's balance
        emit Transfer(msg.sender, to, value);
        return true;
    }

    event Approval(address indexed owner, address indexed spender, uint256 value);

    mapping(address => mapping(address => uint256)) public allowance;

    function approve(address spender, uint256 value)
        public
        returns (bool success)
    {
        allowance[msg.sender][spender] = value;
        emit Approval(msg.sender, spender, value);
        return true;
    }

    function transferFrom(address from, address to, uint256 value)
        public
        returns (bool success)
    {
        require(value <= balanceOf[from]);
        require(value <= allowance[from][msg.sender]);

        balanceOf[from] -= value;
        balanceOf[to] += value;
        allowance[from][msg.sender] -= value;
        emit Transfer(from, to, value);
        return true;
    }
}

What is an Ethereum Token?

Fri, 26 Jan 2018 09:15:05 -0800

This post explains what an Ethereum “token” or “coin” is (and is not). It will convey an intuitive understanding of tokens and describe the implementation of a very simple token in Solidity.

Cryptocurrencies

Tokens are similar to blockchain-based cryptocurrencies, so it will be helpful to review a few salient qualities of cryptocurrencies like Bitcoin and Ethereum:

Cryptocurrencies exist entirely on a blockchain—any relationship to objects (or currencies) in the physical world is based purely on agreements outside of the blockchain.
Cryptocurrency allocations are maintained as per-account balances on the blockchain—an account only “owns” an amount of cryptocurrency to the extent that the blockchain’s ledger reflects that balance for that account.
Cryptocurrency balances can change by virtue of verifiable transfers from one account to another on the blockchain.

The common thread above is that cryptocurrencies are blockchain entities. Cryptocurrencies have physical-world value because people are willing to transfer them on the blockchain in exchange for physical-world money, goods or services.

Cryptocurrency-like Tokens

Our previous post on banking demonstrated that smart contracts can trivially maintain per-account balances, and that it’s trivial to update those balances via transactions. Using very similar techniques, a contract could maintain per-account balances of a new cryptocurrency. If the contract both maintained per-account balances and supported account-to-account balance transfers, you would have all the necessary components of a cryptocurrency. Such contracts create “tokens” (or “coins”).

Contracts that create new tokens are very easy to develop and deploy, which is a big reason why so many “Initial Coin Offerings” are built upon the Ethereum network.

A Simple Token Implementation

minimal_token.sol

pragma solidity ^0.4.19;

contract MinimalToken {
    // Track how many tokens are owned by each address.
    mapping (address => uint256) public balanceOf;

    function MinimalToken(uint256 totalSupply) public {
        // Initially assign all tokens to the contract's creator.
        balanceOf[msg.sender] = totalSupply;
    }

    function transfer(address to, uint256 amount) public {
        require(balanceOf[msg.sender] >= amount);

        balanceOf[msg.sender] -= amount;  // deduct from sender's balance
        balanceOf[to] += amount;          // add to recipient's balance
    }
}

This contract has the necessary components of a cryptocurrency:

It maintains a per-account balance in the balanceOf state variable.
It supports account-to-account transfers via the transfer function.

Note that most tokens built on Ethereum implement a standard called ERC-20. Tokens implementing this standard API can be viewed and transferred using generic wallet software, and they can be bought and sold on generic currency exchanges. The minimal token described here implements only a subset of the ERC-20 standard. In a future post, we’ll implement the rest of the standard.

Summary

Ethereum tokens (or coins) are tracked by on-blockchain balances maintained by smart contracts.
Tokens are held by accounts.
Accounts can (typically) transfer token balances to other accounts.
Tokens balances and operations are very similar to those of blockchain-based cryptocurrencies.

Logging and Watching Solidity Events

Wed, 24 Jan 2018 08:04:38 -0800

[EDIT 2018-03-13] This post has been updated to use Solidity 0.4.21 event syntax.

Events are a way for smart contracts written in Solidity to log that something has occurred. Interested observers, notably JavaScript front ends for decentralized apps, can watch for events and react accordingly. In this post, I’ll show you how to log events from a Solidity smart contract and watch those events in JavaScript. The code in this post builds on the example from the earlier post, Building Decentralized Apps With Ethereum and JavaScript.

Solidity Events

Events in Solidity are declared with the event keyword, and logging an event is done with the emit keyword. Events can be parameterized. The following code is adapted from the Counter example introduced in Writing a Very Simple Smart Contract:

counter-with-events.sol

pragma solidity ^0.4.21;

contract Counter {
    uint256 public count = 0;

    event Increment(address who);   // declaring event

    function increment() public {
        emit Increment(msg.sender); // logging event
        count += 1;
    }
}

The code above introduces the following techniques:

event Increment(address who) declares a contract-level event that takes a single parameter of type address which indicates what address performed the increment operation.
emit Increment(msg.sender) logs the previously declared event with msg.sender as its argument.

By convention, event names begin with uppercase letters. This distinguishes them from functions.

Listening to Events in JavaScript

The following JavaScript code listens for the Increment event and updates the UI accordingly. It is adapted from the code in Building Decentralized Apps With Ethereum and JavaScript:

counter = web3.eth.contract(abi).at(address);

counter.Increment(function (err, result) {
  if (err) {
    return error(err);
  }

  log("Count was incremented by address: " + result.args.who);
  getCount();
});

getCount();

Here’s a brief explanation of the above code:

contract.Increment(...) starts listening for the Increment event, and is parameterized with the callback function.
getCount() is a function that fetches the latest count and updates the UI.

You can see this function in action in the “Counter Example With Events” demo. Unlike in the original example, now the UI is automatically updated any time the counter is incremented. If you open the app in multiple windows or even on different devices, you will see that incrementing the counter in any instance of the app triggers an update in all of them.

Indexed Parameters

Up to three of an event’s parameters can be marked as indexed. An indexed parameter can be used to efficiently filter events. The following code enhances the previous example to track many counters, each identified by a numeric ID:

multicounter.sol

pragma solidity ^0.4.21;

contract Multicounter {
    mapping (uint256 => uint256) public counts;

    event Increment(uint256 indexed which, address who);

    function increment(uint256 which) public {
        emit Increment(which, msg.sender);
        counts[which] += 1;
    }
}

Here’s a brief explanation of the above code:

counts replaces the previous count with a mapping of IDs to counts.
event Increment(uint256 indexed which, address who) adds an indexed parameter which to indicate which counter was incremented.
emit Increment(which, msg.sender) logs the event with both arguments.

Filtering Events in JavaScript

The “Multicounter” demo uses the previous Solidity contract and allows the user to watch and manipulate any counter by entering a numeric counter ID. This may seem a bit contrived, but imagine a contract that implements many instances of a two-person game. The participants in the game would be interested only in events for their specific game, so a game ID could be used as an event filter.

The following code is invoked in the Multicounter demo when the user switches to a new counter ID. It filters for events with the new ID as the which parameter:

log("Switching to counter '" + counterId + "'.");

if (event !== null) {
  // Stop listening to events with the old ID.
  event.stopWatching();
}
event = counter.Increment({ which: counterId }, function (err, result) {
  if (err) {
    return error(err);
  }

  log("Counter " + result.args.which + " was incremented by address: "
      + result.args.who);
  getCount();
});

getCount();

Here’s a brief explanation of the above code:

The first parameter to Increment specifies a filter. Only events matching the filter will trigger the callback function. The simplest type of a filter is used here: a dictionary mapping parameter names to values.
event = counter.Increment(...) captures an event object. This can be used to stop and start listening to the event.
event.stopWatching() stops monitoring for events with the old counter ID.

Event Limitations

Events are built on top of a lower level log interface in Ethereum. Although you typically won’t deal with log messages directly, it’s important to understand their limitations.

Logs are structured as up to four “topics” and a “data” field. The first topic is used to store the hash of the event’s signature, which leaves only three topics for indexed parameters. Topics are required to be 32 bytes long, so if you use an array for an indexed parameter (including types string and bytes), the value will first be hashed to fit into 32 bytes. Non-indexed parameters are stored in the data field and do not have a size limit.

Logs, and therefore events, are not accessible from within the Ethereum virtual machine (EVM). This means that contracts cannot read their own logs or the logs of other contracts.

Summary

Solidity provides a way to log events during transactions.
Decentralized app (DApp) front ends can subscribe to these events.
indexed parameters provide an efficient means for filtering events.
Events are limited by the underlying log mechanism upon which they are built.

Resources

The Solidity documentation on events
The web3.js documentation on events
View the page source for the “Counter With Events” demo and the “Multicounter” demo

Writing a Crowdfunding Contract (a la Kickstarter)

Fri, 19 Jan 2018 06:11:30 -0700

This post will demonstrate how to write a smart contract that controls a crowdfunding effort in the spirit of Kickstarter. It assumes that you have read our previous posts on banking and time.

Kickstarter crowdfunding efforts are “assurance contracts”, which enable projects to raise money from a group of people based on a simple concept: during a fixed crowdfunding period of time, funders pledge funds in an attempt to raise a total amount that meets a fixed goal amount. If pledges meet the goal before the period expires, the funds are transferred to the project so that it may proceed. If pledges are insufficient when the period expires, the funds are refunded to the funders.

Parameterizing the Crowdfunding Contract

This smart contract is parameterized by two values:

The crowdfunding period (in days). (This is very similar to the time post.)
The goal amount (in wei).

The contract keeps track of the owner/crowdfunding account, and it keeps track of the total amount pledged by each account. (This is very similar to the banking post.)

contract Crowdfunding {
    address owner;
    uint256 deadline;
    uint256 goal;
    mapping(address => uint256) public pledgeOf;

    function Crowdfunding(uint256 numberOfDays, uint256 _goal) public {
        owner = msg.sender;
        deadline = now + (numberOfDays * 1 days);
        goal = _goal;
    }

    // ...to be filled in soon...
}

Accepting Pledges

Accepting a pledge is pretty straightforward as well. The function is parameterized by the value attached. (This parameter is checked as a safety measure to avoid accidentally attaching the wrong amount.) It updates the amount pledged by the sending account and determines if the funding goal has been met.

For simplicity’s sake, this contract will strictly divide time into two distinct periods: the fundraising period and the withdrawal period. During the fundraising period, the contract will accept pledges, but it will not allow withdrawals. During the withdrawal period, the contract will not accept pledges, but it will allow withdrawals.

function pledge(uint256 amount) public payable {
    require(now < deadline);                // in the fundraising period
    require(msg.value == amount);

    pledgeOf[msg.sender] += amount;
}

Withdrawing Funds

Funds can only be withdrawn after the deadline passes. As described above, who can withdraw funds depends on whether or not the goal was met.

To separate the logic guarding who can withdraw funds when, I’ve split the functionality into two routines: claimFunds (for the owner), and getRefund (for the funders):

function claimFunds() public {
    require(address(this).balance >= goal); // funding goal is met
    require(now >= deadline);               // in the withdrawal period
    require(msg.sender == owner);

    msg.sender.transfer(address(this).balance);
}

function getRefund() public {
    require(address(this).balance < goal);  // funding goal not met
    require(now >= deadline);               // in the withdrawal period

    uint256 amount = pledgeOf[msg.sender];
    pledgeOf[msg.sender] = 0;
    msg.sender.transfer(amount);
}

The code above includes a few notable things:

Whenever transferring funds out of a contract, it’s really important for a contract to make sure the conditions are correct. Both claimFunds and getRefund check multiple conditions.
The getRefund routine sets the account’s pledgeOf value to 0 before doing the transfer. This is a safety precaution, which is described fully in the banking post.
There is a subtlety to the address(this).balance < goal test in getRefund. Each successful refund will change the value of address(this).balance, which will affect subsequent refund attempts. It is important that such changes not affect future tests of the success of the crowdfunding. In this case that invariant is maintained because refunds decrease address(this).balance, which means that address(this).balance < goal will remain true.

Summary

By (carefully) combining techniques for keeping track of time and per-account balances, a small smart contract can implement a Kickstarter-like crowdfunding.

The Complete Contract

crowdfunding.sol

pragma solidity ^0.4.19;

contract Crowdfunding {
    address owner;
    uint256 deadline;
    uint256 goal;
    mapping(address => uint256) public pledgeOf;

    function Crowdfunding(uint256 numberOfDays, uint256 _goal) public {
        owner = msg.sender;
        deadline = now + (numberOfDays * 1 days);
        goal = _goal;
    }

    function pledge(uint256 amount) public payable {
        require(now < deadline);                // in the fundraising period
        require(msg.value == amount);

        pledgeOf[msg.sender] += amount;
    }

    function claimFunds() public {
        require(address(this).balance >= goal); // funding goal met
        require(now >= deadline);               // in the withdrawal period
        require(msg.sender == owner);

        msg.sender.transfer(address(this).balance);
    }

    function getRefund() public {
        require(address(this).balance < goal);  // funding goal not met
        require(now >= deadline);               // in the withdrawal period

        uint256 amount = pledgeOf[msg.sender];
        pledgeOf[msg.sender] = 0;
        msg.sender.transfer(amount);
    }
}

Verifying Contract Source Code

Tue, 16 Jan 2018 09:16:05 -0800

For a deployed smart contract to be trusted, its source code should be available for inspection. This post explains why source code for smart contracts should be published and how someone can verify that published source code corresponds to a given deployed smart contract.

Trusting Smart Contracts

The power of smart contracts is that they’re “trustless.” Once deployed, a smart contract is immutable and tamper-proof. It is guaranteed to execute exactly the code that was written. That guarantee, however, is only meaningful if you know what code is being executed.

Everything on the blockchain is public, including smart contracts’ bytecode, but bytecode is low-level and quite difficult to understand. The source code, written in Solidity, is much more useful. If you want other people to trust your smart contracts, you should publish the source code, and before you interact with someone else’s smart contract, you should examine their source code.

This raises an important question: what prevents a malicious developer from publishing fake source code for their contract?

Verifying Source Code

As you may recall from our recent post How Smart Contract Deployment Works, the transaction that deploys a smart contract has a payload that is derived from the compiled source code and any constructor parameters. This process is fully deterministic, so if you compile the same source code with the same compiler and apply the same constructor parameters, you’ll get the exact same payload.

This repeatable process is the key to verifying the correspondence between Solidity source code and a deployed smart contract. When publishing your source code, you need to provide all the necessary information to recreate the deployment payload. In addition to the source code itself, you need to share what compiler settings you used, what version of the compiler you used, and what constructor parameters you applied. Anyone can then generate the corresponding deployment payload, and then they can find the transaction on the blockchain that created the smart contract in question. If the two payloads match, then the provided source code was, in fact, what was used to deploy that smart contract.

This process is a bit cumbersome, so most people choose to delegate this responsibility to a third party.

Publishing and Finding Source Code on Etherscan

Etherscan is a highly-regarded set of tools and services for reading information from the Ethereum blockchain. Among other things, they provide source code verification as a service. Anyone can use their verify contract code tool to associate source code with any deployed contract. The tool will build the deployment payload, verify that the payload matches what’s found on the blockchain, and only then associate the payload with the contract. As long as people trust Etherscan to perform this verification process correctly, they don’t need to go through the verification steps themselves.¹

If Etherscan has verified source code for a deployed contract, you can find that code in the “Contract Source” tab when viewing the contract’s address. For example, the Counter Example DApp is published to the Ropsten test network. I verified its source code, so you can view the source code on Etherscan.

Because of the deterministic nature of this process, you don’t need to verify the source code again if you deploy a new smart contract using the same source code, the same compiler settings, and the same constructor parameters. Etherscan associates the source code with the deployment payload, not the individual contract address, so you’ll see the source code immediately after you deploy.

Summary

Smart contracts can’t truly be trusted unless their source code is available.
Source code needs to be verified to make sure it’s what was actually compiled and deployed.
Source code verification is possible because the deployment payload is deterministic.
Etherscan offers smart contract code verification as a service to make the process easier.

Etherscan doesn’t check for an exact match of the full payload data. It specifically checks the compiled bytecode and the constructor parameters. The payload also contains metadata that includes hashes of each source file. By ignoring this metadata, Etherscan can verify source code with changes to whitespace or comments. ↩

Writing a Contract That Handles Time

Fri, 12 Jan 2018 09:22:33 -0800

This post will demonstrate how to write a simple, but complete, smart contract in Solidity that deals with time. It assumes that you have read our previous post, Checking the Sender In a Smart Contract.

Sometimes you may want your smart contract to respond to transactions differently after some point in the future. To do this, the contract needs to have a way to express and store values that represent time. The Ethereum Virtual Machine represents time as the (integer) number of seconds since the “Unix epoch”, and the current time is accessible to a Solidity program as now, which is an alias for block.timestamp.

The code below creates a smart contract that does nothing beyond remembering when it was created:

pragma solidity ^0.4.19;

contract Time {
    uint256 public createTime;

    function Time() public {
        createTime = now;
    }
}

This contract demonstrates the following:

The system-defined variable now contains the current time in seconds since the Unix epoch. This is defined as the timestamp of the block (on the blockchain) that the transaction is a part of.
The natural unit of time in the EVM is seconds.

Relative Time

To demonstrate using time to influence transaction processing, I am going to develop a smart contract to help me save money for a specified period of time. During that period, I (or anybody else!) can deposit ether in the contract, but the contract will not let me withdraw any ether until the waiting period is over.

Solidity has “time units” built in. I can specify 3 days or 5 years, for instance. The savings contract will be parameterized by a waiting period specified in days. Because the EVM naturally stores time in seconds, the contract must scale the waiting period by the number of seconds in a day, which is given by the literal 1 days in Solidity.

savings.sol

pragma solidity ^0.4.19;

contract Savings {
    address owner;
    uint256 deadline;

    modifier onlyOwner() {
        require(msg.sender == owner);
        _;
    }

    function deposit(uint256 amount) public payable {
        require(msg.value == amount);
    }

    function Savings(uint256 numberOfDays) public payable {
        owner = msg.sender;
        deadline = now + (numberOfDays * 1 days);
    }

    function withdraw() public onlyOwner {
        require(now >= deadline);

        msg.sender.transfer(address(this).balance);
    }
}

The code above demonstrates the following new concepts:

(numberOfDays * 1 days) computes the time in seconds in numberOfDays days.
now + (numberOfDays * 1 days) computes the EVM time that represents numberOfDays days in the future.
now >= deadline tests if the current time is greater than or equal to deadline. (I.e, has the deadline passed?)

The Savings contract is parameterized by the number of days during which no withdrawals are permitted. During that period, any withdraw transactions will simply fail. After that time has elapsed, withdrawals will succeed.

Deposits are allowed at any time. Note also that the constructor has the payable modifier, which allows ether to be attached (and transferred) to the contract during deployment.

Summary

Each block in the blockchain includes a timestamp specified as the number of seconds since the Unix epoch. Time values are integers.
Solidity smart contracts can access the timestamp of the current block as now or block.timestamp.
Solidity provides convenient time units like days and years, which are helpful in computing time spans.

Additional Resources

Units and Globally Available Variables has more information about units of time in Solidity.

How Smart Contract Deployment Works

Tue, 09 Jan 2018 07:20:47 -0800

[This blog post explains a little bit about how smart contract deployment works in an Ethereum network, but it is not necessary for learning Solidity programming. We write it for those of you who’d like a little deeper understanding of what is going on when a smart contracts are deployed.]

In our How Ethereum Transactions Work post, we described the essential elements of a transaction message in an Ethereum network and how they work. This post will similarly describe how smart contracts are initially deployed to the network.

Smart Contract Deployments Are Transactions

The Ethereum network has only one transaction mechanism, which is overloaded to handle three distinct kinds of transactions:

A simple ether transfer to an externally owned account
Invocation of code associated with a previously deployed smart contract (and possibly an ether transfer)
Deployment of a smart contract (and possibly an ether transfer to the corresponding deployed contract)

Contract deployment is by far the most subtle operation. To understand it, let’s review the components of a transaction message:

recipient
value
data
gas limit
gas price
nonce
signature

For contract deployment, there is nothing unique about the value (attached ether), the gas limit and price, the nonce, or the signature. The recipient and the data, however, are special:

recipient For contract deployment, the recipient address is 0. This signifies that the transaction creates a contract.
data For contract deployment, the data field holds code to be executed during deployment.

Contract Initialization

The data field of a contract deployment transaction is code to be executed during contract initialization. It is not the code that is executed on subsequent transactions sent to the contract. That code is returned by the initialization code. Essentially, the code in the data field is a program that is going to write a program that gets deployed as a smart contract. Although that sounds fairly open-ended and complex, in practice it is typically quite straightforward. The standard initialization code generated by the Solidity compiler does the following:

Runs the code in the contract’s constructor, setting storage values, etc.
Copies the code for the rest of the contract into memory and returns it.

The code to be copied is simply appended to the constructor’s code in the data field.

Constructor parameters are handled similarly. They are stored last in the data field, and the initialization code reads them from there.

The Address of the Deployed Contract

Once a contract is deployed, it is referenced by its address, which is guaranteed to be unique. Computing the address requires only the address of the sender account and the sender’s nonce. Per Section 7, “Contract Creation,” of the Ethereum yellow paper:

The address of the new account is defined as being the rightmost 160 bits of the Keccak hash of the RLP encoding of the structure containing only the sender and the nonce.

Externally owned accounts have nonces that start at zero and increase with each transaction. Contracts can also deploy other contracts, so they also need to have nonces. Per EIP-161, contracts start with a nonce of 1. This is a fairly recent change, so you may still see older deployed contracts with nonces of 0.¹ The nonce for a contract account only increases when it deploys a new contract. “Internal transactions” (when a contract calls into another contract or transfers ether) do not increase the contract’s nonce.

Summary

Contract deployment is a special Ethereum transaction sent to the address 0.
The deployment has the side effects of creating bytecode at a specific address (i.e, it creates a smart contract account).
Contracts are deployed at predictable addresses based on the address and nonce of the account creating the contract.

Resources

An excellent, although much more detailed, explanation can be found in Diving Into The Ethereum VM Part 5 — The Smart Contract Creation Process.

The definitive explanation is in the Ethereum yellow paper.

On some test networks, the nonce starts at a different value (to avoid replay attacks between networks). So it would be more accurate to say that contract nonces start at n+1, where n is the initial nonce for an account. ↩

Writing a Banking Contract

Fri, 05 Jan 2018 13:10:30 -0800

This article will demonstrate how to write a simple, but complete, smart contract in Solidity that acts like a bank that stores ether on behalf of its clients. The contract will allow deposits from any account, and can be trusted to allow withdrawals only by accounts that have sufficient funds to cover the requested withdrawal.

This post assumes that you are comfortable with the ether-handling concepts introduced in our post, Writing a Contract That Handles Ether.

That post demonstrated how to restrict ether withdrawals to an “owner’s” account. It did this by persistently storing the owner account’s address, and then comparing it to the msg.sender value for any withdrawal attempt. Here’s a slightly simplified version of that smart contract, which allows anybody to deposit money, but only allows the owner to make withdrawals:

pragma solidity ^0.4.19;

contract TipJar {

    address owner;    // current owner of the contract

    function TipJar() public {
        owner = msg.sender;
    }

    function withdraw() public {
        require(owner == msg.sender);
        msg.sender.transfer(address(this).balance);
    }

    function deposit(uint256 amount) public payable {
        require(msg.value == amount);
    }

    function getBalance() public view returns (uint256) {
        return address(this).balance;
    }
}

Maintaining Individual Account Balances

I am going to generalize this contract to keep track of ether deposits based on the account address of the depositor, and then only allow that same account to make withdrawals of that ether. To do this, we need a way keep track of account balances for each depositing account—a mapping from accounts to balances. Fortunately, Solidity provides a ready-made mapping data type that can map account addresses to integers, which will make this bookkeeping job quite simple. (This mapping structure is much more general key/value mapping than just addresses to integers, but that’s all we need here.)

Here’s the code to accept deposits and track account balances:

pragma solidity ^0.4.19;

contract Bank {

    mapping(address => uint256) public balanceOf;   // balances, indexed by addresses

    function deposit(uint256 amount) public payable {
        require(msg.value == amount);

        balanceOf[msg.sender] += amount;     // adjust the account's balance
    }
}

Here are the new concepts in the code above:

mapping(address => uint256) public balanceOf; declares a persistent public variable, balanceOf, that is a mapping from account addresses to 256-bit unsigned integers. Those integers will represent the current balance of ether stored by the contract on behalf of the corresponding address.
Mappings can be indexed just like arrays/lists/dictionaries/tables in most modern programming languages.
The value of a missing mapping value is 0. Therefore, we can trust that the beginning balance for all account addresses will effectively be zero prior to the first deposit.

It’s important to note that balanceOf keeps track of the ether balances assigned to each account, but it does not actually move any ether anywhere. The bank contract’s ether balance is the sum of all the balances of all accounts—only balanceOf tracks how much of that is assigned to each account.

Note also that this contract doesn’t need a constructor. There is no persistent state to initialize other than the balanceOf mapping, which already provides default values of 0.

Withdrawals and Account Balances

Given the balanceOf mapping from account addresses to ether amounts, the remaining code for a fully-functional bank contract is pretty small. I’ll simply add a withdrawal function:

bank.sol

pragma solidity ^0.4.19;

contract Bank {

    mapping(address => uint256) public balanceOf;   // balances, indexed by addresses

    function deposit(uint256 amount) public payable {
        require(msg.value == amount);
        balanceOf[msg.sender] += amount;     // adjust the account's balance
    }

    function withdraw(uint256 amount) public {
        require(amount <= balanceOf[msg.sender]);
        balanceOf[msg.sender] -= amount;
        msg.sender.transfer(amount);
    }
}

The code above demonstrates the following:

The require(amount <= balances[msg.sender]) checks to make sure the sender has sufficient funds to cover the requested withdrawal. If not, then the transaction aborts without making any state changes or ether transfers.
The balanceOf mapping must be updated to reflect the lowered residual amount after the withdrawal.
The funds must be sent to the sender requesting the withdrawal.

Important: Avoiding the Reentrancy Vulnerability

In the withdraw() function above, it is very important to adjust balanceOf[msg.sender] before transferring ether to avoid an exploitable vulnerability. The reason is specific to smart contracts and the fact that a transfer to a smart contract executes code in that smart contract. (The essentials of Ethereum transactions are discussed in How Ethereum Transactions Work.)

Now, suppose that the code in withdraw() did not adjust balanceOf[msg.sender] before making the transfer and suppose that msg.sender was a malicious smart contract. Upon receiving the transfer—handled by msg.sender’s fallback function—that malicious contract could initiate another withdrawal from the banking contract. When the banking contract handles this second withdrawal request, it would have already transferred ether for the original withdrawal, but it would not have an updated balance, so it would allow this second withdrawal!

This vulnerability is called a “reentrancy” bug because it happens when a smart contract invokes code in a different smart contract that then calls back into the original, thereby reentering the exploitable contract. For this reason, it’s essential to always make sure a contract’s internal state is fully updated before it potentially invokes code in another smart contract. (And, it’s essential to remember that every transfer to a smart contract executes that contract’s code.)

To avoid this sort of reentrancy bug, follow the “Checks-Effects-Interactions pattern” as described in the Solidity documentation. The withdraw() function above is an example of implementing this pattern.¹

Summary

Solidity supports a key/value data type called mapping. The default value associated with a missing key is 0.
A mapping(address => unint256) enables straightforward accounting of per-account ether balances.

Resources

Much more detailed explanations of the reentrancy vulnerability can be found here, here, and here.

Note that transfer and send themselves also mitigate this vulnerability. They forward very little gas to the recipient—so little that a reentrant call is not possible. Nonetheless, we recommend that you follow the Checks-Effects-Interactions pattern as a matter of habit, because other types of interactions do not share this mitigation. ↩

Program the Blockchain

Introduction to Ethereum Payment Channels Video

Implementing Harberger Tax Deeds

Deed Tokens

Accounting for Harberger Taxes

Maintaining an Ether Balance

Foreclosure

Collecting Taxes

Buying a Token

Changing the Price

Withdrawing Ether

Changing the Tax Recipient

Summary

The Complete Contract

Writing a Dollar Auction Contract

Auction State

Ether Balances

Bidding

Claiming Tokens

Summary

The Complete Contract

Writing a Penny Auction Contract

Auction State

Ether Balances

Bidding

Claiming Tokens

Summary

The Complete Contract

Contracts Calling Arbitrary Functions

High-Level Function Call Syntax

The Low-Level call() Function

Using call() to Execute Arbitrary Function Calls

Summary

Full Source Code

Anatomy of Transaction Data

Smart Contracts Use Message Passing

Function Selectors

Argument Encoding

Putting It All Together

Using web3.js to Encode Transaction Data

Summary

State Channels with Signing Keys

Signing Key

Contract Changes

Signing Keys in JavaScript

Signing and Verifying Messages in JavaScript

Security Trade-Off

Summary

Full Source Code

Writing a Trivial Multisig Wallet

Immutable List of Owners

Off-Chain Consensus

Summary

The Complete Contract

Performing Multiple Actions Transactionally

Example: Arbitrage

The Complete Contract

Ensuring the Effects of a Transaction

The Challenge

An Example

Simple Pattern

The Complete Contract

Working with State Channels in JavaScript

Overview

Technology Used

Starting a New Game

Joining an Existing Game

Tracking Smart Contract State

Tracking Off-Chain State

Making Moves

Dealing with Timeouts

Canceling a Game

Full Source Code

Future Work

Supporting an Off-Chain Market Maker

Why Not Just Use the Clearinghouse Contract?

Executing Trades

Buying Bundles

Refunding Bundles

Summary

The Low-Level `call()` Function

Using `call()` to Execute Arbitrary Function Calls