Merge pull request #41 from euler-xyz/doc-improvements

Doc improvements

Author: haythemsellami

README.md

@@ -42,6 +42,12 @@ forge test
 forge coverage
 ```
 
+## Smart Contracts Documentation
+
+```sh
+forge doc --serve --port 4000
+```
+
 ## Safety
 
 This software is experimental and is provided "as is" and "as available".

docs/boundary-analysis.md

@@ -0,0 +1,138 @@
+# Boundary analysis
+
+## Introduction
+
+The EulerSwap automated market maker (AMM) curve is governed by two key functions: f() and fInverse(). These functions are critical to maintaining protocol invariants and ensuring accurate swap calculations within the AMM. This document provides a detailed boundary analysis of both functions, assessing their Solidity implementations against the equations in the white paper. It ensures that appropriate safety measures are in place to avoid overflow, underflow, and precision loss, and that unchecked operations are thoroughly justified.
+
+## Implementation of function `f()`
+
+The `f()` function is part of the EulerSwap core, defined in `EulerSwap.sol`, and corresponds to equation (2) in the EulerSwap white paper. The `f()` function is a parameterisable curve in the `EulerSwap` contract that defines the permissible boundary for points in EulerSwap AMMs. The curve allows points on or above and to the right of the curve while restricting others. Its primary purpose is to act as an invariant validator by checking if a hypothetical state `(x, y)` within the AMM is valid. It also calculates swap output amounts for given inputs, though some swap scenarios require `fInverse()`.
+
+### Derivation
+
+This derivation shows how to implement the `f()` function in Solidity, starting from the theoretical model described in the EulerSwap white paper. The initial equation from the EulerSwap white paper is:
+
+\[
+y_0 + \left(\frac{p_x}{p_y}\right) (x_0 - x) \left(c + (1 - c) \frac{x_0}{x}\right)
+\]
+
+Multiply the second term by \(\frac{x}{x}\) and scale `c` by \(1e18\):
+
+\[
+y_0 + \left(\frac{p_x}{p_y}\right) (x_0 - x) \frac{(c \cdot x) + (1e18 - c) \cdot x_0}{x \cdot 1e18}
+\]
+
+Reorder division by \(p_y\) to prepare for Solidity implementation:
+
+\[
+y_0 + p_x \cdot (x_0 - x) \cdot \frac{(c \cdot x) + (1e18 - c) \cdot x_0}{x \cdot 1e18} \cdot \frac{1}{p_y}
+\]
+
+To avoid intermediate overflow, use `Math.mulDiv` in Solidity, which combines multiplication and division safely:
+
+\[
+y_0 + \frac{\text{Math.mulDiv}(p_x \cdot (x_0 - x), c \cdot x + (1e18 - c) \cdot x_0, x \cdot 1e18)}{p_y}
+\]
+
+Applying ceiling rounding with `Math.Rounding.Ceil` ensures accuracy:
+
+\[
+y_0 + \left(\text{Math.mulDiv}(p_x \cdot (x_0 - x), c \cdot x + (1e18 - c) \cdot x_0, x \cdot 1e18, \text{Math.Rounding.Ceil}) + (p_y - 1)\right) / p_y
+\]
+
+Adding `(p_y - 1)` ensures proper ceiling rounding by making sure the result is rounded up when the numerator is not perfectly divisible by `p_y`.
+
+### Boundary analysis
+
+#### Pre-conditions
+
+- \(x \leq x_0\)
+- \(1e18 \leq p_x, p_y \leq 1e36\) (60 to 120 bits)
+- \(1 \leq x_0, y_0 \leq 2^{112} - 1 \approx 5.19e33\) (0 to 112 bits)
+- \(1 < c \leq 1e18\) (0 to 60 bits)
+
+#### Step-by-step
+
+The arguments to `mulDiv` are safe from overflow:
+
+- **Arg 1:** `px * (x0 - x)` ≤ `1e36 * (2**112 - 1)` ≈ 232 bits
+- **Arg 2:** `c * x + (1e18 - c) * x0` ≤ `1e18 * (2**112 - 1) * 2` ≈ 173 bits
+- **Arg 3:** `x * 1e18` ≤ `1e18 * (2**112 - 1)` ≈ 172 bits
+
+If `mulDiv` or the addition with `y0` overflows, the result would exceed `type(uint112).max`. When `mulDiv` overflows, its result would be > `2**256 - 1`. Dividing by `py` (`1e36` max) gives ~`2**136`, which exceeds the `2**112 - 1` limit, meaning these results are invalid as they cannot be satisfied by any swapper.
+
+#### Unchecked math considerations
+
+The arguments to `mulDiv` are protected from overflow as demonstrated above. The `mulDiv` output is further limited to `2**248 - 1` to prevent overflow in subsequent operations:
+
+```solidity
+unchecked {
+    uint256 v = Math.mulDiv(px * (x0 - x), c * x + (1e18 - c) * x0, x * 1e18, Math.Rounding.Ceil);
+    require(v <= type(uint248).max, Overflow());
+    return y0 + (v + (py - 1)) / py;
+}
+```
+
+This does not introduce additional failure cases. Even values between `2**248 - 1` and `2**256 - 1` would not reduce to `2**112 - 1`, aligning with the boundary analysis.
+
+## Implementation of function `fInverse()`
+
+The `fInverse()` function, defined in `EulerSwapPeriphery.sol`, is part of the periphery because it is not required as an invariant. Instead, its sole purpose is to facilitate specific swap input and output calculations that cannot be managed by `f()`. This function maps to equation (22) in the Appendix of the EulerSwap white paper.
+
+### Boundary analysis
+
+#### Pre-conditions
+
+- \(y > y_0\)
+- \(1e18 \leq p_x, p_y \leq 1e36\) (60 to 120 bits)
+- \(1 \leq x_0, y_0 \leq 2^{112} - 1 \approx 5.19e33\) (0 to 112 bits)
+- \(1 < c \leq 1e18\) (0 to 60 bits)
+
+#### Step-by-step
+
+1. **A component (`A = 2 * c`)**
+
+   - Since `c <= 1e18`, `A = 2 * c <= 2e18`, well within `uint256` capacity (max `2**256 - 1`).
+
+2. **B component calculation**
+
+   - `B = int256((px * (y - y0) + py - 1) / py) - int256((x0 * (2 * c - 1e18) + 1e18 - 1) / 1e18)`
+   - The first term is bounded by `(px * (y - y0)) / py`, where `px, py <= 1e36` and `(y - y0) <= 2**112 - 1`.
+   - The second term scales `x0` with `(2 * c - 1e18)`, keeping the result well within the `int256` bounds due to controlled arithmetic and the limits on `c` and `x0`.
+
+3. **Absolute value and B² computation**
+
+   - `absB = B < 0 ? uint256(-B) : uint256(B)`
+   - `squaredB = Math.mulDiv(absB, absB, 1e18, Math.Rounding.Ceil)`
+   - As `absB` is derived from `B`, and `B` is bounded, `squaredB` remains within a safe range.
+
+4. **4AC Component (`AC4 = AC4a * AC4b / 1e18`)**
+
+   - `AC4a = Math.mulDiv(4 * c, (1e18 - c), 1e18, Math.Rounding.Ceil)`
+   - `4 * c * (1e18 - c)` has a maximum of `1e18 * 1e18 = 1e36`, divided by `1e18`, the result ≤ `1e18`.
+   - `AC4b = Math.mulDiv(x0, x0, 1e18, Math.Rounding.Ceil)`
+   - The maximum value of `x0 * x0` is `(2**112 - 1)² ≈ 2**224`, safely within the `uint256` range.
+
+5. **Discriminant calculation**
+
+   - `discriminant = (squaredB + AC4) * 1e18`
+   - Since both `squaredB` and `AC4` are bounded by `uint256`, multiplying by `1e18` does not cause overflow.
+
+6. **Square root computation and adjustment**
+
+   - `uint256 sqrt = Math.sqrt(discriminant)`
+   - The square root of a `uint256` value is always within `uint128`, making this operation safe.
+   - Adjustment step `sqrt = (sqrt * sqrt < discriminant) ? sqrt + 1 : sqrt` maintains precision without overflow.
+
+7. **Final computation of `x`**
+   - `Math.mulDiv(uint256(int256(sqrt) - B), 1e18, A, Math.Rounding.Ceil)`
+   - The subtraction and multiplication are controlled by previous bounds, ensuring no overflow.
+   - Division by `A` is safe as `A` is non-zero and small (`≤ 2e18`).
+
+#### Unchecked math considerations
+
+As above, the use of unchecked arithmetic is safe because all inputs are bounded by pre-conditions.
+
+## Conclusion
+
+The `f()` and `fInverse()` functions of EulerSwap are implemented with rigorous safety measures, using `Math.mulDiv` for safe arithmetic and applying ceiling rounding to maintain precision. Boundary analysis shows that all potential overflow scenarios are precluded by pre-condition checks and bounded operations, justifying the use of unchecked math in the Solidity implementation.

docs/f.md

@@ -0,0 +1 @@
+book/

foundry-docs/.gitignore

@@ -0,0 +1,13 @@
+table {
+    margin: 0 auto;
+    border-collapse: collapse;
+    width: 100%;
+}
+
+table td:first-child {
+    width: 15%;
+}
+  
+table td:nth-child(2) {
+    width: 25%;
+}

foundry-docs/book.css

@@ -0,0 +1,12 @@
+[book]
+src = "src"
+title = "Euler Swap Contracts Documentation"
+
+[output.html]
+no-section-label = true
+additional-js = ["solidity.min.js"]
+additional-css = ["book.css"]
+git-repository-url = "https://github.com/euler-xyz/euler-maglev"
+
+[output.html.fold]
+enable = true

foundry-docs/book.toml

@@ -0,0 +1,74 @@
+hljs.registerLanguage("solidity",(()=>{"use strict";function e(){try{return!0
+}catch(e){return!1}}
+var a=/-?(\b0[xX]([a-fA-F0-9]_?)*[a-fA-F0-9]|(\b[1-9](_?\d)*(\.((\d_?)*\d)?)?|\.\d(_?\d)*)([eE][-+]?\d(_?\d)*)?|\b0)(?!\w|\$)/
+;e()&&(a=a.source.replace(/\\b/g,"(?<!\\$)\\b"));var s={className:"number",
+begin:a,relevance:0},n={
+keyword:"assembly let function if switch case default for leave break continue u256 jump jumpi stop return revert selfdestruct invalid",
+built_in:"add sub mul div sdiv mod smod exp not lt gt slt sgt eq iszero and or xor byte shl shr sar addmod mulmod signextend keccak256 pc pop dup1 dup2 dup3 dup4 dup5 dup6 dup7 dup8 dup9 dup10 dup11 dup12 dup13 dup14 dup15 dup16 swap1 swap2 swap3 swap4 swap5 swap6 swap7 swap8 swap9 swap10 swap11 swap12 swap13 swap14 swap15 swap16 mload mstore mstore8 sload sstore msize gas address balance selfbalance caller callvalue calldataload calldatasize calldatacopy codesize codecopy extcodesize extcodecopy returndatasize returndatacopy extcodehash create create2 call callcode delegatecall staticcall log0 log1 log2 log3 log4 chainid origin gasprice basefee blockhash coinbase timestamp number difficulty gaslimit",
+literal:"true false"},i={className:"string",
+begin:/\bhex'(([0-9a-fA-F]{2}_?)*[0-9a-fA-F]{2})?'/},t={className:"string",
+begin:/\bhex"(([0-9a-fA-F]{2}_?)*[0-9a-fA-F]{2})?"/};function r(e){
+return e.inherit(e.APOS_STRING_MODE,{begin:/(\bunicode)?'/})}function l(e){
+return e.inherit(e.QUOTE_STRING_MODE,{begin:/(\bunicode)?"/})}var o={
+SOL_ASSEMBLY_KEYWORDS:n,baseAssembly:e=>{
+var a=r(e),o=l(e),c=/[A-Za-z_$][A-Za-z_$0-9.]*/,d=e.inherit(e.TITLE_MODE,{
+begin:/[A-Za-z$_][0-9A-Za-z$_]*/,lexemes:c,keywords:n}),u={className:"params",
+begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,lexemes:c,keywords:n,
+contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,o,s]},_={
+className:"operator",begin:/:=|->/};return{keywords:n,lexemes:c,
+contains:[a,o,i,t,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,s,_,{
+className:"function",lexemes:c,beginKeywords:"function",end:"{",excludeEnd:!0,
+contains:[d,u,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,_]}]}},
+solAposStringMode:r,solQuoteStringMode:l,HEX_APOS_STRING_MODE:i,
+HEX_QUOTE_STRING_MODE:t,SOL_NUMBER:s,isNegativeLookbehindAvailable:e}
+;const{baseAssembly:c,solAposStringMode:d,solQuoteStringMode:u,HEX_APOS_STRING_MODE:_,HEX_QUOTE_STRING_MODE:m,SOL_NUMBER:b,isNegativeLookbehindAvailable:E}=o
+;return e=>{for(var a=d(e),s=u(e),n=[],i=0;i<32;i++)n[i]=i+1
+;var t=n.map((e=>8*e)),r=[];for(i=0;i<=80;i++)r[i]=i
+;var l=n.map((e=>"bytes"+e)).join(" ")+" ",o=t.map((e=>"uint"+e)).join(" ")+" ",g=t.map((e=>"int"+e)).join(" ")+" ",M=[].concat.apply([],t.map((e=>r.map((a=>e+"x"+a))))),p={
+keyword:"var bool string int uint "+g+o+"byte bytes "+l+"fixed ufixed "+M.map((e=>"fixed"+e)).join(" ")+" "+M.map((e=>"ufixed"+e)).join(" ")+" enum struct mapping address new delete if else for while continue break return throw emit try catch revert unchecked _ function modifier event constructor fallback receive error virtual override constant immutable anonymous indexed storage memory calldata external public internal payable pure view private returns import from as using pragma contract interface library is abstract type assembly",
+literal:"true false wei gwei szabo finney ether seconds minutes hours days weeks years",
+built_in:"self this super selfdestruct suicide now msg block tx abi blockhash gasleft assert require Error Panic sha3 sha256 keccak256 ripemd160 ecrecover addmod mulmod log0 log1 log2 log3 log4"
+},O={className:"operator",begin:/[+\-!~*\/%<>&^|=]/
+},C=/[A-Za-z_$][A-Za-z_$0-9]*/,N={className:"params",begin:/\(/,end:/\)/,
+excludeBegin:!0,excludeEnd:!0,lexemes:C,keywords:p,
+contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,s,b,"self"]},f={
+begin:/\.\s*/,end:/[^A-Za-z0-9$_\.]/,excludeBegin:!0,excludeEnd:!0,keywords:{
+built_in:"gas value selector address length push pop send transfer call callcode delegatecall staticcall balance code codehash wrap unwrap name creationCode runtimeCode interfaceId min max"
+},relevance:2},y=e.inherit(e.TITLE_MODE,{begin:/[A-Za-z$_][0-9A-Za-z$_]*/,
+lexemes:C,keywords:p}),w={className:"built_in",
+begin:(E()?"(?<!\\$)\\b":"\\b")+"(gas|value|salt)(?=:)"};function x(e,a){return{
+begin:(E()?"(?<!\\$)\\b":"\\b")+e+"\\.\\s*",end:/[^A-Za-z0-9$_\.]/,
+excludeBegin:!1,excludeEnd:!0,lexemes:C,keywords:{built_in:e+" "+a},
+contains:[f],relevance:10}}var h=c(e),v=e.inherit(h,{
+contains:h.contains.concat([{begin:/\./,end:/[^A-Za-z0-9$.]/,excludeBegin:!0,
+excludeEnd:!0,keywords:{built_in:"slot offset length address selector"},
+relevance:2},{begin:/_/,end:/[^A-Za-z0-9$.]/,excludeBegin:!0,excludeEnd:!0,
+keywords:{built_in:"slot offset"},relevance:2}])});return{aliases:["sol"],
+keywords:p,lexemes:C,
+contains:[a,s,_,m,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,b,w,O,{
+className:"function",lexemes:C,
+beginKeywords:"function modifier event constructor fallback receive error",
+end:/[{;]/,excludeEnd:!0,
+contains:[y,N,w,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE],illegal:/%/
+},x("msg","gas value data sender sig"),x("block","blockhash coinbase difficulty gaslimit basefee number timestamp chainid"),x("tx","gasprice origin"),x("abi","decode encode encodePacked encodeWithSelector encodeWithSignature encodeCall"),x("bytes","concat"),f,{
+className:"class",lexemes:C,beginKeywords:"contract interface library",end:"{",
+excludeEnd:!0,illegal:/[:"\[\]]/,contains:[{beginKeywords:"is",lexemes:C
+},y,N,w,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{lexemes:C,
+beginKeywords:"struct enum",end:"{",excludeEnd:!0,illegal:/[:"\[\]]/,
+contains:[y,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{
+beginKeywords:"import",end:";",lexemes:C,keywords:"import from as",
+contains:[y,a,s,_,m,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,O]},{
+beginKeywords:"using",end:";",lexemes:C,keywords:"using for",
+contains:[y,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,O]},{className:"meta",
+beginKeywords:"pragma",end:";",lexemes:C,keywords:{
+keyword:"pragma solidity experimental abicoder",
+built_in:"ABIEncoderV2 SMTChecker v1 v2"},
+contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,e.inherit(a,{
+className:"meta-string"}),e.inherit(s,{className:"meta-string"})]},{
+beginKeywords:"assembly",end:/\b\B/,
+contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,e.inherit(v,{begin:"{",
+end:"}",endsParent:!0,contains:v.contains.concat([e.inherit(v,{begin:"{",
+end:"}",contains:v.contains.concat(["self"])})])})]}],illegal:/#/}}})());
+
+// Ugly hack to reload HLJS
+hljs.initHighlightingOnLoad();