IVaultHandler

Abstract Contract in charge of handling the collateral and the minting of the TCAP Token.

Code

IVaultHandler.sol

Address

Mainnet

ContractAddress
ETH VaultHandler0x717170b66654292dfbd89c39f5ae6753d2ac1381
DAI VaultHandler0x443366a7a5821619d8d57405511e4fadd9964771

Rinkeby

ContractAddress
ETH VaultHandler0x16Ab98d9B7753D6c5da7c29Db6E3d51Abc76BE35
WBTC VaultHandler0x82658c3a6a264E18B477cFe07e73423eaa147214
DAI VaultHandler0x8eD3A1A6221c9B6DA1Af4F21dD98646137bCa5ad

ERC165 Introspection

initialize.selector ^
setRatio.selector ^
setBurnFee.selector ^
setLiquidationPenalty.selector ^
pause.selector ^
unpause.selector => 0x9e75ab0c

The computed interface ID according to ERC-165. The interface ID is a XOR of all interface method selectors.

Vault

struct Vault {
uint256 Id;
uint256 Collateral;
uint256 Debt;
address Owner;
}

Vault object created to manage the mint and burns of TCAP tokens with the following variables:

  • Id: unique identifier of the vault.
  • Collateral: current collateral on vault.
  • Debt: current amount of TCAP tokens minted.
  • Owner: owner of the vault.

Public Variables

Counters.Counter public counter;

Vault Id counter.

TCAP public immutable TCAPToken;

TCAP Token Address.

ChainlinkOracle public immutable tcapOracle;

Total Market Cap/USD Oracle Address.

IERC20 public immutable collateralContract;

Collateral Token Address.

ChainlinkOracle public immutable collateralPriceOracle;

Collateral/USD Oracle Address.

ChainlinkOracle public immutable ETHPriceOracle;

ETH/USD Oracle Address.

uint256 public divisor;

Value used as divisor with the total market cap, just like the S&P 500 or any major financial index would to define the final tcap token price.

uint256 public ratio;

Minimun ratio required to prevent liquidation of vault.

uint256 public burnFee;

Fee percentage of the total amount to burn charged on ETH when burning TCAP Tokens.

uint256 public liquidationPenalty;

Penalty charged to vault owner when a vault is liquidated, this value goes to the liquidator.

IRewardHandler public immutable rewardHandler;

Address of the contract that gives rewards to minters of TCAP, rewards are only given if address is set before minting.

address public treasury;

Address of the treasury multisign contract that allows the multisign to control the rewards and funds generated by the protocol.

mapping(address => uint256) public userToVault;

Owner address to Vault Id mapping.

mapping(uint256 => Vault) public vaults;

Id To Vault mapping.

uint256 public constant oracleDigits = 10000000000;

Value used to multiply chainlink oracle for handling decimals.

uint256 public constant MIN_RATIO = 150;

Minimum value that the ratio can be set to.

uint256 public constant MAX_FEE = 10;

Maximum value that the burn fee can be set to.

Private Variables

bytes4 private constant _INTERFACE_ID_IVAULT = 0x9e75ab0c;

The computed interface ID according to ERC-165. Indicates if this contract supports the vault handler functions.

bytes4 private constant _INTERFACE_ID_TIMELOCK = 0x6b5cc770;

The computed interface ID according to ERC-165. Indicates if this contract supports the timelock functions.

bytes4 private constant _INTERFACE_ID_ERC165 = 0x01ffc9a7;

The computed interface ID according to ERC-165. Indicates if this contract supports the ERC165 interface.

Events

Events are called each time the state changes on the contract.

event NewRatio(address indexed _owner, uint256 _ratio);

An event emitted when the ratio is updated.

event NewBurnFee(address indexed _owner, uint256 _burnFee);

An event emitted when the burn fee is updated.

event NewLiquidationPenalty(
address indexed _owner,
uint256 _liquidationPenalty
);

An event emitted when the liquidation penalty is updated.

event NewTreasury(address indexed _owner, address _tresury);

An event emitted when the treasury contract is updated.

event VaultCreated(address indexed _owner, uint256 indexed _id);

An event emitted when a vault is created.

event CollateralAdded(
address indexed _owner,
uint256 indexed _id,
uint256 _amount
);

An event emitted when collateral is added to a vault.

event CollateralRemoved(
address indexed _owner,
uint256 indexed _id,
uint256 _amount
);

An event emitted when collateral is removed from a vault.

event TokensMinted(
address indexed _owner,
uint256 indexed _id,
uint256 _amount
);

An event emitted when tokens are minted.

event TokensBurned(
address indexed _owner,
uint256 indexed _id,
uint256 _amount
);

An event emitted when tokens are burned.

event VaultLiquidated(
uint256 indexed _vaultId,
address indexed _liquidator,
uint256 _liquidationCollateral,
uint256 _reward
);

An event emitted when a vault is liquidated.

event Recovered(address _token, uint256 _amount);

An event emitted when a erc20 token is recovered.

Modifiers

vaultExists

modifier vaultExists();

Throws if vault hasn't been created.

notZero

modifier notZero(uint256 _value);

Throws if value is 0.

Read-Only Functions

supportsInterface

function supportsInterface(bytes4 interfaceId)
external
override
view
returns (bool);

ERC165 Standard for support of interfaces.

getVault

function getVault(uint256 _id)
external
view
virtual
returns (uint256,uint256,address,uint256);

Returns the Vault information of specified _id.

getOraclePrice

function getOraclePrice(ChainlinkOracle _oracle)
public
view
virtual
returns (uint256 price);

Returns the price of the chainlink oracle multiplied by the digits to get 18 decimals format.

TCAPPrice

function TCAPPrice() public view virtual returns (uint256 price);

Returns the price of the TCAP token in 18 decimals. The formula for calculating the price is:

PP = Td\frac{T}{d}

Where

PP = TCAP Token Price

TT = Total Crypto Market Cap

dd = Divisor

The oracle Total Crypto Market Cap is in wei format.

requiredCollateral

function requiredCollateral(uint256 _amount)
public
view
virtual
returns (uint256 collateral);

Returns the minimal required collateral to mint TCAP token. The formula for calculating the required collateral is:

CC = (Pโˆ—Aโˆ—r)/100cp\frac{(P * A * r) / 100}{cp}

Where

CC = Required Collateral

PP = TCAP Token Price

AA = Amount to Mint

cpcp = Collateral Price

It's divided by 100 as eth price comes in wei to cancel the additional 0s

requiredLiquidationTCAP

function requiredLiquidationTCAP(uint256 _vaultId)
public
view
virtual
returns (uint256 amount)

Returns the minimal required TCAP to liquidate a Vault. The formula for calculating the required collateral is:

LTLT = (((Dโˆ—r)/100)โˆ’cTcap)โˆ—100(rโˆ’(p+100))\frac{(((D * r) / 100) - cTcap) * 100}{ (r - (p + 100))}

cTcapcTcap = Cโˆ—cpP\frac{C*cp}{P}

Where

LTLT = Required Liquidation Collateral

DD = Vault Debt

CC = Required Collateral

PP = TCAP Token Price

cpcp = Collateral Price

rr = Min Vault Ratio

pp = Liquidation Penalty

liquidationReward

function liquidationReward(uint256 _vaultId)
public
view
virtual
returns (uint256 rewardCollateral);

Returns the reward for liquidating a vault, the reward is taken from the collateral staked on the liquidated vault. The formula for calculating the reward is:

RR = (LTโˆ—(p+100))100\frac{(LT * (p + 100))} {100}

Where

RR = Liquidation Reward

LTLT = Required Liquidation TCAP

pp = Liquidation Penalty

getVaultRatio

function getVaultRatio(uint256 _vaultId)
public
view
virtual
returns (uint256 currentRatio);

Returns the Collateral Ratio fo the Vault. The formula for calculating the ratio is:

vrvr = cpโˆ—Cโˆ—100Dโˆ—P\frac{cp * C * 100}{D * P}

Where

vrvr = Vault Ratio

CC = Vault Collateral

cpcp = Collateral Price

DD = Vault Debt

PP = TCAP Token Price

getFee

function getFee(uint256 _amount) public virtual view returns (uint256 fee);

Returns the required fee of ETH to burn the TCAP tokens. The formula for calculating the burning fee is:

ff = ((Pโˆ—Aโˆ—b)/100EP\frac{((P * A * b)/100}{EP}

ff = Burn Fee Value

PP = TCAP Token Price

AA = Amount to Burn

bb = Burn Fee %

EPEP = ETH Price

State-Changing Functions

constructor

constructor(
Orchestrator _orchestrator,
uint256 _divisor,
uint256 _ratio,
uint256 _burnFee,
uint256 _liquidationPenalty,
address _tcapOracle,
TCAP _tcapAddress,
address _collateralAddress,
address _collateralOracle,
address _ethOracle,
address _rewardHandler,
address _treasury
);

Called once the contract it's deployed, sets the orchestrator as owner. It also sets the vault counter to 1 as 0 is reserved for empty objects.

setRatio

function setRatio(uint256 _ratio) external virtual onlyOwner;

Sets the collateral ratio needed to mint tokens. Only owner can call it.

setBurnFee

function setBurnFee(uint256 _burnFee) external virtual onlyOwner;

Sets the burn fee percentage an user pays when burning tcap tokens

setLiquidationPenalty

function setLiquidationPenalty(uint256 _liquidationPenalty)
external
virtual
onlyOwner;

Sets the liquidation penalty % charged on liquidation. Only owner can call it. recommended value is between 1-15% and can't be above 100%.

setTreasury

function setTreasury(address _treasury) external virtual onlyOwner

Sets the treasury contract address where fees are transfered to. Only owner can call it

createVault

function createVault() public virtual whenNotPaused;

Allows sender to creates a Vault with an unique ID. Only one vault per address can be created.

addCollateral

function addCollateral(uint256 _amount)
external
virtual
nonReentrant
vaultExists
whenNotPaused
notZero(_amount);

Adds collateral to vault,_amount should be higher than 0.

removeCollateral

function removeCollateral(uint256 _amount)
external
virtual
nonReentrant
vaultExists
whenNotPaused
notZero(_amount);

Allows users to remove collateral currently not being used to generate TCAP tokens from their vaults. _amount should be higher than 0. Reverts if the resulting ratio is less than the minimun ratio.

mint

function mint(uint256 _amount)
external
virtual
nonReentrant
vaultExists
whenNotPaused
notZero(_amount)

Uses collateral to generate debt on TCAP Tokens which are minted and assigend to caller. _amount should be higher than 0. Requires to have a vault ratio above the minimum ratio.

burn

function burn(uint256 _amount)
external
payable
virtual
nonReentrant
vaultExists
whenNotPaused
notZero(_amount);

Pays the debt of TCAP tokens resulting them on burn, this releases collateral up to minimun vault ratio._amount should be higher than 0. A fee on ETH must be paid when executing a TCAP burn, the fee is a % defined by the contract burnFee of the _amount of TCAP tokens to burn. The fee goes to the treasury contract. if reward handler is set exit rewards.

liquidateVault

function liquidateVault(uint256 _vaultId, uint256 _requiredTCAP)
external
payable
nonReentrant
whenNotPaused

Allow users to burn TCAP tokens to liquidate vaults with current vault collateral ratio under the minium ratio, the liquidator receives the staked collateral of the liquidated vault at a premium.Resulting ratio must be above or equal minimun ratio. The fee goes to the treasury contract.

pause

function pause() external onlyOwner;

Allows the owner to Pause the Contract.

unpause

function unpause() external onlyOwner;

Allows owner to Unpause the Contract.

recoverERC20

function recoverERC20(address _tokenAddress, uint256 _tokenAmount)
external
onlyOwner;

Added to support recovering LP Rewards from other systems such as BAL to be distributed to holders.

safeTransferETH

function safeTransferETH(address _to, uint256 _value) internal;

Allows the safe transfer of ETH.

_burn

function _burn(uint256 _vaultId, uint256 _amount) internal;

Internal function that burns the _amount of TCAP Tokens, called by the burn and liquidateVault functions.