@silo-finance/primitives

Branded types, math utilities, and formatters for type-safe DeFi calculations.

Installation

npm install @silo-finance/primitives

pnpm add @silo-finance/primitives

Modules

| Module | Import | Description | |--------|--------|-------------| | types | @silo-finance/primitives/types | Branded primitive types (Amount, Percent, USD, Address) | | math | @silo-finance/primitives/math | Fixed-point arithmetic, bigint utilities | | format | @silo-finance/primitives/format | Human-readable formatters | | constants | @silo-finance/primitives/constants | Time constants |

Branded Types

Branded types prevent accidentally mixing incompatible values at compile time.

Amount

Raw token amounts as bigint (no inherent decimals).

import { makeAmount, AMOUNT_ZERO, parseAmount } from "@silo-finance/primitives";
import type { Amount } from "@silo-finance/primitives";

const amount: Amount = makeAmount(100n * 10n ** 18n);
const zero: Amount = AMOUNT_ZERO;
const parsed: Amount = parseAmount("1000000000000000000");

Percent

Percentages with 18 decimal precision. 1e18 = 100%.

import {
  makePercent,
  percentFromDecimal,
  percentFromNumber,
  percentToDecimal,
  percentToNumber,
  PERCENT_FACTOR,
  PERCENT_ZERO,
  PERCENT_ONE_HUNDRED,
} from "@silo-finance/primitives";
import type { Percent } from "@silo-finance/primitives";

// Create percentages
const fivePercent = makePercent(5n * PERCENT_FACTOR / 100n);
const fromDecimal = percentFromDecimal(0.05);  // 5%
const fromNumber = percentFromNumber(5);       // 5%

// Convert back
percentToDecimal(fivePercent); // 0.05
percentToNumber(fivePercent);  // 5

// Common constants
PERCENT_ZERO;        // 0%
PERCENT_ONE_HUNDRED; // 100%
PERCENT_FACTOR;      // 1e18 (the scaling factor)

USD

USD values with 6 decimal precision.

import { makeUSD, USD_ZERO, USD_DECIMALS } from "@silo-finance/primitives";
import type { USD } from "@silo-finance/primitives";

const tenDollars: USD = makeUSD(10n * 10n ** BigInt(USD_DECIMALS));

Address

Validated Ethereum addresses.

import { makeAddress, addressEquals, isAddress } from "@silo-finance/primitives";
import type { Address } from "@silo-finance/primitives";

const addr: Address = makeAddress("0x1234...");
addressEquals(addr1, addr2); // Case-insensitive comparison
isAddress(maybeAddress);     // Type guard

Formatters

Human-readable display formatting.

import {
  formatAmount,
  formatPercent,
  formatPercentDecimal,
  formatPercentMultiplier,
  formatUSD,
  parsePercent,
} from "@silo-finance/primitives";

// Format percentages
formatPercent(fivePercent);           // "5.00%"
formatPercent(fivePercent, 4);        // "5.0000%"
formatPercentDecimal(fivePercent);    // "0.0500"
formatPercentMultiplier(leverage);    // "3.00x"

// Parse from strings
parsePercent("75%");  // Percent
parsePercent("0.75"); // Percent

// Format amounts (requires decimals)
formatAmount(amount, 18);    // "100.00"
formatAmount(amount, 18, 4); // "100.0000"

// Format USD
formatUSD(usdValue); // "$10.00"

Math Utilities

BigInt Helpers

import { abs, min, max, clamp, shiftDecimal } from "@silo-finance/primitives";

abs(-100n);              // 100n
min(10n, 20n);           // 10n
max(10n, 20n);           // 20n
clamp(5n, 0n, 10n);      // 5n (within bounds)
clamp(-5n, 0n, 10n);     // 0n (clamped to min)

// Shift decimals (positive = multiply, negative = divide)
shiftDecimal(100n, 2);   // 10000n
shiftDecimal(10000n, -2); // 100n

Fixed-Point Math

18-decimal precision arithmetic ported from Solidity (Balancer MathSol, PRBMath).

import { MathSol, WAD, LogExpMath } from "@silo-finance/primitives/math";

// WAD = 1e18 (standard DeFi precision)
const oneWad = WAD; // 1_000_000_000_000_000_000n

// Multiplication (result is WAD-scaled)
MathSol.mulDownFixed(2n * WAD, 3n * WAD); // 6 * WAD (rounds down)
MathSol.mulUpFixed(2n * WAD, 3n * WAD);   // 6 * WAD (rounds up)

// Division (result is WAD-scaled)
MathSol.divDownFixed(6n * WAD, 2n * WAD); // 3 * WAD (rounds down)
MathSol.divUpFixed(6n * WAD, 2n * WAD);   // 3 * WAD (rounds up)

// Integer division with rounding up
MathSol.divUp(10n, 3n); // 4n (ceil)

// Power function
MathSol.powDownFixed(2n * WAD, 3n * WAD); // 8 * WAD (2^3, rounds down)
MathSol.powUpFixed(2n * WAD, 3n * WAD);   // 8 * WAD (2^3, rounds up)

// Complement: 1 - x
MathSol.complementFixed(WAD / 4n); // 0.75 * WAD

// Exponential and logarithm
LogExpMath.exp(WAD);               // e^1 in WAD
LogExpMath.pow(2n * WAD, WAD / 2n); // sqrt(2) in WAD

Constants

Time Constants

import {
  ONE_DAY_SECONDS,
  THREE_DAYS_SECONDS,
  ONE_WEEK_SECONDS,
  ONE_MONTH_SECONDS,
  SIX_MONTHS_SECONDS,
  ONE_YEAR_SECONDS,
} from "@silo-finance/primitives/constants";

ONE_DAY_SECONDS;   // 86400n
ONE_YEAR_SECONDS;  // 31536000n

Percent Constants

import {
  PERCENT_FACTOR,
  PERCENT_DECIMALS,
  PERCENT_ZERO,
  PERCENT_ONE,
  PERCENT_HALF,
  PERCENT_ONE_HUNDRED,
} from "@silo-finance/primitives";

PERCENT_FACTOR;      // 1e18
PERCENT_DECIMALS;    // 18
PERCENT_ZERO;        // 0n (0%)
PERCENT_ONE;         // 1e16 (1%)
PERCENT_HALF;        // 5e17 (50%)
PERCENT_ONE_HUNDRED; // 1e18 (100%)

Protocol Types

The package also exports TypeScript interfaces for Silo protocol entities:

import type {
  Token,
  Market,
  Silo,
  APRData,
  InterestRateModel,
} from "@silo-finance/primitives";

License

MIT