TinteroLoan

​

TinteroLoan

• CREATED: The loan has been initialized and payments or tranches are being added.
• CANCELED: The loan has been canceled and the collateral is being withdrawn.
• FUNDING: The loan is being funded by the liquidity provider.
• ONGOING: The loan has been funded and the payments are being repaid.
• DEFAULTED: The loan has defaulted and the collateral can be repossessed.
• REPOSSESSED: The collateral is being repossessed by the liquidity provider.
• PAID: The loan has been fully repaid.

​

Concepts

• Payments: A payment is a structure that represents a payment to be made back to the loan. Each payment has a principal amount and an interest rate that is accrued over time in a linear fashion. A premium rate is added to the interest rate after the payment is due (at maturity).
• Tranches: A tranche is a collection of payments that have the same recipient. They are used to sell parts of the loan to different investors.
• Collateral: The collateral is an ERC721 token that is used to back the payments. A payment’s collateral can be repossessed if the loan defaults after a default threshold.

​

Functions

​

onlyLiquidityProvider

modifier onlyLiquidityProvider();

​

onlyBeneficiary

modifier onlyBeneficiary();

​

constructor

constructor();

​

initialize

function initialize(
    address liquidityProvider_,
    address collateralAsset_,
    address beneficiary_,
    uint24 defaultThreshold_
) public initializer;

​

pushPayments

• The caller MUST be the liquidity provider.
• The loan MUST be in CREATED state.
• The collateral tokenIds and payments arrays MUST have the same length.
• The payments MUST be ordered by maturity date.
• The payments MUST NOT have matured.
• The collateral tokenIds MUST NOT have been added before.
• The collateralTokenIds MUST exist.
• The owner of each collateral tokenId MUST have approved this contract to transfer it (if not the contract itself).

• The totalPayments is incremented by the length of the payments array.
• The collateralTokenIds are transferred to this contract.
• The payment function will return the added payments at their corresponding indexes starting at totalPayments.
• Emits a PaymentCreated event for each payment added.*

function pushPayments(uint256[] calldata collateralTokenIds, PaymentLib.Payment[] calldata payment_)
    external
    onlyLiquidityProvider
    returns (uint256 principalRequested);

​

pushTranches

• The caller MUST be the liquidity provider.
• The loan MUST be in CREATED state.
• The paymentIndexes and recipients arrays MUST have the same length.
• The tranche indexes MUST be strictly increasing.
• The total number of tranches MUST be less than the total number of payments.

• The totalTranches is incremented by the length of the tranches array.
• The tranche function will return the added tranches at their corresponding indexes starting at totalTranches.
• The tranches are added to the loan.
• Emits a TrancheCreated event for each tranche added.*

function pushTranches(uint96[] calldata paymentIndexes, address[] calldata recipients) external onlyLiquidityProvider;

​

fundN

• The loan MUST be in CREATED or FUNDING state.
• Tranches MUST include all payments.
• The caller MUST have enough funds to fund the payments
• This contract mus have been approved to transfer the principal amount from the caller.

• Moves to FUNDING state
• Moves to ONGOING state if all payments are funded.
• The currentFundingIndex is incremented by n or the remaining payments.
• The principal of the funded payments is transferred from the liquidity provider to the beneficiary.
• Sets the fundedAt field of the funded payments to the current block timestamp.
• Emits a PaymentsFunded event with the range of funded payments.*

function fundN(uint256 n) external returns (uint256 totalPrincipal);

​

withdrawPaymentCollateral

• The loan MUST be in CREATED or CANCELED state.
• Each payment collateral MUST be owned by this contract.
• The caller MUST be the beneficiary.

• Moves to CANCELED state.
• Each payment collateral is transferred to the beneficiary.
• Emits a PaymentsWithdrawn with the range of payments withdrawn*

function withdrawPaymentCollateral(uint256 start, uint256 end) external onlyBeneficiary;

​

repayCurrent

function repayCurrent(address collateralReceiver) external;

​

repayN

• The loan MUST be in ONGOING or DEFAULTED state.
• The sender MUST have enough funds to repay the principal of the specified payments
• The sender MUST have approved this contract to transfer the principal amount
• The collateral MUST be owned by this contract.

• Moves to ONGOING if paid until below the default threshold.
• Moves to PAID state if all payments are repaid.
• The currentPaymentIndex is incremented by n or the remaining payments.
• The principal of the repaid payments is transferred from the sender to the receiver of each payment tranche
• The collateral is transferred to the collateralReceiver if provided, otherwise it is burned.
• Emits a PaymentsRepaid event with the range of repaid payments.*

function repayN(uint256 n, address collateralReceiver) public;

​

repossess

• The loan MUST be in DEFAULTED or REPOSSESSED state.
• The caller MUST be the liquidity provider.
• The collateral MUST be owned by this contract.
• The receiver MUST implement IERC721Receiver to receive the collateral.

• Moves to REPOSSESSED state.
• The collateral is transferred to the receiver.
• Emits a PaymentsRepossessed event with the range of repossessed payments.*

function repossess(uint256 start, uint256 end, address receiver) external onlyLiquidityProvider;

​

_validatePushPaymentsAndCollectCollateral

• The collateral tokenIds and payments arrays MUST have the same length.
• The payments MUST be ordered by maturity date.
• The payments fundedAt field MUST be 0.
• The payments MUST NOT have matured.
• The collateral tokenIds MUST NOT have been added before.
• The collateralTokenIds MUST exist.
• The owner of each collateral tokenId MUST have approved this contract to transfer it (if not the contract itself).

• The totalPayments is incremented by the length of the payments array.
• The collateralTokenIds are transferred to this contract.
• The payment function will return the added payments at their corresponding indexes starting at totalPayments.
• Emits a PaymentCreated event for each payment added.*

function _validatePushPaymentsAndCollectCollateral(
    uint256[] calldata collateralTokenIds_,
    PaymentLib.Payment[] calldata payments_
) internal returns (uint256);

​

_validateAndPushTranches

• The paymentIndexes and recipients arrays MUST have the same length.
• The tranche indexes MUST be strictly increasing.
• The total number of tranches MUST be less than the total number of payments.

• The totalTranches is incremented by the length of the tranches array.
• The tranche function will return the added tranches at their corresponding indexes starting at totalTranches.
• The tranches are added to the loan.
• Emits a TrancheCreated event for each tranche added.*

function _validateAndPushTranches(uint96[] calldata paymentIndexes_, address[] calldata recipients_) internal;

​

_validatePushPayment

• The payment fundedAt field MUST be 0.
• The payment maturity date MUST NOT be before the latest maturity.
• The payment MUST NOT have matured.
• The collateral tokenId MUST not have been added before.

• The totalPayments is incremented by 1.
• The payment function will return the added _payment after the current totalPayments.
• Emits a PaymentCreated event.*

function _validatePushPayment(
    uint256 i,
    uint256 largestMaturityPeriod,
    uint256 collateralTokenId,
    PaymentLib.Payment calldata payment_
) internal returns (uint256);

​

_collectCollateral

• The collateralTokenIds MUST exist.
• The owner of each collateral tokenId MUST have approved this contract to transfer it (if not the contract itself).

• The collateralTokenIds are transferred to this contract.*

function _collectCollateral(ERC721Burnable asset, uint256 tokenId) internal;

​

_fundN

• Moves to FUNDING state
• Moves to ONGOING state if all payments are funded.
• The currentFundingIndex is incremented by n or the remaining payments.
• The principal of the funded payments is transferred from the liquidity provider to the beneficiary.
• Sets the fundedAt field of the funded payments to the current block timestamp.*

function _fundN(uint256 n) internal returns (uint256);

​

_withdrawPaymentCollateral

• Each payment collateral MUST be owned by this contract.

• Moves to CANCELED state.
• The payment collateral is transferred to the beneficiary.
• Emits a PaymentsWithdrawn event.*

function _withdrawPaymentCollateral(LoanState state_, uint256 start, uint256 end) internal;

​

_repay

• The sender MUST have enough funds to repay the principal of the specified payments
• The sender MUST have approved this contract to transfer the principal amount
• The collateral MUST be owned by this contract.

• Moves to ONGOING if paid until below the default threshold.
• Moves to PAID state if all payments are repaid.
• The currentPaymentIndex is incremented by n or the remaining payments.
• The principal of the repaid payments is transferred from the sender to the receiver of each payment tranche
• The collateral is transferred to the collateralReceiver if provided, otherwise it is burned.
• Emits a PaymentsRepaid event with the range of repaid payments.*

function _repay(uint256 start, uint256 end, address collateralReceiver) internal;

​

_repossess

• The collateral MUST be owned by this contract.
• The receiver MUST implement IERC721Receiver to receive the collateral.

• Moves to REPOSSESSED state.
• The collateral is transferred to the receiver.
• Emits a PaymentsRepossessed event with the range of repossessed payments.*

function _repossess(LoanState state_, uint256 start, uint256 end, address receiver) internal;

​

upgradeLoan

function upgradeLoan(address newImplementation, bytes calldata data) external;

​

_authorizeUpgrade

function _authorizeUpgrade(address newImplementation) internal override onlyLiquidityProvider;

​

_validateStateBitmap

function _validateStateBitmap(bytes32 allowedStates) private view returns (LoanState currentState);

​

_encodeStateBitmap

0x000...10000
  ^^^^^^----- ...
        ^---- ONGOING
         ^--- DEFAULTED
          ^-- REPOSSESSED
           ^- PAID

function _encodeStateBitmap(LoanState loanState) private pure returns (bytes32);

​

_repayByTranches

• The sender MUST have enough funds to repay the principal of the specified payments
• The sender MUST have approved this contract to transfer the principal amount

• The principal of the repaid payments is transferred from the sender to the receiver of each payment tranche
• Moves to ONGOING if paid until below the default threshold.
• Moves to PAID state if all payments are repaid.
• Emits a PaymentsRepaid event with the range of repaid payments.*

function _repayByTranches(uint256 start, uint256 end) private returns (uint256 principalPaid);

​

_prepareToPay

• Moves to ONGOING if paid until below the default threshold.
• Moves to PAID state if all payments are repaid.
• Emits a PaymentsRepaid event with the range of repaid payments.*

function _prepareToPay(uint256 start, uint256 end) private returns (uint256 toPay, uint256 principalPaid);

​

_debitCollateral

• Each payment collateral MUST be owned by this contract.

• The collateral is transferred to the collateralReceiver if provided, otherwise it is burned.*

function _debitCollateral(uint256 start, uint256 end, address collateralReceiver, uint256 discountedPrincipal)
    private;

​

TinteroLoanStorage

​

State Variables

​

TINTERO_LOAN_STORAGE

bytes32 private constant TINTERO_LOAN_STORAGE = 0x1f389b2eba3c6a855b1e43cd4e972600e00166178892203933678c6474e96300;

​

Functions

​

getTinteroLoanStorage

function getTinteroLoanStorage() internal pure returns (LoanStorage storage $);

​

Structs

​

LoanStorage

struct LoanStorage {
    Checkpoints.Trace160 _tranches;
    address liquidityProvider;
    bool _canceled;
    bool _repossessed;
    address collateralAsset;
    PaymentLib.Payment[] payments;
    uint256[] collateralTokenIds;
    EnumerableSet.UintSet heldTokenIds;
    address beneficiary;
    uint24 defaultThreshold;
    uint24 currentPaymentIndex;
    uint24 currentFundingIndex;
}

​

TinteroLoanView

​

State Variables

​

INITIAL_ERC721_COLLATERAL_LOAN_IMPLEMENTATION

address public immutable INITIAL_ERC721_COLLATERAL_LOAN_IMPLEMENTATION = address(new TinteroLoan());

​

Functions

​

predictLoanAddress

function predictLoanAddress(
    address collateralCollection_,
    address beneficiary_,
    uint24 defaultThreshold_,
    bytes32 salt,
    address caller_
) public view returns (address loan, bytes memory bytecode, bytes32 bytecodeHash);

​

_deployLoan

function _deployLoan(address collateralCollection_, address beneficiary_, uint24 defaultThreshold_, bytes32 salt)
    internal
    returns (address loan);

​

_loanProxyBytecode

function _loanProxyBytecode(address collateralCollection_, address beneficiary_, uint24 defaultThreshold_)
    internal
    view
    returns (bytes memory);

​

_salt

function _salt(bytes32 salt, address caller_) internal pure returns (bytes32 value);

​

TinteroLoanFactory

​

Functions

​

lendingAsset

function lendingAsset() public view returns (IERC20);

​

collateralAsset

function collateralAsset() public view returns (ERC721Burnable);

​

liquidityProvider

function liquidityProvider() public view returns (ITinteroVault);

​

tranche

function tranche(uint256 trancheIndex) public view returns (uint96 paymentIndex, address recipient);

​

currentTrancheIndex

function currentTrancheIndex() public view returns (uint256);

​

totalTranches

function totalTranches() public view returns (uint256);

​

payment

function payment(uint256 index) public view returns (PaymentLib.Payment memory);

​

collateralId

function collateralId(uint256 index) public view returns (uint256);

​

currentPaymentIndex

function currentPaymentIndex() public view returns (uint256);

​

totalPayments

function totalPayments() public view returns (uint256);

​

currentFundingIndex

function currentFundingIndex() public view returns (uint256);

​

beneficiary

function beneficiary() public view returns (address);

​

defaultThreshold

function defaultThreshold() public view returns (uint256);

​

state

function state() public view returns (LoanState);

​

_defaulted

function _defaulted(uint256 current) internal view returns (bool);