> For the complete documentation index, see [llms.txt](https://docs.ibis.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibis.app/platform/epochs-and-settlement.md).

# Epochs and settlement

An Epochs facility opens its first epoch at activation and each later epoch when the previous settlement completes. Deposits remain pending and withdrawal requests remain queued until settlement converts the deposits into shares and prices the withdrawals.

The share price follows the facility's fixed rate or, on a variable-rate facility, the yield declared within the range locked for the epoch. Both are nominal annual rates in basis points (bps).

Once the settlement clock and the conditions below allow it, the Curator starts settlement. The facility then pins prices under its [accrual law](/platform/yield-accrual.md).

## Opening and settlement

### Terms locked at opening

The facility locks these terms when an epoch opens. Admin changes apply from the next epoch.

| Term                       | Symbol                      | Applies to                                               |
| -------------------------- | --------------------------- | -------------------------------------------------------- |
| Epoch length               | $$T$$                       | Every Epochs facility                                    |
| Variable-yield range       | $$y\_{min}$$, $$y\_{max}$$  | Variable-rate facilities                                 |
| Settlement window          | $$T\_w$$                    | Every Epochs facility                                    |
| Protected-withdrawal terms | $$b$$, $$\theta$$, $$T\_f$$ | Fixed-rate facilities with protected withdrawals enabled |
| Opening time               | $$t\_{open}$$               | Every Epochs facility                                    |

A rate staged for the next epoch applies when settlement completes. [Facility terms, limits and fees](/platform/facility-terms.md) gives each term's bounds.

### What settlement fixes

When settlement starts, the facility pins the continuing-holder price $$I\_{close}$$ under its accrual law at that moment. The withdrawal price $$I\_{exit}$$ equals it unless the epoch qualifies for [protected withdrawals](#protected-withdrawals). Both prices stay fixed throughout settlement.

Pending deposits convert into shares at $$I\_{close}$$. For queued withdrawals, the facility cancels the requested shares and fixes each request's owed value at $$I\_{exit}$$, rounded down. That owed value is never repriced.

In Winding down, settlement prices queued withdrawals while pending deposits stay refundable and do not convert. [Withdrawals and claims](/platform/withdrawals-owed-value-and-claims.md) gives the request and owed-value rules.

After settlement, the Curator uses facility cash to fund the owed value into the lender's claimable balance, in one or more steps. The lender can claim that balance at any time.

A withdrawal is funded only when the facility holds cash to fund it, normally from borrower repayment.

Settlement can take more than one transaction. While Settling, the facility refuses deposits, withdrawal requests and changes to them, cancellation of pending deposits, and funding of owed value. Claims and repayment continue.

The facility also refuses term changes, yield declarations and rate changes until completion. The Admin can still stage a rate for the next epoch if it leaves the settling epoch's protected classification unchanged.

![An open epoch enters settlement, which converts pending deposits, prices queued withdrawals and opens the next epoch on completion](https://1212871591-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPyk7jtRhMNFPRuPw5d3%2Fuploads%2Fgit-blob-850b4b149429fdbdb7c483b77eedc9ef144839c9%2Fepoch-settlement.svg?alt=media)

*Figure: Settlement of one epoch, from its start to the opening of the next epoch.*

### Completion

When settlement completes, the facility closes the epoch and records its continuing-holder price, withdrawal price, protected classification and payment-due time permanently. Any staged rate takes effect, and the next epoch opens at the completion time under the terms then in force.

After completion, the facility delivers principal from converted deposits to the borrower receiving wallet or withholds it under the rules on [Deposits and principal delivery](/platform/deposits-and-withheld-principal.md).

If settlement opens a protected withdrawal window, the principal stays withheld and funds priority withdrawals first. Any remainder stays withheld through later settlements.

## Settlement timing

The settlement clock records the elapsed time eligible toward settlement, in whole seconds from the epoch's opening. It starts at zero and never runs backward.

### When settlement can begin

**Settlement eligibility**

$$
\Delta t\_s \ge T + b
$$

Where:

$$\Delta t\_s$$ is the settlement-clock time above, in seconds. $$T$$ is the epoch's locked length in seconds. $$b$$ is the reaction buffer in seconds, zero when protected withdrawals are not enabled.

The comparison uses whole seconds, with no rounding. The epoch length is bounded at 1 hour to 365 days and the reaction buffer at 0 to 7 days (bounds).

Illustrative example: with an epoch length of 10 days and a reaction buffer of 1 day, settlement becomes eligible once the settlement clock reads 11 days.

Settlement also requires any earlier priority withdrawal value to be fully funded and, on a variable-rate facility, a yield declaration within the epoch's locked range. Its availability depends on the facility's current operating status.

The facility must be Open or Winding down. Settlement requires the Curator to act; a later start also delays the next epoch's opening.

## Protected withdrawals

Fixed-rate Epochs facilities can enable protected withdrawals. If the next epoch's rate falls below the opening rate by at least the set threshold, queued withdrawals receive the protected price described below and take funding priority.

Each epoch locks the reaction buffer $$b$$, rate-cut threshold $$\theta$$ and funding window $$T\_f$$. The reaction buffer extends the time before settlement may begin, giving lenders time to respond to a staged rate before withdrawals are priced.

**Protected classification**

$$
r\_{open} - r\_{next} \ge \theta
$$

Where:

$$r\_{open}$$ is the fixed rate when the epoch opened, in basis points. $$r\_{next}$$ is the rate for the next epoch, in basis points: the staged rate, or the current rate when none is staged. $$\theta$$ is the rate-cut threshold locked for the epoch, in basis points.

The comparison uses whole basis points, with no rounding, and a cut exactly equal to the threshold qualifies. When protected withdrawals are enabled, the threshold is bounded at 1 to 2,000 bps (0.01% to 20.00%) (bound). An epoch can qualify only if the option was enabled when it opened. The classification is fixed when settlement starts.

Illustrative example: an epoch opens with a fixed rate of 730 bps (7.30%), 600 bps (6.00%) is staged for the next epoch and the threshold is 100 bps (1.00%). The cut of 130 bps (1.30%) qualifies.

**Protected withdrawal price**

$$
I\_{exit} = \left\lfloor I\_{open} \times \left(1 + \frac{r\_{open} \times T}{Y \times 10{,}000}\right) \right\rfloor
$$

Where:

$$I\_{exit}$$ is the withdrawal price pinned at the settlement of a protected epoch, in assets per share to 18 decimals. $$I\_{open}$$ is the share price when the epoch opened, to 18 decimals. $$r\_{open}$$ is the fixed rate when the epoch opened, in basis points. $$T$$ is the epoch's locked length in seconds. $$Y$$ is one year of 365 days, 31,536,000 seconds.

The withdrawal price is rounded down to 18 decimals and subject to the fixed-rate and epoch-length [bounds](/platform/facility-terms.md).

Illustrative example: an epoch opens at a share price of 1.002000000000000000 with a fixed rate of 730 bps (7.30%), an epoch length of 10 days and a reaction buffer of 1 day, and qualifies as protected. In this example, settlement starts after 11 days of accrual time. The withdrawal price is 1.004004000000000000, which includes 10 days of accrual; the continuing-holder price is 1.004204400000000000, which includes 11 days.

The formula describes accrual at one rate from the opening share price over the locked epoch length. In other cases, the protected withdrawal price is the share price reached over the shorter of the epoch's accrual time at settlement start and its locked length.

The continuing-holder price includes reaction-buffer and late-start time, so it is never below the withdrawal price. The formula gives the facility's figure to within one unit of the last decimal place when the previous settlement completed in the transaction that started it. If that settlement spanned several transactions, its time spent Settling counts toward the locked length. An epoch that does not qualify uses the continuing-holder price for withdrawals.

A protected settlement fixes priority withdrawal value. Until that value is fully funded, other owed value cannot be funded and the next settlement cannot start.

The funding window sets a recorded deadline measured from completion. Priority continues after the deadline, ending only when all priority withdrawal value is funded or default is declared. This period is the protected withdrawal window.

## Payment-due time

$$
t\_{due} = t\_{completion} + T\_w
$$

Where:

$$t\_{due}$$ is the payment-due time of the epoch, UTC. $$t\_{completion}$$ is the time settlement completed, UTC. $$T\_w$$ is the settlement window locked for the epoch, in seconds.

The payment-due time is in whole seconds, with no rounding. The settlement window is bounded at 1 hour to 30 days (bound).

Illustrative example: settlement completes at 2026-03-15 14:00 UTC with a settlement window of 5 days, so the payment-due time is 2026-03-20 14:00 UTC.

The payment-due time is a disclosure milestone. It does not gate funding, claims, repayment or facility-state changes, and passing it does not trigger default. Remedies for a missed payment follow the facility's Master Lending Agreement.