Expand description
§Orca Whirlpools Core SDK
This package provides developers with advanced functionalities for interacting with the Whirlpool Program on Solana. The Core SDK offers convenient methods for math calculations, quotes, and other utilities, making it easier to manage complex liquidity and swap operations within Rust projects. It serves as the foundation for the High-Level SDK, providing key building blocks that enable developers to perform sophisticated actions while maintaining control over core details.
§Key Features
- Math Library: Contains a variety of functions for math operations related to bundles, positions, prices, ticks, and tokens, including calculations such as determining position status or price conversions.
- Quote Library: Provides utility functions for generating quotes, such as increasing liquidity, collecting fees or rewards, and swapping, enabling precise and optimized decision-making in liquidity management.
§Installation
cargo add orca_whirlpools_core
§Usage
Here are some basic examples of how to use the package:
§Math Example
The following example demonstrates how to use the is_position_in_range function to determine whether a position is currently in range.
use orca_whirlpools_core::is_position_in_range;
fn main() {
let current_sqrt_price = 7448043534253661173u128;
let tick_index_1 = -18304;
let tick_index_2 = -17956;
let in_range = is_position_in_range(current_sqrt_price.into(), tick_index_1, tick_index_2);
println!("Position in range? {:?}", in_range);
}Expected output:
Position in range? true§Adjust Liquidity Quote Example
The following example demonstrates how to use the increase_liquidity_quote_a function to calculate a quote for increasing liquidity given a token A amount.
use orca_whirlpools_core::increase_liquidity_quote_a;
use orca_whirlpools_core::TransferFee;
fn main() {
let token_amount_a = 1000000000u64;
let slippage_tolerance_bps = 100u16;
let current_sqrt_price = 7437568627975669726u128;
let tick_index_1 = -18568;
let tick_index_2 = -17668;
let transfer_fee_a = Some(TransferFee::new(200));
let transfer_fee_b = None;
let quote = increase_liquidity_quote_a(
token_amount_a,
slippage_tolerance_bps,
current_sqrt_price.into(),
tick_index_1,
tick_index_2,
transfer_fee_a,
transfer_fee_b,
).unwrap();
println!("{:?}", quote);
}Expected output:
IncreaseLiquidityQuote {
liquidity_delta: 16011047470,
token_est_a: 1000000000,
token_est_b: 127889169,
token_max_a: 1010000000,
token_max_b: 129168061,
}Structs§
Enums§
Constants§
- The denominator of the fee rate value.
- Pools with tick spacing above this threshold are considered full range only. This means the program rejects any non-full range positions in these pools.
- The maximum sqrt price for a whirlpool.
- The maximum tick index.
- The minimum sqrt price for a whirlpool.
- The minimum tick index.
- The number of reward tokens in a pool.
- The maximum number of positions in a position bundle.
- The number of ticks in a tick array.
Functions§
- Calculate fees owed for a position
- Calculate rewards owed for a position
- Calculate the quote for decreasing liquidity
- Calculate the quote for decreasing liquidity given a token a amount
- Calculate the quote for decreasing liquidity given a token b amount
- Get the first unoccupied position in a bundle
- Get the minimum and maximum tick index that can be initialized.
- Get the initializable tick index. If the tick index is already initializable, it is returned as is.
- Get the next initializable tick index.
- Get the previous initializable tick index.
- Get the first tick index in the tick array that contains the specified tick index.
- Get the index of a tick in a tick array.
- Calculate the quote for increasing liquidity
- Calculate the quote for increasing liquidity given a token a amount
- Calculate the quote for increasing liquidity given a token b amount
- Invert a price IMPORTANT: floating point operations can reduce the precision of the result. Make sure to do these operations last and not to use the result for further calculations.
- Get the sqrt price for the inverse of the price that this tick represents. Because converting to a tick index and then back to a sqrt price is lossy, this function is clamped to the nearest tick index.
- Get the tick index for the inverse of the price that this tick represents. Eg: Consider tick i where Pb/Pa = 1.0001 ^ i inverse of this, i.e. Pa/Pb = 1 / (1.0001 ^ i) = 1.0001^-i
- Check if a whirlpool is a full-range only pool.
- Check whether a position bundle is empty
- Check whether a position bundle is full A position bundle can contain 256 positions
- Check if a position is in range. When a position is in range it is earning fees and rewards
- Check if a tick is in-bounds.
- Check if a tick is initializable. A tick is initializable if it is divisible by the tick spacing.
- Order tick indexes in ascending order. If the lower tick index is greater than the upper tick index, the indexes are swapped. This is useful for ensuring that the lower tick index is always less than the upper tick index.
- Calculate the token_a / token_b ratio of a (ficticious) position
- Calculate the status of a position The status can be one of three values:
- Convert a price into a sqrt priceX64 IMPORTANT: floating point operations can reduce the precision of the result. Make sure to do these operations last and not to use the result for further calculations.
- Convert a price into a tick index IMPORTANT: floating point operations can reduce the precision of the result. Make sure to do these operations last and not to use the result for further calculations.
- Convert a sqrt priceX64 into a tick index IMPORTANT: floating point operations can reduce the precision of the result. Make sure to do these operations last and not to use the result for further calculations.
- Derive the tick index from a sqrt price. The precision of this method is only guarranted if tick is within the bounds of {max, min} tick-index.
- Computes the exact input or output amount for a swap transaction.
- Computes the exact input or output amount for a swap transaction.
- Convert a tick index into a price IMPORTANT: floating point operations can reduce the precision of the result. Make sure to do these operations last and not to use the result for further calculations.
- Derive the sqrt-price from a tick index. The precision of this method is only guarranted if tick is within the bounds of {max, min} tick-index.
- Apply a swap fee to an amount e.g. You send 10000 amount with 10000 fee rate. The fee amount will be 100. So the amount after fee will be 9900.
- Apply a transfer fee to an amount e.g. You send 10000 amount with 100 fee rate. The fee amount will be 100. So the amount after fee will be 9900.
- Calculate the amount A delta between two sqrt_prices
- Calculate the amount B delta between two sqrt_prices
- Get the maximum amount with a slippage tolerance e.g. Your estimated amount you send is 10000 with 100 slippage tolerance. The max you send will be 10100.
- Get the minimum amount with a slippage tolerance e.g. Your estimated amount you receive is 10000 with 100 slippage tolerance. The min amount you receive will be 9900.
- Calculate the next square root price
- Calculate the next square root price
- Reverse the application of a swap fee to an amount e.g. You received 9900 amount with 10000 fee rate. The fee amount will be 100. So the amount before fee will be 10000.
- Reverse the application of a transfer fee to an amount e.g. You received 9900 amount with 100 fee rate. The fee amount will be 100. So the amount before fee will be 10000.