alula docs

Appearance

Data Types ​

ObligationKey ​

Identifies a user's obligation. Combines the user's address with an optional seed to support multiple isolated positions per address.

rust
pub struct ObligationKey {
    pub user: Address,
    pub seed: Option<BytesN<32>>,
}
typescript
export interface ObligationKey {
  seed: Option<Buffer>;
  user: string;
}
  • seed: None creates a standard obligation
  • seed: Some(pair_seed) creates a pair obligation (for composed strategies)

PoolConfig ​

PoolConfig groups its parameters into sub-configs. For detailed descriptions of each parameter, see Configurable Parameters.

rust
pub struct PoolConfig {
    pub status: PoolStatus,
    pub fee_config: PoolFeeConfig,
    pub health_config: PoolHealthConfig,
    pub accrual_model: AccrualModel,
    pub interest_rate_model: InterestRateModel,
    pub ir_reactivity_constant: u32,
}
typescript
export interface PoolConfig {
  accrual_model: AccrualModel;
  fee_config: PoolFeeConfig;
  health_config: PoolHealthConfig;
  interest_rate_model: InterestRateModel;
  ir_reactivity_constant: u32;
  status: PoolStatus;
}

PoolStatus ​

Per-pool operation control using a 4-bit bitfield.

rust
pub struct PoolStatus {
    pub flags: u32,
}
typescript
export interface PoolStatus {
  flags: u32;
}
BitValueOperation
01Deposit enabled
12Borrow enabled
24Add collateral enabled
38Flash loan enabled

Use flags = u32::MAX (or 15) to enable all operations. Use flags = 0 to disable all.

PoolHealthConfig ​

rust
pub struct PoolHealthConfig {
    pub supply_limit: i128,                    // Hard cap on total supply (0 = unlimited)
    pub utilization_ratio_limit_bps: i128,     // Max utilization ratio for new borrows
    pub withdraw_scarcity_limit_bps: i128,     // Max % of supply withdrawable per tx under throttle
    pub withdraw_scarcity_cooldown_s: u64,     // Min seconds between withdrawals under throttle
    pub open_ltv_bps: i128,                    // Max LTV at borrow time (e.g., 7000 = 70%)
    pub close_ltv_bps: i128,                   // Liquidation threshold (e.g., 8000 = 80%)
    pub liability_factor_bps: i128,            // Risk weight for debt (10000–20000; 10000 = 1×)
    pub liquidation_close_factor_bps: i128,    // Max % of debt repayable per liquidation
    pub max_liquidation_incentive_bps: i128,   // Max collateral discount for liquidators
}
typescript
export interface PoolHealthConfig {
  close_ltv_bps: i128;
  liability_factor_bps: i128;
  liquidation_close_factor_bps: i128;
  max_liquidation_incentive_bps: i128;
  open_ltv_bps: i128;
  supply_limit: i128;
  utilization_ratio_limit_bps: i128;
  withdraw_scarcity_cooldown_s: u64;
  withdraw_scarcity_limit_bps: i128;
}

PoolFeeConfig ​

rust
pub struct PoolFeeConfig {
    pub borrow_fee_bps: u32,                    // One-time borrow fee
    pub flash_loan_fee_bps: u32,                // One-time flash loan fee
    pub deposit_fee_bps: u32,                   // One-time deposit fee (usually 0)
    pub withdraw_fee_bps: u32,                  // One-time withdrawal fee (usually 0)
    pub add_collateral_fee_bps: u32,            // One-time add-collateral fee (usually 0)
    pub remove_collateral_fee_bps: u32,         // One-time remove-collateral friction fee (usually 0)
    pub repay_fee_bps: u32,                     // One-time repayment friction fee (usually 0)
    pub withdraw_max_scarcity_fee_bps: u32,     // Max extra fee when utilization exceeds the utilization ratio limit
    pub take_rate_bps: u32,                     // % of borrower interest diverted to a list of beneficiaries
    pub take_rate_beneficiaries: Option<Map<Address, u32>>,       // Take rate share splits
    pub operation_fee_beneficiaries: Option<Map<Address, u32>>,   // One-time fee splits
    pub referrers: Option<Map<Address, u32>>,                     // Allowed referrers and their fee %
}
typescript
export interface PoolFeeConfig {
  add_collateral_fee_bps: u32;
  borrow_fee_bps: u32;
  deposit_fee_bps: u32;
  flash_loan_fee_bps: u32;
  operation_fee_beneficiaries: Option<Map<string, u32>>;
  referrers: Option<Map<string, u32>>;
  remove_collateral_fee_bps: u32;
  repay_fee_bps: u32;
  take_rate_beneficiaries: Option<Map<string, u32>>;
  take_rate_bps: u32;
  withdraw_fee_bps: u32;
  withdraw_max_scarcity_fee_bps: u32;
}

AccrualModel ​

Determines how interest is compounded.

rust
pub enum AccrualModel {
    Compounded,    // Compound interest (default)
}
typescript
export type AccrualModel = {tag: "Compounded", values: void};

InterestRateModel ​

Defines how borrow APR is computed from pool utilization.

rust
pub enum InterestRateModel {
    Kinked(KinkedIRConfig),
}
typescript
export type InterestRateModel = {tag: "Kinked", values: readonly [KinkedIRConfig]};

KinkedIRConfig ​

A piecewise-linear interest rate curve with two kink points.

rust
pub struct KinkedIRConfig {
    pub base_apr_bps: i128,       // Minimum borrow APR regardless of utilization
    pub kink1_ur_bps: i128,       // First utilization kink (e.g., 7000 = 70%)
    pub kink1_apr_bps: i128,      // APR at kink1
    pub kink2_ur_bps: i128,       // Second utilization kink (e.g., 8000 = 80%)
    pub kink2_apr_bps: i128,      // APR at kink2
    pub max_apr_bps: i128,        // Max APR at 100% utilization
}
typescript
export interface KinkedIRConfig {
  base_apr_bps: i128;
  kink1_apr_bps: i128;
  kink1_ur_bps: i128;
  kink2_apr_bps: i128;
  kink2_ur_bps: i128;
  max_apr_bps: i128;
}

GlobalState ​

rust
pub struct GlobalState {
    pub status: u32,
    pub name: String,
    pub is_owned: bool,
    pub admin: Address,
    pub oracle: Address,
    pub swap_provider: Address,
    pub insurance_fund: Address,
    pub deployer: Address,
    pub max_positions: u32,
    pub insolvency_ltv_bps: i128,
    pub min_collateral_value_cents: i128,
    pub update_in_queue_period: u64,
}
typescript
export interface GlobalState {
  admin: string;
  deployer: string;
  insolvency_ltv_bps: i128;
  insurance_fund: string;
  is_owned: boolean;
  max_positions: u32;
  min_collateral_value_cents: i128;
  name: string;
  oracle: string;
  status: u32;
  swap_provider: string;
  update_in_queue_period: Option<u64>;
}

MarketInitParams ​

Parameters used when constructing a new market contract.

rust
pub struct MarketInitParams {
    pub max_positions: u32,
    pub min_collateral_value_cents: i128,
    pub insolvency_ltv_bps: i128,
    pub update_in_queue_period: u64,
    pub is_owned: bool,
}
typescript
// In the TypeScript SDK, market initialization parameters are passed
// directly to Client.deploy() alongside additional deployment fields:
Client.deploy({
  name: string,
  admin: string,
  oracle: string,
  swap_provider: string,
  insurance_fund: string,
  deployer: string,
  max_positions: u32,
  min_collateral_value_cents: i128,
  insolvency_ltv_bps: i128,
  update_in_queue_period: Option<u64>,
}, options)

MarketStatus ​

rust
pub enum MarketStatus {
    Active,             // 0 - All operations allowed
    BorrowFrozen,       // 1 - Borrowing prohibited
    BorrowFrozenByAdmin,// 2 - Borrowing prohibited, IF cannot override
    DepositFrozen,      // 3 - Borrowing and depositing prohibited
    DepositFrozenByAdmin,// 4 - Borrowing and depositing prohibited, IF cannot override
    Frozen,             // 5 - All operations prohibited
    FrozenByAdmin,      // 6 - All operations prohibited, IF cannot override
}
typescript
export type MarketStatus =
  | {tag: "Active", values: void}
  | {tag: "BorrowFrozen", values: void}
  | {tag: "BorrowFrozenByAdmin", values: void}
  | {tag: "DepositFrozen", values: void}
  | {tag: "DepositFrozenByAdmin", values: void}
  | {tag: "Frozen", values: void}
  | {tag: "FrozenByAdmin", values: void};

The *ByAdmin variants are "hard locks": only the market admin can transition into or out of these states. The Insurance Fund cannot override them.

Obligation ​

rust
pub struct Obligation {
    pub deposits: Map<Address, DepositPosition>,
    pub borrows: Map<Address, BorrowPosition>,
    pub positions_count: u32,
    pub insurance_fund_requests_ids: Map<(Address, u64), ()>,
}
typescript
export interface Obligation {
  borrows: Map<string, BorrowPosition>;
  deposits: Map<string, DepositPosition>;
  insurance_fund_requests_ids: Map<readonly [string, u64], void>;
  positions_count: u32;
}

DepositPosition ​

rust
pub struct DepositPosition {
    pub j_tokens: i128,                // Share of total supplied tokens in the pool
    pub collateral: i128,              // Plain collateral (does not accrue interest)
    pub originally_deposited: i128,    // Tracks original deposit for interest accounting
    pub last_scarcity_withdraw_ts: u64,// Timestamp of last scarcity withdrawal
}
typescript
export interface DepositPosition {
  collateral: i128;
  j_tokens: i128;
  last_scarcity_withdraw_ts: u64;
  originally_deposited: i128;
}

BorrowPosition ​

rust
pub struct BorrowPosition {
    pub d_tokens: i128,                // Share of total debt in the pool
    pub originally_borrowed: i128,     // Tracks original borrow for interest accounting
}
typescript
export interface BorrowPosition {
  d_tokens: i128;
  originally_borrowed: i128;
}

Pool ​

rust
pub struct Pool {
    pub pool_address: Address,
    pub token_address: Address,
    pub token_symbol: String,
    pub token_decimals: u32,
    pub total_borrowed: i128,
    pub total_d_tokens: i128,
    pub total_j_tokens: i128,
    pub total_available: i128,
    pub total_collateral: i128,
    pub name: String,
    pub config: PoolConfig,
    pub last_accrual_timestamp: u64,
    pub borrow_apr_bps: i128,
    pub supply_apr_bps: i128,
    pub operation_fees_sum: i128,
    pub take_rate_fees_sum: i128,
    pub target_utilization_ratio_bps: i128,
    pub interest_rate_modifier: i128,
}
typescript
export interface Pool {
  borrow_apr_bps: i128;
  config: PoolConfig;
  interest_rate_modifier: i128;
  last_accrual_timestamp: u64;
  name: string;
  operation_fees_sum: i128;
  pool_address: string;
  supply_apr_bps: i128;
  take_rate_fees_sum: i128;
  target_utilization_ratio_bps: i128;
  token_address: string;
  token_decimals: u32;
  token_symbol: string;
  total_available: i128;
  total_borrowed: i128;
  total_collateral: i128;
  total_d_tokens: i128;
  total_j_tokens: i128;
}

PoolData ​

Extended pool information with computed values. Returned by get_pool_data.

rust
pub struct PoolData {
    pub pool: Pool,
    pub apy: AnnualPercentageYields,
    pub total_supply: i128,
    pub total_available_adjusted: i128,
    pub j_token_rate_floor_bps: i128,
    pub d_token_rate_ceil_bps: i128,
    pub oracle_asset_price: i128,
}
typescript
export interface PoolData {
  apy: AnnualPercentageYields;
  d_token_rate_ceil_bps: i128;
  j_token_rate_floor_bps: i128;
  oracle_asset_price: i128;
  pool: Pool;
  total_available_adjusted: i128;
  total_supply: i128;
}

AnnualPercentageYields ​

rust
pub struct AnnualPercentageYields {
    pub borrow_bps: u32,
    pub supply_bps: u32,
}
typescript
export interface AnnualPercentageYields {
  borrow_bps: u32;
  supply_bps: u32;
}

MarketData ​

Aggregated market data. Returned by get_market_data.

rust
pub struct MarketData {
    pub pools_data: Vec<PoolData>,
    pub global_state: GlobalState,
    pub oracle_price_decimals: u32,
}
typescript
export interface MarketData {
  asset_decimals: u32;
  global_state: GlobalState;
  multiply_pairs: Array<MultiplyPair>;
  oracle_price_decimals: u32;
  pools_data: Array<PoolData>;
}

MarketUpdate ​

A queued market configuration update.

rust
pub struct MarketUpdate {
    pub new_max_positions: u32,
    pub new_min_collateral_value_cents: i128,
    pub queued_in_timestamp: u64,
}
typescript
// The TypeScript SDK does not expose a direct MarketUpdate type.
// Market updates are queued via the update_market method:
update_market: (
  {new_max_positions, new_min_collateral_value_cents}:
    {new_max_positions: u32, new_min_collateral_value_cents: i128},
  options?: MethodOptions
) => Promise<AssembledTransaction<Result<void>>>

QueuedPoolSet ​

A queued pool creation or configuration update.

rust
pub struct QueuedPoolSet {
    pub token_address: Address,
    pub new_config: PoolConfig,
    pub queued_in_timestamp: u64,
}
typescript
// In the TypeScript SDK, queued pool config updates are represented
// by the PoolUpdate interface (returned by get_pool_config_queued_in_update):
export interface PoolUpdate {
  new_config: PoolConfig;
  queued_in_timestamp: u64;
}