![]() |
|
[Tut] Solidity by Example – Simple Open Auction (Explained) - Printable Version +- Sick Gaming (https://sickgaming.net) +-- Forum: Programming (https://sickgaming.net/forum-76.html) +--- Forum: Python (https://sickgaming.net/forum-83.html) +--- Thread: [Tut] Solidity by Example – Simple Open Auction (Explained) (/thread-99919.html) |
[Tut] Solidity by Example – Simple Open Auction (Explained) - xSicKxBot - 09-08-2022 Solidity by Example – Simple Open Auction (Explained) 5/5 – (1 vote) This article continues on the series we started the last time: Solidity smart contract examples, which implement a simplified real-world process. Here, we’re walking through an example of a simple open auction. Original Source Code: Solidity DocsWe’ll first lay out the entire smart contract example without the comments for readability and development purposes. Then we’ll dissect it part by part, analyze it and explain it. Following this path, we’ll get a hands-on experience with smart contracts, as well as good practices in coding, understanding, and debugging smart contracts. Smart contract – Simple Open Auction Code: // SPDX-License-Identifier: GPL-3.0
pragma 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); }
}Code: // SPDX-License-Identifier: GPL-3.0Compiles only with Solidity compiler version 0.8.4 and later, but before version 0.9. Learn More: Layout of a Solidity FileCode: pragma solidity ^0.8.4; contract SimpleAuction {Parameters of the auction are variables Code: beneficiaryCode: auctionEndTimeData type for time variables is unsigned integer Code: uintCode: address payable public beneficiary; uint public auctionEndTime;The current state of the auction is reflected in two variables, Code: highestBidderCode: highestBidCode: address public highestBidder; uint public highestBid;Previous bids can be withdrawn, that’s why we have mapping data structure to record Code: pendingReturnsCode: mapping(address => uint) pendingReturns;Indicator flag variable for the auction end. By default, the flag is initialized to Code: falseCode: trueCode: bool ended;When changes occur, we want our smart contract to emit the corresponding change events. Code: event HighestBidIncreased(address bidder, uint amount); event AuctionEnded(address winner, uint amount);We’re defining four errors to describe relevant failures. Along with these errors, we’ll also introduce “triple-slash” comments, commonly known as Code: natspec Learn More: Natspec comments are formally defined in Ethereum Natural Language Specification Format.Code: /// 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();Initialization of the contract with the contract creation arguments Code: biddingTimeCode: beneficiaryAddressCode: /// 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; }A bidder bids by sending the currency (paying) to the smart contract representing the beneficiary, hence the Code: bid()Code: payable Learn More: What is Code: payableCode: /// 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 {The function call reverts if the bidding period ended. Code: if (block.timestamp > auctionEndTime) revert AuctionAlreadyEnded();The function rolls back the transaction to the bidder if the bid does not exceed the highest one. Code: if (msg.value <= highestBid) revert BidNotHighEnough(highestBid);The previous highest bidder was outbid and his bid is added to his previous bids reserved for a refund. A direct refund is considered a security risk due to the possibility of executing an untrusted contract.Instead, the bidders (recipients) will withdraw their bids themselves by using withdraw() function below. Code: if (highestBid != 0) { pendingReturns[highestBidder] += highestBid; }The new highest bidder and his bid are recorded; the event Code: HighestBidIncreasedCode: highestBidder = msg.sender; highestBid = msg.value; emit HighestBidIncreased(msg.sender, msg.value); }Bidders call the Code: withdraw()Code: /// Withdraw a bid that was overbid. function withdraw() external returns (bool) { uint amount = pendingReturns[msg.sender]; if (amount > 0) {It is possible to call the Code: withdraw()Code: send()Code: pendingReturns[msg.sender] = 0;Variable type of Code: msg.senderCode: payableIf the Code: send()Code: falseCode: 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; }The Code: auctionEnd()The official Solidity documentation recommends dividing the interacting functions into three functional parts:
Otherwise, by combining these parts rather than keeping them separated, more than one calling contract could try and modify the state of the called contract and change the called contract’s state. Code: /// End the auction and send the highest bid /// to the beneficiary. function auctionEnd() external {Checking the conditions… Code: if (block.timestamp < auctionEndTime) revert AuctionNotYetEnded(auctionEndTime - block.timestamp); if (ended) revert AuctionEndAlreadyCalled();…performing the actions… Code: ended = true; emit AuctionEnded(highestBidder, highestBid);…and interacting with other contracts. Code: beneficiary.transfer(highestBid); }
}Our smart contract example is a simple, but a powerful one, enabling us to bid an amount of currency to the beneficiary. When the contract instantiates via its constructor, it sets the auction end time and its beneficiary, i.e. beneficiary address. The contract has three simple features, implemented via dedicated functions: bidding, withdrawing the bids and ending the auction. A new bid is accepted only if its amount is strictly larger than the current highest bid. A new bid acceptance means that the current highest bid is added to the bidder’s balance for later withdrawal. The new highest bidder becomes the current highest bidder and the new highest bid becomes the current highest bid. Bid withdrawing returns all summed previous bids to each bidder ( Code: mapping pendingReturnsContract Test Scenario Open auction duration (in seconds): Code: 240Beneficiary: Code: 0x5B38Da6a701c568545dCfcB03FcB875f56beddC4Testing/demonstration steps:
Appendix – The Contract Arguments In this section is additional information for running the contract. We should expect that our example accounts may change with each refresh/reload of Remix. Our contract creation arguments are the open auction duration (in seconds) and the beneficiary address (copy this line when deploying the example): Code: 300, 0x5B38Da6a701c568545dCfcB03FcB875f56beddC4 Info: we could’ve used any amount of time, but I went with 300 seconds to timely simulate both a rejected attempt of ending the auction and the successful ending of the auction.Conclusion We continued our smart contract example series with this article that implements a simple open auction. First, we laid out clean source code (without any comments) for readability purposes. Omitting the comments is not recommended, but we love living on the edge – and trying to be funny! ![]() Second, we dissected the code, analyzed it, and explained each possibly non-trivial segment. Just because we’re terrific, safe players who never risk it and do everything by the book ![]() ![]() Programmer Humor – Blockchain [i]“Blockchains are like grappling hooks, in that it’s extremely cool when you encounter a problem for which they’re the right solution, but it happens way too rarely in real life.” source – xkcd[/i]
|