> For the complete documentation index, see [llms.txt](https://docs.ethosis.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ethosis.org/protocol/loan-lifecycle.md). # Loan states and transitions An Ethosis loan occupies one of a handful of states at any moment. Every move between states is a single on-chain transaction that emits an event, which means the complete history of a loan can be reconstructed from chain data with no off-chain records. ## The state diagram ```mermaid stateDiagram-v2 [*] --> Requested : borrower publishes request (off-chain) Requested --> Active : originate() Requested --> Expired : fill deadline missed Active --> Repaid : repay() covers everything owed Active --> Active : partial repayment, collateral top-up, slice added Active --> Refinancing : openRefinance() Refinancing --> Active : bid taken, syndicate replaced Refinancing --> Defaulted : cap hit with no bid Active --> Liquidating : HF under 1.0, startAuction() Active --> Grace : maturity timestamp reached Grace --> Repaid : repay() inside the window Grace --> Defaulted : window closes Defaulted --> Liquidating : startAuction() Liquidating --> Settled : auction clears Repaid --> [*] Settled --> [*] Expired --> [*] ``` ## What each state means | State | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Requested** | The request is known only to the relayer book. No transaction has been sent and no assets are locked. | | **Active** | Collateral sits in escrow, the borrower holds the principal, and every slice is accruing interest second by second. | | **Refinancing** | The borrower has started a rising-rate auction ahead of maturity. The existing slices keep accruing until new lenders buy them out. | | **Grace** | Maturity has arrived. The borrower has 24 hours to repay everything owed before the loan defaults. | | **Defaulted** | Either the grace window closed unpaid or a rollover auction hit its cap with no bid. The collateral may now be auctioned whatever the health factor says. | | **Liquidating** | A Dutch auction on the collateral is running. | | **Settled** | The auction has cleared: lenders paid, penalty split applied, and any surplus returned to the borrower. | | **Repaid** | Principal and interest are fully paid. The collateral has gone back to the borrower and the slice tokens have been burned. | | **Expired** | The fill deadline passed with no origination. Offers aimed at this request can no longer be used. | ## From origination to repayment, step by step ```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, issue 3 slice tokens LD-->>Bo: 20,000 USDG Note over LD: each 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 drops 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 is near Bo->>LD: openRefinance(loanId) LD->>LD: rising-rate auction, incoming lenders replace outgoing end ``` ## Transitions explained ### Origination A loan can only be created through `originate`. The call is all-or-nothing: every offer in the set must verify, every lender's USDG must transfer and the collateral must lock, or the entire transaction reverts. The validation sequence is laid out in [Intents: signing, matching and origination](/protocol/offers-and-matching.md). ### Full and partial repayment Once the minimum interest period has elapsed the borrower may repay at any time. Paying back part of the debt reduces principal on every slice in proportion. Details are in [Accrual and paying back](/protocol/interest-and-repayment.md). ### Adding collateral At any point while a loan is active the borrower can deposit more collateral. Doing so lifts the health factor, and it is the intended response when a warning alert arrives. ### Rolling over Ahead of maturity the borrower can open a rollover auction. See [Term end and rollover](/protocol/maturity-and-refinancing.md). ### Auctioning collateral Collateral becomes auctionable when the health factor falls under 1.0 or when the loan is in the Defaulted state. See [Loan health and collateral auctions](/protocol/health-and-liquidation.md). ## Event trail Every transition emits an event carrying the loan ID, so indexers and keepers can follow loans without polling storage. The full event list lives 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.ethosis.org/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.