A module to swap tokens across markets the Serum DEX, providing a thin wrapper around an Anchor for the sole purpose of * providing a simplified swap API.

Usage

Create a client

const client = new Swap(provider, tokenList)

Swap one token for another across USD(x) quoted markets.

await client.swap({
  fromMint,
  toMint,
  amount,
  minExchangeRate,
});

Default Behavior

Some parameters in the swap API are optional. For example, the fromMarket and toMarket, specifying the markets to swap across. In the event that markets are ommitted, the client will swap across USD(x) quoted markets. For more information about default behavior see the SwapParams documentation. For most GUIs, the application likely already knows the markets to swap accross, since one needs that information to calculate exchange rates for the UI. So it's recommend to pass in most, if not all, the optional parameters explicitly, to prevent unnecessary network requests.

Swap Program Basics

One should have a basic understanding of the on-chain Swap program before using the client. Two core APIs are exposed.

• swap - swaps two tokens on a single A/B market. This is just an IOC trade at the BBO that instantly settles.
• swapTransitive - swaps two tokens across two A/x, B/x markets in the same manner as swap.

For both APIs, if the number of tokens received from the trade is less than the client provided minExchangeRate, the transaction aborts.

Note that if this client package is insufficient, one can always use the Anchor generated client directly, exposing an API mapping one-to-one to these program instructions. See the tests/ for examples of using the Anchor generated swap client.

Serum Orderbook Program Basics

Additionally, because the Swap program is an on-chain frontend for the Serum DEX, one should also be aware of the basic accounts needed for trading on the Serum DEX.

Namely, a wallet must have an "open orders" account for each market the wallet trades on. The "open orders" account is akin to how a wallet must have an SPL token account to own tokens, except instead of holding tokens, the wallet can make trades on the orderbook.

Creating Open Orders Accounts

When the wallet doesn't have an open orders account already created, the swap client provides two choices. Automatically create the required accounts by preloading the instructions in the swap transaction.

Note that if the user is swapping between two non-USD(x) tokens, e.g., wBTC for wETH, then the user needs two open orders accounts on both wBTC/USD(x) and wETH/USD(x) markets. In the event both of these open orders accounts are created for the rfirst time, then the transaction is broken up into two (and Provider.sendAll is used) to prevent hitting transaction size limits.