> 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/payments-and-emi.md).

# Payments & the Waterfall

Trilobyte uses a shared, amortised **installment** for each loan, but repayments are no longer split by a fixed ratio between investors and the borrower. Instead, every payment is allocated through a strict **six-bucket waterfall** across the reserve fee, the senior tranche, the junior tranche, and finally the borrower's own cash pool. This replaces the older fixed `split_ratio` / single EMI-pool model.

## Installment Calculation

The shared installment is calculated using the standard amortisation formula, applied to the loan's total principal:

$$
\text{installment} = P \times \frac{r(1+r)^n}{(1+r)^n - 1}
$$

Where:

* $P$ = Principal (loan amount)
* $r$ = Periodic interest rate (annual rate ÷ periods per year)
* $n$ = Number of periods (loan term)

{% hint style="info" %}
All math is **integer-only** — Soroban has no floating-point support. Trilobyte uses 10¹² internal precision scaling and ceiling-rounds the final installment to ensure the borrower always repays at least the full amount owed.
{% endhint %}

## The Six-Bucket Waterfall

Each period, the interest accrued on the combined outstanding balance (`outstanding_s + outstanding_j`) and the scheduled principal amortisation are allocated in this strict order:

```mermaid
flowchart TD
    R["receive_payment(payer, amount)"] --> B1
    B1["1 · Reserve fee → treasury\nreserve_fee_bps of interest"] --> B2
    B2["2 · Senior interest\nsenior share, net of reserve + junior spread"] --> B3
    B3["3 · Senior principal\nscheduled senior amortisation"] --> B4
    B4["4 · Junior interest\nremainder of interest after 1-2"] --> B5
    B5["5 · Junior principal\nscheduled junior amortisation"] --> B6
    B6["6 · Residual → borrower cash pool\nwhatever remains"]
```

| Order | Bucket           | Recipient               |
| ----- | ---------------- | ----------------------- |
| 1     | Reserve fee      | Treasury                |
| 2     | Senior interest  | Senior tranche pool     |
| 3     | Senior principal | Reduces `outstanding_s` |
| 4     | Junior interest  | Junior tranche pool     |
| 5     | Junior principal | Reduces `outstanding_j` |
| 6     | Residual         | Borrower cash pool      |

## Worked Example

A 100,000 USDC loan, 15% annual rate, 12-month term, 4.00x leverage (junior 20,000 / senior 80,000), a 20% junior spread, and a 10% protocol reserve fee. Month one's installment is 9,026 USDC (1,250 interest + 7,776 principal):

| Bucket           | Amount |
| ---------------- | ------ |
| Reserve fee      | 125    |
| Senior interest  | 700    |
| Senior principal | 6,221  |
| Junior interest  | 425    |
| Junior principal | 1,555  |
| Residual         | 0      |

Effective annualised yields: senior 10.5%, junior 25.5%, protocol 1.5% of principal. See [Tranches and the Waterfall](/overview/tranches-and-the-waterfall.md) for the plain-language version, and [Fees](/protocol-mechanics/fees.md) for how the reserve fee and junior spread are governed.

### A short payment

If the borrower pays only 5,000 of the 9,026 owed, the waterfall still fills strictly in order — reserve fee (125), senior interest (700), then as much of senior principal as remains (4,175). **Junior and the borrower receive nothing.** The 4,026 USDC shortfall is recorded as **arrears** and must be cleared, in the same bucket order, before the next period's own dues are accepted.

## Arrears

`receive_payment` accepts **any** amount greater than zero — there is no minimum-payment rejection and no gross-up. A bucket that isn't fully paid in a period records the deficit in `Arrears` (tracked per bucket 1–5; bucket 6, the residual, never carries arrears). The next payment first clears outstanding arrears, in the same 1→5 order, before any of it counts toward the current period's fresh dues.

The schedule (`payments_made`, `next_due`) only advances once buckets 1–5 are **fully** cleared for a period — a short payment never advances the schedule, and a fresh period's dues only accrue once (guarding against double-counting a still-open period across repeated partial payments).

## Principal Amortisation

Each period's interest is calculated on the combined outstanding balance; the scheduled principal component reduces `outstanding_s` and `outstanding_j` separately. Senior/junior principal splits floor junior's share and give the exact remainder to senior (conservative-for-senior rounding). The loan is fully repaid when **both `outstanding_s` and `outstanding_j` reach zero** — not on a fixed payment count.

## Late Fees

Late fees accrued by `apply_late_fee` are added to buckets 2 and 4 (senior and junior interest arrears) pro rata to each tranche's outstanding share, so a late fee is actually collected through the same waterfall rather than sitting as a separate side balance. See [Fees](/protocol-mechanics/fees.md).

## Yield Claiming

Investors claim their share of their own tranche's pools proportionally to their deposit within that tranche:

$$
\text{claimable} = \frac{\text{your deposit in tranche}}{\text{tranche total raised}} \times \text{tranche pool} - \text{already claimed}
$$

* `claim_yield(investor, tranche)` pays from **that tranche's own** cumulative interest + principal pools only — a senior position never draws from junior's pool or vice versa
* Claims can be made at any time during the **Active** or **FullyRepaid** phases
* Claims are cumulative — you receive the difference between your total entitlement and what you've already claimed

## Token Precision

All amounts use **7 decimal places** (Stellar standard). For example:

* 1 USDC = `10_000_000` (10⁷)
* 0.5% protocol fee = `50_000` in 7-decimal format

*As of September 2026.*