Vault

Complete Reference for the PerpetualsVault Class

Overview

The PerpetualsVault class is a high-level wrapper around a Perpetuals vault - a managed perpetuals account that accepts user deposits (LP tokens), trades across multiple markets, and supports withdrawals via a request-based flow.

Key Features:

• User Actions:

  • Deposit collateral and receive LP tokens

  • Create withdraw requests

  • Cancel or update withdraw requests

  • Process force withdrawals

• Owner Admin Actions:

  • Process pending withdraw requests

  • Update vault parameters (lock period, force withdraw delay, performance fee)

  • Withdraw performance fees

  • Withdraw (redeem) LP tokens

• Trading:

  • Access underlying perpetuals account for trading

  • Trade across up to 12 markets

  • Automated position management

• Preview Methods:

  • Preview deposits and withdrawals

  • Estimate LP token amounts

  • Calculate performance fees

Vault Mechanics:

1. Deposits: Users deposit collateral → receive LP tokens representing vault share

2. Trading: Vault owner trades with pooled collateral

3. Withdrawals: Users request withdrawal → wait for lock period → receive collateral

4. Performance Fees: Owner earns fees on positive performance

5. Force Withdrawals: Emergency mechanism to close positions and process withdrawals

Typical Usage:

import { Aftermath } from "aftermath-ts-sdk";

const afSdk = new Aftermath("MAINNET");
await afSdk.init();

const perps = afSdk.Perpetuals();

// Get all vaults
const { vaults } = await perps.getAllVaults();
const vault = vaults[0];

// Deposit into vault
const { tx } = await vault.getDepositTx({
	walletAddress: "0xUSER_ADDRESS",
	depositAmount: 10_000n * 1_000_000n, // 10,000 USDC (6 decimals)
	minLpAmountOut: 0n,
});

// Check LP coin price
const lpPrice = await vault.getLpCoinPrice();
console.log(`LP Price: ${lpPrice} USD per LP token`);

---

Constructor

constructor

constructor(
  public readonly vaultObject: PerpetualsVaultObject,
  config?: CallerConfig,
  public readonly Provider?: AftermathApi
)

Creates a new PerpetualsVault wrapper instance.

You typically don't construct this directly. Instead, use Perpetuals.getAllVaults(), Perpetuals.getVault(), or Perpetuals.getVaults().

Parameters:

• vaultObject: PerpetualsVaultObject

  • Raw on-chain vault object snapshot containing:

    • objectId: Vault ID

    • ownerAddress: Vault owner address

    • accountId: Underlying perpetuals account ID

    • accountObjectId: Account object ID

    • collateralCoinType: Collateral coin type (e.g., USDC)

    • lpCoinType: LP token coin type

    • lockPeriodMs: Minimum lock period for withdrawals

    • forceWithdrawDelayMs: Delay before force withdrawal can process

    • performanceFeePercentage: Vault performance fee

    • pausedUntilTimestamp: Optional pause timestamp

    • Other vault state fields

• config (optional): CallerConfig

  • Configuration object containing network settings

• Provider (optional): AftermathApi

  • Shared provider instance for transaction building

Remarks:

• This class extends Caller with the "perpetuals" route prefix

• All API calls resolve under /perpetuals/vault/...

Example:

// Standard usage (recommended)
const perps = afSdk.Perpetuals();
const { vaults } = await perps.getAllVaults();
const vault = vaults[0];

// Access vault properties
console.log(`Vault ID: ${vault.vaultObject.objectId}`);
console.log(`Owner: ${vault.vaultObject.ownerAddress}`);
console.log(`Collateral Type: ${vault.vaultObject.collateralCoinType}`);
console.log(`LP Type: ${vault.vaultObject.lpCoinType}`);
console.log(`Lock Period: ${vault.vaultObject.lockPeriodMs / 86400000} days`);
console.log(
	`Performance Fee: ${vault.vaultObject.performanceFeePercentage * 100}%`,
);

// Direct construction (advanced usage)
const rawVaultObject: PerpetualsVaultObject = {
	objectId: "0xVAULT_ID",
	ownerAddress: "0xOWNER_ADDRESS",
	accountId: 123n,
	accountObjectId: "0xACCOUNT_ID",
	collateralCoinType:
		"0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::COIN",
	lpCoinType: "0x...::lp::LP",
	lockPeriodMs: 86400000, // 1 day
	forceWithdrawDelayMs: 3600000, // 1 hour
	performanceFeePercentage: 0.1, // 10%
	// ... other fields
};

const customConfig = {
	network: "MAINNET" as SuiNetwork,
};

const vault = new PerpetualsVault(rawVaultObject, customConfig);

Use Cases:

1. Vault Wrapping: Wrap raw vault data with convenient methods

2. Testing: Create vault instances with mock data

3. Custom Initialization: Initialize with specific network configs

---

Static Constants

PerpetualsVault.constants

static readonly constants = {
  maxLockPeriodMs: 5184000000,        // 2 months
  maxForceWithdrawDelayMs: 86400000,  // 1 day
  maxPerformanceFeePercentage: 0.2,   // 20%
  minDepositUsd: 1,                   // $1
  minOwnerLockUsd: 1,                 // $1
  maxMarketsInVault: 12,              // 12 markets
  maxPendingOrdersPerPosition: 70,    // 70 orders
}

Vault-level protocol limits and UI-friendly constraints.

Constants:

• maxLockPeriodMs: 5184000000 (2 months)

  • Maximum lock period that can be set for withdrawal requests

• maxForceWithdrawDelayMs: 86400000 (1 day)

  • Maximum force withdraw delay period

• maxPerformanceFeePercentage: 0.2 (20%)

  • Maximum performance fee the owner can charge

• minDepositUsd: 1 ($1)

  • Minimum USD value required for user deposits

• minOwnerLockUsd: 1 ($1)

  • Minimum USD value vault owner must lock during creation

• maxMarketsInVault: 12

  • Maximum number of distinct markets the vault can trade

• maxPendingOrdersPerPosition: 70

  • Maximum pending orders per position in the vault

Example:

// Validate lock period
function validateLockPeriod(lockPeriodMs: number): boolean {
	if (lockPeriodMs > PerpetualsVault.constants.maxLockPeriodMs) {
		console.error(
			`Lock period exceeds maximum of ${PerpetualsVault.constants.maxLockPeriodMs / 86400000} days`,
		);
		return false;
	}
	return true;
}

// Validate performance fee
function validatePerformanceFee(fee: number): boolean {
	if (fee > PerpetualsVault.constants.maxPerformanceFeePercentage) {
		console.error(
			`Fee ${fee * 100}% exceeds maximum of ${PerpetualsVault.constants.maxPerformanceFeePercentage * 100}%`,
		);
		return false;
	}
	return true;
}

// Display vault constraints
console.log(`=== Vault Constraints ===`);
console.log(
	`Max Lock Period: ${PerpetualsVault.constants.maxLockPeriodMs / 86400000} days`,
);
console.log(
	`Max Force Withdraw Delay: ${PerpetualsVault.constants.maxForceWithdrawDelayMs / 3600000} hours`,
);
console.log(
	`Max Performance Fee: ${PerpetualsVault.constants.maxPerformanceFeePercentage * 100}%`,
);
console.log(`Min Deposit: $${PerpetualsVault.constants.minDepositUsd}`);
console.log(`Max Markets: ${PerpetualsVault.constants.maxMarketsInVault}`);
console.log(
	`Max Orders Per Position: ${PerpetualsVault.constants.maxPendingOrdersPerPosition}`,
);

// Check vault configuration
function checkVaultConfig(vault: PerpetualsVault): {
	valid: boolean;
	issues: string[];
} {
	const issues: string[] = [];

	if (
		vault.vaultObject.lockPeriodMs >
		PerpetualsVault.constants.maxLockPeriodMs
	) {
		issues.push(
			`Lock period ${vault.vaultObject.lockPeriodMs} exceeds maximum`,
		);
	}

	if (
		vault.vaultObject.forceWithdrawDelayMs >
		PerpetualsVault.constants.maxForceWithdrawDelayMs
	) {
		issues.push(
			`Force withdraw delay ${vault.vaultObject.forceWithdrawDelayMs} exceeds maximum`,
		);
	}

	if (
		vault.vaultObject.performanceFeePercentage >
		PerpetualsVault.constants.maxPerformanceFeePercentage
	) {
		issues.push(
			`Performance fee ${vault.vaultObject.performanceFeePercentage * 100}% exceeds maximum`,
		);
	}

	return {
		valid: issues.length === 0,
		issues,
	};
}

// Usage
const config = checkVaultConfig(vault);
if (!config.valid) {
	console.error("Vault configuration issues:", config.issues);
}

Use Cases:

1. Validation: Validate vault parameters before creation/updates

2. UI Constraints: Set input field limits in user interfaces

3. Documentation: Show users the protocol limits

4. Error Handling: Provide clear error messages when limits exceeded

---

Withdraw Request Transaction Methods

getProcessForceWithdrawRequestTx

async getProcessForceWithdrawRequestTx(inputs: {
  walletAddress: SuiAddress;
  sizesToClose: Record<PerpetualsMarketId, Balance>;
  recipientAddress?: SuiAddress;
  tx?: Transaction;
}): Promise<ApiPerpetualsVaultProcessForceWithdrawRequestTxResponse>

Build a process-force-withdraw-request transaction.

What This Does:

Force-withdraw is an emergency mechanism that:

1. Closes specified positions in the vault

2. Processes a pending withdraw request after the delay window

3. Returns collateral to the user

This is used when normal withdrawal processing is delayed or unavailable.

Parameters:

• walletAddress: SuiAddress

  • User wallet that owns the withdraw request

• sizesToClose: Record<PerpetualsMarketId, Balance>

  • Mapping of market IDs to position sizes to close (in base units, 9 decimals)

  • Sizes are in base asset units scaled by Casting.Fixed.fixedOneN9

• recipientAddress (optional): SuiAddress

  • Address to receive the withdrawn collateral

  • If omitted, collateral goes to walletAddress

• tx (optional): Transaction

  • Existing transaction to extend

Returns:

Object containing:

• tx: Transaction - Transaction ready to sign and execute

• Other response fields from backend

Example:

// Preview before processing
async function previewAndProcessForceWithdraw(walletAddress: string) {
	// First preview to see what needs to be closed
	const preview = await vault.getPreviewProcessForceWithdrawRequest({
		walletAddress,
	});

	if ("error" in preview) {
		console.error(`Preview failed: ${preview.error}`);
		return null;
	}

	console.log(`Force Withdraw Preview:`);
	console.log(
		`  Estimated Collateral Out: ${preview.estimatedCollateralOut}`,
	);
	console.log(
		`  Positions to Close: ${Object.keys(preview.sizesToClose).length}`,
	);

	// Build transaction
	const { tx } = await vault.getProcessForceWithdrawRequestTx({
		walletAddress,
		sizesToClose: preview.sizesToClose,
		recipientAddress: "0xRECIPIENT_ADDRESS",
	});

	return tx;
}

// Usage
const tx = await forceWithdrawFromMarkets("0xUSER_ADDRESS");

// Execute
// await wallet.signAndExecuteTransaction({ transaction: tx });

Use Cases:

1. Emergency Withdrawals: Process withdrawals when normal flow is blocked

2. Position Closure: Close specific positions for withdrawal

3. Partial Withdrawals: Close subset of positions

4. Automated Processing: Build automated force withdrawal systems

---

getPauseVaultForForceWithdrawRequestTx

async getPauseVaultForForceWithdrawRequestTx(inputs: {
  tx?: Transaction;
}): Promise<{ tx: Transaction }>

Build a pause-vault-for-force-withdraw-request transaction.

What This Does:

Pauses the vault temporarily to facilitate force withdraw request processing. This prevents new deposits and trading activity while force withdrawals are being processed.

Parameters:

• tx (optional): Transaction

  • Existing transaction to extend

Returns:

Object containing:

• tx: Transaction - Transaction ready to sign and execute

Example:

// Pause vault for force withdraw
const { tx } = await vault.getPauseVaultForForceWithdrawRequestTx({});

// Execute
// await wallet.signAndExecuteTransaction({ transaction: tx });

// Check if vault is paused
const isPaused = vault.isPaused();
console.log(`Vault paused: ${isPaused}`);

// Pause and process force withdraw workflow
async function pauseAndProcessForceWithdraw(walletAddress: string) {
	// Step 1: Pause vault
	const { tx: pauseTx } = await vault.getPauseVaultForForceWithdrawRequestTx(
		{},
	);
	await wallet.signAndExecuteTransaction({ transaction: pauseTx });

	console.log("Vault paused");

	// Step 2: Wait briefly for state update
	await new Promise((resolve) => setTimeout(resolve, 2000));

	// Step 3: Process force withdraw
	const preview = await vault.getPreviewProcessForceWithdrawRequest({
		walletAddress,
	});

	if ("error" in preview) {
		console.error(preview.error);
		return;
	}

	const { tx: processTx } = await vault.getProcessForceWithdrawRequestTx({
		walletAddress,
		sizesToClose: preview.sizesToClose,
	});

	await wallet.signAndExecuteTransaction({ transaction: processTx });

	console.log("Force withdraw processed");
}

Use Cases:

1. Force Withdraw Preparation: Pause vault before processing force withdrawals

2. Emergency Procedures: Implement emergency pause mechanisms

3. Maintenance: Temporarily halt vault activity

---

getUpdateWithdrawRequestSlippageTx

async getUpdateWithdrawRequestSlippageTx(inputs: {
  minCollateralAmountOut: Balance;
  tx?: Transaction;
}): Promise<{ tx: Transaction }>

Build an update-withdraw-request-slippage transaction.

What This Does:

Updates the minimum acceptable collateral output amount for an existing withdraw request. This allows users to adjust their slippage tolerance after creating a withdraw request.

Parameters:

• minCollateralAmountOut: Balance (bigint)

  • New minimum collateral amount to receive (in collateral units, 6 decimals for USDC)

  • Scaled by 1_000_000n for USDC

• tx (optional): Transaction

  • Existing transaction to extend

Returns:

Object containing:

• tx: Transaction - Transaction ready to sign and execute

Example:

// Update slippage to accept 1% loss
const lpAmount = 1000n * 1_000_000_000n; // 1000 LP tokens
const lpPrice = await vault.getLpCoinPrice();
const expectedCollateral = (Number(lpAmount) / 1_000_000) * lpPrice;
const minCollateral = expectedCollateral * 0.99; // 1% slippage
const minCollateralAmount = BigInt(Math.floor(minCollateral * 1_000_000));

const { tx } = await vault.getUpdateWithdrawRequestSlippageTx({
	minCollateralAmountOut: minCollateralAmount,
});

// More conservative slippage (0.5%)
const conservativeMin = BigInt(
	Math.floor(expectedCollateral * 0.995 * 1_000_000),
);

const { tx: conservativeTx } = await vault.getUpdateWithdrawRequestSlippageTx({
	minCollateralAmountOut: conservativeMin,
});

// Dynamic slippage based on market conditions
async function updateSlippageBasedOnVolatility(
	withdrawRequest: PerpetualsVaultWithdrawRequest,
) {
	// Get current LP price
	const currentLpPrice = await vault.getLpCoinPrice();

	// Calculate volatility (simplified)
	const priceChange =
		Math.abs(currentLpPrice - withdrawRequest.lpPriceAtRequest) /
		withdrawRequest.lpPriceAtRequest;

	// Adjust slippage tolerance based on volatility
	let slippageTolerance: number;
	if (priceChange > 0.05) {
		slippageTolerance = 0.02; // 2% for high volatility
	} else if (priceChange > 0.02) {
		slippageTolerance = 0.01; // 1% for medium volatility
	} else {
		slippageTolerance = 0.005; // 0.5% for low volatility
	}

	const expectedOut = withdrawRequest.lpAmountInUsd / currentLpPrice;
	const minOut = BigInt(
		Math.floor(expectedOut * (1 - slippageTolerance) * 1_000_000),
	);

	console.log(
		`Updating slippage to ${slippageTolerance * 100}% based on ${priceChange * 100}% price change`,
	);

	const { tx } = await vault.getUpdateWithdrawRequestSlippageTx({
		minCollateralAmountOut: minOut,
	});

	return tx;
}

// Update slippage to match current LP price
async function updateToCurrentPrice(
	withdrawRequest: PerpetualsVaultWithdrawRequest,
	slippagePercent: number = 0.01,
) {
	const currentLpPrice = await vault.getLpCoinPrice();
	const lpAmount = withdrawRequest.lpAmount;

	const expectedCollateral =
		(Number(lpAmount) / 1_000_000_000) * currentLpPrice;
	const minCollateral = expectedCollateral * (1 - slippagePercent);
	const minCollateralAmount = BigInt(Math.floor(minCollateral * 1_000_000));

	console.log(`Updating withdraw request slippage:`);
	console.log(`  LP Amount: ${Number(lpAmount) / 1_000_000_000}`);
	console.log(`  Current LP Price: ${currentLpPrice}`);
	console.log(`  Expected Collateral: ${expectedCollateral}`);
	console.log(
		`  Min Collateral (${slippagePercent * 100}% slippage): ${minCollateral}`,
	);

	const { tx } = await vault.getUpdateWithdrawRequestSlippageTx({
		minCollateralAmountOut: minCollateralAmount,
	});

	return tx;
}

// Validate slippage update
function validateSlippageUpdate(
	currentMin: number,
	newMin: number,
	lpAmount: number,
): boolean {
	if (newMin <= 0) {
		console.error("Minimum collateral must be positive");
		return false;
	}

	const slippage = (lpAmount - newMin) / lpAmount;
	if (slippage > 0.1) {
		console.warn(`⚠️  High slippage tolerance: ${slippage * 100}%`);
	}

	if (newMin > currentMin) {
		console.log(`✓ Tightening slippage tolerance`);
	} else {
		console.log(`⚠️  Loosening slippage tolerance`);
	}

	return true;
}

Use Cases:

1. Slippage Adjustment: Update slippage tolerance based on market conditions

2. Price Protection: Tighten slippage during favorable price movements

3. Flexibility: Loosen slippage if withdrawal is urgent

4. Risk Management: Adjust protection dynamically

---

getCancelWithdrawRequestTx

async getCancelWithdrawRequestTx(inputs: {
  walletAddress: SuiAddress;
  tx?: Transaction;
}): Promise<{ tx: Transaction }>

Build a user transaction to cancel an existing vault withdraw request.

What This Does:

Cancels a pending withdraw request, returning the LP tokens to the user's wallet. Use this when you no longer want to withdraw or want to modify the withdraw amount.

Parameters:

• walletAddress: SuiAddress

  • Wallet that created the withdraw request

• tx (optional): Transaction

  • Existing transaction to extend

Returns:

Object containing:

• tx: Transaction - Transaction ready to sign and execute

Example:

// Cancel withdraw request
const { tx } = await vault.getCancelWithdrawRequestTx({
	walletAddress: "0xUSER_ADDRESS",
});

// Execute
// await wallet.signAndExecuteTransaction({ transaction: tx });

---

getDepositTx

async getDepositTx(inputs: {
  walletAddress: SuiAddress;
} & (
  | { depositAmount: Balance }
  | { depositCoinArg: TransactionObjectArgument }
)): Promise<{ tx: Transaction }>

Build a user deposit transaction.

What This Does:

Deposits collateral into the vault and receives LP tokens representing vault share.

Parameters:

• walletAddress: SuiAddress

  • Depositing wallet address

• Deposit Amount (choose one):

  • depositAmount: Balance (bigint)

    • Amount in collateral units (6 decimals for USDC: 1_000_000n)

  • depositCoinArg: TransactionObjectArgument

    • Transaction coin from previous command

• minLpAmountOut: Balance (bigint)

  • Minimum LP tokens to receive (slippage protection)

  • In LP token units (typically 9 decimals)

• tx (optional): Transaction

Returns:

Object containing:

• tx: Transaction

Example:

// Deposit 10,000 USDC
const { tx } = await vault.getDepositTx({
	walletAddress: "0xUSER_ADDRESS",
	depositAmount: 10_000n * 1_000_000n, // 10,000 USDC (6 decimals)
	minLpAmountOut: 9_900n * 1_000_000_000n, // At least 9,900 LP (1% slippage)
});

// Preview first
const preview = await vault.getPreviewDeposit({
	depositAmount: 10_000n * 1_000_000n,
});

const { tx: depositTx } = await vault.getDepositTx({
	walletAddress: "0xUSER_ADDRESS",
	depositAmount: 10_000n * 1_000_000n,
	minLpAmountOut: BigInt(Math.floor(preview.lpAmountOut * 0.99)), // 1% slippage
});

---

Owner Admin Transaction Methods

getOwnerUpdateForceWithdrawDelayTx

async getOwnerUpdateForceWithdrawDelayTx(inputs: {
  forceWithdrawDelayMs: bigint;
  tx?: Transaction;
}): Promise<{ tx: Transaction }>

Update vault's force withdraw delay (owner only).

Example:

// Set 6 hour delay
const { tx } = await vault.getOwnerUpdateForceWithdrawDelayTx({
	forceWithdrawDelayMs: 6n * 3600000n, // 6 hours
});

---

getOwnerUpdateLockPeriodTx

async getOwnerUpdateLockPeriodTx(inputs: {
  lockPeriodMs: bigint;
  tx?: Transaction;
}): Promise<{ tx: Transaction }>

Update vault's withdrawal lock period (owner only).

Example:

// Set 7 day lock period
const { tx } = await vault.getOwnerUpdateLockPeriodTx({
	lockPeriodMs: 7n * 86400000n, // 7 days
});

---

getOwnerUpdatePerformanceFeeTx

async getOwnerUpdatePerformanceFeeTx(inputs: {
  performanceFeePercentage: number;
  tx?: Transaction;
}): Promise<{ tx: Transaction }>

Update vault's performance fee (owner only).

Example:

// Set 10% performance fee
const { tx } = await vault.getOwnerUpdatePerformanceFeeTx({
	performanceFeePercentage: 0.1, // 10%
});

---

getOwnerProcessWithdrawRequestsTx

async getOwnerProcessWithdrawRequestsTx(inputs: {
  userAddresses: SuiAddress[];
  tx?: Transaction;
}): Promise<{ tx: Transaction }>

Process withdraw requests (owner only).

Example:

// Process batch of withdrawals
const { tx } = await vault.getOwnerProcessWithdrawRequestsTx({
	userAddresses: ["0xUSER1_ADDRESS", "0xUSER2_ADDRESS", "0xUSER3_ADDRESS"],
});

---

getOwnerWithdrawPerformanceFeesTx

async getOwnerWithdrawPerformanceFeesTx(inputs: {
  withdrawAmount: Balance;
  recipientAddress?: SuiAddress;
  tx?: Transaction;
}): Promise<ApiPerpetualsVaultOwnerWithdrawPerformanceFeesTxResponse>

Withdraw performance fees (owner only).

Example:

// Withdraw 1,000 USDC in fees
const { tx } = await vault.getOwnerWithdrawPerformanceFeesTx({
	withdrawAmount: 1_000n * 1_000_000n, // 1,000 USDC (6 decimals)
	recipientAddress: "0xOWNER_ADDRESS",
});

---

getOwnerWithdrawCollateralTx

async getOwnerWithdrawCollateralTx(inputs: {
  lpWithdrawAmount: Balance;
  minCollateralAmountOut: Balance;
  recipientAddress?: SuiAddress;
  tx?: Transaction;
}): Promise<ApiPerpetualsVaultOwnerWithdrawCollateralTxResponse>

Owner redeems LP for collateral.

Example:

// Redeem 500 LP tokens
const { tx } = await vault.getOwnerWithdrawCollateralTx({
	lpWithdrawAmount: 500n * 1_000_000_000n,
	minCollateralAmountOut: 490n * 1_000_000n, // 2% slippage
	recipientAddress: "0xOWNER_ADDRESS",
});

---

Preview Methods

getPreviewOwnerProcessWithdrawRequests

async getPreviewOwnerProcessWithdrawRequests(inputs: {
  userAddresses: SuiAddress[];
}): Promise<ApiPerpetualsVaultPreviewOwnerProcessWithdrawRequestsResponse>

Preview processing withdrawals.

---

getPreviewOwnerWithdrawPerformanceFees

async getPreviewOwnerWithdrawPerformanceFees(): Promise<
  ApiPerpetualsVaultPreviewOwnerWithdrawPerformanceFeesResponse
>

Preview available performance fees.

---

getPreviewOwnerWithdrawCollateral

async getPreviewOwnerWithdrawCollateral(inputs: {
  lpWithdrawAmount: Balance;
}): Promise<ApiPerpetualsVaultPreviewOwnerWithdrawCollateralResponse>

Preview owner LP redemption.

---

getPreviewCreateWithdrawRequest

async getPreviewCreateWithdrawRequest(inputs: {
  walletAddress: SuiAddress;
  lpWithdrawAmount: Balance;
}): Promise<ApiPerpetualsVaultPreviewCreateWithdrawRequestResponse>

Preview creating withdraw request.

---

getPreviewDeposit

async getPreviewDeposit(inputs: {
  depositAmount: Balance;
}): Promise<ApiPerpetualsVaultPreviewDepositResponse>

Preview deposit and LP tokens received.

Example:

const preview = await vault.getPreviewDeposit({
	depositAmount: 10_000n * 1_000_000n,
});

console.log(`Will receive ${preview.lpAmountOut} LP tokens`);

---

getPreviewPauseVaultForForceWithdrawRequest

async getPreviewPauseVaultForForceWithdrawRequest(inputs: {
  walletAddress: SuiAddress;
}): Promise<ApiPerpetualsVaultPreviewPauseVaultForForceWithdrawRequestResponse>

Preview the effects of pausing the vault for a force withdraw request.

What This Returns:

Preview of if pausing the vault to facilitate a force withdrawal is possible.

Parameters:

• walletAddress: SuiAddress

  • User wallet with pending force withdraw request

Returns:

ApiPerpetualsVaultPreviewPauseVaultForForceWithdrawRequestResponse containing:

• If vault is able to be paused

• Next possible pause tiemstamp

Example:

// Preview pause for force withdraw
const preview = await vault.getPreviewPauseVaultForForceWithdrawRequest({
	walletAddress: "0xUSER_ADDRESS",
});

if ("error" in preview) {
	console.error(`Preview failed: ${preview.error}`);
} else {
	console.log(`Pause Preview:`);
	console.log(`  Is pausable: ${preview.isPausable}`);
	console.log(
		`  Next possible pause timestamp: ${preview.minNextPauseTimestamp}`,
	);
}

// Workflow: Preview, then pause, then process
async function forceWithdrawWorkflow(walletAddress: string) {
	// Step 1: Preview pause
	const pausePreview =
		await vault.getPreviewPauseVaultForForceWithdrawRequest({
			walletAddress,
		});

	if ("error" in pausePreview) {
		console.error(`Cannot pause: ${pausePreview.error}`);
		return;
	}

	console.log(`Step 1: Pause preview complete`);

	// Step 2: Pause vault
	const { tx: pauseTx } = await vault.getPauseVaultForForceWithdrawRequestTx(
		{},
	);
	await wallet.signAndExecuteTransaction({ transaction: pauseTx });

	console.log(`Step 2: Vault paused`);

	// Step 3: Preview force withdraw
	const withdrawPreview = await vault.getPreviewProcessForceWithdrawRequest({
		walletAddress,
	});

	if ("error" in withdrawPreview) {
		console.error(`Cannot process: ${withdrawPreview.error}`);
		return;
	}

	console.log(`Step 3: Withdraw preview complete`);
	console.log(
		`  Positions to close: ${Object.keys(withdrawPreview.sizesToClose).length}`,
	);
	console.log(
		`  Estimated collateral out: ${withdrawPreview.estimatedCollateralOut}`,
	);

	// Step 4: Process force withdraw
	const { tx: processTx } = await vault.getProcessForceWithdrawRequestTx({
		walletAddress,
		sizesToClose: withdrawPreview.sizesToClose,
	});
	await wallet.signAndExecuteTransaction({ transaction: processTx });

	console.log(`Step 4: Force withdraw processed`);
}

// Check if pause is necessary
async function shouldPauseForForceWithdraw(
	walletAddress: string,
): Promise<boolean> {
	const preview = await vault.getPreviewPauseVaultForForceWithdrawRequest({
		walletAddress,
	});

	if ("error" in preview) {
		return false;
	}

	// Decision logic
	return preview.isPausable;
}

// Usage
const shouldPause = await shouldPauseForForceWithdraw("0xUSER_ADDRESS");
if (shouldPause) {
	console.log("Proceeding with vault pause for force withdraw");
	await forceWithdrawWorkflow("0xUSER_ADDRESS");
} else {
	console.log("Pause not recommended at this time");
}

Use Cases:

1. Impact Assessment: Understand pause effects before executing

2. Decision Support: Help determine if pause is appropriate

3. User Communication: Inform users about potential vault pause

4. Risk Management: Evaluate tradeoffs of pausing

---

getPreviewProcessForceWithdrawRequest

async getPreviewProcessForceWithdrawRequest(inputs: {
  walletAddress: SuiAddress;
}): Promise<ApiPerpetualsVaultPreviewProcessForceWithdrawRequestResponse>

Preview force withdraw processing.

---

Data Query Methods

getWithdrawRequests

async getWithdrawRequests(inputs: {
  userAddresses?: SuiAddress[];
}): Promise<ApiPerpetualsVaultsWithdrawRequestsResponse>

Fetch withdraw requests for the vault.

Example:

// Get all withdraw requests
const { withdrawRequests } = await vault.getWithdrawRequests({});

// Get specific users' requests
const { withdrawRequests: userRequests } = await vault.getWithdrawRequests({
	userAddresses: ["0xUSER_ADDRESS"],
});

---

getAllWithdrawRequests

getAllWithdrawRequests(): Promise<ApiPerpetualsVaultsWithdrawRequestsResponse>

Fetch all withdraw requests for this vault across all users.

What This Returns:

Complete list of all pending withdraw requests for the vault, useful for vault owners to see all pending requests.

Returns:

ApiPerpetualsVaultsWithdrawRequestsResponse containing:

• withdrawRequests: PerpetualsVaultWithdrawRequest[]

  • Array of all withdraw requests

  • Each request contains:

    • walletAddress: User who created the request

    • lpAmount: LP tokens to redeem

    • minCollateralAmountOut: Minimum collateral expected

    • requestTimestamp: When request was created

    • readyTimestamp: When request can be processed

    • Other request metadata

Example:

// Get all withdraw requests
const { withdrawRequests } = await vault.getAllWithdrawRequests();

console.log(`Total withdraw requests: ${withdrawRequests.length}`);

// Display all requests
for (const request of withdrawRequests) {
	const lpAmount = Number(request.lpAmount) / 1_000_000_000;
	const minOut = Number(request.minCollateralAmountOut) / 1_000_000;
	const isReady = request.readyTimestamp <= Date.now();

	console.log(`\nRequest from ${request.walletAddress}:`);
	console.log(`  LP Amount: ${lpAmount}`);
	console.log(`  Min Collateral Out: ${minOut} USDC`);
	console.log(`  Status: ${isReady ? "Ready to process" : "Locked"}`);

	if (!isReady) {
		const timeLeft = request.readyTimestamp - Date.now();
		const hoursLeft = Math.floor(timeLeft / 3600000);
		console.log(`  Time until ready: ${hoursLeft} hours`);
	}
}

// Filter ready requests
const readyRequests = withdrawRequests.filter(
	(req) => req.readyTimestamp <= Date.now(),
);

console.log(`\nReady to process: ${readyRequests.length} requests`);

// Calculate total withdrawal demand
function calculateWithdrawalDemand(
	requests: PerpetualsVaultWithdrawRequest[],
): {
	totalLp: number;
	totalCollateralMin: number;
} {
	let totalLp = 0;
	let totalCollateralMin = 0;

	for (const request of requests) {
		totalLp += Number(request.lpAmount) / 1_000_000_000;
		totalCollateralMin +=
			Number(request.minCollateralAmountOut) / 1_000_000;
	}

	return { totalLp, totalCollateralMin };
}

const { withdrawRequests: allRequests } = await vault.getAllWithdrawRequests();
const demand = calculateWithdrawalDemand(allRequests);

console.log(`\n=== Withdrawal Demand ===`);
console.log(`Total LP to redeem: ${demand.totalLp.toLocaleString()}`);
console.log(
	`Min Collateral needed: ${demand.totalCollateralMin.toLocaleString()} USDC`,
);

// Batch process ready requests
async function processBatchWithdrawals(batchSize: number = 10) {
	const { withdrawRequests } = await vault.getAllWithdrawRequests();

	const readyRequests = withdrawRequests
		.filter((req) => req.readyTimestamp <= Date.now())
		.slice(0, batchSize);

	if (readyRequests.length === 0) {
		console.log("No requests ready to process");
		return null;
	}

	const userAddresses = readyRequests.map((req) => req.walletAddress);

	console.log(`Processing ${userAddresses.length} withdrawal requests`);

	const { tx } = await vault.getOwnerProcessWithdrawRequestsTx({
		userAddresses,
	});

	return tx;
}

// Monitor withdrawal queue
async function monitorWithdrawalQueue() {
	const { withdrawRequests } = await vault.getAllWithdrawRequests();

	const now = Date.now();
	const ready = withdrawRequests.filter((req) => req.readyTimestamp <= now);
	const pending = withdrawRequests.filter((req) => req.readyTimestamp > now);

	console.log(`=== Withdrawal Queue Status ===`);
	console.log(`Total Requests: ${withdrawRequests.length}`);
	console.log(`Ready: ${ready.length}`);
	console.log(`Pending: ${pending.length}`);

	if (pending.length > 0) {
		const nextReady = Math.min(...pending.map((req) => req.readyTimestamp));
		const timeUntilNext = nextReady - now;
		const hoursUntilNext = Math.floor(timeUntilNext / 3600000);

		console.log(`Next request ready in: ${hoursUntilNext} hours`);
	}

	// Calculate slippage tolerance distribution
	const slippages = withdrawRequests.map((req) =>
		PerpetualsVault.calcWithdrawRequestSlippage({ withdrawRequest: req }),
	);

	const avgSlippage =
		slippages.reduce((sum, s) => sum + s, 0) / slippages.length;
	const maxSlippage = Math.max(...slippages);
	const minSlippage = Math.min(...slippages);

	console.log(`\nSlippage Tolerance:`);
	console.log(`  Average: ${avgSlippage * 100}%`);
	console.log(`  Max: ${maxSlippage * 100}%`);
	console.log(`  Min: ${minSlippage * 100}%`);
}

// Usage
await monitorWithdrawalQueue();

Use Cases:

1. Owner Monitoring: Track all pending withdrawal requests

2. Batch Processing: Identify and process ready requests

3. Liquidity Planning: Forecast collateral needs

4. Analytics: Analyze withdrawal patterns and slippage

---

Account Access Methods

partialVaultCap

partialVaultCap(): PerpetualsPartialVaultCap

Build vault cap for account operations.

---

getAccountObject

async getAccountObject(): Promise<{
  account: PerpetualsAccountObject;
}>

Get underlying account object.

---

getAccount

async getAccount(): Promise<{
  account: PerpetualsAccount;
}>

Get PerpetualsAccount wrapper for vault's account.

Example:

const { account } = await vault.getAccount();

// Use account methods
for (const position of account.account.positions) {
	console.log(
		`Position in ${position.marketId}: ${position.baseAssetAmount}`,
	);
}

---

getLpCoinPrice

async getLpCoinPrice(): Promise<number>

Get current LP token price in collateral units.

Example:

const lpPrice = await vault.getLpCoinPrice();
console.log(`1 LP = ${lpPrice} USD`);

---

isPaused

isPaused(): boolean

Check if vault is paused.

Example:

if (vault.isPaused()) {
	console.log("Vault is paused");
}

---

Static Validation Methods

PerpetualsVault.isValidLpCoinName

static isValidLpCoinName(value: string): boolean

Check if string is valid LP coin name (ASCII only).

---

PerpetualsVault.isValidLpCoinTypeSymbol

static isValidLpCoinTypeSymbol(value: string): boolean

Check if string is valid LP coin symbol (A-Z and underscore).

---

Calculation Methods

PerpetualsVault.calcWithdrawRequestSlippage

static calcWithdrawRequestSlippage(inputs: {
  withdrawRequest: PerpetualsVaultWithdrawRequest;
}): number

Calculate withdraw request slippage.

Formula:

(lpAmountInUsd - minCollateralAmountOutUsd) / lpAmountInUsd

Example:

const slippage = PerpetualsVault.calcWithdrawRequestSlippage({
	withdrawRequest,
});

console.log(`Slippage tolerance: ${slippage * 100}%`);

---

Complete Usage Examples

Example 1: User Vault Lifecycle

// 1. Deposit
const depositPreview = await vault.getPreviewDeposit({
	depositAmount: 10_000n * 1_000_000n,
});

const { tx: depositTx } = await vault.getDepositTx({
	walletAddress: "0xUSER_ADDRESS",
	depositAmount: 10_000n * 1_000_000n,
	minLpAmountOut: (depositPreview.lpAmountOut * 99n) / 100n, // 1% slippage
});

// 2. Monitor performance
const lpPrice = await vault.getLpCoinPrice();
console.log(`LP value: ${lpPrice} USD`);

// 3. Request withdrawal
const { tx: withdrawRequestTx } = await vault.getCreateWithdrawRequestTx({
	walletAddress: "0xUSER_ADDRESS",
	lpWithdrawAmount: 5_000n * 1_000_000_000n,
	minCollateralAmountOut: 4_950n * 1_000_000n, // 1% slippage
});

// 4. Wait for lock period, then process

Example 2: Vault Owner Management

// Process withdrawals
const { withdrawRequests } = await vault.getWithdrawRequests({});
const readyToProcess = withdrawRequests.filter(
	(req) => req.readyTimestamp <= Date.now(),
);

const userAddresses = readyToProcess.map((req) => req.walletAddress);

const { tx } = await vault.getOwnerProcessWithdrawRequestsTx({
	userAddresses,
});

// Withdraw fees
const feesPreview = await vault.getPreviewOwnerWithdrawPerformanceFees();

const { tx: feesTx } = await vault.getOwnerWithdrawPerformanceFeesTx({
	withdrawAmount: feesPreview.withdrawableAmount,
	recipientAddress: vault.vaultObject.ownerAddress,
});