SDK Guide#

Coalesce Finance provides SDKs for building applications on the permissioned lending protocol.

Available SDKs#

PDA Reference#

All account addresses in Coalesce Finance are Program Derived Addresses (PDAs). Each SDK provides helpers for deriving these addresses.

Language-specific derivation code: TypeScript | Python | Rust

Available Instructions#

Language-specific instruction building: TypeScript | Python | Rust

Account Structures#

Market#

Lender Position#

Borrower Whitelist#

Haircut State#

Protocol Config#

Language-specific account decoding: TypeScript | Python | Rust

Shared Core#

The @coalescefi/shared-core package provides validation, formatting, and resilience utilities shared across all Coalesce Finance TypeScript applications (web, mobile, API, indexer).

Installation#

npm install @coalescefi/shared-core

Note: This is typically installed as a dependency of @coalescefi/sdk.

Math Functions#

Math functions (WAD arithmetic, interest accrual, utilization, etc.) are maintained in @coalescefi/sdk and re-exported by shared-core for convenience. See the TypeScript SDK Math Reference for the full API.

// Preferred: import math directly from the SDK
import { calculateNormalizedAmount, estimateInterestAccrual } from '@coalescefi/sdk';

// Also works: shared-core re-exports all SDK math functions
import { calculateNormalizedAmount, estimateInterestAccrual } from '@coalescefi/shared-core';

Validation Helpers#

import { validateDepositAmount, validateBorrowAmount } from '@coalescefi/shared-core';

const depositCheck = validateDepositAmount(
  1_000_000n,
  market,
  BigInt(Math.floor(Date.now() / 1000))
);
if (!depositCheck.isValid) {
  console.error(depositCheck.error);
}

const liveVaultBalance = await readVaultBalance(connection, market.vault);
const borrowCheck = validateBorrowAmount(
  500_000_000n,
  market,
  whitelist,
  BigInt(Math.floor(Date.now() / 1000)),
  liveVaultBalance // read from the vault token account via RPC for exactness
);
if (!borrowCheck.isValid) {
  console.error(borrowCheck.errorCode);
}

Formatting Helpers#

import { formatTokenAmount, formatUSD, formatBps, formatPercent } from '@coalescefi/shared-core';

console.log(formatTokenAmount(10_500_000_000n, 6)); // "10,500.00"
console.log(formatUSD(10_500_000_000n, 6)); // "$10,500.00"
console.log(formatBps(800)); // "8%"
console.log(formatPercent(0.75)); // "75%"

Shared Types and Constants#

import type {
  ValidationResult,
  Market,
  LenderPosition,
  BorrowerWhitelist,
} from '@coalescefi/shared-core';
import { WAD, USDC_DECIMALS, SECONDS_PER_YEAR } from '@coalescefi/shared-core';

Related#

• TypeScript SDK
• Python SDK
• Rust SDK
• Error Codes
• Protocol Calculations
• API Reference
• Architecture