Units

A deep dive into the Phoenix units system

Nomenclature and precision are important for understanding the internals of Phoenix. These quantities and conversions enable a robust way to understand how numerical data flows through the matching engine.

Atoms and Units

On Solana, all token quantities can be interpreted as a decimal value.

Token	Decimals	Amount (atoms)	Decimal interpretation (units)
SOL	9	1,000,000,000	1.0 SOL
USDC	6	1,000,000	1.0 USDC

In the context of Phoenix, the smallest possible quantity of a token is referred to as an atom. The associated decimal value for a number of atoms is measured in units.

To convert from an amount of atoms to units, we apply the following formula:

$$\begin{align*} 1 \text{ unit} &= 10^{\text{decimals}} \text{ atoms} \\ A \text{ atoms} &= \frac{K}{10^{\text{decimals}}} \text{ units} \end{align*}$$

Base and Quote

Every Phoenix market represents a venue for exchange between 2 assets (e.g. SOL/USDC). The asset being traded (in our example, SOL) is referred to as the base token and the asset that prices the base token is referred to as the quote token (in our example, USDC).

Lots

A lot is the smallest discrete unit of a token that the Phoenix matching engine can process. Every quantity that is passed into Phoenix must first be converted into the an integer number of lots. Note that lot sizes are set on a per-market level.

The smallest amount of base token (in atoms) the matching engine can work with is referred to as the base lot size, which is a quantity measured in base atoms per base lot.

The smallest amount of quote token (in atoms) the matching engine can work with is referred to as the quote lot size, which is a quantity measured in quote atoms per quote lot.

Converting Between Atoms and Lots

Token	Type	Lot size (units)	Lot size (atoms per lot)
SOL	Base	0.001	1,000,000
USDC	Quote	0.00001	10

We know that the number of base atoms per base unit (for SOL) is $10^9$. So if the base lot size in base units per base lot is 0.001 SOL, we can apply the following conversion to get the base lot size in base atoms per base lot:

$$\begin{equation*} 0.001 \frac{\text{base units}}{\text{base lot}} \times 10^9 \frac{\text{base atoms}}{\text{base units}} = 10^6 \frac{\text{base atoms}}{\text{base lot}} \end{equation*}$$

We can perform a similar conversion for the quote token.

$$0.00001 \frac{\text{quote units}}{\text{quote lot}} \times 10^6 \frac{\text{quote atoms}}{\text{quote unit}} = 10 \frac{\text{quote atoms}}{\text{quote lot}}$$

Ticks

A tick is the smallest discrete unit of price by which 2 orders on the book can differ; all valid prices on a market are an integer number of ticks. The size of a tick is measured in an integer number of quote lots per base unit.

Prices on the book are measured in an integer number of ticks.

Suppose the market has $Q$ quote lots per quote unit and a tick size of $T$ quote lots per base unit per tick. The following formula converts a price of $P$ ticks to the human-readable quote units per base unit:

$$P \text{ ticks} \times T \frac{\text{quote lots}}{\text{base unit} \times \text{tick}} \times \frac{1}{Q} \frac{\text{quote units}}{\text{quote lot}} = \frac{PT}{Q} \frac{\text{quote units}}{\text{base unit}}$$

Observe some examples in the table below:

Price (P)	Tick size (T)	Quote Lots/Quote Unit	Price (quote units/base unit)
2000	1000	10000	20.00
2000	100	1000	20.00
400	5000	10000	20.00

Order Sizes

Every order on the book is represented with a size $S$ in base lots at some price $P$ in ticks.

To compute the number of quote lots $Q$ this order represents (amount posted for bids and amount required to fill the order for offers), use the following formula. Assume a tick size of $T$ quote lots per base unit per tick and $B$ base lots per base unit.

$$P \text{ ticks} \times T \frac{\text{quote lots}}{\text{base unit} \times \text{tick}} \times S \text{ base lots} \times \frac{1}{B} \frac{\text{base units}}{\text{base lot}} = \frac{PTS}{B} \text{ quote lots}$$

Invariants

One important guarantee is that the book will enable trades of an integer number of quote lots for a single base lot at any price. What this means is that at a price of 1 tick, selling a 1 base lot, will return $K$quote lots where $K$is a nonnegative integer. We can rearrange the formula from the previous section to get the following equivalence:

$K* b \ \frac{quote\ lots}{base\ unit\ *\ tick} = T\ \frac{quote\ lots}{base\ unit\ *\ tick}$

This indicates that the tick size must be an integer multiple of the number of base lots found in a base unit