2015-12-07 20:16:25 +00:00
|
|
|
###################
|
|
|
|
Solidity by Example
|
|
|
|
###################
|
|
|
|
|
|
|
|
.. index:: voting, ballot
|
|
|
|
|
|
|
|
.. _voting:
|
|
|
|
|
|
|
|
******
|
|
|
|
Voting
|
|
|
|
******
|
|
|
|
|
|
|
|
The following contract is quite complex, but showcases
|
|
|
|
a lot of Solidity's features. It implements a voting
|
|
|
|
contract. Of course, the main problems of electronic
|
|
|
|
voting is how to assign voting rights to the correct
|
|
|
|
persons and how to prevent manipulation. We will not
|
2016-05-13 14:32:35 +00:00
|
|
|
solve all problems here, but at least we will show
|
2015-12-07 20:16:25 +00:00
|
|
|
how delegated voting can be done so that vote counting
|
|
|
|
is **automatic and completely transparent** at the
|
|
|
|
same time.
|
|
|
|
|
|
|
|
The idea is to create one contract per ballot,
|
|
|
|
providing a short name for each option.
|
|
|
|
Then the creator of the contract who serves as
|
|
|
|
chairperson will give the right to vote to each
|
|
|
|
address individually.
|
|
|
|
|
|
|
|
The persons behind the addresses can then choose
|
|
|
|
to either vote themselves or to delegate their
|
|
|
|
vote to a person they trust.
|
|
|
|
|
2016-05-24 17:57:36 +00:00
|
|
|
At the end of the voting time, ``winningProposal()``
|
2015-12-07 20:16:25 +00:00
|
|
|
will return the proposal with the largest number
|
|
|
|
of votes.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-04-15 21:12:28 +00:00
|
|
|
pragma solidity ^0.4.22;
|
2016-09-05 11:54:54 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
/// @title Voting with delegation.
|
2016-05-05 19:31:00 +00:00
|
|
|
contract Ballot {
|
2015-12-07 20:16:25 +00:00
|
|
|
// This declares a new complex type which will
|
|
|
|
// be used for variables later.
|
|
|
|
// It will represent a single voter.
|
2016-05-05 19:31:00 +00:00
|
|
|
struct Voter {
|
2015-12-07 20:16:25 +00:00
|
|
|
uint weight; // weight is accumulated by delegation
|
|
|
|
bool voted; // if true, that person already voted
|
|
|
|
address delegate; // person delegated to
|
|
|
|
uint vote; // index of the voted proposal
|
|
|
|
}
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
// This is a type for a single proposal.
|
2017-04-15 01:05:53 +00:00
|
|
|
struct Proposal {
|
2015-12-07 20:16:25 +00:00
|
|
|
bytes32 name; // short name (up to 32 bytes)
|
|
|
|
uint voteCount; // number of accumulated votes
|
|
|
|
}
|
|
|
|
|
|
|
|
address public chairperson;
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
// This declares a state variable that
|
|
|
|
// stores a `Voter` struct for each possible address.
|
|
|
|
mapping(address => Voter) public voters;
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
// A dynamically-sized array of `Proposal` structs.
|
|
|
|
Proposal[] public proposals;
|
|
|
|
|
|
|
|
/// Create a new ballot to choose one of `proposalNames`.
|
2018-07-14 21:42:01 +00:00
|
|
|
constructor(bytes32[] memory proposalNames) public {
|
2015-12-07 20:16:25 +00:00
|
|
|
chairperson = msg.sender;
|
|
|
|
voters[chairperson].weight = 1;
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
// For each of the provided proposal names,
|
|
|
|
// create a new proposal object and add it
|
|
|
|
// to the end of the array.
|
2016-05-05 19:31:00 +00:00
|
|
|
for (uint i = 0; i < proposalNames.length; i++) {
|
2015-12-07 20:16:25 +00:00
|
|
|
// `Proposal({...})` creates a temporary
|
2016-05-26 12:43:00 +00:00
|
|
|
// Proposal object and `proposals.push(...)`
|
2015-12-07 20:16:25 +00:00
|
|
|
// appends it to the end of `proposals`.
|
|
|
|
proposals.push(Proposal({
|
|
|
|
name: proposalNames[i],
|
|
|
|
voteCount: 0
|
|
|
|
}));
|
2016-05-05 19:31:00 +00:00
|
|
|
}
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// Give `voter` the right to vote on this ballot.
|
|
|
|
// May only be called by `chairperson`.
|
2017-12-12 18:47:30 +00:00
|
|
|
function giveRightToVote(address voter) public {
|
2018-01-03 14:30:01 +00:00
|
|
|
// If the first argument of `require` evaluates
|
|
|
|
// to `false`, execution terminates and all
|
|
|
|
// changes to the state and to Ether balances
|
|
|
|
// are reverted.
|
|
|
|
// This used to consume all gas in old EVM versions, but
|
|
|
|
// not anymore.
|
|
|
|
// It is often a good idea to use `require` to check if
|
|
|
|
// functions are called correctly.
|
|
|
|
// As a second argument, you can also provide an
|
|
|
|
// explanation about what went wrong.
|
2018-02-19 15:58:56 +00:00
|
|
|
require(
|
2018-01-03 14:30:01 +00:00
|
|
|
msg.sender == chairperson,
|
|
|
|
"Only chairperson can give right to vote."
|
2018-02-19 15:58:56 +00:00
|
|
|
);
|
2018-01-03 14:30:01 +00:00
|
|
|
require(
|
|
|
|
!voters[voter].voted,
|
|
|
|
"The voter already voted."
|
|
|
|
);
|
|
|
|
require(voters[voter].weight == 0);
|
2015-12-07 20:16:25 +00:00
|
|
|
voters[voter].weight = 1;
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Delegate your vote to the voter `to`.
|
2017-12-12 18:47:30 +00:00
|
|
|
function delegate(address to) public {
|
2015-12-07 20:16:25 +00:00
|
|
|
// assigns reference
|
2017-07-26 13:47:03 +00:00
|
|
|
Voter storage sender = voters[msg.sender];
|
2018-01-03 14:30:01 +00:00
|
|
|
require(!sender.voted, "You already voted.");
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2018-01-03 14:30:01 +00:00
|
|
|
require(to != msg.sender, "Self-delegation is disallowed.");
|
2017-03-08 21:45:27 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
// Forward the delegation as long as
|
|
|
|
// `to` also delegated.
|
2016-05-31 11:56:05 +00:00
|
|
|
// In general, such loops are very dangerous,
|
|
|
|
// because if they run too long, they might
|
2016-06-08 22:36:31 +00:00
|
|
|
// need more gas than is available in a block.
|
2016-05-31 11:56:05 +00:00
|
|
|
// In this case, the delegation will not be executed,
|
|
|
|
// but in other situations, such loops might
|
|
|
|
// cause a contract to get "stuck" completely.
|
2017-03-08 21:45:27 +00:00
|
|
|
while (voters[to].delegate != address(0)) {
|
2016-06-01 21:40:38 +00:00
|
|
|
to = voters[to].delegate;
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2017-03-08 21:45:27 +00:00
|
|
|
// We found a loop in the delegation, not allowed.
|
2018-01-03 14:30:01 +00:00
|
|
|
require(to != msg.sender, "Found loop in delegation.");
|
2016-05-05 19:31:00 +00:00
|
|
|
}
|
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
// Since `sender` is a reference, this
|
|
|
|
// modifies `voters[msg.sender].voted`
|
|
|
|
sender.voted = true;
|
|
|
|
sender.delegate = to;
|
2018-02-19 15:58:56 +00:00
|
|
|
Voter storage delegate_ = voters[to];
|
|
|
|
if (delegate_.voted) {
|
2015-12-07 20:16:25 +00:00
|
|
|
// If the delegate already voted,
|
2016-05-13 14:32:35 +00:00
|
|
|
// directly add to the number of votes
|
2018-02-19 15:58:56 +00:00
|
|
|
proposals[delegate_.vote].voteCount += sender.weight;
|
2016-08-24 19:28:07 +00:00
|
|
|
} else {
|
2015-12-07 20:16:25 +00:00
|
|
|
// If the delegate did not vote yet,
|
|
|
|
// add to her weight.
|
2018-02-19 15:58:56 +00:00
|
|
|
delegate_.weight += sender.weight;
|
2016-05-05 19:31:00 +00:00
|
|
|
}
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
/// Give your vote (including votes delegated to you)
|
|
|
|
/// to proposal `proposals[proposal].name`.
|
2017-12-12 18:47:30 +00:00
|
|
|
function vote(uint proposal) public {
|
2017-07-26 13:47:03 +00:00
|
|
|
Voter storage sender = voters[msg.sender];
|
2018-01-03 14:30:01 +00:00
|
|
|
require(!sender.voted, "Already voted.");
|
2015-12-07 20:16:25 +00:00
|
|
|
sender.voted = true;
|
|
|
|
sender.vote = proposal;
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
// If `proposal` is out of the range of the array,
|
|
|
|
// this will throw automatically and revert all
|
|
|
|
// changes.
|
|
|
|
proposals[proposal].voteCount += sender.weight;
|
|
|
|
}
|
|
|
|
|
|
|
|
/// @dev Computes the winning proposal taking all
|
|
|
|
/// previous votes into account.
|
2017-12-12 18:47:30 +00:00
|
|
|
function winningProposal() public view
|
2018-02-19 15:58:56 +00:00
|
|
|
returns (uint winningProposal_)
|
2015-12-07 20:16:25 +00:00
|
|
|
{
|
|
|
|
uint winningVoteCount = 0;
|
2017-12-13 07:55:46 +00:00
|
|
|
for (uint p = 0; p < proposals.length; p++) {
|
|
|
|
if (proposals[p].voteCount > winningVoteCount) {
|
|
|
|
winningVoteCount = proposals[p].voteCount;
|
2018-02-19 15:58:56 +00:00
|
|
|
winningProposal_ = p;
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
2017-06-21 03:48:49 +00:00
|
|
|
|
2016-11-03 16:55:19 +00:00
|
|
|
// Calls winningProposal() function to get the index
|
|
|
|
// of the winner contained in the proposals array and then
|
|
|
|
// returns the name of the winner
|
2017-12-12 18:47:30 +00:00
|
|
|
function winnerName() public view
|
2018-02-19 15:58:56 +00:00
|
|
|
returns (bytes32 winnerName_)
|
2016-11-03 07:32:25 +00:00
|
|
|
{
|
2018-02-19 15:58:56 +00:00
|
|
|
winnerName_ = proposals[winningProposal()].name;
|
2016-11-03 07:32:25 +00:00
|
|
|
}
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
|
2018-02-19 15:58:56 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
Possible Improvements
|
|
|
|
=====================
|
|
|
|
|
|
|
|
Currently, many transactions are needed to assign the rights
|
|
|
|
to vote to all participants. Can you think of a better way?
|
|
|
|
|
|
|
|
.. index:: auction;blind, auction;open, blind auction, open auction
|
|
|
|
|
|
|
|
*************
|
|
|
|
Blind Auction
|
|
|
|
*************
|
|
|
|
|
|
|
|
In this section, we will show how easy it is to create a
|
|
|
|
completely blind auction contract on Ethereum.
|
|
|
|
We will start with an open auction where everyone
|
|
|
|
can see the bids that are made and then extend this
|
|
|
|
contract into a blind auction where it is not
|
|
|
|
possible to see the actual bid until the bidding
|
|
|
|
period ends.
|
|
|
|
|
2016-07-08 16:21:57 +00:00
|
|
|
.. _simple_auction:
|
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
Simple Open Auction
|
|
|
|
===================
|
|
|
|
|
|
|
|
The general idea of the following simple auction contract
|
|
|
|
is that everyone can send their bids during
|
|
|
|
a bidding period. The bids already include sending
|
|
|
|
money / ether in order to bind the bidders to their
|
|
|
|
bid. If the highest bid is raised, the previously
|
|
|
|
highest bidder gets her money back.
|
|
|
|
After the end of the bidding period, the
|
|
|
|
contract has to be called manually for the
|
|
|
|
beneficiary to receive his money - contracts cannot
|
|
|
|
activate themselves.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-04-15 21:12:28 +00:00
|
|
|
pragma solidity ^0.4.22;
|
2016-09-05 11:54:54 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
contract SimpleAuction {
|
|
|
|
// Parameters of the auction. Times are either
|
|
|
|
// absolute unix timestamps (seconds since 1970-01-01)
|
2016-04-12 01:08:29 +00:00
|
|
|
// or time periods in seconds.
|
2015-12-07 20:16:25 +00:00
|
|
|
address public beneficiary;
|
2018-07-13 12:12:06 +00:00
|
|
|
uint public auctionEndTime;
|
2015-12-07 20:16:25 +00:00
|
|
|
|
|
|
|
// Current state of the auction.
|
|
|
|
address public highestBidder;
|
|
|
|
uint public highestBid;
|
|
|
|
|
2016-05-31 11:56:05 +00:00
|
|
|
// Allowed withdrawals of previous bids
|
|
|
|
mapping(address => uint) pendingReturns;
|
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
// Set to true at the end, disallows any change
|
|
|
|
bool ended;
|
|
|
|
|
|
|
|
// Events that will be fired on changes.
|
|
|
|
event HighestBidIncreased(address bidder, uint amount);
|
|
|
|
event AuctionEnded(address winner, uint amount);
|
|
|
|
|
|
|
|
// The following is a so-called natspec comment,
|
|
|
|
// recognizable by the three slashes.
|
|
|
|
// It will be shown when the user is asked to
|
|
|
|
// confirm a transaction.
|
|
|
|
|
|
|
|
/// Create a simple auction with `_biddingTime`
|
|
|
|
/// seconds bidding time on behalf of the
|
|
|
|
/// beneficiary address `_beneficiary`.
|
2018-04-30 14:21:36 +00:00
|
|
|
constructor(
|
2016-05-05 19:31:00 +00:00
|
|
|
uint _biddingTime,
|
|
|
|
address _beneficiary
|
2017-12-12 18:47:30 +00:00
|
|
|
) public {
|
2015-12-07 20:16:25 +00:00
|
|
|
beneficiary = _beneficiary;
|
2018-07-13 12:12:06 +00:00
|
|
|
auctionEndTime = now + _biddingTime;
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
/// Bid on the auction with the value sent
|
|
|
|
/// together with this transaction.
|
|
|
|
/// The value will only be refunded if the
|
|
|
|
/// auction is not won.
|
2017-12-12 18:47:30 +00:00
|
|
|
function bid() public payable {
|
2015-12-07 20:16:25 +00:00
|
|
|
// No arguments are necessary, all
|
|
|
|
// information is already part of
|
2016-09-05 14:29:08 +00:00
|
|
|
// the transaction. The keyword payable
|
|
|
|
// is required for the function to
|
|
|
|
// be able to receive Ether.
|
2017-04-19 18:12:45 +00:00
|
|
|
|
|
|
|
// Revert the call if the bidding
|
|
|
|
// period is over.
|
2018-01-03 14:30:01 +00:00
|
|
|
require(
|
2018-07-13 12:12:06 +00:00
|
|
|
now <= auctionEndTime,
|
2018-01-03 14:30:01 +00:00
|
|
|
"Auction already ended."
|
|
|
|
);
|
2017-04-19 18:12:45 +00:00
|
|
|
|
|
|
|
// If the bid is not higher, send the
|
|
|
|
// money back.
|
2018-01-03 14:30:01 +00:00
|
|
|
require(
|
|
|
|
msg.value > highestBid,
|
|
|
|
"There already is a higher bid."
|
|
|
|
);
|
2017-06-21 03:48:49 +00:00
|
|
|
|
2018-02-21 17:42:57 +00:00
|
|
|
if (highestBid != 0) {
|
2016-05-31 11:56:05 +00:00
|
|
|
// Sending back the money by simply using
|
|
|
|
// highestBidder.send(highestBid) is a security risk
|
2017-08-04 12:08:37 +00:00
|
|
|
// because it could execute an untrusted contract.
|
|
|
|
// It is always safer to let the recipients
|
|
|
|
// withdraw their money themselves.
|
2016-05-31 11:56:05 +00:00
|
|
|
pendingReturns[highestBidder] += highestBid;
|
2016-05-05 19:31:00 +00:00
|
|
|
}
|
2015-12-07 20:16:25 +00:00
|
|
|
highestBidder = msg.sender;
|
|
|
|
highestBid = msg.value;
|
2018-02-16 16:32:30 +00:00
|
|
|
emit HighestBidIncreased(msg.sender, msg.value);
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
|
2016-05-31 11:56:05 +00:00
|
|
|
/// Withdraw a bid that was overbid.
|
2017-12-12 18:47:30 +00:00
|
|
|
function withdraw() public returns (bool) {
|
2017-07-26 13:46:13 +00:00
|
|
|
uint amount = pendingReturns[msg.sender];
|
2016-06-18 01:29:54 +00:00
|
|
|
if (amount > 0) {
|
|
|
|
// It is important to set this to zero because the recipient
|
|
|
|
// can call this function again as part of the receiving call
|
|
|
|
// before `send` returns.
|
|
|
|
pendingReturns[msg.sender] = 0;
|
|
|
|
|
2017-06-21 03:48:49 +00:00
|
|
|
if (!msg.sender.send(amount)) {
|
2016-06-18 01:29:54 +00:00
|
|
|
// No need to call throw here, just reset the amount owing
|
|
|
|
pendingReturns[msg.sender] = amount;
|
|
|
|
return false;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
return true;
|
2016-05-31 11:56:05 +00:00
|
|
|
}
|
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
/// End the auction and send the highest bid
|
|
|
|
/// to the beneficiary.
|
2017-12-12 18:47:30 +00:00
|
|
|
function auctionEnd() public {
|
2016-06-28 15:29:08 +00:00
|
|
|
// It is a good guideline to structure functions that interact
|
|
|
|
// with other contracts (i.e. they call functions or send Ether)
|
|
|
|
// into three phases:
|
|
|
|
// 1. checking conditions
|
|
|
|
// 2. performing actions (potentially changing conditions)
|
|
|
|
// 3. interacting with other contracts
|
|
|
|
// If these phases are mixed up, the other contract could call
|
|
|
|
// back into the current contract and modify the state or cause
|
2017-05-25 21:17:47 +00:00
|
|
|
// effects (ether payout) to be performed multiple times.
|
2016-06-28 15:29:08 +00:00
|
|
|
// If functions called internally include interaction with external
|
|
|
|
// contracts, they also have to be considered interaction with
|
|
|
|
// external contracts.
|
|
|
|
|
|
|
|
// 1. Conditions
|
2018-07-13 12:12:06 +00:00
|
|
|
require(now >= auctionEndTime, "Auction not yet ended.");
|
2018-01-03 14:30:01 +00:00
|
|
|
require(!ended, "auctionEnd has already been called.");
|
2016-06-28 15:29:08 +00:00
|
|
|
|
|
|
|
// 2. Effects
|
|
|
|
ended = true;
|
2018-02-16 16:32:30 +00:00
|
|
|
emit AuctionEnded(highestBidder, highestBid);
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2016-06-28 15:29:08 +00:00
|
|
|
// 3. Interaction
|
2017-05-02 12:12:25 +00:00
|
|
|
beneficiary.transfer(highestBid);
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
Blind Auction
|
2016-05-18 15:05:28 +00:00
|
|
|
=============
|
2015-12-07 20:16:25 +00:00
|
|
|
|
|
|
|
The previous open auction is extended to a blind auction
|
|
|
|
in the following. The advantage of a blind auction is
|
|
|
|
that there is no time pressure towards the end of
|
|
|
|
the bidding period. Creating a blind auction on a
|
|
|
|
transparent computing platform might sound like a
|
|
|
|
contradiction, but cryptography comes to the rescue.
|
|
|
|
|
|
|
|
During the **bidding period**, a bidder does not
|
|
|
|
actually send her bid, but only a hashed version of it.
|
|
|
|
Since it is currently considered practically impossible
|
|
|
|
to find two (sufficiently long) values whose hash
|
|
|
|
values are equal, the bidder commits to the bid by that.
|
|
|
|
After the end of the bidding period, the bidders have
|
|
|
|
to reveal their bids: They send their values
|
|
|
|
unencrypted and the contract checks that the hash value
|
|
|
|
is the same as the one provided during the bidding period.
|
|
|
|
|
|
|
|
Another challenge is how to make the auction
|
|
|
|
**binding and blind** at the same time: The only way to
|
|
|
|
prevent the bidder from just not sending the money
|
|
|
|
after he won the auction is to make her send it
|
|
|
|
together with the bid. Since value transfers cannot
|
|
|
|
be blinded in Ethereum, anyone can see the value.
|
|
|
|
|
|
|
|
The following contract solves this problem by
|
2017-07-17 09:58:41 +00:00
|
|
|
accepting any value that is larger than the highest
|
|
|
|
bid. Since this can of course only be checked during
|
2015-12-07 20:16:25 +00:00
|
|
|
the reveal phase, some bids might be **invalid**, and
|
|
|
|
this is on purpose (it even provides an explicit
|
|
|
|
flag to place invalid bids with high value transfers):
|
|
|
|
Bidders can confuse competition by placing several
|
|
|
|
high or low invalid bids.
|
|
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-04-30 11:30:09 +00:00
|
|
|
pragma solidity >0.4.23 <0.5.0;
|
2016-09-05 11:54:54 +00:00
|
|
|
|
2016-05-05 19:31:00 +00:00
|
|
|
contract BlindAuction {
|
|
|
|
struct Bid {
|
2015-12-07 20:16:25 +00:00
|
|
|
bytes32 blindedBid;
|
|
|
|
uint deposit;
|
|
|
|
}
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
address public beneficiary;
|
|
|
|
uint public biddingEnd;
|
|
|
|
uint public revealEnd;
|
|
|
|
bool public ended;
|
|
|
|
|
|
|
|
mapping(address => Bid[]) public bids;
|
|
|
|
|
|
|
|
address public highestBidder;
|
|
|
|
uint public highestBid;
|
|
|
|
|
2016-05-31 11:56:05 +00:00
|
|
|
// Allowed withdrawals of previous bids
|
|
|
|
mapping(address => uint) pendingReturns;
|
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
event AuctionEnded(address winner, uint highestBid);
|
|
|
|
|
|
|
|
/// Modifiers are a convenient way to validate inputs to
|
|
|
|
/// functions. `onlyBefore` is applied to `bid` below:
|
|
|
|
/// The new function body is the modifier's body where
|
|
|
|
/// `_` is replaced by the old function body.
|
2017-05-02 12:12:25 +00:00
|
|
|
modifier onlyBefore(uint _time) { require(now < _time); _; }
|
|
|
|
modifier onlyAfter(uint _time) { require(now > _time); _; }
|
2015-12-07 20:16:25 +00:00
|
|
|
|
2018-04-30 14:21:36 +00:00
|
|
|
constructor(
|
2016-05-05 19:31:00 +00:00
|
|
|
uint _biddingTime,
|
|
|
|
uint _revealTime,
|
|
|
|
address _beneficiary
|
2017-12-12 18:47:30 +00:00
|
|
|
) public {
|
2015-12-07 20:16:25 +00:00
|
|
|
beneficiary = _beneficiary;
|
|
|
|
biddingEnd = now + _biddingTime;
|
|
|
|
revealEnd = biddingEnd + _revealTime;
|
|
|
|
}
|
|
|
|
|
2018-06-13 15:49:41 +00:00
|
|
|
/// Place a blinded bid with `_blindedBid` =
|
|
|
|
/// keccak256(abi.encodePacked(value, fake, secret)).
|
2015-12-07 20:16:25 +00:00
|
|
|
/// The sent ether is only refunded if the bid is correctly
|
|
|
|
/// revealed in the revealing phase. The bid is valid if the
|
|
|
|
/// ether sent together with the bid is at least "value" and
|
|
|
|
/// "fake" is not true. Setting "fake" to true and sending
|
|
|
|
/// not the exact amount are ways to hide the real bid but
|
|
|
|
/// still make the required deposit. The same address can
|
|
|
|
/// place multiple bids.
|
|
|
|
function bid(bytes32 _blindedBid)
|
2017-12-12 18:47:30 +00:00
|
|
|
public
|
2016-09-05 14:29:08 +00:00
|
|
|
payable
|
2015-12-07 20:16:25 +00:00
|
|
|
onlyBefore(biddingEnd)
|
|
|
|
{
|
|
|
|
bids[msg.sender].push(Bid({
|
|
|
|
blindedBid: _blindedBid,
|
|
|
|
deposit: msg.value
|
|
|
|
}));
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Reveal your blinded bids. You will get a refund for all
|
|
|
|
/// correctly blinded invalid bids and for all bids except for
|
|
|
|
/// the totally highest.
|
2016-05-05 19:31:00 +00:00
|
|
|
function reveal(
|
2018-07-14 21:42:01 +00:00
|
|
|
uint[] memory _values,
|
|
|
|
bool[] memory _fake,
|
|
|
|
bytes32[] memory _secret
|
2016-05-05 19:31:00 +00:00
|
|
|
)
|
2017-12-12 18:47:30 +00:00
|
|
|
public
|
2015-12-07 20:16:25 +00:00
|
|
|
onlyAfter(biddingEnd)
|
|
|
|
onlyBefore(revealEnd)
|
|
|
|
{
|
|
|
|
uint length = bids[msg.sender].length;
|
2017-05-02 15:33:46 +00:00
|
|
|
require(_values.length == length);
|
|
|
|
require(_fake.length == length);
|
|
|
|
require(_secret.length == length);
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
uint refund;
|
2016-05-05 19:31:00 +00:00
|
|
|
for (uint i = 0; i < length; i++) {
|
2018-08-09 13:36:00 +00:00
|
|
|
Bid storage bidToCheck = bids[msg.sender][i];
|
2018-04-30 11:30:09 +00:00
|
|
|
(uint value, bool fake, bytes32 secret) =
|
2015-12-07 20:16:25 +00:00
|
|
|
(_values[i], _fake[i], _secret[i]);
|
2018-08-09 13:36:00 +00:00
|
|
|
if (bidToCheck.blindedBid != keccak256(abi.encodePacked(value, fake, secret))) {
|
2015-12-07 20:16:25 +00:00
|
|
|
// Bid was not actually revealed.
|
|
|
|
// Do not refund deposit.
|
|
|
|
continue;
|
2016-05-05 19:31:00 +00:00
|
|
|
}
|
2018-08-09 13:36:00 +00:00
|
|
|
refund += bidToCheck.deposit;
|
|
|
|
if (!fake && bidToCheck.deposit >= value) {
|
2015-12-07 20:16:25 +00:00
|
|
|
if (placeBid(msg.sender, value))
|
|
|
|
refund -= value;
|
2016-05-05 19:31:00 +00:00
|
|
|
}
|
2015-12-07 20:16:25 +00:00
|
|
|
// Make it impossible for the sender to re-claim
|
|
|
|
// the same deposit.
|
2018-08-09 13:36:00 +00:00
|
|
|
bidToCheck.blindedBid = bytes32(0);
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
2017-04-19 18:12:45 +00:00
|
|
|
msg.sender.transfer(refund);
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// This is an "internal" function which means that it
|
|
|
|
// can only be called from the contract itself (or from
|
|
|
|
// derived contracts).
|
|
|
|
function placeBid(address bidder, uint value) internal
|
|
|
|
returns (bool success)
|
|
|
|
{
|
2016-05-05 19:31:00 +00:00
|
|
|
if (value <= highestBid) {
|
2015-12-07 20:16:25 +00:00
|
|
|
return false;
|
2016-05-05 19:31:00 +00:00
|
|
|
}
|
2018-06-12 23:59:23 +00:00
|
|
|
if (highestBidder != address(0)) {
|
2015-12-07 20:16:25 +00:00
|
|
|
// Refund the previously highest bidder.
|
2016-05-31 11:56:05 +00:00
|
|
|
pendingReturns[highestBidder] += highestBid;
|
2016-05-05 19:31:00 +00:00
|
|
|
}
|
2015-12-07 20:16:25 +00:00
|
|
|
highestBid = value;
|
|
|
|
highestBidder = bidder;
|
|
|
|
return true;
|
|
|
|
}
|
|
|
|
|
2016-05-31 11:56:05 +00:00
|
|
|
/// Withdraw a bid that was overbid.
|
2017-12-12 18:47:30 +00:00
|
|
|
function withdraw() public {
|
2017-07-26 13:46:13 +00:00
|
|
|
uint amount = pendingReturns[msg.sender];
|
2016-06-18 01:29:54 +00:00
|
|
|
if (amount > 0) {
|
|
|
|
// It is important to set this to zero because the recipient
|
|
|
|
// can call this function again as part of the receiving call
|
2017-11-23 17:43:19 +00:00
|
|
|
// before `transfer` returns (see the remark above about
|
2016-06-18 01:29:54 +00:00
|
|
|
// conditions -> effects -> interaction).
|
|
|
|
pendingReturns[msg.sender] = 0;
|
|
|
|
|
2017-07-26 13:47:15 +00:00
|
|
|
msg.sender.transfer(amount);
|
2016-06-18 01:29:54 +00:00
|
|
|
}
|
2016-05-31 11:56:05 +00:00
|
|
|
}
|
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
/// End the auction and send the highest bid
|
|
|
|
/// to the beneficiary.
|
|
|
|
function auctionEnd()
|
2017-12-12 18:47:30 +00:00
|
|
|
public
|
2015-12-07 20:16:25 +00:00
|
|
|
onlyAfter(revealEnd)
|
|
|
|
{
|
2017-04-19 18:12:45 +00:00
|
|
|
require(!ended);
|
2018-02-16 16:32:30 +00:00
|
|
|
emit AuctionEnded(highestBidder, highestBid);
|
2016-06-28 15:29:08 +00:00
|
|
|
ended = true;
|
2017-11-23 17:43:19 +00:00
|
|
|
beneficiary.transfer(highestBid);
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2017-11-23 17:43:19 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
.. index:: purchase, remote purchase, escrow
|
|
|
|
|
|
|
|
********************
|
|
|
|
Safe Remote Purchase
|
|
|
|
********************
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-04-15 21:12:28 +00:00
|
|
|
pragma solidity ^0.4.22;
|
2016-09-05 11:54:54 +00:00
|
|
|
|
2016-05-05 19:31:00 +00:00
|
|
|
contract Purchase {
|
2015-12-07 20:16:25 +00:00
|
|
|
uint public value;
|
|
|
|
address public seller;
|
|
|
|
address public buyer;
|
|
|
|
enum State { Created, Locked, Inactive }
|
|
|
|
State public state;
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2017-08-28 11:14:41 +00:00
|
|
|
// Ensure that `msg.value` is an even number.
|
|
|
|
// Division will truncate if it is an odd number.
|
|
|
|
// Check via multiplication that it wasn't an odd number.
|
2018-04-30 14:21:36 +00:00
|
|
|
constructor() public payable {
|
2015-12-07 20:16:25 +00:00
|
|
|
seller = msg.sender;
|
|
|
|
value = msg.value / 2;
|
2018-01-03 14:30:01 +00:00
|
|
|
require((2 * value) == msg.value, "Value has to be even.");
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2017-05-02 12:12:25 +00:00
|
|
|
modifier condition(bool _condition) {
|
2017-04-19 18:12:45 +00:00
|
|
|
require(_condition);
|
2016-09-05 14:29:08 +00:00
|
|
|
_;
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
2016-05-05 19:31:00 +00:00
|
|
|
|
|
|
|
modifier onlyBuyer() {
|
2018-01-03 14:30:01 +00:00
|
|
|
require(
|
|
|
|
msg.sender == buyer,
|
|
|
|
"Only buyer can call this."
|
|
|
|
);
|
2016-09-05 14:29:08 +00:00
|
|
|
_;
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
2016-05-05 19:31:00 +00:00
|
|
|
|
|
|
|
modifier onlySeller() {
|
2018-01-03 14:30:01 +00:00
|
|
|
require(
|
|
|
|
msg.sender == seller,
|
|
|
|
"Only seller can call this."
|
|
|
|
);
|
2016-09-05 14:29:08 +00:00
|
|
|
_;
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
2016-05-05 19:31:00 +00:00
|
|
|
|
|
|
|
modifier inState(State _state) {
|
2018-01-03 14:30:01 +00:00
|
|
|
require(
|
|
|
|
state == _state,
|
|
|
|
"Invalid state."
|
|
|
|
);
|
2016-09-05 14:29:08 +00:00
|
|
|
_;
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2017-05-25 16:41:40 +00:00
|
|
|
event Aborted();
|
|
|
|
event PurchaseConfirmed();
|
|
|
|
event ItemReceived();
|
2015-12-07 20:16:25 +00:00
|
|
|
|
|
|
|
/// Abort the purchase and reclaim the ether.
|
|
|
|
/// Can only be called by the seller before
|
|
|
|
/// the contract is locked.
|
|
|
|
function abort()
|
2017-12-12 18:47:30 +00:00
|
|
|
public
|
2015-12-07 20:16:25 +00:00
|
|
|
onlySeller
|
|
|
|
inState(State.Created)
|
|
|
|
{
|
2018-02-16 16:32:30 +00:00
|
|
|
emit Aborted();
|
2015-12-07 20:16:25 +00:00
|
|
|
state = State.Inactive;
|
2018-04-30 14:21:36 +00:00
|
|
|
seller.transfer(address(this).balance);
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
/// Confirm the purchase as buyer.
|
|
|
|
/// Transaction has to include `2 * value` ether.
|
|
|
|
/// The ether will be locked until confirmReceived
|
|
|
|
/// is called.
|
|
|
|
function confirmPurchase()
|
2017-12-12 18:47:30 +00:00
|
|
|
public
|
2015-12-07 20:16:25 +00:00
|
|
|
inState(State.Created)
|
2017-05-03 10:02:46 +00:00
|
|
|
condition(msg.value == (2 * value))
|
2016-09-05 14:29:08 +00:00
|
|
|
payable
|
2015-12-07 20:16:25 +00:00
|
|
|
{
|
2018-02-16 16:32:30 +00:00
|
|
|
emit PurchaseConfirmed();
|
2015-12-07 20:16:25 +00:00
|
|
|
buyer = msg.sender;
|
|
|
|
state = State.Locked;
|
|
|
|
}
|
2016-05-05 19:31:00 +00:00
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
/// Confirm that you (the buyer) received the item.
|
|
|
|
/// This will release the locked ether.
|
|
|
|
function confirmReceived()
|
2017-12-12 18:47:30 +00:00
|
|
|
public
|
2015-12-07 20:16:25 +00:00
|
|
|
onlyBuyer
|
|
|
|
inState(State.Locked)
|
|
|
|
{
|
2018-02-16 16:32:30 +00:00
|
|
|
emit ItemReceived();
|
2016-05-31 11:56:05 +00:00
|
|
|
// It is important to change the state first because
|
|
|
|
// otherwise, the contracts called using `send` below
|
|
|
|
// can call in again here.
|
2015-12-07 20:16:25 +00:00
|
|
|
state = State.Inactive;
|
2017-05-02 15:33:46 +00:00
|
|
|
|
|
|
|
// NOTE: This actually allows both the buyer and the seller to
|
2017-05-02 12:12:25 +00:00
|
|
|
// block the refund - the withdraw pattern should be used.
|
2017-05-02 15:33:46 +00:00
|
|
|
|
2017-05-02 12:12:25 +00:00
|
|
|
buyer.transfer(value);
|
2018-04-30 14:21:36 +00:00
|
|
|
seller.transfer(address(this).balance);
|
2015-12-07 20:16:25 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
********************
|
|
|
|
Micropayment Channel
|
|
|
|
********************
|
|
|
|
|
2018-06-07 19:37:14 +00:00
|
|
|
In this section we will learn how to build a simple implementation
|
|
|
|
of a payment channel. It use cryptographics signatures to make
|
2018-07-09 22:45:00 +00:00
|
|
|
repeated transfers of Ether between the same parties secure, instantaneous, and
|
2018-06-07 19:37:14 +00:00
|
|
|
without transaction fees. To do it we need to understand how to
|
|
|
|
sign and verify signatures, and setup the payment channel.
|
|
|
|
|
2018-05-31 09:20:14 +00:00
|
|
|
Creating and verifying signatures
|
|
|
|
=================================
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Imagine Alice wants to send a quantity of Ether to Bob, i.e.
|
2018-06-07 19:37:14 +00:00
|
|
|
Alice is the sender and the Bob is the recipient.
|
2018-07-09 22:45:00 +00:00
|
|
|
Alice only needs to send cryptographically signed messages off-chain
|
|
|
|
(e.g. via email) to Bob and it will be very similar to writing checks.
|
|
|
|
|
2018-05-31 14:03:42 +00:00
|
|
|
Signatures are used to authorize transactions,
|
2018-06-07 19:37:14 +00:00
|
|
|
and they are a general tool that is available to
|
|
|
|
smart contracts. Alice will build a simple
|
|
|
|
smart contract that lets her transmit Ether, but
|
|
|
|
in a unusual way, instead of calling a function herself
|
|
|
|
to initiate a payment, she will let Bob
|
2018-07-09 22:45:00 +00:00
|
|
|
do that, and therefore pay the transaction fee.
|
|
|
|
The contract will work as follows:
|
2018-06-07 19:37:14 +00:00
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
1. Alice deploys the ``ReceiverPays`` contract, attaching enough Ether to cover the payments that will be made.
|
|
|
|
2. Alice authorizes a payment by signing a message with their private key.
|
|
|
|
3. Alice sends the cryptographically signed message to Bob. The message does not need to be kept secret
|
|
|
|
(you will understand it later), and the mechanism for sending it does not matter.
|
|
|
|
4. Bob claims their payment by presenting the signed message to the smart contract, it verifies the
|
|
|
|
authenticity of the message and then releases the funds.
|
2018-05-31 14:03:42 +00:00
|
|
|
|
2018-05-31 09:20:14 +00:00
|
|
|
Creating the signature
|
|
|
|
----------------------
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Alice does not need to interact with Ethereum network to
|
2018-07-10 07:17:33 +00:00
|
|
|
sign the transaction, the process is completely offline.
|
2018-07-09 22:45:00 +00:00
|
|
|
In this tutorial, we will sign messages in the browser
|
|
|
|
using ``web3.js`` and ``MetaMask``.
|
|
|
|
In particular, we will use the standard way described in `EIP-762 <https://github.com/ethereum/EIPs/pull/712>`_,
|
2018-06-07 19:37:14 +00:00
|
|
|
as it provides a number of other security benefits.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-06-03 15:31:46 +00:00
|
|
|
/// Hashing first makes a few things easier
|
2018-05-31 09:20:14 +00:00
|
|
|
var hash = web3.sha3("message to sign");
|
|
|
|
web3.personal.sign(hash, web3.eth.defaultAccount, function () {...});
|
|
|
|
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Note that the ``web3.personal.sign`` prepends the length of the message to the signed data.
|
|
|
|
Since we hash first, the message will always be exactly 32 bytes long,
|
|
|
|
and thus this length prefix is always the same, making everything easier.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
What to Sign
|
|
|
|
------------
|
|
|
|
|
|
|
|
For a contract that fulfills payments, the signed message must include:
|
|
|
|
|
|
|
|
1. The recipient's address
|
|
|
|
2. The amount to be transferred
|
2018-07-09 22:45:00 +00:00
|
|
|
3. Protection against replay attacks
|
2018-06-07 19:37:14 +00:00
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
A replay attack is when a signed message is reused to claim authorization for
|
2018-06-07 19:37:14 +00:00
|
|
|
a second action.
|
|
|
|
To avoid replay attacks we will use the same as in Ethereum transactions
|
2018-07-09 22:45:00 +00:00
|
|
|
themselves, a so-called nonce, which is the number of transactions sent by an
|
2018-06-07 19:37:14 +00:00
|
|
|
account.
|
2018-07-09 22:45:00 +00:00
|
|
|
The smart contract will check if a nonce is used multiple times.
|
|
|
|
|
2018-06-07 19:37:14 +00:00
|
|
|
There is another type of replay attacks, it occurs when the
|
2018-07-09 22:45:00 +00:00
|
|
|
owner deploys a ``ReceiverPays`` smart contract, performs some payments,
|
|
|
|
and then destroy the contract. Later, she decides to deploy the
|
|
|
|
``RecipientPays`` smart contract again, but the new contract does not
|
2018-05-31 14:03:42 +00:00
|
|
|
know the nonces used in the previous deployment, so the attacker
|
2018-07-09 22:45:00 +00:00
|
|
|
can use the old messages again.
|
|
|
|
|
|
|
|
Alice can protect against it including
|
|
|
|
the contract's address in the message, and only
|
|
|
|
messages containing contract's address itself will be accepted.
|
|
|
|
This functionality can be found in the first two lines of the ``claimPayment()`` function in the full contract
|
|
|
|
at the end of this chapter.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
Packing arguments
|
|
|
|
-----------------
|
|
|
|
|
2018-05-31 14:03:42 +00:00
|
|
|
Now that we have identified what information to include in the
|
2018-06-07 19:37:14 +00:00
|
|
|
signed message, we are ready to put the message together, hash it,
|
2018-07-09 22:45:00 +00:00
|
|
|
and sign it. For simplicity, we just concatenate the data.
|
|
|
|
The
|
2018-05-31 14:03:42 +00:00
|
|
|
`ethereumjs-abi <https://github.com/ethereumjs/ethereumjs-abi>`_ library provides
|
2018-07-09 22:45:00 +00:00
|
|
|
a function called ``soliditySHA3`` that mimics the behavior
|
|
|
|
of Solidity's ``keccak256`` function applied to arguments encoded
|
|
|
|
using ``abi.encodePacked``.
|
|
|
|
Putting it all together, here is a JavaScript function that
|
|
|
|
creates the proper signature for the ``ReceiverPays`` example:
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
// recipient is the address that should be paid.
|
|
|
|
// amount, in wei, specifies how much ether should be sent.
|
|
|
|
// nonce can be any unique number to prevent replay attacks
|
|
|
|
// contractAddress is used to prevent cross-contract replay attacks
|
2018-05-31 09:20:14 +00:00
|
|
|
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
|
|
|
|
-----------------------------------------
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
In general, ECDSA signatures consist of two parameters, ``r`` and ``s``.
|
|
|
|
Signatures in Ethereum include a third parameter called ``v``, that can be used
|
2018-05-31 14:03:42 +00:00
|
|
|
to recover which account's private key was used to sign in the message,
|
2018-07-09 22:45:00 +00:00
|
|
|
the transaction's sender. Solidity provides a built-in function
|
|
|
|
`ecrecover <mathematical-and-cryptographic-functions>`_
|
|
|
|
that accepts a message along with the ``r``, ``s`` and ``v`` parameters and
|
2018-05-31 14:03:42 +00:00
|
|
|
returns the address that was used to sign the message.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
Extracting the Signature Parameters
|
|
|
|
-----------------------------------
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Signatures produced by web3.js are the concatenation of ``r``, ``s`` and ``v``,
|
|
|
|
so the first step is splitting those parameters back out. It can be done on the client,
|
2018-05-31 14:03:42 +00:00
|
|
|
but doing it inside the smart contract means only one signature parameter
|
|
|
|
needs to be sent rather than three.
|
2018-07-09 22:45:00 +00:00
|
|
|
Splitting apart a byte array into component parts is a little messy.
|
|
|
|
We will use `inline assembly <assembly>`_ to do the job
|
|
|
|
in the ``splitSignature`` function (the third function in the full contract
|
|
|
|
at the end of this chapter).
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
Computing the Message Hash
|
|
|
|
--------------------------
|
|
|
|
|
2018-05-31 14:03:42 +00:00
|
|
|
The smart contract needs to know exactly what parameters were signed,
|
|
|
|
and so it must recreate the message from the parameters and use that
|
2018-07-09 22:45:00 +00:00
|
|
|
for signature verification. The functions ``prefixed`` and
|
|
|
|
``recoverSigner`` do this and their use can be found in the
|
|
|
|
``claimPayment`` function.
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
|
|
|
|
The full contract
|
|
|
|
-----------------
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-06-11 23:14:17 +00:00
|
|
|
pragma solidity ^0.4.24;
|
2018-05-31 09:20:14 +00:00
|
|
|
|
2018-06-03 15:31:46 +00:00
|
|
|
contract ReceiverPays {
|
|
|
|
address owner = msg.sender;
|
2018-05-31 09:20:14 +00:00
|
|
|
|
2018-06-03 15:31:46 +00:00
|
|
|
mapping(uint256 => bool) usedNonces;
|
2018-05-31 09:20:14 +00:00
|
|
|
|
2018-06-03 21:20:53 +00:00
|
|
|
constructor() public payable {}
|
2018-05-31 09:20:14 +00:00
|
|
|
|
2018-06-03 15:31:46 +00:00
|
|
|
function claimPayment(uint256 amount, uint256 nonce, bytes signature) public {
|
|
|
|
require(!usedNonces[nonce]);
|
|
|
|
usedNonces[nonce] = true;
|
|
|
|
|
|
|
|
// this recreates the message that was signed on the client
|
2018-06-11 23:14:17 +00:00
|
|
|
bytes32 message = prefixed(keccak256(abi.encodePacked(msg.sender, amount, nonce, this)));
|
2018-06-03 15:31:46 +00:00
|
|
|
|
2018-06-03 21:20:53 +00:00
|
|
|
require(recoverSigner(message, signature) == owner);
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
msg.sender.transfer(amount);
|
|
|
|
}
|
|
|
|
|
|
|
|
/// destroy the contract and reclaim the leftover funds.
|
|
|
|
function kill() public {
|
|
|
|
require(msg.sender == owner);
|
|
|
|
selfdestruct(msg.sender);
|
|
|
|
}
|
|
|
|
|
|
|
|
/// signature methods.
|
|
|
|
function splitSignature(bytes sig)
|
|
|
|
internal
|
|
|
|
pure
|
2018-07-09 22:45:00 +00:00
|
|
|
returns (uint8 v, bytes32 r, bytes32 s)
|
2018-06-03 15:31:46 +00:00
|
|
|
{
|
|
|
|
require(sig.length == 65);
|
|
|
|
|
|
|
|
assembly {
|
|
|
|
// first 32 bytes, after the length prefix.
|
2018-07-09 22:45:00 +00:00
|
|
|
r := mload(add(sig, 32))
|
2018-06-03 15:31:46 +00:00
|
|
|
// second 32 bytes.
|
2018-07-09 22:45:00 +00:00
|
|
|
s := mload(add(sig, 64))
|
2018-06-03 15:31:46 +00:00
|
|
|
// 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)
|
|
|
|
{
|
2018-07-09 22:45:00 +00:00
|
|
|
(uint8 v, bytes32 r, bytes32 s) = splitSignature(sig);
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
return ecrecover(message, v, r, s);
|
|
|
|
}
|
|
|
|
|
|
|
|
/// builds a prefixed hash to mimic the behavior of eth_sign.
|
2018-06-03 20:57:15 +00:00
|
|
|
function prefixed(bytes32 hash) internal pure returns (bytes32) {
|
2018-06-11 23:14:17 +00:00
|
|
|
return keccak256(abi.encodePacked("\x19Ethereum Signed Message:\n32", hash));
|
2018-06-03 15:31:46 +00:00
|
|
|
}
|
2018-05-31 09:20:14 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
Writing a Simple Payment Channel
|
|
|
|
================================
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Alice will now build a simple but complete implementation of a payment channel.
|
2018-05-31 14:03:42 +00:00
|
|
|
Payment channels use cryptographic signatures to make repeated transfers
|
2018-07-09 22:45:00 +00:00
|
|
|
of Ether securely, instantaneously, and without transaction fees.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
What is a Payment Channel?
|
|
|
|
--------------------------
|
|
|
|
|
2018-06-07 19:37:14 +00:00
|
|
|
Payment channels allow participants to make repeated transfers of Ether without
|
2018-05-31 14:03:42 +00:00
|
|
|
using transactions. This means that the delays and fees associated with transactions
|
2018-06-07 19:37:14 +00:00
|
|
|
can be avoided. We are going to explore a simple unidirectional payment channel between
|
|
|
|
two parties (Alice and Bob). Using it involves three steps:
|
2018-05-31 09:20:14 +00:00
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
1. Alice funds a smart contract with Ether. This "opens" the payment channel.
|
|
|
|
2. Alice signs messages that specify how much of that Ether is owed to the recipient. This step is repeated for each payment.
|
|
|
|
3. Bob "closes" the payment channel, withdrawing their portion of the Ether and sending the remainder back to the sender.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Not ethat only steps 1 and 3 require Ethereum transactions, step 2 means that
|
|
|
|
the sender transmits a cryptographically signed message to the recipient via off chain ways (e.g. email).
|
2018-05-31 14:03:42 +00:00
|
|
|
This means only two transactions are required to support any number of transfers.
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Bob is guaranteed to receive their funds because the smart contract escrows
|
2018-06-07 19:37:14 +00:00
|
|
|
the Ether and honors a valid signed message. The smart contract also enforces a timeout,
|
2018-07-09 22:45:00 +00:00
|
|
|
so Alice is guaranteed to eventually recover their funds even if the recipient refuses
|
2018-05-31 14:03:42 +00:00
|
|
|
to close the channel.
|
2018-06-07 19:37:14 +00:00
|
|
|
It is up to the participants in a payment channel to decide how long to keep it open.
|
2018-05-31 14:03:42 +00:00
|
|
|
For a short-lived transaction, such as paying an internet cafe for each minute of network access,
|
|
|
|
or for a longer relationship, such as paying an employee an hourly wage, a payment could last for months or years.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
Opening the Payment Channel
|
|
|
|
---------------------------
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
To open the payment channel, Alice deploys the smart contract,
|
2018-06-07 19:37:14 +00:00
|
|
|
attaching the Ether to be escrowed and specifying the intendend recipient
|
2018-06-03 15:31:46 +00:00
|
|
|
and a maximum duration for the channel to exist. It is the function
|
2018-07-09 22:45:00 +00:00
|
|
|
``SimplePaymentChannel`` in the contract, that is at the end of this chapter.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
Making Payments
|
|
|
|
---------------
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Alice makes payments by sending signed messages to Bob.
|
2018-05-31 14:03:42 +00:00
|
|
|
This step is performed entirely outside of the Ethereum network.
|
|
|
|
Messages are cryptographically signed by the sender and then transmitted directly to the recipient.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
Each message includes the following information:
|
|
|
|
|
|
|
|
* The smart contract's address, used to prevent cross-contract replay attacks.
|
2018-06-07 19:37:14 +00:00
|
|
|
* The total amount of Ether that is owed the recipient so far.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
2018-05-31 14:03:42 +00:00
|
|
|
A payment channel is closed just once, at the of a series of transfers.
|
|
|
|
Because of this, only one of the messages sent will be redeemed. This is why
|
2018-06-07 19:37:14 +00:00
|
|
|
each message specifies a cumulative total amount of Ether owed, rather than the
|
2018-05-31 14:03:42 +00:00
|
|
|
amount of the individual micropayment. The recipient will naturally choose to
|
2018-06-07 19:37:14 +00:00
|
|
|
redeem the most recent message because that is the one with the highest total.
|
2018-07-09 22:45:00 +00:00
|
|
|
The nonce per-message is not needed anymore, because the smart contract will
|
2018-05-31 14:03:42 +00:00
|
|
|
only honor a single message. 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.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Here is the modified javascript code to cryptographically sign a message from the previous chapter:
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
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.
|
2018-06-07 19:37:14 +00:00
|
|
|
// amount, in wei, specifies how much Ether should be sent.
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
function signPayment(contractAddress, amount, callback) {
|
|
|
|
var message = constructPaymentMessage(contractAddress, amount);
|
|
|
|
signMessage(message, callback);
|
|
|
|
}
|
2018-06-03 15:31:46 +00:00
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
|
2018-06-03 15:31:46 +00:00
|
|
|
Closing the Payment Channel
|
|
|
|
---------------------------
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
When Bob is ready to receive their funds, it is time to
|
|
|
|
close the payment channel by calling a ``close`` function on the smart contract.
|
|
|
|
Closing the channel pays the recipient the Ether they are owed and destroys the contract,
|
|
|
|
sending any remaining Ether back to Alice.
|
|
|
|
To close the channel, Bob needs to provide a message signed by Alice.
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
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.
|
2018-07-09 22:45:00 +00:00
|
|
|
The Solidity functions ``isValidSignature`` and ``recoverSigner`` work just like their
|
2018-06-03 15:31:46 +00:00
|
|
|
JavaScript counterparts in the previous section. The latter is borrowed from the
|
2018-07-09 22:45:00 +00:00
|
|
|
``ReceiverPays`` contract in the previous chapter.
|
2018-06-03 15:31:46 +00:00
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
The ``close`` function can only be called by the payment channel recipient,
|
2018-06-03 15:31:46 +00:00
|
|
|
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,
|
2018-06-07 19:37:14 +00:00
|
|
|
they could provide a message with a lower amount and cheat the recipient out of what they are owed.
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
The function verifies the signed message matches the given parameters.
|
2018-06-07 19:37:14 +00:00
|
|
|
If everything checks out, the recipient is sent their portion of the Ether,
|
2018-07-09 22:45:00 +00:00
|
|
|
and the sender is sent the rest via a ``selfdestruct``.
|
|
|
|
You can see the ``close`` function in the full contract.
|
2018-06-03 15:31:46 +00:00
|
|
|
|
2018-06-03 16:20:49 +00:00
|
|
|
Channel Expiration
|
2018-06-03 15:31:46 +00:00
|
|
|
-------------------
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Bob can close the payment channel at any time, but if they fail to do so,
|
|
|
|
Alice needs a way to recover their escrowed funds. An *expiration* time was set
|
|
|
|
at the time of contract deployment. Once that time is reached, Alice can call
|
|
|
|
``claimTimeout`` to recover their funds. You can see the ``claimTimeout`` function in the
|
2018-06-03 15:31:46 +00:00
|
|
|
full contract.
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
After this function is called, Bob can no longer receive any Ether,
|
|
|
|
so it is important that Bob closes the channel before the expiration is reached.
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
|
|
|
|
The full contract
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-06-11 23:14:17 +00:00
|
|
|
pragma solidity ^0.4.24;
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2018-06-11 23:14:17 +00:00
|
|
|
constructor (address _recipient, uint256 duration)
|
2018-06-03 15:31:46 +00:00
|
|
|
public
|
|
|
|
payable
|
|
|
|
{
|
|
|
|
sender = msg.sender;
|
|
|
|
recipient = _recipient;
|
|
|
|
expiration = now + duration;
|
|
|
|
}
|
|
|
|
|
|
|
|
function isValidSignature(uint256 amount, bytes signature)
|
2018-07-09 22:45:00 +00:00
|
|
|
internal
|
|
|
|
view
|
|
|
|
returns (bool)
|
2018-06-03 15:31:46 +00:00
|
|
|
{
|
2018-06-11 23:14:17 +00:00
|
|
|
bytes32 message = prefixed(keccak256(abi.encodePacked(this, amount)));
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
// 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,
|
2018-07-10 07:17:33 +00:00
|
|
|
/// then the Ether is released back to the sender.
|
2018-07-14 16:32:47 +00:00
|
|
|
function claimTimeout() public {
|
2018-06-03 15:31:46 +00:00
|
|
|
require(now >= expiration);
|
|
|
|
selfdestruct(sender);
|
|
|
|
}
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
/// All functions below this are just taken from the chapter
|
|
|
|
/// 'creating and verifying signatures' chapter.
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
function splitSignature(bytes sig)
|
|
|
|
internal
|
|
|
|
pure
|
2018-07-09 22:45:00 +00:00
|
|
|
returns (uint8 v, bytes32 r, bytes32 s)
|
2018-06-03 15:31:46 +00:00
|
|
|
{
|
|
|
|
require(sig.length == 65);
|
|
|
|
|
|
|
|
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)
|
|
|
|
{
|
2018-07-09 22:45:00 +00:00
|
|
|
(uint8 v, bytes32 r, bytes32 s) = splitSignature(sig);
|
2018-06-03 15:31:46 +00:00
|
|
|
|
|
|
|
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) {
|
2018-06-11 23:14:17 +00:00
|
|
|
return keccak256(abi.encodePacked("\x19Ethereum Signed Message:\n32", hash));
|
2018-06-03 15:31:46 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2018-07-09 22:45:00 +00:00
|
|
|
Note: The function ``splitSignature`` is very simple and does not use all security checks.
|
|
|
|
A real implementation should use a more rigorously tested library, such as
|
|
|
|
openzepplin's `version <https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/ECRecovery.sol>`_ of this code.
|
2018-06-03 15:31:46 +00:00
|
|
|
|
2018-05-31 14:13:14 +00:00
|
|
|
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
Verifying Payments
|
|
|
|
------------------
|
|
|
|
|
2018-05-31 14:03:42 +00:00
|
|
|
Unlike in our previous chapter, 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
|
2018-05-31 09:20:14 +00:00
|
|
|
in the end.
|
|
|
|
|
|
|
|
The recipient should verify each message using the following process:
|
|
|
|
|
|
|
|
1. Verify that the contact address in the message matches the payment channel.
|
|
|
|
2. Verify that the new total is the expected amount.
|
2018-06-07 19:37:14 +00:00
|
|
|
3. Verify that the new total does not exceed the amount of Ether escrowed.
|
2018-05-31 09:20:14 +00:00
|
|
|
4. Verify that the signature is valid and comes from the payment channel sender.
|
|
|
|
|
2018-05-31 14:03:42 +00:00
|
|
|
We'll use the `ethereumjs-util <https://github.com/ethereumjs/ethereumjs-util>`_
|
2018-06-03 15:31:46 +00:00
|
|
|
library to write this verifications. The final step can be done a number of ways,
|
|
|
|
but if it's being done in **JavaScript**.
|
|
|
|
The following code borrows the `constructMessage` function from the signing **JavaScript code**
|
|
|
|
above:
|
2018-05-31 09:20:14 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
// 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();
|
|
|
|
}
|