> 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/overview/how-a-loan-works.md).

# How a Loan Works

A Trilobyte loan follows a structured lifecycle from creation to settlement, funded across two tranches and repaid through a strict payment waterfall. Here's how a typical loan flows through the protocol. For the tranche mechanics themselves, see [Tranches and the Waterfall](/overview/tranches-and-the-waterfall.md).

## Step-by-Step

### 1. Vault Creation

A **Pool Manager** evaluates a business's creditworthiness and negotiates loan terms off-chain. Once agreed, the manager creates a vault via the **Factory** contract with the following parameters:

* **Principal** — The loan amount (e.g. 100,000 USDC)
* **Interest rate** — Annual rate in basis points (e.g. 1500 = 15%)
* **Loan term** — Duration in months (e.g. 12)
* **Leverage ratio** — How large senior capital may be as a multiple of junior (e.g. 400 = 4.00x), which derives `junior_target` and `senior_target`
* **Reporting interval** — Optional manager reporting cadence covenant (0 = none)
* **Funding deadline** — Optional deadline for full funding
* **Approval deadline** — Optional deadline for manager approval after funding
* **Grace period** — Window before default can be triggered after a missed payment
* **Permissioned** — Whether only allowlisted investors can participate
* **Related party** — A manager-declared disclosure flag for deals policy considers related, even where addresses don't literally match
* **Collateral fields** — Optional borrower real-world-asset pledge parameters (escrow, token, recovery party, minimum)

The Factory validates all parameters against global settings — including the leverage cap for the vault's collateral type and borrower/manager exposure caps against total outstanding principal — checks the manager's collateral and credit limit, rejects `borrower == manager`, and deploys a new Vault smart contract.

### 2. Fundraising — junior first, then senior

The vault enters the **RaisingFunds** phase. **Junior investors deposit first**, alongside the manager's own Globals-locked collateral, which counts as a credit toward the junior target. Once junior capital reaches its target, the manager calls `lock_junior`, which opens the vault to **senior deposits** up to the senior target. All deposits mint **SEP-41 debt tokens** at a 1:1 ratio (net of the protocol fee); an investor can hold a position in both tranches.

The vault automatically transitions to **AwaitingApproval** once both tranches are fully funded.

{% hint style="info" %}
If a funding deadline is set and the vault fails to raise the full principal by that date, anyone can call `check_funding_expiry()`. The vault moves to **Cancelled**, and each investor then pulls their own refund with `claim_refund`.
{% endhint %}

### 3. Approval & Disbursement

The **Pool Manager** reviews the funded vault and calls `approve_and_disburse`. This:

* Verifies any required borrower collateral pledge, if the vault is collateral-backed
* Disburses the funded amount to the borrower
* Calculates the shared installment schedule
* Sets the first payment due date
* Transitions the vault to **Active**

{% hint style="info" %}
If an approval deadline is set and the manager fails to approve by that date, anyone can call `check_approval_expiry()`. The vault moves to **Cancelled**, and each investor pulls their own refund.
{% endhint %}

### 4. Repayments — the six-bucket waterfall

The **Borrower** makes periodic repayments. Each payment flows through a strict order: reserve fee → senior interest → senior principal → junior interest → junior principal → residual (borrower cash pool). A bucket that isn't fully paid carries forward as arrears, ahead of the next period's dues. See [Tranches and the Waterfall](/overview/tranches-and-the-waterfall.md) for the worked example.

The loan completes when **both tranches' outstanding principal reach zero** — not on a fixed payment count.

### 5. Yield Distribution

**Investors** can call `claim_yield` at any time during the Active or FullyRepaid phases to claim their pro-rata share of their own tranche's accumulated interest and principal pools.

### 6. Settlement

When both tranches are fully repaid, the vault transitions to **FullyRepaid** and the manager's collateral is released. Once every investor has claimed their yield and the borrower has withdrawn the remaining cash pool, anyone can call `finalize()`, moving the vault to the terminal **Finalized** state.

If the loan instead defaults, recoveries are distributed senior-first — see [Default & Risk Management](/protocol-mechanics/default-and-risk-management.md).

## Visual Overview

```mermaid
stateDiagram-v2
  [*] --> RaisingFunds: Factory.create_vault
  RaisingFunds --> RaisingFunds: deposit junior, lock_junior, deposit senior
  RaisingFunds --> AwaitingApproval: both tranches reach target
  RaisingFunds --> Cancelled: check_funding_expiry
  AwaitingApproval --> Active: approve_and_disburse by manager
  AwaitingApproval --> Cancelled: check_approval_expiry
  Cancelled --> Finalized: every investor claim_refund
  Active --> FullyRepaid: receive_payment, both tranches' outstanding reach 0
  Active --> Renegotiation: propose_renegotiation
  Renegotiation --> Active: approve or reject (both manager and borrower authorize approval)
  Active --> Defaulted: check_default, past due plus grace
  FullyRepaid --> Finalized: finalize, all yield claimed, cash pool empty
  Defaulted --> Defaulted: distribute_recovery, claim_recovery
  Defaulted --> Finalized: finalize, all recovery claimed
  Finalized --> [*]
```

*As of September 2026 — see* [*Vault Lifecycle*](/protocol-mechanics/vault-lifecycle.md) *for the full phase reference, including the new terminal* [*Cancelled*](/protocol-mechanics/vault-lifecycle/cancelled.md) *phase.*