Stock lending

StockLendingVault lends one Stock Token. A holder's tokens earn a fee while they still back the holder's loan, and the fee is what short sellers pay. There is one vault per Stock Token, an ERC-4626 vault over the token in its raw units, so a dividend or split, which moves only the token's ERC-8056 multiplier, passes through every loan.

Source: contracts/src/StockLendingVault.sol. Shares are named thl<symbol>, for example thlTSLA.

Who uses it#

The vault has two fixed counterparties, each set once by the owner.

You lend through the margin accounts, with accounts.lend, accounts.unlend and accounts.recall. You borrow by opening a short. What you can call on the vault yourself is buyIn, sync and the reads. The vault's owner must be the accounts' owner, so nobody else chooses who borrows the tokens that back a loan.

Read a vault#

import { stockLending } from '@tapehouse/sdk'

const terms = await stockLending.terms(publicClient, deployments, 'TSLA')
const ticket = await stockLending.ticket(publicClient, deployments, 'TSLA', 0n)

terms returns, at one block, utilization and the borrowRate and supplyRate (a year, 18 decimals), locked, idle, debt and borrowable in the token's raw units, totalAssets, the ticket next in turn (head), maxUtilization, notice in seconds and feeShare in basis points. ticket returns a ticket's span of the queue, what it has taken, when its notice runs out and what the vault holds for it.

For any other call, use the generated ABI with the vault's address from the registry:

import { stockLendingVaultAbi } from '@tapehouse/sdk'

const vault = deployments.stockLending.TSLA
const owed = await publicClient.readContract({ address: vault, abi: stockLendingVaultAbi, functionName: 'debt' })

Functions#

Reads#

depositor, borrower, rateModel, feeShare, idle, locked, debt, scaledDebt, borrowIndex, lastAccrual, borrowable, utilization, borrowRate, supplyRate, tickets, head, requested, assigned, served, ticket(id), claimable(id), reachable(ids), the constants below, and the ERC-4626 views.

The fee#

The fee accrues on the debt in the token itself, through a borrow index with 27 decimals. The rate follows utilisation on a two-slope curve, in basis points a year:

• base when nothing is lent.
• base + slope1 at optimal utilisation.
• base + slope1 + slope2 when everything is lent, which the vault reaches only once lenders take back what the borrower left idle.

Nothing accrues while nothing is lent. The owner takes feeShare of the fee as shares minted at each accrual, and every conversion counts those pending shares, so no deposit or redemption takes part of them. supplyRate is the fee on the share lent, less the owner's share.

Recall and buy-in#

What lenders want back comes, in order, from the tokens the vault holds, from new lending and repayments, from the borrower within a notice, and last from a forced buy-in. Each recall is a ticket at the end of one queue. Every token that comes into the vault is held for the tickets in their order (locked, up to assigned) before any is free to borrow or withdraw (idle).

Each ticket has a notice of one day. Once it runs out, anyone may call buyIn(ticket), which has the borrower buy in and return all the vault does not yet hold of the queue up to that ticket's end, as far as the borrower owes it, or reverts with BuyInFailed. The recall is in raw units, so a dividend or split during the notice changes nothing owed. The short positions contract is the borrower and pays for the buy-in from its shorts' USDG.

The depositor takes what came back with reclaim and gives up the rest of a ticket with forfeit. A lender leaves with unlend and then the accounts' withdraw, to its own address.

Parameters and limits#

slope1 may not exceed slope2. A rate model outside these bounds reverts with InvalidRateModel. feeShare is fixed at deployment.

The issuer's controls#

While the token is paused, the vault is blocklisted, or its balance is below its count, every max* view returns zero and nothing enters or leaves. A burn from the vault falls on this vault's lenders in proportion to their shares and on no other asset's holders. sync() brings the count down to the balance. Until it runs, a position that lent through the vault borrows nothing, as from a blocklisted vault. Tokens sent to the vault directly change no share's value.

Events#

Errors#

Next#

• Short positions
• Margin accounts
• Short and baskets
• Earn