Architecture

Multiple such systems can operate independently

Contracts

Credit Vault

• Deployed by Twyne
• Unmodified Euler EVault based on EVK, so has 1 asset that can be lent/borrowed. This asset can be used as a collateral in some lending market. For instance, we use eulerWETH as an asset which is a collateral asset to borrow USDC from Euler’s eUSDC vault.
• Only collateral vaults can borrow from intermediate vaults.

Collateral Vault

• Deployed by the borrower via factory
• At the time of deployment, the user specifies the collateral asset, external lending contract and liquidation LTV
• The factory then
  1. picks the intermediate vault based on the collateral asset.
  2. deploys collateral vault and configure it with the borrower-supplied parameters (collateral asset, external lending contract and liquidation LTV).
  3. configures intermediate vault (setLTV()) so that collateral vault can borrow from it with collateral vault’s own shares as collateral.
• Each collateral vault has one borrower, but a borrower may have multiple collateral vaults. So borrower to collateral vaults is a one-to-many relationship.

Terminology

• Borrow and repay: If used standalone, these terms always refer to borrowing/repaying debt from/to the external lending market.
• Reserve and release: These terms always refer to borrowing/repaying debt (aka credit) from/to the intermediate vault.

Collateral vault enables borrowers to deposit and withdraw collateral, interact with intermediate vault (to reserve and release credit from LPs) and external lending protocol (to borrow and repay debt).

User types

Credit Liquidity Provider (LP)

A credit LP is an entity looking to earn yield. They are likely to be lenders on existing lending markets maintaining low LTV, thus indicating they don’t borrow and are just earning yield on their assets.

They deposit their assets (eulerWETH) to an intermediate vault to earn a higher yield.

Possible Credit LP actions

• Deposit asset in an intermediate vault and receive vault shares.
• Withdraw asset from an intermediate vault by burning vault shares.

Borrower

A borrower on Twyne is an entity either looking to borrow more aggressively than allowed on existing lending markets, or looking to protect their borrow position from liquidation.

They deploy collateral vaults to deposit collateral (eulerWETH), reserve credit (eulerWETH) from intermediate vault, and borrow (USDC) from the pre-determined external lending market (Euler).

Possible Borrower actions

• Deploy a collateral vault via factory. A collateral vault is configured with the collateral asset, intermediate vault and external lending contract.
• Deposit asset as collateral (eulerWETH) into the collateral vault, reserve credit (eulerWETH) from intermediate vault, and borrow (USDC) from external lending contract. A borrower pays the following interest rates:
  1. Interest to the external lending protocol on the borrowed amount. This interest accumulation is handled by the external lending contract.
  2. Interest to the intermediate vault. This is handled by the collateral vault and the ownership of portion of borrower’s collateral is continuously siphoned off to the intermediate vault.
• Withdraw collateral from the collateral vault, release credit back to intermediate vault, and repay debt to the external lending market.
• Update collateral vault’s liquidation LTV.

Collateral Vault (again)

With the above context, we can look into the collateral vault with more depth.

A collateral vault:

• deposits and withdraws collateral from the borrower
• reserves and releases credit (same asset as collateral) from the intermediate vault
• borrows and repays debt to the external lending contract.

How much can be borrowed and reserved depends on our invariants. The key requirement is the vault must not be liquidatable, and the details of Twyne liquidation mechanics are explained here.

A collateral vault can also be liquidated:

• Liquidated by Twyne
• Externally liquidated (on the underlying protocol)

Collateral vault can also be rebalanced. This is an action of releasing excess credit back to the intermediate vault. Further details on how rebalancing works are in the mechanics section.