> For the complete documentation index, see [llms.txt](https://docs.usegimbal.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usegimbal.app/mechanics/loan-states.md). # Every state a loan can hold The six statuses the desk assigns to a loan, the calls that move a loan between them, and the events that make up its flight log. The desk stores a `LoanStatus` on every loan. Setting aside `None`, which means no such loan, there are six: `Active`, `Refinancing`, `Liquidating`, `Repaid`, `Settled` and `Defaulted`. A loan holds one of them at a time. Every change is made by one transaction and announced by one event, so a loan's full history can be replayed from the chain and nothing else. The Explorer calls that replay the flight log: the events of one loan in order, each pointing at its Blockscout transaction. ## Before there is a loan A borrow request is not yet a loan: it sits in the relayer book as a signed message, with no collateral locked and nothing on the chain. Two things end it without a loan being written: * The fill deadline, the request's launch window, passes. `originate` then rejects it with `RequestExpired`, and offers targeted at its hash are left with nothing to fill. * The borrower calls `cancelRequest`, spending the digest so no relayer can present it later; `RequestCancelled` is emitted. A fill spends the same digest, so a request funds one loan at most. ## The state machine ```mermaid stateDiagram-v2 [*] --> Active : originate() writes the loan Active --> Active : repay() in part, addCollateral() Active --> Repaid : repay() covers the whole debt Active --> Refinancing : openRefinance() before maturity Refinancing --> Active : target funded, clearRefinance() installs the new syndicate Refinancing --> Active : borrower withdraws, cancelRefinance() Refinancing --> Defaulted : window ends short of the target, fail() Defaulted --> Defaulted : repay() in part, addCollateral() Defaulted --> Repaid : repay() covers the whole debt Active --> Liquidating : startAuction(), HF under 1.0 or past maturity plus grace Refinancing --> Liquidating : startAuction(), rollover cancelled first Defaulted --> Liquidating : startAuction(), no health check Liquidating --> Liquidating : buy(), restart() Liquidating --> Settled : target reached or escrow empty, finalizeLiquidation() Repaid --> [*] Settled --> [*] ``` ## What each status means | Status | Repayment | Meaning | | ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Active` | Open | Collateral in escrow, principal with the borrower, every slice accruing. Covers the term, the 24-hour grace window after maturity, and any time beyond it until an auction opens. | | `Refinancing` | Closed | A rollover auction is running; outgoing slices keep accruing until incoming lenders fund the target or the borrower withdraws. | | `Defaulted` | Open | A rollover window closed short of its target and the acceptors were refunded. The one difference from `Active`: a collateral auction may open whatever the health factor. | | `Liquidating` | Closed | A Dutch auction of the collateral is running, or awaiting a restart from a fresh quote. | | `Settled` | Ended | The auction closed and the desk ran the waterfall: keeper share, lender claims, both penalty shares, then surplus and unsold collateral to the borrower. | | `Repaid` | Ended | The debt reached zero, the collateral went back and every slice token was burned. | ### The grace window is not a state Maturity changes nothing in storage. For 24 hours after `maturity` the loan stays `Active` and can be repaid. After that window `startAuction` accepts the loan without a health check, as it does a `Defaulted` one. ## One loan, three endings ```mermaid sequenceDiagram participant Bo as Borrower participant Le as Lenders participant Rel as Relayer participant Desk as TermDesk participant Reg as RoleRegistry participant Sen as PriceSentinel participant Kp as Keeper participant CA as CollateralAuction participant RA as RolloverAuction Bo->>Rel: signed request: 250 NVDA, 20,000 USDG, 9.00% ceiling, 30 days Le->>Rel: signed offers: 5,000 at 8.50%, 10,000 at 8.90%, 5,000 at 9.00% Rel-->>Bo: a syndicate that covers the request Bo->>Desk: originate(request, borrowerSignature, offers, signatures) Desk->>Reg: requireRole(borrower, BORROWER), requireLender(each maker) Desk->>Sen: refresh(NVDA): price, session, staleness Desk->>Desk: authenticate offers, check LTV, book fills, pull USDG, escrow 250 NVDA, mint 3 slices Desk-->>Bo: 20,000 USDG net of the origination fee alt Repayment Bo->>Desk: repay(loanId, amount) Desk-->>Le: per slice: interest less the protocol share, plus principal Desk-->>Bo: collateral out of escrow else Health factor under 1.0 Kp->>CA: startAuction(loanId) CA->>CA: price falls from a 3% premium to the floor over 45 minutes CA->>Desk: finalizeLiquidation(loanId, proceeds, keeper) Desk-->>Le: claims plus the lenders' penalty share Desk-->>Bo: surplus and any unsold collateral else Rollover before maturity Bo->>RA: openRefinance(loanId) RA->>Desk: clearRefinance once acceptances cover debt plus the fee end ``` ## The calls behind the arrows **`originate`** is the sole path by which a loan gets written, and it is all or nothing: every offer must authenticate, every lender's USDG must arrive and the collateral must reach escrow, or the call reverts. [Offers, requests and origination](/mechanics/offers-and-origination.md) sets out the checks in order. **`repay`** is open to anyone while the loan is `Active` or `Defaulted`. Interest is settled before principal and the payment is spread across slices in proportion. The minimum interest period is 3 days; that interest is owed even when the loan closes sooner. A payment reaching the full debt moves the loan to `Repaid`. [Interest, repayment and settlement](/mechanics/interest-and-settlement.md) has the numbers. **`addCollateral`** is open to anyone in every state that accepts repayment, and during a rollover too, so the borrower can lift the health factor first. It is the expected answer to a warning alert, sent when the health factor is under 1.10. The desk emits `CollateralAdded`. **`openRefinance`** lives on `RolloverAuction`; only the borrower may call it, and only while the loan is `Active` and maturity is still ahead. [Maturity, grace and rollover](/mechanics/maturity-and-rollover.md) covers the auction. **`startAuction`** lives on `CollateralAuction` and is permissionless; the caller becomes the keeper. It accepts a loan when the health factor is under 1.0, when the loan is `Defaulted`, or when it is `Active` past maturity plus the grace window. Opened while the equity market is closed, it first carves slices whose lenders opted out of closed-market liquidation into a fresh `Active` loan, reported as `LoanSplit`. [Health factor and auctions](/mechanics/health-and-auctions.md) goes through the sale. ## Reading the flight log Every event above carries the loan id: `LoanOriginated`, `SliceCreated`, `CollateralAdded`, `LoanPartiallyRepaid`, `LoanRepaid`, `RefinanceStarted`, `RefinanceCancelled`, `RefinanceCleared`, `LoanDefaulted`, `LiquidationStarted`, `LoanSplit`, `InKindLiquidation`, `LiquidationFinalized` and `SliceTransferred`. Indexers and keepers follow a loan from its events alone, never reading storage. The Explorer assembles the flight log from them, one entry per event with a link to the transaction on Blockscout. [The contract set](/architecture/contracts.md) lists every event with its parameters. --- # 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.usegimbal.app/mechanics/loan-states.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.