Yearn V3 totalIdle records unallocated underlying assets in the allocator vault; totalDebt records its strategy allocations after recognized gains and losses. In VaultV3, totalAssets equals their sum. Moving tokens between these categories does not by itself create profit. A strategy report can change the recorded total without returning cash, so check exit limits and actual receipts separately.
Read the totals at the allocator vault
This explanation follows Yearn's multi-strategy VaultV3 v3.1.1, pinned to source commit 89ab996, checked on 28 October 2026. Identify a live vault's chain, address and implementation before applying it. A V3 label alone does not establish that version or configuration.
Yearn separates the allocator vault, the strategies it holds, and optional contracts that manage allocations or assess fees. A TokenizedStrategy is itself a standalone ERC-4626 vault. The official V3 overview describes these layers. A token sitting idle inside a strategy still belongs to the allocator's strategy position; it does not become allocator totalIdle merely because the strategy has cash.
| Field | What it measures | Useful distinction |
|---|---|---|
totalIdle() | Recorded underlying assets held unallocated in the allocator | Different from cash inside a strategy |
totalDebt() | Aggregate recorded value allocated to strategies | Includes recognized gains and losses |
totalAssets() | Idle plus debt in this implementation | An accounting total, not an exit quote |
Strategy current_debt | The allocator's recorded amount for one strategy | Different from that strategy's entire asset pool |
The VaultV3 reference names the first three getters. Their amounts use the underlying asset's units. For a six-decimal asset, 1,000 displayed tokens are 1,000,000,000 base units. Vault shares are another quantity; the ERC-4626 shares and assets guide explains how to keep those units separate.
The accounting identity is totalAssets = totalIdle + totalDebt. Adding the underlying value of strategy shares to totalAssets again would count those positions twice. Likewise, max_debt is an allocation ceiling, not a balance to add to the total.
Separate a debt update from a report
A debt increase sends assets from the allocator into a strategy. A loss-free debt decrease returns assets to the allocator. These movements change where the assets sit. They leave the combined total unchanged when the actual amounts sent and received match the accounting reduction.
The argument to update_debt(strategy, target_debt) is the desired ending debt, rather than the amount to transfer. The vault management guide explains that debt updates also respect the strategy's deposit or redemption limits, its maximum debt and the vault's minimum idle setting. A target therefore needs comparison with the achieved debt.
A report performs a valuation comparison. The allocator reads the strategy shares it owns and converts them into underlying assets using that strategy's convertToAssets. It compares this value with current_debt to recognize a gain or loss. The yield accrual guide explains why a strategy's own report and the allocator's process_report(strategy) are separate accounting steps.
For a Yearn TokenizedStrategy, its own accounting and profit unlocking can affect when its conversion changes. Do not substitute external protocol earnings directly for the value returned by the strategy. The example below instead uses two hypothetical ERC-4626 strategies whose conversions expose the stated values.
Follow 10,000 assets through the ledger
This is an illustrative example, with fictitious underlying token U and six decimals for U and vault shares. One owner deposits 10,000 U into an empty allocator and receives 10,000 shares. Auto-allocation is off. The vault has no accountant, hooks or existing locked profit, and its profit unlock time is zero. Both strategies have sufficient deposit capacity and maximum debt. Strategy and token transfer fees are zero, and all exits shown are loss-free.
The minimum idle setting is 1,000 U. Strategy A receives 6,000 U and B receives 3,000 U. The allocator owns all 6,000 of A's strategy shares, also using six decimals. Later, A's conversion values that position at 6,300 U, or 1.05 U per strategy share. The allocator then processes A's report. All amounts in the table are displayed U, not share quantities or dollar values.
| Completed state | totalIdle | totalDebt | totalAssets |
|---|---|---|---|
| Owner deposits 10,000 | 10,000 | 0 | 10,000 |
| Allocate 6,000 to A | 4,000 | 6,000 | 10,000 |
| Allocate 3,000 to B | 1,000 | 9,000 | 10,000 |
| A's conversion rises; allocator has not reported | 1,000 | 9,000 | 10,000 |
| Allocator processes A's 300 gain | 1,000 | 9,300 | 10,300 |
| Manager returns 800 from B | 1,800 | 8,500 | 10,300 |
| A 2,400 withdrawal reverts | 1,800 | 8,500 | 10,300 |
| A 2,060 withdrawal succeeds | 0 | 8,240 | 8,240 |
The report changes value without returning cash
Before A's allocator report, its current_debt is 6,000 U even though the strategy conversion values the position at 6,300 U. B's debt is 3,000 U. The stored sum remains 1,000 + 6,000 + 3,000 = 10,000 U.
Processing the report recognizes 6,300 − 6,000 = 300 U of gain. A's debt becomes 6,300 U, aggregate debt becomes 9,300 U and total assets become 10,300 U. Idle stays at 1,000 U because this step returns no underlying to the allocator.
The zero unlock time deliberately isolates that asset ledger. A vault with profit locking enabled needs the separate Yearn V3 profit locking and share-price calculation. A 300 U increase in recorded assets alone does not specify the immediate change in each depositor's share conversion.
Returning 800 changes the location
The manager targets 2,200 U of ending debt in B. B returns exactly 800 U from its 3,000 U position. Idle rises to 1,800 U, while B's debt falls to 2,200 U. Together with A's 6,300 U, aggregate debt is now 8,500 U.
The check is 1,800 + 8,500 = 10,300 U. Recording the 800 U return as income would overstate the result. It is a movement of assets already included in the total.
Test liquidity against the intended exit
At this point, suppose A can release only 500 U and B can release nothing further. These are hypothetical strategy limits at the observation state. Both strategies are in the effective withdrawal queue and every permitted redemption returns its stated amount. The only changes during the requests are the modeled withdrawals.
Available assets for a loss-free exit are therefore 1,800 + 500 + 0 = 2,300 U. The owner's accounting claim is 10,300 U, but a 2,400 U withdrawal cannot be completed. The attempted transaction reverts, including intermediate strategy movements. No shares are burned and the receiver receives no U from that failed request. Any network fee needs its own record.
Yearn's integration guide separates conversions from maxWithdraw and maxRedeem, which accept corresponding optional exit parameters. Check the owner, effective strategy list and explicit loss tolerance. In this loss-free example, the owner's withdrawal limit is 2,300 U. Under unrealized losses, the pinned limit calculation can describe a nominal request amount rather than guaranteed net assets received; inspect that branch before turning a limit into a cash estimate.
The owner next withdraws 2,060 U with zero permitted loss. The vault uses its 1,800 U idle and retrieves 260 U from A. A's preview rounds 260 / 1.05 up to 247.619048 strategy shares. Redeeming them and rounding the asset output down to six decimals returns exactly 260.000000 U. A's debt falls from 6,300 to 6,040 U, and B remains at 2,200 U.
The share cost is 2,060 × 10,000 / 10,300 = 2,000 shares. Burning those shares leaves 8,000 shares. The recipient receives 2,060 U and the allocator ends with zero idle. Its remaining assets are 6,040 + 2,200 = 8,240 U.
The whole-period reconciliation also closes: 10,000 + 300 − 2,060 = 8,240 U. Allocations and the B return disappear from this cash-flow equation because they were internal movements. The remaining owner's 8,000 shares represent the remaining 8,240 U accounting claim.
The minimum idle setting did not reserve 1,000 U against that user withdrawal. In the pinned implementation, it constrains debt management; the user exit can consume the idle buffer. If the stated liquidity conditions otherwise persist, A has only 240 U of its initially accessible 500 U left after supplying 260 U.
Reconcile a real observation before explaining the difference
Use one block reference for the reads in a snapshot. Save the implementation, underlying address and decimals alongside the values. Sum debt across every tracked strategy, including funded positions omitted from the current withdrawal queue. Combining yesterday's debt with today's idle can produce a mismatch that never existed onchain.
| Check | Evidence to retain |
|---|---|
| Accounting identity | totalIdle, totalDebt, totalAssets and each strategy's current_debt |
| Report boundary | Strategy share balance, its conversion, last report and recognized gain or loss |
| Asset movement | Before-and-after underlying balances and confirmed deposit, debt-update or withdrawal events |
| Proposed exit | Owner shares, applicable limit, effective queue, loss tolerance and simulation result |
Compare the allocator's raw underlying balanceOf with recorded idle as a separate check. VaultV3 stores idle instead of recomputing it from that token balance on every read. A direct underlying transfer can create a difference; the self-report path, process_report(vault), can account for unrecorded underlying. Preserve the transfer's origin before classifying that adjustment as strategy earnings.
A closed identity shows that the fields agree. It does not independently verify the strategy valuation used in the last report. Inspect that strategy's valuation method and report freshness before treating recorded debt as recoverable assets.
Reports also need their configured fee and refund treatment. An accountant can return fee or refund amounts that affect the report's consequences; the accountant fees versus reported profit guide develops that reconciliation. Removing the accountant in this example is an assumption, not a claim about a production vault.
For an exit, inspect pause status and any withdrawal hook in the selected version, then confirm the transaction's share burn and recipient transfer. The lending receipt-token accounting guide uses the same distinction between a remaining claim and completed receipts.
For this ledger, retain 8,240 U of remaining recorded assets, 2,060 U actually paid, and 240 U still accessible under the stated conditions. Put those amounts in separate fields before interpreting an allocation percentage or planning another exit.