An overview of the contract that implements the BitFlow StableSwap, which features a liquidity pool comprising of USDA and sUSDT.
This contract is designed to administer the USDA-sUSDT liquidity pool for the BitFlow StableSwap. It enables users to execute transactions, such as swapping USDA for sUSDT and vice versa, as well as providing or removing liquidity.
Data Storage
These structures are used to enable the contract to maintain its state, track information, and ensure data integrity.
A data variable that holds the swap fees (inclusive of both fees for liquidity providers and the protocol), denominated in bps. Please note that 1 bps is equivalent to 0.01%.
liquidity-fees
(define-data-var liquidity-fees uint u3)
A data variable that holds the fee levied by the protocol as a liquidity fee, measured in bps. Please note that 1 bps is equivalent to 0.01%.
helper-principal
(define-data-var helper-principal principal tx-sender)
A data variable that represents an address with privileges to add or remove administrators from this contract's administrator list.
A map that holds data for each cycle related to all pairs for this contract's liquidity pool.
Error Codes
These error codes are displayed when there's a problem executing any of the functions defined in this smart contract.
err-no-pair-data
This error code indicates that the contract could not retrieve data for the requested token pair.
err-pair-not-approved
This error code indicates that the specified token pair has not been granted the necessary approval or permissions to proceed with the action.
err-x-amount-too-high
This error code indicates that the specified amount for token X exceeds the allowed or available limit.
err-min-y-amount
This error code indicates that the provided amount for token Y is below the minimum acceptable threshold.
err-transferring-token-x
This error code indicates that there was an issue while attempting to transfer token X.
err-transferring-token-x-fee
This error code indicates that an issue arose while trying to deduct the fee from token X.
err-transferring-token-x-fee-protocol
This error code indicates that an issue occurred while trying to transfer the protocol fee taken from token X.
err-transferring-token-y
This error code indicates that there was an issue while attempting to transfer token Y.
err-y-amount-too-high
This error code indicates that the specified amount for token Y exceeds the allowed or available limit.
err-min-x-amount
This error code indicates that the provided amount for token X is below the minimum acceptable threshold.
err-transferring-token-y-swap-fee
This error code indicates that an issue arose while trying to transfer the swap fee deducted from token Y.
err-transferring-token-y-protocol-fee
This error code indicates that an issue occurred while trying to transfer the protocol fee taken from token Y.
err-x-or-y-amount-added-zero
This error code indicates that the amount of token X or Y being added is zero.
err-d2-less-than-d0
This error code indicates that the derived value d2 is less than the initial value d0.
err-derived-amount-less-than-lp
This error code indicates that the derived amount is smaller than the liquidity pool's requirements.
err-transferring-token-x-escrow
This error code indicates that there was an issue while attempting to transfer token X to the escrow.
err-transferring-token-x-protocol
This error code indicates that an issue occurred during the transfer of token X to the protocol.
err-transferring-token-y-protocol
This error code indicates that an issue occurred during the transfer of token Y to the protocol.
err-minting-lp-tokens
This error code indicates that there was a problem while minting liquidity pool tokens.
err-withdrawal-balance-x-less-than-min-x-amount
This error code indicates that the amount of token X received after withdrawal is less than the minimum amount.
err-withdrawal-balance-y-less-than-min-y-amount
This error code indicates that the amount of token Y received after withdrawal is less than the minimum amount.
This error code indicates that there was a problem while burning liquidity pool tokens.
err-getting-x-decimals
This error code indicates that there was an issue while getting decimals for token X.
err-getting-y-decimals
This error code indicates that there was an issue while getting decimals for token Y.
err-not-admin
This error code indicates that the contract caller is not an authorized administrator.
err-pair-xy-or-yx-exists
This error code indicates that the specified XY or YX pair already exists for this contract's liquidity pool.
err-initial-bal-zero
This error code indicates that the initial balance is zero.
err-initial-bal-odd
This error code indiciates that the initial balance is an odd number.
err-already-admin
This error code indicates that the specified principal is already an authorized administrator.
err-admin-overflow
This error code indicates that the number of administrators has exceeded the contract's maximum allowable limit.
err-not-auth
This error code indicates that a specified principal is not authorized to perform a specified action.
err-not-whitelisted
This error code indicates that a specified principal is not whitelisted for a specified action.
Public Functions
These functions can be accessed by external contracts or users, allowing for interaction with the contract and modification of its state.
swap-x-for-y
(define-public (swap-x-for-y (x-token <og-sip-010-trait>) (y-token <susdt-sip-010-trait>) (lp-token <lp-trait>) (x-amount uint) (min-y-amount uint))
(let
(
(swapper tx-sender)
(pair-data (unwrap! (map-get? PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)}) (err "err-no-pair-data")))
(current-approval (get approval pair-data))
(current-balance-x (get balance-x pair-data))
(current-balance-y (get balance-y pair-data))
(x-decimals (get x-decimals pair-data))
(y-decimals (get y-decimals pair-data))
(swap-fee-lps (get lps (var-get swap-fees)))
(swap-fee-protocol (get protocol (var-get swap-fees)))
(total-swap-fee (+ swap-fee-lps swap-fee-protocol))
;; Scale up balances and the swap amount to perform AMM calculations with get-y
(scaled-up-balances (get-scaled-up-token-amounts current-balance-x current-balance-y x-decimals y-decimals))
(current-balance-x-scaled (get scaled-x scaled-up-balances))
(current-balance-y-scaled (get scaled-y scaled-up-balances))
(scaled-up-swap-amount (get-scaled-up-token-amounts x-amount u0 x-decimals y-decimals))
(x-amount-scaled (get scaled-x scaled-up-swap-amount))
(x-amount-fees-lps-scaled (/ (* x-amount-scaled swap-fee-lps) u10000))
(x-amount-fees-protocol-scaled (/ (* x-amount-scaled swap-fee-protocol) u10000))
(updated-x-amount-scaled (- x-amount-scaled (+ x-amount-fees-lps-scaled x-amount-fees-protocol-scaled)))
(updated-x-balance-scaled (+ current-balance-x-scaled updated-x-amount-scaled))
(new-y-scaled (get-y updated-x-balance-scaled current-balance-y-scaled updated-x-amount-scaled (* (get amplification-coefficient pair-data) number-of-tokens)))
;; Scale down to precise amounts for y and dy, as well as x-amount-fee-lps, and x-amount-fee-protocol
(new-y (get scaled-y (get-scaled-down-token-amounts u0 new-y-scaled x-decimals y-decimals)))
(dy (- current-balance-y new-y))
(x-amount-fee-lps (get scaled-x (get-scaled-down-token-amounts x-amount-fees-lps-scaled u0 x-decimals y-decimals)))
(x-amount-fee-protocol (get scaled-x (get-scaled-down-token-amounts x-amount-fees-protocol-scaled u0 x-decimals y-decimals)))
(updated-x-amount (- x-amount (+ x-amount-fee-lps x-amount-fee-protocol)))
(updated-x-balance (+ current-balance-x updated-x-amount))
)
;; Assert that pair is approved
(asserts! current-approval (err "err-pair-not-approved"))
;; Assert that x-amount is less than x10 of current-balance-x
(asserts! (< x-amount (* u10 current-balance-x)) (err "err-x-amount-too-high"))
;; Assert that dy is greater than min-y-amount
(asserts! (> dy min-y-amount) (err "err-min-y-amount"))
;; Transfer updated-x-balance tokens from tx-sender to this contract
(if (> updated-x-amount u0)
(unwrap! (contract-call? x-token transfer updated-x-amount swapper (as-contract tx-sender) none) (err "err-transferring-token-x"))
false
)
;; Transfer x-amount-fee-lps tokens from tx-sender to staking-and-rewards-contract
(if (> x-amount-fee-lps u0)
(unwrap! (contract-call? x-token transfer x-amount-fee-lps swapper (var-get staking-and-rewards-contract) none) (err "err-transferring-token-x-fee"))
false
)
;; Transfer x-amount-fee-protocol tokens from tx-sender to protocol-address
(if (> x-amount-fee-protocol u0)
(unwrap! (contract-call? x-token transfer x-amount-fee-protocol swapper protocol-address none) (err "err-transferring-token-x-fee-protocol"))
false
)
;; Transfer dy tokens from this contract to tx-sender
(if (> dy u0)
(unwrap! (as-contract (contract-call? y-token transfer dy tx-sender swapper none)) (err "err-transferring-token-y"))
false
)
;; Update all appropriate maps
;; Update PairsDataMap
(map-set PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)} (merge
pair-data
{
balance-x: updated-x-balance,
balance-y: new-y,
d: (get-D updated-x-balance-scaled new-y-scaled (* (get amplification-coefficient pair-data) number-of-tokens))
}
))
;; Match if map-get? returns some for CycleDataMap
(ok (match (map-get? CycleDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token), cycle-num: (get-current-cycle)})
cycle-data
;; Update CycleDataMap
(map-set CycleDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token), cycle-num: (get-current-cycle)} (merge
cycle-data
{
cycle-fee-balance-x: (+ (get cycle-fee-balance-x cycle-data) x-amount-fee-lps)
}
))
;; Create new CycleDataMap
(map-set CycleDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token), cycle-num: (get-current-cycle)} {
cycle-fee-balance-x: x-amount-fee-lps,
cycle-fee-balance-y: u0,
})
))
)
)
Parameter
Type
x-token
og-sip-010-trait
y-token
susdt-sip-010-trait
lp-token
lp-trait
x-amount
uint
min-y-amount
uint
A public function that facilitates the token swapping process by allowing a user to exchange token x (denoted as x-token) for token y (denoted as y-token), within the confines of the stipulated liquidity pool (represented by lp-token).
swap-y-for-x
(define-public (swap-y-for-x (y-token <susdt-sip-010-trait>) (x-token <og-sip-010-trait>) (lp-token <lp-trait>) (y-amount uint) (min-x-amount uint))
(let
(
(swapper tx-sender)
(pair-data (unwrap! (map-get? PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)}) (err "err-no-pair-data")))
(current-approval (get approval pair-data))
(current-balance-x (get balance-x pair-data))
(current-balance-y (get balance-y pair-data))
(x-decimals (get x-decimals pair-data))
(y-decimals (get y-decimals pair-data))
(swap-fee-lps (get lps (var-get swap-fees)))
(swap-fee-protocol (get protocol (var-get swap-fees)))
(total-swap-fee (+ swap-fee-lps swap-fee-protocol))
;; Scale up balances and the swap amount to perform AMM calculations with get-x
(scaled-up-balances (get-scaled-up-token-amounts current-balance-x current-balance-y x-decimals y-decimals))
(current-balance-x-scaled (get scaled-x scaled-up-balances))
(current-balance-y-scaled (get scaled-y scaled-up-balances))
(scaled-up-swap-amount (get-scaled-up-token-amounts u0 y-amount x-decimals y-decimals))
(y-amount-scaled (get scaled-y scaled-up-swap-amount))
(y-amount-fees-lps-scaled (/ (* y-amount-scaled swap-fee-lps) u10000))
(y-amount-fees-protocol-scaled (/ (* y-amount-scaled swap-fee-protocol) u10000))
(updated-y-amount-scaled (- y-amount-scaled (+ y-amount-fees-lps-scaled y-amount-fees-protocol-scaled)))
(updated-y-balance-scaled (+ current-balance-y-scaled updated-y-amount-scaled))
(new-x-scaled (get-x updated-y-balance-scaled current-balance-x-scaled updated-y-amount-scaled (* (get amplification-coefficient pair-data) number-of-tokens)))
;; Scale down to precise amounts for y and dy, as well as y-amount-fee-lps, and y-amount-fee-protocol
(new-x (get scaled-x (get-scaled-down-token-amounts new-x-scaled u0 x-decimals y-decimals)))
(dx (- current-balance-x new-x))
(y-amount-fee-lps (get scaled-y (get-scaled-down-token-amounts u0 y-amount-fees-lps-scaled x-decimals y-decimals)))
(y-amount-fee-protocol (get scaled-y (get-scaled-down-token-amounts u0 y-amount-fees-protocol-scaled x-decimals y-decimals)))
(updated-y-amount (- y-amount (+ y-amount-fee-lps y-amount-fee-protocol)))
(updated-y-balance (+ current-balance-y updated-y-amount))
)
;; Assert that pair is approved
(asserts! current-approval (err "err-pair-not-approved"))
;; Assert that y-amount is less than x10 of current-balance-y
(asserts! (< y-amount (* u10 current-balance-y)) (err "err-y-amount-too-high"))
;; Assert that dx is greater than min-x-amount
(asserts! (> dx min-x-amount) (err "err-min-x-amount"))
;; Transfer updated-y-balance tokens from tx-sender to this contract
(if (> updated-y-amount u0)
(unwrap! (contract-call? y-token transfer updated-y-amount swapper (as-contract tx-sender) none) (err "err-transferring-token-y"))
false
)
;; Transfer y-amount-fee-lps tokens from tx-sender to staking-and-rewards-contract
(if (> y-amount-fee-lps u0)
(unwrap! (contract-call? y-token transfer y-amount-fee-lps swapper (var-get staking-and-rewards-contract) none) (err "err-transferring-token-y-swap-fee"))
false
)
;; Transfer y-amount-fee-protocol tokens from tx-sender to protocol-address
(if (> y-amount-fee-protocol u0)
(unwrap! (contract-call? y-token transfer y-amount-fee-protocol swapper protocol-address none) (err "err-transferring-token-y-protocol-fee"))
false
)
;; Transfer dx tokens from this contract to tx-sender
(if (> dx u0)
(unwrap! (as-contract (contract-call? x-token transfer dx tx-sender swapper none)) (err "err-transferring-token-x"))
false
)
;; Update all appropriate maps
;; Update PairsDataMap
(map-set PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)} (merge
pair-data
{
balance-x: new-x,
balance-y: updated-y-balance,
d: (get-D new-x-scaled updated-y-balance-scaled (* (get amplification-coefficient pair-data) number-of-tokens))
}
))
;; Match if map-get? returns some for CycleDataMap
(ok (match (map-get? CycleDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token), cycle-num: (get-current-cycle)})
cycle-data
;; Update CycleDataMap
(map-set CycleDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token), cycle-num: (get-current-cycle)} (merge
cycle-data
{
cycle-fee-balance-y: (+ (get cycle-fee-balance-y cycle-data) y-amount-fee-lps)
}
))
;; Create new CycleDataMap
(map-set CycleDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token), cycle-num: (get-current-cycle)} {
cycle-fee-balance-x: u0,
cycle-fee-balance-y: y-amount-fee-lps,
})
))
)
)
Parameter
Type
y-token
susdt-sip-010-trait
x-token
og-sip-010-trait
lp-token
lp-trait
y-amount
uint
min-x-amount
uint
A public function that is similar to the swap-x-for-y function but facilitates the reverse operation: a user swaps token y (denoted as y-token) for token x (denoted as x-token), within the specified liquidity pool (lp-token).
A public function that allows a user (liquidity provider) to add liquidity to a specified token pair. Liquidity is added in terms of two tokens (x-token and y-token), and in return, the user receives LP tokens (lp-token) proportional to the amount of liquidity added and the current state of the liquidity pool.
withdraw-liquidity
(define-public (withdraw-liquidity (x-token <og-sip-010-trait>) (y-token <susdt-sip-010-trait>) (lp-token <lp-trait>) (lp-amount uint) (min-x-amount uint) (min-y-amount uint))
(let
(
;; Grabbing all data from PairsDataMap
(current-pair (unwrap! (map-get? PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)}) (err "err-no-pair-data")))
(current-approval (get approval current-pair))
(x-decimals (get x-decimals current-pair))
(y-decimals (get y-decimals current-pair))
(current-balance-x (get balance-x current-pair))
(current-balance-y (get balance-y current-pair))
(current-total-shares (get total-shares current-pair))
(current-amplification-coefficient (get amplification-coefficient current-pair))
(withdrawal-balance-x (/ (* current-balance-x lp-amount) current-total-shares))
(withdrawal-balance-y (/ (* current-balance-y lp-amount) current-total-shares))
(new-balance-x (- current-balance-x withdrawal-balance-x))
(new-balance-y (- current-balance-y withdrawal-balance-y))
(liquidity-remover tx-sender)
;; get-D using the new-balance-x and new-balance-y
(new-balances-scaled (get-scaled-up-token-amounts new-balance-x new-balance-y x-decimals y-decimals))
(new-balance-x-scaled (get scaled-x new-balances-scaled))
(new-balance-y-scaled (get scaled-y new-balances-scaled))
(new-d (get-D new-balance-x-scaled new-balance-y-scaled current-amplification-coefficient))
)
;; Assert that withdrawal-balance-x is greater than min-x-amount
(asserts! (> withdrawal-balance-x min-x-amount) (err "err-withdrawal-balance-x-less-than-min-x-amount"))
;; Assert that withdrawal-balance-y is greater than min-y-amount
(asserts! (> withdrawal-balance-y min-y-amount) (err "err-withdrawal-balance-y-less-than-min-y-amount"))
;; Burn LP tokens from tx-sender
(unwrap! (contract-call? lp-token burn liquidity-remover lp-amount) (err "err-burning-lp-tokens"))
;; Transfer withdrawal-balance-x tokens from this contract to liquidity-taker
(unwrap! (as-contract (contract-call? x-token transfer withdrawal-balance-x tx-sender liquidity-remover none)) (err "err-transferring-token-x"))
;; Transfer withdrawal-balance-y tokens from this contract to liquidity-taker
(unwrap! (as-contract (contract-call? y-token transfer withdrawal-balance-y tx-sender liquidity-remover none)) (err "err-transferring-token-y"))
;; Update all appropriate maps
;; Update PairsDataMap
(ok (map-set PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)} (merge
current-pair
{
balance-x: new-balance-x,
balance-y: new-balance-y,
total-shares: (- current-total-shares lp-amount),
d: new-d
}
)))
)
)
Parameter
Type
x-token
og-sip-010-trait
y-token
susdt-sip-010-trait
lp-token
lp-trait
lp-amount
uint
min-x-amount
uint
min-y-amount
uint
A public function that allows users to withdraw liquidity from a pair specified by x-token, y-token, and lp-token. It deducts the LP tokens and ensures that the amount withdrawn respects the user-defined minimums for each token (min-x-amount and min-y-amount).
create-pair
(define-public (create-pair (x-token <og-sip-010-trait>) (y-token <susdt-sip-010-trait>) (lp-token <lp-trait>) (amplification-coefficient uint) (pair-name (string-ascii 32)) (initial-x-bal uint) (initial-y-bal uint))
(let
(
(lp-owner tx-sender)
(x-decimals (unwrap! (contract-call? x-token get-decimals) (err "err-getting-x-decimals")))
(y-decimals (unwrap! (contract-call? y-token get-decimals) (err "err-getting-y-decimals")))
(scaled-up-balances (get-scaled-up-token-amounts initial-x-bal initial-y-bal x-decimals y-decimals))
(initial-x-bal-scaled (get scaled-x scaled-up-balances))
(initial-y-bal-scaled (get scaled-y scaled-up-balances))
)
;; Assert that tx-sender is an admin using is-some & index-of with the admins var
(asserts! (is-some (index-of (var-get admins) tx-sender )) (err "err-not-admin"))
;; Assert using and that the pair does not already exist using is-none & map-get?
(asserts! (and
(is-none (map-get? PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)}))
(is-none (map-get? PairsDataMap {x-token: (contract-of y-token), y-token: (contract-of x-token), lp-token: (contract-of lp-token)}))
) (err "err-pair-xy-or-yx-exists"))
;; Assert that both initial balances are greater than 0
(asserts! (or (> initial-x-bal u0) (> initial-y-bal u0)) (err "err-initial-bal-zero"))
;; Assert that x & y tokens are the same
(asserts! (is-eq initial-x-bal-scaled initial-y-bal-scaled) (err "err-initial-bal-odd"))
;; Mint LP tokens to tx-sender
(unwrap! (as-contract (contract-call? lp-token mint lp-owner (+ initial-x-bal-scaled initial-y-bal-scaled))) (err "err-minting-lp-tokens"))
;; Transfer token x liquidity to this contract
(unwrap! (contract-call? x-token transfer initial-x-bal tx-sender (as-contract tx-sender) none) (err "err-transferring-token-x"))
;; Transfer token y liquidity to this contract
(unwrap! (contract-call? y-token transfer initial-y-bal tx-sender (as-contract tx-sender) none) (err "err-transferring-token-y"))
;; Update all appropriate maps
(ok (map-set PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)} {
approval: true,
total-shares: (+ initial-x-bal-scaled initial-y-bal-scaled),
x-decimals: x-decimals,
y-decimals: y-decimals,
balance-x: initial-x-bal,
balance-y: initial-y-bal,
d: (+ initial-x-bal-scaled initial-y-bal-scaled),
amplification-coefficient: amplification-coefficient,
}))
)
)
Parameter
Type
x-token
og-sip-010-trait
y-token
susdt-sip-010-trait
lp-token
lp-trait
amplification-coefficient
uint
pair-name
string-ascii 32
initial-x-bal
uint
initial-y-bal
uint
A public function that allows an admin to create a new liquidity pair between x-token and y-token with a corresponding LP token, lp-token. The pair is also initialized with an amplification coefficient, a descriptive name (pair-name), and initial token balances (initial-x-bal and initial-y-bal).
set-pair-approval
(define-public (set-pair-approval (x-token <og-sip-010-trait>) (y-token <susdt-sip-010-trait>) (lp-token <lp-trait>) (approval bool))
(let
(
(current-pair (unwrap! (map-get? PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)}) (err "err-no-pair-data")))
)
;; Assert that tx-sender is an admin using is-some & index-of with the admins var
(asserts! (is-some (index-of (var-get admins) tx-sender)) (err "err-not-admin"))
;; Update all appropriate maps
(ok (map-set PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)} (merge
current-pair
{
approval: approval
}
)))
)
)
Parameter
Type
x-token
og-sip-010-trait
y-token
susdt-sip-010-trait
lp-token
lp-trait
approval
bool
A public function that allows the modification of a token pair's approval status. Given specific tokens x-token, y-token, and lp-token, and the desired approval status, this function updates the token pair's approval in the PairsDataMap. To invoke this function, the transaction sender must be an approved administrator.
add-admin
(define-public (add-admin (admin principal))
(let
(
(current-admins (var-get admins))
;;(new-admins (unwrap! (as-max-len? (append current-admins admin) u5) ("err-add-admin-overflow")))
)
;; Assert that tx-sender is an admin using is-some & index-of with the admins var
(asserts! (is-some (index-of current-admins tx-sender)) (err "err-not-admin"))
;; Assert that admin is not already an admin using is-none & index-of with the admins var
(asserts! (is-none (index-of current-admins admin)) (err "err-already-admin"))
;; Update all appropriate maps
(ok (var-set admins (unwrap! (as-max-len? (append current-admins admin) u5) (err "err-admin-overflow"))))
)
)
Parameter
Type
admin
principal
A public function that enables the addition of a new administrator to the list of approved administrators. The provided principal, admin, will be appended to the current list of administrators, but only if the invoking transaction sender is already an approved administrator.
remove-admin
(define-public (remove-admin (admin principal))
(let
(
(current-admin-list (var-get admins))
(caller-principal-position-in-list (index-of current-admin-list tx-sender))
(removeable-principal-position-in-list (index-of current-admin-list admin))
)
;; asserts tx-sender is an existing whitelist address
(asserts! (is-some caller-principal-position-in-list) (err "err-not-auth"))
;; asserts param principal (removeable whitelist) already exist
(asserts! (is-eq removeable-principal-position-in-list) (err "err-not-whitelisted"))
;; temporary var set to help remove param principal
(var-set helper-principal admin)
;; filter existing whitelist address
(ok
(var-set admins (filter is-not-removeable current-admin-list))
)
)
)
Parameter
Type
admin
principal
A public function that facilitates the removal of an administrator from the list of approved administrators. The provided principal, admin, will be removed from the list. The invoking transaction sender must be an approved administrator to execute this function.
change-swap-fee
(define-public (change-swap-fee (new-lps-fee uint) (new-protocol-fee uint))
(let
(
(current-admins (var-get admins))
)
;; Assert that tx-sender is an admin using is-some & index-of with the admins var
(asserts! (is-some (index-of current-admins tx-sender)) (err "err-not-admin"))
(ok (var-set swap-fees {lps: new-lps-fee, protocol: new-protocol-fee}))
)
)
Parameter
Type
new-lps-fee
uint
new-protocol-fee
uint
A public function that allows an approved administrator to modify the swap fee structure. It updates both the liquidity provider's fee (new-lps-fee) and the protocol fee (new-protocol-fee). To invoke this function, the transaction sender must be an approved administrator.
change-liquidity-fee
(define-public (change-liquidity-fee (new-liquidity-fee uint))
(let
(
(current-admins (var-get admins))
)
;; Assert that tx-sender is an admin using is-some & index-of with the admins var
(asserts! (is-some (index-of current-admins tx-sender)) (err "err-not-admin"))
(ok (var-set liquidity-fees new-liquidity-fee))
)
)
Parameter
Type
Description
new-liquidity-fee
uint
A public function that enables an approved administrator to adjust the liquidity fee. The new liquidity fee is set using the new-liquidity-fee parameter. To invoke this function, the transaction sender must be an approved administrator.
change-amplification-coefficient
(define-public (change-amplification-coefficient (x-token <og-sip-010-trait>) (y-token <susdt-sip-010-trait>) (lp-token <lp-trait>) (amplification-coefficient uint))
(let
(
(current-pair (unwrap! (map-get? PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)}) (err "err-no-pair-data")))
(current-admins (var-get admins))
)
;; Assert that tx-sender is an admin using is-some & index-of with the admins var
(asserts! (is-some (index-of current-admins tx-sender)) (err "err-not-admin"))
;; Update all appropriate maps
(ok (map-set PairsDataMap {x-token: (contract-of x-token), y-token: (contract-of y-token), lp-token: (contract-of lp-token)} (merge
current-pair
{
amplification-coefficient: amplification-coefficient
}
)))
)
)
Parameter
Type
x-token
og-sip-010-trait
y-token
susdt-sip-010-trait
lp-token
lp-trait
amplification-coefficient
uint
A public function that permits an approved administrator to alter the amplification coefficient of a specified token pair (x-token, y-token, and lp-token). After determining the token pair in the PairsDataMap, the function updates the amplification coefficient value to the given amplification-coefficient. The invoking transaction sender must be an approved administrator to execute this function.
set-staking-contract
(define-public (set-staking-contract (staking-contract principal))
(let
(
(current-admins (var-get admins))
)
;; Assert that tx-sender is an admin using is-some & index-of with the admins var
(asserts! (is-some (index-of current-admins tx-sender)) (err "err-not-admin"))
;; Set contract for handling staking and rewards
(ok (var-set staking-and-rewards-contract staking-contract))
)
)
Parameter
Type
staking-contract
principal
A public function that allows an approved administrator to set or change the contract responsible for handling staking and rewards. The new contract is identified by the staking-contract principal. The invoking transaction sender must be an approved administrator to execute this function.
Private Functions
These functions are confined to the contract in which they are defined, ensuring encapsulation and restricting external access to certain functionalities.
A private function that processes iterative calculations related to an x variable in a loop until a convergence condition is met. It updates the value of x based on certain arithmetic operations and checks if the new value has converged to a threshold. If the convergence condition is met, it stops further iterations for x.
A private function that operates similarly to the x-for-loop, but for the variable y. It iteratively updates the value of y based on certain arithmetic calculations, and checks if the new value meets a convergence threshold. If the convergence condition is satisfied, it halts further iterations for y.
D-for-loop
(define-private (D-for-loop (n uint) (D-info {D: uint, x-bal: uint, y-bal: uint, ann: uint, converged: uint}))
(let
(
;; Grabbing everything from D-info
(current-D-partial (get D D-info))
(current-D (get D D-info))
(current-x-bal (get x-bal D-info))
(current-y-bal (get y-bal D-info))
(current-S (+ current-x-bal current-y-bal))
(current-ann (get ann D-info))
(current-converged (get converged D-info))
;; Start logic for calculating new D
;; Calculate new partial D with respect to x
(new-D-partial-x (/ (* current-D current-D-partial) (* u2 current-x-bal)))
;; Calculate new partial D with respect to now x & y
(new-D-partial (/ (* current-D new-D-partial-x ) (* u2 current-y-bal)))
(new-numerator (* (+ (* current-ann current-S) (* number-of-tokens new-D-partial)) current-D))
(new-denominator (+ (* (- current-ann u1) current-D) (* (+ number-of-tokens u1 ) new-D-partial)))
(new-D (/ new-numerator new-denominator))
)
;; Check if converged value / new D was already found
(if (is-eq current-converged u0)
(if (> new-D current-D)
(if (<= (- new-D current-D) convergence-threshold)
{D: new-D, x-bal: current-x-bal, y-bal: current-y-bal, ann: current-ann, converged: new-D}
{D: new-D, x-bal: current-x-bal, y-bal: current-y-bal, ann: current-ann, converged: u0}
)
(if (<= (- current-D new-D) convergence-threshold)
{D: new-D, x-bal: current-x-bal, y-bal: current-y-bal, ann: current-ann, converged: new-D}
{D: new-D, x-bal: current-x-bal, y-bal: current-y-bal, ann: current-ann, converged: u0}
)
)
D-info
)
)
)
Parameter
Type
n
uint
D-info
map
A private function tasked with iterative calculations related to the variable D. It calculates a new value for D based on specific logic using the values of x-bal, y-bal, and ann. The function then determines if the newly calculated D value has reached the desired convergence threshold.
get-scaled-up-token-amounts
(define-private (get-scaled-up-token-amounts (x-amount-unscaled uint) (y-amount-unscaled uint) (x-num-decimals uint) (y-num-decimals uint))
(let
(
(scaled-x
;; if same number of decimals, set to x-amount-unscaled
(if (is-eq x-num-decimals y-num-decimals)
x-amount-unscaled
;; if x has more decimals, set to x-amount-unscaled; otherwise scale up by the difference in decimals
(if (> x-num-decimals y-num-decimals) x-amount-unscaled (* x-amount-unscaled (pow u10 (- y-num-decimals x-num-decimals))))
)
)
(scaled-y
;; if same number of decimals, set to y-amount-unscaled
(if (is-eq x-num-decimals y-num-decimals)
y-amount-unscaled
;; if y has more decimals, set to y-amount-unscaled; otherwise scale up by the difference in decimals
(if (> y-num-decimals x-num-decimals) y-amount-unscaled (* y-amount-unscaled (pow u10 (- x-num-decimals y-num-decimals))))
)
)
)
{scaled-x: scaled-x, scaled-y: scaled-y}
)
)
Parameter
Type
x-amount-upscaled
uint
y-amount-upscaled
uint
x-num-decimals
uint
y-num-decimals
uint
A private function that is designed to scale up token amounts based on the difference in decimal precision between two tokens, x and y. It ensures that both x and y amounts are represented with the same scale. If the two tokens have the same number of decimals, no scaling is applied.
get-scaled-down-token-amounts
(define-private (get-scaled-down-token-amounts (x-amount-scaled uint) (y-amount-scaled uint) (x-num-decimals uint) (y-num-decimals uint))
(let
(
(scaled-x
;; if same number of decimals, set to x-amount-scaled
(if (is-eq x-num-decimals y-num-decimals)
x-amount-scaled
;; if x has more decimals, set to x-amount-scaled; otherwise scale down by the difference in decimals
(if (> x-num-decimals y-num-decimals) x-amount-scaled (/ x-amount-scaled (pow u10 (- y-num-decimals x-num-decimals))))
)
)
(scaled-y
;; if same number of decimals, set to y-amount-scaled
(if (is-eq x-num-decimals y-num-decimals)
y-amount-scaled
;; if y has more decimals, set to y-amount-scaled; otherwise scale down by the difference in decimals
(if (> y-num-decimals x-num-decimals) y-amount-scaled (/ y-amount-scaled (pow u10 (- x-num-decimals y-num-decimals))))
)
)
)
{scaled-x: scaled-x, scaled-y: scaled-y}
)
)
Parameter
Type
x-amount-scaled
uint
y-amount-scaled
uint
x-num-decimals
uint
y-num-decimals
uint
A private function designed to scale down token amounts based on the difference in decimal precision between two tokens, x and y. If the two tokens have the same decimal precision, no changes are made to their values. Otherwise, adjustments are made to align them to the same scale.
A private function that checks if a given admin principal is removable. It returns true if the admin principal is different from the stored helper-principal, suggesting the admin is not removable, and false otherwise.
Read-only Functions
These functions are read-only and are utilized for querying or retrieving data. While they can be invoked by external contracts or users, they do not alter the underlying state of the contract.
A read-only function that retrieves data associated with a pair in the contract's liquidity pool. It uses the provided x-token, y-token, and lp-token as parameters to pinpoint the relevant pair data.
A read-only function designed to fetch data for a given cycle. It uses the x-token, y-token, lp-token, and cycle-num parameters to extract the relevant cycle's data.
A read-only function tasked with determining and returning the current cycle number based on the difference between the current block height and the contract's deployment height, adjusted by the cycle length.
A read-only function that computes and provides the cycle corresponding to a designated block height. The function uses the specified height parameter to determine the cycle by considering the height difference from the contract's deployment and adjusting with the cycle length.
A read-only function that calculates the block height where a particular cycle started. It calculates this using the specified cycle parameter, accounting for the deployment height and the cumulative length of the cycles.
A read-only function that calculates the quantity of x-token that one would receive in exchange for a specified amount of y-token (considering fees). It takes into account the current liquidity pool's balance and swap fees, scales up amounts for precise AMM calculations, and scales down to get the final dx amount that a user would receive post-swap.
A read-only function that iteratively determines the amount of x-token corresponding to a given amount of y-token, adjusted for the amplification coefficient. The function takes in balances, a swap amount, and the amplification coefficient to compute the adjusted x-token amount.
A read-only function that calculates the quantity of y-token one would receive when swapping a specified quantity of x-token. Similar to get-dx, it scales amounts, factors in the current liquidity pool balance and swap fees, and then scales down to determine the final dy amount that a user would get post-swap.
A read-only function designed to calculate the amount of y-token equivalent to a specific amount of x-token, considering the amplification coefficient. This function utilizes the existing balances, an amount to be swapped, and the amplification coefficient to calculate the resultant y-token quantity.
A read-only function that computes the invariant D using an iterative process. The function takes in the current balances of x-token and y-token as well as the amplification coefficient. The result is used to maintain the relative values of tokens in the pool and ensure low slippage between stablecoins.
