From 44dd95f580a414fd4e4ad9ce57200f912b4fd03b Mon Sep 17 00:00:00 2001 From: Satyam Agrawal Date: Wed, 23 Aug 2023 13:43:56 +0530 Subject: [PATCH] fix apis --- application/20230522-pool-based-dex.md | 120 +++++++++++++++++++++---- 1 file changed, 105 insertions(+), 15 deletions(-) diff --git a/application/20230522-pool-based-dex.md b/application/20230522-pool-based-dex.md index c377ba53..7d62ce5a 100644 --- a/application/20230522-pool-based-dex.md +++ b/application/20230522-pool-based-dex.md @@ -56,7 +56,7 @@ pub resource interface ExactSwapAndReturnValue { pub resource interface ImmediateSwap { - /// @notice It will Swap the source token for the target token + /// @notice It will Swap the source token for the target token, In the below API, provided `sourceVault` would be consumed fully /// /// If the user wants to swap USDC to FLOW then the /// sourceToTargetTokenPath is [Type, Type] and @@ -64,41 +64,131 @@ pub resource interface ImmediateSwap { /// /// Necessary constraints /// - For the given source vault balance, Swapped target token amount should be - /// greater than or equal to `exactTargetAmount`, otherwise swap would fail. + /// greater than or equal to `minimumTargetTokenAmount`, otherwise swap would fail. /// - If the swap settlement time i.e getCurrentBlock().timestamp is less than or /// equal to the provided expiry then the swap would fail. /// - Provided `recipient` capability should be valid otherwise the swap would fail. /// - If the provided path doesn’t exists then the swap would fail. /// - /// @param sourceToTargetTokenPath: Off-chain computed path for reaching source token to target token + /// @param sourceToTargetTokenPath: Off-chain computed path for reaching source token to target token + /// `sourceToTargetTokenPath[0]` should be the source token type while + /// `sourceToTargetTokenPath[sourceToTargetTokenPath.length - 1]` should be the target token + /// and all the remaining intermediaries token types would be necessary swap hops to swap the + /// source token with target token. + /// @param sourceVault: Vault that holds the source token. + /// @param minimumTargetTokenAmount: Minimum amount expected from the swap, If swapped amount is less than `minimumTargetTokenAmount` + /// then function execution would throw a error. + /// @param expiry: Unix timestamp after which trade would get invalidated. + /// @param recipient: A valid capability that receives target token after the completion of function execution. + /// @return receivedTargetTokenAmount: Amount of tokens user would received after the swap + pub fun swapExactSourceToTargetTokenUsingPath( + sourceToTargetTokenPath: [Type], + sourceVault: @FungibleToken.Vault, + minimumTargetTokenAmount: UFix64, + expiry: UFix64, + recipient: Capability<&{FungibleToken.Receiver}>, + ): UFix64 + { + pre { + expiry >= getCurrentBlock().timestamp : "Expired swap request" + recipient.check() : "Provided recipient capability can not be borrowed" + sourceToTargetTokenPath.length >= 2 : "Incorrect source to target token path" + sourceVault.balance > 0.0 : "Swap is not permitted for zero source vault balance" + } + post { + result >= minimumTargetTokenAmount: "Minimum target token amount have not received during the swap" + } + } + + + /// @notice It will Swap the exact source token for to target token and + /// return `FungibleToken.Vault` + /// + /// If the user wants to swap USDC to FLOW then the + /// sourceToTargetTokenPath is [Type, Type] and + /// USDC would be the source token. + /// + /// This function would be more useful when smart contract is the function call initiator + /// and wants to perform some actions using the receiving amount. + /// + /// Necessary constraints + /// - For the given source vault balance, Swapped target token amount should be + /// greater than or equal to `minimumTargetTokenAmount`, otherwise swap would fail + /// - If the swap settlement time i.e getCurrentBlock().timestamp is less than or equal to the provided expiry then the swap would fail + /// - If the provided path doesn’t exists then the swap would fail. + /// + /// @param sourceToTargetTokenPath: Off-chain computed path for reaching source token to target token /// `sourceToTargetTokenPath[0]` should be the source token type while /// `sourceToTargetTokenPath[sourceToTargetTokenPath.length - 1]` should be the target token - /// and all the remaining intermediaries token types would be necessary swap hops to swap the - /// source token with target token. - /// @param sourceVault: Vault that holds the source token. - /// @param exactTargetAmount: Exact amount expected from the swap, If swapped amount is less than `exactTargetAmount` then - /// function execution would throw a error. - /// @param expiry: Unix timestamp after which trade would get invalidated. - /// @param recipient: A valid capability that receives target token after the completion of function execution. + /// and all the remaining intermediaries token types would be necessary swap hops to swap the + /// source token with target token. + /// @param sourceVault: Vault that holds the source token. + /// @param minimumTargetTokenAmount: Minimum amount expected from the swap, If swapped amount is less than `minimumTargetTokenAmount` + /// then function execution would throw a error. + /// @param expiry: Unix timestamp after which trade would get invalidated. + /// @return A valid vault that holds target token and an optional vault that may hold leftover source tokens. + pub fun swapExactSourceToTargetTokenUsingPathAndReturn( + sourceToTargetTokenPath: [Type], + sourceVault: @FungibleToken.Vault, + minimumTargetTokenAmount: UFix64, + expiry: UFix64 + ): @FungibleToken.Vault { + pre { + expiry >= getCurrentBlock().timestamp : "Expired swap request" + sourceToTargetTokenPath.length >= 2 : "Incorrect source to target token path" + sourceVault.balance > 0.0 : "Swap is not permitted for zero source vault balance" + } + post { + result.balance >= minimumTargetTokenAmount : "Unable to perform exact source to target token swap" + } + } + + /// @notice It will Swap the source token for the target token while expected targetToken amount would be fixed + /// + /// If the user wants to swap USDC to FLOW then the + /// sourceToTargetTokenPath is [Type, Type] and + /// USDC would be the source token + /// + /// Necessary constraints + /// - For the given source vault balance, Swapped target token amount should be + /// equal to `exactTargetAmount`, otherwise swap would fail. + /// - If the swap settlement time i.e getCurrentBlock().timestamp is less than or + /// equal to the provided expiry then the swap would fail. + /// - Provided `recipient` capability should be valid otherwise the swap would fail. + /// - If the provided path doesn’t exists then the swap would fail. + /// + /// @param sourceToTargetTokenPath: Off-chain computed path for reaching source token to target token + /// `sourceToTargetTokenPath[0]` should be the source token type while + /// `sourceToTargetTokenPath[sourceToTargetTokenPath.length - 1]` should be the target token + /// and all the remaining intermediaries token types would be necessary swap hops to swap the + /// source token with target token. + /// @param sourceVault: Vault that holds the source token. + /// @param exactTargetAmount: Exact amount expected from the swap, If swapped amount is different from `exactTargetAmount` + /// then function execution would throw a error. + /// @param expiry: Unix timestamp after which trade would get invalidated. + /// @param recipient: A valid capability that receives target token after the completion of function execution. /// @param remainingSourceTokenRecipient: A valid capability that receives surplus source token after the completion of function execution. - pub fun swapExactSourceToTargetTokenUsingPath( + pub fun swapSourceToExactTargetTokenUsingPath( sourceToTargetTokenPath: [Type], sourceVault: @FungibleToken.Vault, exactTargetAmount: UFix64, expiry: UFix64, recipient: Capability<&{FungibleToken.Receiver}>, remainingSourceTokenRecipient: Capability<&{FungibleToken.Receiver}> - ) + ): UFix64 { pre { expiry >= getCurrentBlock().timestamp : "Expired swap request" recipient.check() : "Provided recipient capability can not be borrowed" + remainingSourceTokenRecipient.check() : "Provided remaining source token recipient capability can not be borrowed" sourceToTargetTokenPath.length >= 2 : "Incorrect source to target token path" sourceVault.balance > 0.0 : "Swap is not permitted for zero source vault balance" } + post { + result == exactTargetAmount: "Unable to perform source to exact target token swap" + } } - /// @notice It will Swap the source token for to target token and /// return `ExactSwapAndReturnValue` /// @@ -125,7 +215,7 @@ pub resource interface ImmediateSwap { /// function execution would throw a error. /// @param expiry: Unix timestamp after which trade would get invalidated. /// @return A valid vault that holds target token and an optional vault that may hold leftover source tokens. - pub fun swapExactSourceToTargetTokenUsingPathAndReturn( + pub fun swapSourceToExactTargetTokenUsingPathAndReturn( sourceToTargetTokenPath: [Type], sourceVault: @FungibleToken.Vault, exactTargetAmount: UFix64, @@ -137,7 +227,7 @@ pub resource interface ImmediateSwap { sourceVault.balance > 0.0 : "Swap is not permitted for zero source vault balance" } post { - result.targetTokenVault.balance == exactTargetAmount : "Unable to perform exact swap" + result.targetTokenVault.balance == exactTargetAmount : "Unable to perform source to exact target token swap" } }