Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/ControlFlow.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ actually executed within a pre-loaded liquidity curve.
### Ambient Mints & Burns

Ambient liquidity positions represent liquidity that's active at every price point along the curve. Because this liquidity never goes in or out of
range there's less gas cost associated with these actions, and external staking contracts can be guaranteed that these positions continiously add
range there's less gas cost associated with these actions, and external staking contracts can be guaranteed that these positions continuously add
liquidity across their entire lifetime.

A mint action is when the user adds liquidity to the pool by creating a new position or increasing the liquidity in a previous position:
Expand All @@ -55,7 +55,7 @@ A burn action is when the user removes liquidity from the pool by deleting or de
### Range Concentrated Mints & Burns

Range concentrated liquidity positions are only active within an arbitrary user-specified price range. This gives the user control over when and where
her position adds liquidity, and increases capital efficiency by removing the need for supporting collateral outside the price range.
their position adds liquidity, and increases capital efficiency by removing the need for supporting collateral outside the price range.

A mint occurs when the user adds range liquidity by creating a new position or increasing the liquidity in a previous position:

Expand All @@ -70,4 +70,4 @@ A burn occurs when the user removes range liquidity by deleting or decreasing th
A swap occurs within a liquidity curve when one token is converted to the token from the opposite side. This adjusting the price within the invariant of the AMM,
knocking liquidity in or out depending on the range-bound LPs whose boundaries were crossed, and assimilating the associated liquidity fees into the curve:

![Burn Ambient](assets/SwapFlow.jpeg)
![Swap](assets/SwapFlow.jpeg)
4 changes: 2 additions & 2 deletions docs/CurveBounds.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ Beyond this, the protocol imposes a tighter limit of [2^-48, 2^60] on the curve

The Q64.64 representation of root price also means that the minimum precision of any price change is 2^-64 in square root space. In percentage terms that means pools with lower prices have lower precision. Since the protocol enforces a minimum value of 2^-48 on root price, all curves have a minimum percentage precision of 2^-16 in square root terms. Or 0.003% in price terms.

Any swap will have its price imapct rounded up in terms of minimum price precision. The floating side of the swap is rounded in favor of the pool to prevent under-collateralization. Practically this means that the swapper will "burn" a small percentage on every swap proportional to the curve's total liquidity and minimum price precision.
Any swap will have its price impact rounded up in terms of minimum price precision. The floating side of the swap is rounded in favor of the pool to prevent under-collateralization. Practically this means that the swapper will "burn" a small percentage on every swap proportional to the curve's total liquidity and minimum price precision.

## Concentrated Liquidity

Concentrated liquidity for the curve is represented as 128-bit unsigned integer. Liquidity is represented as the square root of full range XY=K liquidity. This imposes a bound on the liqudity
Concentrated liquidity for the curve is represented as 128-bit unsigned integer. Liquidity is represented as the square root of full range XY=K liquidity. This imposes a bound on the liquidity
ceiling of any given pool.

For pools with a price of unity (1.0), this imposes a limit of 2^128 in terms of XY=K equivalent base or quote tokens. For tokens with 18 decimals represents over one quintillion XY=K equivalent tokens.
Expand Down
2 changes: 1 addition & 1 deletion docs/Encoding.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ To optimize gas, long-form CrocSwap calls rely on Solidity ABI encoding for prim
based on specification described here. CrocSwap will also make available a TypeScript based SDK to support client-side encoding.

The input argument for long-form orders is a binary encoding, with several nested variable length array fields. Each array field is preceded by a count field that
must allign with the number of elements in the array. The nested structure is visualized below.
must align with the number of elements in the array. The nested structure is visualized below.

(*In the below and following diagrams all primitive type fields are marked with their Solidity type and byte size.*)

Expand Down
6 changes: 3 additions & 3 deletions docs/FeeOdometer.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ The below illustrates an example of how rewards would accumulate to a range orde

Even though the whole pool accumulated 575 units of reward during the above timeline, the range order only accumulated 150 units of reward, representing the time and price range it was active at.

## Lifetime Rewards Rewards
## Lifetime Range Rewards

The first step to calculating accumulated rewards for a range order is to calculate the total cumulative rewards for a specific range. Regardless of the range, an order’s accumulative rewards is simply the growth in the cumulative rewards in that range from the begging to the end of the order’s lifetime.
The first step to calculating accumulated rewards for a range order is to calculate the total cumulative rewards for a specific range. Regardless of the range, an order’s accumulative rewards is simply the growth in the cumulative rewards in that range from the beginning to the end of the order’s lifetime.

The below illustrates an example of how an order’s accumulated rewards can be calculated based off the cumulative rewards for its corresponding range:

Expand All @@ -38,7 +38,7 @@ The odometer snapshots the global cumulative rewards that occured on the opposit

The odometer flips its snapshot every time the curve crosses the tick price. Because rewards can’t accumulate on a given side until the curve price crosses the tick, the odometer always is up to date.

Calculating the cumulative rewards below the tick, when the curve price is below the tick just involves subtracting the up to date cumulative global rewards from the last snapshot of what the cumulative rewards above the rick were.
Calculating the cumulative rewards below the tick, when the curve price is below the tick just involves subtracting the up to date cumulative global rewards from the last snapshot of what the cumulative rewards above the tick were.

(By convention when a tick is first created, the odometer is setup to assume that all existing cumulative rewards occurred below the tick. Since we ultimately only care about the *change* of accumulated rewards when calculating rewards over an order lifetime, the initialization value doesn’t matter as long as it’s consistent over the lifetime of the order.)

Expand Down
2 changes: 1 addition & 1 deletion docs/Layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Math and calculation libraries:
* CompoundMath.sol - Calculators for compound growth and deflation rates
* CurveMath.sol - Computes price and reserve changes across a constant product AMM curve.

Libraries related to exeucting swaps and tracking LP positions
Libraries related to executing swaps and tracking LP positions

* CurveRoll.sol - Derives flow on a constant-product AMM curve based on targeted price or reserve changes
* CurveAssimilate.sol - Converts collected fees into liquidity on the AMM curve.
Expand Down
2 changes: 1 addition & 1 deletion docs/TokenModel.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ CrocSwap is a fully permissionless AMM, and users can create pools on any token

An unsafe or malicious token could easily lead to any pools with that token becoming silently under-collateralized. For example if a malicious token zeroes the `CrocSwapDex` address balance in the token tracker contract. If a pool becomes under-collateralized it may no longer be possible to recover the underlying tokens in an existing liquidity position. Therefore users, particularly liquidity providers **must fully trust** all tokens for CrocSwap pools that they’re interacting with.

In addition CrocSwap does not natively support fee on transfer, rebase tokens, or any other token that doesn’t respect the ERC20 `transfer()` and `transferFrom()`standard. In addition CrocSwap verifies that transfer amount matches at pool initialization time, but for efficiency does not check on any subsequent calls. If a token ever stops conforming to the `transfer()` ERC20 standard, a pool may be silently become under-collateralized or silently underpay the receiver leg of a `swap()` call. Therefore users, both swappers and liquidity providers, must be responsible in assuring that any tokens they’re interacting with on CrocSwap are fully conformant with the ERC20 standard, do not have fee on transfer, are not rebasing.
In addition CrocSwap does not natively support fee on transfer, rebase tokens, or any other token that doesn’t respect the ERC20 `transfer()` and `transferFrom()`standard. In addition CrocSwap verifies that transfer amount matches at pool initialization time, but for efficiency does not check on any subsequent calls. If a token ever stops conforming to the `transfer()` ERC20 standard, a pool may be silently become under-collateralized or silently underpay the receiver leg of a `swap()` call. Therefore users, both swappers and liquidity providers, must be responsible in assuring that any tokens they’re interacting with on CrocSwap are fully compliant with the ERC20 standard, do not have fee on transfer, are not rebasing.

The same standards apply to user surplus collateral balances. A user depositing a surplus collateral balance to the `CrocSwapDex` contract is responsible for assuring that all of the above conditions are true for that token otherwise the token balance may become **partially or fully uncrecoverable**.

Expand Down
2 changes: 1 addition & 1 deletion docs/UpgradeGuidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Introduction

The CrocSwap protocol, particularly the core `CrocSwapDex` contract is designed to be incrementally and modularly upgradeable, subject to protocol governance. The core smart contract is designed to support up to 65,000 attached proxy contracts. Any proxy contract can be directly invoked by and end-user with the `userCmd` or `protocolCmd` function call to the `CrocSwapDex` contract.
The CrocSwap protocol, particularly the core `CrocSwapDex` contract is designed to be incrementally and modularly upgradeable, subject to protocol governance. The core smart contract is designed to support up to 65,000 attached proxy contracts. Any proxy contract can be directly invoked by an end-user with the `userCmd` or `protocolCmd` function call to the `CrocSwapDex` contract.

Although the architecture is highly amenable to incremental upgrades, the upgrade process is still a highly risky operation and should be carefully considered and reviewed before being executed. In addition given the relatively unique architecture of the smart contract there are a set of specific considerations and guidelines that should be applied to any proposed upgrade.

Expand Down