Vault: totalIdle, totalDebt, and Donation Defense

What You Are Building

Section 4 introduced _totalAssets() as totalIdle + totalDebt without much explanation. This section adds the public totalAssets(), the ERC-4626-compatible aliases (convertToAssets, convertToShares), and maxAvailableShares. The actual code is short. The reason this is a dedicated section is the donation attack: why the vault must NOT trust token.balanceOf(this) and how the explicit totalIdle accumulator is the structural defense.

If you only remember one thing from this section, remember the invariant: token.balanceOf(this) >= totalIdle. Anything in excess of that inequality is donated underlying that no depositor has a claim on.