npm package: @silo-finance/primitives
Description: Branded types, math utilities, and formatters for Silo Finance SDK
Latest version: 0.0.1

# @silo-finance/primitives

<a href="https://www.npmjs.com/package/@silo-finance/primitives">
    <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/v/@silo-finance/primitives?colorA=21262d&colorB=21262d&style=flat">
        <img src="https://img.shields.io/npm/v/@silo-finance/primitives?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="Version">
    </picture>
</a>
<a href="https://github.com/silo-finance/silo-sdk/blob/main/LICENSE">
    <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/l/@silo-finance/primitives?colorA=21262d&colorB=21262d&style=flat">
        <img src="https://img.shields.io/npm/l/@silo-finance/primitives?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="MIT License">
    </picture>
</a>
<br />
<br />

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

## Installation

```bash
npm install @silo-finance/primitives
```

```bash
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).

```typescript
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%`.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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

```typescript
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).

```typescript
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

```typescript
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

```typescript
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:

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

## License

[MIT](/LICENSE)