TimeMint: Timeswap V1 with Controller Vault and Oracle-Guided Soft Liquidation

General
1

TimeMint: Timeswap V1 with Controller Vault and Oracle-Guided Soft Liquidation

This is part of Document 2 of the TimeMint Series.

This document proposes a controller-layer redesign on top of Timeswap V1 pool math. Goal: keep V1 term-pricing mechanics, but add oracle-based collateral management so borrower positions are actively risk-controlled before maturity.

Design idea

A borrower no longer interacts with the pair directly.

They open a position through a ControllerVault:

  1. A portion of posted collateral is sent to the Timeswap pair to satisfy V1 due collateral requirements.

  2. The remaining collateral stays in the controller as a buffer vault.

  3. The controller monitors collateralization using an oracle.

  4. If collateralization falls below 150%, the controller sells collateral buffer for asset and repays debt until collateralization returns to 175%.

Initial opening target: 200% collateralization.

Notation

For one borrower position at maturity T:

  • d: remaining due debt (asset units)

  • q: due-collateral locked in Timeswap pair (collateral units)

  • v: extra collateral buffer in controller vault (collateral units)

  • Q=q+v: total collateral attributed to the position

Oracle prices:

  • P_a: asset price (USD per asset)

  • P_c: collateral price (USD per collateral)

Risk and execution parameters:

  • h\in(0,1]: risk haircut on collateral valuation

  • \eta\in(0,1]: execution efficiency when swapping collateral \to asset (captures slippage + fees)

Collateral ratio:

CR=\frac{hQP_c}{dP_a}

Thresholds:

  • Open threshold: \theta_{open}=2.00

  • Soft-liquidation trigger: \theta_{soft}=1.50

  • Soft-liquidation target: \theta_{target}=1.75

Link to Timeswap V1 borrow math

When opening or increasing debt, the controller still uses V1 borrow equations:

d_{new}=\Delta x + \Big\lceil\frac{\tau\,\Delta y}{k_y}\Big\rceil
q_{new}=\Big\lceil\frac{\tau\,\Delta z}{k_z}\Big\rceil + \Big\lceil\frac{z\,\Delta x}{x-\Delta x}\Big\rceil

where \tau=T-t.

Controller enforces deposited collateral C_0 to satisfy:

C_0 \ge q_{new},\quad v_0=C_0-q_{new}
CR_0=\frac{h(q_{new}+v_0)P_c}{d_{new}P_a} \ge \theta_{open}=2.00

Intuition: V1 determines the minimum structural collateral q; controller adds a market-value buffer v.

Pre-maturity operations (t<T)

Open Position

Input: desired borrow trade (\Delta x,\Delta y,\Delta z), maturity T, collateral deposit C_0.

Steps:

  1. Execute V1 borrow through controller, creating due (d,q).

  2. Lock q in pair; keep v=C_0-q in vault.

  3. Require CR\ge2.00, otherwise revert.

Intuition: borrower gets borrowed asset, but controller requires substantial extra collateral from day one.

Add Buffer Collateral

User deposits \Delta v>0:

v\leftarrow v+\Delta v, \quad Q\leftarrow q+v

Intuition: raises health factor without changing debt.

Remove Buffer Collateral

User withdraws \Delta v>0 only if post-withdraw ratio remains safe:

CR' = \frac{h(q+v-\Delta v)P_c}{dP_a} \ge \theta_{open}

Intuition: no buffer extraction that weakens position below open standard.

Manual Repay

Borrower repays a asset via V1 pay(a,c) and can unlock due-collateral c subject to:

aq \ge cd

State update:

d\leftarrow d-a,\quad q\leftarrow q-c,\quad v\leftarrow v+c

Intuition: repayment can simultaneously reduce debt and migrate unlocked due-collateral into the controller buffer, so collateral is not stranded.

Soft Liquidation (Controller-Triggered)

Trigger condition:

CR<\theta_{soft}=1.50

Controller action:

  1. Sell s collateral from vault buffer v for asset.

  2. Received asset used to repay debt via V1 pay with c=0.

Conversion and state update:

\text{asset repaid } r = \eta s\frac{P_c}{P_a}
v\leftarrow v-s, \quad d\leftarrow d-r, \quad q\text{ unchanged}

Targeting formula (minimum sale to reach \theta_{target}=1.75):

CR' = \frac{h(q+v-s)P_c}{(d-r)P_a}=\theta_{target}

with r=\eta s\frac{P_c}{P_a}, giving:

s^*=\frac{P_a}{P_c}\cdot\frac{\theta_{target}d-\frac{hP_c}{P_a}(q+v)}{\theta_{target}\eta-h}

Execution amount:

s=\min\{\max(s^*,0),\ v\}

Feasibility condition for the closed form:

\theta_{target}\eta > h

If this does not hold, parameters must be changed (or liquidation must use iterative/degraded logic).

Intuition: this is a “soft” deleveraging band. Instead of liquidating the whole position, controller trims debt using buffer collateral and pushes the ratio back up.

Optional Emergency Rule

If v=0 and CR<\theta_{soft}, soft liquidation cannot sell more collateral.

A hard mode can be added (not required for stage 2), e.g. forced close before maturity or third-party liquidation logic.

Full Close Before Maturity

If borrower fully repays debt, controller closes the due and returns all collateral.

Choose:

a=d,\quad c=q

which satisfies aq \ge cd at equality.

After V1 pay(a,c):

d\leftarrow 0,\quad q\leftarrow 0,\quad v\leftarrow v+c

Then controller returns full residual collateral v to borrower (minus configured fees).

Intuition: this is the canonical "no stranded collateral" path before maturity.

Post-maturity operations (t\ge T)

At maturity, V1 settlement semantics remain. Controller primarily handles accounting and residual distribution.

Maturity Freeze

For each position at t\ge T:

  1. No new borrow/increase operations.

  2. Soft liquidation is disabled (V1 pay is pre-maturity only).

  3. Snapshot (d_T,q_T,v_T).

Intuition: maturity is the cutoff; positions stop being dynamically repaired.

Borrower-Side Finalization

  • Remaining buffer v_T is returned to borrower (or reserved for protocol penalties if configured).

  • Any remaining q_T>0 means borrower did not fully close pre-maturity; that collateral stays in pair reserves and is consumed by V1 maturity settlement.

Intuition: post-maturity, borrower no longer manages due terms; outcome is transferred into claim settlement.

Lender/LP Settlement (unchanged from V1)

Controller does not alter V1 payout equations:

  1. Lenders burn (b_P,b_I,i_P,i_I) in withdraw to receive asset/collateral by waterfall.

  2. LPs burn liquidity in burn to receive residual asset/collateral + accrued fees.

Intuition: stage-2 controller improves pre-maturity debt quality, but final payout ordering remains identical to V1.

Why this helps

Compared to pure V1:

  1. Adds market-value risk guardrails (oracle-based CR thresholds).

  2. Reduces sudden maturity shortfall by continuous pre-maturity deleveraging.

  3. Preserves existing Timeswap pricing/invariant and claim waterfall.

Tradeoff: extra complexity and oracle/execution risk; these must be managed with oracle staleness checks, swap slippage bounds, and keeper incentives.

Minimal parameter set

  • \theta_{open}=2.00

  • \theta_{soft}=1.50

  • \theta_{target}=1.75

  • h (haircut)

  • max soft-liquidation step per call

  • max allowed slippage for collateral sale

  • oracle heartbeat/staleness/deviation limits

This is sufficient to implement a practical stage-2 “soft liquidation controller” over V1 pools.

2 Likes