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

Protocol Config

Language-specific account decoding: TypeScript | Python | Rust

Shared Core

The @coalescefi/shared-core package provides shared utilities for calculations across all Coalesce Finance applications.

Installation

npm install @coalescefi/shared-core

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

Overview

shared-core ensures consistent calculations across:

• SDK (client-side)
• API (server-side)
• Indexer (processing)
• Web/Mobile apps (display)

Core Math Helpers

import {
  calculateScaledAmount,
  calculateNormalizedAmount,
  calculateSettlementPayout,
  estimateInterestAccrual,
  formatTokenAmount,
} from '@coalescefi/shared-core';

const scaled = calculateScaledAmount(1_000_000_000n, 1_020_000_000_000_000_000n);
const value = calculateNormalizedAmount(scaled, 1_020_000_000_000_000_000n);
const payout = calculateSettlementPayout(value, 980_000_000_000_000_000n);

const { newScaleFactor } = estimateInterestAccrual(market, BigInt(Math.floor(Date.now() / 1000)));
console.log('Display value:', formatTokenAmount(value, 6));
console.log('Next scale factor:', newScaleFactor.toString());

Note: full withdraw payout is a two-step calculation: normalizedAmount = calculateNormalizedAmount(scaledBalance, scaleFactor) then payout = calculateSettlementPayout(normalizedAmount, settlementFactorWad).

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 borrowCheck = validateBorrowAmount(
  500_000_000n,
  market,
  whitelist,
  BigInt(Math.floor(Date.now() / 1000))
);
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