# imdUSD user documentation, first half

Scope: the overview, borrower and redeemer guides and keeper guides (eleven pages). The sibling job writes `reference/`, `governance/` and `economics/`; links to those pages are relative and will resolve once both halves are merged.

Pages: `overview/what-is-imdusd`, `overview/how-it-holds-a-dollar`, `overview/glossary`, `guides/use-the-terminal`, `guides/open-a-position`, `guides/manage-and-protect-a-position`, `guides/redeem`, `keepers/how-liquidation-works`, `keepers/mark-and-liquidate`, `keepers/relay-oracle-updates`, `keepers/keeper-economics`.

## Sources used

Authority is `src/*.sol`. Read in full or in the relevant part: `CDPVault.sol`, `ParameterizedVault.sol`, `Parameters.sol` (validation and bounds), `SwarmFeed.sol`, `SwarmRelay.sol`, `UsdPriceFeed.sol`, `PriceFeed.sol`, `SpotFeed.sol`, `NhiFeed.sol`, `ImdUSD.sol`, `DeploymentConfig.sol`, parts of `Treasury.sol` and `SwarmWorkOracle.sol`. Supporting: `docs/NAMING.md`, `docs/MAINNET-RUNBOOK.md` (keeper funding), `docs/REDEMPTION-CHECKS.md`, the repository `README.md`, and the terminal source in `web/src/` (`App.tsx`, `Panes.tsx`, `Redemption.tsx`, `actions.tsx`, `math.ts`, `explain.ts`, `state.ts`, `Charts.tsx`). Not read in depth: `docs/ABI.md`, the audit documents, `COMPUTE-BACKING-DESIGN.md`, `Registry.sol`, `SharePriceFeed.sol`. Nothing was executed; no test or build was run, and no contract was called.

The two pinned skill files under `.imd/reads/skills/` concern web UI. Only their writing guidance was applied: consistent vocabulary, link text that names its destination, sentence-case headings, errors paired with a fix.

## Practices adopted

Facts about the sources are stated as read. The mapping below is my reading of them.

- **Four kinds of documentation kept apart** ([Diataxis](https://diataxis.fr/)): explanation (`overview/how-it-holds-a-dollar`), how-to guides (`guides/*`, `keepers/mark-and-liquidate`, `keepers/relay-oracle-updates`), reference (the sibling set, plus the glossary here), and no tutorial. I wrote no tutorial because a tutorial would need a live deployment to follow, which does not exist before launch. Each guide is one task, with prerequisites, numbered steps, and what can block it.
- **Concepts before integration, reference last** ([Aave docs](https://aave.com/docs)): its top level reads "Get familiar", then "Integrate", then quick links for addresses and parameters. Mine runs overview, guides, keepers, then reference and governance.
- **Audience sections and a separate developer summary** ([Liquity docs index](https://docs.liquity.org/llms.txt)): the index separates borrowing, redemptions and staking from a developer README, and lists a risk disclosure. I followed this with `audience` front matter on every page and a risks page in the sibling set.
- **Keeper material as its own section, split into how it works and what to do** ([MakerDAO keeper docs](https://docs.makerdao.com/keepers/the-auctions-of-the-maker-protocol) and the [Dog and Clipper module documentation](https://github.com/sky-ecosystem/mcd-docs-content/blob/master/smart-contract-modules/dog-and-clipper-detailed-documentation.md)). I only saw these as search results, not as opened pages (see Limits).
- **Plain words for actions, identifiers beside them**: the terminal's button labels are the names in prose, and the contract call appears once in code format, for example "Borrow (`draw`)".
- **Every parameter value withheld**: the pages say what each parameter is and how it works, and write "(under consideration)" in place of the value.
- **A visible TODO instead of an invented mechanism**: see below.

## Limits of the research

- The [MakerDAO/Sky documentation portal](https://developers.skyeco.com/) returned HTTP 403 to my fetch tool, so I could not read its layout. What I say about it rests on a search result page and page titles.
- I opened the Liquity index file (`llms.txt`), not the pages behind it. I learned its section names, not its page style. The Liquity landing page itself returned no section list.
- The Aave landing page gave a section list but not page-level structure.
- The whitepaper (https://infer.miyagod.eth.limo) was read only through my fetch tool's summary, not as a full document. Treat the whitepaper disagreements below as likely, not verified.

## Disagreements between code and other documents

The code was followed in each case.

1. **Redemption.** The repository `README.md` says there is no redemption. `CDPVault.cash` implements it, and `docs/NAMING.md` lists it.
2. **What a divergence or stale feed pauses.** `README.md` says a divergence halts minting, marking and liquidation "while still allowing withdrawal". In `CDPVault.free`, withdrawal with debt requires fresh agreeing feeds; only a debt-free withdrawal is always open. `cash` and `earn` (with a finite ceiling) are paused too. `lock` and `wipe` are never paused. The pages follow the code.
3. **Whitepaper redemption.** The whitepaper summary describes a fixed-price redemption from a reserve through a stability module, paid in a stable asset. The code pays IMD at the lesser of $1 and backing per imdUSD, less a fee, from the Treasury's IMD and then from a named candidate position.
4. **Whitepaper liquidation and collateral.** The summary gives fixed liquidation thresholds and a multi-day notice in an emergency. The code derives `mat` and the grace `lull` continuously from the network health index; grace is shorter, not longer, when health is low. The summary also describes reputation-backed positions with a loan-to-value cap; no such position type exists in `src/` (`Registry.sol` is not read by anything).
5. **Whitepaper oracle.** The summary describes an hourly series averaged over many attestations, with a fallback grace using the last valid average. The code stores one attested window price per accepted attestation, guarded by panel floors, question binding, replay, freshness and a deviation bound. When a feed is stale, price actions revert with `StaleFeed`; there is no fallback.
6. **`DeploymentConfig.sol` comments.** The `DUTY_BPS` comment says the fee ships at zero and accrues "from deployment"; the constant is nonzero and `chi()` accrues from the last checkpoint (`indexCheckpointAt`). The `CDPVault` contract header refers to "NHI alone" and "no parameter admin", true of the base vault but not of `ParameterizedVault`, which reads its parameters from the governed `Parameters`.
7. **`UsdPriceFeed.ethUsdPrice` comment** says the vault reads it to convert the reserve; the current `ParameterizedVault.reserveValue` does not (it is already in dollars).
8. **The terminal (`web/`)** was built against the earlier names. Its labels and calls still use the retired stablecoin name, `minCR`, `mintCOMP`, `repayCOMP`, `depositCollateral`, `withdrawCollateral`, `redeem`, `markUnderwater`, `liquidate`, `clearRecoveredMark`, `mintFromWork`, and its action buttons read "Review ...". `docs/NAMING.md` says it will be renamed with the next deployment. The pages use the plain labels named in the assignment (Deposit, Withdraw, Borrow, Repay, Redeem, Mark, Liquidate, Clear mark, Mint from work) with the identifiers from source. If the terminal ships unchanged, the guide's figure names (for example "Backing per imdUSD", "required ratio") will differ from the screen.
9. **Terminal features with no counterpart in the sources:** a test-IMD faucet, a reporter-fallback tool and a faucet work-credit mode. `SwarmFeed` states that no reporter fallback exists. These are omitted from the guides.
10. **Network-specific values in `DeploymentConfig.sol`** (the pinned relayer, the ETH/USD aggregator, the work-oracle factory placeholder) are constants that have to be set for the launch chain before deployment (`docs/MAINNET-RUNBOOK.md`). The pages assume the feeds pin the launch `SwarmRelay`. I could not verify that, because it is not in the source.

## TODOs left

- `keepers/relay-oracle-updates.md`: one `TODO(oracle-funding)`, covering how attestations are purchased on chain through an Intake contract and funded from treasury assets.
- `keepers/keeper-economics.md`: two `TODO(oracle-funding)` lines, covering who pays for attestations and whether relayers are reimbursed.
- Every contract address is "(waiting for mainnet launch)". The links into `reference/`, `governance/` and `economics/` depend on the sibling job.

## What is fact, inference and unknown

- **Fact (from source, cited in each page's `sources`):** function behaviour, revert conditions, event names, the order of the feed checks, the redemption payout formula, the three-way split of the bonus, the marker rule in `bite` and the `relayAndBite` token flow.
- **Inference:** that redemption pushes the market price up when it is below the redemption price (no code enforces a price); that a keeper's net profit depends on gas and inventory; the reading of the web terminal's behaviour from its source without running it.
- **Not verified:** the terminal's rendered text (no browser was run); the final values of every economic parameter; the funding mechanism for oracle updates; whether feeds at launch will pin the launch relay.
- **Unanswered:** whether a chip credited to the relay contract could ever be recovered (the source says no, and I wrote that); whether the split of the bonus leaves smaller positions worth liquidating.