Integrating with gtUSDa
gtUSDa is the ERC20 for our flagship stablecoin vault on Base which can be integrated into other DeFi applications. Here is a basic integration guide to incorporate gtUSDa into your protocol or app.
All user interactions with the vault happen on Base. We also have a dedicated frontend for supplying into this vault at app.gauntlet.xyz/vaults/gtusda.
Supplying via Contract Calls
Supplying into gtUSDa is a combination of 2 function calls: an approve
call to spend the USDC, and a requestDeposit
call.
call
approve
on the USDC contract to allow the USDC amount to be spent by the provisioner contractNote that this is not the vault contract itself, as the request runs through the provisioner to issue vault units asynchronously via a solving mechanism (see Entry/Exit with Provisioner for more details)
requestDeposit
.requestDeposit
is an asynchronous operation, the user will submit the USDC to the provisioner and after the request is solved gtUSDa units will be sent back to the users wallet directly. This will generally happen within 6 hours though can take up to as long as 3 days (or otherwise based on deadline). See Entry/Exit with Provisioner for more detailstoken:
0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
(USDC contract on base)tokensIn: USDC amount in (decimal adjusted value)
minUnitsOut: This parameter needs to be based on the current price of gtUSDa. To calculate it refer to the PriceAndFeeCalculator contract, specifically the
convertTokensToUnit
function call.convertTokensToUnit(0x000000000001CdB57E58Fa75Fe420a0f4D6640D5, 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913, tokensIn)
-> Returns the decimal adjusted gtUSDa unitsMultiply the above value by 0.97 (some buffer in case there are price changes)
solverTip:
0
deadline:
block.timestamp + 259200
(3 days in seconds)maxPriceAge:
3600
(1 hour in seconds)isFixedPrice:
False
Example Request to deposit 1000 USDC
Call approve
on the Base USDC contract to allow the provisioner to spend
approve(
0x18CF8d963E1a727F9bbF3AEffa0Bd04FB4dBdA07, // Provisioner Contract Address
1000000000 // USDC amount decimal adjusted
)
call requestDeposit
on the provisioner, parameterizing this call is important
requestDeposit(
0x833589fcd6edb6e08f4c7c32d4f71b54bda02913, // USDC Contract on base
1000000000, // USDC amount decimal adjusted
0.97 * convertTokensToUnit(0x000000000001CdB57E58Fa75Fe420a0f4D6640D5, 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913, 1000000000), // minUnitsOut see above for more details
0, // solverTip
block.timestamp + 259200, // deadline: Set to at least 3 days, this is 3 days in seconds
3600, // maxPriceAge: Set to 1 hour, 1 hour in seconds
False // isFixedPrice
)
Withdrawing via contract calls
To withdraw you similarly need to do an approve
call followed by requestRedeem
on the Provisioner Contract with the correct parameters.
call
approve
on the gtUSDa contract to allow the gtUSDa amount to be spent by the provisioner contractrequestRedeem
This is similarly an asynchronous call where the user provides vaultUnits back to the Provisioner contract and after the request is solved the user will receive USDC in their wallettoken:
0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
(USDC contract on base)unitsIn: The amount of vault units you wish to redeem, correctly decimal adjusted. If you want to calculate the
unitsIn
based on the USDC value for the user you can again use theconvertTokenToUnits
function on the PriceAndFeeCalculator contract as per the deposit call.minTokensOut: This parameter needs to be based on the current price of gtUSDa. To calculate it refer to the PriceAndFeeCalculator contract, specifically the
convertUnitsToToken
function.convertUnitsToToken(0x000000000001CdB57E58Fa75Fe420a0f4D6640D5, 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913, unitsIn)
-> Returns the Decimal adjusted USDC value of the VaultUnitsMultiply the above value by 0.97 (some buffer in case there are price changes)
solverTip:
0
deadline:
block.timestamp + 259200
(3 days in seconds)maxPriceAge:
3600
(1 hour in seconds)isFixedPrice:
False
Example Request to withdraw 1000 USDC
call approve
on the gtUSDa contract to allow the provisioner to spend
approve(
0x18CF8d963E1a727F9bbF3AEffa0Bd04FB4dBdA07, // Provisioner Contract Address
convertTokensToUnit(0x000000000001CdB57E58Fa75Fe420a0f4D6640D5, 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913, 1000000000) // gtusda amount decimal adjusted
)
call requestRedeem
on the provisioner, parameterizing this call is important
requestRedeem(
0x833589fcd6edb6e08f4c7c32d4f71b54bda02913, // token: USDC Contract on base
convertTokensToUnit(0x000000000001CdB57E58Fa75Fe420a0f4D6640D5, 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913, 1000000000), // unitsIn: 1000 USDC via the PriceAndFee calculator
0.97* convertUnitsToToken(0x000000000001CdB57E58Fa75Fe420a0f4D6640D5, 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913, unitsIn), // minTokensOut: unitsIn is the previous line response
0, // solverTip
block.timestamp + 259200, // deadline: Set to at least 3 days, this is 3 days in seconds
3600, // maxPriceAge: Set to 1 hour days, this is 1 hour in seconds
False // isFixedPrice
)
[ADVANCED] Monitoring and refunding orders
Tracking orders
When an asynchronous order is placed, the user will have an active but unfilled order. To provide additional transparency to users, these orders can be monitored by tracking the following DepositRequested
or RedeemRequested
events:
/// @notice Emitted when a user creates a deposit request
/// @param user The address requesting the deposit
/// @param token The token being deposited
/// @param tokensIn The amount of tokens to deposit
/// @param minUnitsOut The minimum amount of units expected
/// @param solverTip The tip offered to the solver in deposit token terms
/// @param deadline Timestamp until which the request is valid
/// @param maxPriceAge Maximum age of price data that solver can use
/// @param isFixedPrice Whether the request is a fixed price request
/// @param depositRequestHash The hash of the deposit request
event DepositRequested(
address indexed user,
IERC20 indexed token,
uint256 tokensIn,
uint256 minUnitsOut,
uint256 solverTip,
uint256 deadline,
uint256 maxPriceAge,
bool isFixedPrice,
bytes32 depositRequestHash
);
/// @notice Emitted when a user creates a redeem request
/// @param user The address requesting the redemption
/// @param token The token requested in return for units
/// @param minTokensOut The minimum amount of tokens the user expects to receive
/// @param unitsIn The amount of units being redeemed
/// @param solverTip The tip offered to the solver in redeem token terms
/// @param deadline The timestamp until which this request is valid
/// @param maxPriceAge Maximum age of price data that solver can use
/// @param isFixedPrice Whether the request is a fixed price request
/// @param redeemRequestHash The hash of the redeem request
event RedeemRequested(
address indexed user,
IERC20 indexed token,
uint256 minTokensOut,
uint256 unitsIn,
uint256 solverTip,
uint256 deadline,
uint256 maxPriceAge,
bool isFixedPrice,
bytes32 redeemRequestHash
);
Checking when orders are filled
When a deposit or redeem is filled, one of the following events will be emitted in the Provisioner:
/// @notice Emitted when a deposit request is solved successfully
/// @param depositHash The unique identifier of the deposit request that was solved
event DepositSolved(bytes32 indexed depositHash);
/// @notice Emitted when a redeem request is solved successfully
/// @param redeemHash The unique identifier of the redeem request that was solved
event RedeemSolved(bytes32 indexed redeemHash);
Refunding expired orders
If the deadline passes but an order isn't solved (rare), the user has to claim back their USDC or gtUSDa tokens using the refundRequest
function.
/// @notice Request parameters for deposits and redemptions
/// @dev
/// - For deposits:
/// - units: minimum units the user wants to receive (minUnitsOut)
/// - tokens: amount of tokens the user is providing (tokensIn)
/// - For redemptions:
/// - units: amount of units the user is redeeming (unitsIn)
/// - tokens: minimum tokens the user wants to receive (minTokensOut)
struct Request {
/// @notice Request type(deposit/redeem + auto/fixed price)
RequestType requestType;
/// @notice User address making the request
address user;
/// @notice Amount of vault units
uint256 units;
/// @notice Amount of underlying tokens
uint256 tokens;
/// @notice Tip paid to solver, always in tokens
uint256 solverTip;
/// @notice Timestamp after which request expires
uint256 deadline;
/// @notice Maximum age of price data allowed
uint256 maxPriceAge;
}
/// @notice Refund an expired deposit or redeem request
/// @param token The token involved in the request
/// @param request The request to refund
/// @dev Can only be called after request deadline has passed
function refundRequest(IERC20 token, Request calldata request) external;
Getting the User's balance of gtUSDa
Simply call the balanceOf function on gtUSDa with the user's address.
Pricing gtUSDa units in USDC (and vice versa)
We provide simple price conversion utilities between gtUSDa and USDC via the PriceAndFeeCalculator contract.
Specifically there are two functions of relevance
convertTokensToUnits
-> Takes in USDC value and returns amount of vaultUnits at current pricevault:
0x000000000001CdB57E58Fa75Fe420a0f4D6640D5
(gtUSDa vault contract)token:
0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
(USDC contract on base)tokenAmount: Decimal adjusted USDC value (USDC has 6 decimals)
convertUnitsToTokens
-> Takes in vaultUnits and returns USDC value at current pricevault:
0x000000000001CdB57E58Fa75Fe420a0f4D6640D5
(gtUSDa vault contract)token:
0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
(USDC contract on base)unitsAmount: Decimal adjusted gtUSDa value (gtUSDa has 18 decimals)
Fetching the APY of the vault
This one is a little trickier as of right now, but we aim to make this simpler in the future via an API. As of right now the best way to get the APY of the vault is to index the price of the vault units in USDC over a given time period and extrapolate this to a yearly APY number.
Calculating the TVL of the vault
To get the total TVL of the vault use the convertUnitsToTokens
function and use the totalSupply
of gtUSDa as an input.
Last updated