Architecture

Sonic

This is the main entry point contract that coordinates the unstaking flow and allows other users to fulfill withdraw orders at a discount. In this contract the user starts an unstaking request by providing the parameters for the order to inform other users of their request to exit and the discount they are willing to give in order for their order to be fulfilled as soon as possible. These orders can then be viewed and fulfilled by other users who wish to buy the derivative tokens at the discount specified by the initial order's owner.

Read more about Sonic contract: here

Buy order (buy LSD or deposit)

With Sonic, users have the flexibility to interact with each supported liquid token in two ways. They can choose to stake their base token directly and receive the corresponding liquid token, or they can take advantage of the automatic market order fulfillment option to purchase the liquid token at a discounted rate. Sonic leverages the existing order book of the same token type to offer discounted buying opportunities, ensuring users can maximize their returns while participating in the liquidity ecosystem.

Fulfilling an order

There are two modalities for a user to fulfill a limit order. The user can decide to fulfill an order of an LSD, thus at the time of fulfillment, the user receives the LSD in exchange for the base tokens at the current market rate minus the discount provided by the order owner.

The second modality pertains to orders where the owner decides to start the withdrawal (aka unbonding) process. In this case, the user fulfilling the order receives the claim on the unbonding order of the LSDs. The order creator receives the tokens when the order is fulfilled, and the one who fulfilled the order receives the native tokens once the unbonding period is over.

Selling an order (sell or withdraw)

A user looking to withdraw their LSD can create a limit order to be sent to the market using two modalities.

In the first modality the user may decide to try to sell the liquid tokens at a discount, but may choose not to withdraw (aka unstake) the tokens at the same time. Thus while the order remains, the user continues to accrue staking rewards and the person (or contract) on the other side will receive in turn the same LSD when fulfilling the order.

In the second modality, the user may decide to start the withdrawal process. In this scenario two outcomes can happen, given an attractive discount, someone will fulfill the order, and the owner of the order will receive the base tokens much earlier than the unbonding period. If there were to be no takers of the order during this time, the user will come back and claim (similarly to standard unstaking at the original liquid token contract) the base tokens.

Strategies

A Strategy is a tested contract that handles the logic for a specific chain. It is responsible for the staking and unstaking of funds while also ensuring the correct exchange rate of the underlying token to the derivative token. A Strategy must implement the following methods:

/// @notice Returns id of the withdraw order processed
function withdraw(uint256 amount) external returns (uint256);

/// @notice After unbonding period user can claim base tokens
function claim(uint256 id) external returns (uint256);

/// @notice Refunds liquid tokens after a unbonding order expires
function refund(uint256 id) external returns (uint256);

/// @notice Returns the amount of base tokens on a given order
function getAmountTokenOrder(uint256 id) external view returns (uint256);

/// @notice Exchanges amount of liquid tokens to base tokens at current exchange rate
function exchangeLiquidTokens(uint256 amount) external view returns (uint256);

/// @notice Exchanges amount of liquid tokens to base tokens at current exchange rate
function getStatus(uint256 id) external view returns (OrderStatus);

Exchange Rate Protection

The FxProtection is a feature to ensure that the rates originating from the staking protocols deviate only within the predicted bounds of the yearly rates to ensure no external factors may manipulate the contract or the funds. When a new strategy is added, tolerated deviations on the exchange rate are configured. In certain situations, e.g. in massive slashing events, where the exchange rate volatility may increase more than the historic norm, the contract will lock itself and an admin/dao override is required to resume operations.