[mikemaccana]

Merge order: this PR must merge after the companion PR quicknode/solana-program-examples#144. That PR makes the vault strategy record what it holds and price shares from those records, ignoring donations. Every identifier and number below describes what it ships, so merging this first would have the book describing a defense the companion had not shipped.

An earlier version of this PR described virtual shares. The companion switched to ignoring donations, which is simpler for this vault and keeps the one-to-one first deposit and every existing number, so this version replaces it.

What changed

• Vault Strategy chapter
  • The account model names usdc_holdings and asset_holdings.
  • The deposit values the fund from those records rather than vault balances. It records what each swap moved, and refuses a swap that returns nothing (DepositTooSmall).
  • Withdrawal legs and the math section use the recorded holdings. The invariants gain one: prices and payouts come from the records, which never exceed the vault balances.
  • The failure mode "The first deposit has no dead-shares guard" becomes two bullets:
    • Donations are ignored, run against the Adversary chapter's numbers: the next depositor's 1,000 USDC still buys 1,000 shares, and the donation is never paid out. rebalance cannot sell or spend donated tokens (InsufficientHoldings).
    • A deposit too small to buy anything is refused. minimum_shares remains for a share price that moved between signing and landing. The pointer to the Adversary chapter's empty-pool section stays.
  • The testing section names the four new or extended tests, and the summary bullet says to value what the program recorded.
• Adversary chapter, "The Empty Pool"
  • The walkthrough's bare pool is "priced from the token balance in its vault, as the book's vault strategy did before it chose a defense".
  • The minimum_shares paragraph says the vault strategy keeps the argument without relying on it.
  • The "Ignore donations" bullet names the vault strategy's recorded holdings next to the lending market's available_liquidity, and points at test_donation_does_not_inflate_share_price.
  • The closing line names the defense each of the book's programs chose.
• Perpetual Futures chapter: the cross-reference that called the vault strategy's guard "missing" now says the Vault Strategy chapter ignores donations instead.
• WRITING-PLAN.md, War Story Register: the Vault Strategy chapter teaches ignoring donations.
• Figures: none changed. No vault figure draws a vault balance feeding the valuation, and the deposit figure's "900 USDC in, 900 shares out" still holds.

I grepped for one-to-one, dead-shares, virtual and missing guard. The remaining hits are the bare pool in the Adversary walkthrough, the vault's still-one-to-one first deposit, the AMM's and lending's own mechanisms, and the virtual-shares bullet describing that general defense. No line says the vault's first deposit is unguarded.

Relation to other PRs

• The Adversary edits sit on #94 (the numbered inflation-attack walkthrough), which is still open. This branch is Walk the inflation attack through with numbers, and rewrite the Adversary chapter in plain language #94's current head, which already merges main, plus one commit. If Walk the inflation attack through with numbers, and rewrite the Adversary chapter in plain language #94 merges first, this diff shrinks to that one commit.
• #95 rewrote the dead-shares bullet to describe the undefended behavior. It was closed without merging; this PR's bullets supersede it.

Verification

• npm run lint clean.
• node scripts/check-figure-geometry.mjs clean.
• npm run build-pdf wrote the book, 260 pages.
• Every identifier the new prose names resolves in the companion PR: usdc_holdings, asset_holdings, DepositTooSmall, InsufficientHoldings, minimum_shares, and the four test names.

🤖 Generated with Claude Code

https://claude.ai/code/session_012jbHknFnC6NKkeWvgvziB1