PalPool

PalPools are the main component of the Protocol.

Each PalPool is independent and holds its own underlying ERC20 governance token.

Users can deposit the underlying token in the PalPool, receiving an amount of PalToken representing their share in the PalPool, and receive part of the fees of the PalPool.

The main use of the PalPool is to Borrow voting/proposition power. When starting a Borrow, the PalPool will create a PalLoan, by cloning the Delegator contract set in the PalPool, it will transfer the amount of tokens borrowed and the fees paid by the borrower, delegate the PalLoan voting power to the borrower, and issue a PalLoanToken to represent the ownership of the PalLoan.

The Borrow can later be extended, closed (and the unused fees will be returned to the borrower), or killed if all the fees were used. The owner of the Borrow can also change the recipient of his PalLoan voting power.

A Borrow is the data struct listed in the PalPool storage, listing all the data relative to the borrowed voting power. A PalLoan (also referred as Loan) is the contract holding the voting power, and delegating it to the given address.

Each PalLoan is linked to a Borrow, and to a PalLoanToken (ERC 721 token representing ownership of a PalLoan and its Borrow)

Methods :

Events :

Deposit

event Deposit(address user, uint amount, address palPool);

When a user deposits in the Pool.

Withdraw

event Withdraw(address user, uint amount, address palPool);

When a user withdraws from the Pool.

NewLoan

event NewLoan(address borrower, address delegatee, address underlying, uint amount, address palPool, address loanAddress, uint256 palLoanTokenId, uint startBlock);

When a Borrow is started and a PalLoan is created.

ExpandLoan

event ExpandLoan(address borrower, address delegatee, address underlying, address palPool, uint newFeesAmount, address loanAddress, uint256 palLoanTokenId);

When the borrower adds more fees to the PalLoan to extend the duration of the loan.

ChangeLoanDelegatee

event ChangeLoanDelegatee( address borrower, address newDelegatee, address underlying, address palPool, address loanAddress, uint256 palLoanTokenId);

When the borrower change the delegatee (recipient of the voting power) of the PalLoan

CloseLoan

event CloseLoan(address borrower, address delegatee, address underlying, uint amount, address palPool, uint usedFees, address loanAddress, uint256 palLoanTokenId, bool wasKilled);

When the Borrow is either closed or killed (the wasKilled flag is ‘true’ if the Borrow was killed).

Read-only methods :

palLoanToken

function palLoanToken() public view returns(address);

Returns the address of the PalLoanToken contract

underlying

function underlying() public view returns(address);

Returns the underlying governance token held by the Pool

palToken

function palToken() public view returns(address);

Returns the address of the palToken linked to this Pool

totalReserve

function totalReserve() public view returns(uint);

Returns the amount in the Pool’s Reserve (in wei)

totalBorrowed

function totalBorrowed() public view returns(uint);

Returns the current total amount of funds borrowed from the Pool (in wei)

minBorrowLength

function minBorrowLength() public view returns(uint);

Returns the minimum duration of a Borrow (in number of blocks)

killFactor

function killFactor() public view returns(uint);

Returns the health factor value at which a Borrow can be killed (scale 1e18)

killerRatio

function killerRatio() public view returns(uint);

Returns the ratio of fees to reward the killer of a Borrow (scale 1e18)

reserveFactor

function reserveFactor() public view returns(uint);

Returns the factor of fees to set as Reserve (scale 1e18)

accrualBlockNumber

function accrualBlockNumber() public view returns(uint);

Returns the block number for the last interest update for this Pool

borrowIndex

function borrowIndex() public view returns(uint);

Returns the last computed Borrow Index for this Pool (scale 1e18)

controller

function controller() public view returns(address);

Returns the address of the current Controller for this Pool

underlyingBalance

function underlyingBalance() public view returns(uint);

Returns the amount of underlying token in the Pool (in wei)

balanceOf

function balanceOf(address _account) external view returns(uint);

Returns balance of the user in palToken (in wei)

underlyingBalanceOf

function underlyingBalanceOf(address _account) external view returns(uint)

Returns balance of the user in the underlying token (in wei)

isLoanOwner

function isLoanOwner(address _loanAddress, address _user) external view returns(bool)

Returns 'true' if the given user is the owner of the PalLoan

idOfLoan

function idOfLoan(address _loanAddress) external view returns(uint256)

Returns the PalLoanToken Id for the given PalLoan

getLoansPools

function getLoansPools() external view returns(address [] memory);

Returns a list of all the Loans (active or closed)

getLoansByBorrower

function getLoansByBorrower(address _borrower) external view returns(address [] memory);

Returns a list of all the user's Loans (active or closed)

getBorrowData

function getBorrowData(address _loanAddress) external view returns (address _borrower, address _loan, uint _amount, address _underlying, uint _feesAmount, uint _feesUsed, uint _startBlock, bool _closed)

Returns all the data stored for the given Borrow (for the given PalLoan)

Parameters :

name	type	desc
_loanAddress	address	address of the PalLoan

Returns :

name	type	desc
_borrower	address	address of the owner of the Borrow (by being owner of the PalLoanToken)
_delegatee	address	address of the recipient of the voting power
_loanPool	address	address of the PalLoan for this Borrow
_palLoanTokenId	uint256	id of the PalLoanToken for this PalLoan
_amount	uint	amount of token borrowed for delegation
_underlying	address	address of the governance token
_feesAmount	uint	amount of fees paid by the borrower
_feesUsed	uint	amount of fees already used by the Borrow
_startBlock	uint	block where the Borrow was started
_closed	bool	‘false’ if the Borrow is still active
_killed	bool	'true' if the Borrow was killed

borrowRatePerBlock

function borrowRatePerBlock() external view returns (uint);

Returns the current Borrow Rate (scale 1e18)

supplyRatePerBlock

function supplyRatePerBlock() external view returns (uint);

Returns the current Supply Rate (scale 1e18)

exchangeRateStored

function exchangeRateStored() external view returns (uint);

Returns the last updated Exchange Rate (scale 1e18)

minBorrowFees

function minBorrowFees(uint _amount) external view returns (uint);

Amount minimum of fees to allow the borrow() method. Calculated on the given amount parameter (in wei). Return the minimum amount of fees (in wei)

isKillable

function isKillable(address _loan) external view returns(bool);

Returns true if the health factor of a Borrow (given by the PalLoan address) is low enough to be killed

State-changing methods :

deposit

function deposit(uint _amount) external returns(uint);

Deposit the underlying token into the Pool, and receive an amount of palToken corresponding to the deposit.

Parameters :

name	type	desc
_amount	uint	amount of token to deposit in the Pool

Returns :

name	type	desc
	uint	amount of palTokens minted to the user

The _amount value must be approved for the PalPool before this transaction

withdraw

function withdraw(uint _amount) external returns(uint);

Burn an amount of palToken to withdraw the underlying token of the Pool.

Parameters :

name	type	desc
_amount	uint	amount of palToken to burn

Returns :

name	type	desc
	uint	amount of underlying token returned to the user

borrow

function borrow(address _delegatee, uint _amount, uint _feeAmount) external returns(uint);

Starts a Borrow, creates a PalLoan (and mint the PalLoanToken linked to this PalLoan), and sends the borrowed amount and the fees to the PalLoan, to delegate the voting/proposition power to the delegatee.

A minimum of fees, to cover the Minimum Borrow Length, is required to start the Borrow

Parameters :

name	type	desc
_delegatee	address	address to receive the voting power
_amount	uint	amount of governance token to borrow (representing how much power to receive through delegation)
_feeAmount	uint	amount of fees paid for the Borrow

Returns :

name	type	desc
	uint	amount of token delegated to the borrower

The _feeAmount value must be approved for the PalPool before this transaction

expandBorrow

function expandBorrow(address _loanPool, uint _feeAmount) external returns(uint);

If the borrower wants to extend his Borrow length, fees can be paid to be added to the Borrow (and transferred to the corresponding PalLoan)

Parameters :

name	type	desc
_loanPool	address	address of the PalLoan linked to the Borrow to expand
_feeAmount	uint	amount of fees to add to the Borrow

Returns :

name	type	desc
	uint	amount of fees added to the Borrow

The _feeAmount value must be approved for the PalPool before this transaction

closeBorrow

function closeBorrow(address _loanPool) external;

A borrower can close his own Borrows if he wants, recovering the fees not used.

If the borrower tries to close the Borrow before the Minimum Borrow Length, Penalty Fees will be be applied to the fees to return to the users, corresponding to the amount of fees to pay up to the Minimum Borrow Length (applied using the Borrow Rate at the time of closing).

Parameters :

name	type	desc
_loanPool	address	address of the PalLoan linked to the Borrow to close

killBorrow

function killBorrow(address _loanPool) external;

If a Borrow used all its fees, it can be killed to stop the delegation, and return the voting power to the Pool.

The Killer cannot be the user owning the Borrow, and the Killer is rewarded a part of the fees of this Borrow.

Parameters :

name	type	desc
_loanPool	address	address of the PalLoan linked to the Borrow to kill

changeBorrowDelegatee

function changeBorrowDelegatee(address _loanPool, address _newDelegatee) external;

Changes the recipient of voting power for the given PalLoan, updating the data in the Borrow, and triggering a delegation process for the PalLoan to give the voting power to the new delegatee address.

Parameters :

name	type	desc
_loanPool	address	address of the PalLoan
_newDelegatee	address	address of the new delegatee to receive the PalLoan voting power

exchangeRateCurrent

function exchangeRateCurrent() external returns (uint);

Updates the Pool state & returns the last updated Exchange Rate

Returns :

name	type	desc
	uint	current Exchange Rate for the palToken (scale 1e18)

_updateInterest

function _updateInterest() external returns (uint);

Update the Pool interests & storage values. This method is called before any deposit/withdraw/borrow/closeBorrow/…, but can also be called to update the Pool state.

Returns :

name	type	desc
	bool	Update success