Accounting fields of Custodies

Let's first review the fields on the Assets of the Custody object, where the accounting is primarily done:

#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
pub struct AssetsData {
    /// Total tokens in the insurance fund
    pub insurance: u64,
    /// Total tokens lost when we owe profits to users that aren't covered by locked_amount, or the insurance fund, and we have to pay them.
    pub impairment_losses: u64,
    /// Losses incurred by users when they are owed profits and we are unable to pay them because we have no tokens between
    /// the insurance fund or the custody with which to do it.
    pub user_losses: u64,
    /// Total tokens collateral + base provided by swap
    pub owned: u64,
    /// When users swap in tokens for LP tokens, this goes up or down
    pub base: u64,
    /// Increased by some % of the maximum total value of a trade when initiated (fees not included)
    /// These tokens cannot then be used by some other trade until the position is closed.
    pub locked: u64,
    /// total tokens longed
    pub longed: u64,
    /// total shorted
    pub shorted: u64,
    /// Total loans across the custody
    pub guaranteed_usd: u64,
    /// total tokens that can be reinvested in LP purchases. owned + fee_reserves = total tokens in the token account.
    pub fee_reserves: u64,
}

Key Fields

Overview

The three most important fields for tracking the health of a Custody are locked, base, and owned.

locked represents the sum total of all tokens in all Positions being set aside to pay off collateral, loans, fees, and some profit, to traders that cannot be unlocked by LPs until those Positions are closed or liquidated.

base represents all tokens in a specific Custody given by LPs for use in loans. Not all of them are available for use.

owned represents all tokens in a specific Custody given by LPs or traders. Not all are available for use.

Key Relationships

They're related quite simply. This is always true:

owned >= base >= locked

Also, if we add up all the collateral in the Positions of the system, then it's true that

owned = base + all_position_collateral

It's also true that when an LP injects stablecoins into a Pool, they are placed in the appropriate Custody for that mint address and then the LP is given LP tokens from the Pool according to a constant product curve across all Custodies assuming a 1:1 value between the stables.

When this happens, base is increased. Concomitantly, if an LP wants to remove tokens from the Pool, the only tokens available for removal are those not locked for use in Positions, which means they can only exchange:

exchangeable_tokens = base - locked

Note that there is a lower limit beyond this equation according to the trade_blockage_utilization_limit but we're simplifying here.

Now, the strategy of holding back locked tokens from LPs does prevent traders from potentially losing their collateral and some profit, as well as the Custody from losing it's loan in each Position if LP's want to raid the Custody.

What the strategy does not do is prevent the LPs from impairment losses due to traders making profits above and beyond the locked_amounts previously set during Position initializations due to the position closure payout rules.

What Changes the Fields

locked

locked is increased when a Position is initialized and tokens are allocated to fund it so that it can later payoff it's collateral, loan, fee, and some profit obligations. locked will be increased again when a Position is decreased in size if locked_amount on the Position is less than size_usd.

locked decreases when a Position closes, partially closes, or liquidates and these tokens are no longer needed to be held in a locked state. When this happens, this means that tokens are now freed up for use in other loans, or paid out to the trader in the prior Position as profits or collateral payback.

base

base can be increased when LPs add stablecoins of the same mint type as the Custody to the Pool in exchange for the LP tokens of that Pool, and decreased by a similar transaction. It can also be increased by losses from traders forcing them to leave collateral in the system permanently, and decreased by profits to traders forcing the Custody to part ways with tokens to pay them out, according to payout rules.

owned

owned is increased whenever base is increased and vice versa and mirrors it as much as possible. It differs from base in that it also includes all collateral tokens present in the Custody on top of LP tokens. Whenever a Position is opened or increased, the collateral added increases owned. When a Position is closed, owned is correspondingly decreased.