Skip to main content

Swaps

Introduction​

Swap means taking part in exchange of one HTS token to another one. For end-users, swapping is intuitive: a user selects an input token and an output token with a certain input amount. Then the Sigmaswap protocol will automatically calculate the amount of 1output tokens. Next, the user simply executes the swap and confirms the transaction. The output token will be transferred to the user’s wallet automatically immediately.

note: Using the web interfaces to swap via the Sigmaswap protocol may cause additional permission structures, and may result in different execution behavior compared to using the Sigmaswap protocol directly.

Swaps using the Sigmaswap protocol are different from traditional order book trades in that they are not executed against discrete orders on a first-in-first-out basis — rather, swaps execute against a passive pool of liquidity2, with liquidity providers earning fees proportional to their capital committed. Sigmaswap uses an automated market maker mechanism to provide instant feedback on rates and slippages.

Swap Anatomy​

At the most basic level, all swaps happen within a single function, aptly named swap:

function swap(uint amount0Out, uint amount1Out, address to, bytes calldata data);

Association​

Before a swap is executed, including in transaction confirmations, there is an additional transaction called Association. This is the requirement assigned from Hedera that all users have to associate their account (receiver account) with a designated token in order to receive, own, transfer, or begin any operations with the token or else the transaction is reverted. Read more

Receiving Tokens from Swap Contract​

In order for the user to receive the output token, all swap processes including internal transactions must be successfully executed. The swap function caller specifies the amount{0,1}Out and the program then sends a designated amount of the output token to the caller.

Sending Tokens to Swap Contract​

Sigmaswap receive tokens as payment for the swap. Typically, smart contracts which need tokens to perform some functionality require callers to first make an approval on the token contract, then call a function that in turn calls transferFrom on the token contract. However, this is not how a pair contract accepts tokens. Instead, pairs check their token balances at the end of every interaction. Then, at the beginning of the next interaction, current balances are differentiated against the stored values to determine the amount of tokens that were sent by the current interactor.

Price Impact​

In a traditional order-book market, a sizeable market-buy order may deplete the available liquidity of a prior limit-sell and continue to execute against a subsequent limit-sell order at a higher price. The result is the final execution price of the order is somewhere in between the two limit-sell prices against which the order was filled.

Price impact affects the execution price of a swap similarly but is a result of a different dynamic. When using an automated market maker, the relative value of one asset in terms of the other continuously shifts during the execution of a swap, leaving the final execution price somewhere between where the relative price started - and ended.

This dynamic affects every swap using the Sigmaswap protocol, as it is an inextricable part of AMM design.

As the amount of liquidity available at different price points may vary, the price impact for a given swap size will change accordingly to the amount of liquidity available at any given point in price space. The greater the liquidity available at a given price, the lower the price impact for a given swap size. The lesser the liquidity available, the higher the price impact.

Approximate3 price impact is anticipated in real-time via the Sigmaswap interface, and warnings appear if unusually high price impact will occur during a swap. Anyone executing a swap will have the ability to assess the circumstances of price impact when needed.

Slippage​

The other relevant detail to consider when approaching swaps with the Sigmaswap protocol is slippage. Slippage is the term used to describe alterations to a given price that could occur while a submitted transaction is pending.

Slippage tolerances establish a margin of change acceptable to the user beyond price impact. As long as the execution price is within the slippage range, e.g., %1, the transaction will be executed. If the execution price exceeds the accepted slippage range, the transaction will be rejected and fail, which the swap will not occur.

A comparable situation in a traditional market would be a market-buy order executed after a delay. One can know the expected price of a market-buy order when submitted, but much can change in the time between submission and execution.

Safety Checks​

Price impact and slippage can both change while a transaction is pending, which is the main reason why numerous safety checks have been implemented into the Sigmaswap protocol. This helps protect end-users from drastic changes in the execution environment of their swap. Some of the most commonly encountered safety checks:

  • Expired : A transaction error that occurs when a swap is pending longer than a predetermined deadline. The deadline is the latest time which the transaction should be completed. However, if it is pending far exceeds the time limit, the swap will be automatically canceled to protect users from the abnormal or unusually long pending periods and the changes in price that typically accompany the passage of time.

  • INSUFFICIENT_LIQUIDITY : The error is raised when the specified output token amount is greater than the amount in the pool reserve.

  • INSUFFICIENT_OUTPUT_AMOUNT : When a user proceeds the swap, the Sigmaswap interface will send an estimated amount of the purchased token that the user should expect to receive. If the anticipated output amount of a swap does not match the estimation within a certain margin of error (the slippage tolerance), the swap will be canceled. This attempts to protect the user from any drastic and unfavorable price changes while their transaction is pending.

  • INSUFFICIENT_INPUT_AMOUNT : The requirement in the swap function used to ensure that the amount0In and amount1In is greater than zero.

  • INVALID_TO : Before calling the swap function, the input to needs to be filled as a receiver address of the swap. This requirement is to check that the receiver address is not a token address of _token0 or _token1. However, if there is the case, Hedera will revert the transaction itself since addresses on Hedera are classified into multiple types ( account, token, contract etc.).

  • K : The error occurs when new K (post-swap) is less than old K (pre-swap).

1 An output amount in this instance takes into account many factors, including the relative price of one token in terms of the other, slippage, price impact, and other factors related to the open and adversarial nature of Hedera.

2 For information about liquidity provision, see Pool.

3 The Sigmaswap interface informs the user about the circumstances of their swap, but it is not guaranteed.