> For the complete documentation index, see [llms.txt](https://docs.hann.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hann.finance/mechanics/deep-dives/yield-bearing-stables.md). # Yield-bearing receipt tokens earnUSDT shares, the wEarnUSDT collateral wrapper, valuation, and USDT withdrawal earnUSDT is a SuperEarn receipt token representing vault shares. Hann Finance wraps these shares as wEarnUSDT for CDP collateral accounting. The shares’ value comes from the assets represented by each share; wrapping changes their token precision. ## The three assets | Asset | What it represents | Role | | --------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- | | USDT | The underlying stablecoin | Deposited into or received from the external SuperEarn system | | earnUSDT | SuperEarn vault shares | The receipt token accepted by the EarnUSDT collateral deposit flow | | wEarnUSDT | Wrapped earnUSDT shares with 18 decimals | Collateral held by the EarnUSDT Trove branch and paid out by its Stability Pool and redemptions | The app uses 6 decimals for earnUSDT deposits and 18 decimals for wEarnUSDT collateral accounting. ```mermaid flowchart LR U[USDT] -->|SuperEarn deposit| E[earnUSDT shares] E -->|Wrap| W[wEarnUSDT] W -->|Deposit collateral| T[Trove] T -->|Recover collateral| W W -->|Unwrap| E E -->|Request redemption and claim| U ``` *Recovering Trove collateral, unwrapping shares, and receiving USDT are separate asset conversions.* ## Share count and value per share A share balance can stay constant while the assets represented by each share change. Let `NAV` be the USDT amount represented by one share: $$ \text{USDTValue} \approx \text{Shares} \times \text{NAV} $$ For 1,000 shares, a NAV change from 1.00 to 1.03 USDT changes the quoted underlying value from 1,000 to 1,030 USDT. The share count remains 1,000. Withdrawal fees, realized losses, and available liquidity affect the amount ultimately received. Receipt-token implementations use their own share conversion methods. Hann Finance’s earnUSDT NAV provider reads `SuperEarnRouter.previewRedeem(earnUSDT, oneShare)` and normalizes the result to 18 decimals. ## Deposit, hold, and recover the assets ### 1. Obtain earnUSDT shares The external SuperEarn router exposes `deposit(earnVault, amount, receiver, minSharesOut)` to deposit USDT and issue shares. Its preview methods quote deposits, mints, and redemptions. The ordinary Hann Finance EarnUSDT collateral deposit accepts **earnUSDT shares**. The token amount in this flow is a share amount. ### 2. Use the shares as collateral EarnUSDTZapper wraps the received earnUSDT into wEarnUSDT before passing it into the Trove. Borrowing USDHN creates a separate debt that accrues interest. The wrapper conversion is fixed by token decimals: $$ \text{WrappedRaw} = \text{EarnRaw} \times 10^{18-d} $$ Here `d` is earnUSDT’s decimals. With 6 decimals, 1 earnUSDT is 1,000,000 raw units and maps to 1,000,000,000,000,000,000 raw wEarnUSDT units. Both represent one share in human-readable units. ### 3. Recover the collateral Closing or reducing a Trove releases collateral according to the loan’s conditions. EarnUSDTZapper unwraps collateral payouts to earnUSDT. The integrated leverage close path pays out its wEarnUSDT or earn vault tokens without starting a SuperEarn USDT redemption. Stability Pool collateral rewards and protocol redemptions pay wEarnUSDT. The wrapper’s `withdraw` or `withdrawTo` converts it back to earnUSDT. Unwrapping rounds down to whole raw earnUSDT units. The sub-unit wEarnUSDT remainder stays in the holder’s balance. `previewWithdraw` returns the burnable wrapped amount, underlying amount, and remainder; `maxWithdrawable` quotes the largest whole-unit unwrap for an account. ### 4. Request and claim USDT SuperEarn’s `redeem(earnVault, shares, receiver, minAssetsOut)` returns a withdrawal request ID. The cooldown vault records the receiver, asset amount, request time, request-specific cooldown period, and claim state. Once the request is ready, `claim(requestId, maxLossBps)` returns the assets. The vault exposes `cooldownPeriod()` and `maxLossThresholdBps()`. Use the request’s recorded period and the allowed loss limit for that claim. A market sale of receipt tokens is a separate exit route. Its proceeds depend on the market’s price and liquidity. ## Protocol collateral price WEarnUSDTPriceFeed reads the NAV through `EarnUSDTNavProviderRouter` and applies a configured valuation haircut. The haircut uses the cooldown vault’s reported shortfall and claim loss relative to its locked and idle assets, with configured multipliers and caps. The normal collateral price is the NAV less the haircut. For redemptions, the feed first rounds NAV upward to a USDT raw-unit step, then applies the haircut. The feed also checks the configured cross-chain keeper’s snapshot age. A stale snapshot causes `SnapshotStale` and reverts the price read. A zero or failed NAV read, or failed haircut-accounting read, triggers branch shutdown and switches the feed to its last good price. ## Market value and collateral ratio A receipt token’s market value also depends on USDT’s dollar price: $$ \text{MarketValue} \approx \text{Shares} \times \text{NAV} \times \text{USDTMarketPrice} $$ For 1,000 shares, NAV of 1.03 USDT, and USDT at $1.00, the market value is $1,030. If USDT trades at $0.97, the same shares have a value of: $$ 1{,}000 \times 1.03 \times 0.97 = 999.1\ \text{USD} $$ These amounts exclude exit fees and price impact. The current wEarnUSDT feed uses NAV and the haircut; it has no separate USDT/USD market-price input. A USDT market-price decline therefore does not automatically enter the displayed collateral ratio through that input. The protocol collateral ratio uses: $$ CR\_{protocol} = \frac{\text{wEarnUSDTAmount} \times \text{PriceFeedValue}}{\text{USDHNDebt}} $$ Share-value changes, losses, haircut changes, and debt interest affect this ratio. Cooldowns and market liquidity affect how and when the collateral can be converted to USDT. ## Before signing Check the deposited token, the share conversion quote, and the asset the transaction will return. For a Trove, also check current debt and collateral ratio. For a USDT withdrawal, check the request’s cooldown and claim-loss settings. Cross-chain asset accounting and the external SuperEarn contracts are part of the receipt token’s dependencies. [Zapper Guide](/protocol/zapper.md) covers collateral conversion routes. [Technical Overview](/developers/technical-overview.md) covers contract roles. [CDP Safety](/mechanics/deep-dives/cdp-safety.md), [Liquidations & Earn](/mechanics/deep-dives/liquidations-and-earn.md), and [Risk Disclosure](/security/risk-disclosure.md) cover position accounting and risks. --- # 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.hann.finance/mechanics/deep-dives/yield-bearing-stables.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.