> For the complete documentation index, see [llms.txt](https://docs.usd.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usd.ai/technical-overview/technical-protocol-overview.md). # Technical Protocol Overview ### USDai USDai is an [$PYUSD](https://www.paypal.com/us/digital-wallet/manage-money/crypto/pyusd)-backed stablecoin. It is primarily used as the on and off ramp to Staked USDai (sUSDai), but may offer other incentives in the future. #### Minting KYC'ed institutions can mint USDai by depositing PYUSD. ```solidity /** * @notice Deposit * @param depositAmount Deposit amount * @param recipient Recipient * @return USDai amount */ function deposit( uint256 depositAmount, uint256 usdaiAmountMinimum ) external returns (uint256); ``` ```mermaid sequenceDiagram actor Institution User->>+USDai: Deposit PYUSD USDai->>+User: Mint USDai token ``` #### Burning KYC'ed institutions can burn USDai and withdraw to PYUSD. ```solidity /** * @notice Withdraw * @param usdaiAmount USD amount * @param recipient Recipient * @return Withdraw amount */ function withdraw( uint256 usdaiAmount, address recipient ) external returns (uint256); ``` ```mermaid sequenceDiagram actor Institution User->>+USDai: Burns USDai USDai->>+User: Receives PYUSD ``` ### Staked USDai Staked USDai (sUSDai) is a yield bearing ERC4626 (ERC7540 redeem) vault token that earns yield from USDai PYUSD emissions and [LoanRouter](https://github.com/usdai-foundation/usdai-loan-router-contracts) loans. USDai can be staked for sUSDai, and later redeemed back for USDai. Unlike USDai, sUSDai is not a stablecoin, but is a free floating token, representing shares in an assortment of targeted lending positions and unallocated USDai. #### Staking Users can stake USDai to receive sUSDai at the current deposit share price. Staking is a synchronous ERC4626 deposit operation. ```solidity function deposit(uint256 assets, address receiver) external returns (uint256 shares); function mint(uint256 shares, address receiver) external returns (uint256 assets); ``` ```mermaid sequenceDiagram actor User User->>+sUSDai: Stake USDai (deposit()/mint()) Note right of sUSDai: USDai transferred to sUSDai sUSDai->>+User: Mint sUSDai tokens ``` Overloads for `deposit()` and `mint()` are provided with slippage protections for EOAs. #### Unstaking Users can unstake sUSDai to receive USDai at the current redemption share price. Unstaking is an asynchronous ERC7540 redeem operation. Redemptions are are processed at the end of a fixed time window (e.g. 30 days). ```solidity function requestRedeem(uint256 shares, address controller, address owner) external returns (uint256 requestId); function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets); function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares); ``` ```mermaid sequenceDiagram actor User User->>+sUSDai: Unstake sUSDai (requestRedeem()) Note right of sUSDai: sUSDai burned sUSDai->>+User: Redemption ID ``` #### Position Managers The underlying asset held by the sUSDai vault is USDai, which is harvested for yield and deployed into loans with the help of position managers. The `STRATEGY_ADMIN_ROLE` is required to interact with position managers. Currently, these operations are scheduled offchain and executed by a multisig, but in the future will be governance-driven. The [`BasePositionManager`](https://github.com/usdai-foundation/usdai-contracts/blob/devel/src/positionManagers/BasePositionManager.sol) is responsible for harvesting base yield for the PYUSD held in the USDai contract. PYUSD base yield can be harvested with the `harvestBaseYield()` API: ```solidity /** * @notice Harvest base yield * @return Harvested USDai amount * @return Admin fee */ function harvestBaseYield() external returns (uint256, uint256); ``` ```mermaid sequenceDiagram actor Strategy Strategy->>+sUSDai: Harvest Base Yield sUSDai->>USDai: Harvest USDai->>+Base Yield Escrow: Harvest Base Yield Escrow->>+USDai: PYUSD tokens USDai->>+sUSDai: Mint USDai tokens ``` The [`LoanRouterPositionManager`](https://github.com/usdai-foundation/usdai-contracts/blob/devel/src/positionManagers/LoanRouterPositionManager.sol) is responsible for deploying funds for loans and depositing loan repayments. Loans are funded from deposits in the Deposit Timelock, which are released when a borrower executes a loan. Funds can be deposited into the Deposit Timelock for specific, predetermined loan terms with the `depositLoanTimelock()` API: ```solidity /** * @notice Deposit loan timelock * @param loanTermsHash Loan terms hash * @param usdaiAmount USDai amount * @param expiration Expiration timestamp */ function depositLoanTimelock(bytes32 loanTermsHash, uint256 usdaiAmount, uint64 expiration) external; ``` ```mermaid sequenceDiagram actor Strategy Strategy->>+sUSDai: Deposit Loan Timelock sUSDai->>+Deposit Timelock: USDai tokens ``` In case of loan terms changes or expiration, funds can be withdrawn from the Deposit Timelock with the `cancelLoanTimelock()` API: ```solidity /** * @notice Cancel loan timelock * @param loanTermsHash Loan terms hash */ function cancelLoanTimelock( bytes32 loanTermsHash ) external; ``` ```mermaid sequenceDiagram actor Strategy Strategy->>+sUSDai: Cancel Loan Timelock Deposit Timelock->>+sUSDai: USDai tokens ``` Principal and interest payments are automatically transferred to the sUSDai contract when a borrower makes a loan repayment. These repayments are then redeposited as USDai in the sUSDai contract with the `depositLoanRepayment()` API: ```solidity /** * @notice Deposit loan repayment * @param currencyToken Currency token * @param depositAmount Deposit amount * @param usdaiAmountMinimum Minimum USDai amount * @param data Swap data */ function depositLoanRepayment( address currencyToken, uint256 depositAmount, uint256 usdaiAmountMinimum, bytes calldata data ) external; ``` ```mermaid sequenceDiagram actor Strategy Strategy->>+sUSDai: Deposit Loan Repayment sUSDai->>+External Swap: Swap Repayment for PYUSD (if repayment is not in PYUSD) External Swap->>+sUSDai: PYUSD tokens sUSDai->>+USDai: Deposit PYUSD for USDai USDai->>+sUSDai: USDai tokens ``` #### Share Pricing - Net Asset Value (NAV) The net asset value of sUSDai is the combined value of unallocated USDai and its loan positions. Loan positions are valued conservatively with the remaining balance of the loan, or optimistically with the remaining balance of the loan plus the interest accrued since last repayment. The **deposit share price** is computed from the **optimistic net asset value**, while the **redemption share price** is computed from the **conservative net asset value**. In general, the deposit share price is greater than or equal to the redemption share price. If there are no active loans, they are equal. The remainder of this section describes the optimistic NAV used for our deposit share pricing. In general, our optimistic NAV can be defined by the following: $$ \begin{aligned} S\_t &: \text{USDai total supply} \\ r\_b &: \text{USDai yield rate} \\ P\_{i,u} &: \text{outstanding principal on loan } i \text{ at time } u \\ r\_i &: \text{interest rate on loan } i \\ n &: \text{number of loans} \end{aligned} $$ $$ \mathrm{NAV}*t = \mathrm{NAV}*0 + \underbrace{\int\_0^t \sum*{i=1}^{n} r\_i P*{i,u} , du}*{\text{continuous loan accrual}} + \underbrace{\int\_0^t r\_b S\_u , du}*{\text{continuous USDai yield}} $$ Upon an event of default or similar, the loan in question stops accruing interest. To account for such scenarios, NAV is more precisely defined with a switch: $$ \mathbf{1}{i \text{ live at } u} = \begin{cases} 1 & \text{loan } i \text{ performing} \ 0 & \text{loan } i \text{ in default} \end{cases} $$ $$ \mathrm{NAV}*t = \mathrm{NAV}*0 + \underbrace{\int\_0^t \sum*{i=1}^{n} r\_i P*{i,u} , \mathbf{1}{i \text{ live at } u} , du}*{\text{continuous loan accrual}} + \underbrace{\int\_0^t r\_b S\_u , du}*{\text{continuous USDai yield}} $$ To illustrate the recovery of liquidated assets and the adjustment of the optimistic NAV, we define the following terms: $$ \begin{aligned} \tau &&&: \text{time of default} \\ T &&&: \text{time proceeds are returned to the protocol} \\ V\_j &= P\_{j,\tau} + A\_j(\tau) &&: \text{frozen principal and accrued unpaid interest at default} \\ R\_j &&&: \text{asset sale proceeds} \\ F\_j &&&: \text{warrantied price (based on predefined RVI schedule)} \\ I\_j &&&: \text{insurance payout} \\ \Pi\_j &&&: \text{proceeds returned to the protocol} \end{aligned} $$ Residual value insurance covers the shortfall between the insured value of the collateral and the proceeds realized on its sale. It pays out only when sale proceeds fall below the warrantied value. $$ I\_j = \max\left( F\_j - R\_j, ; 0 \right) $$ {% hint style="info" %} The above assumes full and timely payment on a valid claim. Coverage carve-outs, claim-eligibility conditions, and insurer counterparty risk are not modeled. {% endhint %} Proceeds returned to the protocol are the sum of sale proceeds and any insurance payout, capped at the frozen principal and interest. The protocol is a lender, not an equity holder, it does not capture recovery above the value of its claim. $$ \Pi\_j = \min\left( R\_j + I\_j, ; V\_j \right) = \min\big( \max(R\_j, F\_j), ; V\_j \big) $$ With proceeds returned, NAV is adjusted accordingly. This is the only discrete NAV event in the default lifecycle: $$ \mathrm{NAV}*T = \mathrm{NAV}*{T^-} + \Pi\_j - V\_j $$ Further information about event of default operations can be found in the [Borrower Onchain / Offchain interplay](/borrower/onchain-offchain-interplay.md) section of the docs. No service provider has discretion to increase NAV or allocate additional yield outside the disclosed methodology. #### Redemption Queue Redemptions in sUSDai are managed with a FIFO queue, which are collected throughout and processed at the end of fixed time windows (e.g. 30 days). In the future, the redemption queue will implement a built-in auction to bid on queue position. Redemptions are serviced periodically by the `STRATEGY_ADMIN_ROLE`. When sufficient USDai is available, the strategy calls `serviceRedemptions()` to process redemptions in the queue: ```solidity /** * @notice Service pending redemption requests * @param shares Shares to process * @return Amount processed */ function serviceRedemptions( uint256 shares ) external returns (uint256); ``` #### Depositor NFT Description The Depositor NFT is the onchain instrument through which capital providers access yield from the GPU loan book. Minted at loan closing and deposited into the sUSDai vault, it simultaneously routes cashflows from borrowers to depositors, records the existence and status of a lender's position in the Onchain Register, and reflects the legal participation rights established in the underlying SPV documents. Neither GPU Finance, Permian Labs, nor the USD.AI Foundation has discretion to determine ordinary-course payment allocation or yield distribution outside the applicable contract and protocol rules. The matrix below maps each of these functions explicitly:
NFT FunctionApplicability to Depositor NFTNotes
Routing TokenYesThe Depositor NFT is minted by the Protocol and deposited directly into the sUSDai vault, representing the pro rata claim to loan cashflows. It routes yield from the borrower's onchain wallet through the automated payment waterfall to sUSDai holders — the NFT's presence in the vault is what technically enables the distribution logic to fire.
Evidence of contractual participationYesThe Onchain Record (the authoritative lender register) tracks each lender's share of the loan, principal outstanding, interest accrued, and payment status. The Depositor NFT is the onchain instrument that represents a lender's position in that register. It does not create the contractual right — the executed legal documents and SPV structure do — but it is the tamper-evident, publicly verifiable evidence that a participation exists and is in good standing.
Record of payment rightIndirectThe Depositor NFT sits inside the sUSDai vault, which captures yield (yield on GPU loans plus T-bill yield or PYUSD incentives on idle reserves) and reflects it in the sUSDai exchange rate. The NFT's lifecycle — mint on loan closing, vault-lock on default (unitl sale proceeds compensate the position), nonfucntional artifact when the Agent deposits sale/insurance proceeds — tracks the existence and status of the underlying payment stream. When the NFT is live and unfrozen, the payment right is active. The NFT does not itself confer the right to sue for payment (the legal docs do that), but it is the onchain record that payments are due and flowing.
Transfer InstrumentLimitedThe Depositor NFT is deposited into the sUSDai vault at issuance — it does not circulate freely. What does transfer is sUSDai itself, which is a fungible ERC-20 token that can be held, traded, or composed into other onchain products. So the NFT provides the economic exposure that makes sUSDai transferable, but the NFT itself is vault-locked.
The Depositor NFT is Depositor NFT is not the physical collateral itself, and it does not replace the off-chain loan, lien, SPV, datacenter, pledge, guaranty, or enforcement documents related to the GPU-backed financings ### Omnichain Support USDai and sUSDai support `burn()`/`mint()`-style omnichain token transfers. This interface requires the `BRIDGE_ADMIN_ROLE`, which is granted to the token messaging contract. Support for LayerZero is available with [`OAdapter`](https://github.com/usdai-foundation/usdai-contracts/blob/devel/src/omnichain/OAdapter.sol), which implements the messaging endpoint, and the [`OToken`](https://github.com/usdai-foundation/usdai-contracts/blob/devel/src/omnichain/OToken.sol), which implements an ERC20 of the bridged representation.
### Vault operations execution Certain vault operations may be submitted by authorized execution roles or multisig-controlled wallets for operational security, batching, and transaction-safety purposes. These roles execute predefined smart-contract functions when objective protocol conditions are satisfied. They do not have discretion to select loans, allocate assets outside approved protocol parameters, alter redemption priority, change NAV, redirect ordinary-course payments, or determine yield distributions. Any offchain scheduling process is solely a secure transaction-submission mechanism within disclosed protocol rules. Note: core contracts each have a pause function controlled by a dedicated pause-admin role. It's a safety measure. When it's on, the contract temporarily stops moving value, but all balances stay put and every read function keeps working. In practice that means deposits, withdrawals, redemptions, cross-chain mint and burn, and loan repayments are put on hold. The pause role can only be deployed by the USD.AI Foundation in a few urgent cases, i.e., if there is a suspected bug or signs of an active exploit; if something looks wrong with a system the protocol relies on like a price oracle or a bridge; or if the protocol needs a brief window for an emergency upgrade.\
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.usd.ai/technical-overview/technical-protocol-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.