> For the complete documentation index, see [llms.txt](https://docs.syndromics.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.syndromics.xyz/protocol/loan-lifecycle.md). # Loan lifecycle A Syndromics loan moves through a small number of states. Each transition is a single on-chain transaction that emits an event, so the full history of any loan can be rebuilt from the chain alone. ## State machine ```mermaid stateDiagram-v2 [*] --> Requested : borrower posts request (off-chain) Requested --> Active : settle() Requested --> Expired : fill deadline passes Active --> Repaid : repay() in full Active --> Active : partial repay / top-up / add slice Active --> Refinancing : openRefinance() Refinancing --> Active : bid accepted, new syndicate Refinancing --> Defaulted : cap reached, no bid Active --> Liquidating : HF < 1.0, startAuction() Active --> Grace : maturity reached Grace --> Repaid : repay() within window Grace --> Defaulted : window passes Defaulted --> Liquidating : startAuction() Liquidating --> Settled : auction fills Repaid --> [*] Settled --> [*] Expired --> [*] ``` ## States | State | Meaning | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Requested** | The request exists in the relayer order book only. Nothing is on-chain yet and nothing is escrowed. | | **Active** | Collateral is escrowed, principal has been disbursed, interest is accruing per second on every slice. | | **Refinancing** | The borrower has opened a rising-rate auction before maturity. Existing slices continue to accrue until they are bought out. | | **Grace** | Maturity has passed. The borrower has a 24 hour window to repay in full before default. | | **Defaulted** | The grace window has passed, or a refinance auction reached its cap without a bid. The loan is liquidatable regardless of health factor. | | **Liquidating** | A Dutch auction of the collateral is open. | | **Settled** | The auction has cleared. Lenders have been paid, the penalty split has been applied, and any surplus has been returned to the borrower. | | **Repaid** | Principal and interest have been paid in full. Collateral has been released to the borrower and position NFTs are burned. | | **Expired** | The request's fill deadline passed without settlement. Offers that targeted it are no longer fillable. | ## Sequence: origination to repayment ```mermaid sequenceDiagram participant Bo as Borrower participant Le as Lenders (n) participant Rel as Relayer participant LS as LoanSettlement participant El as EligibilityRegistry participant Or as OracleRouter participant Au as LiquidationAuction 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: matched set Bo->>LS: settle(request, offers[], sigs[]) LS->>El: check(borrower, lenders[]) LS->>Or: price(NVDA) with session haircut LS->>LS: verify sigs, LTV within tier max LS->>LS: escrow collateral, pull USDG per lender, mint 3 position NFTs LS-->>Bo: 20,000 USDG Note over LS: interest accrues per second at each slice's APR alt Repay Bo->>LS: repay(principal + interest) LS-->>Le: pro-rata payout, net of interest share LS-->>Bo: collateral released else Health factor below 1.0 Au->>LS: startAuction(loanId) Au->>Au: Dutch auction, ~45 min, floor bounded Au-->>Le: proceeds pro rata plus penalty share Au-->>Bo: surplus else Maturity approaching Bo->>LS: openRefinance(loanId) LS->>LS: rising-rate auction; new lenders replace old end ``` ## Transitions in detail ### Settlement The `settle` call is the only way a loan comes into existence. It is atomic: either every offer in the set verifies, every lender's USDG transfers and the collateral escrows, or the whole transaction reverts. See [Offers and matching](/protocol/offers-and-matching.md) for the validation steps. ### Repayment and partial repayment Repayment is permitted at any time after the minimum interest period. A partial repayment reduces principal pro rata across every slice. See [Interest and repayment](/protocol/interest-and-repayment.md). ### Top-up A borrower may add collateral to an active loan at any time. Adding collateral raises the health factor and is the expected response to a warning alert. ### Refinancing Before maturity a borrower may open a refinance auction. See [Maturity and refinancing](/protocol/maturity-and-refinancing.md). ### Liquidation A loan becomes liquidatable when its health factor is below 1.0, or when it is in the Defaulted state. See [Health factor and liquidation](/protocol/health-and-liquidation.md). ## Events Every transition emits an event with the loan ID, so indexers and keepers never have to poll storage. The event set is listed 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.syndromics.xyz/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.