diff --git a/core/cap-0038.md b/core/cap-0038.md index ea68042bc..2ad08adbc 100644 --- a/core/cap-0038.md +++ b/core/cap-0038.md @@ -700,8 +700,8 @@ specified by minPrice and maxPrice. is equivalent to `lpdo.minPrice.n / lpdo.minPrice.d > lpdo.maxPrice.n / lpdo.maxPrice.d`) -The process of applying `LiquidityPoolDepositOp lpdo` with source `sourceAccount` -is +The process of applying `LiquidityPoolDepositOp lpdo` with source `sourceAccount` is: + ``` tlPool = loadTrustLine(sourceAccount, lpdo.liquidityPoolID) if !exists(tlPool) @@ -758,7 +758,7 @@ else if INT64_MAX - amountA < cp.reserveA || INT64_MAX - amountB < cp.reserveB || - INT64_MAX - amountPoolShares < cp.totalPolShares + INT64_MAX - amountPoolShares < cp.totalPoolShares Fail with LIQUIDITY_POOL_DEPOSIT_POOL_FULL tlA.balance -= amountA @@ -788,8 +788,8 @@ minAmountA and minAmountB. - `lpwo.minAmountA < 0` - `lpwo.minAmountB < 0` -The process of applying `LiquidityPoolWithdrawOp lpwo` with source `sourceAccount` -is +The process of applying `LiquidityPoolWithdrawOp lpwo` with source `sourceAccount` is: + ``` tlPool = loadTrustLine(sourceAccount, lpwo.liquidityPoolID) if !exists(tlPool) @@ -879,7 +879,7 @@ If `line.type() == ASSET_TYPE_POOL_SHARE` and - If pool share trust line is being deleted - `poolSharesTrustLineCount` is decremented on the corresponding liquidity - pool, and `liquidityPoolUseCount` is decremented on each asset trust line. + pool and `liquidityPoolUseCount` is decremented on each asset trust line. - If `poolSharesTrustLineCount` on the corresponding liquidity pool becomes 0, then that liquidity pool is erased. @@ -890,13 +890,14 @@ referenced asset trust lines get their authorization revoked. For each redeemed pool share trust line, a claimable balance will be created for every constituent asset if there is a balance being withdrawn and the claimant is not the issuer. This means that for a redeemed pool share trust line, there can be zero, one, or -two claimable balances created. These claimable balances will be sponsored by the -sponsor of the pool share trust line, and will be unconditionally claimable by the +two claimable balances created. These claimable balances are sponsored by the +sponsor of the pool share trust line and are unconditionally claimable by the owner of the pool share trust line. The validity conditions for `SetTrustLineFlagsOp` and `AllowTrustOp` are unchanged. -The process of applying `SetTrustLineFlagsOp` and `AllowTrustOp` +The process of applying `SetTrustLineFlagsOp` and `AllowTrustOp` is: + ``` tl = loadTrustLine(trustor, asset) @@ -1021,7 +1022,7 @@ such a liquidity pool is `(X + x - Fx) (Y - y) >= XY` where - `x` is the amount received by the liquidity pool - `y` is the amount disbursed by the liquidity pool -There are two important cases to handle: if we know the amount received, and if +There are two important cases to handle: if we know the amount received and if we know the amount disbursed. If we know the amount received `x`, then the invariant can be rearranged to yield ``` @@ -1064,8 +1065,8 @@ Three different flags can be set (enforced by This will allow validators to disable parts of this CAP in the event that unexpected behavior is encountered. These flags can only be set if -validators vote for them, and they should only be used in case of emergency. The -ability to disable these pool related features is only temporary, and will be +validators vote for them and they should only be used in case of emergency. The +ability to disable these pool related features is only temporary and will be removed in the future. ## Design Rationale @@ -1123,7 +1124,7 @@ the Claimable Balance in the first place and make this scenario simpler for the ### Authorization revocation of an asset trust line in a pool can fail Here are the possible scenarios when a trust line in a pool has it's authorization revoked. -Remember that the pool share trust line is deleted to free up reserves for two claimable balances - +(Remember that the pool share trust line is deleted to free up reserves for two claimable balances.) 1. Account A has a pool share trust line. - On revoke, claimable balances are sponsored by A. Guaranteed to succeed. @@ -1178,11 +1179,11 @@ satisfying `x',y' > 0` and `f(x',y') = 0` that are sufficiently near to are constrained to satisfy `f(x,y) = 0`. Then the value of the reserves can be minimized by the method of Lagrange multipliers. Let `z` be a Lagrange multiplier and define the Lagrangian `L(x,y,z) = x + py - z f(x,y)`. This -yields the system of equations +yields the system of equations: ``` 0 = dL/dx = 1 - z df/dx 0 = dL/dy = p - z df/dy -0 = dL/dz = -f(x,y) . +0 = dL/dz = -f(x,y) ``` `z` can be eliminated by combining the first two equations, which produces `df/dy = p df/dx`. Following from the definition of `f`, there exist unique @@ -1207,9 +1208,9 @@ x = py ``` has the unique solution `y = sqrt(k/p), x = sqrt(kp)` where `x,y > 0`. Now note that for any `(x',y')` satisfying `x',y' > 0` and `f(x',y') = 0`, the AM-GM -inequality implies +inequality implies: ``` -x' + py' = x' + kp/x' >= 2 sqrt(kp) = x + py . +x' + py' = x' + kp/x' >= 2 sqrt(kp) = x + py ``` ### Price Bounds for LiquidityPoolWithdrawOp @@ -1278,10 +1279,10 @@ payments check authorization. ### Clawback assets from a pool There are no operations that clawback directly from a pool, but the same results can be achieved by using `SetTrustlineFlagsOp` or `AllowTrustOp`. The -issuer can deauthorize an asset trust line, which will redeem the all pool -trust lines using that asset and account back to the owner account if -possible, and if not, into a claimable balance. The issuer can then use -`ClawbackOp` or `ClawbackClaimableBalanceOp` to clawback the assets. +issuer can deauthorize an asset trust line, which will either redeem the all +pool trust lines using that asset and account back to the owner account if +possible or, if not possible, into a claimable balance. The issuer can then +use `ClawbackOp` or `ClawbackClaimableBalanceOp` to clawback the assets. ### Alternative authorization revocation solution The current proposal forces a redemption of all referenced pool trust lines when an @@ -1290,7 +1291,7 @@ solution. We could instead require the issuer to revoke authorization on individual pool trust lines to force a redemption. This approach will require the issuer to look up all pool trust lines for an asset trust line to perform the revoke. It would also add an additional step when regulating assets for the -issuer, so we would need to add an opt in flag for liquidity pools so issuers +issuer, so we would need to add an opt-in flag for liquidity pools so issuers are aware of this. This approach would be simpler to implement, and we wouldn't need to tie the @@ -1317,7 +1318,7 @@ changes to clients that depend on exchange. Because this is an opaque interface, the only thing we should absolutely require is that adding liquidity pools as an execution option should never make the -exchange price worse. This is a weak requirement. Specifically it is much weaker +exchange price worse. This is a weak requirement. Specifically, it is much weaker than requiring that exchange produces the best price. The primary reason not to require that exchange produces the best price is ease @@ -1327,7 +1328,7 @@ any liquidity pools. In other words, the exchange might cross some offers and also exchange with liquidity pools. Compare against the simpler implementation where an exchange will execute against either -- the order book alone (this is exactly what happens in protocol 16) +- the order book alone (this is exactly what happens in protocol 16) or - one specific liquidity pool alone depending on which produces the better price. This price is not guaranteed to be