github.com/gravity-devs/liquidity@v1.5.3/x/liquidity/spec/02_state.md (about)

     1  <!-- order: 2 -->
     2  
     3   # State
     4  
     5  The liquidity module `x/liquidity` keeps track of the Pool and PoolBatch states. The state represents your app at a given moment.
     6  ## Pool
     7  
     8  Pool stores information about the liquidity pool.
     9  
    10  Pool type has the following structure.
    11  
    12  ```go
    13  type Pool struct {
    14      Id                     uint64         // index of this liquidity pool
    15      TypeId                 uint32         // pool type of this liquidity pool
    16      ReserveCoinDenoms      []string       // list of reserve coin denoms for this liquidity pool
    17      ReserveAccountAddress  string         // reserve account address for this liquidity pool to store reserve coins
    18      PoolCoinDenom          string         // denom of pool coin for this liquidity pool
    19  }
    20  ```
    21  
    22  The parameters of the Pool state are:
    23  
    24  - Pool: `0x11 | Id -> ProtocolBuffer(Pool)`
    25  
    26  - PoolByReserveAccIndex: `0x12 | ReserveAccLen (1 byte) | ReserveAcc -> ProtocolBuffer(uint64)`
    27  
    28  - GlobalLiquidityPoolIdKey: `[]byte("globalLiquidityPoolId")`
    29  
    30  - ModuleName, RouterKey, StoreKey, QuerierRoute: `liquidity`
    31  
    32  - PoolCoinDenomPrefix: `pool`
    33  ## PoolBatch
    34  
    35  PoolBatch stores information about the liquidity pool batch states.
    36  
    37  PoolBatch type has the following structure.
    38  
    39  ```go
    40  type PoolBatch struct {
    41      PoolId           uint64  // id of target liquidity pool
    42      Index            uint64  // index of this batch
    43      BeginHeight      uint64  // block height when batch is created
    44      DepositMsgIndex  uint64  // last index of DepositMsgStates
    45      WithdrawMsgIndex uint64  // last index of WithdrawMsgStates
    46      SwapMsgIndex     uint64  // last index of SwapMsgStates
    47      Executed         bool    // true if executed, false if not executed
    48  }
    49  ```
    50  
    51  ## Batch Messages
    52  
    53  Deposit, withdrawal, or swap orders are accumulated in a liquidity pool for a pre-defined period, which can be one or more blocks in length. Orders are then added to the pool and executed at the end of the batch. The following messages are executed in batch-style. 
    54  
    55  ### DepositMsgState
    56  
    57  `DepositMsgState` defines the state of deposit message as it is processed in the next batch or batches.
    58  
    59  When a user sends `MsgDepositWithinBatch` transaction to the network, it is accumulated in a batch. `DepositMsgState` contains the state information about the message; if the transaction is executed, successfully matched, and if it is to be deleted in the next block.
    60  
    61  ```go
    62  type DepositMsgState struct {
    63      MsgHeight  int64  // block height where this message is appended to the batch
    64      MsgIndex   uint64 // index of this deposit message in this liquidity pool
    65      Executed   bool   // true if executed on this batch, false if not executed
    66      Succeeded  bool   // true if executed successfully on this batch, false if failed
    67      ToBeDelete bool   // true if ready to be deleted on kvstore, false if not ready to be deleted
    68      Msg        MsgDepositWithinBatch
    69  }
    70  ```
    71  ### WithdrawMsgState
    72  
    73  `WithdrawMsgState` defines the state of the withdraw message as it is processed in the next batch or batches.
    74  
    75  When a user sends a `MsgWithdrawWithinBatch` transaction to the network, it is accumulated in a batch. `WithdrawMsgState` contains the state information about the message:
    76  
    77  - If the transaction is executed
    78  - If the transaction is successfully matched
    79  - If the transaction will be deleted in the next block
    80  
    81  ```go
    82  type WithdrawMsgState struct {
    83      MsgHeight  int64  // block height where this message is appended to the batch
    84      MsgIndex   uint64 // index of this withdraw message in this liquidity pool
    85      Executed   bool   // true if executed on this batch, false if not executed
    86      Succeeded  bool   // true if executed successfully on this batch, false if failed
    87      ToBeDelete bool   // true if ready to be deleted on kvstore, false if not ready to be deleted
    88      Msg        MsgWithdrawWithinBatch
    89  }
    90  ```
    91  ### SwapMsgState
    92  
    93  `SwapMsgState` defines the state of swap message as it is processed in the next batch or batches.
    94  
    95  When a user sends a `MsgSwapWithinBatch` transaction to the network, it is accumulated in a batch. `SwapMsgState` contains the state information about the message:
    96  
    97  - If the transaction is executed
    98  - If the transaction is successfully matched
    99  - If the transaction will be deleted in the next block
   100  
   101  ```go
   102  type SwapMsgState struct {
   103      MsgHeight          int64  // block height where this message is appended to the batch
   104      MsgIndex           uint64 // index of this swap message in this liquidity pool
   105      Executed           bool   // true if executed on this batch, false if not executed
   106      Succeeded          bool   // true if executed successfully on this batch, false if failed
   107      ToBeDelete         bool   // true if ready to be deleted on kvstore, false if not ready to be deleted
   108      OrderExpiryHeight  int64  // swap orders are cancelled when current height is equal to or greater than ExpiryHeight
   109      ExchangedOfferCoin sdk.Coin // offer coin exchanged so far
   110      RemainingOfferCoin sdk.Coin // offer coin  remaining to be exchanged
   111      Msg                MsgSwapWithinBatch
   112  }
   113  ```
   114  
   115  The parameters of the PoolBatch, DepositMsgState, WithdrawMsgState, and SwapMsgState states are:
   116  
   117  - PoolBatch: `0x22 | PoolId -> ProtocolBuffer(PoolBatch)`
   118  
   119  - PoolBatchDepositMsgStates: `0x31 | PoolId | MsgIndex -> ProtocolBuffer(DepositMsgState)`
   120  
   121  - PoolBatchWithdrawMsgStates: `0x32 | PoolId | MsgIndex -> ProtocolBuffer(WithdrawMsgState)`
   122  
   123  - PoolBatchSwapMsgStates: `0x33 | PoolId | MsgIndex -> ProtocolBuffer(SwapMsgState)`