# Introduction ## Intro to SmartPiggies SmartPiggies are non-fungible digital contracts that provide their owners with protection against undesirable changes in the price of any asset, product, or service. In traditional finance terms, SmartPiggies could be compared to a capped option. A SmartPiggy can be thought of as a tradable digital piggy bank into which money can be deposited, and which is smart enough to distribute its funds between an owner and creator based on pre-agreed terms. SmartPiggies also have a native self-auctioning mechanism that allows them to globally market themselves, eliminating the need for exchanges. Anyone or any business wishing to protect themselves against unexpected changes in price or who has spare capital and is willing to take on risk in exchange for a premium may wish to participate in the SmartPiggies ecosystem. # Accessing Testnet Smartpiggies has a Testnet version of the platform for testing purposes running on the Arbitrum Rinkby. Arbitrum Rinkeby docs: SmartPiggies Testnet: Rinkeby Ether Faucet: When bridging Rinkeby ETH please make sure you are connected to Rinkeby (layer 1 testnet) and transferring funds to RinkArby (layer 2 testnet) ![](/files/-MiXCAbbMX4pUMUM0UPW) The Testnet version of the SmartPiggies application has a TRFL Faucet. TRFLs are testnet stable tokens that can be used to collateralize and buy SmartPiggies. ![](/files/-MiXCrWbOfGthRmEjCac) # What is a SmartPiggy NFT? Prerequisite background reading: [What is a Financial option?](/getting-started/what-is-a-piggy/background-what-is-a-financial-option) "Decentralized options offer the potential to protect against changes in the price of a broad spectrum of assets, well beyond the scope of traditional options offered to retail investors today. Using these options, a pig farmer could protect against movement in the prices of gasoline, livestock feed, or agricultural output, a small import-export business owner could hedge against fluctuations in exchange rates for local currency, and a cryptocurrency trader could insure the value of a portfolio. For any asset, product, or service with a suitable price feed, a decentralized option offers protection against unexpected fluctuations in that price, enabling individuals to manage risk in their personal finances and business ventures." Made possible by : * Smart contracts * ERC-20 stable tokens * Decentralized oracles Inspired by: * ERC-721 NFTs An ERC-721 is a framework to describe a standard for non-fungible tokens on the Ethereum network. The specification of this standard can be found here: \ NFTs are like [ERC20](https://eips.ethereum.org/EIPS/eip-20) tokens but they differ in their uniqueness. ERC20 tokens are identical to each other, where ERC721 tokens are different from every other ERC721 token. SmartPiggies are NFTs that anyone can create on the Ethereum network. Each "piggy" is a non-fungible token, with value locked inside. The value locked in each piggy are a special kind of ERC20 token, called "stable tokens." Stable tokens are ERC20 tokens that are generally convertible in a one-for-one fashion for a currency, e.g. Dollars, Euros, or Yuan. [USDC](https://www.circle.com/en/usdc), a digital dollar stable token, is one example of an ERC20 token, issued on Ethereum, that can be freely, and consistently, traded for US Dollars. 1 USDC is always and forever equal to 1 US Dollar. These stable tokens are deposited into a non-fungible piggy when someone creates a piggy. These stable tokens are then locked inside the piggy, and under certain conditions, the piggy can be "broken" open so that the stable tokens can be taken out. Taking out, or "withdrawing," the stable tokens or funds from a piggy is an automagic process that a user can execute if favorable conditions develop for the owner of the piggy. Non-fungible piggies can be "broken" open under certain conditions. This process is similar to how traditional financial options execute. For example, Alice can create a non-fungible piggy that follows the dollar price of Ethereum (or **anything** really), and deposits 100 USDC into the piggy. This piggy is non-fungible, and therefore not like any other piggy. Even if Bob created a piggy to follow the dollar price of Ethereum, with 100 USDC locked inside, Alice and Bob's piggies would be different from each other. And even if they were parameterized to execute exactly the same, they would have different token IDs. Alice, with her ETHUSD piggy, can put it up for auction, where anyone with access to the Ethereum network can purchase it. Let's say Alice is selling protection, or insurance, against the Ethereum price in US Dollars moving lower, i.e. ETHUSD is $100 and the piggy will payout if the price goes below $80. Carol is looking for exactly this protection, to insure her ETH holdings. After Alice places her piggy on auction, Carol can buy it. And if the price of ETHUSD goes below $80, Carol can break open her piggy, while the SmartPiggies smart contract automagically distributes the winnings to Carol and the remaining funds to Alice. Alice is the creator or writer of the piggy, and Carol is the holder. ![](/files/-Mf4ewNk8UTaaP1Rj0Oq) SmartPiggies are peer-to-peer, non-fungible tokens that hold value in the form of stable tokens, and can be opened under parameterized conditions. They can be created, auctioned, cleared, and settled without intermediaries. This is all done on the Ethereum network. # Background: What is a financial option? In the simplest terms, an options contract is very much what it sounds like: the right (but not obligation) to purchase or sell an asset at a fixed price at some point in the future. Because options rely on a reference asset (called the "underlying"), they are said to be a type of "derivative" asset – they derive their value from the value of the underlying. **Call Option** A Call Option is a contract that allows the holder to **purchase** the underlying asset in the future. **Put Option** A Put Option is a contract that allows the holder to **sell** the underlying asset in the future. **Cash Settled vs. Physically Settled** Physically settled options oblige the seller to deliver the actual underlying if the option is executed. Upon execution of a cash settled option a calculation is performed and the holder receives the amount of cash they would have had the they delivered/received the underlying and purchased/sold the position on the open market. Cash settled options are often preferred to physical settlement as cash is usually more convenient. Cash allows for leverage and does not require delivering/receiving a physical asset (of uncertain quality) at a certain place and time. Physically settled options on the other hand eliminate the need for fair market price. SmartPiggies contracts are settled in cash. **Strike Price** Strike Price is the price which the contract holder entitled to buy/sell the underlying. **Maturity** Maturity is the date/time at which to optionality of the contract expires. For a SmartPiggies contract, the holder may clear and settle at any time. After maturity, the contract writer is also free to clear and settle the contract. **Capped** A capped option limits the possible profit for its holder. A traditional capped option is automatically exercised by your broker-dealer/banker once the cap is reached. Smartpiggies contracts are not automatic and must be settled by the holder. The contracts are capped because each Smartpiggy is allocated a limited amount of collateral, once that collateral is exhausted, the maximum benefit to the holder has been reached and the holder should take action to clear and settle the contract. Since the failure scenarios ... vs margin .... also flexability ... nft nature Further Reading: Example Real-World Use Cases (Pink Paper) # Where do Piggies live? SmartPiggies are non-fungible tokens that live on the Ethereum network (well, technically on L2, more on this below). They are "smart" piggy banks that hold value, and can be "broken" open under certain conditions in the future. The creation, auctioning, and execution of SmartPiggies are handled by a smart contract on the Ethereum network. There is no third party responsible for the interaction between users of smart piggies, all interaction is peer-to-peer. The SmartPiggies contracts are deployed on the Arbitrum network which is layer 2 extension of the Ethereum network. The smart contract that describes the rules of SmartPiggies, from creating a piggy to claiming payouts, can be found here. (add link to smart contracts) Utilizing the Arbitrum network reduces transaction fee costs to a fraction of Ethereum mainnet while inheriting it's security guarantees and decentralization properties. The demand and growth of decentralized finance (DeFi) on Ethereum throughout 2020 has made transaction fees prohibitive for many decentralized applications (dApps) that use Ethereum as a transaction and execution layer. This has been a consistent and growing concern, most recently evidenced by the yield farming, token swapping, NFT art boom of 2020-2021 $$^{1}$$ . SmartPiggies was conceived as a public, permissionless project allowing anyone with an internet connection to access advanced financial tools, a luxury most in the world are never given. When fees began to increase on Ethereum, the SmartPiggies team became concerned that some users would be priced out of participation in the piggy ecosystem. In view of this, the decision was made to deploy the SmartPiggies contracts on a layer-2 network, bringing the cost of participation more in line with the mandate of the project. A move to a layer-2 solution means that all of the infrastructure moves to the layer-2 network as well. The SmartPiggies team desired the scalability and cost reduction in moving off of the Ethereum mainnet, but still required the security guarantees of the Ethereum network. With these goals in mind, SmartPiggies runs on the Arbitrum layer-2 network, as a scaling solution for Ethereum. Arbitrum offers many benefits, including scaling, and leverages optimistic rollups which inherit the security of Ethereum. ## Footnotes 1 One may also add in Flash Loan and Fee Sniping craze. # Arbitrum Introduction A product of Offchain Labs: https\://offchainlabs.com/ Arbitrum is a true layer 2 solution for Ethereum based on optimistic rollups. In exchange for some ease-of-use trade-offs, transactions on Arbitrum are much faster and cheaper. "Arbitrum is an L2 scaling solution for Ethereum...**"** $$^{1}$$ which uses optimistic rollups to reduce gas fees while offering the security guarantees of the Ethereum network. Rollup explainer: (And how this relates to $$ saved for the user.) In short, all transaction data is made available on mainnet (Ethereum) but optimistic rollups use a separate network (Arbitrum) to perform network calculations. Transaction validity is guaranteed by a crypto-economic challenge process. Network security guarantees are especially important platforms in which users lock up a significant amount of capital for a significant amount of time. While there are other networks and sidechains that are cheaper and faster, Ethereum roll-up solutions (Arbitrum, Optimism, ZKrollups, etc.) offer the highest security guarantees while minimizing transaction costs. Read more about Roll-ups here: Read more about Arbitrum here Arbitrum vs. Optimism: When creating a non-fungible piggy on the Ethereum mainnet, the gas costs were quite demanding. This is due to the amount of information needed to correctly execute a piggy.\ Layer 1 gas costs were running around: ## | Layer 1 action | gas consumed | gas price | fee (ETH) | ETHUSD | fee (USD) | | :------------: | ------------ | --------- | --------- | ------ | --------- | | create | 319408 | 10 gwei | 0.0031941 | $200 | $ 0.64 | | auction | 182889 | 10 gwei | 0.0018289 | $200 | $ 0.37 | | oracle | 211342 | 10 gwei | 0.0021134 | $200 | $ 0.42 | Previously the gas costs and transaction fees were tenable. A lot of gas was consumed when interacting with the SmartPiggies contracts, but the gas costs (\~10 gwei) and Ethereum US Dollar cross rate (\~$200) were low. When everything goes up, so does the transaction fees. When we look at current prices $$^{2}$$ the story changes: | Layer 1 action | gas consumed | gas price | fee (ETH) | ETHUSD | fee (USD) | | -------------- | ------------ | --------- | --------- | ------ | --------- | | create | 319408 | 100 gwei | 0.0319408 | $2000 | $63.88 | | auction | 182889 | 100 gwei | 0.0182889 | $2000 | $36.58 | | oracle | 211342 | 100 gwei | 0.0211342 | $2000 | $42.26 | The fees in the current market have increased by a factor of 100. If gas cost fluctuation is taken into account, when there is a market event and the gas price goes above 200 gwei, settling a piggy goes from $42 to $88 right when one may want to take that piggy action. This does not make for a great user experience. If we look at the reductions from using Arbitrum, we get the following picture: | Layer 2 action | gas consumed | gas price | fee (ETH) | ETHUSD | fee (USD) | | -------------- | ------------ | --------- | --------- | ------ | --------- | | create | 6752 | 100 gwei | 0.0006752 | $2000 | $1.35 | | auction | 5728 | 100 gwei | 0.0005728 | $2000 | $1.16 | | oracle | 2656 | 100 gwei | 0.0002656 | $2000 | $0.53 | Using Arbitrum as a scaling solution, SmartPiggies can be created, auctioned, and settled for under $5. This is more in line with the SmartPiggies mission or bringing access and opportunity, where before there was little to none.
There are other advantages to using a layer 2 solution, for example escaping the code size limitations inherent to the Ethereum mainnet, and yet more advantages to using Arbitrum. For more information, please visit the Arbitrum [docs](https://developer.offchainlabs.com/docs/inside_arbitrum). ## Footnotes 1 2 At current prices as of 2021 # How to use Arbitrum ## The Arbitrum Bridge This will all depend on whether we implement the integrated bridge or not. For now: ## Moving funds from L1 to L2 Actual instructions. ## Moving funds from L2 to L1 Actual instructions. # Parts of a Piggy ## Underlying The underlying is a financial asset (separate from the option itself) to which the SmartPiggy NFT token will refer. ## Collateral Collateral is the type of token that is assigned to the contract and potentially rewarded to the holder. It is also the token for which the contract is sold for during an auction. It is effectively the currency that the contract is denominated in. In the current implementation, the collateral must be a stable token that is pegged to the denomination of the price feed. Examples of such tokens would be DAI or USDC. ## **Lot Size** The lot size is most easily thought of as a "multiplier" on the price of the underlying. SmartPiggy NFT tokens are limited to a lot size of between 1 and 10. ## **Strike Price** The strike price is a benchmark price for the underlying which the actual price will be compared to at the time of exercise to determine the value of the option. When the option is exercised, the current price of the underlying will very likely deviate from the strike price. Depending on which direction it deviates in, and the "directionality" of the option itself, the holder of the option may stand to benefit from the exercise.
## Max Loss (per lot) Max loss is the amount of collateral that the contract writer has locked into the contract. This is the maximum that the contract writer may lose and the holder can can gain (per lot). ## **Expiration Date** The expiration date is the date at which the option may be exercised if the holder chooses to do so. The expiration date is always in the future relative to the time at which the option is written. It is the date on which the strike price and the price of the underlying would be compared to determine the value of the option to the holder at the time of exercise.
## **Direction of Transaction** Lastly, an option may have one of two "directions," which relate to the "direction" (buy or sell) that the holder of the option will have to transact the underlying with respect to the writer of the option. An option contract where the option holder may purchase shares (at the strike price) from the writer is termed a "call" option – the holder of the option may "call in" the shares from the writer of the option at the specified strike price if they wish to do so. An option where the holder would be able to sell shares at the strike price to the writer at the time of exercise is known as a "put" option – the holder may "put" the shares back on to the proverbial shoulders of the writer.
# An example Piggy ### Insurance SmartPiggies can be used as downside price protection in the depreciation of an asset, said another way, as insurance against the price of something going down. This is typically useful when someone holds an asset that they are not interested in selling. A classic example is if Bob holds Tesla stock and wants to continue to hold the stock, but would like to recoup any losses below a certain price, say the price he initially paid for the stock. Bob is willing to pay a premium to someone to provide this protection. Bob enters into a contract with Carol for this protection. Carol agrees to pay Bob if the price of Tesla stock drops below $100. It is up to Carol to decide how much to charge Bob for guaranteeing these conditions. If Bob is willing to pay the premium to Carol, he has insured his Tesla stock holdings if the price per share goes lower than $100. Of course if Bob does not want to pay the premium, he can shop around for other offers, or forego insurance, or sell the stock outright if he thinks the situation is not in his benefit to hold it. For a concrete example lets say Ellinore purchases 32 ETH at $500 to stake it. She pays a total of $16,000 for these assets. Ellinore is planning to hold this ETH for quite some time, with the hope of collecting the staking rewards until ETH 2.0 is launched, which could be two years away. Ellinore wants to hold the 32 ETH for at least two years, but also wants to protect her initial purchase cost for the 32 ETH. She is willing to pay someone a premium for insurance that will cover losses incurred if the price of ETH drops below a certain price. Let's say, for example, that Ellinore is not comfortable if the price of ETH drops below $450. She wants to keep the ETH, but does not like the idea of losing more than $50 per ETH or $1600. Ellinore, then, seeks out some insurance against the price of ETH dropping below $450. Ellinore finds Fran who is willing to provider the insurance. Since Ellinore purchased her 32 ETH, the price of ETH has risen to $600. Fran looks at the price rise, and other factors about the likelihood of ETH falling below $450, and determines a premium for each contract that Ellinore wants to purchase. Fran will agree to insure Ellinore's ETH for $5 per contract. For each contract Ellinore is willing to purchase, she will have to pay Fran an upfront cost of $5 per contract. This will insure Ellinore's initial $16,000 purchase. Ellinore decides that the price is fine, but only decides to cover 30 of her 32 ETH. Ellinore agrees to pay $150 ($5/contract x 30 ETH) for insurance to Fran. Fran will create a piggy that has $10,000 inside it (max payout), which Ellinore can execute if the price of ETH is below $450, for a duration of 3-months, and charge Ellinore $150 for it. This means Ellinore is covered for 3-months if the price of ETH goes below $450, and Ellinore can recoup up to $10,000. Because SmartPiggies are peer-to-peer, the back and forth between Ellinore and Fran is a contrived example. Practically, Fran has made many piggies, with different parameters, and put them up for auction. Ellinore sees a piggy that fits her individual circumstance, a piggy that costs $150 to provide protection against the price of ETH going below $450, which expires in 3-months. This piggy will resemble an American Put option, with underlying ETH:USD, strike price $450, expiry three-months, collateralized with $10,000 USDC. To continue with this example, the price of ETH drops from $600, the price when Fran made the piggy and Ellinore purchased it, to $400. Ellinore doesn't like the price below $450 and decides to execute the piggy, hence break it open and take out some money to offset her loses. Ellinore requests an oracle price, the oracle returns a price of $400. Once that price is received by the SmartPiggies contract, Ellinore or Fran can settle that piggy, in which case the $10,000 USDC held in the piggy is distributed between Ellinore and Fran. The piggy covered 30 ETH at a strike price of $450, therefore 1500 USDC (450-400 x 30) would go to Ellinore as her payout, and the remaining 8500 USDC would return back to Fran. At this point the piggy is settled and can be burned. The agreement between Ellinore and Fran has concluded, completely managed by smart contracts. ### Speculation The opposite scenario can also be provided. If Ellinore thinks the price of ETH is going to the moon, and wants to be compensated if her assertion is proved correct, she can seek out a piggy that pays out if the price of ETH goes above a certain price. Fran is a liquidity provider and makes piggies that payout when the price of ETH is below a certain amount, and also when the price of ETH goes above a certain amount. Fran has made a piggy that pays out if the price of ETH is anywhere above $1000 and auctions them off. Ellinore sees this piggy that Fran has made and wants to buy it. So she does. The price of ETH goes from $600 to $1500, and when the price is $1500 Ellinore executes the piggy. For this piggy Fran only put in 1000 USDC and Ellinore only covered 1 ETH, which means that Ellinore will get 500 USDC, with the remaining 500 USDC going back to Fran \ (1500-1000 x 1 = 500). This piggy would resemble an American Call option. ### Liquidity Providers Wow, this seems great for Ellinore, but Fran seems to be losing a lot of money! Well, Fran is pretty smart, and will either charge a high premium for probable payout scenarios or provide piggies that she determines are unlikely to payout. Fran is going to manage her risk in a way to limit frequent large payouts, or else she will be bankrupt very quickly. Over a long time frame Fran is going to make money by charging premiums for her services, which will offset the cost of capital lockup for her depositing the collateral into the piggies. Fran may provide collateral to piggies that payout every now and again, but on average she determines that she will earn more premium from putting collateral into piggies, than putting her money elsewhere, or letting it sit around. ### Capped Collateral *(A note about the potential upside and downside loss with regard to collateral held inside SmartPiggies)* SmartPiggies are fully collateralized. This has some advantages as well as some disadvantages that should be considered. For Ellinore this is great news. It limits Ellinore's payout, but it also guarantees that if the piggy pays out, Ellinore will get the proceeds. If Fran has mismanaged her capital, and all of her positions move against her, all of her counterparties holding piggies will get paid. If Fran was fractionally collateralizing her agreements with counterparties, her counterparties would not get their expected payout. From Fran's perspective, she is dealing with all of the risk, so she is going to charge for it. Being that SmartPiggies are 100% collateralized, Fran can more accurately manage her risk but also incurs a higher cost of capital. Fran has to put her capital in a piggy, and can't get it out until the piggy expires or the counterparty executes it. This means that Fran is going to be looking at a decent return for putting her capital at risk, and for choosing to put them in piggies rather than somewhere else where her funds may make a better return. SmartPiggies have benefits and costs, but all participants get what they pay for. # Creating your first Piggy ## Creating vs Requesting Piggies can be created **or** requested. Creating a piggy is done by someone providing liquidity, insurance, or otherwise adding inventory, which culminates in putting collateral into a piggy. These created piggies are purchased by those looking to protect their assets or speculatively bet on the future price movements. On the opposite side, someone can request a piggy from a liquidity provider or anyone willing to put collateral into a piggy. When someone puts collateral into a piggy they receive the auction premium offered as a bounty for fulfilling the request. ### Creating a piggy Creating a non-fungible smart piggy involves knowing all the requisite parameters needed, filling in these parameters and formatting them into a data object to be included in an Ethereum transaction. This transaction is sent to the network, and if there are no errors with the transaction, a piggy is made. Creating a piggy requires the following parameters: 1. Collateral Contract Address 2. Oracle Contract Address 3. Arbiter Address 4. Collateral Amount 5. Lot Size 6. Strike Price 7. Expiry 8. Execution Style 9. Direction 10. Request Field The creator of a piggy is referred to as the writer or creator. The purchaser of a piggy is referred to as the holder or owner of the piggy. The creator determines the terms of the piggy, all attributes above, and supplies the collateral for the piggy. The holder purchases the piggy on the market, pays a premium to the writer, and owns the piggy. A holder can transfer the piggy to another account address, split the piggy if it becomes valuable, or re-auction the piggy and sell it to someone else. If the piggy executes as an American style, the holder can request a settlement price at any time, to begin the settlement process and claim a payout. If the piggy executes as a European style, anyone can request a settlement price after it has matured. A holder is the party that **requests** a piggy. If a participant requests a piggy, the piggy is in a "virtual" state, it isn't a real piggy yet. The request is parameterized, but has no collateral inside. The holder is broadcasting interest that she is willing to pay someone else to create this piggy and pay a premium to do so. The holder of a request can then auction the request-for-piggy (**RFP**), associating the RFP with a premium, and whomever fulfills that request, by putting collateral inside that RFP, will gain the premium. This RFP moves from a request to a real piggy, and is now identical to a piggy created in the process detailed in the previous paragraph. An RFP initially has a holder, but no writer. Once the RFP is filled, the fulfiller becomes the writer, and the holder remains unchanged. ### Collateral Contract Address A piggy holds a type of collateral in the form of ERC20 stable tokens. Any ERC20 stable token that conforms to the standard can be used as collateral for SmartPiggies. $$^{1}$$ \ SmartPiggies should only be used with stable tokens as the payout calculations assume that the price of the underlying is the denominated in the same currency that the stable token is pegged to. ### Oracle Contract Address Every piggy has an oracle contract address associated with it. This is the contract that gets called when the holder requests a settlement price for the piggy and also if the seller protection feature has been enabled. When requesting a settlement price, the SmartPiggies contract will call the oracle contract address, and ask for a price. The oracle contract will reply with a price, and this price is used to calculate the payout of the piggy or in the case for seller protection, determine whether the sale is allowed. ### Arbiter Address This field is used for arbitration and is optional. If either counterparty feels the intention of of agreement has been violated, an arbitration process can be engaged. The arbiter address is the account of a trusted third party that can choose to agree with a proposed settlement price by either the holder or the writer of the piggy. This optional protection feature is intended to address incorrect (unintentional or otherwise) prices supplied by the oracle, or if the oracle never responds and a price is never received. ### Collateral Amount This is the amount of collateral the piggy will hold, the maximum payout available to the holder of a piggy, also the maximum loss possible for the writer. ### Lot Size This is the multiplier for the piggy (the number underlings the contract represents). If someone wants to cover 32 ETH, this field will be 32, and the payout will be multiplied by this factor. ### Strike Price This is the execution price of the underlying where by the piggy is "in-the-money" and begins to pay out. When the price of the underlying moves beyond the strike price, the piggy can be settled for a profit. ### Expiry This is the expiration date of the piggy. This is treated as a unix timestamp that is checked to determined if the piggy is mature. As blockchains progress in discrete time events represented as blocks, the timestamp is a soft expiration constraint. The piggy expires after a timestamp, because of this, it is possible for a gap to occur where by the unix time has passed but the block that would confirm this has yet to be mined. There is no negative consequence of this as the true dependency is that the oracle returns an accurate price at or arounds expiry. ### Execution Style This refers to how the piggy can be settled. Piggies are inspired by classic options contracts, and this attribute determines if the piggy behaves as an American style or European style option. The holder, and only the holder, can settle a piggy before expiration for an American style piggy. No one can settle a piggy before expiration if it is created or requested as a European style. ### Direction This refers to whether the piggy pays out as a classic PUT or CALL option. ### Request Field Is this piggy a request-for-piggy or not. If this field is true, the piggy will be an RFP, if this field is false, the piggy will be a regular, "real" piggy collateralized with tokens. ## Footnotes 1. The EIP detailing the standard for ERC20 tokens on Ethereum does not include a decimals attribute. This, however, is **required** to be implemented to serve as appropriate collateral for SmartPiggies. SmartPiggies will not execute payouts correctly if there is no decimals data supported in the token contract used for collateral. All commonly known and widely used stable tokens implement this attribute on their contracts. # Create a Piggy Refer back to [Parts of a Piggy](/getting-started/parts-of-a-piggy) as required. ## New Piggy ![](/files/-MXmghfWSGZpNVNDlL94) To create a piggy, select the **New Piggy** button on the menu bar. This will open a model which will allow a choice between creating a piggy or requesting a piggy. ![](/files/-MXmh1zCvGG2T_Gpg-o2) Choose **Create** to create a piggy (Requesting a piggy is detailed in the next section). ## Choosing an underlying Selecting **Create** will navigate to a form in which each parameter can be specified. ![](/files/-MXmLik84n_tEAg1_pPM) Click on the drop down menu to choose an underlying. SmartPiggies maintains a set of curated underlyings on the platform. In this example, the Ethereum price in dollars serves as the underlying for the piggy. The underlying selection will also detail the oracle providing the price upon settlement. In this example SmartPiggies will provide the price, as denoted by **SP**. There are other oracle services to choose from, some on-chain, some off-chain. See the **Oracles** section for more details. ## Choosing a collateral Next, select the type of collateral that will be deposited into the piggy. ![](/files/-MXmhfSRT7xeiw3qhuZ5) Click the drop down menu and select a listed collateral. SmartPiggies also maintains a curated set of collateral ERC20 tokens available to be deposited. The collateral choices available on the platform conform to the ERC20 standard, and have been tested. If you would like to choose from a collateral token not listed, contact the team to see if it is possible to add. The SmartPiggies smart contract can also be interacted with directly to supply any parameters not available on the platform at a specific time. The contract is public and permissionless. For this piggy, the Truffle Stable Token is chosen. ### Approving the collateral Collateral must be approved in order to deposit collateral into a piggy. This is a common design pattern in Ethereum, and has to do with the SmartPiggies smart contract depositing the collateral into a piggy on behalf of the user. The contract can only deposit what you confirm, but an approval transaction is needed before a piggy can be created. $$^{1}$$ If approval has not yet been completed for a desired collateral token, use the wallet drop down menu on the top right of the page, and toggle the collateral choices listed. This will initiate an approval transaction. *include picture of this, Toby's laptop can't see this section of the website.* We make a single, high-value approval. (Amount?) TODO: Picture from PP. The approval can be revoked at any time using the associated wallet switch. (Or by using or .) ## Choosing the parameters Following the collateral, the next set of execution parameters can be selected. ![](/files/-MXmMvk3nP4uIdk_uDn4) Select a **Strike Price** for the piggy. **This will determine the direction of the piggy.** If the strike price is above the spot price of the underlying, the piggy will execute as a CALL option. If the strike price is set below the spot price, the piggy will execute as a PUT option. The current example will be a PUT, as the date it is being created the spot price of ETH/USD is $2000. As the piggy is in-the-money when the price descends below $1500, this piggy will execute as a classic PUT option would. The **Max Loss** is the total amount of collateral that will be deposited into the piggy. Please be sure that your wallet has approved this collateral transfer to the SmartPiggies smart contract, and that you have enough collateral described by the parameters. Otherwise the transaction will fail. Next choose the **Lot Size** and **Expiration**. ![](/files/-MXmPqyPzUM3uBOoJN5g) **Lot Size** is the multiplier for the piggy. This represents the contracts covered by the piggy, and during settlement will factor into the payout. In the current example, the piggy will execute as a PUT option, with a strike at $1500. The **Max Loss** is $1000, this is the total amount of payout available to holder of this piggy. If the price of Ethereum went to $1000, and the holder settles the piggy, the payout would be ((Strike - Spot) \* Lot Size) and in our example equate to $500 ((1500-1000) \* 1). If the **Lot Size** had been 2, the payout would have been $1000. Note that this is the **Max Loss** of the piggy. The holder gets the full collateral deposited into the piggy and the write receives no difference. If the **Lot Size** had been 4, the Max Loss is reached much faster. When the **Lot Size** is 4 the collateral is depleted when the Ethereum price hits $1250 ((1500 - 1250) \* 4). This means the holder could have executed the piggy at $1250 for a payout of the **Max Loss**, or could have still executed at $1000, but the payout would be the same. The maximum payout of the piggy is $1000. ## Payout Triangle To visualize how a piggy pays out, when creating a piggy, the **Payout Triangle** can be used. Payout with a **Max Loss** of $1000 and a **Lot Size** of 1 ![](/files/-MXhGfyGEi1N6qSEuuJS) Payout with a **Max Loss** of $1000 and a **Lot Size** of 2 ![](/files/-MXhGqkfPu-b6j6fvmLu) Payout with a **Max Loss** of $1000 and a **Lot Size** of 4 ![](/files/-MXhGxfRhSFnCcPp16Pn) The payouts react differently depending on the **Lot Size**. ## Expiration The piggy is only valid for a certain duration of time. There is no limit to this time frame, only that it needs to be in the future. The expiration is represented as a Unix Timestamp. Click on the **Contact Expiration Date** field to set a date. This prompts with a calendar for easy selection. ![](/files/-MXmPQbDxaEBziZdhFap) A piggy does have second resolution, but keep in mind that the timestamp is extracted from the block, so there will be small gaps between the time a piggy may expire in seconds, and the block representing the passage of that time. See the **Expiry** section in **Creating your first Piggy** for more information. ## Setting the auction parameters The piggy isn't going to do any good if no one can see it. To offer the piggy to anyone who may need it, the piggy must be placed on auction. To auction the a piggy specify the start price, reserve price, and auction expiration date: ![](/files/-MXmkaZiSmkpkwIykLnm) A piggy undergoes a dutch auction, where by the price starts high, and decreases over the duration of the auction. Here, the Start Price is $100 and will decrease to $20, the reserve. If no one buys the piggy before the reserve is hit, the piggy will remain at a price of $20, until someone does buy it, or the auction expires. This auction will be valid until May 31st, 2021. After the expiration no one will be able to purchase the piggy. ## Protecting the piggy You can protect the piggy from price movements during the auction by setting a **Protection Limit**. This will make the piggy un-purchasable if the price gets too close or exceeds the **Strike Price** during an auction. Select the toggle next to the **Create & Auction** button to activate the fields. ![](/files/-MXmivjYswrQO-0_v8ee) In this example, the piggy executes as a PUT option with a **Strike Price** of $1500. If the piggy is on auction, and there is an extreme market event that drops the price below $1600, this piggy can't be purchased. The price must be above $1699 in order for someone else to buy it. Of course if someone is already the holder of a piggy and there is a market event that moves the price of Ethereum to $1000, the holder, already owning the piggy, can execute. But if this situation occurred and the piggy was on auction, the piggy is insulated from this event, and the writer protected against this volatility prior to a counterparty purchasing it. ## Create it! Click on the Create & Auction button to send the transaction to the network. The user wallet will pop up to confirm the transaction. ![](/files/-MXmmOtIXMLGGWwPzIto) ## Footnotes 1. Note that it is possible for a malicious application to approve a large amount of tokens on behalf of a user, and attempt to trick the user into transferring more tokens than expected, or having a large approval can open the user to attacks if the contract is exploited. The SmartPiggies platform does approve a large amount, this is done for convenience so that user doesn't have to make an approval every time a piggy is created. However, the user **must** confirm any transaction, firstly, and second, please be aware of the transfer amount listed on the transaction. Confirm the token amount being transferred. If something looks wrong, **do not** confirm the transaction on MetaMask. # Request a Piggy TODO: Draw comparison to tradfi over-the-counter markets? Requesting a piggy signals interest in an underlying with specific execution parameters. Where creating a piggy may frequently be done by liquidity providers (i.e. those who want to make the premia by collateralizing piggies), requesting a piggy is done by those looking for protection or speculation on something not widely available, or currently unavailable. This could take the for form of a particular constraint, for example, a very long dated piggy, or a unique or very specific underlying, that is not offered, as in input costs for a business. As long as there is a reputable way to access the price of the underlying, a piggy can be requested. The process for requesting a piggy, request-for-piggy or RFP, is similar to the steps for creating a piggy, with the difference being the collateral and premium. With an RFP, collateral is not deposited into the piggy, this is done when someone fulfills the request. However, upon successful creation of a request, the user will want to put the RFP up for auction so someone else can fulfill it. When an RFP goes up for auction, a premium is sent along with the auction, this is the compensation someone will receive when they fulfill the RFP. ## New Piggy To request a piggy click on the **New Piggy** button on the menu: ![](/files/-MXmghfWSGZpNVNDlL94) This will open a model offering the choice to Create or Request a Piggy. Choose **Request**. ![](/files/-MXmI2Im5lUnqBk2_jEt) ## Choosing an underlying Selecting Request will navigate to a form in which each parameter can be specified. ![](/files/-MXmLik84n_tEAg1_pPM) Click on the drop down menu to choose an underlying. SmartPiggies maintains a set of curated underlyings on the platform. In this example, the Ethereum price in dollars serves as the underlying for the RFP. The underlying selection will also detail the oracle providing the price upon settlement. In this example SmartPiggies will provide the price, as denoted by **SP**. There are other oracle services to choose from, some on-chain, some off-chain. See the **Oracles** section for more details. ## Choosing a collateral Next, select the type of collateral that will this RFP will require to be deposited when it is fulfilled. ![](/files/-MXmhfSRT7xeiw3qhuZ5) Click the drop down menu and select a listed collateral. SmartPiggies also maintains a curated set of collateral ERC20 tokens available to be deposited. The collateral choices available on the platform conform to the ERC20 standard, and have been tested. If you would like to choose from a collateral token not listed, contact the team to see if it is possible to add. The SmartPiggies smart contract can also be interacted with directly to supply any parameters not available on the platform at a specific time. The contract is public and permissionless. For this piggy, the Truffle Stable Token is chosen. ### Approving the collateral For an RFP, the requester does not deposit any collateral, so an approval is not needed. When the RFP is auctioned, so as to make it available to be fulfilled by a counterparty, an approval would be needed, as the premium is denominated in the collateral type. This is explained in more detail under the **Lifecycle of a Piggy** section under **Auction**, but briefly which ever collateral has been selected for a request, is also the token used for premium on the auction. ## Choosing the parameters Following the collateral, the next set of execution parameters can be selected. ![](/files/-MXmMvk3nP4uIdk_uDn4) Select a **Strike Price** for the RFP. **This will determine the direction of the RFP.** If the strike price is above the spot price of the underlying, the RFP will execute as a CALL option. If the strike price is set below the spot price, the RFP will execute as a PUT option. The current example will be a PUT, as the date it is being created the spot price of ETH/USD is $2000. As the piggy will be in-the-money when the price descends below $1500, this RFP when it becomes a piggy will execute as a classic PUT option would. The **Max Loss** is the total amount of collateral that will be deposited into the piggy when it is fulfilled. Next choose the **Lot Size** and **Expiration**. ![](/files/-MXmPqyPzUM3uBOoJN5g) **Lot Size** is the multiplier for the RFP. This represents the contracts covered by the RFP, and during settlement will factor into the payout. In the current example, the RFP, when it becomes a piggy, will execute as a PUT option, with a strike at $1500. The **Max Loss** is $1000, this is the total amount of payout available to holder of this RFP, the requester in this case. Assuming the RFP becomes a piggy, if the price of Ethereum went to $1000, and the holder settles the piggy, the payout would be ((Strike - Spot) \* Lot Size) and in our example equate to $500 ((1500-1000) \* 1). If the **Lot Size** had been 2, the payout would have been $1000. Note that this is the **Max Loss** of the piggy. The holder gets the full collateral deposited into the piggy and the write receives no difference. If the **Lot Size** had been 4, the Max Loss is reached much faster. When the **Lot Size** is 4 the collateral is depleted when the Ethereum price hits $1250 ((1500 - 1250) \* 4). This means the holder could have executed the piggy at $1250 for a payout of the **Max Loss**, or could have still executed at $1000, but the payout would be the same. The maximum payout of the piggy is $1000. You can see this in the **Max Loss** price tag: ![](/files/-MXmOQCotQeTNO9M2-Hx) The piggy is only valid for a certain duration of time. There is no limit to this time frame, only that it needs to be in the future. The expiration is represented as a Unix Timestamp. Click on the **Contact Expiration Date** field to set a date. This prompts with a calendar for easy selection. ![](/files/-MXmPQbDxaEBziZdhFap) A piggy does have second resolution, but keep in mind that the timestamp is extracted from the block, so there will be small gaps between the time a piggy may expire in seconds, and the block representing the passage of that time. See the **Expiry** section in **Creating your first Piggy** for more information. ## Setting the auction parameters The RFP isn't going to do any good if it doesn't get fulfilled. To get it fulfiller it needs to be placed on auction so that someone else can put in the collateral, and make this request a "real" piggy. To auction the RFP select the start price, reserve price, and auction expiration date: ![](/files/-MXmR2T2r_9Bvl0JNyjP) Note that for RFP auctions, the Start Price is less than the Reserve Price, because RFP auctions are conducted as a reverse dutch auction. Hence, the price begins low and increases over time, until the price reaches the reserve. At this point the RFP is ready to send to the network. However, in this example, the protection will be demonstrated. ## Protecting the RFP You can protect the piggy from price movements during the auction by setting a **Protection Limit**. This will make the RFP un-fillable if the price gets too close or exceeds the **Strike Price** during an auction. Select the toggle next to the **Create & Auction** button to activate the fields. ![](/files/-MXmRvNwH9W2WgYmAcBp) This will drop down the **Protection Limit** parameter. The protection limit can be adjusted to protect the premium of the requester if the price of the underlying moves in such a way that would render the RFP un-usable. For example, in the above, if the price of Ethereum reaches $1761 from the $2000 spot price, the RFP can be purchased. As long as the price is above $1761 this RFP is not purchasable. This protects the premium the requestor is willing to pay for the RFP, in the event that the price moves significantly upwards. For instance, a requestor may not offer to pay as much for a PUT RFP with a strike price of $1500, if the price of Ethereum is $20,000, as the likelihood that the price moves from $20,000 to $1500 is low. The requestor, however, may be willing to pay a lot for the same PUT RFP if the price of Ethereum is currently $2000. The protection limit on an RFP becomes a trigger of when that RFP is available to be fulfilled, while protecting the requestor's interest in the RFP. ## Push the button Click the **Create & Auction** button to launch the wallet connected to the site, and confirm the transaction to complete the request! ![](/files/-MXmgBT48zGxx8V0wc7F) # Approve Collateral Allowing SmartPiggies to hold the collateral A first step which must be observed before buying, selling, or creating any piggies is to approve the collateral that is to be transacted in. When creating a smart piggy, collateral is transferred from the creator's account to the SmartPiggies' smart contract. $$^1$$ In order for this to take place, the SmartPiggies smart contract must be authorized to make this transfer. In addition to this interaction, all purchases of piggies on auction are denominated in the collateral locked in the piggy. For example, if a piggy pays DAI, when a piggy is on auction, the auction premium is paid in DAI. Consequently, the buyer must approve the collateral to be sent from their account to the seller's account. This is facilitated by the SmartPiggies smart contract, and therefore the buyer must first approve the collateral token that will be used for payment, before the purchase can be executed. $$^2$$ To approve collateral, switch the toggle next to the desired token listed under the **Manage Wallet** dropdown menu: ![](/files/-McQ0BrDtpmN0AHVpYBB) The **Manage Wallet** menu will list all collateral tokens available on the SmartPiggies application. In the above graphic, Truffle Token $$^3$$ is approved. Any unapproved token will show the toggle in the left position. To make the approval, click on the toggle, and confirm the transaction. This transaction will cost a small fee, however, the transaction will "approve" a large enough amount of tokens, which allows these approval transactions to be made sparingly. Once the approval amount is depleted (this amount is reduced during each transfer), an approval will need to be made again. The SmartPiggies application will only list certain collateral tokens. These tokens have been tested, and authorized for use on the SmartPiggies platform. It is recommended to use only homologated tokens with SmartPiggies, however any ERC20 token, that includes a **decimals()** function, can be used. Note that an approval must be made for each collateral token a user may want to participate with. If a buyer wants to buy a piggy that holds DAI and another that holds USDC, an approval must be made for both DAI and USDC. ## Footnotes 1 Tokens are technically not sent to the SmartPiggies smart contract. Technically ownership rights are just transferred on the token's smart contract. In this example, the ownership rights of the token are changed from the creator/writer to the SmartPiggies smart contract. When the creator withdraws the collateral after settlement, the ownership rights of the tokens are assigned back to the creator's Ethereum account. 2 Again, technically the buyer doesn't "send" tokens to the seller. In an auction, the ownership rights of the tokens are updated on the smart contract of the specific ERC20 token being used. 3 Truffle Token is a SmartPiggies ERC20 token primarily used for testing at this phase. There are additional uses being explored by the team for these tokens, but at this stage these tokens are purely used for educational purposes. # Auction Auctioning piggies ## Native sale 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 | ## Native purchase 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." ## Protection Limit 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. ## Auction Examples ### Native Sale or Auction a piggy 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. ### Native Purchase or Auction an RFP 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. # Buy Purchasing piggies on auction SmartPiggies that are on auction can be purchased from the "Explore Markets" tab on the SmartPiggies app. To purchase a piggy from the market, navigate to the market explore by clicking the "Explore Markets" tab: ![](/files/-MbbRG3MTVaJzQcKk-5P) The Explore Markets section lists all piggies for sale. Once there, anyone can purchase a piggy that appears in the market. If you find a piggy that meets your requirements, click the "Buy" button to purchase: ![](/files/-MbbSYflJSXAXwUqCS4U) This will prompt a confirmation model to approve the purchase, and make an on chain transaction. Once the transaction has been confirmed, you will become the holder of the piggy, which will confer all rights of the owner to the transacting account (e.g. if the piggy executes as an american style option, you may call an oracle to settle the piggy prior to expiry and collect any payout). Piggies for sale are denominated in the collateral tokens deposited in the piggy. If the piggy settles in DAI, the premium to purchase the piggy will be paid in DAI. This requires that the buyer have enough DAI in their wallet to cover the purchase price, as well as enough ETH to cover the transaction fee $$^1$$ . If a user is going to purchase a piggy with DAI, the user must approve transfer of the token on behalf of the SmartPiggies smart contract. This is the standard approval process for most ERC20 tokens. Piggies are listed in either the **Available Contracts** section or the **Requested Contracts** section. If a piggy appears in the **Requested** section, the piggy is a Request For Piggy (RFP) and is waiting to be "filled" with collateral from anyone wanting to provide liquidity for that piggy. In this section, the piggies will be able to be filled, where by collateral is transferred, from the fulfiller, into the piggy. In these types of purchases, the owner remains the requester, and the writer becomes the fulfiller (or this purchaser). To buy an RFP, click the "fill" button on the RFP: ![](/files/-MbgpftYV7XiYChABa0m) The "purchaser" in this scenario is taking the premium being offered from the requester, which increases as the auction proceeds, and deposits collateral into the piggy. This is in effect creating or instantiating a piggy. Because the piggy is being funded, the fulfiller will need to have the available collateral to deposit (as well as making sure that the collateral is approved to be transferred on behalf of the SmartPiggies smart contract). Once the RFP is funded, it will become a "real" $$^2$$ piggy, where the fulfiller/purchaser will become the underwriter, and the requester will remain the owner/holder, resulting in the piggy now being active. ## Footnotes 1 As the SmartPiggies smart contracts are currently deployed to Arbitrum, the user will need the collateral token on Arbitrum, and ArbGas for the transaction. 2 We make the distinction between "real" piggies and "virtual" piggies, purely for illustrative purposes, as the technical difference between a piggy and an RFP is that an RFP has no writer and no collateral, which we consider to be a pre-piggy, or "virtual" piggy. # Bid Bidding on piggies A piggy may be for sale under a "bid" auction, where the sale of the piggy is protected from price fluctuations in the underlying. If a piggy is under a "bid" auction, it can be bid on by pressing the "Bid" button: ![](/files/-MbghEBoSAQHupzePyne) This will begin the bidding process, where by the spot price of the underlying must be queried from the oracle and confirmed that the oracle price does not violate the protection limit set during the creation of the auction. After the bid has been placed, the piggy will appear in the users Dashboard section, where the user must **Finalize** the bid by initiating an oracle call. Pressing the **Finalize** button will initiate a on-chain transaction to request a price from the oracle. ![](/files/-MbwWU-LmVvyrJa5uMpz) Once the "bid" auction has been finalized, after the oracle has returned a price that does not violate the protection limit (set upon the creation of the auction), the user now owns the piggy. After a piggy is bid on, the piggy will enter a "cooldown" period . The "cooldown" period is an anti-spamming measure to protect against bidders taking piggies under "bid" auction off the market, only to later cancel their bid: ![](/files/-MbwX6s-zDw50j2TGF15) Once the "cooldown" period has completed, the bidder can cancel their bid: ![](/files/-Mc0cm0WyGXDmcJw1qe2) If a piggy is under a "bid" auction and the current spot price of the underlying is currently violating the protection limit set for the auction, the piggy will appear in the "Protected Contracts" section of the market: ![](/files/-MbgnfA0NnGYUY-OHty0) If the spot price of the underlying moves back to where the protection limit is no longer in violation, the piggy will appear in the **Available Contracts** section and can be bid upon. # Finalize Finalizing a bid If a user has bid on a piggy, the next step in securing ownership of that piggy is to "finalize" the bid. The bidding process is set to only complete if the current spot price of the underlying is within a set tolerance, defined at the beginning of the auction. A protection limit enforces that the piggy can only be purchased if the spot price is above or below the limit depending on the direction of the piggy. The protection limit, as detailed in the **Auction** section: > 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. After the bid is placed, the piggy will appear in the user's **Dashboard**, where the piggy is now ready to **Finalize**. Either counterparty can **Finalize** the bid by pressing the "Finalize" button that is now present in the action area of the piggy: ![](/files/-MbwWU-LmVvyrJa5uMpz) This will create an on-chain transaction that will request the current price of the underlying from an oracle. The oracle will make an off-chain query to retrieve the price, and then make an on-chain transaction to send the observed price back to the SmartPiggies smart contract. Once this process is complete, presuming the returned price did not violate the protection limit, the piggy will be in a "cooldown" period. After the "cooldown" is complete the piggy can be cleared. # Clear Clearing a piggy by requesting a price from an oracle Clearing a piggy is the first step in the settlement process of a piggy, in which the price of the underlying is retrieved and saved into the piggy. This step is needed before the piggy can be "settled". Settling the piggy is the step where the payout is calculated and distributed. Clearing, then, is the prior step of capturing the clearing price. Because the blockchain is a user-initiated, push technology, a user or other agent initiates actions which change the state of the data on the blockchain. With this view, SmartPiggies requires a two step process for clearing a piggy, and therefore retrieving the price which is used to determine the payout. There are a few condition in which a user can "clear" a piggy: * American Style - holder can clear at any point * American Style (matured) - anyone can clear * European Style - anyone can clear only post maturity For example, if a user owns an American style piggy, she can clear the piggy whenever it is to her advantage, pre or post expiry. If she can secure a payout by requesting the price of the underlying before the piggy expires, she may do so. Prior to expiry, the price retrieved and delivered by the oracle is stored within the piggy, and that price is used to calculate the payout. **This is a one time action and cannot be undone.** If the price continues to move in the owner's favor, another oracle call (via clearing the piggy) will fail. The clearing price is locked at this point. If for any reason the returned price is unacceptable (do to a garbage value or otherwise corrupted data returned from the oracle) the **arbitration** process is available to reconcile a breakdown in the natural process of settling a piggy. To **Clear** a piggy click the "clear" button on the piggy: ![](/files/-McG8juEnWNRranIpsWQ) Once a "clear" transaction has been processed, and the price returned from the oracle is saved in the piggy, the **Settle** step can be executed. In traditional options markets, options are rarely executed. Although piggies can be settled via a third-party oracle, and all execution can be done without the need for the writer to participate in the settlement process, SmartPiggies would expect that clearing piggies is a rare practice, as selling a piggy back to the writer may be more advantageous among the counterparties. When the counterparties do not agree on some aspect of the settlement process, the oracle may be engaged to conclude the contract. But as this incurs extra costs, we would recommend piggies be sold back to the writers for payout when necessary, rather than settled via oracle execution. # Settle Finalizing the payout After a piggy is "cleared," the settlement process can be completed by "settling" a piggy. If any funds are owed to the holder of a piggy, this phase will distribute funds between counterparties. If the piggy expires out-of-the-money (no payment is owed to the holder), the writer of the piggy can "settle" the piggy to get back the collateral locked inside. This phase distributes the collateral, and must be complete by some agent $$^1$$ for the collateral to be assigned from the SmartPiggies smart contract to either the holder of the piggy, the writer of the piggy, or a split between counterparties. In order to **Settle** a piggy, the piggy must be have previously be "cleared." Once the piggy is cleared, and the piggy has received the clearing price from an oracle, the piggy can calculate the payout and disburse the collateral among the counterparties. When the piggy has been "cleared" the piggy will be available to "settle": ![](/files/-McG8B4qtOLRp9E9tpSW) ## Footnotes 1 After a piggy has been cleared, anyone can "settle" it. The party could be a good Samaritan if they are not privy to benefit from the payout, or the agent can be the holder or writer of the piggy. # Claim payout Retrieving funds from SmartPiggies There are a few ways in which a user may be owed funds from the SmartPiggies smart contract. If a writer creates a piggy that no one is interested in purchasing, the writer may burn that piggy, where by the collateral locked inside the piggy is assigned back to the writer. If a counterparty purchases a piggy on auction, the premium paid for the piggy is assigned to the seller. If a holder of a piggy executes the piggy pre or post maturity, and the holder is owed a payout that does not exceed the collateral locked in the piggy, both counterparties are owed an amount of the collateral. In all of the circumstances above, collateral tokens are held by the SmartPiggies smart contract $$^1$$and assigned to the account of the owed party. If any party has an outstanding balance on the SmartPiggies smart contract, he or she can claim the balance, thereby reclaiming ownership rights of those tokens. To claim a balance held on the SmartPiggies smart contract navigate to the **Manage Wallet** drop down menu. If the account does not have an outstanding balance, the default wallet menu is displayed. When the account does have an outstanding balance a claim button will appear: ![](/files/-McQ-bL3yiRPmFQ0s-dG) Clicking the "Claim" button will initiate an on-chain transaction to transfer the tokens back to the connected account. ## Footnotes 1 The SmartPiggies smart contract doesn't technically own or hold the tokens, but rather has ownership rights of a certain amount of tokens on the token smart contract. # Burn - Reclaim collateral Returning tokens from SmartPiggies Whenever a piggy is created, it must be destroyed. This can happen just after creation or upon completion of the piggy life cycle. If a writer creates a piggy that has some mistake, like a mistyped parameter for instance, and the writer does not want to auction the piggy, she may burn the piggy, thereby deleting all the parameters and reclaiming the collateral that was sent to the piggy. In this scenario, the writer will still need to **Claim** the collateral from the SmartPiggies smart contract, but the piggy will cease to exist. $$^1$$ After a piggy has been settled, the piggy can be burned as well. All of the parameters of the piggy will be zero'ed out, and the piggy will be burned, whereby no further action can be taken with regard to it. To **Burn** a piggy, navigate to the **Advanced Functions** tab from the drop down panel on the row of the desired piggy. The drop down panel can be accessed by clicking the switch located to the left of the piggy ID, and then navigate to the **Advanced Functions** tab to view the Burn button: ![](/files/-McVTGI86yfaPg_zMGeU) Then click the "Burn" button: ![](/files/-McVPu-7emT9ag0I6sOd) The piggy will be "burned" and deleted. If any collateral exists in the piggy, it will be returned to the writer, to be claimed. $$^2$$ ## Footnotes 1 The record of the piggy will exist in the contract as a zero'ed piggy, but all reference to ownership and associated collateral will be removed. The piggy is effectively deleted, it isn't active, can't be auctioned, cleared, settled, nor transferred. 2 There are a handful of circumstances when a piggy can be burned and when a piggy cannot. If the writer has never successfully auctioned the piggy, the writer can burn the piggy to reclaim the collateral. Consequently, a holder who requests a piggy, can burn it, if she decides the piggy is not worth auctioning. This will return the premium to the holder. # Transfer A SmartPiggy NFT is owned by it's holder. As such, it may be freely transferred to another holder. In the SmartPiggy app, the 'Transfer' function may be accessed by expanding the details of your contract and selecting the 'Advanced Functions' tab. ![](/files/-MhyyxN1FLKxyTWFOORS) ![](/files/-MiHtlRK6J72Ew-NDxtW) # Split A SmartPiggy NFT may be split into two contracts with differing amounts of collateral. The amount of protection will be distributed between the two new contracts but all other contract parameters will remain the same. In the SmartPiggy app, the 'Split 'function may be accessed by expanding the details of your contract and selecting the 'Advanced Functions' tab. ![](/files/-MiHsl97tGyvICzyFBef) ![](/files/-MiHt3kTk2PkMTnPVoSg) # Explore Markets SmartPiggies view of available piggies for sale The **Explore Markets** tab will show all piggies that are available for purchase. ![Markets view when wallet not connected](/files/-Mi-W14BBWVY35CmZZdF) If an Ethereum wallet is not connected to the application, the markets view is the only tab available. Note that piggies can only be purchased from the markets sections with a connected Ethereum wallet. If a piggy has been created or requested, and put up for auction, that piggy will be listed on the markets page. The piggy market is a filtered view of the SmartPiggies smart contract listing piggies that are available to buy. The markets page is a view port of what is available to buy from the perspective of the signed in account. The markets page **will not** show piggies on auction from the signed in account.$$^1$$ ![](/files/-Mi-VSit6lKtl7fL50y1) The markets view is organized in two sections, **Available Contracts** and **Requested Contracts**. Available contracts are all "real" piggies (piggies that have been created and collateralized) that are on auction, and available to be purchased by the signed in account. Piggies listed in this section can be purchased by clicking the **Buy** button. This will create an on-chain transaction that will prompt a MetaMask confirmation modal. If the transaction completes successfully, the piggy will now list the transacting account as the holder. Requested contracts are all contracts that are waiting to be filled with collateral, and on auction. We refer to these as Request For Piggy, or RFPs. All RFPs are listed in this section. Piggies listed in this section can be purchased by clicking the **Fill** button. When the fill button is clicked, a MetaMask confirmation modal will display confirming the transaction. This transaction will confirm that the purchasing account will transfer the requested collateral to be deposited into the piggy$$^2$$and become the owner of the piggy. The owner will the the underwriter of the piggy, supplying the collateral, and the requestor remains the holder. If the transaction completes successfully, the collateral will be transferred from the transacting account, and this account now has the premium assigned to it.$$^3$$ Once a piggy has been successfully purchased, the piggy will show up in the account holder's dashboard. ## Footnotes 1. If you created a piggy (or requested one) and have put that piggy up for auction, you will not see this piggy listed on the markets page. These piggies are only piggies that are available to you, the signed in account. You cannot satisfy your own auction. 2. Technically there is nothing deposited into any piggy, it is only an accounting update on the token contract defining the collateral. 3. When an RFP is put up for auction, the requestor allocates a premium to compensate a counterparty to put up the requested collateral to create a piggy. This premium is held on behalf of the requestor and assigned to the SmartPiggies smart contract. When a fulfiller adds the requested collateral, the premium is assigned from the requestor to the fulfiller. This is internal accounting which takes place in the SmartPiggies contract. Once the transaction to fulfill a piggy is complete the fulfiller can withdraw the premium from the SmartPiggies smart contract. # Table Dropdown Market table dropdown panels Each piggy listed in the Market sections has additional information available from the dropdown panel, activated from the toggle to the left of the piggy ID: ![](/files/-Mi-bu6-y4XyGgZ-Fdhf) Each table row contains information regarding the specific piggy from the following tabs $$^1$$ : * Charts * Details and Events * Advanced Functions * CounterParty Management * Arbiter History * CounterParty History Each of these tabs may contain information relevant in determining if the piggy is worth purchasing. For example the **Charts** tab lists historical price information aligned with the payout triangle of the piggy: ![](/files/-Mi-dOs8xZp0O7EqDxzg) The **Details and Events** tab list information about the piggy and auction details: ![](/files/-Mi-dpVa0u7qP46m1lat) These tabs are useful in understanding all primary and auxiliary information about a specific piggy up for auction, and may help determine if a piggy is the right choice for a perspective buyer, or fulfiller. ## Footnotes 1. See **My Dashboard** section for more information on each of these tabs. # My Dashboard The user view of all accounted associated piggies The **My Dashboard** view is only available when an Ethereum wallet is connected: ![](/files/-Mi-ge-e3uGsYlIH-T4Y) When connected, the dashboard will display all piggies associated with the connected account. Piggies are displayed in two sections, **Put Contracts** and **Call Contracts**. Any piggy that the connected account is associated with, either as a holder or owner, will be displayed in the Put or Call section, based on the direction of the piggy. For example, the Put section shows all piggies that follow a put contract: ![](/files/-Mi-il-tBfXmfsqUZJAk) The section shows the put piggies, with the above paged to five piggies per page. Each row lists the following fields: * Piggy ID * Underlying * Current Spot Price * Time to expiration * Strike Price * Collateral Type * Amount of Collateral Available * Moneyness * Actions Available * Token Lifecycle **ID**: The Piggy ID is the unique identifier associated with a piggy. Each ID is unique to only one piggy. **Underlying**: The asset that the piggy targets. **Spot Price**: The current price of the underlying. **Time Left**: The time till maturity. **Strike**: The target price in which the piggy begins to pay out. **Collateral:** The type of collateral that will be paid out from the piggy. **Amount**: The total available collateral in the piggy, including the multiplier (or lot size) **Moneyness**: The relative value calculated for the piggy. **Actions**: Current available actions that can be executed on the piggy, which include: * Sell - put the piggy up for auction again * Update Request - if an RFP, change the parameters * Tender - destroy the piggy and recoup the collateral * Finalize - if the piggy is under bid auction, finalize the auction bid to complete the purchase * Clear - request a settlement price from an oracle * Settle - once an oracle price is received, execute the payout **Token Lifecycle**: the current stage in the lifecycle of the piggy
# Table Dropdown additional piggy information panels As seen in the **Explore Markets** section, each piggy has additional information in the dropdown panels with can be seen by selecting the toggle to the left of the **ID:** ![](/files/-Mi3uS4CGpN-x_XNyN5f) The dropdown panels include: * Charts * Details and Events * Advanced Functions * CounterParty Management * Arbiter History * CounterParty History The **Charts** panel contains a historical price chart of the underlying inline with the payout triangle: ![](/files/-Mi3v8LkvYnS0hdOnxi-) The **Details and Events** panel contains the contract details, auction details, and lifecycle details: ![](/files/-Mi3vonxi4uBNCd-Onug) The **Advanced Functions** panel allows access to the Transfer, Split, and Burn functionality: ![](/files/-Mi3wAyBhOXq6ICIaZFt) The **Counterparty Management** panel allows interested parties to engage in the arbitration process: ![](/files/-Mi3wWig_RlGWDpqFPjV) In this panel, a user can view all counterparty account addresses, and propose a settlement price for arbitration if an arbiter has been chosen. The **Arbiter History** panel lists all arbitrations executed by the declared arbiter account. The **CounterParty History** panel lists a history of all interactions performed by the accounts associated with the piggy: ![](/files/-Mi3xP3L7xk6egyN8Mcj) # Wallet wallet management features A user can manage their wallet by clicking on the dropdown menu of the **Manage Wallet** component located on the right side of the header: ![](/files/-Mi3yvp_jQihj7JkNStu) Note that if an Ethereum wallet account is not connected to the application, the **Manage Wallet** component will be replaced by a connect button: ![Connect an Ethereum wallet to access the management features ](/files/-Mi3zS8_S0y-cSohjRSD) From the wallet menu a user can view the connected account and the account balances for Ethereum and all accepted collateral tokens available to use with the SmartPiggies platform: ![](/files/-Mi4-javx6fny_NWfJKz) # Approving Collateral tokens Approve collateral token transfers In the Ethereum token ecosystem a common practice has developed around transferring ERC20 tokens by a smart contract on behalf of a user. In order to create a piggy with the SmartPiggy smart contract the transacting account must first allow the SmartPiggies smart contract to transfer the collateral from the user to the SmartPiggies smart contract. $$^1$$ This approval must be done for each collateral token a user wants to collateralize a piggy with. If a user wanted to make a piggy collateralized with USDC, and an additional piggy collateralized with DAI, that user must make an approval for USDC and an approval for DAI. To complete this approval, the connected account can select the toggle to the left of the desired collateral listed in the **Manage Wallet** menu: ![](/files/-Mi41ygPyKOWjpu2Afkw) In the image above, truffle token (TRFL) is already approved, but chainlink (LINK) is not approved. To approve LINK the connected account can click the toggle. This will prompt a MetaMask confirmation modal. When the transaction has succeeded, that account can use the approved token with the SmartPiggies smart contract. Visit the next section to review approving oracle tokens. ## Footnotes 1. Technically this is only an accounting update to the state of the collateral token smart contract, there are no tokens or Ethereum held in the SmartPiggies smart contract. # Approving Oracle tokens Oracle tokens need approvals too Any token that needs to be transferred to execute a SmartPiggies function must first be approved by the transacting account. This is needed to create piggies, purchase piggies, and also to clear piggies for settlement, **if the oracle declared in the piggy requires a fee**. SmartPiggies offers oracles that do not require a fee, but the SmartPiggies smart contract also supports oracles that require a fee, such as Chainlink. If the piggy references an oracle that require a fee, the token required for the fee must be approved by the user, so that the SmartPiggies contract can transfer that token as payment on behalf of the user making the oracle request. If a chainlink oracle is used for the oracle in a piggy, a token approval must be made for the LINK token. This is the same process as making a collateral token approval and can be done from the **Manage Wallet** menu: ![](/files/-Mi443vv5JR6LOyMShB4) Select the toggle to the left of the LINK icon to create an approval transaction. After the MetaMask confirmation is confirmed, and the transaction completes successfully, an oracle call using a chainlink oracle can be executed by this Ethereum account. Note that the transacting account needs to have the required LINK to make the oracle call, but does not need a LINK balance to complete the approve transaction. # Claiming payouts Withdrawing the payouts from piggies When it is time to extract your winnings, you can claim any payouts you have made from settled piggies. If you have a balance for any collateral token that balance will show up in the Manage Wallet menu: ![](/files/-Mi45UjoUpallUecW5S-) In the above image, the connected account has a balance of 624.99 truffle tokens. Click on the **Claim** button $$^1$$ to withdraw the tokens. A user may have a balance for multiple collateral tokens. For example, is a user had payouts on piggies that paid UCSD, and also payouts on piggies that paid DAI, the user will have a balance of USDC tokens and DAI tokens which will be visible in the **Manage Wallet** menu. In the above image, these balances would be listed under or in place of the truffle token balance. Note that is the connected account does not have a balance, the **Claim** button will not be visible. The **Claim** button is only visible if the account has a balance on the SmartPiggies smart contract. ## Footnotes 1. Click on the red Claim button in the example it says: "Claim $624.99." Click on that! # Supported wallets Which Ethereum wallets are supported As of this writing the SmartPiggies application only supports the MetaMask extension. If there are strong requests for additional wallet support, the team can look into additional support. Please visit the project [discord](https://discord.gg/hQe39uG) and let us know what you are interested in seeing supported on the platform. # Available oracles Oracles, Resolvers, and Underlyings The SmartPiggies app offers a handful of underlyings, but a limited and specific set. These have been tested, and each underlying requires a unique resolver to return the price of the underlying if the piggy is executed. Currently, SmartPiggies, supports its own oracles which fetch data when requested. As SmartPiggies requires certain features from an oracle, it is possible to use other oracles with SmartPiggies, if they execute in the way the SmartPiggies contract expects. If user would like more resolvers or the use of other oracle providers, please visit the SmartPiggies [discord](https://discord.gg/hQe39uG) to make requests. The following is a list of available resolvers that can be used on the SmartPiggies platform. ### Arbitrum Mainnet Resolvers: BTCUSD: 0xb839f1E75FCB54004b6287a30C534e9C922896fD ETHUSD: 0xDAf2bb291F394f732308a760B8ce7D6d4F21a9ea XAUUSD: 0xaa99B5424586B68ea89949E7685A0218D506bD5b XAGUSD: 0x72Ee2614953A8Cd11DaCB377Af30320913B3A5d7 LINKUSD: 0xF6b33DE49eF37EFD2b5912Ec996b2E579983Aa30 ### Arbitrum Testnet Resolver: ETHUSD: 0xA47FC1d98086bE75aa5d53971701D778C74cE201 # Using your own oracles Making an oracle, resolver, or adding an underlying As of now, SmartPiggies only allows certain resolvers and underlyings. The SmartPiggies oracles need to enforce the execution price after expiration. For example, most price oracles return the spot price at the time of the call. With SmartPiggies, a piggy needs to execute a payout calculation based on the price it receives from an oracle. If a piggy matures on a particular data, say January 1st, 2021, and either counterparty doesn't call the oracle for settlement until February 1st, 2021, the execution price cannot be from February 1st, it must be from January 1st. Because of this requirement, creating oracles is challenging. The current oracle providers will retrieve and return a "live" price, which works for American style options, or if the oracle returns the price at the time of maturity for both American and European. However, because the blockchain is a push oriented technology, any automatic execution needs to be handled off-chain. There are plans to create an oracle marketplace, with reputation and governance mechanics. But this is not implemented at this time. For the time being, SmartPiggies will continue to add and maintain oracles and resolvers for the application, with plans for community participation in the future. It is possible to interact directly with the SmartPiggies contract, and in this case, a user can provide any resolver during the creation of a piggy. However, if the resolver is not recognized by the SmartPiggies platform, it will not be available to users of the application. $$^1$$ There are safety considerations with this approach, and at this time the platform will only display curated resolvers, and by extension only piggies exhibiting these resolvers and underlyings. ## Footnotes 1. Piggies that have resolvers or collateral not recognized by the platform will not show up in the market place, for example. # SmartPiggies and Oracles How SmartPiggies uses oracles SmartPiggies use off-chain data to settle a piggy. Although SmartPiggies recommends selling a piggy back to the writer, as are typically done for traditional options, there are many reasons why the counterparties may need to execute a piggy, and this will involve a call to an oracle to retrieve off-chain data. Off-chain data, here prices, are requested by a **resolver**, which is a smart contract that receives requests and relays results. A resolver contract address is associated with a piggy, this is, for all intents and purposes, the underlying that the piggy will execute against. When a piggy makes a request for a price, which can happen during the bidding process or the settlement process, SmartPiggies will execute a **fetchData()** function on the resolver. When the function is executed on the resolver, an external process (on following the blockchain, but not on it) will pick up the request being made on the resolver. $$^1$$ This external process is the **oracle** and is responsible for sending the desired data back to the resolver. There will be a unique resolver for each underlying. The contract address of this specific resolver is saved into the piggy. This is the contract address used to fetch the price data, if the piggy is executed. For example, if a piggy's underlying is ETHUSD, a unique contract address, referencing the ETHUSD resolver, will be saved as the underlying of the piggy. With this approach underlyings can be added or removed to the app. When interacting directly with the SmartPiggies contract, any address can be provided, but there are strict requirements for the resolver to execute correctly, and SmartPiggies recommends only using approved resolvers. ## Footnotes 1 The technical sequence of events begins by the SmartPiggies contract calling a specific resolver. That resolver will call a **DataProvider** contract. The DataProvider will create a request event, which an external process will catch. The external process (the oracle) will fetch the data, and then make an on-chain call to the DataProvider including the data. The DataProvider will callback the resolver with the data, and the resolver will callback the SmartPiggies contract, updating the piggy with the requested data. # The (optional) Need for Arbitration **Assigning an Arbitrator is optional**, however, as no data source that is external to the network can be guaranteed to be correct or incorruptible, it may be necessary in some cases to introduce a trusted third party arbitrator into the settlement process of a SmartPiggies option, particularly if that option contains a large amount of collateral. Examples of a data source failure that would warrant arbitration: * Human error * Corrupt data records * Corrupt reporting authorities * Infrastructure failure * Price manipulation Employing an Arbitrator introducing it's own risks. An individual entering a contract should carefully consider whether an Arbiter is trustworthy as the assigned Arbiter could potentially collude to force the contract to settle in the counterparty's interest. By entering a contract with an assigned Arbiter, a user is implicitly agreeing to the Arbiter's future actions or inactions. In order to assist in a user's decision to agree to an assigned Arbiter, SmartPiggies application has a built in inspector to allow users to review the past behavior of an assigned arbiter. # Setting an arbitrator An Arbiter must be assigned on contract creation, otherwise a new Arbiter may be assigned if both the Writer and Holder of the contract agree to a new Arbiter by proposing the same new 'Arbiter Choice' address. If an Arbiter is not assigned the Writer and Holder can propose a new arbiter. If the addresses that the Writer and Holder propose are identical, then that address becomes the Arbiter. In the SmartPiggy app, the current Arbiter of any contract may be reviewed by expanding the details and selecting the 'Counterparty Management' tab. ![](/files/-Mhz4o6KIuj4DnhKUXKN) # The Arbitration Process The Arbiter process involves up to three counterparty addresses; the Writer, Holder, and Arbiter. If any two of the counterparty addresses propose a an identical price, the contract will immediately clear at that price. Since a contract creator may assign any address to be an Arbitrator, a signaling flag can be triggered by the assigned Arbiter to publicly acknowledge they have been nominated. It should be noted that an Arbiter is not under any direct on-chain commitment to intervene. An individual who is entering into an existing contract should ensure that they trust the assigned arbiter and that the Arbiter has acknowledged the existence of the contract. If an Arbiter is assigned, the normal clearing process is placed on 3 day cooldown in order to give all counterparties an opportunity to challenge the settlement price provided by the Oracle. During this cooldown, one of the counterparties must propose a new settlement price and convince the Arbiter to propose the same price in order to clear at a new 'correct' price. If no Arbiter is assigned, then the counterparties can directly agree by proposing identical settlement prices; triggering the contract to clear immediately. If an Oracle fails to respond, and an Arbiter is assigned but not responding, and the counterparties cannot agree to a new Arbiter, then the funds in the contract will be inaccessible until both counterparties propose an identical mutually agreed price. The proposal of settlement prices can be managed through the Contract Details, Counterparty Management tab. ![](/files/-MiIZ9zIQUoRU0oQppJQ) # Arbiter Reputation and History Given the importance of selecting a trustworthy Arbiter, the SmartPiggies app displays an on-chain history for the assigned Arbiter for any given contract The SmartPiggies app tracks all contracts to which the the assigned Arbiter has been nominated, whether the Arbiter has acknowledged the nomination, whether the Arbiter has made price proposals, and what the price proposals were. A user may review the on-chain history and determine for themselves whether an Arbiter has behaved in a way that is reliable and accurate. Unless a user has a reason to trust an Arbiter, a user should avoid contracts with an arbiter that has a limited or questionable history. In the future iterations of the platform, Arbiter services will be incentivized by fees and a good reputation will be important. The historical behavior of the an assigned Arbiter may be reviewed in the 'Arbiter History' tab. ![](/files/-MiIfNX1qbFjTy6YeEEE) # FAQ FAQ Why focus on an options protocol? * An option contract is the simplest type of financial contract that requires conditional logic and guarantees of execution. If programmable distributed ledger technologies (DLTs) should be good for anything, it should be good for allowing counterparties to enter into an option agreement with confidence. Bilateral options are not fancy or complicated, but it is a product that is used in the real world that should benefit from DLTs. Our goal is to create the best possible version of this simple contract using DLTs. Why not a fungible token? * Our approach has been one of first principles. At the most basic level, an option contract is a financial insurance agreement between two counterparties. Since each contract can have a unique set of terms, counterparties, and committed collateral, the contracts themselves are fundamentally unique and non-fungible. * While options contracts can be made fungible and tradable on exchanges, it can only be done effectively by restricting the terms, collateral, and underlyings to the few that are the most liquid. The few products that are popular and liquid are already widely available on both centralized and decentralized exchanges. * The fundamental issue with fungible tokens is that they require a minimum amount of liquidity on exchanges for price discovery to occur. The liquidity requirements for options tokens are exponentially higher as each underlying may have dozens or hundreds of derivatives, each of them requiring their own liquidity. * Recognizing options contracts as fundamentally non-fungible allowed us to retain full flexibility of terms, collateral, and underlyings and led us to choose a price discovery mechanic that is independent of liquidity (dutch and reverse-dutch auctions). What about liquidity? * The existing OTC derivatives market is already significant (\~25 trillion USD annual gross market value). We have plans to engage existing market participants as liquidity providers as well as establish a liquidity reward program. What about capital and opportunity costs? * For version 2 of our contracts we will be adding the ability to use yield generating tokens (e.g. aave tokens) so that users can simultaneously generate premium and interest on the committed collateral. Why capped options vs. standard options? * In order to serve effectively as price insurance, we decided that it is critical that the contracts fulfill their terms even in extreme circumstances. As such, each contract itself controls a dedicated amount of unmargined collateral. Synthesizing a standard option would require the implementation of margin mechanics which would be prone to failure. What about partial fills on offers and requests? * We are considering this for version 2 of our contracts Why Cash Settled? * ‘Physically’ settled arrangements are limited to on-chain assets and we wanted to offer a product that had real world applications. As a result, we made the design choice to use oracles for real world price data and settle in cash. * Cash settlement allows our contracts to have a leverage multiplier (number of underlyings it represents). Why aren’t you using a black-scholes on your platform? * Black-sholes is a pricing model. As with any valuation model for any asset, black scholes is an imperfect estimation. The actual fair price of an asset can only be determined by an open market of buyers and sellers. Our platform creates a market; it is up to the buyers and sellers to choose which models they want to use. Why not use real world implied vols to create an AMM? * This would be possible, but such a platform would be restricted to underlyings for which there are existing liquid markets. This would be a poor accomplishment as the platform would not be an original market; it would not be able to exist on its own and would only offer a few highly liquid products that already exist. * Our design goal is to create a platform that can support options contracts for anyone, anywhere, and for anything. Depending on implied vols would contradict that goal. Why not design a DEX based AMM? * Our design goal is to create a platform that can support options contracts for anyone, anywhere, and for anything. As discussed in “Why not a fungible token?”, aside from a few of the most popular assets, options are too illiquid to support price discovery through DEXs. How decentralized will your platform be? * Our contracts are truly non-custodial. There is no master account that can steal funds, rescue them, or upgrade the contracts to something new. * We have intentionally designed the platform such that in it’s ultimate form: * We do not sell products. Users do. * We do not buy products. Users do. * We do not price products. Users do. * We do not decide what products are available. Users do. * We do not provide underlying price data. Users do. * We do not arbitrate in conflicts. Users do. * We have deployed a version of our front end on ICP, which is a decentralized network capable of hosting web applications. * We plan to use ICP to replace our backend services * We plan to use ICP to allow users to host their own price data services * Our ultimate goal is that the SmartPiggies ecosystem be solely operated by users, exist solely on decentralized infrastructure, and be fully self-sustaining. # Contracts Current deployed contracts The current SmartPiggies contracts deployed include: ## Arbitrum Mainnet: [https://app.smartpiggies.com](https://app.smartpiggies.com/dashboard) SmartPiggies Contract: 0x013a50da2aF5D5d31572AABf289aFdCf8FF485Bd Companion Contract: 0xd59624C2fC3763F388f3316cB0f287908526158A Truffle Token: 0x036C4A07468558A08d594d56DE6747F7E9E43F77 please see the **Available oracles** section for resolver addresses. ## Arbitrum Rinkeby Testnet: [https://testnet.smartpiggies.com](https://testnet.smartpiggies.com/) SmartPiggies Contract: 0xdB1277ACA60e783cdDb2E25683b3b3A23Cc83BA8 Companion Contract: 0x64E5dcc9080491FAAE67C94D6881C7b8Aa620dab Truffle Token: 0x7f069Cb1c0b55EeBfBa403d185DB2Fb6bAbd6b70 please see the **Available oracles** section for resolver addresses. # Calling the contracts directly Public and permissionless The SmartPiggies smart contracts are public and permissionless. Although we suggest interacting with the SmartPiggies smart contract through the application, anyone can access all the functionality offered on the application, through direct interaction with the SmartPiggies smart contract. All functions available for creating, managing, auctioning, settling, and withdrawing funds are available through direct function calls on the SmartPiggies smart contract deployed to the Arbitrum mainnet. For example, and this is not recommended, however, anyone can load up the contracts in remix and do anything that the SmartPiggies application offers. If anyone is interested in direct interaction or hosting alternative user interfaces, please visit the SmartPiggies [discord](https://discord.gg/hQe39uG) and let us know what you are interested in.