TON NFT Auction Contract Product & Technical Requirements

TON NFT Auction Contract Product Description

This document contains certain product and technical requirements for developing FunC auction contract.

Technical requirements

Basic product requirements

• seller should be able to set minimum starting bid
• seller should be able to optionally set auction duration
• seller should be able to optionally set max bid, in case of such bid NFT gets transferred to bidder and auction is closed
• seller should be able to stop auction at any time, it this case NFT is returned to seller
• bidders should be able any bid with respect of minimum & maximum bids

Technical details of smart contract

Smart contract should contain customizable parameters above:

• marketplace_address (address of marketplace in which auction is started)
• minimum_bid_value
• maximum_bid_value
• marketplace_fee_address (address to which marketplace fees will be sent)
• marketplace_fee_params (includes address to which marketplace fees will be sent, numerator and denominator, as in NFT standard https://github.com/ton-blockchain/TIPs/issues/66)
• royalty_params (same as marketplace_fee_params but for NFT royalties)
• auction_finish_time (unixtime time at which auction finishes

Parameters above would be set on marketplace while setting-up stateInit for auction smart contract deployment.

Deployment process

We suggest to use same approach as in standard NFT sale contract:

• Smart contract expects deploy message only from marketplace address
• after deployment sale contract expects ownership_assigned message from nft and set’s nft owner address

Bids process

• after sales nft is transferred to auction contract and it’s fully initialized - auction starts
• any address could place a bid
• coins with appropriate bid value is sent to auction contract
• auction contract stores bid coins until auction is finished or until there is any bigger bid
• if someone makes bigger bid then coins from previous bid should return to previous bidder
• if someone makes bid with maximum_bid_value coins - then auction is immediately finishes and NFT gets transferred to the bidder

Auction cancellation

• nft owner should be able to cancel auction at any time
• in this case last bid value should be returned to bidder (if any) and NFT should be transferred back to original owner

Finish process

Auction is considered to be finished in one of two cases:

• there was a bid with maximum_bid_value
• auction_finish_time is passed

Payments process

If auction is finished and there was appropriate bid than payment process should start.

If auction is finished by time - than this process should be able to be initialized via some control message to auction smart contract

In payments process auction smart contract should do:

• transfer NFT to the winner
• calculate and send royalties
• calculate and send marketplace fees

For security reasons auction smart contract should not get deleted after finish and should not accept any bids.

Any bids after auction finish should be returned either via bounce process by throwing exception or via sending message to the bidder with flag 64 set (preferred).

Developers are free to define some get-functions in smart contract for retrieving useful data about auction.

Development requirements

• Smart contract should be written in FunC language
• Smart contract should be fully covered with unit-tests (we suggest using http://github.com/Naltox/ton-contract-executor)
• All methods of sales smart contract should require some extra coins for gas & message fees and should return not used coins to the initiator.
• developers should provide some code for setting-up smart contract & for invoking methods

User Stories

In case technical requirements are not enough to understand the usecases, we have user stories set up. Teams ready to deliver Stage 2 will get preferences.

User stories: Stage 1

Stage 1 describes basic MVP capable of accepting bids and settling the auction.

Seller perspective

Feature: auction kick-off

As a seller

I want to start an auction with my NFT

So I can promote this auction and eventually sell NFT

Scenario: user setups an auction

Given seller has Tonkeeper, NFT and 1 TON

And seller knows the initial price and reserve price

Then user signs message with Tonkeeper

Then contract gets deployed

And user is able to find contract on blockchain explorer

Feature: settling auction

As a seller

I want to put up NFT for sale and sell it

So I transfer NFT to contract and get money some time later

Scenario: user sells NFT

Given auction contract is deployed

And a bid greater than initial price was made

And seller signs the message to accept the bid

Then buyer gets NFT, seller gets the money, auction contract gets destroyed

Scenario: user sells NFT by reserve price

Given auction contract is deployed

And contract gets a bid

And a bid greater than reserve price

Then buyer gets NFT, seller gets the reserve price, auction contract gets destroyed, bidder gets the remaining sum if bid was greater than reserve price

Feature: auction shutdown

As a seller

I want to shutdown an auction with my NFT, so I get it back

So I can get tons of hate

Scenario: user shutdowns an auction

Given contract is deployed

And seller signs the message with Tonkeeper and pays 0.42 TON

Then auction gets shutdown

And all the bids are returned to bidders

And NFT is returned to the seller

Bidder perspective

Feature: bidding

As a bidder

I want to bid on NFT lot

So I can buy NFT

Scenario: bidder makes a correct bid

Given bidder has Tonkeeper, and n TON

And bidder signs the transaction and transmits it

And auction has initial price or higher bid < n

Then contract accepts the bid

Scenario: bidder makes an incorrect bid

Given bidder has Tonkeeper, and n TON

And bidder signs the transaction and transmits it

And auction has initial price or higher bid > n

Then contract returns the bid -0.42% commission (tax for inaccuracy)

Scenario: bidder gets outbid and forfeits 

Given Bidder 1 made a bid

And Bidder 2 makes a bigger bid

And Bidder 1 forfeits

Then auction settles

Then Bidder 1 gets bid back

Scenario: bidder gets outbid and bids again 

Given Bidder 1 made a bid

And Bidder 2 makes a bigger bid

And Bidder 1 keeps bidding

Then Bidder 1 increases the bid by sending more TON to the contract

User stories: Stage 2. Timer

Stage 2 suggests improvements to the original concept, covering a timeout to deal with auction sniping https://en.wikipedia.org/wiki/Auction_sniping. Regular grant applications might ignore this Stage.

Seller perspective

Feature: settling auction by timeout (anti-sniping deadline)

As a seller

I want to put up NFT for sale and sell it

So I transfer NFT to contract and get money some time later

Scenario: user sells NFT by timeout without competition

Given auction contract is deployed

And bid was made not less than 5 minutes prior to deadline

And a bid greater than initial price was made

And deadline has passed

Then buyer gets NFT, seller gets the money, auction contract gets destroyed

Scenario: user sells NFT by timeout with competition

Given auction contract is deployed

And bid was made less than 5 minutes prior to deadline

And a bid greater than initial price was made

And deadline has passed

Then auction gets prolonged for 10 minutes