EIP2266: Atomic Swap-based American Call Option Contract Standard

0xmountaintop commented 5 years ago

eip: 2266 title: Atomic Swap-based American Call Option Contract Standard author: Runchao Han runchao.han@monash.edu, Haoyu Lin chris.haoyul@gmail.com, Jiangshan Yu jiangshan.yu@monash.edu discussions-to: https://github.com/ethereum/EIPs/issues/2266 status: Draft type: Standards Track category: ERC created: 2019-08-17

Simple Summary

A standard for token contracts providing Atomic Swap-based American Call Option functionalities.

Abstarct

This standard provides functionality to make Atomic Swap-based American Call Option payment. The Atomic Swap protocol based on Hashed Time-Locked Contract (HTLC) [^1] has optionality [^2], and such optionality can be utilised to construct American Call Options without trusted third party. This standard defines the common way of implementing this protocol. In particular, this EIP defines technical terms, provides interfaces, and gives reference implementations of this protocol.

Motivation

Atomic Swap allows users to atomically exchange their tokens without trusted third parties while the HTLC is commonly used for the implementation. However, the HTLC-based Atomic Swap has optionality. More specifically, the swap initiator can choose to proceed or abort the swap for several hours, which gives him time for speculating according to the exchange rate. A discussion[^2] shows that the HTLC-based Atomic Swap is equivalent to an American Call Option in finance. On the other hand,thanks to such optionality, the HTLC-based Atomic Swap can be utilised to construct American Call Options without trusted third party. A paper[^3] proposes a secure Atomic-Swap-based American Call Option protocol on smart contracts. This protocol not only eliminates the arbitrage opportunity but also prevents any party from locking the other party's money maliciously. This EIP aims at providing the standard of implementing this protocol in existing token standards.

Specification

The Atomic Swap-based American Call Option smart contract should follow the syntax and semantics of Ethereum smart contracts.

Definitions

initiator: the party who publishes the advertisement of the swap.
participant: the party who agrees on the advertisement and participates in the swap with initiator.
asset: the amount of token(s) to be exchanged.
premium: the amount of token(s) that initiator pays to participant as the premium.
redeem: the action to claim the token from the other party.
refund: the action to claim the token from the party herself/himself, because of timelock expiration.
secrect: a random string chosen by initiator as the preimage of a hash.
secrectHash: a string equals to the hash of secrect, used for constructing HTLCs.
timelock: a timestamp representing the timelimit, before when the asset can be redeemed, and otherwise can only be refunded.

Storage Variables

swap

This mapping stores the metadata of the swap contracts, including the parties and tokens involved. Each contract uses different secretHash, and is distinguished by secretHash.

mapping(bytes32 => Swap) public swap;

initiatorAsset

This mapping stores the detail of the asset initiators want to sell, including the amount, the timelock and the state. It is asscociated with the swap contract with the same secretHash.

mapping(bytes32 => InitiatorAsset) public initiatorAsset;

participantAsset

This mapping stores the details of the asset participants want to sell, including the amount, the timelock and the state. It is asscociated with the swap contract with the same secretHash.

mapping(bytes32 => ParticipantAsset) public participantAsset;

premiumAsset

This mapping stores the details of the premium initiators attach in the swap contract, including the amount, the timelock and the state. It is asscociated with the swap contract with the same secretHash.

mapping(bytes32 => Premium) public premium;

Methods

setup

This function sets up the swap contract, including the both parties involved, the tokens to exchanged, and so on.

function setup(bytes32 secretHash, address payable initiator, address tokenA, address tokenB, uint256 initiatorAssetAmount, address payable participant, uint256 participantAssetAmount, uint256 premiumAmount) public payable

initiate

The initiator invokes this function to fill and lock the token she/he wants to sell and join the contract.

function initiate(bytes32 secretHash, uint256 assetRefundTime) public payable

fillPremium

The initiator invokes this function to fill and lock the premium.

function fillPremium(bytes32 secretHash, uint256 premiumRefundTime) public payable

participate

The participant invokes this function to fill and lock the token she/he wants to sell and join the contract.

function participate(bytes32 secretHash, uint256 assetRefundTime) public payable

redeemAsset

One of the parties invokes this function to get the token from the other party, by providing the preimage of the hash lock secret.

function redeemAsset(bytes32 secret, bytes32 secretHash) public

refundAsset

One of the parties invokes this function to get the token back after the timelock expires.

function refundAsset(bytes32 secretHash) public

redeemPremium

The participant invokes this function to get the premium. This can be invoked only if the participant has already invoked participate and the participant's token is redeemed or refunded.

function redeemPremium(bytes32 secretHash) public

refundPremium

The initiator invokes this function to get the premium back after the timelock expires.

function refundPremium(bytes32 secretHash) public

Events

SetUp

This event indicates that one party has set up the contract using the function setup().

event SetUp(bytes32 secretHash, address initiator, address participant, address tokenA, address tokenB, uint256 initiatorAssetAmount, uint256 participantAssetAmount, uint256 premiumAmount);

Initiated

This event indicates that initiator has filled and locked the token to be exchanged using the function initiate().

event Initiated(uint256 initiateTimestamp, bytes32 secretHash, address initiator, address participant, address initiatorAssetToken, uint256 initiatorAssetAmount, uint256 initiatorAssetRefundTimestamp);

Participated

This event indicates that participant has filled and locked the token to be exchanged using the function participate().

event Participated(uint256 participateTimestamp, bytes32 secretHash, address initiator, address participant, address participantAssetToken, uint256 participantAssetAmount, uint256 participantAssetRefundTimestamp);

PremiumFilled

This event indicates that initiator has filled and locked premium using the function fillPremium().

event PremiumFilled(uint256 fillPremiumTimestamp, bytes32 secretHash, address initiator, address participant, address premiumToken, uint256 premiumAmount, uint256 premiumRefundTimestamp);

InitiatorAssetRedeemed/ParticipantAssetRedeemed

These two events indicate that asset has been redeemed by the other party before the timelock by providing secret.

event InitiatorAssetRedeemed(uint256 redeemTimestamp, bytes32 secretHash, bytes32 secret, address redeemer, address assetToken, uint256 amount);

event ParticipantAssetRedeemed(uint256 redeemTimestamp, bytes32 secretHash, bytes32 secret, address redeemer, address assetToken, uint256 amount);

InitiatorAssetRefunded/ParticipantAssetRefunded

These two events indicate that asset has been refunded by the original owner after the timelock expires.

event InitiatorAssetRefunded(uint256 refundTimestamp, bytes32 secretHash, address refunder, address assetToken, uint256 amount);

event ParticipantAssetRefunded(uint256 refundTimestamp, bytes32 secretHash, address refunder, address assetToken, uint256 amount);

PremiumRedeemed

This event indicates that premium has been redeemed by participant. This implies that asset is either redeemed by initiator if it can provide the preimage of secrectHash before asset timelock expires; or refunded by participant if asset timelock expires.

event PremiumRedeemed(uint256 redeemTimestamp,bytes32 secretHash,address redeemer,address token,uint256 amount);

PremiumRefunded

This event indicates that premium has been refunded back to initiator, because of participant doesn't participate at all, by the time of premium timelock expires.

event PremiumRefunded(uint256 refundTimestamp, bytes32 secretHash, address refunder, address token, uint256 amount);

Rationale

To achieve the atomicity, HTLC is used.
The participant should decide whether to participate after the initiator locks the token and sets up the timelock.
The initiator should decide whether to proceed the swap (redeem the tokens from the participant and reveal the preimage of the hash lock), after the participant locks the tokens and sets up the time locks.
Premium is redeemable for the participant only if the participant participates in the swap and redeems the initiator's token before premium's timelock expires.
Premium is refundable for the initiator only if the initiator initiates but the participant does not participate in the swap at all.

Backwards Compatibility

This proposal is fully backward compatible. Functionalities of existing standards will not be affected by this proposal, as it only provides additional features to them.

Implementation

Please visit here to find our example implementation.

Copyright

Copyright and related rights waived via CC0.

[^1]: Hash Time Locked Contracts [^2]: An Argument For Single-Asset Lightning Network [^3]: On the optionality and fairness of Atomic Swaps

MicahZoltu commented 4 years ago

This EIP looks like a Good Idea rather than a standard. A standard is useful when there is a many-to-many relationship between parties. For example, there are many web browsers and there are many websites, and we want all websites to work in all web browsers so there is value to create standards around how web pages are rendered.

In this case, an atomic swap/option contract will likely be strongly tied to a specific user interface (dapp) and the coordination only needs to happen between two parties. This suggests that one can just write a contract and an interface and call it a day, there is little value in standardizing that interface because each dapp can implement it their own way and that won't break anything for other dapps.

MicahZoltu commented 4 years ago

Try not to link to external resources whenever possible. External links are likely to turn into 404 errors over time, and we want EIPs to live for a long time, like other standards. Recommend inlining as much as you can, or adding assets to ../assets/eip-2266/whatever.ext.

Chxpz commented 3 years ago

That's an awesome proposal. I might be missing a few points, please correct me on that,

I don't see why the initiator needs to pay the premium. In a stock option transaction, the premium is what makes the writers (initiators) earning a profit, in this case, the premium is paid by the buyer (participants). So, what's the point here?

I can see a transaction that can be done by 02 parties. How to create a derivative asset (option) from this originally the first transaction in order to trade it in the market? I mean, as a buyer I hold a derivative asset (call option) from asset X and I want to sell it to a third party who was not engaged in the original transaction. Are there any thoughts on this?

I might have one or another consideration but if I could get a better understanding of this both in the first place would be fantastic. I appreciate cheers

SebastianElvis commented 3 years ago

That's an awesome proposal. I might be missing a few points, please correct me on that,

Thanks for your interest in this EIP!

I don't see why the initiator needs to pay the premium. In a stock option transaction, the premium is what makes the writers (initiators) earning a profit, in this case, the premium is paid by the buyer (participants). So, what's the point here?

Who pays the premium depends on who is the one having the option. In Atomic Swap, the initiator is the one with the option: the initiator can choose to proceed or abort the swap. Atomic Swap is a Call Option, where the initiator buys an option of buying the participant's asset. The stock option case above is a Put Option, where the initiator sells an option of buying its asset. For detailed definition of Call/Put option please refer to https://en.wikipedia.org/wiki/Call_option

I can see a transaction that can be done by 02 parties. How to create a derivative asset (option) from this originally the first transaction in order to trade it in the market? I mean, as a buyer I hold a derivative asset (call option) from asset X and I want to sell it to a third party who was not engaged in the original transaction. Are there any thoughts on this?

This requires an order matching process beforehand. Order matching is a module independent from the order execution (namely Atomic Swap here). Therefore this EIP proposal assumes Alice and Bob have already been matched and focuses on standardising the interfaces of Atomic-Swap-based American Call Option.

I might have one or another consideration but if I could get a better understanding of this both in the first place would be fantastic. I appreciate cheers

fulldecent commented 3 years ago

Has anybody deployed any contract using this? This should be reference in the text.
This does not meet the requirements of what should be standardized / argued by Micah / https://github.com/ethereum/EIPs/issues/2266#issuecomment-689995637
Rationale does not discuss alternatives considered and the given reasons are too sparse.

github-actions[bot] commented 2 years ago

There has been no activity on this issue for two months. It will be closed in a week if no further activity occurs. If you would like to move this EIP forward, please respond to any outstanding feedback or add a comment indicating that you have addressed all required feedback and are ready for a review.

github-actions[bot] commented 2 years ago

This issue was closed due to inactivity. If you are still pursuing it, feel free to reopen it and respond to any feedback or request a review in a comment.

ethereum / EIPs