computeRequiredCollateral()

function computeRequiredCollateral(price, creditedTokenAmount, collateralFactor): bigint;

Performs a conversion from a credited token amount to the required equivalent collateral necessary based on a given collateral factor and price. Formula: creditedAmount × 10_000 ÷ (collateralFactorBp × price), then bumped up (never down) until the contract’s own collateral-factor check would accept it. Most integrators want getRequiredCollateralForDynamicLOC, which fetches the price and factor and returns undefined for a disabled pair instead of throwing.

Parameters

Parameter	Type	Description
price	Price	The price conversion of the pair.
creditedTokenAmount	bigint	The token amount to convert.
collateralFactor	bigint	The collateral factor to apply (in basis points).

Returns

bigint

The smallest collateral amount at or above the floor estimate that the deployed contract’s creation collateral factor check accepts.

Example

const price = await sdk.pricing.getPrice({
  inputToken: WETH,
  outputToken: USDC,
});
const factor = await sdk.loc.getCollateralFactor({
  collateralToken: WETH,
  creditedToken: USDC,
});
// The SDK returns undefined for an unconfigured pair. A configured pair
// with a zero creation factor also cannot back a new dynamic LOC.
if (!factor || factor.creationCollateralFactorBasisPoints === 0n) {
  throw new Error('WETH/USDC is not a configured pair');
}
// 1,000 USDC = 1_000_000_000n (6 decimals). At an 8_000 bp creation
// factor
// the collateral must be worth 1000 / 0.80 = 1,250 USDC. At $2,000/ETH
// that is 0.625 WETH = 625_000_000_000_000_000n wei.
const requiredWei = computeRequiredCollateral(
  price,
  1_000_000_000n,
  factor.creationCollateralFactorBasisPoints
);

Remarks

This is the single required-collateral implementation in the SDK. The floor estimate (all multiplications before one final floor division) can land below what the deployed contract accepts: the contract floors the collateral VALUE first (Pricing.collateralAmountInCreditedToken) and derives the current CF from that floored value, so an estimate that is exact in real numbers can still produce currentCF > creationCF on-chain and revert with InvalidCollateralFactor. The estimate is therefore re-verified through the contract-exact forward mirror (calculateCollateralFactorBasisPoints) and bumped to the first amount that clears the contract’s creation check. For positive credited amounts the result is never 0n, keeping dust validation fail-closed.

Throws

InvalidArgumentError if the collateral factor or oracle price is zero — the amount is undefined for those inputs, and returning a sentinel would be read by callers as a real (zero) minimum.

Throws

Error if no clearing amount is found within the evaluation bound, which indicates the forward mirror has drifted from the contract.