Auction
Auctioning piggies

The native sale mechanism for SmartPiggies is a form of Dutch auction, whereby the holder of a token may elect to define a starting price, minimum reserve price, price step, and time step, subsequently marking the piggy as "for sale." When this auction mechanism is activated, the token will hold a Dutch auction for itself: the initial price will be the starting price specified by the holder, which will decrement along the slope defined by the ratio of the price step to the time step, until it meets the reserve price.
After a piggy has been created it can be put up for auction adhering to this structure. An auction also defines a length (in seconds), in which the auction is valid. If the auction has expired, no one will be able to purchase the piggy. The seller will need to re-auction the piggy. An auction cannot extend beyond the expiry of the piggy. If an auction length is supplied, which is past the piggy expiry, the transaction to place that piggy on auction will fail. If no one finds this particular piggy desirable, the seller can end the auction, and burn the piggy, reclaiming the collateral, to create another piggy with more desirable characteristics.
The native sale auction parameters consist of the following:
Native Sale Auction
Parameters
Token ID
1
Starting Price
$100
Reserve Price
$20
Auction Length
86400 seconds
Time Step
30 seconds
Price Step
$1
Limit Price
$1699
Bid Limit Set
true

This native purchase capability is provided by two functions in the contract. The first function is the same auction function used for native sale, with the same parameters: starting price, reserve price, time step, price step, auction expiry, and a boolean indicating whether or not the auction is active. The difference is in the nature of the auction when activated for a token in the RFP state: whereas the native sale mechanism uses a Dutch auction format, the native purchase mechanism is a reverse Dutch auction. The requestor will specify a low starting "bid" for the premium that she would pay in exchange for the particular SmartPiggies option as defined by variables noted above, along with the extra parameter for RFPs denoting the desired collateral for the option itself.
(Alternate) The native purchase functionality is to be used with the sale of requests (request-for-piggy or RFP). An RFP auction is a native purchase which uses the same parameters as the native sale in the previous section:
Native Purchase Auction
Parameters
Token ID
2
Starting Price
$10
Reserve Price
$100
Auction Length
86400 seconds
Time Step
30 seconds
Price Step
$1
Limit Price
$1761
Bid Limit Set
true
However, the starting price and reserve price are inverted in native purchase format. This is because RFPs undergo a reverse Dutch auction, the seller of this auction will specify a low starting price and a high reserve. As the auction proceeds, the price will increase, until it hits the reserve price. Once the reserve price it reached, the price of this RFP will stay the same, in the above $100, until the auction expires. A purchaser can watch the auction take place and purchase when the request becomes desirable and hits a target premium. If the auction doesn't execute, and no one purchases the RFP, the seller can re-auction it, or update the parameters to make the sale more desirable.
Once the auction expires, no one will be able to purchase the RFP. As with the Native Sale, the auction expire cannot exceed the RFP expiration.
If someone does purchase this RFP, that purchaser will deposit collateral into the RFP, at that point creating a piggy. Once the RFP converts to a piggy, that piggy can be executed for a claim of the collateral. Until an RFP has been fulfilled by a purchaser, the RFP is only a virtual piggy, waiting to become "real."

The last two parameters of an auction, whether it is a native sale or purchase, are optional protection parameters which will create a "bid" auction. Limit Price defines a price at which the underlying must currently be at in order for the auction to execute. This is a bidding process. A purchaser becomes a bidder on the auction. When a bid is placed, an oracle call is made. If the returned spot price from the oracle satisfies the protection limit, the auction will execute, and then succeed. If the price returned from the oracle violates the protection limit price, the bid will fail. The bidder is refunded her bid, and the auction continues.

In the case of a native sale, someone create a piggy (with collateral) and wants to put it up for sale. Taking the example piggy from the Create a Piggy section:
Piggy ID
1
Strike Price
$1500
Max Loss
1000 (USDC)
Lot Size
1
Expiry
June 1, 2021
Auction Start Price
100 (USDC)
Auction Reserve
20 (USDC)
Auction Expiry
May 31, 2021
Protection Limit Price
$1699
This auction will execute as a native sale, following a Dutch auction format where the price will begin at $100. As the auction progresses the price will decrease until it hits the reserve amount of $20. The protection limit for this auction has been set, at a limit price of $1699. This means that this auction will undergo a bidding process. Only one counterparty can bid on this auction.
For example, Alice creates the piggy above and puts it up for auction. Bob wants to the buy the piggy (presumably to protect his ETH position against downside price movements). If the Protection Limit had not been set, Bob can purchase the piggy outright, the premium calculated at the time Bob makes the transaction. Let's say Bob buys the piggy when the price is $50, midway through the auction. Bob will send a transaction with 50 USDC (remember the collateral for this piggy is denominated in USDC) to the SmartPiggies smart contract, and Alice can withdraw the 50 USDC Bob has paid.
Now, when the Protection Limit is set, Bob must first place a $50 bid on the auction. At this point an oracle call is made to retrieve the spot price of Ethereum in US Dollars. Bob makes the transaction to purchase the piggy, sends along 50 USDC to the SmartPiggies contract, and waits for the oracle to return. The oracle returns a price of $1900. This is great, the current spot price of the underlying is above the protection limit for this piggy, and Bob can now finalize the bid, and take ownership of the piggy, whereby he becomes the holder. Alice can now withdraw her 50 USDC.
In this scenario, Alice has placed a protection limit on the piggy because she does not want Bob to be able to buy a piggy that is immediately in-the-money, and can be executed. Alice would like to protect her collateral deposited in the piggy with a condition, if the price of the underlying gets too close to the strike price, this piggy cannot be purchased. This will help Alice (the liquidity provider in this case) manage her risk, and allow her to confidently create long-dated piggies, which also helps Bob if he wants long-term protection.
A note about this example. Remember that the piggy used in this example executes as a classic PUT style option. If the Protection Limit is set, the protection enforces the price getting "too close" to the strike price, or the spot price of the underlying must be above the limit price. If the piggy executes as a classic CALL style option, the protection enforces the price getting "too far" from the strike price, or the spot price of the underlying must be below the limit price.

For the next example, the RFP from the Request a Piggy section can be used to demonstrate the auction of an RFP. The RFP created in that section has the following details:
Piggy ID
2
Strike Price
$1500
Max Loss
1000 (USDC)
Lot Size
1
Expiry
June 1, 2021
Auction Start Price
10 (USDC)
Auction Reserve
100 (USDC)
Auction Expiry
May 31, 2021
Protection Limit Price
$1761
Because this is an RFP, the auction format will follow a reverse Dutch auction, the beginning price is low, and gradually increase over the course of the auction. If Bob wants a piggy that he can not find on the market, he can request one, and see if anyone will fulfill the request. Bob then puts this RFP up for auction, in doing so sends along the reserve amount of USDC in the transaction. Here Native Purchase refers to the idea that someone needs to purchase this RFP, thereby collateralizing it, so that it is useful to Bob. Alice, our liquidity provider, decides that she will fulfill Bob's request, and purchases this RFP.
Again, if the Protection Limit is not, Alice deposits 1000 USDC into the RFP (thereby making it a "real" piggy), and collects Bob's premium. The price Alice receives as premium depends on when Alice makes the purchase. Here, Alice decides that she will fulfill the piggy for a premium of 80 USDC. Alice then waits until the auction price rises to $80. She then makes the transaction securing the 80 USDC.
Now, the Protection Limit in this scenario is set, so Alice first bids on Bob's RFP. The 80 USDC that Alice would have received is locked, until the protection limit can be verified. Alice's bid will initiate an oracle call for the spot price of the underlying, here the US dollar price of Ethereum. The oracle returns a price of $1600. This satisfies the protection limit for Bob's RFP. Alice then finalizes the bid, Alice gets 80 USDC, the RFP is collateralized with 1000 USDC, Bob the original requestor, stays the holder of the piggy, and Alice becomes the writer. Bob is also refunded 20 USDC in the process, as he initially put up 100 USDC as reserve for the auction.
Why does a price of $1600 from the oracle pass the protection limit price? The Protection Limit on RFPs are the inverse of piggies. This request for a PUT style piggy is a limit from Bob's perspective of protection. Here, Bob wants to make sure the price doesn't get too high and therefore pays for a piggy that can never be paid out. If Bob places this RFP up for auction, and the US dollar price of Ethereum goes from $2000 to $20,000, the likelihood of this piggy being useful to Bob is very low. In this way, Bob protects his premium by making sure the price stays under a limit.
If the RFP was a CALL it would be the opposite case than the PUT. Bob would want to make sure the price stays above a certain limit so the piggy remains relatively useful to him. In either case Bob wants to make sure Alice can't come along and take Bob's money without Bob getting the intended benefit of the piggy he is requesting.
The following sections detail each step of an auction in more detail.
Copy link
On this page
Native sale
Native purchase
Protection Limit
Auction Examples
Native Sale or Auction a piggy
Native Purchase or Auction an RFP