# Market
The Market module contains the logic for atomic swaps between Terra currencies (e.g. UST<>KRT), as well as between Terra and Luna (e.g. SDT<>Luna).
The ability to guarantee an available, liquid market with fair exchange rates between different Terra denominations and between Terra and Luna is critical for user-adoption and price-stability.
As mentioned in the protocol, the price stability of TerraSDR's peg to the SDR is achieved through Terra<>Luna arbitrage activity against the protocol's algorithmic market-maker which expands and contracts Terra supply to maintain the peg.
# Concepts
# Swap Fees
Since Terra's price feed is derived from validator oracles, there is necessarily a delay between the on-chain reported price and the actual realtime price.
This difference is on the order of about 1 minute (our oracle VotePeriod
is 30 seconds), which is negligible for nearly all practical transactions. However an attacker could take advantage of this lag and extract value out of the network through a front-running attack.
To defend against this, the Market module enforces the following swap fees
a Tobin Tax (set at 0.25%) for spot-converting Terra<>Terra swaps
To illustrate, assume that oracle reports that the Luna<>SDT exchange rate is 10, and for Luna<>KRT, 10,000. Sending in 1 SDT will get you 0.1 Luna, which is 1000 KRT. After applying the Tobin Tax, you'll end up with 997.5 KRT (0.25% of 1000 is 2.5), a better rate than any retail currency exchange and remittance[1].
a minimum spread (set at 2%) for Terra<>Luna swaps
Using the same exchange rates above, swapping 1 SDT will return 980 KRT worth of Luna (2% of 1000 is 20, taken as the swap fee). In the other direction, 1 Luna would give you 9.8 SDT (2% of 10 = 0.2), or 9800 KRT (2% of 10,000 = 200).
# Market Making Algorithm
Terra uses a Constant Product market-making algorithm to ensure liquidity for Terra<>Luna swaps. [2]
With Constant Product, we define a value
NOTE
Our implementation of Constant Product diverges from Uniswap's, as we use the fiat value of Luna instead of the size of the Luna pool. This nuance means changes in Luna's price don't affect the product, but rather the size of the Luna pool.
For example, we'll start with equal pools of Terra and Luna, both worth 1000 SDR total. The size of the Terra pool is 1000 SDT, and assuming the price of Luna<>SDR is 0.5, the size of the Luna pool is 2000 Luna. A swap of 100 SDT for Luna would return around 90.91 SDR worth of Luna (≈ 181.82 Luna). The offer of 100 SDT is added to the Terra pool, and the 90.91 SDT worth of Luna are taken out of the Luna pool.
CP = 1000000 SDR
(1000 SDT) * (1000 SDR of Luna) = 1000000 SDR
(1100 SDT) * (909.0909... SDR of Luna) = 1000000 SDR
Of course, this specific example was meant to be more illustrative than realistic -- with much larger liquidity pools used in production, the magnitude of the spread is diminished.
The primary advantage of Constant-Product over Columbus-2 is that it offers “unbounded” liquidity, in the sense that swaps of arbitrary size can be serviced (albeit at prices that become increasingly unfavorable as trade size increases).
# Virtual Liquidity Pools
The market starts out with two liquidity pools of equal sizes, one representing Terra (all denominations) and another representing Luna, initialiazed by the parameter BasePool
, which defines the initial size,
In practice, rather than keeping track of the sizes of the two pools, the information is encoded in a number TerraPoolDelta
, representing the deviation of the Terra pool from its base size in units µSDR.
The size of the Terra and Luna liquidity pools can be generated from
At the end of each block, the market module will attempt to "replenish" the pools by decreasing the magnitude of PoolRecoveryPeriod
, with lower periods meaning lower sensitivity to trades, meaning previous trades are more quickly forgotten and the market is able to offer more liquidity.
This mechanism ensures liquidity and acts as a sort of low-pass filter, allowing for the spread fee (which is a function of TerraPoolDelta
) to drop back down when there is a change in demand, hence necessary change in supply which needs to be absorbed.
# Swap Procedure
Market module receives
MsgSwap
message and performs basic validation checksCalculate exchange rate
and using k.ComputeSwap()
Update
TerraPoolDelta
withk.ApplySwapToPool()
Transfer
OfferCoin
from account to module usingsupply.SendCoinsFromAccountToModule()
Burn offered coins, with
supply.BurnCoins()
.Let
, this is the spread fee. Mint
coins of AskDenom
withsupply.MintCoins()
. This implicitly applies the spread fee as thecoins are burned. Send newly minted coins to trader with
supply.SendCoinsFromModuleToAccount()
Emit
swap
event to publicize swap and record spread fee
If the trader's Account
has insufficient balance to execute the swap, the swap transaction fails.
Upon successful completion of Terra<>Luna swaps, a portion of the coins to be credited to the user's account is withheld as the spread fee.
# Seigniorage
For Luna swaps into Terra, the Luna that recaptured by the protocol is burned and is called seigniorage -- the value generated from issuing new Terra. At the end of the epoch, the total seigniorage for the epoch will be calculated and reintroduced into the economy as ballot rewards for the exchange rate oracle and to the community pool by the Treasury module, described more fully here.
# State
# Terra Pool Delta δ
- type:
sdk.Dec
Represents the difference between size of current Terra pool and its original base size, valued in µSDR.
# Message Types
# MsgSwap
A MsgSwap
transaction denotes the Trader
's intent to swap their balance of OfferCoin
for new denomination AskDenom
, for both Terra<>Terra and Terra<>Luna swaps.
// MsgSwap contains a swap request
type MsgSwap struct {
Trader sdk.AccAddress `json:"trader" yaml:"trader"` // Address of the trader
OfferCoin sdk.Coin `json:"offer_coin" yaml:"offer_coin"` // Coin being offered
AskDenom string `json:"ask_denom" yaml:"ask_denom"` // Denom of the coin to swap to
}
JSON Example
{
"type": "market/MsgSwap",
"value": {
"trader": "terra...",
"offer_coin": {
"denom": "umnt",
"amount": "999"
},
"ask_denom": "ukrw"
}
}
Events
Type | Attribute Key | Attribute Value |
---|---|---|
swap | offer | {offerCoin} |
swap | trader | {traderAddress} |
swap | recipient | {recipientAddress} |
swap | swap_coin | {swapCoin} |
swap | swap_fee | {swapFee} |
message | module | market |
message | action | swap |
message | sender | {senderAddress} |
# MsgSwapSend
A MsgSendSwap
first performs a swap of OfferCoin
into AskDenom
and the sends the resulting coins to ToAddress
. Tax is charged normally, as if the sender were issuing a MsgSend
with the resutling coins of the swap.
type MsgSwapSend struct {
FromAddress sdk.AccAddress `json:"from_address" yaml:"from_address"` // Address of the offer coin payer
ToAddress sdk.AccAddress `json:"to_address" yaml:"to_address"` // Address of the recipient
OfferCoin sdk.Coin `json:"offer_coin" yaml:"offer_coin"` // Coin being offered
AskDenom string `json:"ask_denom" yaml:"ask_denom"` // Denom of the coin to swap to
}
JSON Example
{
"type": "market/MsgSwapSend",
"value": {
"from_address": "terra...",
"to_address": "terra...",
"offer_coin": {
"denom": "umnt",
"amount": "999"
},
"ask_denom": "ukrw"
}
}
Events
Type | Attribute Key | Attribute Value |
---|---|---|
swap | offer | {offerCoin} |
swap | trader | {traderAddress} |
swap | recipient | {recipientAddress} |
swap | swap_coin | {swapCoin} |
swap | swap_fee | {swapFee} |
message | module | market |
message | action | swapsend |
message | sender | {senderAddress} |
# Functions
# k.ComputeSwap()
func (k Keeper) ComputeSwap(ctx sdk.Context, offerCoin sdk.Coin, askDenom string)
(retDecCoin sdk.DecCoin, spread sdk.Dec, err sdk.Error)
This function detects the swap type from the offer and ask denominations and returns:
The amount of asked coins that should be returned for a given
offerCoin
. This is achieved by first spot-convertingofferCoin
to µSDR and then from µSDR to the desiredaskDenom
with the proper exchange rate reported from by the Oracle.The spread % that should be taken as a swap fee given the swap type. Terra<>Terra swaps simply have the Tobin Tax spread fee. Terra<>Luna spreads are the greater of
MinSpread
and spread from Constant Product pricing.
If the offerCoin
's denomination is the same as askDenom
, this will raise ErrRecursiveSwap
.
NOTE
k.ComputeSwap()
uses k.ComputeInternalSwap()
internally, which just contains the logic for calculating proper ask coins to exchange, without the Constant Product spread.
# k.ApplySwapToPool()
func (k Keeper) ApplySwapToPool(ctx sdk.Context, offerCoin sdk.Coin, askCoin sdk.DecCoin) sdk.Error
k.ApplySwapToPools()
is called during the swap to update the blockchain's measure of TerraPoolDelta
, when the balances of the Terra and Luna liquidity pools have changed.
Terra currencies share the same liquidity pool, so TerraPoolDelta
remains unaltered during Terra<>Terra swaps.
For Terra<>Luna swaps, the relative sizes of the pools will be different after the swap, and
- For Terra to Luna,
- For Luna to Terra,
# Transitions
# End-Block
Market module calls k.ReplenishPools()
at the end of every block, which decreases the value of TerraPoolDelta
(which measures the difference between Terra and Luna pools) depending on PoolRecoveryPeriod
,
This allows the network to sharply increase spread fees in during acute price fluctuations, and automatically return the spread to normal after some time when the price change is long term.
# Parameters
The subspace for the Market module is market
.
type Params struct {
PoolRecoveryPeriod int64 `json:"pool_recovery_period" yaml:"pool_recovery_period"`
BasePool sdk.Dec `json:"base_pool" yaml:"base_pool"`
MinSpread sdk.Dec `json:"min_spread" yaml:"min_spread"`
TobinTax sdk.Dec `json:"tobin_tax" yaml:"tobin_tax"`
}
# PoolRecoveryPeriod
- type:
int64
- default:
BlocksPerDay
Number of blocks it takes for the Terra & Luna pools to naturally "reset" toward equilibrium (
# BasePool
- type:
Dec
- default: 250,000 SDR (= 250,000,000,000 µSDR)
Initial starting size of both Terra and Luna liquidity pools.
# MinSpread
- type:
Dec
- default: 2%
Minimum spread charged on Terra<>Luna swaps to prevent leaking value from front-running attacks.
# TobinTax
- type:
Dec
- default: 0.25%
A fee added on for swap between Terra currencies (spot-trading).
Though contrary to our initial policy for zero-fee swaps, we have decided to implement the Tobin tax as a necessity to prevent attackers from exploiting the exchange rate latency and profiting at the cost of ordinary users. The rationale behind setting a Tobin tax at this rate is described in depth in this post (opens new window). ↩︎
For a more in-depth treatment of our updated market-making algorithm, check Nick Platias's SFBW 2019 presentation here (opens new window). ↩︎