🤝Swap

Swap means to take a portion of liquidity from a market in exchange for another asset.

Swapping is the most common activity in the Joint protocol. It involves the exchange of an asset held in a user’s wallet for another asset provided to a market.

For example, in an ETH/USDT market, users can swap USDT held in their wallet for ETH.

Users who swap are known as takers or swappers.

Types of Swap

There are two types of swaps a user can perform:

Instant

This is a swap between two on-chain assets. For example, a swap in a market where base and quote assets are either ERC20 (ex. WETH, USDC) or an NFT (ex. DROID) will result in an instant swap.

Interactive

This is a swap between two assets, one existing on-chain and the other a synthetic asset representing an off-chain store of value such as fiat (e.g. USD, JPY, EUR), gift card, collectable and other real-world assets.

Interactive Swap

A synthetic asset describes an off-chain asset or store of value like fiat and gift cards.

An interactive swap involves swapping an on-chain asset for an off-chain or synthetic asset. In this type of swap, the synthetic asset can be anything that is transferred through an off-chain channel.

Unlike instant swaps, an interactive swap is not instant. The swap participants must pass through a time-bound trade flow where they inform the protocol about the progress of the trade.

A taker creates a swap, the off-chain payer marks the swap as paid, and the liquidity provider releases the escrowed asset.

Interactive Swap Phases

This is the life-cycle of an interactive swap:

• Creation: The swap order is created.

• Payment: In this phase, payment is expected to be sent off-chain. If the liquidity provider is the payer, they are expected to send payment to the taker. If the taker is the payer, they must pay the liquidity provider. Both parties must agree upon the mode of payment.

  • Payment Notification: The payer must mark the trade as paid once they have sent the payment to the counterpart. Failure to do this may result in swap order cancellation.

• Grace: This phase is entered only when the payer did not mark the swap order as paid within the liquidity provider’s preferred payment time. The grace period gives the payer more time to make payment before the swap is eligible for cancellation.

• Cancellation: After the grace period elapses, the swap enters the cancellation phase, where either counterpart can cancel the swap.

• Release: After the swap order is marked as paid, the swap enters the release phase, where the token must be released by the counterpart who received an off-chain payment.

• Dispute: A dispute phase can be started when either counterpart wants to cancel or force a release of the trade due to any issues (e.g. payment, communication, misinformation). Disputes can only be started if the swap is marked as paid.

Swap Price

The liquidity provider sets the swap price. A market can have many liquidity providers, each specifying a different price.

During the creation of a swap, the swapper must ensure they have enough quote tokens in their wallet; otherwise, the swap will fail.

For instance, in an ETH/USDT market where the price of 1 ETH = 1000 USDT, if the swapper intends to take 10 ETH, they must ensure they have 10,000 USDT in their wallet. If the market includes fees and the protocol fee is turned on, they must also account for them.

Price Slippage Guard

Joint supports a slippage guard that allows the swapper to target a specific price range.

Suppose a liquidity's price changes after a swap transaction has been created and broadcast to the blockchain miners. In that case, the swap will be cancelled if the updated liquidity price exceeds the maximum price set during the creation time.

Conversely, if the price is lower, the swap is executed using the lower price.

Swap Fee

Depending on the market, a swap transaction is subject to at least one type of fee — market fee and protocol fee.

The market fee is paid to the market creator or owner. If a swap originates from a market that takes a fee, the fee is deducted at the end of the swap. Market fees can be optional if the market takes no fee.

The protocol fee is a fee paid to the protocol. Unlike market fees, it is not optional.

In an instant swap, the fee is deducted from the base token received by the taker. For example, in an ETH/BTC swap order, the fee is taken from the ETH side.

For an interactive swap, the fee is deducted from the side with the on-chain asset. For example, in an ETH/JPY swap order, the fee is taken from the ETH side. Conversely, in a JPY/ETH swap order, a fee is also taken from the ETH side.

Swap Expiry

Sometimes, a user intends to get into a position within a duration but may be unable to pay the high gas fee to get their transaction mined quickly. If the transaction remains unmined for too long, they may miss the opportunity and enter an undesirable position when their transaction is finally mined.

Joint supports swap transaction expiration that allows users sent the duration of their swap transaction to remain valid in the mempool. When this time elapses, the swap transaction will be rejected when finally mined.

By default, the Joint Team interface sets the expiry time to 30 minutes but allows users to provide a custom value.