@silo-finance/core

Core SDK and pure functional library for Silo Finance. Contains the main SiloSdk class and all calculation logic.

Note: This package provides the SDK interface and calculations. For blockchain connectivity, you need an adapter:

• @silo-finance/adapter-viem - Viem adapter for blockchain reads/writes
• @silo-finance/indexer - GraphQL client for indexed data

Installation

npm install @silo-finance/core

pnpm add @silo-finance/core

SiloSdk Class

The main entry point for interacting with Silo protocol. Uses an adapter for blockchain connectivity.

import { SiloSdk } from "@silo-finance/core";
import { ViemAdapter } from "@silo-finance/adapter-viem";
import { createPublicClient, http } from "viem";
import { arbitrum } from "viem/chains";

const publicClient = createPublicClient({ chain: arbitrum, transport: http() });
const adapter = new ViemAdapter({ provider: publicClient });
const sdk = new SiloSdk({ chain: "arbitrum", adapter });

// Namespaced API
const apr = await sdk.markets.getBorrowAPR(siloAddress);
const position = await sdk.positions.get(market, userAddress);
const balance = await sdk.tokens.getBalance(tokenAddress, userAddress);
const apy = sdk.calc.getApy({ apr, periods: 365n });

SDK Modules

| Module | Description | |--------|-------------| | sdk.markets | Fetch market data, APRs, utilization, liquidity | | sdk.positions | Fetch user positions, LTV, solvency | | sdk.tokens | Token balances, allowances, metadata | | sdk.actions | Write operations (deposit, withdraw, borrow, repay) | | sdk.calc | Pure calculations (APY, risk level, LTV analysis) |

Calculation Modules

The SDK provides focused modules for different calculation domains:

| Module | Import | Description | |--------|--------|-------------| | apr | @silo-finance/core/apr | APR/APY calculations, rewards, leverage rates | | ltv | @silo-finance/core/ltv | Loan-to-value analysis, health factors | | health | @silo-finance/core/health | Position health and risk assessment | | silo | @silo-finance/core/silo | ERC4626 vault operations, interest accrual | | market | @silo-finance/core/market | Market utilities and token helpers | | position | @silo-finance/core/position | User position management |

APR Module

Calculate deposit and borrow rates, rewards, and leverage APR.

import {
  getCollateralBaseApr,
  getCollateralBaseAprByUtilization,
  getApy,
  calculateRewardsApr,
  calculateLeverageApr,
  calculateSimpleInterest,
  getProjectionsState,
  getAprState,
} from "@silo-finance/core/apr";

Calculate Supply APR

import { getCollateralBaseApr, getApy } from "@silo-finance/core";

// Calculate supply APR from accrued assets
const supplyApr = getCollateralBaseApr({
  collateralAccruedAssets: 1000000n * 10n ** 18n,
  debtAccruedAssets: 500000n * 10n ** 18n,
  debtBaseApr: 50000000000000000n, // 5% as 1e18
  daoFee: 10000000000000000n,      // 1%
  deployerFee: 5000000000000000n,  // 0.5%
});

// Convert APR to APY (daily compounding)
const supplyApy = getApy({ apr: supplyApr, periods: 365n });

Calculate Leverage APR

import { calculateLeverageApr } from "@silo-finance/core";
import { makePercent, PERCENT_FACTOR } from "@silo-finance/primitives";

const leverageApr = calculateLeverageApr({
  leverage: makePercent(300n * PERCENT_FACTOR / 100n), // 3x
  supplyBaseApr: makePercent(50000000000000000n),      // 5%
  supplyUnderlyingApy: makePercent(0n),
  supplyRewardsApr: makePercent(10000000000000000n),   // 1%
  borrowBaseApr: makePercent(80000000000000000n),      // 8%
  borrowUnderlyingApy: makePercent(0n),
  borrowRewardsApr: makePercent(5000000000000000n),    // 0.5%
});

APR Trend Analysis

import { getProjectionsState, getAprState } from "@silo-finance/core";

const projection = getProjectionsState({
  baseApr: currentApr,
  baseApr3d: threeDayAvgApr,
}); // "increasing" | "decreasing" | "stable"

const aprState = getAprState({
  projectionsState: projection,
  utilizationState: "aboveOptimal",
}); // "stable" | "increasingSlowly" | "increasingRapidly" | "decreasing"

LTV Module

Comprehensive loan-to-value analysis for position health.

import {
  calculateLtv,
  getMaxBorrowWithBuffer,
  getMaxWithdrawWithBuffer,
  convertToken,
  BORROW_LTV_BUFFER,
  WITHDRAW_LTV_BUFFER,
} from "@silo-finance/core/ltv";

Calculate Position LTV

import { calculateLtv } from "@silo-finance/core/ltv";

const ltvResult = calculateLtv({
  collateralSilo: {
    tokenAddress: "0x...",
    decimals: 18,
    protectedBalance: 0n,
    collateralBalance: 100n * 10n ** 18n,
    maxLtv: 800000000000000000n,    // 80%
    lt: 850000000000000000n,        // 85% liquidation threshold
    lendingQuote: 3000n * 10n ** 8n,
    solvencyQuote: 3000n * 10n ** 8n,
  },
  debtSilo: {
    tokenAddress: "0x...",
    decimals: 6,
    debtBalance: 150000n * 10n ** 6n,
    lendingQuote: 10n ** 8n,
    solvencyQuote: 10n ** 8n,
  },
});

// Access results
console.log(ltvResult.lendingLtv);         // Current LTV
console.log(ltvResult.healthFactor);       // Health factor (100% = safe)
console.log(ltvResult.borrowPowerUsed);    // % of borrow capacity used
console.log(ltvResult.riskFactor);         // Distance to liquidation
console.log(ltvResult.isAtRiskOfLiquidation);
console.log(ltvResult.maxBorrow);          // Remaining borrow capacity
console.log(ltvResult.maxWithdraw);        // Max safe withdrawal

Safe Borrow/Withdraw Limits

import { getMaxBorrowWithBuffer, getMaxWithdrawWithBuffer } from "@silo-finance/core/ltv";

// Apply safety buffers to prevent tx failures from price fluctuations
const safeBorrow = getMaxBorrowWithBuffer(ltvResult);    // -0.25% buffer
const safeWithdraw = getMaxWithdrawWithBuffer(ltvResult); // -0.5% buffer

Health Module

Position risk assessment and health factor calculations.

import {
  calculateHealthFactor,
  calculateLTV,
  analyzeHealth,
  getRiskLevel,
  isLiquidatable,
  calculateMaxBorrow,
  calculateRequiredCollateral,
} from "@silo-finance/core/health";

Analyze Position Health

import { analyzeHealth, RiskLevel } from "@silo-finance/core/health";

const health = analyzeHealth(position, prices);

console.log(health.healthFactor);    // 1.5 = 150% collateralized
console.log(health.ltv);             // Current LTV ratio
console.log(health.riskLevel);       // RiskLevel enum
console.log(health.isLiquidatable);  // boolean

// Risk levels
// RiskLevel.Safe       - HF >= 1.5
// RiskLevel.Medium     - HF >= 1.2
// RiskLevel.High       - HF >= 1.05
// RiskLevel.Critical   - HF >= 1.0
// RiskLevel.Insolvent  - HF < 1.0

Silo Module

ERC4626 vault operations and interest calculations.

import {
  convertToShares,
  convertToAssets,
  maxWithdraw,
  sharesForWithdraw,
  getExchangeRate,
  calculateUtilization,
  accrueInterest,
  calculateSupplyAPR,
} from "@silo-finance/core/silo";

ERC4626 Conversions

import { convertToShares, convertToAssets } from "@silo-finance/core/silo";

const silo = {
  totalAssets: 1000000n * 10n ** 18n,
  totalShares: 900000n * 10n ** 18n,
};

const shares = convertToShares(silo, 100n * 10n ** 18n);
const assets = convertToAssets(silo, shares);

Interest Accrual

import { accrueInterest, calculateUtilization, calculateSupplyAPR } from "@silo-finance/core/silo";
import { makePercent, PERCENT_FACTOR } from "@silo-finance/primitives";

// Calculate utilization
const utilization = calculateUtilization(
  1000000n * 10n ** 18n, // deposited
  500000n * 10n ** 18n   // borrowed
); // 50%

// Calculate supply APR from borrow APR
const supplyAPR = calculateSupplyAPR(
  makePercent(80000000000000000n), // 8% borrow APR
  utilization,
  makePercent(10000000000000000n)  // 1% protocol fee
);

// Accrue interest over time
const newPrincipal = accrueInterest(
  1000n * 10n ** 18n,              // principal
  makePercent(50000000000000000n), // 5% APR
  86400                             // 1 day in seconds
);

Market Module

Utilities for working with Silo markets.

import {
  getCollateralSilo,
  getDebtSilo,
  isValidToken,
  getOtherToken,
  getTokens,
} from "@silo-finance/core/market";

Market Navigation

import { getCollateralSilo, getDebtSilo, getOtherToken } from "@silo-finance/core/market";

// Get the silo address for depositing collateral
const collateralSilo = getCollateralSilo(market, tokenAddress);

// Get the silo address for borrowing (opposite silo)
const debtSilo = getDebtSilo(market, tokenAddress);

// Get the paired token in the market
const otherToken = getOtherToken(market, tokenAddress);

Type Safety

All functions use branded types from @silo-finance/primitives to prevent mixing incompatible values:

import type { Amount, Percent, USD } from "@silo-finance/primitives";
import { makePercent, makeAmount, PERCENT_FACTOR } from "@silo-finance/primitives";

// Create typed values
const apr: Percent = makePercent(50000000000000000n); // 5%
const amount: Amount = makeAmount(100n * 10n ** 18n);

// Values use 18 decimal precision (1e18 = 100%)
const fivePercent = (5n * PERCENT_FACTOR) / 100n;

License

MIT