Skip to content

Lyrebird Aviary

Contract Information

Script Hash: 0x4768c475e4c8465f2edf97f265c85950dfebc787

Address: NYHuuS7ZLZ7BhQratBbj9PTzjjCW9zMedp

Overview

The Aviary is a contract that implements swap functionality between LRB and L-assets. It needs to address several concerns:

  1. Providing swaps between LRB and L-assets with a low enough spread to ensure that arbitrage activity can maintain the L-asset price close to the target price.
  2. Ensuring that the protocol can survive a sudden and drastic increase in selling pressure on L-assets.
  3. Protecting the protocol from malicious actors who may attempt to manipulate Oracle prices to generate favorable swaps.

In order to address all three of these concerns, the Aviary contract implements a modified Uniswap-style constant product virtual pool.

\[ k = Pool_{$LRB} \cdot Pool_{$L-assets} \]

In this equation, \(Pool_{$LRB}\) refers to the USD value of the LRB virtual pool and \(Pool_{$L-assets}\) refers to the USD value of the L-asset virtual pool. Note how this differs from Uniswap, in which each pool is the quantity of the token.

As an example, if the current price of LRB is $0.10, the target price of USDL is $1.00, and both pool sizes at $100, we have an initial condition of:

\[ k = 100 \cdot 100 = 10000 \]

If we then swap 10 LRB = $1.00 for USDL, we must have:

\[ Pool_{$L-assets} = \frac{k}{Pool_{$LRB}} = \frac{10000}{101} \approx 99.01 \]

Thus, we receive approximately \(100 - 99.01 = 0.99\) dollars worth of USDL, which also happens to be 0.99 USDL since the target price of USDL is $1.00. In this example, the swap spread ended up being 1%, but in practice it will generally be smaller since the default pool sizes are set to $2.5 million. There is, however, a minimum spread of 0.25% that is applied to every swap transaction that would otherwise incur a smaller swap spread.

This pool-based swap mechanism offers several advantages over a simple model that always exchanges tokens at the same rate, including:

  • Unlimited liquidity at reasonable prices unless there is a large amount of trade activity in one direction in a small period of time.
  • Increased difficulty of exchange price manipulation by a malicious party to generate favorable swaps.

However, there are also a couple of disadvantages:

  • In case of large and sudden market movements, the L-asset pegs will not be precisely held. However, we believe an eventual recovery to be a more favorable outcome than a possible collapse of the protocol due to attempting to hold the precise peg.
  • Increased swap spread fees in the same direction for anyone attempting to trade after a large swap.

To counteract the potential increase in swap spread fees after large swaps, we implement a pool recovery period of 240 blocks - roughly 1 hour - at which point the virtual pools will reset to their original values. The pool recovery happens continuously and linearly.

Oracle Prices

The Aviary contract makes heavy use of Neo N3's native Oracle to ensure that swaps are computed at fair prices. Because the Oracle requires multiple nodes to retrieve the same value, Lyrebird's price feed updates every cycle, as soon as new block is added.

If the latest price is more than 5 minutes old, the price will be deemed invalid and swap activity will be denied until the price feed is restored.

For L-assets, there are two definitions of price that are relevant, both expressed in USD value. The first is the actual price of the token based on exchange activity. We refer to this quantity simply as the price. The second is the target price peg of the token, which we refer to as the targetPrice. targetPrice is the quantity that is used for computing the swap output. For USDL, this is always $1.00. As Lyrebird starts to support more currencies, this quantity will vary with fluctuating cross rates.

Initially, LRB and USDL will only be listed on Flamingo so the price feed will come directly from Flamingo. Once they start trading on more exchanges, price feeds will be weighted by transaction volume.

While not likely, it is always possible that some Oracle nodes retrieve the price before update and some nodes after; this will result in an error and the swap transaction will be refunded.

Swap Spread Fee Collection

Users executing swaps will pay the swap spread denominated in the desired token. As an example, if a user exchanges LRB for USDL, the swap spread fee will be paid in USDL.

Fees collected denominated in LRB and all L-assets will be held by the Aviary contract and distributed periodically to LRB stakers in proportion to their staked quantities.

Hatchery Reserve

Lyrebird features a community pool affectionately known as the Hatchery. The Hatchery's reserves are accumulated through swap activity in the Aviary contract. These reserves may be used to fund ecosystem projects, distributed to LRB stakers, or burned as the community sees fit.

When an L-asset is exchanged for LRB, the offered L-asset quantity is burned. However, when LRB is exchanged for an L-asset, a parameter burnRatio determines the percentage of the offered LRB to be burned. The remaining quantity is set aside and peridically sent to fund the Hatchery.

burnRatio will be initially set to 0 and increased as swap activity stabilizes and funds are accumulated.

Tunable Parameters

oracleFee (default=0.15)
The amount of GAS sent to the Oracle to fund the response invocation on a swap request.
minSpread (default=0.25%)
The minimum spread fee to be charged on a swap request.
basePool (default=2_500_000)
The dollar value of the equilibrium LRB and L-asset virtual pool sizes.
poolRecoveryPeriod (default=240)
The number of blocks after which the virtual pool sizes will return to their initial values.
burnRate (default=0.0)
The percentage of LRB offered on swap to be burned.