Skip to content

Commit

Permalink
docs: update spec docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@kingcre
kingcre committed Sep 7, 2023
1 parent 3796495 commit 383f79b
Show file tree
Hide file tree
Showing 15 changed files with 138 additions and 430 deletions.
42 changes: 23 additions & 19 deletions x/amm/spec/02_state.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,41 @@

## Pool

* LastPoolId: `0x?? -> BigEndian(LastPoolId)`
* Pool: `0x?? | BigEndian(PoolId) -> ProtocolBuffer(Pool)`
* PoolByReserveAddressIndex: `0x?? | AddrLen (1 byte) | ReserveAddress -> BigEndian(PoolId)`
* PoolByMarketIndexKeyPrefix: `0x?? | BigEndian(MarketId) -> BigEndian(PoolId)`
* PoolState: `0x?? | BigEndian(PoolId) -> ProtocolBuffer(PoolState)`
* LastPoolId: `0x40 -> BigEndian(LastPoolId)`
* Pool: `0x42 | BigEndian(PoolId) -> ProtocolBuffer(Pool)`
* PoolState: `0x43 | BigEndian(PoolId) -> ProtocolBuffer(PoolState)`
* PoolByReserveAddressIndex: `0x44 | AddrLen (1 byte) | ReserveAddress -> BigEndian(PoolId)`
* PoolByMarketIndexKeyPrefix: `0x45 | BigEndian(MarketId) -> BigEndian(PoolId)`

```go
type Pool struct {
Id uint64
MarketId uint64
Denom0 string
Denom1 string
TickSpacing uint32
ReserveAddress string
Id uint64
MarketId uint64
Denom0 string
Denom1 string
ReserveAddress string
RewardsPool string
TickSpacing uint32
MinOrderQuantity sdk.Dec
MinOrderQuote sdk.Dec
}

type PoolState struct {
CurrentTick int32
CurrentPrice sdk.Dec
CurrentLiquidity sdk.Int
TotalLiquidity sdk.Int
FeeGrowthGlobal sdk.DecCoins
FarmingRewardsGrowthGlobal sdk.DecCoins
}
```

## Position

* LastPositionId: `0x?? -> BigEndian(LastPositionId)`
* Position: `0x?? | BigEndian(PositionId) -> ProtocoulBuffer(Position)`
* PositionByParamsIndex: `0x?? | BigEndian(PoolId) | AddrLen (1 byte) | Owner | Sign (1 byte) | BigEndian(LowerTick) | Sign (1 byte) | BigEndian(UpperTick) -> BigEndian(PositionId)`
* PositionsByPoolIndex: `0x?? | BigEndian(PoolId) | BigEndian(PositionId) -> nil`
* LastPositionId: `0x41 -> BigEndian(LastPositionId)`
* Position: `0x46 | BigEndian(PositionId) -> ProtocoulBuffer(Position)`
* PositionByParamsIndex: `0x47 | AddrLen (1 byte) | Owner | BigEndian(PoolId) | Sign (1 byte) | BigEndian(LowerTick) | Sign (1 byte) | BigEndian(UpperTick) -> BigEndian(PositionId)`
* PositionsByPoolIndex: `0x48 | BigEndian(PoolId) | BigEndian(PositionId) -> nil`

```go
type Position struct {
Expand All @@ -53,7 +57,7 @@ type Position struct {

## TickInfo

* TickInfo: `0x?? | BigEndian(PoolId) | Sign (1 byte) | BigEndian(Tick) -> ProtocolBuffer(TickInfo)`
* TickInfo: `0x49 | BigEndian(PoolId) | Sign (1 byte) | BigEndian(Tick) -> ProtocolBuffer(TickInfo)`

```go
type TickInfo struct {
Expand All @@ -66,9 +70,9 @@ type TickInfo struct {

## FarmingPlan

* LastFarmingPlanId: `0x?? -> BigEndian(LastFarmingPlanId)`
* FarmingPlan: `0x?? | BigEndian(FarmingPlanId) -> ProtocolBuffer(FarmingPlan)`
* NumPrivateFarmingPlans: `0x?? -> BigEndian(NumPrivateFarmingPlans)`
* LastFarmingPlanId: `0x4a -> BigEndian(LastFarmingPlanId)`
* FarmingPlan: `0x4b | BigEndian(FarmingPlanId) -> ProtocolBuffer(FarmingPlan)`
* NumPrivateFarmingPlans: `0x4c -> BigEndian(NumPrivateFarmingPlans)`

```go
type FarmingPlan struct {
Expand Down
16 changes: 9 additions & 7 deletions x/amm/spec/06_params.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,12 @@

The amm module contains the following parameters:

| Key | Type | Example |
|-------------------------------|-----------------------|----------------------------------------|
| PoolCreationFee | array (sdk.Coins) | [{"denom":"stake","amount":"1000000"}] |
| DefaultTickSpacing | uint32 | 25 |
| PrivateFarmingPlanCreationFee | array (sdk.Coins) | [{"denom":"stake","amount":"1000000"}] |
| MaxNumPrivateFarmingPlans | uint32 | 50 |
| MaxFarmingBlockTime | int64 (time.Duration) | 10s |
| Key | Type | Example |
|-------------------------------|-----------------------|---------------------------------------|
| PoolCreationFee | array (sdk.Coins) | [{"denom":"ucre","amount":"1000000"}] |
| DefaultTickSpacing | uint32 | 25 |
| DefaultMinOrderQuantity | sdk.Dec | "10000.000000000000000000" |
| DefaultMinOrderQuote | sdk.Dec | "10000.000000000000000000" |
| PrivateFarmingPlanCreationFee | array (sdk.Coins) | [{"denom":"ucre","amount":"1000000"}] |
| MaxNumPrivateFarmingPlans | uint32 | 50 |
| MaxFarmingBlockTime | int64 (time.Duration) | 10s |
1 change: 1 addition & 0 deletions x/amm/spec/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ parent:
* [MsgRemoveLiquidity](03_messages.md#msgremoveliquidity)
* [MsgCollect](03_messages.md#msgcollect)
* [MsgCreatePrivateFarmingPlan](03_messages.md#msgcreateprivatefarmingplan)
* [MsgTerminatePrivateFarmingPlan](03_messages.md#msgterminateprivatefarmingplan)
4. [Begin-Block](04_begin_block.md)
5. [Events](05_events.md)
* [Begin-Block](05_events.md#begin-block)
Expand Down
39 changes: 19 additions & 20 deletions x/exchange/spec/02_state.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,20 @@

## Market

* LastMarketId: `0x?? -> BigEndian(LastMarketId)`
* Market: `0x?? | BigEndian(MarketId) -> ProtocolBuffer(Market)`
* MarketState: `0x?? | BigEndian(MarketId) -> ProtocolBuffer(Market)`
* MarketByDenomsIndex: `0x?? | DenomLen (1 byte) | BaseDenom | QuoteDenom -> BigEndian(MarketId)`
* LastMarketId: `0x60 -> BigEndian(LastMarketId)`
* Market: `0x62 | BigEndian(MarketId) -> ProtocolBuffer(Market)`
* MarketState: `0x63 | BigEndian(MarketId) -> ProtocolBuffer(Market)`
* MarketByDenomsIndex: `0x64 | DenomLen (1 byte) | BaseDenom | QuoteDenom -> BigEndian(MarketId)`

```go
type Market struct {
Id uint64
BaseDenom string
QuoteDenom string
EscrowAddress string
MakerFeeRate sdk.Dec
TakerFeeRate sdk.Dec
Id uint64
BaseDenom string
QuoteDenom string
EscrowAddress string
MakerFeeRate sdk.Dec
TakerFeeRate sdk.Dec
OrderSourceFeeRatio sdk.Dec
}

type MarketState struct {
Expand All @@ -27,9 +28,11 @@ type MarketState struct {

## Order

* LastOrderId: `0x?? -> BigEndian(LastOrderId)`
* OrderKey: `0x?? | BigEndian(OrderId) -> ProtocoulBuffer(Order)`
* OrderBookOrderIndex: `0x?? | BigEndian(MarketId) | IsBuy | SortableDecBytes(Price) | BigEndian(OrderId) -> BigEndian(OrderId)`
* LastOrderId: `0x61 -> BigEndian(LastOrderId)`
* OrderKey: `0x65 | BigEndian(OrderId) -> ProtocoulBuffer(Order)`
* OrderBookOrderIndex: `0x66 | BigEndian(MarketId) | IsBuy | SortableDecBytes(Price) | BigEndian(OrderId) -> BigEndian(OrderId)`
* OrdersByOrdererIndex: `0x67 | AddrLen (1 byte) | Orderer | BigEndian(MarketId) | BigEndian(OrderId) -> nil`
* NumMMOrders: `0x68 | AddrLen (1 byte) | Orderer | BigEndian(MarketId) -> BigEndian(NumMMOrders)`

```go
type Order struct {
Expand All @@ -39,10 +42,10 @@ type Order struct {
MarketId uint64
IsBuy bool
Price sdk.Dec
Quantity sdk.Int
Quantity sdk.Dec
MsgHeight int64
OpenQuantity sdk.Int
RemainingDeposit sdk.Int
OpenQuantity sdk.Dec
RemainingDeposit sdk.Dec
Deadline time.Time
}

Expand All @@ -54,7 +57,3 @@ const (
OrderTypeMM OrderType = 2
)
```

## Transient Balance Difference

* TransientBalance: `0x?? | AddrLen (1 byte) | Address | Denom -> ProtocolBuffer(Amount)`
14 changes: 7 additions & 7 deletions x/exchange/spec/03_messages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ type MsgPlaceLimitOrder struct {
MarketId uint64
IsBuy bool
Price sdk.Dec
Quantity sdk.Int
Quantity sdk.Dec
Lifespan time.Duration
}
```
Expand All @@ -33,7 +33,7 @@ type MsgPlaceBatchLimitOrder struct {
MarketId uint64
IsBuy bool
Price sdk.Dec
Quantity sdk.Int
Quantity sdk.Dec
Lifespan time.Duration
}
```
Expand All @@ -46,7 +46,7 @@ type MsgPlaceMMLimitOrder struct {
MarketId uint64
IsBuy bool
Price sdk.Dec
Quantity sdk.Int
Quantity sdk.Dec
Lifespan time.Duration
}
```
Expand All @@ -59,7 +59,7 @@ type MsgPlaceMMBatchLimitOrder struct {
MarketId uint64
IsBuy bool
Price sdk.Dec
Quantity sdk.Int
Quantity sdk.Dec
Lifespan time.Duration
}
```
Expand All @@ -71,7 +71,7 @@ type MsgPlaceMarketOrder struct {
Sender string
MarketId uint64
IsBuy bool
Quantity sdk.Int
Quantity sdk.Dec
}
```

Expand Down Expand Up @@ -99,7 +99,7 @@ type MsgCancelAllOrders struct {
type MsgSwapExactAmountIn struct {
Sender string
Routes []uint64
Input types.Coin
MinOutput types.Coin
Input types.DecCoin
MinOutput types.DecCoin
}
```
25 changes: 18 additions & 7 deletions x/exchange/spec/06_params.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,21 @@

The amm module contains the following parameters:

| Key | Type | Example |
|---------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Fees | Fees | `{"market_creation_fee":[{"denom":"stake","amount":"1000000"}],"default_maker_fee_rate":"-0.001500000000000000","default_taker_fee_rate":"0.003000000000000000"}` |
| MaxOrderLifespan | int64 (time.Duration) | 168h |
| MaxOrderPriceRatio | sdk.Dec | "0.100000000000000000" |
| MaxSwapRoutesLen | uint32 | 3 |
| MaxNumMMOrders | uint32 | 15 |
| Key | Type | Example |
|--------------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| MarketCreationFee | sdk.Coins | `[{"denom":"ucre","amount":"100000000"}]` |
| Fees | Fees | `{"default_maker_fee_rate":"-0.001500000000000000","default_taker_fee_rate":"0.003000000000000000","default_order_source_fee_ratio":"0.800000000000000000"}` |
| MaxOrderLifespan | int64 (time.Duration) | 168h |
| MaxOrderPriceRatio | sdk.Dec | "0.100000000000000000" |
| MaxSwapRoutesLen | uint32 | 3 |
| MaxNumMMOrders | uint32 | 15 |

## Fees

```go
type Fees struct {
DefaultMakerFeeRate sdk.Dec
DefaultTakerFeeRate sdk.Dec
DefaultOrderSourceFeeRatio sdk.Dec
}
```
4 changes: 4 additions & 0 deletions x/exchange/spec/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,12 @@ parent:
3. [Messages](03_messages.md)
* [MsgCreateMarket](03_messages.md#msgcreatemarket)
* [MsgPlaceLimitOrder](03_messages.md#msgplacelimitorder)
* [MsgPlaceBatchLimitOrder](03_messages.md#msgplacebatchlimitorder)
* [MsgPlaceMMLimitOrder](03_messages.md#msgplacemmlimitorder)
* [MsgPlaceMMBatchLimitOrder](03_messages.md#msgplacemmbatchlimitorder)
* [MsgPlaceMarketOrder](03_messages.md#msgplacemarketorder)
* [MsgCancelOrder](03_messages.md#msgcancelorder)
* [MsgCancelAllOrders](03_messages.md#msgcancelallorders)
* [MsgSwapExactAmountIn](03_messages.md#msgswapexactamountin)
4. [Begin-Block](04_begin_block.md)
5. [Events](05_events.md)
Expand Down
65 changes: 1 addition & 64 deletions x/liquidamm/spec/01_concepts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,67 +2,4 @@

# Concepts

This is the concept for `Liquidfarming` module in Crescent Network.

## LiquidFarming Module

The `liquidfarming` module provides a functionality for farmers to have another option to use with their liquidity pool coins in Crescent Network.

The module allows farmers to farm their pool coin and mint a synthetic version of the pool coin called LFCoin.
Farmers can use the LFCoin to take a full advantage of Crescent functionality, such as Boost.
On behalf of farmers, the module stakes their pool coin to the `lpfarm` module and receives farming rewards for every block.
The module provides auto-compounding of the rewards by going through an auction process, which results in the exchange of the farming rewards coin(s) into the pool coin.

## Registration of Liquidfarm

A `liquidFarm` corresponds to one unique pool id. A `liquidFarm` stakes and unstakes the pool coins as users’ requests. When the rewards are allocated by staking the pool coins, the `liquidFarm` creates and manages an auction in order to exchange the rewards to pool coins to be staked additionally.

A `liquidFarm` can be registered to the parameter `liquidFarms` by governance for activating the liquid farming of a pool.
When the `liquidFarm` is registered to the parameter, users can request to farm their pool coins.

A `liquidFarm` can be removed in the parameter `liquidFarms` by governance for deactivating the liquid farming of a pool.
When the `liquidFarm` is removed, the module unstakes all pool coins in the module, users cannot request to farm their pool coins, but users can still request to unfarm LF coins.
In this case, the ongoing rewards auction becomes finished, all bids are refunded, and a new auction is not started.

## Liquid Farm

Once a user farms their pool coin, the user receives LFCoin instantly minted.
The following formula is used for an exchange rate of `LFCoinMint` when a user farms with `LPCoinFarm`.

$$LF Coin Mint = \frac{LF Coin Supply}{LP Coin Farming Amount} \times LP Coin Farm,$$

where `LFCoinSupply` is not zero.
If `LF Coin Supply` is zero, then the following formula is applied:

$$LF Coin Mint = LP Coin Farm.$$

## Liquid Unfarm

When a user unfarms their LFCoin, the module burns the LFCoin and releases the corresponding amount of pool coin.
The following formula is used for an exchange rate of `LFCoinBurn` to receive `LPCoinUnfarm`:

$$LP Coin Unfarm = \frac{LP Coin Farming Amount - Compounding Rewards}{LF Coin Supply} \times LF Coin Burn,$$

if $$LFCoinBurn < LF Coin Supply$$, where `CompoundingRewards` is the amount of pool coins obtained from the last rewards auction.
If $$LFCoinBurn = LF Coin Supply$$, the following formula is used:

$$LP Coin Unfarm = \frac{LP Coin Farming Amount}{LF Coin Supply} \times LF Coin Burn.$$

If the `liquidfarm` is not registered in the governance parameter, the `LiquidFarming` module unstakes all LP coin, and the following formula is used an exchange rate of `LFCoinBurn`:

$$LP Coin Unfarm = \frac{LP Coin In Module}{LF Coin Supply} \times LF Coin Burn.$$

## Farming Rewards and Auction

On behalf of users, the module stakes their pool coins and claims farming rewards.
In order to exchange the rewards coin(s) into the pool coin to be additionally staked for farming, the module creates an auction to sell the rewards that will be received at the end of the auction period.
Note that the exact amount of the rewards being auctioned is not determined when the auction is created, but will be determined when the auction ends.
The amount of the rewards depends on the total amount of staked pool coins and the `liquidfarming` module’s staked pool coin, which can be varied during the auction period.
Therefore, a bidder to place a bid for the auction should be aware of this uncertainty of the rewards amount.

## Bidding for Auction and Winning Bid

A bidder can place a bid with the pool coin, which is the paying coin of the auction.
A bidder only can place a single bid per auction of a liquid farm.
The bid amount of the pool coin must be higher than the current winning bid amount that is the highest bid amount of the auction at the moment.
The bidder placing the bid with the highest amount of the pool coin becomes the winner of the auction and will takes all the accumulated rewards amount at the end of the auction.
## LiquidAMM
Loading

0 comments on commit 383f79b

Please sign in to comment.