https://docs.convex.world/assets/js/dc3cf873.cf4f33c4.js

1"use strict";(globalThis.webpackChunkconvex_docs=globalThis.webpackChunkconvex_docs||[]).push([[1734],{7028:(e,n,t)=>{t.d(n,{R:()=>a,x:()=>o});var i=t(758);const s={},r=i.createContext(s);function a(e){const n=i.useContext(r);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:a(e.components),i.createElement(r.Provider,{value:n},e.children)}},7077:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>d,contentTitle:()=>o,default:()=>u,frontMatter:()=>a,metadata:()=>i,toc:()=>l});const i=JSON.parse('{"id":"cad/torus/index","title":"CAD030: Torus DEX","description":"Torus is a decentralised exchange (DEX) built on Convex. It is an open source actor that operates by facilitating smart contract interactions between:","source":"@site/docs/cad/030_torus/index.md","sourceDirName":"cad/030_torus","slug":"/cad/torus/","permalink":"/docs/cad/torus/","draft":false,"unlisted":false,"editUrl":"https://github.com/Convex-Dev/design/tree/develop/docs/cad/030_torus/index.md","tags":[],"version":"current","frontMatter":{},"sidebar":"cadsSidebar","previous":{"title":"CAD029: Fungible Token Standard","permalink":"/docs/cad/fungible/"},"next":{"title":"CAD031: NFT Metadata","permalink":"/docs/cad/nft_metadata/"}}');var s=t(6070),r=t(7028);const a={},o="CAD030: Torus DEX",d={},l=[{value:"Specification",id:"specification",level:2},{value:"Torus actor",id:"torus-actor",level:3},{value:"Markets",id:"markets",level:3},{value:"Trades",id:"trades",level:3},{value:"Liquidity Pool",id:"liquidity-pool",level:3},{value:"Adding and withdrawing liquidity",id:"adding-and-withdrawing-liquidity",level:3},{value:"Torus Market SPI",id:"torus-market-spi",level:3}];function c(e){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",ul:"ul",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"cad030-torus-dex",children:"CAD030: Torus DEX"})}),"\n",(0,s.jsx)(n.p,{children:"Torus is a decentralised exchange (DEX) built on Convex. It is an open source actor that operates by facilitating smart contract interactions between:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Liquidity providers, who earn commission on trades"}),"\n",(0,s.jsx)(n.li,{children:"Traders who wish to swap fungible tokens"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"specification",children:"Specification"}),"\n",(0,s.jsx)(n.h3,{id:"torus-actor",children:"Torus actor"}),"\n",(0,s.jsx)(n.p,{children:"The Torus actor manages all Torus DEX markets and provides user functionality."}),"\n",(0,s.jsx)(n.p,{children:"Users typically import the Torus actor as a library to make Torus functions available in their environment:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-clojure",children:"(import exchange.torus :as torus)\n"})}),"\n",(0,s.jsx)(n.h3,{id:"markets",children:"Markets"}),"\n",(0,s.jsx)(n.p,{children:"Torus maintains a market for each fungible token that users wish to exchange."}),"\n",(0,s.jsx)(n.p,{children:"Markets are created on demand when the first user requests creation:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-clojure",children:"(torus/create-market token-id)\n=> #678\n"})}),"\n",(0,s.jsx)(n.p,{children:"A new market is a deployed actor that implements the Torus market SPI. Initially the market will have zero liquidity (this may be added by liquidity providers later)."}),"\n",(0,s.jsx)(n.p,{children:"If a second user requests creation of a market after it is already created, the original market is returned and no new market is deployed."}),"\n",(0,s.jsxs)(n.p,{children:["Subsequently, the address of a market can be accessed with the ",(0,s.jsx)(n.code,{children:"get-market"})," function:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-clojure",children:"(torus/get-market token-id)\n=> #678\n"})}),"\n",(0,s.jsxs)(n.p,{children:["If no market exists for a fungible asset, ",(0,s.jsx)(n.code,{children:"get-market"})," returns ",(0,s.jsx)(n.code,{children:"nil"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"trades",children:"Trades"}),"\n",(0,s.jsx)(n.p,{children:"Any user may trade on a Torus market."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-clojure",children:";; Assume a CAD token identified by TOKEN\n\n;; Buy a 100 token quantity of a token\n(torus/buy-tokens TOKEN 100)\n\n;; Sell 100 tokens\n(torus/sell-tokens TOKEN 100)\n\n;; Buy 1000 CVM using the token\n(torus/buy-cvx TOKEN 1000)\n\n;; Sell 1000 CVM, receiving the token\n(torus/sell-cvx TOKEN 1000)\n"})}),"\n",(0,s.jsx)(n.p,{children:"It is also possible to do swaps between any two tokens. These are atomic swaps that execute a Torus trade on both underlying markets."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-clojure",children:";; Assume we have a second token named USD\n\n;; Buy 200 TOKEN using USD\n(torus/buy TOKEN 200 USD)\n\n;; Sell 300 TOKEN and receive USD\n(torus/sell TOKEN 300 USD)\n\n"})}),"\n",(0,s.jsx)(n.p,{children:"Trades will fail if any of the following are true:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"An attempt is made to buy or sell a negative quantity"}),"\n",(0,s.jsx)(n.li,{children:"The liquidity pool has insufficient liquidity to complete the trade"}),"\n",(0,s.jsx)(n.li,{children:"The user has insufficient funds (CVM or token) to complete the trade"}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"liquidity-pool",children:"Liquidity Pool"}),"\n",(0,s.jsx)(n.p,{children:"Each Torus market holds a liquidity pool of two assets:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Convex Coins"}),"\n",(0,s.jsx)(n.li,{children:"The CAD29 fungible token that the market represents"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Each active Torus market MUST have a positive Convex Coins in the liquidity pool."}),"\n",(0,s.jsx)(n.p,{children:"Each active Torus market MUST own a positive balance of the CAD29 fungible token being traded."}),"\n",(0,s.jsx)(n.p,{children:"The Torus market assumes the two asset quantities have equal value."}),"\n",(0,s.jsx)(n.p,{children:"We use Convex Coins as the common pairing for each fungible token because:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"This enables swaps between any two CAD29 tokens with just two swaps, avoiding the need to create a market for every possible fungible token pair."}),"\n",(0,s.jsx)(n.li,{children:"Convex Coins generally make sense to hold as a common asset for ecosystem participants"}),"\n",(0,s.jsx)(n.li,{children:"It provides an additional opportunity to earn a return on Convex Coins"}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"adding-and-withdrawing-liquidity",children:"Adding and withdrawing liquidity"}),"\n",(0,s.jsxs)(n.p,{children:["A prospective liquidity provide MAY add liquidity to a market at any time with the ",(0,s.jsx)(n.code,{children:"torus/add-liquidity"})," function."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-clojure",children:";; Add initial liquidity with Convex quantity\n;; This is necessary for the initial liquidity provided\n(torus/add-liquidity token-id token-quantity convex-quantity)\n\n;; Add liquidity with token quantity only \n;; (will infer Convex quantity from current price)\n(torus/add-liquidity token-id token-quantity)\n"})}),"\n",(0,s.jsxs)(n.p,{children:["If successful, ",(0,s.jsx)(n.code,{children:"add-liquidity"})," will return an integer equal to the number of liquidity shares gained by the liquidity provider."]}),"\n",(0,s.jsx)(n.p,{children:"The attempt to add liquidity will fail if the user has insufficient Convex coins or tokens to provide the liquidity."}),"\n",(0,s.jsxs)(n.p,{children:["If the market does not already exist, one will be created as if ",(0,s.jsx)(n.code,{children:"create-market"})," was used."]}),"\n",(0,s.jsx)(n.h3,{id:"torus-market-spi",children:"Torus Market SPI"}

1),"\n",(0,s.jsxs)(n.p,{children:["The Torus market SPI is usually not directly accessed by users: Torus functionality should be accessed by the ",(0,s.jsx)(n.code,{children:"exchange.torus"})," library."]}),"\n",(0,s.jsx)(n.p,{children:"A Torus market MUST implement a CAD29 fungible token SPI so that its liquidity share function as a fungible token."}),"\n",(0,s.jsx)(n.p,{children:"The Torus market SPI MAY change due to updates of Torus"})]})}function u(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(c,{...e})}):c(e)}}}]);