Python SDK#

from coalescefi_sdk import CoalesceClient

client = CoalesceClient.mainnet("https://api.mainnet-beta.solana.com")

lender = Pubkey.from_string("Lender...")
market = Pubkey.from_string("Market...")

# Build a deposit instruction (resolves vault, ATA, blacklist check, etc.)
ixs = await client.deposit(lender, market, 100_000_000_000)  # 100,000 USDC (6 decimals)

# Withdraw all shares and close the position in one transaction
ixs = await client.withdraw_and_close(lender, market)

# Claim haircut recovery after a settlement shortfall
ixs = await client.claim_haircut(lender, market)

# Claim haircut and close the position in one transaction
ixs = await client.claim_haircut_and_close(lender, market)

from solana.rpc.async_api import AsyncClient
from solders.pubkey import Pubkey

from coalescefi_sdk import (
    configure_sdk,
    find_market_pda,
    find_lender_position_pda,
    fetch_market,
    create_deposit_instruction,
)

# Configure the SDK
configure_sdk(network="devnet")

# Or with explicit program ID
configure_sdk(program_id=Pubkey.from_string("CoaLfi..."))

# Derive PDAs
borrower = Pubkey.from_string("Borrower...")
market_pda, market_bump = find_market_pda(borrower, market_nonce=1)
lender_pda, lender_bump = find_lender_position_pda(market_pda, lender_pubkey)

# Fetch account data
async def main():
    connection = AsyncClient("https://api.devnet.solana.com")
    market = await fetch_market(connection, market_pda)
    if market:
        print(f"Total deposited: {market.total_deposited}")
        print(f"Interest rate: {market.annual_interest_bps} bps")

asyncio.run(main())

from coalescefi_sdk import (
    find_protocol_config_pda,
    find_market_pda,
    find_market_authority_pda,
    find_vault_pda,
    find_lender_position_pda,
    find_borrower_whitelist_pda,
    find_blacklist_check_pda,
    find_haircut_state_pda,
    derive_market_pdas,
)

# Protocol config (singleton)
config_pda, config_bump = find_protocol_config_pda()

# Market PDAs
market_pda, market_bump = find_market_pda(borrower, market_nonce=1)
authority_pda, authority_bump = find_market_authority_pda(market_pda)
vault_pda, vault_bump = find_vault_pda(market_pda)

# Lender position
lender_pda, lender_bump = find_lender_position_pda(market_pda, lender)

# Borrower whitelist
whitelist_pda, whitelist_bump = find_borrower_whitelist_pda(borrower)

# Haircut state (per-market, tracks recovery distribution)
haircut_state_pda, haircut_bump = find_haircut_state_pda(market_pda)

# Derive all market-related PDAs at once
market_pdas = derive_market_pdas(borrower, market_nonce=1)
print(market_pdas.market)
print(market_pdas.market_authority)
print(market_pdas.vault)

from solana.rpc.async_api import AsyncClient
from coalescefi_sdk import (
    fetch_protocol_config,
    fetch_market,
    fetch_lender_position,
    fetch_borrower_whitelist,
    RetryConfig,
)

async def fetch_accounts():
    connection = AsyncClient("https://api.devnet.solana.com")

    # With default retry config (3 retries, exponential backoff)
    market = await fetch_market(connection, market_pda)

    # With custom retry config
    custom_retry = RetryConfig(
        max_retries=5,
        base_delay_ms=500,
        max_delay_ms=5000
    )
    config = await fetch_protocol_config(
        connection,
        config_pda,
        retry_config=custom_retry
    )

    # Returns None if account doesn't exist
    position = await fetch_lender_position(connection, lender_pda)
    if position is None:
        print("Position not found")

from coalescefi_sdk import (
    decode_protocol_config,
    decode_market,
    decode_lender_position,
    decode_borrower_whitelist,
    decode_account,  # Auto-detects type
)

# Decode specific account type
market = decode_market(account_data)
print(f"Borrower: {market.borrower}")
print(f"Annual interest: {market.annual_interest_bps} bps")
print(f"Maturity: {market.maturity_timestamp}")

# Auto-detect and decode
account = decode_account(raw_data)
if isinstance(account, Market):
    print("It's a market!")

from coalescefi_sdk import (
    create_deposit_instruction,
    create_borrow_instruction,
    create_repay_instruction,
    create_withdraw_instruction,
)

# Deposit instruction
deposit_ix = create_deposit_instruction(
    accounts={
        "market": market_pda,
        "lender": lender_pubkey,
        "lender_token_account": lender_ata,
        "vault": vault_pda,
        "lender_position": lender_position_pda,
        "blacklist_check": blacklist_check_pda,
        "protocol_config": config_pda,
        "mint": usdc_mint,
        "token_program": TOKEN_PROGRAM_ID,
        "system_program": SYSTEM_PROGRAM_ID,
    },
    args={"amount": 1_000_000},  # 1 USDC (6 decimals)
)

from coalescefi_sdk import (
    CoalescefiError,
    CoalescefiErrorCode,
    parse_coalescefi_error,
    is_user_recoverable_error,
    get_error_recovery_action,
)

try:
    # ... transaction execution
    pass
except Exception as e:
    error = parse_coalescefi_error(e)
    if error:
        print(f"Error code: {error.code.name}")
        print(f"Message: {error.message}")

        if is_user_recoverable_error(error.code):
            action = get_error_recovery_action(error.code)
            print(f"Recovery action: {action}")

from coalescefi_sdk import (
    IdempotencyManager,
    generate_idempotency_key,
)

manager = IdempotencyManager()

# Generate deterministic key for operation
key = generate_idempotency_key("deposit", {
    "market": str(market_pda),
    "amount": str(amount),
    "lender": str(lender),
})

# Execute with idempotency protection
async def safe_deposit():
    result = await manager.execute_once(
        connection,
        key,
        lambda: execute_deposit_transaction(),
    )
    return result

from coalescefi_sdk import (
    # Core WAD arithmetic
    mul_wad,              # (a * b) / WAD
    pow_wad,              # base^exp in WAD
    growth_factor_wad,    # Daily compound + linear sub-day growth

    # Deposit/Withdraw conversions
    calculate_scaled_amount,      # tokens → sTokens (shares)
    calculate_normalized_amount,  # sTokens → tokens

    # Position analysis
    calculate_position_value,     # Current value of lender shares
    estimate_value_at_maturity,   # Projected value at maturity
    calculate_settlement_payout,  # Actual payout after settlement

    # Market analytics
    estimate_interest_accrual,    # Preview interest growth
    calculate_total_supply,       # Normalized total supply
    calculate_available_vault_balance,  # Deprecated approximation; prefer vault RPC balance
    calculate_utilization_rate,   # Outstanding principal / supply (bps + decimal)
    calculate_apr,                # BPS to decimal (e.g., 1000 → 0.10)

    # Utilities
    safe_divide,          # Returns 0 on division by zero
    would_overflow_u64,
    would_overflow_u128,

    # Constants
    SECONDS_PER_DAY,      # 86,400
    DAYS_PER_YEAR,        # 365

    # Types
    InterestAccrualResult,
    UtilizationRateResult,
    MathOverflowError,
)

from coalescefi_sdk import (
    calculate_apr,
    calculate_total_supply,
    calculate_utilization_rate,
    fetch_market,
)

market = await fetch_market(connection, market_pda)

apr = calculate_apr(market.annual_interest_bps)
total_supply = calculate_total_supply(market.scaled_total_supply, market.scale_factor)
utilization = calculate_utilization_rate(market)

print(f"APR: {apr * 100:.2f}%")
print(f"Total supply: {total_supply}")
print(f"Utilization: {utilization.decimal * 100:.2f}% ({utilization.bps} bps)")

# Exact available vault balance: read the SPL Token account balance for market.vault via RPC.
# Deprecated approximation if you only have market counters:
# approx_available = calculate_available_vault_balance(market)

from coalescefi_sdk import (
    calculate_settlement_payout,
    calculate_normalized_amount,
)

# After maturity — what does a lender actually receive?
# Two-step: normalize by scale_factor, then apply settlement_factor
payout = calculate_settlement_payout(
    position.scaled_balance, market.scale_factor, market.settlement_factor_wad
)
full_value = calculate_normalized_amount(
    position.scaled_balance, market.scale_factor
)
haircut_bps = (full_value - payout) * 10_000 // full_value if full_value > 0 else 0
print(f"Payout: {payout}, haircut: {haircut_bps / 100:.2f}%")

from coalescefi_sdk import (
    # Mathematical constants
    WAD,  # 10^18 - precision factor
    BPS,  # 10000 - basis points denominator
    SECONDS_PER_YEAR,

    # Protocol limits
    MAX_ANNUAL_INTEREST_BPS,  # 10000 (100%)
    MAX_FEE_RATE_BPS,  # 10000 (100%)
    USDC_DECIMALS,  # 6

    # Account sizes
    PROTOCOL_CONFIG_SIZE,
    MARKET_SIZE,
    LENDER_POSITION_SIZE,
    BORROWER_WHITELIST_SIZE,
    HAIRCUT_STATE_SIZE,      # 88 bytes

    # Seeds
    SEED_PROTOCOL_CONFIG,
    SEED_MARKET,
    SEED_VAULT,
    SEED_HAIRCUT_STATE,
)