Pool Operations

Gearbox pools are ERC-4626 compliant vaults. Liquidity providers deposit underlying assets and receive diesel tokens (shares) that appreciate as borrowers pay interest. This page covers how to interact with pools using the TypeScript SDK and viem.

Pool Overview

Concept	Description
Underlying	The base asset (e.g. USDC, WETH)
Diesel token	The pool's share token (e.g. dUSDC, dWETH)
Diesel rate	Share price in RAY (27 decimals): 1 diesel = `dieselRate / 10^27` underlying
ERC-4626	Standard vault interface for deposit, withdraw, mint, redeem

Reading Pool State

TypeScript

import { GearboxSDK } from "@gearbox-protocol/sdk";

const sdk = await GearboxSDK.attach({ client, marketConfigurators: [] });
const market = sdk.marketRegister.findByPool(poolAddress);
const pool = market.pool;

console.log(`Underlying: ${pool.underlying.symbol}`);
console.log(`Total assets: ${pool.totalAssets}`);
console.log(`Available liquidity: ${pool.availableLiquidity}`);
console.log(`Diesel rate: ${pool.dieselRate}`);

Deposit

Deposit underlying assets and receive diesel tokens:

TypeScript

import { erc20Abi } from "viem";
import { iPoolV3Abi } from "@gearbox-protocol/sdk";

// 1. Approve the pool to spend underlying
const approveHash = await walletClient.writeContract({
  address: underlyingAddress,
  abi: erc20Abi,
  functionName: "approve",
  args: [poolAddress, amount],
});
await publicClient.waitForTransactionReceipt({ hash: approveHash });

// 2. Deposit and receive shares
const depositHash = await walletClient.writeContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "deposit",
  args: [amount, receiverAddress],
});
const receipt = await publicClient.waitForTransactionReceipt({ hash: depositHash });

Deposit with Referral

Track referrals on-chain using the Gearbox-specific extension:

TypeScript

const hash = await walletClient.writeContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "depositWithReferral",
  args: [amount, receiverAddress, 123n], // referralCode
});

Preview Operations

Check expected shares or assets before executing:

TypeScript

// How many shares for a given deposit?
const expectedShares = await publicClient.readContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "previewDeposit",
  args: [amount],
});

// How many assets needed to mint exact shares?
const requiredAssets = await publicClient.readContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "previewMint",
  args: [shares],
});

// How many shares burned on withdraw?
const sharesBurned = await publicClient.readContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "previewWithdraw",
  args: [amount],
});

// How many assets received on redeem?
const assetsReceived = await publicClient.readContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "previewRedeem",
  args: [shares],
});

Withdraw

Withdraw exact underlying assets by burning the required shares:

TypeScript

const hash = await walletClient.writeContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "withdraw",
  args: [amount, receiverAddress, ownerAddress],
});

Redeem

Burn exact shares and receive underlying assets:

TypeScript

const hash = await walletClient.writeContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "redeem",
  args: [shares, receiverAddress, ownerAddress],
});

Mint

Mint exact shares by depositing the required underlying:

TypeScript

// Preview required assets first
const requiredAssets = await publicClient.readContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "previewMint",
  args: [shares],
});

// Approve and mint
await walletClient.writeContract({
  address: underlyingAddress,
  abi: erc20Abi,
  functionName: "approve",
  args: [poolAddress, requiredAssets],
});

await walletClient.writeContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "mint",
  args: [shares, receiverAddress],
});

Maximum Operations

Query the maximum deposit, withdraw, mint, or redeem for a given address:

TypeScript

const maxDeposit = await publicClient.readContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "maxDeposit",
  args: [receiverAddress],
});

const maxWithdraw = await publicClient.readContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "maxWithdraw",
  args: [ownerAddress],
});

const maxRedeem = await publicClient.readContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "maxRedeem",
  args: [ownerAddress],
});

const maxMint = await publicClient.readContract({
  address: poolAddress,
  abi: iPoolV3Abi,
  functionName: "maxMint",
  args: [receiverAddress],
});

ERC-4626 Method Summary

Method	Input	Output	Description
`deposit(assets, receiver)`	Underlying amount	Shares minted	Deposit exact assets
`mint(shares, receiver)`	Share amount	Assets deposited	Mint exact shares
`withdraw(assets, receiver, owner)`	Underlying amount	Shares burned	Withdraw exact assets
`redeem(shares, receiver, owner)`	Share amount	Assets received	Burn exact shares
`previewDeposit(assets)`	Underlying amount	Expected shares	Preview deposit
`previewMint(shares)`	Share amount	Required assets	Preview mint
`previewWithdraw(assets)`	Underlying amount	Shares to burn	Preview withdraw
`previewRedeem(shares)`	Share amount	Assets to receive	Preview redeem

Utilization Calculation

Compute pool utilization from available data:

TypeScript

const market = sdk.marketRegister.findByPool(poolAddress);
const pool = market.pool;

const totalAssets = pool.totalAssets;
const available = pool.availableLiquidity;
const borrowed = totalAssets - available;

// Utilization in basis points (0-10000)
const utilizationBps = totalAssets > 0n
  ? Number(borrowed * 10000n / totalAssets)
  : 0;

console.log(`Utilization: ${(utilizationBps / 100).toFixed(2)}%`);

Next Steps

Interest Rates & Quotas -- How borrow rates and quota fees are determined
Insurance Mechanism -- How protocol revenue protects lenders
Markets Data -- Query market state and credit manager config