> For the complete documentation index, see [llms.txt](https://docs.hoard.world/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hoard.world/protocol/architecture.md). # Architecture Every contract lives in one repository and is exercised against a real in-repo Uniswap v4 PoolManager in the Foundry suite. ## The contracts | Contract | What it does | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **HoardToken** | The 2,222-unit ERC20, a thin subclass of the audited DN404. Exact transfers, no tax, no admin balance control. | | **HoardlingMirror** | The ERC721 side of DN404: one Hoardling per whole unit held. | | **HoardFeeHook** | The Uniswap v4 hook on the canonical pool: 3% USDG fee on every swap shape, zero native LP fee enforced, oracle recorded on every swap, fee exemption keyed to the LiquidationRouter only. | | **HoardOracle** | Price from the pool's own observations. Borrow price is the lowest of spot, 30-minute TWAP and 4-hour TWAP; liquidation price is the lower of the 5-minute and 30-minute TWAPs. | | **Nest** | Escrow for nested Hoardlings. Records who deposited what, binds a Hoardling to its owner's loan account for the 65% tier, blocks unnesting while boosted debt is above the 45% limit. | | **StockVault** | Receives the vault share of fees and interest, keeps the per-Hoardling reward index, batch-buys SPY through a pluggable purchaser, pays claims pro-rata to executed conversions, asks the EligibilityGate first. | | **V4SpyPurchaser** | The vault's SPY route: an exact-input USDG to SPY swap through a Uniswap v4 pool with a minimum-out bound. Holds nothing between calls. | | **EligibilityGate** | The claim allowlist: attestors write it, the owner names attestors. Moves no funds. | | **USDGWallManager** | Holds the wall's one-sided positions in the PoolManager: USDG below the market, HOARD recovery liquidity above it after a downturn. Permissionless `rebalance()` and `deployIdle()`. | | **LenderVault** | The single lender pool on OpenZeppelin's ERC4626: automatic cap, interest routing, seven-day reward drip, the launch HOARD stream, pro-rata write-downs. | | **LoanController** and **LoanAccount** | One controller-owned account per borrower holds pledged HOARD and the bound Hoardling, enforces the 45%/65% limits, accrues interest through a global borrow index. | | **JumpRateModelV2** | Compound's audited rate model, vendored: the 40% / 70% at 80% / 120% curve. | | **LiquidationRouter** | Atomic, permissionless, sized liquidation: seize, sell fee-exempt through the canonical pool, pay the incentive, repay the pool, return surplus. | | **LiquidityLock** | The seed liquidity position with a forward-only unlock date and a one-way permanent lock. | | **TeamVesting** | OpenZeppelin VestingWallet with nine monthly tranches. | | **TimelockController** | OpenZeppelin's timelock holding the 8% rewards reserve behind a six-hour delay. | ## Foundations Custom code exists only where no audited equivalent does: the borrow index, the hook's fee capture, the wall's positions, the oracle's gating, the Hoardling bind, and liquidation routing. Everything else is DN404, Solady, OpenZeppelin (ERC4626, VestingWallet, TimelockController, Ownable2Step, SafeERC20, ReentrancyGuard) and Compound's rate model. ## The keeper A scheduled round every ten minutes, each step guarded by what the contracts report: rebalance and deploy the wall when eligible, batch-buy SPY when the vault holds enough unconverted USDG, warn when the oracle's last observation is a day old, and warn when spot and the 30-minute TWAP diverge by more than 15%. A round with nothing to do costs no gas. Every one of these calls is also open to anyone. ## The app A painted world rendered in PixiJS with the real pages inside each building's dialogue window. Reads are independent, so one reverting call degrades the display with a notice instead of hiding it; writes are simulated before the wallet opens, so a refusal comes back with its reason. --- # 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.hoard.world/protocol/architecture.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.