This article continues on the Solidity Smart Contract Examples series, which implements a simple, but the useful process of safe remote purchase.
Here, we’re walking through an example of a blind auction (docs).
- We’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 – Safe Remote Purchase
// SPDX-License-Identifier: GPL-3.0 pragma solidity ^0.8.4; contract Purchase { uint public value; address payable public seller; address payable public buyer; enum State { Created, Locked, Release, Inactive } State public state; modifier condition(bool condition_) { require(condition_); _; } error OnlyBuyer(); error OnlySeller(); error InvalidState(); error ValueNotEven(); modifier onlyBuyer() { if (msg.sender != buyer) revert OnlyBuyer(); _; } modifier onlySeller() { if (msg.sender != seller) revert OnlySeller(); _; } modifier inState(State state_) { if (state != state_) revert InvalidState(); _; } event Aborted(); event PurchaseConfirmed(); event ItemReceived(); event SellerRefunded(); constructor() payable { seller = payable(msg.sender); value = msg.value / 2; if ((2 * value) != msg.value) revert ValueNotEven(); } function abort() external onlySeller inState(State.Created) { emit Aborted(); state = State.Inactive; seller.transfer(address(this).balance); } function confirmPurchase() external inState(State.Created) condition(msg.value == (2 * value)) payable { emit PurchaseConfirmed(); buyer = payable(msg.sender); state = State.Locked; } function confirmReceived() external onlyBuyer inState(State.Locked) { emit ItemReceived(); state = State.Release; buyer.transfer(value); } function refundSeller() external onlySeller inState(State.Release) { emit SellerRefunded(); state = State.Inactive; seller.transfer(3 * value); } }
Code breakdown and analysis
// SPDX-License-Identifier: GPL-3.0 pragma solidity ^0.8.4; contract Purchase {
The state variables for recording the value, seller, and buyer addresses.
uint public value; address payable public seller; address payable public buyer;
For the first time, we’re introducing the enum
data structure that symbolically defines the four possible states of our contract. The states are internally indexed from 0
to enum_length - 1
.
enum State { Created, Locked, Release, Inactive }
The variable state keeps track of the current state. Our contract starts by default in the created state and can transition to the Locked, Release, and Inactive state.
State public state;
The condition
modifier guards a function against executing without previously satisfying the condition, i.e. an expression given alongside the function definition.
modifier condition(bool condition_) { require(condition_); _; }
The error definitions are used with the appropriate, equally-named modifiers.
error OnlyBuyer(); error OnlySeller(); error InvalidState(); error ValueNotEven();
The onlyBuyer
modifier guards a function against executing when the function caller is not the buyer.
modifier onlyBuyer() { if (msg.sender != buyer) revert OnlyBuyer(); _; }
The onlySeller
modifier guards a function against executing when the function caller differs from the seller.
modifier onlySeller() { if (msg.sender != seller) revert OnlySeller(); _; }
The inState
modifier guards a function against executing when the contract state differs from the required state_
.
modifier inState(State state_) { if (state != state_) revert InvalidState(); _; }
The events that the contract emits to acknowledge the functions abort()
, confirmPurchase()
, confirmReceived()
, and refundSeller()
were executed.
event Aborted(); event PurchaseConfirmed(); event ItemReceived(); event SellerRefunded();
The constructor is declared as payable
, meaning that the contract deployment (synonyms creation, instantiation) requires sending a value (msg.value
) with the contract-creating transaction.
constructor() payable {
The seller
state variable is set to msg.sender
address, cast (converted) to payable.
seller = payable(msg.sender);
The value state variable is set to half the msg.value
, because both the seller and the buyer have to put twice the value of the item being sold/bought into the contract as an escrow agreement.
π‘ Info: “Escrow is a legal arrangement in which a third party temporarily holds money or property until a particular condition has been met (such as the fulfillment of a purchase agreement).” (source)
In our case, our escrow is our smart contract.
value = msg.value / 2;
If the value is not equally divided, i.e. the msg.value
is not an even number, the function will terminate. Since the seller will always
if ((2 * value) != msg.value) revert ValueNotEven(); }
Aborting the remote safe purchase is allowed only in the Created
state and only by the seller.
The external
keyword makes the function callable only by other accounts / smart contracts. From the business perspective, only the seller can call the abort()
function and only before the buyer decides to purchase, i.e. before the contract enters the Locked
state.
function abort() external onlySeller inState(State.Created) {
Emits the Aborted
event, the contract state transitions to inactive, and the balance is transferred to the seller.
emit Aborted(); state = State.Inactive;
π‘ Note: “Prior to version 0.5.0, Solidity allowed address members to be accessed by a contract instance, for example, this.balance. This is now forbidden and an explicit conversion to address must be done: address(this).balance.” (docs).
In other words, this keyword lets us access the contract’s inherited members.
Every contract inherits its members from the address type and can access these members via address(this).<a member>
(docs).
seller.transfer(address(this).balance); }
The confirmPurchase()
function is available for execution only in the Created
state.
It enforces the rule that a msg.value
must be twice the value of the purchase.
The confirmPurchase()
function is also declared as payable
, meaning the caller, i.e. the buyer has to send the currency (msg.value
) with the function call.
function confirmPurchase() external inState(State.Created) condition(msg.value == (2 * value)) payable {
The event PurchaseConfirmed()
is emitted to mark the purchase confirmation.
emit PurchaseConfirmed();
The msg.sender
value is cast to payable and assigned to the buyer variable.
π‘ Info: Addresses are non-payable by design to prevent accidental payments; that’s why we have to cast an address to a payable before being able to transfer a payment.
buyer = payable(msg.sender);
The state is set to Locked
as seller and buyer entered the contract, i.e., our digital version of an escrow agreement.
state = State.Locked; }
The confirmReceived()
function is available for execution only in the Locked
state, and only to the buyer.
Since the buyer deposited twice the value amount and withdrew only a single value amount, the second value amount remains on the contract balance with the seller’s deposit.
function confirmReceived() external onlyBuyer inState(State.Locked) {
Emits the ItemReceived()
event.
emit ItemReceived();
Changes the state to Release.
state = State.Release;
Transfers the deposit to the buyer.
buyer.transfer(value); }
The refundSeller()
function is available for execution only in the Release
state, and only to the seller.
Since the seller deposited twice the value amount and earned a single value amount from the purchase, the contract transfers three value amounts from the contract balance to the seller.
function refundSeller() external onlySeller inState(State.Release) {
Emits the SellerRefunded()
event.
emit SellerRefunded();
Changes the state to Inactive
.
state = State.Inactive;
Transfers the deposit of two value amounts and the one earned value amount to the seller.
seller.transfer(3 * value); } }
Our smart contract example of a safe remote purchase is a nice and simple example that demonstrates how a purchase may be conducted on the Ethereum blockchain network.
The safe remote purchase example shows two parties, a seller and a buyer, who both enter a trading relationship with their deposits to the contract balance.
Each deposit amounts to twice the value of the purchase, meaning that the contract balance will hold four times the purchase value at its highest point, i.e. in the Locked
state.
The height of deposits is intended to stimulate the resolution of any possible disputes between the parties, because otherwise, their deposits will stay locked and unavailable in the contract balance.
When the buyer confirms that he received the goods he purchased, the contract will transition to the Release
state, and the purchase value will be released to the buyer.
The seller can now withdraw his earned purchase value with the deposit, the contract balance drops to 0 Wei, the contract transitions to the Inactive
state, and the safe remote purchase concludes with execution.
The Contract Arguments
This section contains additional information for running the contract. We should expect that our example accounts may change with each refresh/reload of Remix.
Our contract creation argument is the deposit (twice the purchase value). We’ll assume the purchase value to be 5 Wei, making the contract creation argument very simple:
10
Contract Test Scenario
- Account
0x5B38Da6a701c568545dCfcB03FcB875f56beddC4
deploys the contract with a deposit of 10 Wei, effectively becoming a seller. - Account
0xAb8483F64d9C6d1EcF9b849Ae677dD3315835cb2
confirms the purchase by calling theconfirmPurchase()
function and enters the trade with a deposit of 10 Wei, effectively becoming a buyer. - The buyer confirms receiving the order by calling the
confirmReceived()
function. - The seller concludes the trade by calling the
refundSeller()
function.
Conclusion
We continued our smart contract example series with this article that implements a safe remote purchase.
First, we laid out clean source code (without any comments) for readability purposes.
Second, we dissected the code, analyzed it, and explained each possibly non-trivial segment.