TimeMint: Timeswap V1 - A Mathematical Description

General
1

TimeMint: Timeswap V1 - A Mathematical Description

This is part of Document 1 of the the TimeMint Series.

A Heavyweight Guidance

This document describes Timeswap V1 at the mechanism level (state variables, invariants, and payoff equations), abstracted away from the original Timeswap V1 Solidity implementation details.

State and notation

For each maturity timestamp T, Timeswap maintains an independent pool state:

  • Constant-product state: (x, y, z)

  • Reserves: (A, C) where:

  • A: asset reserve

  • C: collateral reserve

  • Liquidity supply: L

  • Fee accumulator for LPs: F_{LP}

  • Protocol fee accumulator: F_P

  • Aggregate claims outstanding:

  • bond principal B_P, bond interest B_I

  • insurance principal I_P, insurance interest I_I

A borrower due is a tuple (d, q):

  • d: remaining debt in asset units

  • q: remaining collateral claim

Let t be current time, \tau = T-t, and constants:

  • k_F = 2^{40} (fee fixed-point scale)

  • k_y = 2^{32} (interest-time scale)

  • k_z = 2^{25} (collateral/insurance-time scale)

  • k_L = 2^{16} (initial liquidity scale)

  • k_m = 2^{4} (minimum-interest scaling, i.e. divide by 16)

Fee parameters are per-second fixed-point values f and p (LP fee and protocol fee), with f+p used in trade fee adjustment.

Rounding operators used by the protocol:

  • \lfloor \cdot \rfloor: floor

  • \lceil \cdot \rceil: ceil

Core invariant

For admissible state transitions before maturity, the pool enforces:

x' y' z' \ge xyz

This is the central Timeswap V1 invariant (product non-decreasing).

Pre-maturity operations

LP Mint

State move:

x' = x + \Delta x,\quad y' = y + \Delta y,\quad z' = z + \Delta z

Liquidity minted:

  • If L=0:
\Delta L = \Delta x\cdot k_L
  • Else:
\Delta L_x = \Big\lfloor L\frac{\Delta x}{x}\Big\rfloor,\; \Delta L_y = \Big\lfloor L\frac{\Delta y}{y}\Big\rfloor,\; \Delta L_z = \Big\lfloor L\frac{\Delta z}{z}\Big\rfloor

with constraints \Delta L_y\le\Delta L_x, \Delta L_z\le\Delta L_x, and

\Delta L = \min(\Delta L_y,\Delta L_z)

LP fee-share checkpoint increase:

\Delta F_{LP}^{(mint)} = \Big\lceil F_{LP}\frac{\Delta L}{L}\Big\rceil

A new due (d,q) is created:

d = \Delta x + \Big\lceil \frac{\tau\,\Delta y}{k_y} \Big\rceil
q = \Delta z + \Big\lceil \frac{\tau\,\Delta z}{k_z} \Big\rceil

Short explanation: LP mint is dual-purpose, producing both liquidity shares and a borrower due.

For existing pools, \Delta L_y and \Delta L_z are the linearized partial-derivative share terms of the xyz geometry (in y and z, respectively), and \Delta L=\min(\Delta L_y,\Delta L_z) enforces the tightest admissible joint contribution.

Lend

Input: \Delta x>0, \Delta y\ge0, \Delta z\ge0 interpreted as

x' = x + \Delta x,\quad y' = y - \Delta y,\quad z' = z - \Delta z

Constraints:

  1. Invariant: x'y'z'\ge xyz

  2. Minimum interest reduction:

\Delta y \ge \Big\lfloor \frac{1}{k_m}\cdot \frac{\Delta x\,y}{x+\Delta x} \Big\rfloor

Claims minted by lend:

b_P = \Delta x
b_I = \Big\lfloor \frac{\tau\,\Delta y}{k_y} \Big\rfloor
i_P = \Big\lfloor \frac{z\,\Delta x}{x+\Delta x} \Big\rfloor
i_I = \Big\lfloor \frac{\tau\,\Delta z}{k_z} \Big\rfloor

where (b_P,b_I) are bond claims and (i_P,i_I) are insurance claims.

Fee assessed on lender (total):

\Delta F_{tot}^{(lend)}= \Big\lceil \Delta x\cdot\frac{k_F+\tau(f+p)}{k_F}\Big\rceil-\Delta x

Split:

\Delta F_{LP}^{(lend)}=\Big\lfloor\Delta F_{tot}^{(lend)}\frac{f}{f+p}\Big\rfloor, \quad \Delta F_{P}^{(lend)}=\Delta F_{tot}^{(lend)}-\Delta F_{LP}^{(lend)}

Short explanation: lending moves the pool toward lower y,z in exchange for upfront asset input, and mints two claims: bond (asset-side repayment) and insurance (collateral-side protection if asset repayment is insufficient at maturity).

Borrow

Input: \Delta x>0, \Delta y\ge0, \Delta z\ge0 interpreted as

x' = x - \Delta x,\quad y' = y + \Delta y,\quad z' = z + \Delta z

Constraints:

  1. Invariant: x'y'z'\ge xyz

  2. Upper bounds:

\Delta y \le \Big\lceil \frac{\Delta x\,y}{x-\Delta x} \Big\rceil, \quad \Delta z \le \Big\lceil \frac{\Delta x\,z}{x-\Delta x} \Big\rceil
  1. Lower bound (anti-degenerate pricing):
\Delta y \ge \Big\lceil \frac{1}{k_m}\cdot\Big\lceil \frac{\Delta x\,y}{x-\Delta x} \Big\rceil \Big\rceil

Borrower due created:

d = \Delta x + \Big\lceil \frac{\tau\,\Delta y}{k_y} \Big\rceil
q = \Big\lceil \frac{\tau\,\Delta z}{k_z} \Big\rceil + \Big\lceil \frac{z\,\Delta x}{x-\Delta x} \Big\rceil

Borrow trade fee (total):

\Delta F_{tot}^{(borrow)}= \Delta x-\Big\lfloor \Delta x\cdot\frac{k_F}{k_F+\tau(f+p)}\Big\rfloor

Split exactly as in lend by f:(f+p).

Net asset sent to borrower:

\text{assetOut}=\Delta x-\Delta F_{tot}^{(borrow)}

Short explanation: borrowing moves the pool in the opposite direction of lending, gives immediate asset out, and creates a due (d,q) that records required asset repayment and locked collateral.

Pay

For each selected due (d_i,q_i), payer chooses (a_i,c_i) with:

a_i q_i \ge c_i d_i

and updates:

d_i \leftarrow d_i-a_i, \quad q_i \leftarrow q_i-c_i

Short explanation: pay is a monotone deleveraging step; each repayment reduces debt and can only release collateral at or below the due-implied ratio. If payer is not due owner, protocol only allows c_i=0.

Post-maturity claim settlement

Let totals:

B=B_P+B_I, \quad I=I_P+I_I

Withdraw

Given user claims (b_P,b_I,i_P,i_I), where:

  • b_P: user bond principal claim

  • b_I: user bond interest claim

  • i_P: user insurance principal claim

  • i_I: user insurance interest claim

If A\ge B:

\text{assetOut}=b_P+b_I, \quad \text{collateralOut}=0

If A<B, define deficit D=B-A.

Asset side:

  • If A\ge B_P:
\text{assetOut}=b_P + b_I\frac{A-B_P}{B_I}
  • Else:
\text{assetOut}=b_P\frac{A}{B_P}

Collateral side is insurance waterfall:

  • If CB\ge D(I_P+I_I):
\text{collateralOut}=(i_P+i_I)\frac{D}{B}

  • Else if CB\ge DI_P: principal fully covered, interest partially covered

  • Else: insurance principal itself is pro-rata impaired

(All divisions use integer truncation in implementation; economically this is the piecewise proportional waterfall above.)

LP Burn

Given \ell liquidity burned:

LP fee payout:

\text{feeOut}=F_{LP}\frac{\ell}{L}

Principal/collateral payout:

  • If A\ge B:
\text{assetOut}=(A-B)\frac{\ell}{L}, \quad \text{collateralOut}=C\frac{\ell}{L}

  • If A<B: let D=B-A

  • If CB>D(I_P+I_I):

\text{collateralOut}= \Big(C-\Big\lceil\frac{D(I_P+I_I)}{B}\Big\rceil\Big)\frac{\ell}{L}
  • Else: \text{assetOut}=\text{collateralOut}=0 (LP residual exhausted by lender protection waterfall)

Economic interpretation

  • x: asset-side state that moves opposite for lenders vs borrowers.

  • y: interest state; changing y determines debt/bond interest via \tau/k_y.

  • z: collateralization/insurance state; changing z determines collateral and insurance via \tau/k_z.

  • Lenders receive two legs: bond claim (asset-side) and insurance claim (collateral-side).

  • Borrowers create dues (d,q), can repay before maturity, and can only withdraw collateral in proportion to repayment.

  • At maturity, asset shortfall D is allocated first by reducing bond recoveries, then compensated through insurance collateral waterfall; LP residual is junior to that waterfall.

Source basis

Formulas in this note are reconstructed from Timeswap V1 Core repository logic:

  • contracts/libraries/TimeswapMath.sol

  • contracts/libraries/ConstantProduct.sol

  • contracts/TimeswapPair.sol

  • contracts/interfaces/IPair.sol

  • test math mirrors under test/libraries/*.ts