[Caviarnine Adapter V1]: Initial Readme

radixdlt · Jan 24, 2024 · e6f1cc1 · e6f1cc1
1 parent 381d498
commit e6f1cc1
Show file tree

Hide file tree

Showing 4 changed files with 229 additions and 0 deletions.
diff --git a/diagrams/.$caviarnine.drawio.bkp b/diagrams/.$caviarnine.drawio.bkp
@@ -0,0 +1,94 @@
+<mxfile host="Electron" modified="2024-01-24T12:58:58.461Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/22.1.21 Chrome/120.0.6099.109 Electron/28.1.0 Safari/537.36" version="22.1.21" etag="ziaQ_kFkw1uU1jMveRi5" type="device">
+  <diagram id="pqKDRAmi3_s86vAvQmJZ" name="Basic">
+    <mxGraphModel dx="608" dy="1214" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="3" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="150" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="4" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="100" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="5" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="50" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="7" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="350" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="8" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="300" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="9" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="250" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="10" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="200" y="240" width="20" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="11" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="220" y="240" width="20" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="13" value="" style="endArrow=classic;html=1;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="40" y="480" as="sourcePoint" />
+            <mxPoint x="40" y="200" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="14" value="" style="endArrow=classic;html=1;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="40" y="480" as="sourcePoint" />
+            <mxPoint x="430" y="480" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="15" value="Liquidity Amount" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="10" y="170" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="16" value="Bin" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="430" y="460" width="40" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="17" value="27000" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="30.12" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="18" value="27010" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="80" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="19" value="27020" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="130" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="20" value="27030" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="180.25" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="21" value="27040" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="230" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="22" value="27050" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="280" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="23" value="27060" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="330" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="24" value="" style="endArrow=classic;html=1;fontFamily=Iosevka;exitX=0.5;exitY=1;exitDx=0;exitDy=0;fontColor=#FFFFFF;" parent="1" source="25" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="220" y="190" as="sourcePoint" />
+            <mxPoint x="220" y="230" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="25" value="Current Price" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="190" y="160" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="27" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="40" y="570" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="28" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="40" y="530" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="29" value="Asset X" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="70" y="530" width="60" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="30" value="Asset Y" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="70" y="570" width="60" height="20" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/diagrams/caviarnine-basic.png b/diagrams/caviarnine-basic.png
diff --git a/diagrams/caviarnine.drawio b/diagrams/caviarnine.drawio
@@ -0,0 +1,94 @@
+<mxfile host="Electron" modified="2024-01-24T14:24:19.803Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/22.1.21 Chrome/120.0.6099.109 Electron/28.1.0 Safari/537.36" version="22.1.21" etag="az8l9ohWE7KrqHrO6_Gg" type="device">
+  <diagram id="pqKDRAmi3_s86vAvQmJZ" name="Basic">
+    <mxGraphModel dx="608" dy="1214" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" background="#0D1116" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="3" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="150" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="4" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="100" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="5" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="50" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="7" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="350" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="8" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="300" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="9" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="250" y="240" width="40" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="10" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="200" y="240" width="20" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="11" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="220" y="240" width="20" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="13" value="" style="endArrow=classic;html=1;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="40" y="480" as="sourcePoint" />
+            <mxPoint x="40" y="200" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="14" value="" style="endArrow=classic;html=1;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="40" y="480" as="sourcePoint" />
+            <mxPoint x="430" y="480" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="15" value="Liquidity Amount" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="10" y="170" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="16" value="Bin" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="430" y="460" width="40" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="17" value="27000" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="30.12" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="18" value="27010" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="80" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="19" value="27020" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="130" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="20" value="27030" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="180.25" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="21" value="27040" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="230" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="22" value="27050" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="280" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="23" value="27060" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;rotation=-90;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="330" y="484.88" width="39.75" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="24" value="" style="endArrow=classic;html=1;fontFamily=Iosevka;exitX=0.5;exitY=1;exitDx=0;exitDy=0;fontColor=#FFFFFF;" parent="1" source="25" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="220" y="190" as="sourcePoint" />
+            <mxPoint x="220" y="230" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="25" value="Current Price" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="190" y="160" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="27" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#FFFFFF;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="40" y="570" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="28" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#FFFFFF;strokeColor=#314354;fontFamily=Iosevka;" parent="1" vertex="1">
+          <mxGeometry x="40" y="530" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="29" value="Asset X" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="70" y="530" width="60" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="30" value="Asset Y" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Iosevka;fontColor=#FFFFFF;" parent="1" vertex="1">
+          <mxGeometry x="70" y="570" width="60" height="20" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/packages/caviarnine-adapter-v1/README.md b/packages/caviarnine-adapter-v1/README.md
@@ -0,0 +1,41 @@
+# Caviarnine Adapter
+
+## Calculation of Fees
+
+This section of the document describes how the adapter estimates how much fees have been earned on a liquidity position for the period that it's been opened. There is some amount of knowledge of Caviarnine required to fully understand this calculation which is also described in this section as we go.
+
+First, I will describe some of the basics of Caviarnine that we will build the model on. Caviarnine allows users to concentrate their liquidity in a Uniswap V3 style where users can add liquidity to different bins. A bin is a discrete range in the price range between 0 and infinity. Adding liquidity to a specific bin means that the user's liquidity is only active when the price is inside that bin's range. Once the price exits that of the bin that the user has their assets in then the user stops earning fees. Of course, the user is allowed to add liquidity to multiple different bins so that their liquidity is active in a wider price range.
+
+<p align="center">
+  <img width="500px" src="../../diagrams/caviarnine-basic.png" />
+</p>
+
+The above diagram depicts the liquidity in some pool that is made up of assets X and Y and the various bins that exist in this pool. The x-axis of the diagram is the bin number. The distance between each bin and the other is called the bin span. In this diagram, the bin span is 10 which we can calculate by subtracting the second bin from the first (27010 - 27000). The bin span is the same throughout the pool and could change for different pools.
+
+The spot price can be calculated from the bin number by using the following equation:
+
+$$
+\mathrm{Spot \space Price}(\mathrm{Bin}) = 1.0005 ^ {2\mathrm{Bin} - 54000}
+$$
+
+The first bin in the diagram above is 27000 and the last bin starts at 27060 and ends at 27070. With the equation above this means that the diagram has a price range of:
+
+$$
+\mathrm{Spot \space Price}(27000) = 1.0005 ^ {54000 - 54000} = 1.0005 ^ 0 = 1
+$$
+
+$$
+\mathrm{Spot \space Price}(27070) = 1.0005 ^ {54140 - 54000} = 1.0005 ^ {140} = 1.07248941878
+$$
+
+The y-axis in the diagram represents the amount of liquidity in each of the bins. To simplify things, this diagram assumes that each of the bins contains an equal amount of liquidity, which is of course not realistic but simplifies things.
+
+The bin where the current price of the asset lies is called the _active bin_. Not all bins hold both the X and Y assets:
+
+* The currently active bin is the only bin that holds both X and Y assets.
+* All bins above the active bin hold X assets
+* All bins below the active bin hold Y assets
+
+This is seen in the diagram with the two different colors used for the bins and the active bin (the middle one) being split in half containing both of the colors. 
+
+> This bit is not too relevant to the calculation of fees or anything, but is relevant for the overall understanding of the reader on the Caviarnine system. As you've read above, some of the bins only contain one of the assets and not both. Therefore, unlike Uniswap V2 where the users are obligated to provide two assets of equal value to the pool, the users in this case are not obligated to do that. A user can provide a single side of the liquidity or provide both as they see fit.