> For the complete documentation index, see [llms.txt](https://docs.trilobyte.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trilobyte.finance/protocol-mechanics/vault-lifecycle.md).

# Vault Lifecycle

Every Trilobyte vault goes through a series of phases that represent the state of the loan. Transitions between phases are triggered by on-chain actions — deposits, approvals, payments, or enforcement calls.

## Phase Diagram

```mermaid
stateDiagram-v2
  [*] --> RaisingFunds: Factory.create_vault
  RaisingFunds --> AwaitingApproval: both tranches reach target
  RaisingFunds --> Cancelled: check_funding_expiry (deadline missed)
  AwaitingApproval --> Active: approve_and_disburse by manager
  AwaitingApproval --> Cancelled: check_approval_expiry (deadline missed)
  Cancelled --> Finalized: finalize, once every investor has claim_refund'd
  Active --> FullyRepaid: receive_payment, both tranches' outstanding reach 0
  Active --> Renegotiation: propose_renegotiation
  Renegotiation --> Active: approve_renegotiation (manager + borrower) or reject
  Active --> Defaulted: check_default, past due date plus grace
  FullyRepaid --> Finalized: finalize, all yield claimed, cash pool empty
  Defaulted --> Defaulted: distribute_recovery, claim_recovery
  Defaulted --> Finalized: finalize, once recovery is distributed and fully claimed
  Finalized --> [*]
```

## Phases at a Glance

| Phase                | Description                                                                                                                                                                                 | Who Acts                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| **RaisingFunds**     | Vault is open for investor deposits — junior first, then senior once `lock_junior` is called                                                                                                | Manager, Investors               |
| **AwaitingApproval** | Fully funded (both tranches at target), waiting for manager to approve and disburse                                                                                                         | Pool Manager                     |
| **Active**           | Loan is live — borrower makes payments through the waterfall, investors claim yield per tranche                                                                                             | Borrower, Investors, Manager     |
| **FullyRepaid**      | Both tranches' outstanding reached zero — investors claim remaining yield, borrower withdraws remaining cash. **Terminal** transition target via `finalize`.                                | Investors, Borrower              |
| **Cancelled**        | The vault never reached disbursement (funding or approval deadline missed) — manager collateral and any borrower pledge are released once, and each investor pulls their own `claim_refund` | Anyone, then each Investor       |
| **Finalized**        | Terminal state — reached from FullyRepaid, Defaulted, or Cancelled once all claims/refunds are settled                                                                                      | —                                |
| **Renegotiation**    | Terms are being renegotiated (**from Active only**)                                                                                                                                         | Pool Manager, Borrower           |
| **Defaulted**        | Borrower failed to repay within the grace period. **Terminal** (manager collateral is slashed, any borrower pledge seized, recovery distributed senior-first).                              | Anyone (trigger), then Investors |

## Transition Rules

* **RaisingFunds → AwaitingApproval**: Automatic once `junior_raised + senior_raised == principal` (both tranches at their targets)
* **RaisingFunds → Cancelled**: Funding deadline expired (permissionless call, `check_funding_expiry`)
* **AwaitingApproval → Active**: Manager calls `approve_and_disburse` (with a pledge id, if the vault requires borrower collateral)
* **AwaitingApproval → Cancelled**: Approval deadline expired (permissionless call, `check_approval_expiry`)
* **Cancelled → Finalized**: Every investor has pulled their own `claim_refund`; anyone then calls `finalize()`
* **Active → FullyRepaid**: Automatic when both `outstanding_s` and `outstanding_j` reach zero (investors claim remaining yield here; the borrower withdraws remaining cash pool)
* **FullyRepaid → Finalized**: Once every investor has claimed their tranche pool in full and the cash pool is empty, anyone calls `finalize()`
* **Active → Renegotiation**: Manager proposes new terms
* **Active → Defaulted**: Grace period expired after a missed payment (permissionless call; terminal)
* **Renegotiation → Active**: Manager and borrower **both** authorize `approve_renegotiation` (EMI recalculated) — or the manager rejects it, which restores **Active**
* **Defaulted → Finalized**: Once `distribute_recovery` has run and every tranche pool is fully claimed, anyone calls `finalize()`

*(Defaulted, FullyRepaid, and Cancelled all resolve into Finalized — the only true terminal state — once every party has claimed. Renegotiation is only reachable from — and returns to — Active; a defaulted loan cannot be renegotiated because the manager's collateral has already been slashed.)*

{% hint style="info" %}
Explore each phase in detail using the sub-pages below.
{% endhint %}

*As of September 2026.*