# What is Crescent? Crescent is to provide a connected DeFi functionality for Cosmos Ecosystem to enhance capital efficiency and manage risk effectively. It focuses on the three main functionalities; * Crescent DEX * Crescent Derivatives Crescent Network will commit to, and evolve toward embodiment of the following objectives: * Providing a marketplace for multi-chain assets with capital-efficient liquidity incentivization * Securing a cross-chain collateralization protocol for users to effectively manage risks of their portfolio An array of utilities will be built by the team and perfected by the community through governance, each embracing the core fundamentals of the network. # Crescent DEX The long-term road to a decentralized, active network begins with Crescent DEX, a marketplace that embodies the foundational direction: * Maximization of capital-efficiency through Hybrid AMM/Orderbook methodologies via fair order matching mechanism * An incentive structure designed to optimize capital-efficiency and quality of liquidity * Prioritize security when handling exchanges of bridged assets The structural design of Crescent DEX prevents: * Unnecessary low-latency competition * Front-running and validator extractable value (VEV) * Attack vectors that exploit LP or market makers while encouraging: * Healthy order price competition among traders and orderbook market makers * Participation by market-makers, regardless of scale * Attraction of frequent traders, market makers and arbitrageurs * An optimized trading fee distribution plan for LP, market makers, and CRE holders # Market A market on Crescent DEX is a place where two tokens, known as a trading pair, are exchanged. The base token is the first in the pair and serves as the standard for transactions, while the quote token is the second in the pair and signifies the trade's counter value. Each trading pair on Crescent DEX comes with details regarding the fees involved in trading these tokens. This fee information is not static; it can be adjusted through governance. Every market created on Crescent DEX is exclusive and cannot be duplicated with the same base and quote tokens. However, a new market can be established with the pair's roles reversed, meaning the base and quote tokens are switched. While these two markets perform parallel functions within the exchange, certain differences exist between them. They may showcase distinct prices, conform to varying settlement norms, and adopt unique fee structures if required.

Market and Coin pair

# Pool (Liquidity Pool) Pools act as a cornerstone within the Automated Market Maker (AMM) DEX ecosystem. They furnish the liquidity required for traders to swap tokens seamlessly without the need for direct counterparts. The liquidity contributors—pool investors—form an integral part of this process, reaping rewards from the exchange. Also, on Crescent DEX, pools play a crucial role in aggregating liquidity from users and facilitating token trades based on predefined rules. In the past, there were multiple pools offering liquidity across different price ranges, and users could choose to participate in any of them. However, the current pool system represents a more unified solution that centralizes and manages user-generated positions in a single place. A defining feature of pools is a parameter termed "tick spacing", which specifies the minimum interval between successive orders they place within the order book. The selection of tick spacing value is pivotal as it harmonizes the trade-off between the number of skipped ticks and user convenience. A larger tick spacing omits more ticks, compromising user convenience, while a smaller one heightens user convenience but increases the load on the module. This tick spacing value isn't one-size-fits-all—it may differ according to the specific market and can be adjusted via governance.

Liquidity Pool and Market

# Position In the context of Crescent DEX, a "position" is a user-defined construct established by a liquidity provider intending to contribute tokens within a specific price range. The user, as the architect of this position, maintains complete control and ownership, possessing exclusive rights to inject or withdraw liquidity and to claim accrued rewards. Liquidity providers have the flexibility to own multiple positions and can even set up positions to provide liquidity across the entire range (0 to INF) if desired. These positions serve as the fundamental units for accumulating swap fees and farming rewards. Rewards for different positions vary significantly based on their liquidity contribution, the farming plan of the associated market, and the duration of their contribution. Each position is distinctly tied to its owner and doesn't generate a secondary product like a pool token, which was characteristic of the legacy module. With the absence of pool tokens, users are freed from the obligation of farming (staking) these tokens post-deposit. Instead, as soon as users make a deposit, they are immediately enlisted as liquidity providers and start accumulating rewards.

Positions, Pool and Market

# Order-book and Tick system Crescent DEX differentiates itself from a typical DEX by functioning as an order-book-based exchange, significantly enhancing the user experience in terms of adaptability and transparency. In an order-book-based exchange, a "tick" refers to the minimum price movement that a particular asset can make. Each asset on the exchange is assigned a certain tick size, which is the smallest possible increment that the price can change by. For example, if the tick size for an asset is $0.01, the price can only move up or down in increments of $0.01. The tick size is an important consideration for traders because it can affect the cost and liquidity of their trades. For instance, if the tick size is very small, it can be easier to enter and exit trades at precise price points, which can increase liquidity. On the other hand, if the tick size is too large, it can be difficult to enter and exit trades at specific price levels, and traders may have to accept less favorable prices in order to execute their trades. This doesn't mean that blindly reducing the tick size is a good idea. While infinite computing power could theoretically manage innumerable ticks, it isn't efficient or necessary to accommodate all information within unrequired ticks. Exchange operators can adjust the tick size for different assets based on a variety of factors, including market volatility, trading volume, and the specific needs of traders on their platform. Ultimately, the tick size is a key aspect of the order-book model, helping to ensure that trades can be executed efficiently and accurately while maintaining a market and it can be adjusted by governance.

Orderbook and Tick system

# Hybrid DEX There are many ways to define a hybrid DEX, but in the context of Crescent, hybrid refers to both AMM and traditional order-book trading operating simultaneously in the same market. In a typical DEX, a calculation logic such as CPM(constant product model) determines the amount of tokens that can be received in a swap or the amount of tokens that must be put in to obtain a certain amount of outputs(exact-in, exact-out), and the swap price, which is determined as a ratio of the input and output quantities, appears to increase or decrease continuously. The fact that the swap price is continuous means that as the user's order quantity changes, the rate of exchange actually exchanged changes slightly. This results in the inability to exchange tokens at an identical swap price for two different orders, even if the difference between their input quantities is minuscule. However, the continuous nature of swap prices is incompatible with order-book in traditional finance. In the order book, the execution price does not change no matter how many tokens a trader buys, as long as the liquidity already at the best price allows. Then, when the liquidity at that price is exhausted, the next price will start to fill, and the order will never fill at a price between those prices. This means that the execution price is “discrete”. As mentioned earlier, there are ticks in the order-book, and as a hybrid DEX, Crescent is designing the basic UI and UX in a way that is not off-putting to traditional order-book users, so we want to provide an order-book with an explicit tick system. Therefore, when the amount that a pool can provide is calculated through CPM and applied to the order-book, it is necessary to calibrate the liquidity to the discrete tick system. Instead of making a calibration, it might be better to modify the CPM logic itself or develop a different way of providing pool liquidity. However, given the computational benefits and additional convenience we gain by sticking with CPM, we felt that tweaking the original was a much better direction than going the hard way.

Hybrid DEX

# Batch Matching In the context of MEV(Maximal Extractable Value), there is a significant inequality between professional validator and ordinary users that cannot be resolved. Since validator have the power to determine the order in which transactions are executed and included in a block, they can prioritize transactions that benefit their own financial interests, potentially at the expense of other market participants. Even in traditional finance, many have long been concerned about the inequality between specialized institutions and ordinary individuals, and some have made significant efforts to resolve this issue. Cryptocurrencies, in fact, emerged out of a distrust in these traditional financial institutions. The principle of decentralization, a cornerstone of the crypto ecosystem, can also be viewed as a push against the dominance of large institutions. This is why we handle the matching algorithm in order-book in a batch format(although technically it's a hybrid that allows for sequential matching after the batch to provide additional functionality). We want to prevent professional participants from taking advantage of common users and ensure that everyone has an equal footing in the market. Batch matching essentially eliminates order priority during the matching phase. Consequently, irrespective of the sequence in which one or more orders are sorted, each orderer receives the same matching outcome, rendering MEV attacks essentially impotent.

Concept of Batch matching

# Sequential Matching Most orders are processed in batches, but some orders are processed sequentially for additional features like multi-hop swap. Since sequential matching happens after batch matching, it has no effect on batch matching and will require higher fees than normal, so it should only be used when absolutely necessary. Unlike batch matching, sequential matching makes it easier for users to predict in advance how much they will receive from a swap. This isn't just about increased predictability of transaction outcomes, it also means that it's easier to bundle multiple actions involving swaps and process them all at once. To illustrate, consider a scenario where a liquidity provider possesses only one token and intends to swap a portion of it before providing liquidity within a desired price range. By considering only the state of the pool and their own order, without taking into account other users' orders, it becomes feasible to calculate how their order will impact the pool's price and determine the percentage of each token that should be offered within their desired price range based on the adjusted price. This enhanced modularity of the swap function allows for the composition of multiple actions as a combination of different functions, which can then be processed together within a module. This capability streamlines the execution of multi transactions and contributes to a more efficient and flexible trading experience. It might be difficult to completely prevent MEVs during the sequential match phase, so in the future, we may decide to open up slots to users who want MEVs, charge a large fee, and return the revenue to ecosystem participants.

Concept of sequential matching

# Multi-hop Swap(SlipLess Swap) Multi-hop swap(Slipless swap) is a type of trade that involves multiple token swaps to convert one cryptocurrency into another. It allows users to exchange tokens that do not have a direct trading market on a particular DEX by creating a series of intermediate trades. For example, suppose you want to trade token A for token D on a DEX, but there is no direct trading market between A and D. In that case, you can use a multi-hop swap to make the trade. You would first swap A for B, then swap B for C, and finally, swap C for D. The advantage of multi-hop swap is that they provide greater liquidity and more trading options to users by allowing for trades between tokens that may not have a direct swap route. Multi-hop swaps epitomize how leveraging the modularity of sequential swaps can augment functionality. It's noteworthy that exchanges which solely rely on batch matching can encounter difficulties when managing multi-hop swaps. This is largely due to the complex nature of modularizing token swaps. To illustrate, consider a scenario where an exchange processes a multi-hop swap A→B→C and subsequently receives a request for a multi-hop swap B→C→D. In this situation, attempting to swap B→C is problematic because the batch matching process has already taken place for the B→C swap. Even if it were possible to do the B→C swap again in the second multi-hop swap(B→C→D), it would be at the expense of liquidity compared to the B→C swap from the first multi-hop swap(A→B→C), which does not increase user convenience and creates equity issues.

Multi-hop swap

# Ranged Liquidity Ranged liquidity is concept for liquidity providing which provide liquidity only within a predefined price range of a given token pair. It gives multiple use cases such as: * Markets with similar token pairs with maximized capital efficiency * Leveraged liquidity providing positions within specific price range * One-sided positions which only require one kind of token to be deposited for liquidity providing * More sophisticated liquidity providing methodology for professional market makers # Comparison with Basic position A basic position provides liquidity in all price range, which means that a user can buy or sell a coin in any price. However, the trading amount at a given price by the pool becomes not much large since the liquidity of the pool are spread over all the price.

Basic position

Once the liquidity is concentrated in a specific range of the price, enough liquidity can be provided for trading market in the price range even with the small capital. The following example is a ranged liquidity position with the price range from 0.8 to 1.2. In this regards, the ranged position could be more useful to the pair with stable price, e.g., bCRE/CRE, ETH/ETH, and USDC/USDC pairs.

Ranged position

# Liquidity Amplification Factor A ranged position with price range from 0.8 to 1.2 in the above example provides the liquidity only in the range. Since the ranged pool does not provide the liquidity outside of the range, its liquidity is concentrated in the range. Compared to the basic position with the same capital, the ranged position with \[0.8, 1.2] range provides liquidity 10 times greater than the basic position in the price range. This value of 10 is the liquidity amplification factor of the ranged position. The liquidity amplification factor depends on the price range. As it can be seen below, the liquidity amplification factor increases as the size of the range is getting smaller. | Current Pool Price | Min Price | Max Price | Liquidity Amplification Factor | | ------------------ | --------- | --------- | ------------------------------ | | 1 | 0.8 | 1.2 | 10.38 | | 1 | 0.9 | 1.1 | 20.44 | | 1 | 0.98 | 1.02 | 100.49 | | 1 | 0.99 | 1.01 | 200.49 | | 1.079 | 1.063 | 1.15 | 51.54 | For a ranged pool with Pmin, Pmax and P as the minimum price, maximum price and current pool price, the amplication factor (AMP) can be calculated as $$AMP=\frac{1}{1 - \frac{1}{2}\left(\sqrt{\frac{P\_{min}}{P}} + \sqrt{\frac{P}{P\_{max}}} \right)}$$ Note that $$P\_{min}≤P≤P\_{max}$$ # Possibility of Change to a Single-Coin position A ranged position normally has two kinds of coins in the position as the same as a basic position. This is only applied to the case that the price is in the range of the position. Once the price is out of the range, only a single kind of coin remains in the position. For example, for the ranged position with the range of 0.8 and 1.2, if the price is below 0.8, then the position has only A coins. This means this position sells out B coins and buys A coins at the price above 0.8. On contrary, if the price is above 1.2, then the position has only B coins, which means the position sells A coins and buy B coins at the price below 1.2. In that case of out-of-range, the users can deposit or withdraw to/from the position with only a single kind of coin.

Ranged position's reserve change

# Multiple Positions in the Pool The pool can have multiple liquidity positions with different ranges. The following example illustrates one basic position and one ranged position together providing the liquidity to the market. Thanks to the higher capital efficiency of the ranged position, the traders benefit very low slippage in the price range of the position. In the out-of-range of the ranged position, the liquidity can still be provided by the basic position, which enables trading in the region.

Pools are composed of different positions

# Fee In traditional order book exchanges, such as centralized cryptocurrency exchanges, there are often two types of fees: maker fees and taker fees. These fees are charged to users based on their role in the trading process. The fee structure incentivizes users to act as makers and provide liquidity to the market. By offering lower fees for makers, exchanges encourage users to place limit orders, add depth to the order book and make liquidity providing position. This, in turn, improves market efficiency and reduces slippage for traders. In general, distinguishing between makers and takers is typically straightforward because trades in the order book are executed sequentially. The order book operates in a way that when a trade takes place, it indicates that a newly submitted order has been matched with existing orders already present in the order book. Consequently, we can consider the maker order as one that was already in the order book, while the taker order represents a newly submitted order that resulted in a trade. However, in the case of Crescent DEX, a large number of orders are processed during the batch matching process, which erases the time priority of the orders, making it difficult to simply apply traditional methods. To solve this problem, Crescent determines the maker and taker in the following way: 1. In the batch matching process, maker orders are orders that resist price movement and taker orders are orders that create price movement. In other words, if the price is rising after matching, sell orders become makers and buy orders become takers, and vice versa. 2. In the sequential matching process, the distinction is the same as usual: orders that were already in the order book are maker orders, and newly submitted orders that are matched are taker orders. 3. Orders submitted by liquidity pools are also classified as maker or taker based on the above criteria, but orders in the pool are not charged a fee even if they are classified as taker. (Taker orders in the pool are set to 0% fee rate) # Farming In the context of AMM DEX, farming refers to a process where users provide liquidity to a pool and, in return, receive rewards usually in the form of governance token of the DEX. Although it is the same as swap fee (trading fee) in that it is the profit of the pool investors, farming reward is a basic reward provided by the DEX to attract pool investors, so it is given to users regardless of the actual swap frequency. The amount of rewards that users can earn depends on several factors, including the farming plan of the DEX, the size of the liquidity pool, the duration of the farming period. As previously mentioned, farming rewards in AMM DEXs are typically the governance token of the DEX. However, there are instances where other tokens are added to create synergies with external protocols. In these cases, the external protocol may specify their preferred trading token markets, liquidity providing range, and type of reward token they wish to offer in order to ensure the best possible outcome. In this way, users can benefit from both the farming rewards and the external tokens, making it a worthwhile endeavor for those interested in participating in the AMM DEXs. # Current Farming vs Legacy Farming

Current Farming vs Legacy Farming

Crescent’s farming module is providing farming functionality that provides farming rewards to farmers. Each farmer to the pool having the farming plan(s) can get the farming rewards. One main difference between Farming v1 and Farming v2 is the period of the rewards distribution. * In Farming v1, the farming rewards is distributed at 00:00 UTC everyday to the farmer that has farmed for the entire previous day. In this case, if the farmer changes the position that the farmer provides the liquidity for, the farmer would lose the farming rewards for a day. This makes the farmers hesitate to change the position for liquidity. * In Farming v2, the farming rewards are distributed at every block to the farmers. Thanks to this feature, the farmers can dynamically choose the position for their liquidity to get more rewards. Another main difference is the farming plan for a given pair. * In Farming v1, the farming plan is given to a specific range. Therefore, each range can have separate fixed amount of the rewards regardless of its liquidity. For example, a ranged position with price range of \[0.99, 1.01] has the amplification factor of 200, i.e., the liquidity of the ranged position is 200 times of the basic position with the same TVL. Even in this case, if the farming rewards to the both ranges are the same, then the farmers of the ranged position and the basic position will get the same amount of rewards with the same TVL. This means, there is not so much motivation to provide liquidity to the ranged position. * In Farming v2, the farming plan can be given to a pool, which has multiple positions. For example, bCRE/CRE pool has multiple positions with different ranges. In this case, a farming plan can be given to bCRE/CRE pool, not a specific range. Then, the farming rewards automatically distributed according to the liquidity of each position. With this feature, the farmer providing its liquidity to the ranged position will get more rewards compared to the farmer of basic position with same TVL. # Market Maker Incentives ### Market Maker Market makers provide liquidity to the exchange by placing orders which are not executed immediately. These orders make it easy for traders to trade against provided market maker orders without waiting. ### Inclusion of Market Maker Any Crescent address can apply as a market maker for selected market pairs. A governance process decides inclusion, rejection and exclusion of registered market makers. ### Market Maker Incentives Registered market makers can earn CRE as incentives for providing liquidity. These incentives are calculated for each month by the off-chain market maker scoring system and distribute incentives based on the allocation suggested by governance proposals. ### **Market Maker incentive policy** Because Crescent DEX has the orderbook system, we have a possibility of providing much more capital-efficient liquidity compared to the liquidity provided by the traditional AMM model. The disadvantage of AMM is that it requires too much liquidity to be pooled to provide the same level of effective-liquidity compared to traditional financial markets. In other words, in the case of major tokens that are easy to hedge, if the incentive system for market makers is well designed, they will show capital efficiency comparable to that of the traditional financial market in providing liquidity. Through the incentive policy for market makers, we will incentivize them to bring a more tokens to our DEX, reduce the spread as much as possible, and provide liquidity to both bids and asks evenly. Market makers who maintain stable liquidity within the valid range on the orderbook will get relatively high score. There are two sections for market maker incentive program. First, the module manages the list of registered market makers and distributes incentives via governance process. Second, scoring system for off-chain evaluation of market maker performance. # MarketMaker Apply / Incentive Claim ### Market Maker Eligibility * Any Crescent address can apply as a market maker for selected market pairs. A governance process decides inclusion, rejection and exclusion of registered market makers. * New applicants are requested to submit ApplyMarketMaker message to be included in the uptime evaluation. Those who meet the uptime requirement can be included in eligible market makers through governance. * Market makers who fail to meet the requirements would excluded ### Applying Market Maker * Deposit designated deposit amount multiplied by number of pairs. * Submit ApplyMarketMaker message to be included in the uptime evaluation. * Those who meet the uptime requirement can be included in eligible market maker through governance. Uptime requirement is described in 'MarketMaker Scoring' page. * Governance proposal submit to decide inclusion, rejection, and exclusion of market makers. * Deposit will be refunded after inclusion or rejection. ### Incentives Claim * Only eligible market makers receive CRE incentives. Applicants who will get eligibility next month cannot claim incentive. * Market makers who support multiple pairs receive a combined amount of incentives at a time. * Incentives are claimable after the governance is passed. ## # MarketMaker Scoring ### Methodology * The evaluation objective is to reward market makers who consistently provide tight and deep liquidity for users. * Market makers earn points according to liquidity contribution, which means there is a score cap per block. * The calculation is done off-chain based on on-chain blockchain data. The codebase is publicly available for any third-party verification. ### Market Maker Eligibility * Market maker eligibility is decided by governance every month. * Only registered market makers can earn incentives based on their scores. Market makers who fail to meet the uptime requirements are also given their month incentives. * New applicants are requested to submit ApplyMarketMaker transaction to be included in the uptime evaluation. Those who meet the uptime requirement will be included in eligible market makers through governance. * The governance can exclude existing market makers who fail to meet the requirements for 2 consecutive months or 3 months within the last 5 months. ### Market Maker Orders Requirement * Orders satisfying following conditions can be recognized and evaluated: * Use MMOrder from eligible MMAddress * `Spread`equal or smaller than `MaxSpread` * Min(`AskWidth`,`BidWidth`) equal or larger than `MinWidth` * Min(`AskDepth`,`BidDepth`) equal or larger than `MinDepth` * Parameters (bottom of the document) are assigned differently for each pair depending on the market characteristics, and can be adjusted by governance ### Uptime Requirement * Uptime requirement is measured in 2 stages: * `LiveHour` is added as market maker provide valid orders for an hour. Following 1 out of 2 conditions, it fails: * No valid orders longer than `MaxDowntime` in a row * No valid orders longer than `MaxTotalDowntime` total in an hour * `LiveDay` is added as `LiveHour` is equal or larger than `MinHours` in a day * Those who earn`LiveDay` equal or larger than `MinDays` satisfy the uptime requirement. * Parameters (bottom of the document) are decided and adjusted by governance. ### Formula * Following formula is used to compute how much incentives should be rewarded to each market maker per month. The amount of CRE earned is determined by the relative share of each market maker’s score. 1. First step (within a block) * Calculate 2-sided liquidity point and take minimum value (take integer part) * $$P = min \lbrack{ {AskQ1}\over{AskD1^2} }+ { {AskQ2}\over{AskD2^2} } + ... , { {BidQ1}\over{BidD1^2} }+ { {BidQ2}\over{BidD2^2} } + ... \rbrack$$ 2. Second step (within a block) * Obtain contribution score by taking proportion of the point within the block $$P\_m \over \sum\_i P\_i$$ 3. Third step (within a month) * Calculate `Uptime` by dividing `LiveHour` with total hours in a month U = Total `LiveHour` / Total hours in a month 4. Forth step (Final score) * Final score of market maker ‘m’ is as following : $$S\_m = {U\_m} ^3 \sum ^{B}{t=1} \lbrack { P{mt} \over \sum\_i P\_{it} }\rbrack$$ * $$U\_m$$ : % of Market maker m’s `Uptime` in the month * $$B$$ : Total number of blocks for the month * $$P\_{mt}$$ : Contribution score of market maker ‘m’ at block ‘t’ ### Processing Order data * All variables are used as final values after the trade is made. * Even if the order of n-th tick is partially filled, the tick can still be a reference point(whether the highest bid or lowest ask) of measures when one of the following conditions is met. If not, the following tick becomes the reference point. * Min(`AskQ(n)`,`BidQ(n)`) is equal or larger than `MinOpenRatio` of the original order * Min(`AskQ(n)`,`BidQ(n)`) is equal or larger than `MinOpenDepthRatio` of `MinDepth`

Illustration of Bid/Ask

### Measures * Breadth * `MidPrice` : Average price of lowest ask and highest bid * `Spread` : Price difference between lowest ask and highest bid divide by `MidPrice` * `AskWidth` : Price difference between maximum and minimum ask divided by `MidPrice`. `BidWidth` is same with bid prices * `AskD(n)` : Price difference between `MidPrice` and n-th ask price divided by `MidPrice`. `BidD(n)` is same with bid prices * Depth * `AskQ(n)`,`BidQ(n)` : The amount of token remaining in n-th tick * `AskDepth`,`BidDepth` : Total amount of token remaining in ask or bid side ## Example
* Assume `MaxSpread` 0.012, `MinWidth` 0.002, `MinDepth` 100, `MinOpenRatio` 0.5, `MinOpenDepthRatio` 0.1 * Measure * Block 1
Market Maker AMarket Maker B
MidPrice9.945 = (9.96 + 9.93) / 29.945 = (9.97 + 9.92) / 2
Spread0.00301659.. = (9.96 - 9.93) / 9.9450.00502765.. = (9.97 - 9.92) / 9.945
AskWidth0.00301659.. = (9.99-9.96) / 9.9450.00201106.. = (9.99 - 9.97) / 9.945
BidWidth0.00301659.. = (9.93-9.90) / 9.9450.00201106.. = (9.92 - 9.90) / 9.945
AskD(1)0.00150829.. = (9.96-9.945) / 9.9450.00251382.. = (9.97 - 9.945) / 9.945
AskD(2)0.00251382.. = (9.97-9.945) / 9.9450.00351935.. = (9.98 - 9.945) / 9.945
AskD(3)0.00351935.. = (9.98-9.945) / 9.9450.00452488.. = (9.99 - 9.945) / 9.945
AskD(4)0.00452488.. = (9.99-9.945) / 9.945-
BidD(1)0.00150829.. = (9.945-9.93) / 9.9450.00251382.. = (9.945 - 9.92) / 9.945
BidD(2)0.00251382.. = (9.945-9.92) / 9.9450.00351935.. = (9.945 - 9.91) / 9.945
BidD(3)0.00351935.. = (9.945-9.91) / 9.9450.00452488.. = (9.945 - 9.90) / 9.945
BidD(4)0.00452488.. = (9.945-9.90) / 9.945-
AskDepth200225
BidDepth160240
AskQ(1)5075
AskQ(2)5075
AskQ(3)5075
AskQ(4)50-
BidQ(1)4080
BidQ(2)4080
BidQ(3)4080
BidQ(4)40-
* Block 2
Market Maker AMarket Maker B
MidPrice9.935 = (9.96 + 9.91) / 29.945 = (9.97 + 9.92) / 2
Spread0.00503271.. = (9.96 - 9.91) / 9.9350.00502765.. = (9.97 - 9.92) / 9.945
AskWidth0.00301962.. = (9.99-9.96) / 9.9350.00201106.. = (9.99 - 9.97) / 9.945
BidWidth0.00100654.. = (9.91-9.90) / 9.9350.00201106.. = (9.92 - 9.90) / 9.945
AskD(1)0.00251635.. = (9.96-9.935) / 9.9350.00251382.. = (9.97 - 9.945) / 9.945
AskD(2)0.00352289.. = (9.97-9.935) / 9.9350.00351935.. = (9.98 - 9.945) / 9.945
AskD(3)0.00452944.. = (9.98-9.935) / 9.9350.00452488.. = (9.99 - 9.945) / 9.945
AskD(4)0.00553598.. = (9.99-9.935) / 9.935-
BidD(1)0.00050327.. = (9.935-9.93) / 9.9350.00251382.. = (9.945 - 9.92) / 9.945
BidD(2)0.00150981.. = (9.935-9.92) / 9.9350.00351935.. = (9.945 - 9.91) / 9.945
BidD(3)0.00251635.. = (9.935-9.91) / 9.9350.00452488.. = (9.945 - 9.90) / 9.945
BidD(4)0.00352289.. = (9.935-9.90) / 9.935-
AskDepth190225
BidDepth80180
AskQ(1)4075
AskQ(2)5075
AskQ(3)5075
AskQ(4)50-
BidQ(1)020
BidQ(2)580
BidQ(3)4080
BidQ(4)40-
* In case of market maker A, the highest bid has moved from 9.93 to 9.91 at block 2. `BidQ(2)` does not meet the either conditions of `MinOpenRatio` of original order amount (5/40 < 0.5) nor `MinOpenDepthRatio` ( 100(`MinDepth`) \* 0.1 = 10 ). * For market maker B’s case, reference point haven’t changed. `BidQ(1)` could not meet the `MinOpenRatio` (20/80 < 50)condition, but larger than `MinOpenDepthRatio`. * Liquidity Point * Block 1 * Both market maker A and B meet the condition * `Spread(A)`, `Spread(B)` < `MaxSpread` (0.012) * `AskWidth(A)`, `BidWidth(A)`, `AskWidth(B)`, `BidWidth(B)` > `MinWidth` (0.002) * `AskDepth(A)`, `BidDepth(A)`, `AskDepth(B)`, `BidDepth(B)` > `MinDepth` (100) * Each point on Block 1 is as follows, $$P\_{A1} = min \lbrack{ {50}\over{0.0015..^2} }+ {{50}\over{0.0025..^2} } + {{50}\over{0.0035..^2} }+ {{50}\over{0.0045..^2} }, {{40}\over{0.0015..^2} }+ {{40}\over{0.0025..^2} } + {{40}\over{0.0035..^2}}+ {{40}\over{0.0035..^2} }\rbrack$$ $$P\_{A1} = min \lbrack36369600, 29095680\rbrack = 29,095,680$$\ $$P\_{B1} = min \lbrack{ {75}\over{0.0025..^2} }+ {{75}\over{0.0035..^2} } + {{75}\over{0.0045..^2} }, {{80}\over{0.0025..^2} }+ {{80}\over{0.0035..^2} } + {{80}\over{0.0045..^2}}\rbrack$$\ $$P\_{B1} = min \lbrack 21586725, 23025840\rbrack = 21,586,725$$ * Block 2 * Only Market maker B meet the condition, * `Spread(A)`, `Spread(B)` < `MaxSpread` (0.012) * `AskWidth(A)`, `AskWidth(B)`, `BidWidth(B)` > `MinWidth` (0.002) * `BidWidth(A) < MinWidth` * `AskDepth(A)`, `AskDepth(B)`, `BidDepth(B)` > `MinDepth` (100) * `BidDepth(A) < MinDepth` $$P\_{A2} = min \lbrack 14414430,0\rbrack = 0$$\ $$P\_{B2} = min \lbrack{ {75}\over{0.0025..^2} }+ {{75}\over{0.0035..^2} } + {{75}\over{0.0045..^2} }, {{20}\over{0.0025..^2} }+ {{80}\over{0.0035..^2} } + {{80}\over{0.0045..^2}}\rbrack$$\ $$P\_{B2} = min \lbrack 21586725, 13531150\rbrack = 13,531,150$$ * Contribution Score * Block 1\ $$C\_{A1} = \frac{29095680}{29095680+21586725} = 0.574078..$$\ $$C\_{B1} = \frac{21586725}{29095680+21586725} = 0.425921..$$ * Block 2\ $$C\_{A2} = 0$$\ $$C\_{B2} = 1$$ * Final Score * Sum up all of the contribution scores for the month and product cube of uptime * Market maker A : (Assuming uptime 70%) $$S\_A = (0.7)^3 \*(0.5740.. + 0 +...)$$ * Market maker B : (Assuming uptime 90%) : $$S\_B = (0.9)^3 \*( 0.4259..+1+...)$$ ### Parameters Scoring module contains following parameters : #### Common Parameters
KeyDefinitionExample
MinOpenRatioMinimum ratio to maintain the tick order0.5
MinOpenDepthRatioMinimum ratio of open amount to MinDepth0.1
MaxDowntimeMaximum allowable consecutive blocks of outage20 (blocks)
MaxTotalDowntimeMaximum allowable sum of blocks in an hour100 (blocks)
MinHoursMinimum value of LiveHour to achieve LiveDay16
MinDaysMinimum value of LiveDay to maintain MM eligibility22
#### Parameters for each pair
KeyDefinitionExample
PairIdPair id of liquidity module20
UpdateTimeTime the pair variables start to be applied to the scoring system2022-12-01T00:00:00Z
IncentiveWeightIncentive weights for each pair0.1
MaxSpreadMaximum allowable spread between bid and ask0.006 (ETH-USDC pair), 0.012 (ATOM-USDC pair)
MinWidthMinimum allowable price difference of high and low on both side of orders0.001 (ETH-USDC pair), 0.002 (ATOM-USDC pair)
MinDepthMinimum allowable order depth on each side600000000000000000 (ETH-USDC pair), 100000000 (ATOM-USDC pair)
# Liquid Staking Description of Liquid Staking in Crescent Crescent DEX will help you utilize staked native token. The key is that native token stakers will be able to optimize their financial positions using interesting features of Crescent DeFi while maintaining their voting power. # Staking vs. Liquid Staking ### **Staking vs. Liquid Staking** As the same as the concept of the existing staking of dPoS blockchain, holders of the native staking token of the chain, which is `CRE` in Crescent Network can become validators and can delegate tokens to validators, ultimately determining the effective validator set for the system. This is the staking. Once the tokens of a user are delegated via staking, those are locked and the user cannot swap/transfer/deposit the staked tokens. This means, the user's staked token is not liquidable anymore for a while. For the users to also enjoy many utilities (swap/transfer/deposit) with their assets while staking, Crescent Network introduces the concept of `liquid staking`. Once a user stakes `CRE` through liquid staking module, the staked `CRE` is locked but the user receive `bCRE` (pegged staked representative tokens) instead. ![Staking vs. Liquid Staking](/files/BwJYdQjwjQoodlsYv15l) When the delegators want to unstake `bCRE`, the module will burn the `bCRE` and give them `CRE` back, which will be larger amount of `CRE` thanks to the liquid staking rewards during delegation period. Liquid staking solves the problem of assets remaining dormant by expanding secondary investment opportunities while still giving the user the same power of voting and delegation. This minimizes opportunity cost of traditional staking, which negates an unnecessarily high staking reward rate to pursue more capital-efficient CRE inflation usage for the whole ecosystem: * Liquid staking results in diversified delegations to liquid staking validators with predefined power weights * Liquid staking validator group is managed by community governance process # Overview of Staking Rewards ### How is the staking rewards received? Once you liquid-stake your `CRE`, you will get `bCRE` according to the mint rate. During liquid staking period, the staking rewards are added to the liquid staking module. When you liquid-unstake your `bCRE` after some time, you will get `CRE` which will be larger amount than what you originally liquid staked. ![Illustration of staking rewards](/files/j3lAyeK4FPZ9YsyAcJ7n) As illustrated above, with the assumption that you liquid-stake `X CREs`, after some duration, you will get `X+Y CREs`. ![Staking rewards and Staking APR](/files/4TC6kIGFwGssPq2sQQJO) During 1 year, your rewards is as much as `Staking APR` (annual percentage rate) with the following relation. $$ Staking APR = \frac{Y}{X} ;(%) $$ # Calculations for Staking Rewards ### **Mint rate** Mint rate is the exchange ratio between CRE and bCRE. Therefore, it is defined as the ratio between the total amount of bCRE currently issued and the total amount of CRE tied by the liquid staking module, i.e, temporarily vested to the proxy account. $$ Mint\space rate\space =\space \frac{bCRE\space total\space supply}{net\space CRE\space amount\space in\space proxy\space account} $$ ### **Calculation of Mint Amount of bCRE** The tokens liquid staked by users are first collected in a liquid staking proxy account and then distributed to each liquid validator according to their weight. The liquid staking users will receive bCRE in exchange for CRE staking, at this time, the amount of newly issued bCRE is determined according to the internally calculated mint rate. $$ Mint\space amount\space of \space bCRE\space = Liquid\space Staking\space amount\space of\space CRE\space \times \space Mint\space rate $$ ### **Calculation of Liquid Unstaked CRE** The bCRE holders can unstake their bCRE in order to receive CRE. Inside the module, since the subject of delegation to validators is the proxy account, after burning the bCRE, the corresponding amount of CRE is unbonded by the proxy account. At this time, by changing the termination address of unbonding delegation to the address of user who unstaked bCRE, the CRE will be finally sent to the addresses of users. The unstaking process requires a certain period of time, which is currently set to 14 days. $$ Receiving\space amount\space of\space CRE\space =\space \frac{Liquid\space Unstaking\space amount\space of\space bCRE}{Mint\space rate}\times (1-fee\space rate) $$ ### **Rebalancing (Auto-redelegation)** Due to the events like slashing or tombstoning, the actual current weights of the CRE of the liquid validators can be slightly different from what was target weight intended. Therefore, rebalancing of delegated assets is needed. At the beginning of every block, the module calculate the actual weight(CRE amount of the validator relative to the total amount) of liquid validators and the difference between it and originally intended weight. If the maximum difference exceeds criteria called rebalancing trigger, the rebalancing will be executed. # Liquid Staking Validator ### **Liquid Staking Validator** Crescent Network’s liquid staking utility consists of whitelisted validators that receive delegation directly from the liquid staking module. When a user stakes their CRE, the delegated amount is distributed equally among the set of whitelisted validators that can be changed by governance, led by the Crescent Foundation. Validator addition conditions: * Maximum of 1 validator added each month to existing group when no performance issues exist on the network * The validator’s performance and potential contribution to Crescent Network must be provided and addition must be agreed on by governance Grounds of expulsion from group: * Potential significant network performance drag caused by the validator * Commission rate set differently than the commission rate decided by signal governance * Statistical evidence of VEV(validator extractable value) The Crescent Foundation can monitor the statistical differences between mempools in multiple full-nodes and the transactions in each proposed block to prevent VEV. When there exists very strong statistical evidence that a significant number of blocks are proposed by a certain validator, the below punishment on the validator can be executed via governance process: * Expulsion of the validator from the liquid staking validator group * Slash proportion of delegations towards the validator * Tombstone the validator # Snowball (Liquid AMM) Description of Liquid AMM in Crescent Snowball (Liquid AMM), as made possible by Crescent, involves tokenizing liquidity-providing positions and utilizing them for various purposes. These tokens can be used as collateral for loans, traded in a marketplace against other tokens, or utilized in other innovative ways. In a typical DEX, liquidity providers are required to lock their tokens on the platform to earn swap fees and incentives. These tokens are managed by the platform for potential swap trades, which exposes them to price movements and impermanent loss. In this context, impermanent loss is a quantifiable value that can be calculated based on the token prices and occurs when there is a change in the relative price of the two tokens. This means that the value of a liquidity providing position can be calculated using only the token prices as input, so there is no problem with tokenizing the position itself. This is because being able to fairly value those tokens is the most important thing to enable tokenization. One important consideration when tokenizing a liquidity-providing position is how to handle the swap fees and incentives accumulated on that position. Crescent simplifies this process for users by reinvesting those rewards through an auction mechanism. Snowball token(sb-token) holders do not need to manually claim and reinvest their rewards back into the position. This approach ensures that sb-tokens, regardless of their origin or location, can eventually be valued equally, making them fungible and enabling free tokenization.

Liquid AMM (Snowball) vs Private position

# Mint & Burn sb-Token To mint sb tokens, users need to deposit both assets that make up the liquidity-providing position, and this should be done in a required ratio determined by the module. The underlying position of the sb token is functionally and structurally similar to a private position that users can individually create, with the only difference being tokenization. As such, the position also has a price range and the range is determined by the platform based on necessity or user requirements, not by individual users’ choices. The ratio of the two tokens required to mint sb tokens is determined based on the current price and the desired range. When a user deposits the correct ratio of the two tokens, the module calculates the number of newly minted sb tokens using the existing supply of sb tokens, the total liquidity in the current position, and the liquidity being deposited. Now, let's talk about burning sb tokens. This process allows you to get back the original two native tokens. To initiate a burn, the user submits the sb tokens they want to burn. The module then calculates the liquidity value corresponding to the number of tokens being burned. This calculation considers the circulating sb tokens, the quantity of sb tokens being burned, and the total liquidity of the current position. Based on the liquidity value, the AMM module calculates the actual amount of both tokens to be withdrawn and sends them to the user's address. However, in the case of a burn, the user's contribution is not recognized for the liquidity associated with the rewards reinvested through the previous auction. This measure is in place to prevent abuse through repeated minting and burning. In practice, sb tokens offer various incentives for long-term holding, minimizing the impact on profits due to the exclusion of these reinvested rewards. **Calculate minting amount** $$sbToken Mint = sbToken Supply\times\frac{added\space Liquidity}{Total\space Liquidity\space of\space the\space position}$$ where sbTokenSupply is not zero. If sbTokenSupply is zero, then the following formula is applied: $$sbTokenMint = added\space Liquidity$$ Here, the added Liquidity can be calculated from deposit amount of two tokens and information about price range of the underlying position. $$L=\min(\frac{\sqrt{P\_{cur}}\sqrt{P\_{max}}}{\sqrt{P\_{max}}-\sqrt{P\_{cur}}}\times amount\_{0}, \frac{amount\_{1}}{\sqrt{P\_{cur}}-\sqrt{P\_{min}}})$$ where amount0 is input base token amount and amount1 is input quote token amount **Calculate token amounts from sb token burning** $$amount\_{0}=removed\space Liquidity\times\frac{\sqrt{P\_{max}}-\sqrt{P\_{cur}}}{\sqrt{P\_{cur}}\sqrt{P\_{max}}}$$ $$amount\_{1}=removed\space Liquidity\times\ ({\sqrt{P\_{cur}}-\sqrt{P\_{min}}})$$ Here, removed Liquidity can be calculated from buring sb token amount. $$L = Total\space Liquidity\times \frac{burned\space sbToken\space amount}{sb Token Supply+prevWinningBidAmount}$$ where prevWinningBidAmount is the amount of sb tokens obtained from the last rewards auction. # Reward Auction As previously mentioned, Crescent employs a reward auction to tokenize liquid farming positions. The fee revenue generated from the underlying position consists of the two tokens used for trading by default. However, the farming reward provided as an incentive for the position can be in the form of CRE or an additional token from an external protocol. While the module could directly swap these tokens into trading tokens and reinvest them, such a process could result in losses due to imperfections of automated swap logic and create vulnerabilities to potential MEV attacks. These attacks could disrupt the intended swap plan and reduce the profits of sb token holders. To mitigate these risks, it is preferable to competitively dispose of the reward tokens in the market at a minimal discount. By allowing only the sb token itself as the quote token for the auction, we eliminate the need for additional reinvestment process. Instead of sending the accumulated rewards to the auction winner, the module receives a certain amount of sb tokens. These sb tokens that enter the module through the auction are immediately burned. Unlike a normal burn where the user withdraws the original two tokens while burning the sb token, in this case, only the sb token itself is burned. The module does not send any tokens elsewhere in response. To clarify, participants in the auction are required to deposit two trading tokens in order to mint sb tokens for bidding. After the auction concludes, the winning bidder is determined, and the sb tokens they bid on are burned, effectively removing those sb tokens from circulation. As a result, the auction reward is automatically reinvested from the perspective of existing sb holders. # How to Participate The following is the example of the process of auction bidding. 1. **Find the current auction id and the auction end time** * In every auction period, a new auction is started and auction id increases. * This can be queried with liquid farm id and auction status as `AuctionStatusStarted`. 2. **Find the accumulated rewards of the liquidfarm** * This can be queried from the module, and the module returns the amount of rewards accumulated from the last successful auction to the current time. * This value keeps increasing to the end of auction. The rewards value at the end of the auction will be the rewards that the winning bidder will be received. * Make sure that bidders cannot guarantee the exact amount of rewards when bidding. The exact value of rewards for the auction is determined at the end of the auction. 3. **Find the highest bidding amount for the auction** * This can be queried from the module with liquid amm id. 4. **Decide the bidding amount as sb tokens** * A bidder needs to have sb tokens for bidding. That is, the bidding coin is sb token. * The bidding amount needs to decided by considering the value of sb token and rewards to be received. * The bidding amount should be higher than the current highest bidding amount. 5. **Place a bid with sb tokens** * A bidder broadcasts a transaction having message for placing a bid. Then, the bidding amount is sent to the module. * If a give bidder places another bid for the same auction, then the old bid is automatically refunded. Each bidder can have only one single valid bid for the auction. 6. **Check the bid lists of the auction** * Check the bids of the auction to see the status of the bidding. 7. **Check the auction result** * After the auction ends, the winner, the winning bid amount, and the rewards (including fee) can be known. The users who wants to participate in the auction needs to use CLI or gRPC commands. No frontend is provided for auctions. # Gas and Fees ### Gas Fee Gas is a unit of computational cost for processing a transaction. This has two main purposes in that it enables to make sure transactions not consuming too much computational resources and to prevent unnecessary spamming from the users. `Gas fee` is calculated by $$ Gas Fee = Gas Amount \times Gas Price. $$ The minimum amount of `Gas Amount` is determined according to the transaction. There are the recommendations of Gas Amount for the kinds of transactions. For example, for a transaction of deposit and claim, the recommended gas is `200,000`while `3,000,000` is recommended for liquid staking. Any transaction that does not meet both the minimum `Gas Amount` and the minimum `Gas Fee` will not be processed. The minimum `Gas Fee` in Crescent Network is set by each validator, where only transactions including more than the minimum `Gas Fee` will be included in a block proposed by the validator. ### Swap Fee Swap fees for takers and makers vary by market. These values can be changed through governance proposal. ### Pair/Pool Creation Fee No position creation fees. Users can move from position to position as they want. # Liquid Governance As you can see in the liquid staking section, our governance token (CRE) will be liquidated as soon as users stake it via liquid staking module and can be used for other utilities. Unlike other services that promote similar functions, we designed a module that minted token (bCRE) can fully exercise its voting power. ### **Liquidity Providers** We believe that bCRE holders will strive to manage their assets more efficiently, such as by providing liquidity to pools containing bCRE, rather than holding bCRE as-is in their wallets. Therefore, the issue of maintaining the voting power of bCRE-included LP investors is the most important issue to be dealt with in implementing the liquid staking function of the governance token. ### **Voting Power** Like closing of the shareholder registry and conforming voting rights in traditional stock market, when a specific governance proposal is submitted and voting is required, the voting power of all users with bCRE is calculated based on a specific point in time, and the users exercise their voting rights in the same way as general dPoS-type blockchains. At this time, the bCRE holding amount is converted to the CRE holding amount using the mint rate at that time, so there is no problem in calculating the voting power with users participating in the network through normal staking rather than liquid staking. $$ Voting\space power\space of\space user\space =\space staked\space CRE(normal\space staking)\space +\space \frac{bCRE}{Mint\space rate} $$ The method of calculating the voting power of users based on a specific time which is similar to a snapshot is especially important in estimating the voting power of bCRE-included LP investors. Because, as you know, the quantity of tokens in the LP position changes in real time depending on the price of the corresponding tokens. Furthermore, once Crescent Boost is activated, it is possible to leverage the LP position (so-called leverage farming). At this time, voting power for leveraged bCRE-included LP positions will also be recognized as fully vested in the investor. That means we respect those who taking the short-term risk in order to vote on a governance proposal by leveraging a bCRE position, or borrowing bCRE from others. # Partnership
Crescent Network uses TradingView's charting technology. TradingView stands as a global platform featuring valuable market insights, heatmaps and tools to [track Bitcoin price](https://www.tradingview.com/symbols/BTCUSD/). # Crescent Derivatives More detailed information about Crescent Derivatives will be announced soon. # Crescent DEX (legacy) The subdocuments in this document are from before the Crescent V5 update. For current information, please see the Crescent DEX page. # Coin Pair In Crescent DEX, anyone can create a pair of two coins, which is an ordered pair. The ordered coin pair is unique in Crescent DEX, which means only a single pair of a given ordered coin pair is allowed. For example, Crescent DEX can have only one pair for `A-B` coin pair consisting of `Coin A` and `Coin B`. Crescent DEX can also have `B-A` coin pair, which is different from `A-B` coin pair. The base coin is the first coin that appears in a coin pair quotation. Consequently, the second coin appeared in the pair is a quote coin. ![Base coin and quote coin of an ordered coin pair](/files/K6rLXfUYDTInGynpkYtA) Example > In the pool of `bCRE-CRE`, the base coin is `bCRE` while the quote coin is `CRE`. The pool price `1.133` means, the base coin `1 bCRE` is traded against the quote coin `CRE` and exchanged for `1.133 CRE`. # Liquidity Pool For a coin pair, a liquidity pool can be created by anyone in Crescent DEX, where the liquidity pool is to reserve the amount of two different coins of the coin pair. ![Liquidity pool (LP) for a coin pair and LP providers](/files/sy8TsKY04kzGzs8MDDv6) Users can deposit a pair of coins into the pool so that those users become liquidity providers. A liquidity provider can be anyone who provides liquidity by depositing reserve coins into the pool. In Crescent DEX, a liquidity pool takes a role of automated market maker (AMM) by utilizing CPM (Constant Product Model) to calculate available liquidity. The pool price is defined as the ratio of the number of the quote coins and the number of the base coins in the pool. For the coin pair `A-B`, the pool price is the number of coin `B` divided by the number of coin `A` in the pool. Crescent DEX will support multiple liquidity pools for a given coin pair with introducing later ranged pools. # Legacy Farming Rewards (LP Incentives) This farming rewards was used before Crescent V3. Crescent Network provides liquidity incentives to two different liquidity providers: liquidity pool (LP) investors and market makers on orderbook. In this section, how the incentive for LP providers will be received. Crescent DEX provides incentives to liquidity pool (LP) investors via farming. We target to design the incentive plan to break away from the bleeding competition prevalent in the DeFi market and create a capital-efficient and sustainable ecosystem. In the initial stage, LP incentives are provided to stabilize the market and diversify investment options for CRE holders. ### Farming Status Change: FarmQueued and FarmStaked A user having a pair of two coins can deposit those coins to a pool, which is a kind of providing liquidity to the pool. * When the user deposit the pair of two coins, the user will get the corresponding pool tokens. * When the user farms the pool tokens, then the pool token goes into the status of `FarmQueued`. * After 24 hours are passed, the pool token in `FarmQueued` automatically goes into the status of `FarmStaked`. * For the pool token in `FarmStaked` during the entire epoch time, the corresponding farming rewards will be dropped. * When the user unfarms the pool token of `FarmQueued` and `FarmStaked`, the pool token is instantly given to the user. * When the user withdraws the pool token, then the user gets the calculated amounts of coins. ![How coins and pool token status could changed](/files/GKhA5xp0Pb5iK8Qfk9PJ) ### Annual Percentage Rate (APR) of LP Incentives The APR displayed in the UI is the expected APR, which means how much rewards the user will receive if the user starts to farm now. The detailed equation is as below. ![Calculation of expected A](/files/okb6YK0KZHG7hIFNqKrJ) ### **How to get the farming rewards (LP incentive)** When a user deposits a pair of two tokens into a pool, they receive a certain amount of pool tokens based on the amount of deposits. Once the user triggers to farm some amount of the above pool tokens, the farming clock is getting started and the request stays in the queue for 24 hours. After 24 hours, the farm requests of all users in the queue are automatically staked at once. It changes the state of requests and the actual farming begins. ![Example of farming timeline](/files/mvfp2S8PV26nDCp8zy7b) **Day 1: A user deposits a pair of tokens into a pool, and begins liquidity farming** * The user’s pool tokens for their contribution is now QUEUED for farming, farming to be activated after 24 hours. **Day 2: The user’s contribution to the pool is now farming rewards based on the APR(Annual percentage rate)** * A full 24 hour period (Day 2 00:00 UTC \~ Day 3 00:00 UTC) as FarmQueued and FarmStaked has to pass in order to receive rewards **Day 3: The user’s contribution has now yielded rewards(CRE), which can be claimed** * The confirmed rewards can be claimed at Farm>Manage>Claim **Day 4: The user then decides to unfarm the whole contribution on this day** * Upon unfarming the full amount, unclaimed confirmed rewards are given, but rewards for Day 4 is not included because Day 4 hasn’t fully passed yet When a user requests to claim the rewards or unfarms whole staked pool tokens, the rewards accumulated until then are instantly received to the user. ### Now, what happens when a user adds liquidity to an already farming pool? ![Case of additional farming](/files/Kb85KlIslvO1kV0YeYu6) **Day 2: Seeing yielded rewards, the user decides to add liquidity to their already farming position** * The newly added amount is now in queue for farming, while the initial amount remains farming rewards ### What if you partially unfarmed during a farming epoch? ![Case of partially unfarming](/files/fbgHcky2Hn3DM1tEAqnv) In this example, the user unfarms 50% of the user's farming amount. Then, only the mount of farming will be eligible for rewards during the epoch, claimable at the end of the epoch. # New Farming Rewards (LP Incentives) This farming rewards is being used since Crescent V3. ### Farming V2 * The actual name of this module is `lpfarm`, but for the easier reading, we call it as `Farming V2`in this document.

Comparison of Farming V1 and V2

Crescent’s farming module is providing farming functionality that keeps track of staking and provides farming rewards to farmers. Each farmer to the pool having the farming plan(s) can get the farming rewards. One main difference between `Farming v1` and `Farming v2` is the period of the rewards distribution. * In `Farming v1`, the farming rewards is distributed at 00:00 UTC everyday to the farmer that has farmed for the entire previous day. In this case, if the farmer changes the pool that the farmer provides the liquidity for, the farmer would lose the farming rewards for a day. This makes the farmers hesitate to change the pool for liquidity. * In `Farming v2`, the farming rewards are distributed at every block to the farmers. Thanks to this feature, the farmers can dynamically choose the pool for their liquidity to get more rewards. Another main difference is the farming plan for a given pair. * In `Farming v1`, the farming plan is given to a pool. Therefore, each pool can have separate fixed amount of the rewards regardless of its effective liquidity. For example, a ranged pool with price range of \[0.99, 1.01] has the amplification factor of 200, i.e., the effective liquidity of the ranged pool is 200 times of the basic pool with the same TVL. Even in this case, if the farming rewards to the pools are the same, then the farmers of the ranged pool and the basic pool will get the same amount of rewards with the same liquidity. This means, there is not so much motivation to provide liquidity to the ranged pool. * In `Farming v2`, the farming plan can be given to a pair, which has multiple pools. For example, `bCRE/CRE` pair has multiple pools including a basic pool and ranged pools with different ranges. In this case, a farming plan can be given to `bCRE/CRE` pair, not a specific pool. Then, the farming rewards automatically distributed according to the EFFECTIVE liquidity of each pool, where the `effective liquidity` means the actual TVL multiplied by the amplification factor of the ranged pool. This means, the `effective liquidity` indicates how much liquidity at a tick of the orderbook is provided by the pool. With this feature, the farmer providing its liquidity to the ranged pool will get more rewards. This results in less slippage from token swap at Crescent orderbook. * p-th pool of a given pair having `TotalReward` get the rewards for the farmers of the pool as * $$Reward\_{p}=\left(\frac{AMP\_p \times TVL\_p}{\sum\_{k=1}^{K} AMP\_k \times TVL\_k} \right)\cdot TotalReward$$ * i-th farmer of the p-th pool will get the rewards as * $$Reward\_p(i) = \frac{\text{farming amount of i-th farmer}}{FarmingAmount\_p} \cdot Reward\_p$$, where $$FarmingAmount\_p$$ is the total farming amount of `Liquid Farming` module to the p-th pool. # Orderbook and Tick System ## Orderbook Crescent Network introduce the concept of an orderbook for versatility and visibility. For a coin pair, a single orderbook is given. The users can submit both limit and market orders and transparently observe existing limit orders on orderbooks. ![](/files/aQYD21gimmTw49DIVzRA) ## Tick System Crescent Network introduces tick system alongside with enabling order book feature. Tick system allows better data and calculation efficiency, and also orderbook standardization for users who are familiar with traditional orderbook system. The size of tick can be adjusted by a governance proposal. ## Relationship between Liquidity Pool and **Orderbook** Recent enhancements in blockchain technology have allowed developers to build scalable, automated utilities upon trustless infrastructure. One utility class that has evolved significantly is Automated Market Makers (AMM). In Crescent Network, a liquidity pool becomes AMM so that it allow investors without significant capital or financial knowledge to invest in market-making opportunities. The liquidity pool of a coin pair automatically makes orders in the orderbook of the coin pair by CPM (Constant Product Model). ![Relationship between a liquidity pool and orderbook](/files/VlR6vOr6sCLeTN2XeeaE) As illustrated above, LP provides who deposit two different types of coins into the pool while the liquidity in the pool is automatically converted to the orders to be submitted to the orderbook. # Hybrid DEX ## Hybrid DEX In Crescent DEX, each liquidity pool act just like another market participant on orderbook. It calculates groups of limit orders for each tick in the orderbook with order amount derived from CPM. Then, all integrated orders on orderbook including liquidity pools’ are matched each other at once. ![Concept of Hybrid DEX in Crescent Network](/files/iFqZkCq8oZHCcoALJB25) As illustrated above, AMM provided by the liquidity pool and traditional market makers coexist in Crescent DEX. That is so called hybrid DEX. This kind of hybrid DEX outperforms in perspective of capital efficiency so that traders (users of Crescent DEX) can enjoy the effectively abundant liquidity on the orderbook. ## Multiple Pools Note that because liquidity pools act like additional participants, multiple liquidity pools with same token pair with different configurations can participate on the orderbook at the same time under the fair matching system of the orderbook. This will be implemented in Crescent Network V2. ![Multiple pools for a given coin pair](/files/PAYo67FaefSOZUWU9VWz) # Batch Execution In traditional exchanges or newer AMM DEXs, prioritization of orders by sub-second latency creates huge problems around fairness of the marketplace. Especially in decentralized setup, MEV(Miner Extractable Value) is a huge cost to every ordinary traders in DEXs. In Crescent DEX, we minimize such value extraction by adopting batch execution for orderbook order matching mechanism. In batch execution, orders within a batch are treated equally without prioritization by order time. The only prioritization is the order price, not the order time. It brings healthy competition among arbitrageurs and traders which result in more efficient price discovery of the orderbook. # Ranged Pools Ranged pools are customized pools which provide liquidity only within a predefined price range of a given token pair. It gives multiple use cases such as: * Pools with similar token pairs with maximized capital efficiency * Leveraged pools within specific price range * One-sided pools which only require one kind of token to be deposited for liquidity providing * More sophisticated liquidity providing methodology for professional market makers ### Comparison with Basic Pool A basic pool provides liquidity in all price range, which means that a user can buy or sell a coin in any price. However, the trading amount at a given price by the pool becomes not much large since the liquidity of the pool are spread over all the price. ![Basic liquidity pool](/files/8xN8lL6g2ST5XzcjwlL6) Once the liquidity is concentrated in a specific range of the price, enough liquidity can be provided for trading market in the price range even with the small capital. The following example is a ranged liquidity pool with the price range from 0.8 to 1.2. In this regards, the ranged pool could be more useful to the pair with stable price, e.g., bCRE/CRE, ETH/ETH, and USDC/USDC pairs. ![Ranged liquidity pool to enjoy higher capital efficiency](/files/h9fcaPownIthjWLDiX22) ### Liquidity Amplification Factor of Ranged Pool Depending on Price Range A ranged pool with price range from 0.8 to 1.2 in the above example provides the liquidity only in the range. Since the ranged pool does not provide the liquidity outside of the range, its liquidity is concentrated in the range. Compared to the basic pool with the same capital, the ranged pool with \[0.8, 1.2] range provides 10 times liquidity than the basic pool in the price range. This value of 10 is the liquidity amplification factor of the ranged pool. The liquidity amplification factor depends on the price range. As it can be seen below, the liquidity amplification factor increases as the size of the range is getting smaller.
Current Pool PriceMin PriceMax PriceLiquidity Amplification Factor
10.81.210.38
10.91.120.44
10.981.02100.49
10.991.01200.49
1.0791.0631.1551.54
For a ranged pool with $$P\_{min}$$, $$P\_{max}$$, and $$P$$ as the minimum price, maximum price and current pool price, the amplication factor (AMP) can be calculated as $$AMP=\frac{1}{1 - \frac{1}{2}\left(\sqrt{\frac{P\_{min}}{P}} + \sqrt{\frac{P}{P\_{max}}} \right)}$$. Note that $$P\_{min} \leq P \leq P\_{max}$$. ### Possibility of Change to a Single-Coin Pool A ranged pool normally has two kinds of coins in the pool as the same as a basic pool. This is only applied to the case that the price is in the range of the pool. Once the price is out of the range, only a single kind of coin remains in the pool. For example, for the ranged pool with the range of 0.8 and 1.2, if the price is below 0.8, then the pool has only A coins. This means this pool sells out B coins and buys A coins at the price above 0.8. On contrary, if the price is above 1.2, then the pool has only B coins, which means the pool sells A coins and buy B coins at the price below 1.2. In that case of out-of-range, the users can deposit or withdraw to/from the pool with only a single kind of coin. ![Kinds of coins in the ranged pool corresponding to the price](/files/D4FFQBY3FVEs5o57SnqM) ### Multiple Pools per Coin Pair A pair of coins can have multiple liquidity pools such as one basic pool and multiple ranged pool with different ranges. The following example illustrates one basic pool and one ranged pool together providing the liquidity to the market. Thanks to the higher capital efficiency of the ranged pool, the traders benefit very low slippage in the price range of the pool. In the out-of-range of the ranged pool, the liquidity can still be provided by the basic pool, which enables trading in the region. ![Liquidity concentration only for predefined price range](/files/2DdJarU9hrrbWRQqSyvj) For more details with mathematics, please see [**here**](https://github.com/crescent-network/crescent/tree/main/docs/whitepapers/liquidity). # Market Maker Incentives ### Market Maker Market makers provide liquidity to the exchange by placing orders which are not executed immediately. These orders make it easy for traders to trade against provided market maker orders without waiting. ### Inclusion of Market Maker Any Crescent address can apply as a market maker for selected market pairs. A governance process decides inclusion, rejection and exclusion of registered market makers. ### Market Maker Incentives Registered market makers can earn CRE as incentives for providing liquidity. These incentives are calculated for each month by the off-chain market maker scoring system and distribute incentives based on the allocation suggested by governance proposals. ### **Market Maker incentive policy** Because Crescent DEX has the orderbook system, we have a possibility of providing much more capital-efficient liquidity compared to the liquidity provided by the traditional AMM model. The disadvantage of AMM is that it requires too much liquidity to be pooled to provide the same level of effective-liquidity compared to traditional financial markets. In other words, in the case of major tokens that are easy to hedge, if the incentive system for market makers is well designed, they will show capital efficiency comparable to that of the traditional financial market in providing liquidity. Through the incentive policy for market makers, we will incentivize them to bring a more tokens to our DEX, reduce the spread as much as possible, and provide liquidity to both bids and asks evenly. Market makers who maintain stable liquidity within the valid range on the orderbook will get relatively high score. There are two sections for market maker incentive program. First, the module manages the list of registered market makers and distributes incentives via governance process. Second, scoring system for off-chain evaluation of market maker performance. # MarketMaker Apply / Incentive Claim ### Market Maker Eligibility * Any Crescent address can apply as a market maker for selected market pairs. A governance process decides inclusion, rejection and exclusion of registered market makers. * New applicants are requested to submit ApplyMarketMaker message to be included in the uptime evaluation. Those who meet the uptime requirement can be included in eligible market makers through governance. * Market makers who fail to meet the requirements would excluded ### Applying Market Maker * Deposit designated deposit amount multiplied by number of pairs. * Submit ApplyMarketMaker message to be included in the uptime evaluation. * Those who meet the uptime requirement can be included in eligible market maker through governance. Uptime requirement is described in 'MarketMaker Scoring' page. * Governance proposal submit to decide inclusion, rejection, and exclusion of market makers. * Deposit will be refunded after inclusion or rejection. ### Incentives Claim * Only eligible market makers receive CRE incentives. Applicants who will get eligibility next month cannot claim incentive. * Market makers who support multiple pairs receive a combined amount of incentives at a time. * Incentives are claimable after the governance is passed. ## # MarketMaker Scoring ### Methodology * The evaluation objective is to reward market makers who consistently provide tight and deep liquidity for users. * Market makers earn points according to liquidity contribution, which means there is a score cap per block. * The calculation is done off-chain based on on-chain blockchain data. The codebase is publicly available for any third-party verification. ### Market Maker Eligibility * Market maker eligibility is decided by governance every month. * Only registered market makers can earn incentives based on their scores. Market makers who fail to meet the uptime requirements are also given their month incentives. * New applicants are requested to submit ApplyMarketMaker transaction to be included in the uptime evaluation. Those who meet the uptime requirement will be included in eligible market makers through governance. * The governance can exclude existing market makers who fail to meet the requirements for 2 consecutive months or 3 months within the last 5 months. ### Market Maker Orders Requirement * Orders satisfying following conditions can be recognized and evaluated: * Use MMOrder from eligible MMAddress * `Spread`equal or smaller than `MaxSpread` * Min(`AskWidth`,`BidWidth`) equal or larger than `MinWidth` * Min(`AskDepth`,`BidDepth`) equal or larger than `MinDepth` * Parameters (bottom of the document) are assigned differently for each pair depending on the market characteristics, and can be adjusted by governance ### Uptime Requirement * Uptime requirement is measured in 2 stages: * `LiveHour` is added as market maker provide valid orders for an hour. Following 1 out of 2 conditions, it fails: * No valid orders longer than `MaxDowntime` in a row * No valid orders longer than `MaxTotalDowntime` total in an hour * `LiveDay` is added as `LiveHour` is equal or larger than `MinHours` in a day * Those who earn`LiveDay` equal or larger than `MinDays` satisfy the uptime requirement. * Parameters (bottom of the document) are decided and adjusted by governance. ### Formula * Following formula is used to compute how much incentives should be rewarded to each market maker per month. The amount of CRE earned is determined by the relative share of each market maker’s score. 1. First step (within a block) * Calculate 2-sided liquidity point and take minimum value (take integer part) * $$P = min \lbrack{ {AskQ1}\over{AskD1^2} }+ { {AskQ2}\over{AskD2^2} } + ... , { {BidQ1}\over{BidD1^2} }+ { {BidQ2}\over{BidD2^2} } + ... \rbrack$$ 2. Second step (within a block) * Obtain contribution score by taking proportion of the point within the block $$P\_m \over \sum\_i P\_i$$ 3. Third step (within a month) * Calculate `Uptime` by dividing `LiveHour` with total hours in a month U = Total `LiveHour` / Total hours in a month 4. Forth step (Final score) * Final score of market maker ‘m’ is as following : $$S\_m = {U\_m} ^3 \sum ^{B}{t=1} \lbrack { P{mt} \over \sum\_i P\_{it} }\rbrack$$ * $$U\_m$$ : % of Market maker m’s `Uptime` in the month * $$B$$ : Total number of blocks for the month * $$P\_{mt}$$ : Contribution score of market maker ‘m’ at block ‘t’ ### Processing Order data * All variables are used as final values after the trade is made. * Even if the order of n-th tick is partially filled, the tick can still be a reference point(whether the highest bid or lowest ask) of measures when one of the following conditions is met. If not, the following tick becomes the reference point. * Min(`AskQ(n)`,`BidQ(n)`) is equal or larger than `MinOpenRatio` of the original order * Min(`AskQ(n)`,`BidQ(n)`) is equal or larger than `MinOpenDepthRatio` of `MinDepth`

Illustration of Bid/Ask

### Measures * Breadth * `MidPrice` : Average price of lowest ask and highest bid * `Spread` : Price difference between lowest ask and highest bid divide by `MidPrice` * `AskWidth` : Price difference between maximum and minimum ask divided by `MidPrice`. `BidWidth` is same with bid prices * `AskD(n)` : Price difference between `MidPrice` and n-th ask price divided by `MidPrice`. `BidD(n)` is same with bid prices * Depth * `AskQ(n)`,`BidQ(n)` : The amount of token remaining in n-th tick * `AskDepth`,`BidDepth` : Total amount of token remaining in ask or bid side ## Example
* Assume `MaxSpread` 0.012, `MinWidth` 0.002, `MinDepth` 100, `MinOpenRatio` 0.5, `MinOpenDepthRatio` 0.1 * Measure * Block 1
Market Maker AMarket Maker B
MidPrice9.945 = (9.96 + 9.93) / 29.945 = (9.97 + 9.92) / 2
Spread0.00301659.. = (9.96 - 9.93) / 9.9450.00502765.. = (9.97 - 9.92) / 9.945
AskWidth0.00301659.. = (9.99-9.96) / 9.9450.00201106.. = (9.99 - 9.97) / 9.945
BidWidth0.00301659.. = (9.93-9.90) / 9.9450.00201106.. = (9.92 - 9.90) / 9.945
AskD(1)0.00150829.. = (9.96-9.945) / 9.9450.00251382.. = (9.97 - 9.945) / 9.945
AskD(2)0.00251382.. = (9.97-9.945) / 9.9450.00351935.. = (9.98 - 9.945) / 9.945
AskD(3)0.00351935.. = (9.98-9.945) / 9.9450.00452488.. = (9.99 - 9.945) / 9.945
AskD(4)0.00452488.. = (9.99-9.945) / 9.945-
BidD(1)0.00150829.. = (9.945-9.93) / 9.9450.00251382.. = (9.945 - 9.92) / 9.945
BidD(2)0.00251382.. = (9.945-9.92) / 9.9450.00351935.. = (9.945 - 9.91) / 9.945
BidD(3)0.00351935.. = (9.945-9.91) / 9.9450.00452488.. = (9.945 - 9.90) / 9.945
BidD(4)0.00452488.. = (9.945-9.90) / 9.945-
AskDepth200225
BidDepth160240
AskQ(1)5075
AskQ(2)5075
AskQ(3)5075
AskQ(4)50-
BidQ(1)4080
BidQ(2)4080
BidQ(3)4080
BidQ(4)40-
* Block 2
Market Maker AMarket Maker B
MidPrice9.935 = (9.96 + 9.91) / 29.945 = (9.97 + 9.92) / 2
Spread0.00503271.. = (9.96 - 9.91) / 9.9350.00502765.. = (9.97 - 9.92) / 9.945
AskWidth0.00301962.. = (9.99-9.96) / 9.9350.00201106.. = (9.99 - 9.97) / 9.945
BidWidth0.00100654.. = (9.91-9.90) / 9.9350.00201106.. = (9.92 - 9.90) / 9.945
AskD(1)0.00251635.. = (9.96-9.935) / 9.9350.00251382.. = (9.97 - 9.945) / 9.945
AskD(2)0.00352289.. = (9.97-9.935) / 9.9350.00351935.. = (9.98 - 9.945) / 9.945
AskD(3)0.00452944.. = (9.98-9.935) / 9.9350.00452488.. = (9.99 - 9.945) / 9.945
AskD(4)0.00553598.. = (9.99-9.935) / 9.935-
BidD(1)0.00050327.. = (9.935-9.93) / 9.9350.00251382.. = (9.945 - 9.92) / 9.945
BidD(2)0.00150981.. = (9.935-9.92) / 9.9350.00351935.. = (9.945 - 9.91) / 9.945
BidD(3)0.00251635.. = (9.935-9.91) / 9.9350.00452488.. = (9.945 - 9.90) / 9.945
BidD(4)0.00352289.. = (9.935-9.90) / 9.935-
AskDepth190225
BidDepth80180
AskQ(1)4075
AskQ(2)5075
AskQ(3)5075
AskQ(4)50-
BidQ(1)020
BidQ(2)580
BidQ(3)4080
BidQ(4)40-
* In case of market maker A, the highest bid has moved from 9.93 to 9.91 at block 2. `BidQ(2)` does not meet the either conditions of `MinOpenRatio` of original order amount (5/40 < 0.5) nor `MinOpenDepthRatio` ( 100(`MinDepth`) \* 0.1 = 10 ). * For market maker B’s case, reference point haven’t changed. `BidQ(1)` could not meet the `MinOpenRatio` (20/80 < 50)condition, but larger than `MinOpenDepthRatio`. * Liquidity Point * Block 1 * Both market maker A and B meet the condition * `Spread(A)`, `Spread(B)` < `MaxSpread` (0.012) * `AskWidth(A)`, `BidWidth(A)`, `AskWidth(B)`, `BidWidth(B)` > `MinWidth` (0.002) * `AskDepth(A)`, `BidDepth(A)`, `AskDepth(B)`, `BidDepth(B)` > `MinDepth` (100) * Each point on Block 1 is as follows, $$P\_{A1} = min \lbrack{ {50}\over{0.0015..^2} }+ {{50}\over{0.0025..^2} } + {{50}\over{0.0035..^2} }+ {{50}\over{0.0045..^2} }, {{40}\over{0.0015..^2} }+ {{40}\over{0.0025..^2} } + {{40}\over{0.0035..^2}}+ {{40}\over{0.0035..^2} }\rbrack$$ $$P\_{A1} = min \lbrack36369600, 29095680\rbrack = 29,095,680$$\ $$P\_{B1} = min \lbrack{ {75}\over{0.0025..^2} }+ {{75}\over{0.0035..^2} } + {{75}\over{0.0045..^2} }, {{80}\over{0.0025..^2} }+ {{80}\over{0.0035..^2} } + {{80}\over{0.0045..^2}}\rbrack$$\ $$P\_{B1} = min \lbrack 21586725, 23025840\rbrack = 21,586,725$$ * Block 2 * Only Market maker B meet the condition, * `Spread(A)`, `Spread(B)` < `MaxSpread` (0.012) * `AskWidth(A)`, `AskWidth(B)`, `BidWidth(B)` > `MinWidth` (0.002) * `BidWidth(A) < MinWidth` * `AskDepth(A)`, `AskDepth(B)`, `BidDepth(B)` > `MinDepth` (100) * `BidDepth(A) < MinDepth` $$P\_{A2} = min \lbrack 14414430,0\rbrack = 0$$\ $$P\_{B2} = min \lbrack{ {75}\over{0.0025..^2} }+ {{75}\over{0.0035..^2} } + {{75}\over{0.0045..^2} }, {{20}\over{0.0025..^2} }+ {{80}\over{0.0035..^2} } + {{80}\over{0.0045..^2}}\rbrack$$\ $$P\_{B2} = min \lbrack 21586725, 13531150\rbrack = 13,531,150$$ * Contribution Score * Block 1\ $$C\_{A1} = \frac{29095680}{29095680+21586725} = 0.574078..$$\ $$C\_{B1} = \frac{21586725}{29095680+21586725} = 0.425921..$$ * Block 2\ $$C\_{A2} = 0$$\ $$C\_{B2} = 1$$ * Final Score * Sum up all of the contribution scores for the month and product cube of uptime * Market maker A : (Assuming uptime 70%) $$S\_A = (0.7)^3 \*(0.5740.. + 0 +...)$$ * Market maker B : (Assuming uptime 90%) : $$S\_B = (0.9)^3 \*( 0.4259..+1+...)$$ ### Parameters Scoring module contains following parameters : #### Common Parameters
KeyDefinitionExample
MinOpenRatioMinimum ratio to maintain the tick order0.5
MinOpenDepthRatioMinimum ratio of open amount to MinDepth0.1
MaxDowntimeMaximum allowable consecutive blocks of outage20 (blocks)
MaxTotalDowntimeMaximum allowable sum of blocks in an hour100 (blocks)
MinHoursMinimum value of LiveHour to achieve LiveDay16
MinDaysMinimum value of LiveDay to maintain MM eligibility22
#### Parameters for each pair
KeyDefinitionExample
PairIdPair id of liquidity module20
UpdateTimeTime the pair variables start to be applied to the scoring system2022-12-01T00:00:00Z
IncentiveWeightIncentive weights for each pair0.1
MaxSpreadMaximum allowable spread between bid and ask0.006 (ETH-USDC pair), 0.012 (ATOM-USDC pair)
MinWidthMinimum allowable price difference of high and low on both side of orders0.001 (ETH-USDC pair), 0.002 (ATOM-USDC pair)
MinDepthMinimum allowable order depth on each side600000000000000000 (ETH-USDC pair), 100000000 (ATOM-USDC pair)
# Synergy with Crescent Boost #### **Hedging and Leveraging Liquidity Pool Investment by Crescent Boost** Crescent Boost, which is the second utility of Crescent Network, allows liquidity pool investors to collateralize liquidity pool positions to borrow tokens. If an investor borrows and sells the same kind of token provided for collateral, value fluctuation can be minimized. Furthermore, if the investor choose to borrow and deposit instead of to borrow and sell, the investor will have a leveraged reward while the effect of value fluctuation is same as before. Crescent Boost provides users a simplified process to enjoy the leveraging and hedging utility to enhance risk-return profile of their investment by reducing risk and multiplying rewards. #### **Amplified Rewards with Market Neutrality** Crescent Network will lead significant changes in DeFi investment culture. Crescent will provide various ways to reduce risk and enhance rewards at the same time to achieve much better sharpe ratio on their DeFi investment. Crescent Boost will benefit Crescent DEX by inducing additional liquidity. # CLI and API This pages will be updated continuously. ## Prerequisite for CLI You can [download](https://github.com/crescent-network/crescent/releases) the latest release (as of writing time, it is V5.0.0) of Crescent Network as source code or binary files for your OS. {% embed url="" %} # AMM module # CLI Reference ## Transaction ### CreatePool Create a pool to market for trading. A pool is tied to a single market and places orders to market based on the preset logic. Once a pool is created, liquidity providers can create positions. Usage ```bash create-pool [market-id] [price] ``` | **Argument** | **Description** | | ------------ | ------------------------------------------------------ | | market-id | id of the market where the pool's order will be placed | | price | initial pool price | Example ```bash # Create a pool crescentd tx amm create-pool 1 10 \ --chain-id localnet \ --from alice # # Tips # # You can query pools by using the following command crescentd q amm pools -o json | jq ``` ### AddLiquidity Add liquidity to existing position or make a new position. Position(s) belong to a pool. Therefore, a pool must exist in order to create a position. Anyone can create a position with custom range. Usage ```bash add-liquidity [pool-id] [lower-price] [upper-price] [desired-amount] ``` | **Argument** | **Description** | | -------------- | -------------------------------------------------- | | pool-id | pool id | | lower-price | lower bound for price range of liquidity providing | | upper-price | upper bound for price range of liquidity providing | | desired-amount | deposit amounts of base and quote coins | Example ```bash # Create a position with 10ATOM/10USD which provide liquidity to price range [9,11] crescentd tx amm add-liquidity 1 9 11 10000000uatom,10000000uusd \ --chain-id localnet \ --from alice # # Tips # # You can query expected result of add-liquidity by using the following command crescentd q amm add-liquidity-simulation 1 9 11 10000000uatom,10000000uusd -o json | jq ``` ### RemoveLiquidity Withdraw coins from the liquidity providing position. Withdrawal requests are typically processed in the order they are received, rather than being delayed until the end of a batch. Usage ```bash remove-liquidity [position-id] [liquidity] ``` | **Argument** | **Description** | | ------------ | --------------------------------------------------- | | position-id | position id | | liquidity | amount of liquidity to be removed from the position | Example ```bash # Remove 10000 liquidity from position with id 1 crescentd tx amm remove-liquidity 1 10000 \ --chain-id localnet \ --from alice # # Tips # # You can query expected result of remove-liquidity by using the following command crescentd q amm remove-liquidity-simulation 1 10000 -o json | jq ``` ### Collect Collect rewards accumulated in a position. The reward consists of the swap fee and farming reward accumulated in the position. Usage ```bash collect [position-id] [amount] ``` | **Argument** | **Description** | | ------------ | --------------------------------- | | position-id | position id | | amount | amounts of reward to be withdrawn | Example ```bash # Withdraw 10uATOM and 10uUSD of reward from the positino crescentd tx amm collect 1 10uatom,10uusd \ --chain-id localnet \ --from alice # # Tips # # You can query collectible reward by using the following command crescentd crescentd q amm collectible-coins --position-id 1 -o json | jq ``` ### CreatePrivateFarmingPlan Create a new private farming plan. The newly created plan's farming pool address is automatically generated and will have no balances in the account initially. Manually send enough reward coins to the generated farming pool address to make sure that the rewards allocation happens. The plan's termination address is set to the plan creator. ```bash create-private-farming-plan [description] [termination-address] [start-time] [end-time] [reward-allocations...] ``` | **Argument** | **Description** | | --------------------- | ------------------------------------------------------------------------------------------------------- | | description | a brief description of the plan | | termination-address | address where the remaining farming rewards in the farming pool transferred when the plan is terminated | | start-time | the time at which the plan begins, in RFC3339 format | | end-time | the time at which the plan ends, in RFC3339 format | | reward-allocations... | whitespace-separated list of the reward allocations | Example ```bash # Create private farming plan crescentd tx amm create-private-farming-plan "New farming plan" cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p 2023-01-01T00:00:00Z 2024-01-01T00:00:00Z 1:1000000uatom \ --chain-id localnet \ --from alice \ # # Tips # # You can query farming plans by using the following command crescentd q amm farming-plans -o json | jq ``` ### TerminatePrivateFarmingPlan Terminate a private farming plan. The plan's termination address must be same with the message sender. Usage ```bash terminate-private-farming-plan [farming-plan-id] ``` \| **Argument** | **Description** | | |:------------------|:--------------- | | farming-plan-id | farming plan id | Example ```bash # Withdraw pool coin from the pool crescentd tx amm terminate-private-farming-plan 1 \ --chain-id localnet \ --from alice \ # # Tips # # You can query farming plans by using the following command crescentd q amm farming-plans -o json | jq ``` ## Query ### Params Query the current amm parameters information Usage ```bash params ``` Example ```bash crescentd q amm params -o json | jq ``` ### AllPools Query for all pools Usage ```bash pools ``` Example ```bash crescentd q amm pools -o json | jq ``` ### Pool Query details for the particular pool Usage ```bash pool [pool-id] ``` Example ```bash crescentd q amm pool 1 -o json | jq ``` ### AllPositions Query for all positions Usage ```bash positions ``` Example ```bash # Query all positions crescentd q amm positions -o json | jq # Query all positions that has the pool id crescentd q amm positions --pool-id 1 -o json | jq # Query all positions of particular address crescentd q amm position --owner cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq ``` ### Position Query details for the particular position Usage ```bash position [position-id] ``` Example ```bash crescentd q amm position 1 -o json | jq ``` ### AddLiquiditySimulation Query expected result for add-liquidity Usage ```bash add-liquidity-simulation [pool-id] [lower-price] [upper-price] [desired-amount] ``` Example ```bash crescentd q amm add-liquidity-simulation 1 9 11 10000000uatom,10000000uusd -o json | jq ``` ### RemoveLiquiditySimulation Query expected result for remove-liquidity Usage ```bash remove-liquidity-simulation [position-id] [liquidity] ``` Example ```bash crescentd q amm remove-liquidity-simulation 1 10000 -o json | jq ``` ### CollectibleCoins Query collectible coins(fees, rewards) in the position. Usage ```bash collectible-coins ``` Example ```bash # Query collectible coins with address crescentd q amm collectible-coins --owner cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq # Query collectible coins with position id crescentd q amm collectible-coins --position-id 1 -o json | jq ``` ### AllTickInfos Query for information of all ticks in the particular pool Usage ```bash tick-infos [pool-id] ``` Example ```bash # Query all ticks in pool crescentd q amm tick-infos 1 -o json | jq # Query all ticks above designated lower tick crescentd q amm tick-infos 1 --lower-tick 10000 -o json | jq # Query all ticks below designated upper tick crescentd q amm tick-infos 1 --upper-tick 10000 -o json | jq ``` ### TickInfo Query details for the particular tick in the pool Usage ```bash tick-info [pool-id] [tick] ``` Example ```bash crescentd q amm tick-info 1 10000 -o json | jq ``` ### AllFarmingPlans Query for all farming plans Usage ```bash farming-plans ``` Example ```bash # Query all farming plans crescentd q amm farming-plans -o json | jq # Query farming plans based on private status crescentd q amm farming-plans --is-private true -o json | jq # Query farming plans based on private status crescentd q amm farming-plans --is-terminated true -o json | jq ``` ### FarmingPlan Query details for the particular farming plan Usage ```bash farming-plan [plan-id] ``` Example ```bash crescentd q amm farming-plan 1 -o json | jq ``` # API Reference ### Params Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/params ``` Example Response ```json { "params": { "pool_creation_fee": [ { "denom": "stake", "amount": "1000000" } ], "default_tick_spacing": 50, "private_farming_plan_creation_fee": [ { "denom": "stake", "amount": "1000000" } ], "max_num_private_farming_plans": 50, "max_farming_block_time": "10s" } } ``` ### AllPools Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/pools http://localhost:1317/crescent/amm/v1beta1/pools?market_id=1 ``` Example Response ```json { "pools": [ { "id": "1", "market_id": "1", "balance0": { "denom": "uatom", "amount": "706867" }, "balance1": { "denom": "uusd", "amount": "12020740" }, "reserve_address": "cre1pf3w839s80c26z8dqccuzu4epyj58jrzglqv93yppqpj6yggu9qs8vpazr", "rewards_pool": "cre1srphgsfqllr85ndknjme24txux8m0sz0hhpnnksn2339d3a788rs3ax6tu", "tick_spacing": 50, "min_order_quantity": "1.000000000000000000", "min_order_quote": "1.000000000000000000", "current_tick": 90208, "current_price": "10.208470700277704312", "current_liquidity": "61622776", "total_liquidity": "61622776", "fee_growth_global": [ { "denom": "uatom", "amount": "2417937.160117551341731180" }, { "denom": "uusd", "amount": "8072226411.870831654841385269" } ], "farming_rewards_growth_global": [ { "denom": "uatom", "amount": "1363132.358723988675875290" } ] } ], "pagination": { "next_key": null, "total": "1" } } ``` ### Pool Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/pools/1 ``` Example Response ```json { "pool": { "id": "1", "market_id": "1", "balance0": { "denom": "uatom", "amount": "706867" }, "balance1": { "denom": "uusd", "amount": "12020740" }, "reserve_address": "cre1pf3w839s80c26z8dqccuzu4epyj58jrzglqv93yppqpj6yggu9qs8vpazr", "rewards_pool": "cre1srphgsfqllr85ndknjme24txux8m0sz0hhpnnksn2339d3a788rs3ax6tu", "tick_spacing": 50, "min_order_quantity": "1.000000000000000000", "min_order_quote": "1.000000000000000000", "current_tick": 90208, "current_price": "10.208470700277704312", "current_liquidity": "61622776", "total_liquidity": "61622776", "fee_growth_global": [ { "denom": "uatom", "amount": "2417937.160117551341731180" }, { "denom": "uusd", "amount": "8072226411.870831654841385269" } ], "farming_rewards_growth_global": [ { "denom": "uatom", "amount": "6052956.783381521144065276" } ] } } ``` ### AllPositions Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/positions http://localhost:1317/crescent/amm/v1beta1/positions?pool_id=1 http://localhost:1317/crescent/amm/v1beta1/positions?owner=cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p ``` Example Response ```json { "positions": [ { "id": "1", "pool_id": "1", "owner": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", "lower_price": "9.000000000000000000", "upper_price": "11.000000000000000000", "liquidity": "61622776", "last_fee_growth_inside": [ ], "owed_fee": [ ], "last_farming_rewards_growth_inside": [ ], "owed_farming_rewards": [ ] } ], "pagination": { "next_key": null, "total": "1" } } ``` ### Position Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/positions/1 ``` Example Response ```json { "position": { "id": "1", "pool_id": "1", "owner": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", "lower_price": "9.000000000000000000", "upper_price": "11.000000000000000000", "liquidity": "61622776", "last_fee_growth_inside": [ ], "owed_fee": [ ], "last_farming_rewards_growth_inside": [ ], "owed_farming_rewards": [ ] } } ``` ### AddLiquiditySimulation Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/simulation/add_liquidity?pool_id=1&lower_price=9&upper_price=11&desired_amount=100uatom,100uusd ``` Example Response ```json { "liquidity": "559", "amount": [ { "denom": "uatom", "amount": "8" }, { "denom": "uusd", "amount": "100" } ] } ``` ### RemoveLiquiditySimulation Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/simulation/remove_liquidity?position_id=1&liquidity=10000 ``` Example Response ```json { "amount": [ { "denom": "uatom", "amount": "130" }, { "denom": "uusd", "amount": "1785" } ] } ``` ### CollectibleCoins Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/collectible_coins?owner=cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p http://localhost:1317/crescent/amm/v1beta1/collectible_coins?position_id=1 ``` Example Response ```json { "fee": [ { "denom": "uatom", "amount": "147" }, { "denom": "uusd", "amount": "2571" } ], "farming_rewards": [ { "denom": "uatom", "amount": "63407" } ] } ``` ### AllTickInfos Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/pools/1/tick_infos ``` Example Response ```json { "tick_infos": [ { "tick": 80000, "gross_liquidity": "61622776", "net_liquidity": "61622776", "fee_growth_outside": [ ], "farming_rewards_growth_outside": [ ] }, { "tick": 91000, "gross_liquidity": "61622776", "net_liquidity": "-61622776", "fee_growth_outside": [ ], "farming_rewards_growth_outside": [ ] } ], "pagination": { "next_key": null, "total": "2" } } ``` ### TickInfo Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/pools/1/tick_infos/80000 ``` Example Response ```json { "tick_info": { "tick": 80000, "gross_liquidity": "61622776", "net_liquidity": "61622776", "fee_growth_outside": [ ], "farming_rewards_growth_outside": [ ] } } ``` ### AllFarmingPlans Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/farming_plans ``` Example Response ```json { "farming_plans": [ { "id": "1", "description": "New farming plan", "farming_pool_address": "cre1ll5dtdmug9n54fnhr9fpr8nmr840s72dstydd723ufgsxzrjg5qq9kzn3e", "termination_address": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", "reward_allocations": [ { "pool_id": "1", "rewards_per_day": [ { "denom": "uatom", "amount": "1000000" } ] } ], "start_time": "2023-01-01T00:00:00Z", "end_time": "2024-01-01T00:00:00Z", "is_private": true, "is_terminated": false } ], "pagination": { "next_key": null, "total": "1" } } ``` ### FarmingPlan Example Request ```bash http://localhost:1317/crescent/amm/v1beta1/farming_plans/1 ``` Example Response ```json { "farming_plan": { "id": "1", "description": "New farming plan", "farming_pool_address": "cre1ll5dtdmug9n54fnhr9fpr8nmr840s72dstydd723ufgsxzrjg5qq9kzn3e", "termination_address": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", "reward_allocations": [ { "pool_id": "1", "rewards_per_day": [ { "denom": "uatom", "amount": "1000000" } ] } ], "start_time": "2023-01-01T00:00:00Z", "end_time": "2024-01-01T00:00:00Z", "is_private": true, "is_terminated": false } } ``` # Exchange module # CLI Reference ## Transaction ### CreateMarket Create a market for trading assets. Usage ```bash create-market [base-denom] [quote-denom] ``` | **Argument** | **Description** | | ------------ | -------------------------------------- | | base-denom | denom of the base coin for the market | | quote-denom | denom of the quote coin for the market | Example ```bash # Create a pool crescentd tx exchange create-market uatom uusd \ --chain-id localnet \ --from alice # # Tips # # You can query markets using the following command crescentd q exchange markets -o json | jq ``` ### PlaceLimitOrder Place a limit order to markets. This order will be placed in sequential matching stage. For buy orders, it allows orders up to 10% above the current price, and for sell orders, it allows orders up to 10% below the current price. This is to prevent users from incurring large financial losses due to simple mistakes. Usage ```bash place-limit-order [market-id] [is-buy] [price] [quantity] [lifespan] ``` | **Argument** | **Description** | | ------------ | ---------------------------------------------------------------------------------------- | | market-id | market id | | is-buy | if this is true, the order is placed to buy base coin | | price | order price; the exchange ratio is the amount of quote coin over the amount of base coin | | quantity | amount of base coin that the orderer is willing to buy or sell | | lifespan | duration that the order lives until it is expired | Example ```bash # Place a limit order crescentd tx exchange place-limit-order 1 true 15 100000 1h \ --chain-id localnet \ --from alice # # Tips # # You can query orders by using the following command # Query all orders crescentd q exchange orders -o json | jq # Query all orders in particular market crescentd q exchange orders --makret-id 1 -o json | jq # Query all orders of particular orderer crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq ``` ### PlaceBatchLimitOrder Place a batch limit order. Batch orders are matched prior to normal orders in a batch matching stage. For buy orders, it allows orders up to 10% above the current price, and for sell orders, it allows orders up to 10% below the current price. This is to prevent users from incurring large financial losses due to simple mistakes. Usage ```bash place-batch-limit-order [market-id] [is-buy] [price] [quantity] [lifespan] ``` | **Argument** | **Description** | | ------------ | ---------------------------------------------------------------------------------------- | | market-id | market id | | is-buy | if this is true, the order is placed to buy base coin | | price | order price; the exchange ratio is the amount of quote coin over the amount of base coin | | quantity | amount of base coin that the orderer is willing to buy or sell | | lifespan | duration that the order lives until it is expired | Example ```bash # Place a batch limit order crescentd tx exchange place-batch-limit-order 1 true 15 100000 1h \ --chain-id localnet \ --from alice # # Tips # # You can query orders by using the following command # Query all orders crescentd q exchange orders -o json | jq # Query all orders in particular market crescentd q exchange orders --makret-id 1 -o json | jq # Query all orders of particular orderer crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq ``` ### PlaceMMLimitOrder Place a market maker limit order. For buy orders, it allows orders up to 10% above the current price, and for sell orders, it allows orders up to 10% below the current price. This is to prevent users from incurring large financial losses due to simple mistakes. Usage ```bash place-mm-limit-order [market-id] [is-buy] [price] [quantity] [lifespan] ``` | **Argument** | **Description** | | ------------ | ---------------------------------------------------------------------------------------- | | market-id | market id | | is-buy | if this is true, the order is placed to buy base coin | | price | order price; the exchange ratio is the amount of quote coin over the amount of base coin | | quantity | amount of base coin that the orderer is willing to buy or sell | | lifespan | duration that the order lives until it is expired | Example ```bash # Place a market maker limit order crescentd tx exchange place-mm-limit-order 1 true 15 100000 1h \ --chain-id localnet \ --from alice # # Tips # # You can query orders by using the following command # Query all orders crescentd q exchange orders -o json | jq # Query all orders in particular market crescentd q exchange orders --makret-id 1 -o json | jq # Query all orders of particular orderer crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq ``` ### PlaceMMBatchLimitOrder Place a market maker batch limit order. Batch orders are matched prior to normal orders in a batch matching stage. For buy orders, it allows orders up to 10% above the current price, and for sell orders, it allows orders up to 10% below the current price. This is to prevent users from incurring large financial losses due to simple mistakes. Usage ```bash place-mm-batch-limit-order [market-id] [is-buy] [price] [quantity] [lifespan] ``` | **Argument** | **Description** | | ------------ | ---------------------------------------------------------------------------------------- | | market-id | market id | | is-buy | if this is true, the order is placed to buy base coin | | price | order price; the exchange ratio is the amount of quote coin over the amount of base coin | | quantity | amount of base coin that the orderer is willing to buy or sell | | lifespan | duration that the order lives until it is expired | Example ```bash # Place a market maker batch limit order crescentd tx exchange place-mm-batch-limit-order 1 true 15 100000 1h \ --chain-id localnet \ --from alice # # Tips # # You can query orders by using the following command # Query all orders crescentd q exchange orders -o json | jq # Query all orders in particular market crescentd q exchange orders --makret-id 1 -o json | jq # Query all orders of particular orderer crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq ``` ### PlaceMarketOrder Place a market order. Usage ```bash place-market-order [market-id] [is-buy] [quantity] ``` | **Argument** | **Description** | | ------------ | -------------------------------------------------------------- | | market-id | market id | | is-buy | if this is true, the order is placed to buy base coin | | quantity | amount of base coin that the orderer is willing to buy or sell | Example ```bash # Place a market order crescentd tx exchange place-market-order 1 false 100000 \ --chain-id localnet \ --from alice ``` ### CancelOrder Cancel an existing order. Usage ```bash cancel-order [order-id] ``` | **Argument** | **Description** | | ------------ | --------------- | | order-id | order id | Example ```bash # Place a market order crescentd tx exchange cancel-order 1 \ --chain-id localnet \ --from alice ``` ### CancelAllOrders Cancel all orders in a market placed by the sender Usage ```bash cancel-all-orders [market-id] ``` | **Argument** | **Description** | | ------------ | --------------- | | market-id | market id | Example ```bash # Place a market order crescentd tx exchange cancel-all-orders 1 \ --chain-id localnet \ --from alice ``` ### SwapExactAmountIn Swap with exact input amount. User need to specify swap routes from input to output. If the result of the swap falls short of user's desired output, the request will be reverted. Usage ```bash swap-exact-amount-in [routes] [input] [min-output] ``` | **Argument** | **Description** | | ------------ | --------------------------------------------------------------- | | routes | sequential swap routes | | input | input token denom and amount | | min-output | The denom and minimum amount of the user's desired output token | Example ```bash # Place a market order crescentd tx exchange swap-exact-amount-in 1,2,3 1000000uusd 98000uatom \ --chain-id localnet \ --from alice ``` ## Query ### Params Query the current exchange parameters information Usage ```bash params ``` Example ```bash crescentd q exchange params -o json | jq ``` ### AllMarkets Query for all markets Usage ```bash markets ``` Example ```bash crescentd q exchange markets -o json | jq ``` ### Market Query details for the particular market Usage ```bash market [market-id] ``` Example ```bash crescentd q exchange market 1 -o json | jq ``` ### AllOrders Query for all orders Usage ```bash orders ``` Example ```bash # Query all orders crescentd q exchange orders -o json | jq # Query all orders in particular market crescentd q exchange orders --makret-id 1 -o json | jq # Query all orders of particular orderer crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq ``` ### Order Query details for the particular order Usage ```bash order [order-id] ``` Example ```bash crescentd q exchange order 1 -o json | jq ``` ### BestSwapExactAmountInRoutes Query for the route that can be swapped at the best price given the input token denom and volume, and the denom of the output token. Usage ```bash best-swap-exact-amount-in-routes [input] [output-denom] ``` Example ```bash crescentd q exchange best-swap-exact-amount-in-routes 1000000uusd uatom -o json | jq ``` ### Orderbook Query orderbook of particular market from exisiting orders Usage ```bash order-book [market-id] ``` Example ```bash crescentd q exchange order-book 1 -o json | jq ``` # API Reference ### Params Example Request ```bash http://localhost:1317/crescent/exchange/v1beta1/params ``` Example Response ```json { "params": { "market_creation_fee": [ { "denom": "stake", "amount": "1000000" } ], "fees": { "default_maker_fee_rate": "0.001500000000000000", "default_taker_fee_rate": "0.003000000000000000", "default_order_source_fee_ratio": "0.500000000000000000" }, "max_order_lifespan": "86400s", "max_order_price_ratio": "0.100000000000000000", "max_swap_routes_len": 3, "max_num_mm_orders": 15 } } ``` ### AllMarkets Example Request ```bash http://localhost:1317/crescent/exchange/v1beta1/markets ``` Example Response ```json { "markets": [ { "id": "1", "base_denom": "uatom", "quote_denom": "uusd", "escrow_address": "cre1whhqyaxuv9vrmr00slaqa6zg9cf30nk4k6ltpqvp6ecn6vks5mfsttzq30", "maker_fee_rate": "0.001500000000000000", "taker_fee_rate": "0.003000000000000000", "order_source_fee_ratio": "0.500000000000000000", "last_price": "15.000000000000000000", "last_matching_height": "6948" } ], "pagination": { "next_key": null, "total": "1" } } ``` ### Market Example Request ```bash http://localhost:1317/crescent/exchange/v1beta1/markets/1 ``` Example Response ```json { "market": { "id": "1", "base_denom": "uatom", "quote_denom": "uusd", "escrow_address": "cre1whhqyaxuv9vrmr00slaqa6zg9cf30nk4k6ltpqvp6ecn6vks5mfsttzq30", "maker_fee_rate": "0.001500000000000000", "taker_fee_rate": "0.003000000000000000", "order_source_fee_ratio": "0.500000000000000000", "last_price": "15.000000000000000000", "last_matching_height": "6948" } } ``` ### AllOrders Example Request ```bash http://localhost:1317/crescent/exchange/v1beta1/orders ``` Example Response ```json { "orders": [ { "id": "6", "type": "ORDER_TYPE_MM", "orderer": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", "market_id": "1", "is_buy": true, "price": "15.000000000000000000", "quantity": "100000.000000000000000000", "msg_height": "7213", "open_quantity": "100000.000000000000000000", "remaining_deposit": "1500000.000000000000000000", "deadline": "2023-08-30T05:30:50.090404Z" } ], "pagination": { "next_key": null, "total": "1" } } ``` ### Order Example Request ```bash http://localhost:1317/crescent/exchange/v1beta1/orders/1 ``` Example Response ```json { "order": { "id": "1", "type": "ORDER_TYPE_LIMIT", "orderer": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", "market_id": "1", "is_buy": true, "price": "9.000000000000000000", "quantity": "100000", "msg_height": "6549", "open_quantity": "100000", "remaining_deposit": "900000", "deadline": "2023-06-29T07:28:37.840415Z" } } ``` ### BestSwapExactAmountInRoutes Example Request ```bash http://localhost:1317/crescent/exchange/v1beta1/best_swap_exact_amount_in_routes?input=100uatom&output_denom=uusd ``` Example Response ```json { "routes": [ "1" ], "output": { "denom": "uusd", "amount": "1016" }, "results": [ { "market_id": "1", "input": { "denom": "uatom", "amount": "100" }, "output": { "denom": "uusd", "amount": "1016" }, "fee": { "denom": "uusd", "amount": "4" } } ] } ``` ### Orderbook Example Request ```bash http://localhost:1317/crescent/exchange/v1beta1/markets/1/order_book ``` Example Response ```json { "order_books": [ { "price_interval": "0.001000000000000000", "sells": [ ], "buys": [ { "p": "15.000000000000000000", "q": "100000.000000000000000000" } ] }, { "price_interval": "0.010000000000000000", "sells": [ ], "buys": [ { "p": "15.000000000000000000", "q": "100000.000000000000000000" } ] }, { "price_interval": "0.100000000000000000", "sells": [ ], "buys": [ { "p": "15.000000000000000000", "q": "100000.000000000000000000" } ] } ] } ``` # LiquidStaking module # CLI Reference ## Transaction ### LiquidStake Liquid stake coin. It requires `whitelisted_validators` to be registered. The [config.yml](https://github.com/crescent-network/crescent/blob/main/config.yml) file registers a single whitelist validator for testing purpose. #### Usage ``` liquid-stake [amount] ``` | **Argument** | **Description** | | ------------ | --------------------------------------------------------- | | amount | amount of coin to liquid stake; it must be the bond denom | #### Example ``` crescentd tx liquidstaking liquid-stake 5000000000stake \ --chain-id localnet \ --from bob \ --keyring-backend test \ --gas 1000000 \ --broadcast-mode block \ --yes \ --output json | jq # # Tips # # Query account balances # Notice the newly minted bToken crescentd q bank balances cre1mzgucqnfr2l8cj5apvdpllhzt4zeuh2c5l33n3 -o json | jq # Query the voter's liquid staking voting power crescentd q liquidstaking voting-power cre1mzgucqnfr2l8cj5apvdpllhzt4zeuh2c5l33n3 -o json | jq ``` ### LiquidUnstake Unstake coin. #### Usage ``` liquid-unstake [amount] ``` | **Argument** | **Description** | | ------------ | ------------------------------------------------------ | | amount | amount of coin to unstake; it must be the bToken denom | #### Example ``` crescentd tx liquidstaking liquid-unstake 1000000000bstake \ --chain-id localnet \ --from bob \ --keyring-backend test \ --gas 1000000 \ --broadcast-mode block \ --yes \ --output json | jq # # Tips # # Query account balances # Notice the newly minted bToken crescentd q bank balances cre1mzgucqnfr2l8cj5apvdpllhzt4zeuh2c5l33n3 -o json | jq # Query the voter's liquid staking voting power crescentd q liquidstaking voting-power cre1mzgucqnfr2l8cj5apvdpllhzt4zeuh2c5l33n3 -o json | jq ``` ## Query ### Params Query the current liquidstaking parameters information. #### Usage ``` params ``` #### Example ``` crescentd query liquidstaking params -o json | jq ``` ### LiquidValidators Query all liquid validators. #### Usage ``` liquid-validators ``` #### Example ``` crescentd query liquidstaking liquid-validators -o json | jq ``` ### States Query net amount state. #### Usage ``` states ``` #### Example ``` crescentd query liquidstaking states -o json | jq ``` ### VotingPower Query the voter’s staking and liquid staking voting power. #### Usage ``` voting-power [voter] ``` | **Argument** | **Description** | | ------------ | --------------------- | | voter | voter account address | #### Example ``` crescentd query liquidstaking voting-power cre1mzgucqnfr2l8cj5apvdpllhzt4zeuh2c5l33n3 -o json | jq ``` # API Reference ### Params #### Example Request ``` http://localhost:1317/crescent/liquidstaking/v1beta1/params ``` #### Example Response ``` { "params": { "liquid_bond_denom": "bstake", "whitelisted_validators": [ { "validator_address": "crevaloper1zaavvzxez0elundtn32qnk9lkm8kmcszyvldht", "target_weight": "100000000" } ], "unstake_fee_rate": "0.001000000000000000", "min_liquid_staking_amount": "1000000" } } ``` ### Validators #### Example Request ``` http://localhost:1317/crescent/liquidstaking/v1beta1/validators ``` #### Example Response ``` { "liquid_validators": [ { "operator_address": "crevaloper1zaavvzxez0elundtn32qnk9lkm8kmcszyvldht", "weight": "100000000", "status": "VALIDATOR_STATUS_ACTIVE", "del_shares": "0.000000000000000000", "liquid_tokens": "0" } ] } ``` ### VotingPower #### Example Request ``` http://localhost:1317/crescent/liquidstaking/v1beta1/voting_power/cre1mzgucqnfr2l8cj5apvdpllhzt4zeuh2c5l33n3 ``` #### Example Response ``` { "voting_power": { "voter": "cre1mzgucqnfr2l8cj5apvdpllhzt4zeuh2c5l33n3", "staking_voting_power": "0", "liquid_staking_voting_power": "5000000000", "validator_voting_power": "0" } } ``` ### States #### Example Request ``` http://localhost:1317/crescent/liquidstaking/v1beta1/states ``` #### Example Response ``` { "net_amount_state": { "mint_rate": "0.999682079425781607", "btoken_total_supply": "5000000000", "net_amount": "5001590108.399267325000000000", "total_del_shares": "5000000000.000000000000000000", "total_liquid_tokens": "5000000000", "total_remaining_rewards": "1590108.399267325000000000", "total_unbonding_balance": "0", "proxy_acc_balance": "0" } } ``` # LiquidAmm module # CLI Reference ## Transaction ### MintShare Mint liquid farm share for auto compounding rewards. The module mints the corresponding amount of `sbCoin` and sends it to the farmer when the execution is complete. Usage ```bash mint-share [public-position-id] [desired-amount] ``` | **Argument** | **Description** | | ------------------ | --------------------------------------- | | public-position-id | liquid farm id | | desired-amount | deposit amounts of base and quote coins | Example ```bash # In order to fully test the module in your local network, liquidFarm must be set up by governance proposal. # # For example, crescentd tx gov submit-proposal public-position-create proposal.json --chain-id localnet --from alice Where proposal.json contains: { "title": "Public Position Create Proposal", "description": "Let's start new liquid amm", "pool_id": "1", "lower_price": "4.5", "upper_price": "5.5", "min_bid_amount": "100000000", "fee_rate": "0.003" } # mint share crescentd tx liquidamm mint-share 1 100000000uatom,500000000uusd \ --chain-id localnet \ --from alice # # Tips # # Query all the registered public position objects crescentd q liquidamm public-positions -o json | jq # # Query account balances to see if Alice has sb-coin. crescentd q bank balances cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq ``` ### BurnShare Burn liquid amm share to withdraw underlying tokens. Usage ```bash burn-share [public-position-id] [share] ``` | **Argument** | **Description** | | ------------------ | ------------------------------- | | public-position-id | liquid farm id | | share | desired amount of burning share | Example ```bash crescentd tx liquidamm burn-share 1 10000000000sb1 \ --chain-id localnet \ --from alice \ # # Tips # # Query account balances crescentd q bank balances cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq ``` ### PlaceBid Place a bid for a rewards auction. Bidders estimate how much rewards for the next epoch will be accumulated and place their bids accordingly with sb coin amount. Usage ```bash place-bid [public-position-id] [auction-id] [share] ``` | **Argument** | **Description** | | ------------------ | ---------------------- | | public-position-id | liquid farm id | | auction-id | auction id | | share | bid amount for auction | Example ```bash crescentd tx liquidamm place-bid 1 1 10000000sb1 \ --chain-id localnet \ --from alice \ # # Tips # crescentd q liquidamm bids 1 -o json | jq ``` ## Query ### Params Query the current liquidamm parameters information. Usage ```bash params ``` Example ```bash crescentd query liquidamm params -o json | jq ``` ### PublicPositions Query for all public positions. Usage ```bash public-positions ``` Example ```bash crescentd query liquidamm public-positions -o json | jq ``` ### PublicPosition Query the specific public position with id. Usage ```bash public-position [public-position-id] ``` Example ```bash crescentd query liquidamm public-position 1 -o json | jq ``` ### RewardsAuctions Query all rewards auctions for specific public position. Usage ```bash rewards-auctions [public-position-id] ``` Example ```bash # The "rewards_auction_duration" param is the duration that is used to create new rewards auction in begin blocker. # You can adjust the value in config-test.yml file to make it faster or slower. # By default, the value is set to 8 hours but for local testing purpose it is set to 120 seconds. # If you wait 120 seconds (2 minutes) after starting a local network, the module automatically creates new rewards auction. crescentd query liquidamm rewards-auctions 1 -o json | jq crescentd query liquidamm rewards-auctions 1 --status AUCTION_STATUS_STARTED -o json | jq crescentd query liquidamm rewards-auctions 1 --status AUCTION_STATUS_FINISHED -o json | jq crescentd query liquidamm rewards-auctions 1 --status AUCTION_STATUS_SKIPPED -o json | jq ``` ### RewardsAuction Query the specific reward auction Usage ```bash rewards-auction [public-position-id] [auction-id] ``` Example ```bash crescentd query liquidamm rewards-auction 1 1 -o json | jq ``` ### Bids Query all bids for the rewards auction Usage ```bash bids [public-position-id] [auction-id] ``` Example ```bash crescentd query liquidamm bids 1 1 -o json | jq ``` ### Rewards Query current farming rewards for the particular liquid farm Usage ```bash rewards [public-position-id] ``` Example ```bash crescentd query liquidamm rewards 1 -o json | jq ``` # API Reference ### Params Example Request ```bash http://localhost:1317/crescent/liquidamm/v1beta1/params ``` Example Response ```json { "params": { "rewards_auction_duration": "3600s", "max_num_recent_rewards_auctions": 10 } } ``` ### PublicPositions Example Request ```bash http://localhost:1317/crescent/liquidamm/v1beta1/public_positions ``` Example Response ```json { "public_positions": [ { "id": "1", "pool_id": "1", "lower_tick": 35000, "upper_tick": 45000, "bid_reserve_address": "cre1rkln8d74uhfyc9qp3645xnwks0pd8rsterguf6uugd2g60m37dmqwcapvh", "min_bid_amount": "100000", "fee_rate": "0.003000000000000000", "last_rewards_auction_id": "0", "liquidity": "0", "position_id": "0", "total_share": { "denom": "sb1", "amount": "0" } } ], "pagination": { "next_key": null, "total": "1" } } ``` ### PublicPosition Example Request ```bash http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1 ``` Example Response ```json { "public_position": { "id": "1", "pool_id": "1", "lower_tick": 35000, "upper_tick": 45000, "bid_reserve_address": "cre1rkln8d74uhfyc9qp3645xnwks0pd8rsterguf6uugd2g60m37dmqwcapvh", "min_bid_amount": "100000", "fee_rate": "0.003000000000000000", "last_rewards_auction_id": "0", "liquidity": "0", "position_id": "0", "total_share": { "denom": "sb1", "amount": "0" } } } ``` ### RewardsAuctions Example Request ```bash http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions?status=AUCTION_STATUS_STARTED http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions?status=AUCTION_STATUS_FINISHED http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions?status=AUCTION_STATUS_SKIPPED ``` Example Response ```json { "rewards_auctions": [ { "public_position_id": "1", "id": "1", "start_time": "2023-07-05T01:59:28.180826Z", "end_time": "2023-07-06T00:00:00Z", "status": "AUCTION_STATUS_STARTED", "winning_bid": null, "rewards": [ ], "fees": [ ] } ], "pagination": { "next_key": null, "total": "1" } } ``` ### RewardsAuction Example Request ```bash http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions/1 ``` Example Response ```json { "rewards_auction": { "public_position_id": "1", "id": "1", "start_time": "2023-07-05T01:59:28.180826Z", "end_time": "2023-07-06T00:00:00Z", "status": "AUCTION_STATUS_STARTED", "winning_bid": null, "rewards": [ ], "fees": [ ] } } ``` ### Bids Example Request ```bash http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions/1/bids ``` Example Response ```json { "bids": [ { "public_position_id": "1", "rewards_auction_id": "1", "bidder": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", "share": { "denom": "sb1", "amount": "1000000" } } ], "pagination": { "next_key": null, "total": "1" } } ``` ### Rewards Example Request ```bash http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards ``` Example Response ```json { "rewards": [ { "denom": "uatom", "amount": "50456" }, { "denom": "uusd", "amount": "749866" } ] } ``` # Market Maker ## Checking pool information * CLI * All Pools: * Pool: * API * All Pools: * Pool: ## Making a limit order * CLI: ## Making a batch limit order * CLI: ## Making a mm limit order * CLI: ## Making a mm batch limit order * CLI: ## Making a market order * CLI: ## Canceling an order * CLI: ## Canceling all orders * CLI: ## More Informations * For more detailed informations about the amm module and exchange module: {% content-ref url="/pages/11D77UC6nmXw9gPNeGso" %} [AMM module](/developer-guide/cli-and-api/amm-module) {% endcontent-ref %} {% content-ref url="/pages/XWrXUfrnDPFrrDyWfM3X" %} [Exchange module](/developer-guide/cli-and-api/exchange-module) {% endcontent-ref %} # Farming Planner ## Making a market * CLI: ## Making a pool * CLI: ## Making a private farming plan * CLI: ## Terminating private farming plan * CLI: ## More Informations * For more detailed informations about the amm module and exchange module: {% content-ref url="/pages/11D77UC6nmXw9gPNeGso" %} [AMM module](/developer-guide/cli-and-api/amm-module) {% endcontent-ref %} {% content-ref url="/pages/XWrXUfrnDPFrrDyWfM3X" %} [Exchange module](/developer-guide/cli-and-api/exchange-module) {% endcontent-ref %} # Network Configurations Network configurations for Crescent Mainnet and Testnet. ## Crescent-1 (Mainnet) * ChainID: crescent-1 * RPC: [https://mainnet.crescent.network:26657](https://mainnet.crescent.network:26657/) * GRPC: mainnet.crescent.network:9090 (TLS) * LCD: [https://mainnet.crescent.network:1317](https://mainnet.crescent.network:1317/) * Block Explorers * * * [https://crescent.explorers.guru](https://crescent.explorers.guru/) * Quicksync/Snapshop * * * P2P seed: `929f22a7b04ff438da9edcfebd8089908239de44@18.180.232.184:26656` * INFO: * Binary: ## Mooncat (Public Testnet) * Chain ID: `mooncat-2-external` * LCD: [https://testnet-endpoint.crescent.network:26657](https://testnet-endpoint.crescent.network:26657/) * GRPC: testnet-endpoint.crescent.network:9090 (tls) * RPC: [https://testnet-endpoint.crescent.network:1317](https://testnet-endpoint.crescent.network:1317/) * Block Explorers * * * Faucet: * P2P node: `89760782cc1fcf11ca8a1cdc3494a8d788699313@52.74.77.1:26656` * INFO: * Binary: # Crescent Design Assets ## Logos ### Crescent ![](/files/3yw1TMQlG6xiI8haUY2I) {% file src="/files/rADUuUoX0oPwXILKUklp" %} including AI/PNG/SVG files {% endfile %} ### CRE {% file src="/files/wJpM7gm0g26mcDfdt8Of" %} ### bCRE {% file src="/files/FQxpDuIHMQJeB19rqBw8" %}