> For the complete documentation index, see [llms.txt](https://docs.usefarlight.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usefarlight.com/protocol/loan-lifecycle.md). # Loan states and the flight log Each state a loan can be in, the single transaction that moves it to the next one, and the flight log of events that records the whole path. At any given moment a Farlight loan is in exactly one of a small number of states. Moving from one state to another always takes a single on-chain transaction, and that transaction always emits an event. The consequence is that the whole history of a loan can be rebuilt from chain data alone. That history is the loan's flight log: the ordered event record of one loan, with every entry linked to its transaction on Blockscout. ## State machine ```mermaid stateDiagram-v2 [*] --> Requested : borrower publishes request (off-chain) Requested --> Active : originate() Requested --> Expired : fill deadline passes Active --> Repaid : repay() clears the full balance Active --> Active : partial repayment, collateral top-up, slice added Active --> Refinancing : openRefinance() Refinancing --> Active : bid accepted, syndicate replaced Refinancing --> Defaulted : cap reached with no bid Active --> Liquidating : HF under 1.0, startAuction() Active --> Grace : maturity timestamp reached Grace --> Repaid : repay() before the window closes Grace --> Defaulted : window closes unpaid Defaulted --> Liquidating : startAuction() Liquidating --> Settled : auction clears Repaid --> [*] Settled --> [*] Expired --> [*] ``` ## The states | State | Meaning | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Requested** | Only the relayer book knows about the request. Nothing has been sent on-chain and no assets are locked. | | **Active** | The collateral is in escrow, the borrower has the principal, and each slice is accruing interest every second. | | **Refinancing** | The borrower has opened a rising-rate auction before maturity. Existing slices go on accruing until incoming lenders buy them out. | | **Grace** | Maturity has passed. The borrower has 24 hours to settle the full amount owed before the loan defaults. | | **Defaulted** | The grace window ended without payment, or a rollover auction reached its cap with no bid. The collateral can now be auctioned regardless of the health factor. | | **Liquidating** | A Dutch auction on the collateral is in progress. | | **Settled** | The auction has cleared. Lenders have been paid, the penalty has been split, and any surplus has gone back to the borrower. | | **Repaid** | Principal and interest are paid in full. The collateral has been returned to the borrower and the slice tokens burned. | | **Expired** | The fill deadline passed without an origination. Offers targeted at this request are no longer usable. | ## A worked sequence The diagram below follows one loan from the request through origination, then branches into the three ways it can end. ```mermaid sequenceDiagram participant Bo as Borrower participant Le as Lenders (n) participant Rel as Relayer participant LD as LoanDesk participant AR as AccessRegistry participant PG as PriceGate participant CA as CollateralAuction Bo->>Rel: request (250 NVDA, 20,000 USDG, max 9.00% APR, 30d) Le->>Rel: signed offers (5k @ 8.50%, 10k @ 8.90%, 5k @ 9.00%) Rel-->>Bo: proposed fill Bo->>LD: originate(request, offers[], sigs[]) LD->>AR: check(borrower, lenders[]) LD->>PG: price(NVDA) with session haircut LD->>LD: recover signatures, confirm LTV under tier max LD->>LD: lock collateral, draw USDG from each lender, mint 3 slice tokens LD-->>Bo: 20,000 USDG Note over LD: every slice accrues per second at its own APR alt Borrower repays Bo->>LD: repay(principal + interest) LD-->>Le: pro-rata payout, interest share deducted LD-->>Bo: collateral returned else HF falls under 1.0 CA->>LD: startAuction(loanId) CA->>CA: Dutch auction, roughly 45 min, bounded floor CA-->>Le: proceeds pro rata plus penalty share CA-->>Bo: surplus else Maturity approaches Bo->>LD: openRefinance(loanId) LD->>LD: rising-rate auction, incoming lenders replace outgoing end ``` ## The transitions ### Origination `originate` is the only way a loan comes into existence, and it either succeeds completely or not at all. Every offer in the set has to verify, every lender's USDG has to transfer and the collateral has to lock; if any of those fails, the whole transaction reverts. [Signed offers and the originate call](/protocol/offers-and-matching.md) lists the checks in order. ### Repaying in full or in part After the minimum interest period has passed, the borrower can repay whenever they choose. A partial payment reduces the principal of every slice in proportion. [Interest and settling a loan](/protocol/interest-and-repayment.md) has the arithmetic. ### Topping up collateral While a loan is active the borrower may add collateral at any time. This raises the health factor, and it is the expected reaction to a warning alert. ### Rolling over Before maturity the borrower can open a rollover auction. [Maturity, grace and the rollover auction](/protocol/maturity-and-refinancing.md) describes the mechanism. ### Auctioning the collateral Collateral becomes auctionable in two situations: the health factor drops under 1.0, or the loan reaches the Defaulted state. [Health factor and the collateral auction](/protocol/health-and-liquidation.md) covers both. ## Reading the flight log Each transition emits an event that carries the loan ID, so indexers and keepers can track a loan without polling contract storage. The flight log shown for each loan in the explorer is built from these events, entry by entry, each linked to its Blockscout transaction. The complete event list is in [Smart contracts](/architecture/smart-contracts.md#events). --- # 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.usefarlight.com/protocol/loan-lifecycle.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.