{"id":127877,"date":"2022-09-06T17:56:59","date_gmt":"2022-09-06T17:56:59","guid":{"rendered":"https:\/\/blog.finxter.com\/?p=651290"},"modified":"2022-09-06T17:56:59","modified_gmt":"2022-09-06T17:56:59","slug":"solidity-by-example-simple-open-auction-explained","status":"publish","type":"post","link":"https:\/\/sickgaming.net\/blog\/2022\/09\/06\/solidity-by-example-simple-open-auction-explained\/","title":{"rendered":"Solidity by Example \u2013 Simple Open Auction (Explained)"},"content":{"rendered":"\n
\n
\n
\n
\n
<\/div>\n<\/p><\/div>\n
\n
<\/div>\n<\/p><\/div>\n
\n
<\/div>\n<\/p><\/div>\n
\n
<\/div>\n<\/p><\/div>\n
\n
<\/div>\n<\/p><\/div>\n<\/p><\/div>\n
\n
\n
<\/div>\n<\/p><\/div>\n
\n
<\/div>\n<\/p><\/div>\n
\n
<\/div>\n<\/p><\/div>\n
\n
<\/div>\n<\/p><\/div>\n
\n
<\/div>\n<\/p><\/div>\n<\/p><\/div>\n<\/div>\n
5\/5 – (1 vote) <\/div>\n<\/div>\n
\"YouTube<\/a>
<\/figcaption><\/figure>\n

This article continues on the series we started the last time: Solidity smart contract examples<\/a>, which implement a simplified real-world process. <\/p>\n

Here, we’re walking through an example of a simple open auction.<\/p>\n

\"\ud83c\udf0d\" Original Source Code<\/strong>: Solidity Docs<\/a><\/p>\n

We’ll first lay out the entire smart contract<\/a> example without the comments for readability and development purposes. <\/p>\n

Then we’ll dissect it part by part, analyze it and explain it. <\/p>\n

Following this path, we’ll get a hands-on experience with smart contracts, as well as good practices in coding, understanding, and debugging<\/a> smart contracts.<\/p>\n

<\/a>Smart contract – Simple Open Auction<\/h2>\n
\/\/ SPDX-License-Identifier: GPL-3.0\npragma solidity ^0.8.4; contract SimpleAuction { address payable public beneficiary; uint public auctionEndTime; address public highestBidder; uint public highestBid; mapping(address => uint) pendingReturns; bool ended; event HighestBidIncreased(address bidder, uint amount); event AuctionEnded(address winner, uint amount); error AuctionAlreadyEnded(); error BidNotHighEnough(uint highestBid); error AuctionNotYetEnded(uint timeToAuctionEnd); error AuctionEndAlreadyCalled(); constructor( uint biddingTime, address payable beneficiaryAddress ) { beneficiary = beneficiaryAddress; auctionEndTime = block.timestamp + biddingTime; } function bid() external payable { if (block.timestamp > auctionEndTime) revert AuctionAlreadyEnded(); if (msg.value <= highestBid) revert BidNotHighEnough(highestBid); if (highestBid != 0) { pendingReturns[highestBidder] += highestBid; } highestBidder = msg.sender; highestBid = msg.value; emit HighestBidIncreased(msg.sender, msg.value); } function withdraw() external returns (bool) { uint amount = pendingReturns[msg.sender]; if (amount > 0) { pendingReturns[msg.sender] = 0; if (!payable(msg.sender).send(amount)) { pendingReturns[msg.sender] = amount; return false; } } return true; } function auctionEnd() external { if (block.timestamp < auctionEndTime) revert AuctionNotYetEnded(auctionEndTime - block.timestamp); if (ended) revert AuctionEndAlreadyCalled(); ended = true; emit AuctionEnded(highestBidder, highestBid); beneficiary.transfer(highestBid); }\n}\n<\/pre>\n
<\/a>Code breakdown and analysis<\/h2>\n
\/\/ SPDX-License-Identifier: GPL-3.0<\/pre>\n
Compiles only with Solidity compiler version 0.8.4 and later, but before version 0.9.<\/p>\n
\"\ud83c\udf0d\" Learn More<\/strong>: Layout of a Solidity File<\/a><\/p>\n
pragma solidity ^0.8.4; contract SimpleAuction {\n<\/pre>\n
Parameters of the auction are variables beneficiary<\/code> and auctionEndTime<\/code> which we’ll initialize with contract creation arguments while the contract gets created<\/a>, i.e. in the contract constructor. <\/p>\n
Data type for time variables is unsigned integer uint<\/code>, so that we can represent either absolute Unix timestamps (seconds since 1970-01-01) or time periods in seconds (seconds lapsed from the reference moment we chose).<\/p>\n
 address payable public beneficiary; uint public auctionEndTime;\n<\/pre>\n
The current state of the auction is reflected in two variables, highestBidder<\/code> and highestBid<\/code>.<\/p>\n
 address public highestBidder; uint public highestBid;\n<\/pre>\n
Previous bids can be withdrawn, that’s why we have mapping data structure to record pendingReturns<\/code>.<\/p>\n
 mapping(address => uint) pendingReturns;<\/pre>\n
Indicator flag variable for the auction end. By default, the flag is initialized to false<\/code>; we’ll prevent changing it once it switches to true<\/code>.<\/p>\n
 bool ended;<\/pre>\n
When changes occur, we want our smart contract to emit<\/a> the corresponding change events.<\/p>\n
 event HighestBidIncreased(address bidder, uint amount); event AuctionEnded(address winner, uint amount);\n<\/pre>\n
We’re defining four errors to describe relevant failures. Along with these errors, we’ll also introduce “triple-slash” comments, commonly known as natspec<\/code> comments. They enable users to see comments when an error is displayed or when users are asked to confirm the transaction. <\/p>\n
\"\ud83c\udf0d\" Learn More<\/strong>: Natspec comments are formally defined in Ethereum Natural Language Specification Format<\/a>.<\/p>\n
 \/\/\/ The auction has already ended. error AuctionAlreadyEnded(); \/\/\/ There is already a higher or equal bid. error BidNotHighEnough(uint highestBid); \/\/\/ The auction has not ended yet, the remaining seconds are displayed. error AuctionNotYetEnded(uint timeToAuctionEnd); \/\/\/ The function auctionEnd has already been called. error AuctionEndAlreadyCalled();\n<\/pre>\n
Initialization of the contract with the contract creation arguments biddingTime<\/code> and beneficiaryAddress<\/code>.<\/p>\n
 \/\/\/ Create a simple auction with `biddingTime` \/\/\/ seconds bidding time on behalf of the \/\/\/ beneficiary address `beneficiaryAddress`. constructor( uint biddingTime, address payable beneficiaryAddress ) { beneficiary = beneficiaryAddress; auctionEndTime = block.timestamp + biddingTime; }\n<\/pre>\n
A bidder bids by sending the currency (pa<\/a>ying<\/a>) to the smart contract representing the beneficiary, hence the bid()<\/code> function is defined as payable<\/a><\/code>.<\/p>\n
\"\ud83c\udf0d\" Learn More<\/strong>: What is payable<\/code> in Solidity?<\/a><\/p>\n
 \/\/\/ Bid on the auction with the value sent \/\/\/ together with this transaction. \/\/\/ The value will only be refunded if the \/\/\/ auction is not won. function bid() external payable {\n<\/pre>\n
The function call reverts if the bidding period ended.<\/p>\n
 if (block.timestamp > auctionEndTime) revert AuctionAlreadyEnded();\n<\/pre>\n
The function rolls back the transaction to the bidder if the bid does not exceed the highest one.<\/p>\n
 if (msg.value <= highestBid) revert BidNotHighEnough(highestBid);\n<\/pre>\n
The previous highest bidder was outbid and his bid is added to his previous bids reserved for a refund. <\/p>\n
\"\ud83d\udca1\" A direct refund is considered a secu<\/a>r<\/a>ity risk<\/a> due to the possibility of executing an untrusted contract. <\/p>\n
Instead, the bidders (recipients) will withdraw their bids themselves by using withdraw() function below.<\/p>\n
 if (highestBid != 0) { pendingReturns[highestBidder] += highestBid; }\n<\/pre>\n
The new highest bidder and his bid are recorded; the event HighestBidIncreased<\/code> is emitted carrying this information pair.<\/p>\n
 highestBidder = msg.sender; highestBid = msg.value; emit HighestBidIncreased(msg.sender, msg.value); }\n<\/pre>\n
Bidders call the withdraw()<\/code> function to retrieve the amount they bid.<\/p>\n
 \/\/\/ Withdraw a bid that was overbid. function withdraw() external returns (bool) { uint amount = pendingReturns[msg.sender]; if (amount > 0) {\n<\/pre>\n
It is possible to call the withdraw()<\/code> function again before the send()<\/code> function returns. That’s the reason why we need to disable multiple sequential withdrawals from the same sender by setting the pending returns for a sender to 0.<\/p>\n
 pendingReturns[msg.sender] = 0;<\/pre>\n
Variable type of msg.sender<\/code> is not address payable<\/code>, therefore we need to convert it explicitly by using function payable() as a wrapping function. <\/p>\n
If the send()<\/code> function ends with an error, we’ll just reset the pending amount and return false<\/code>.<\/p>\n
 if (!payable(msg.sender).send(amount)) { \/\/ No need to call throw here, just reset the amount owing pendingReturns[msg.sender] = amount; return false; } } return true; }\n<\/pre>\n
The auctionEnd()<\/code> function ends the auction and sends the highest bid to the beneficiary. <\/p>\n
The official Solidity documentation recommends dividing the interacting functions into three functional parts:<\/p>\n