Skip to main content

Types

This segment introduces key data types essential for understanding and working with the Invariant Protocol. Additionally, it's important to note that these types are defined based on decimals, holding numerical values, and serving as fundamental types in the storage layer.

Defining Decimal

We have implemented a custom decimal system, which is detailed in our repository here. The structure of the decimal is outlined below in Rust syntax:

#[decimal(#scale, #big_type)]
pub struct DecimalName(pub #underlying_type)
NameDescription
#scaleAn integer that determines the number of decimal places.
#big_typeThe type to which it will be extended in big operations (default is U256).
DecimalNameThe name of the struct.
#underlying_typeThe underlying numeric type.

Examples

Creating a custom decimal type with name "Decimal", 3 decimal places, u128 as underyling type and default big type (U256):

#[decimal(3)]
pub struct Decimal(pub u128)

Creating a decimal value:

let my_decimal = Decimal::new(12042);

In this example, the result of creation should be interpreted as 12.042, calculated as 12042 * 10^-3, considering the specified scale of 3.

Definitions

These decimal types are integral to the protocol, offering a granular level of precision for various calculations. They play key roles in pricing, fee accumulation, liquidity representation, percentage metrics, time measurements, and token quantity tracking, contributing to the robust functionality of the Invariant Protocol.

NameDecimalsPrimitive typeBig typeDescription
TokenAmount0u128U256Quantity of specific token
SqrtPrice24u128U256Square root of price value
FixedPoint24U256U512Number with fixed number of decimal places
Liquidity6u128U256Amount of virtual liquidity
Percentage12u64U256A numerical percentage value
FeeGrowth28U256U512Accumulated amount of fees per unit of liquidity
SecondsPerLiquidity24u128U256Measures the time in seconds per unit of liquidity

TokenAmount

The TokenAmount type stores integer token amounts.

#[decimal(0)]
pub struct TokenAmount(pub u128);

SqrtPrice

The SqrtPrice type stores the square root of the y-to-x token ratio.

#[decimal(24)]
pub struct SqrtPrice(pub u128);

FixedPoint

FixedPoint is a helper type used for calculating SqrtPrice. The only difference is it has U256 type to avoid additional type casting.

#[decimal(24)]
pub struct FixedPoint(pub U256);

Liquidity

The liquidity type represents a value that indicates the ability to exchange. Liquidity is determined by the product of the amount of tokens X, the amount of tokens Y, or the sum of X and Y, and the level of concentration. It is associated with a specific price range. As a result, it can be either active or inactive, depending on whether the current price is within or outside the liquidity range.

#[decimal(6)]
pub struct Liquidity(pub u128);

Percentage

The type represents a percentage and is used to simplify interest calculations for various types.

#[decimal(12)]
pub struct Percentage(pub u64);

FeeGrowth

FeeGrowth is used to calculate the fee amount within a specified price range. FeeGrowth represents TokenAmount in X or Y per unit of liquidity.

#[decimal(28)]
pub struct FeeGrowth(pub U256);

SecondsPerLiquidity

SecondsPerLiquidity represents the time difference measured in seconds per liquidity unit. This metric is employed to calculate the accumulated time during which the price was situated between any given ticks. While not essential for the core functionality of CLAMM, it serves a crucial role in constructing farms or incentives for token distribution across diverse models. For instance, it enables the prioritization of the most concentrated liquidity, fostering the development of farms and incentives that align with specific liquidity concentration preferences.

#[decimal(24)]
pub struct SecondsPerLiquidity(pub u128);