pooldepths.md

How to calculate depth from events

Keeping a running total of RUNE depth per pool requires the handling of several events: stakes, swaps, adds, rewards, errata, gas, emissions (?).

Here I will go through the events one by one and describe how to update the pool depths based on their values.

Stake event

Stake events are fired when an LP adds stake to a pool.

type Stake struct {
 Pool       []byte // asset ID
 AssetTx    []byte // transfer transaction ID (may equal RuneTx)
 AssetChain []byte // transfer backend ID
 AssetE8    int64  // transfer asset quantity times 100 M
 RuneTx     []byte // pool transaction ID
 RuneChain  []byte // pool backend ID
 RuneAddr   []byte // pool contender address
 RuneE8     int64  // pool transaction quantity times 100 M
 StakeUnits int64  // pool's liquidiy tokens—gained quantity
}

Which pool to update

Specified in the Pool field

RUNE depth

Add RuneE8

Asset depth

Add AssetE8

Unstake event

Stake events are fired when an LP adds stake to a pool.

type Unstake struct {
 Tx          []byte // THORChain transaction ID
 Chain       []byte // transfer backend ID
 FromAddr    []byte // transfer pool address
 ToAddr      []byte // transfer contender address
 Asset       []byte // transfer unit ID
 AssetE8     int64  // transfer quantity times 100 M
 Memo        []byte
 Pool        []byte  // asset ID
 StakeUnits  int64   // pool's liquidiy tokens—lost quantity
 BasisPoints int64   // ‱ of what?
 Asymmetry   float64 // lossy conversion of what?
}

Which pool to update

Specified in the Pool field

RUNE depth

If Asset equals RUNE Deduct AssetE8

Asset depth

If Asset is not RUNE Deduct AssetE8

Swap event

The swap event is fired when a user swaps one asset to another - either RUNE -> asset or asset -> RUNE

type Swap struct {
 Tx             []byte // THOR transaction identifier
 Chain          []byte // backend identifier
 FromAddr       []byte // input address on Chain
 ToAddr         []byte // output address on Chain
 FromAsset      []byte // input unit
 FromE8         int64  // FromAsset quantity times 100 M
 Memo           []byte // encoded parameters
 Pool           []byte // asset identifier
 ToE8Min        int64  // output quantity constraint
 TradeSlipBP    int64  // ‱ the trader experienced
 LiqFeeE8       int64  // Pool asset quantity times 100 M
 LiqFeeInRuneE8 int64  // equivalent in RUNE times 100 M
}

Which pool to update

Specified in the Pool field

RUNE depth

If FromAsset equals Pool then get the ToE8 amount by looking up the tx and add that value to the RUNE depth

Else if FromAsset is not equal to Pool then add FromE8 to the RUNE depth

Asset depth

If FromAsset equals Pool then add FromE8 to the asset depth

Else if FromAsset is not equal to Pool then get the ToE8 amount by looking up the tx and add that value to the RUNE depth

Add events

The add event is a rare event which is fired when an asset is manually added to the pool, most likely by the team incase there is a solvency issue.

type Add struct {
 Tx       []byte
 Chain    []byte
 FromAddr []byte
 ToAddr   []byte
 Asset    []byte
 AssetE8  int64 // Asset quantity times 100 M
 Memo     []byte
 RuneE8 int64 // Number of runes times 100 M
 Pool []byte
}

Which pool to update

Specified in the Pool field

RUNE depth

Add RuneE8

Asset depth

Add AssetE8

Reward events

This is an example of a bond:

{
  "bond_reward": "827404",
  "pool_rewards": [
    {
      "asset": "BNB.AVA-ADF",
      "amount": "4"
    },
    {
      "asset": "BNB.XRP-FB8",
      "amount": "14"
    },
    {
      "asset": "BNB.KAI-04E",
      "amount": "-3"
    }
  ]
}

rune depth for BNB.AVA-ADF will increase by 4

rune depth for BNB.XRP-FB8 will increase by 14

rune depth for BNB.KAI-04E will decrease by 3

type Rewards struct {
 BondE8 int64 // rune amount times 100 M
 Pool   []Amount
}

Which pool to update

Specified in the Pool array. Update each pool in the array as specified by the asset field

RUNE depth

Increase the RUNE depth for each pool by the number specified in the amount field

Asset depth

Do nothing

Errata events

Chain forks may cause this event to happen and they result in an update to pool depths similar to the add events.

type Errata struct {
 InTx    []byte
 Asset   []byte
 AssetE8 int64 // Asset quantity times 100 M
 RuneE8  int64 // Number of runes times 100 M
}

Which pool to update

Specified in Asset field

RUNE depth

Add RuneE8

Asset depth

Add AssetE8

Gas events

These are fired to "pay back" amounts paid out as gas to the pools under certain circumstances. We deduct the asset amount and increase the RUNE amount according to the event values.

type Gas struct {
 Asset   []byte
 AssetE8 int64 // Asset quantity times 100 M
 RuneE8  int64 // Number of runes times 100 M
 TxCount int64
}

Which pool to update

Specified in Asset field

RUNE depth

Add RuneE8

Asset depth

Deduct AssetE8

Emission events (?)

Apparently these should exist but they don't. Further investigation underway.