Variable Reference Guide
Understanding Twyne’s mechanics requires navigating between mathematical theory and practical implementation. This reference guide serves as your “Rosetta Stone” for translating between the whitepaper’s elegant mathematical notation, the litepaper’s simplified expressions, and the Solidity code’s implementation details.
Why This Guide Exists
When building DeFi protocols, we often face a fundamental tension between mathematical clarity and implementation practicality. The whitepaper uses notation like C, B, and C_LP because these symbols create clean, readable equations. However, Solidity code must handle precision issues, gas optimization, and naming conventions that make sense to developers. This guide bridges that gap, helping you understand how theoretical concepts map to actual code.
Core Position Variables
These variables define the fundamental state of any position in Twyne. Think of them as the “atoms” from which all other calculations are built.
Collateral (User’s Own Assets)
| Context | Notation | Description |
|---|---|---|
| Whitepaper | C |
User’s collateral deposited in their Collateral Vault |
| Litepaper | C |
Simplified notation matching whitepaper |
| Solidity | userCollateral or borrowerAssets |
Actual collateral owned by the borrower, excluding any reserved credit |
| Plain English | The borrower’s own assets used as collateral, not including borrowed credit from CLPs |
Implementation Note: In Solidity, this value is often calculated as totalAssets - reservedCredit rather than stored directly, which helps maintain consistency as interest accrues.
Borrowed Amount (External Debt)
| Context | Notation | Description |
|---|---|---|
| Whitepaper | B |
User’s borrowed amount from external lending protocol |
| Litepaper | B |
Outstanding external borrow |
| Solidity | externalDebt or targetDebt |
Amount owed to the underlying lending protocol (e.g., Euler) |
| Plain English | The actual debt the borrower owes to the external lending market |
Implementation Note: This value includes accrued interest and is denominated in the borrowed asset (e.g., USDC).
Reserved Credit (CLP Assets)
| Context | Notation | Description |
|---|---|---|
| Whitepaper | C_LP |
Credit reserved from Intermediate Vault |
| Litepaper | C_LP |
Outstanding CLP collateral being reserved |
| Solidity | reservedCredit or intermediateVaultAssets |
Amount borrowed from the Credit Vault to boost position |
| Plain English | The extra collateral borrowed from Credit LPs to increase borrowing power |
Implementation Note: This is tracked separately to ensure proper interest accrual and ownership accounting.
Total Collateral
| Context | Notation | Description |
|---|---|---|
| Whitepaper | C_total or C + C_LP |
Total collateral as seen by external protocol |
| Litepaper | Not explicitly defined | Implicit in calculations |
| Solidity | totalAssetsDepositedOrReserved or totalAssets |
Sum of user collateral and reserved credit |
| Plain English | The total collateral backing the position from the external protocol’s perspective |
Key Relationship: totalAssets = userCollateral + reservedCredit
Loan-to-Value (LTV) Parameters
These parameters control when positions can be liquidated and how much can be borrowed. Understanding their relationships is crucial for grasping Twyne’s dual-LTV system.
Twyne LTV (User Perspective)
| Context | Notation | Description |
|---|---|---|
| Whitepaper | λ_t |
Twyne loan-to-value ratio |
| Litepaper | λ_twyne |
Simplified notation |
| Solidity | twyneLTV |
Calculated as externalDebt / userCollateral |
| Plain English | The borrower’s effective LTV considering only their own collateral |
Formula: λ_t = B / C
External LTV (Protocol Perspective)
| Context | Notation | Description |
|---|---|---|
| Whitepaper | λ_e |
External loan-to-value ratio |
| Litepaper | λ_ext |
External protocol’s view |
| Solidity | externalLTV |
Calculated as externalDebt / totalAssets |
| Plain English | How the external lending protocol sees the position’s LTV |
Formula: λ_e = B / (C + C_LP)
Twyne Liquidation LTV
| Context | Notation | Description |
|---|---|---|
| Whitepaper | λ̃_t |
Twyne liquidation LTV threshold (tilde indicates liquidation) |
| Litepaper | λ^liq_twyne |
User-selected liquidation parameter |
| Solidity | twyneLiqLTV or liqLTV |
Stored as basis points (e.g., 8500 = 85%) |
| Plain English | The Twyne LTV at which the position becomes liquidatable internally |
Implementation Note: Users select this value within protocol-defined bounds.
Maximum Twyne Liquidation LTV
| Context | Notation | Description |
|---|---|---|
| Whitepaper | λ̃^max_t |
Maximum allowed Twyne liquidation LTV |
| Litepaper | λ^liq_max_twyne |
Protocol-enforced upper bound |
| Solidity | maxTwyneLiqLTV |
Stored in VaultManager per collateral type |
| Plain English | The highest liquidation LTV a user can select for their position |
External Protocol Liquidation LTV
| Context | Notation | Description |
|---|---|---|
| Whitepaper | λ̃_e |
External protocol’s liquidation threshold |
| Litepaper | λ^liq_ext |
Underlying protocol’s liquidation LTV |
| Solidity | externalLiqLTV or underlyingLiquidationLTV |
Retrieved from external protocol |
| Plain English | The LTV at which the external protocol (e.g., Euler) would liquidate |
Important: This includes consideration of both collateral types when different assets are involved.
Safety and Buffer Parameters
These parameters ensure Twyne triggers liquidations before the external protocol, protecting Credit LPs from losses.
Safety Buffer
| Context | Notation | Description |
|---|---|---|
| Whitepaper | β_safe |
Safety buffer below external liquidation |
| Litepaper | β_safe |
Safety buffer below external liquidation |
| Solidity | safetyBuffer or externalLiqBuffer |
Typically 0.95-0.99 (95%-99%) |
| Plain English | How much “breathing room” to maintain below external liquidation threshold |
Dynamic Safety Buffer
| Context | Notation | Description |
|---|---|---|
| Whitepaper | β_dyn_safe |
User-specific dynamic safety buffer |
| Litepaper | Not covered | Advanced topic |
| Solidity | Calculated inline | Adjusts based on user’s risk level |
| Plain English | An adaptive safety margin that increases for riskier positions | Currently NOT implemented in Solidity code |
Formula: β_dyn_safe = max(ρ, β_safe) where ρ = λ̃_t / λ̃_max_t
Interest Rate Parameters
These control how much borrowers pay for using CLP credit and how much CLPs earn.
Utilization Rate
| Context | Notation | Description |
|---|---|---|
| Whitepaper | u |
Credit utilization ratio |
| Litepaper | u |
Fraction of CLP funds in use |
| Solidity | utilization |
Calculated as totalReserved / totalSupplied |
| Plain English | What percentage of available CLP funds are currently being used |
Interest Rate Function
| Context | Notation | Description |
|---|---|---|
| Whitepaper | IR(u) |
Curved interest rate model |
| Litepaper | IR(u) |
Simplified presentation |
| Solidity | computeInterestRate() |
Implemented in TwyneIRM contract |
| Plain English | The function that determines interest rates based on utilization |
Siphoning Rate
| Context | Notation | Description |
|---|---|---|
| Whitepaper | r_C |
Rate at which collateral is “siphoned” to CLPs |
| Litepaper | r_C |
Borrower’s interest payment rate |
| Solidity | siphonRate or calculated inline |
Affects collateral ownership over time |
| Plain English | The interest rate borrowers pay on reserved CLP funds |
Precision and Implementation Considerations
When working with Twyne’s codebase, keep these implementation details in mind:
Basis Points vs Decimals
- Theory: Uses decimals (0.85 for 85%)
- Solidity: Uses basis points (8500 for 85%) to avoid precision loss
- Conversion: Multiply decimals by 10,000 for basis points
Fixed-Point Arithmetic
- Most calculations use 18 decimal places (1e18 = 1.0)
- This prevents rounding errors in division operations
- Always scale appropriately when interfacing with external protocols
Rounding Direction
- User collateral calculations: Round down (conservative for protocol)
- Required credit calculations: Round up (ensures sufficient backing)
- Interest calculations: Follow specific rules to prevent exploitation
Common Formula Transformations
The Solidity code often rearranges theoretical formulas for precision. Here are key examples:
Credit Reservation Invariant
Theoretical (Whitepaper Equation 7):
C_LP = C * (λ̃_t / (β_safe * λ̃_e) - 1)
Solidity Implementation:
requiredCredit = userCollateral * twyneLiqLTV / (safetyBuffer * externalLiqLTV - twyneLiqLTV)
The rearrangement avoids intermediate division that could lose precision.
Excess Credit Calculation
Theoretical:
C_excess = C_LP - C_ideal_LP
Solidity Implementation:
excessCredit = totalAssets > requiredTotal ? totalAssets - requiredTotal : 0
The ternary operator prevents underflow while maintaining clarity.
Using This Guide
When reading Twyne documentation or code:
- Start with the concept - Understand what the variable represents
- Check the context - Different documents use different notation
- Note the units - Basis points vs decimals, asset units vs USD
- Consider precision - Implementation may rearrange formulas
- Follow the relationships - Many variables are derived from others
This guide will be updated as new variables are introduced or naming conventions evolve. When in doubt, the Solidity implementation is the source of truth for how calculations are performed on-chain.