English Auction Contract Overview
The EnglishAuction contract implements ascending-price auctions. Each auction is its own contract instance, deployed by the AuctionFactory (as an EIP-1167 minimal-proxy clone of a template) — so every auction holds exactly its own NFT and its own funds, isolated from all others.
The permissions to initiate an auction and participate in bidding are handled through Role-Based Access Control at the application layer.
Lifecycle
- Creation — the factory verifies the seller owns the NFT and has approved the factory, then deploys the auction and transfers the NFT into the auction contract (NFT escrow) for the auction's lifetime.
- Bidding — bidders send ETH with their bids; each new bid must exceed the current highest bid.
- End — after the end time,
end()finalizes the auction (it is deliberately callable by anyone, since contracts don't execute on their own). The NFT transfers to the highest bidder; the winning payment stays escrowed in the contract. - Settlement — the buyer's
confirmDelivery()releases payment to the seller. If the buyer never confirms, the seller may withdraw after a 7-day grace period, so funds can never be locked forever.
Properties
An auction has these properties:
| Property | Description |
|---|---|
| nft / nftId | The ERC-721 contract and token being sold (held by the auction). |
| seller | Address of the seller who initiated the auction. |
| highestBid | Current highest bid amount. |
| highestBidder | Address of the current highest bidder. |
| bids | Mapping of outbid amounts, reclaimable per bidder (pull pattern). |
| endAt | Timestamp at which the auction ends. |
| started / ended | Lifecycle flags. |
| paymentReleased | Whether escrowed funds have been released to the seller. |
Design notes
| Decision | Rationale |
|---|---|
| Pull-payment withdrawals | Outbid funds accumulate in bids[bidder] and are reclaimed via withdraw() — safer than pushing refunds, and immune to griefing by contracts that reject transfers. |
Permissionless end() | Contracts cannot wake themselves up; anyone may finalize an expired auction, so settlement never depends on one party showing up. |
| Escrowed settlement | Payment is released by the buyer's delivery confirmation rather than instantly — appropriate for physical goods. A 7-day CONFIRMATION_GRACE_PERIOD lets the seller withdraw if the buyer disappears. |
| Reentrancy guard | All value-moving functions are protected against reentrancy. |
Actions
| Action | Description | Who |
|---|---|---|
| create auction | Factory clones the contract and escrows the NFT | seller (via app) |
| bid | Place a bid above the current highest, sending ETH | any non-seller |
| withdraw | Reclaim funds after being outbid | outbid bidders |
| end | Finalize after endAt; NFT → winner, funds → escrow | anyone |
| confirmDelivery | Release escrowed payment to the seller | winning buyer |
| sellerWithdraw | Collect payment after the 7-day grace period | seller |