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>>,
}
  • seed: None — standard obligation
  • seed: Some(earn_seed) — earn-only obligation (deposit-only, no borrowing)
  • seed: Some(pair_seed) — 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,
}

PoolStatus ​

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

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

Use flags = u32::MAX 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
}

PoolFeeConfig ​

rust
pub struct PoolFeeConfig {
    pub borrow_fee_bps: u32,                    // One-time borrow origination fee
    pub flash_loan_fee_bps: u32,                // Flash loan fee
    pub deposit_fee_bps: u32,                   // Deposit friction fee (usually 0)
    pub withdraw_fee_bps: u32,                  // Withdrawal friction fee (usually 0)
    pub withdraw_max_scarcity_fee_bps: u32,     // Max extra fee during high utilization
    pub add_collateral_fee_bps: u32,            // Add-collateral friction fee (usually 0)
    pub remove_collateral_fee_bps: u32,         // Remove-collateral friction fee (usually 0)
    pub repay_fee_bps: u32,                     // Repayment friction fee (usually 0)
    pub take_rate_bps: u32,                     // % of borrower interest diverted as revenue
    pub take_rate_beneficiaries: Option<Map<Address, u32>>,       // Revenue share splits
    pub operation_fee_beneficiaries: Option<Map<Address, u32>>,   // Origination fee splits
    pub referrers: Option<Map<Address, u32>>,                     // Allowed referrers and their fee %
}

AccrualModel ​

Determines how interest is compounded.

rust
pub enum AccrualModel {
    Compounded,    // Compound interest (default)
}

InterestRateModel ​

Defines how borrow APR is computed from pool utilization.

rust
pub enum InterestRateModel {
    Kinked(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
}

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,
}

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,
}

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
}

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), ()>,
}

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
}

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
}

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,
}

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,
}

AnnualPercentageYields ​

rust
pub struct AnnualPercentageYields {
    pub borrow_bps: u32,
    pub 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,
}

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,
}

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,
}