> For the complete documentation index, see [llms.txt](https://docs.creditcoop.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.creditcoop.xyz/developers/architecture-v2.md). # Protocol Architecture (v2) The v2 protocol is two contract suites: **Line-Of-Credit-v2** (the credit facilities) and **Vaults** (pooled lending). All facility contracts are deployed as minimal-proxy clones from factories and initialized atomically via `initializeFromFactory`. ## Line-Of-Credit-v2 ### SecuredLine The deployed facility contract. Inheritance: `SecuredLine is SpigotedLine, EscrowedLine` — which both extend `LineOfCredit` (core lending), which extends `InterestRateCredit`, `MutualConsent`, and `ReentrancyGuard`. * **LineOfCredit** — core facility logic: positions, mutual consent + nonce, borrowing, repayment (FIFO queue), interest accrual, fees, statuses, withdrawal, close. Key state: `borrower`, `admin`, `isServicer` mapping, `otcSwapServicer`, `recoveryEnabled`, `nonce`, `fees`, per-position `Credit` structs keyed by ERC-721 tokenId. * **SpigotedLine** — binds the facility to its Spigot: applying claimed revenue and Reserves to repayment (`useAndRepay`), revenue trading via the configured swap target, and split step-up on default. * **EscrowedLine** — binds the facility to its Escrow: collateral-ratio covenant in `_healthcheck`, and escrow-aware borrower resolution (supports Smart Escrow facilities where the escrow is the borrower of record). * **SecuredLine** additions — `abort()` (mutual consent Admin + borrower, requires `recoveryEnabled`) → ABORTED; escrow/spigot hooks (`clearProposals`, `activateLine`, `incrementNonce`); `revokeConsent` with position-token proposal tracking; OTC price-impact configuration. Statuses: `UNINITIALIZED, ACTIVE, LIQUIDATABLE, REPAID, INSOLVENT, ABORTED`. ### CreditPositionToken (CPT) ERC-721 representing every credit position. Minted only by lines deployed from supported factories. Enforces: no transfer while the position has open proposals; optional transfer restriction with borrower-granted, single-use transfer approvals. Exposes `getPositionInfo` (deposit, principal, interest accrued/repaid, rates, deadline, min cratio) and `getCRatio`. ### Escrow Holds facility collateral. ERC-20 / ERC-4626 collateral with Admin-enabled whitelist (enable-only); Uniswap V3 NFT collateral with pair enabling and a dedicated `univ3Manager` for liquidity management; oracle-based `getCollateralValue` / `getCollateralRatio`; `operate()` calls on Admin-registered contracts with whitelisted selectors; OTC swaps (Admin + counterparty mutual consent, stablecoin whitelist, price-impact cap); liquidation when LIQUIDATABLE; recovery when ABORTED; borrower-updatable minimum collateral ratio only with no open positions (clears proposals, bumps nonce). ### SmartEscrow / LaaSEscrow `SmartEscrow is Escrow` — the escrow acts as the Line's borrower: proxies `addCredit`, `refinanceCredit`, `close`, `depositAndRepay` (open to anyone when LIQUIDATABLE); draws land in the escrow as collateral. `LaaSEscrow is SmartEscrow` — adds pre-configured liquidity-position strategies against a designated pool: `drawDownAndCreateLP`, `drawdownAndIncreaseLiquidity`, `reduceLiquidity`, and Servicer-executed `liquidatePosition`, with a post-drawdown minimum collateral ratio and minimum-collateral-value checks throughout. Strategy/pool configuration is only mutable with no active positions or proposals and always increments the nonce. ### Spigot Escrows and distributes borrower cash flows. Per-revenue-contract `Setting` = `{ownerSplit (≤100), claimFunction, transferOwnerFunction}`. Multi-beneficiary distribution (`DiscreteDistribution`): the Line is the default beneficiary; third-party beneficiaries carry allocations, credit token, pool address, repayment function, and a `getDebtFunc` for live onchain debt reads (overpayment reverts). Revenue conversion via 0x-style swap target (`tradeAndDistribute`, Admin) or OTC swap (OTC Swap Servicer + counterparty consent). Claims: `pullTokens` (Operator/Servicer), `claimOwnerTokens`, `claimOperatorTokens`, `sweepOwnerOperatorTokens` (REPAID + no beneficiary debt). Admin tools: `reassignTokens`, `impairBeneficiaryDebtOwed`, `recoverBeneficiaryTokens`, `recoverSpigotTokens` (ABORTED). Native ETH received is auto-wrapped to WETH. ## Vaults ### LendingVault ERC-4626 + ERC-7540 (+ ERC-7575) vault. Async request lifecycle: `requestDeposit`/`requestRedeem` → operator `process*` (single or batch, with min/max share/asset bounds and available-liquidity checks; fees accrue first) → claim via `deposit`/`mint`/`withdraw`/`redeem` → `cancel*` any time pre-processing. `preview*` functions revert per ERC-7540. `totalAssets = liquid assets (vault + strategies, net of ring-fenced pending deposits and claimable redemption assets) + CreditStrategy.totalActiveCredit()`. Manager moves capital via `depositIntoStrategy`/`withdrawFromStrategy` and can `migrateLiquidStrategy`. Pausable by PAUSER\_ROLE with fee-fair pause/unpause. ### CreditStrategy Holds the vault's CPTs and interacts with lines: `addCredit` / `refinanceCredit` (Manager), `revokeProposal`, `useAndRepay`, `withdrawCredit` (Operators), `swapCreditPositionForTokens` (mutual consent Manager + buyer; buy token must be the vault asset) for secondary sales, `addCreditPosition` callback (line-only) for atomic registration, `sync` to prune transferred positions and accrue fees, and `totalActiveCredit` which excludes positions on INSOLVENT/ABORTED lines — impairment flows to share price automatically. Self-lending reverts. ### LiquidStrategy Idle-capital deployment into owner-approved external ERC-4626 vaults with per-operation slippage minimums (`reallocateFunds`, `migrateFrom4626`); optional Ethena USDe/sUSDe holdings valued by oracle; CoW Protocol integration via relayer approval and order pre-signing/cancellation. ### FeeManager / VaultAdmin / ERC721Manager `FeeManager` — performance fee vs. a high-water-mark share price and pro-rata management fee (365.25-day year), both charged by share inflation; recipient split between Manager and Protocol Treasury per `protocolSplit` (≤100), changeable only by their mutual consent; fee ceilings via `FEE_COEFFICIENT` (10000 bps). `VaultAdmin` — Manager, Operators, Protocol Treasury, and whitelist management. `ERC721Manager` — Manager-gated ERC-721 operations for the vault's position tokens. ## Cross-suite integration When a `CreditStrategy` is the lender on `addCredit`/`increaseCredit`, the Line detects it via ERC-165 (`_tryAddCreditPosition`, with an explicit min-gas guard) and registers the new position in the strategy in the same transaction — vault accounting and facility state can never drift apart at origination. ## Security The v2 contracts have been audited; formal verification work is being completed for the next protocol generation. See [Security Audits](/developers/v1-developer-material/security-audits.md) — this page will be updated with current reports. --- # 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.creditcoop.xyz/developers/architecture-v2.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.