Core Lending Instructions

Initialize

Discriminator: 0x00

Creates a new LendingPool PDA for the given SPL token mint with default interest rate parameters. Must be called by the protocol authority before any deposits or borrows.

Accounts

Instruction Data

Example

import { initializeIx } from './lib/veil/instructions';
import { findPoolPda, findPoolAuthorityPda } from './lib/veil/pda';
 
const [pool, poolBump] = await findPoolPda(tokenMint);
const [authority, authorityBump] = await findPoolAuthorityPda(pool);
 
const ix = initializeIx(
  payer.publicKey,
  admin.publicKey,
  pool,
  tokenMint,
  vault,
  poolBump,
  authorityBump,
  0,
);

Deposit

Discriminator: 0x01

Deposit tokens into the pool. Mints deposit shares to the user’s UserPosition at the current supply_index. The UserPosition PDA is created on first deposit.

Accounts

Instruction Data

Share Calculation

shares_minted = amount × WAD / supply_index

Because supply_index only grows over time, later depositors receive fewer shares per token — correctly reflecting that earlier depositors have already earned interest.

Example

import { depositIx } from './lib/veil/instructions';
import { findUserPositionPda } from './lib/veil/pda';
 
const [userPosition, positionBump] = await findUserPositionPda(user, pool);
 
const ix = depositIx(
  user,
  userTokenAccount,
  vault,
  pool,
  userPosition,
  poolAuthority,
  1_000_000n,     // amount in base units
  positionBump,
);

Withdraw

Discriminator: 0x02

Burn deposit shares and transfer the underlying tokens back to the user.

Accounts

Instruction Data

Token Amount

tokens_out = shares × supply_index / WAD

Errors

• ExceedsDepositBalance — shares requested exceed user_position.deposit_shares
• InsufficientLiquidity — pool doesn’t have enough free liquidity to cover the withdrawal

Borrow

Discriminator: 0x03

Borrow tokens against deposited collateral. Enforces the LTV cap and ensures the health factor remains ≥ 1.0 after the borrow.

Accounts

Instruction Data

Risk Checks (in order)

1. pool.paused == 0 — pool must be active
2. debt_after ≤ deposit_balance × LTV — LTV cap
3. health_factor(deposit_balance, debt_after, liq_threshold) ≥ WAD — HF ≥ 1.0
4. amount ≤ total_deposits - total_borrows - accumulated_fees — available liquidity

Health Factor Formula

HF = (deposit_balance × liquidation_threshold) / current_debt

If HF < WAD (i.e. < 1.0), the position is liquidatable.

Errors

• PoolPaused — pool is paused
• ExceedsCollateralFactor — borrow would exceed LTV cap
• Undercollateralised — resulting HF < 1.0
• InsufficientLiquidity — not enough free liquidity

Repay

Discriminator: 0x04

Repay outstanding debt. The repay amount is capped at the current total debt (principal + accrued interest).

Accounts

Instruction Data

Errors

• NoBorrow — user has no outstanding debt
• ExceedsDebtBalance — amount exceeds total debt (capped automatically in practice)

Liquidate

Discriminator: 0x05

Repay part of an underwater position and seize collateral at a discount. Requires no instruction data beyond the discriminator.

Accounts

Instruction Data

Liquidation Mechanics

repay_amount   = current_debt × close_factor          (default: 50%)
seized         = repay_amount × (1 + liquidation_bonus) (default: +5%)
protocol_fee   = seized × protocol_liq_fee             (default: 10% of seized)
liquidator_gets = seized - protocol_fee

Default parameters:

• Close factor: 50%
• Liquidation bonus: 5%
• Protocol liquidation fee: 10% of seized

Errors

• PositionHealthy — HF ≥ 1.0
• NoBorrow — position has no debt