FAQ

Troubleshooting

Why won't my wallet connect, or why does it keep disconnecting?

Make sure you're on the right network (testnet vs mainnet), refresh the page, and reconnect from the wallet extension/app. If it still drops, close other dapps using the wallet and try again.

What should I do if a transaction is pending for a long time or fails after I sign it?

Don't keep re-signing the same transaction. Check your wallet activity/history, make sure you have enough XLM for fees, then retry once. If it keeps failing, try a smaller amount (you may be hitting a limit or cap).

What happens if I don't have enough XLM to pay network fees?

Your transaction won't submit or will fail. Add a small amount of XLM to your wallet, then try again.

Why can't I supply or borrow more even when I have balance and the market shows liquidity?

You may be blocked by a pool rule, not your wallet balance. Common reasons: the pool hit its Supply Limit, borrowing is constrained by available liquidity, utilization-based throttles are active, or the market is temporarily paused for certain actions.

Why is an asset marked Restricted, and what does it mean for me?

Restricted assets require extra rules (like KYC/allow-listing). If you're not eligible, you may be unable to supply, borrow, or use that asset as collateral until you meet the requirements.

Why can't I borrow in the same pool where I have a deposit (or supply to a pool where I have an active loan)?

Alula can separate "earning" positions from borrowing positions depending on how you supplied. If you supplied in a way that's meant to be borrow-disabled (for example, an earn-only path), you won't be able to borrow from that same position. Use the standard supply/borrow flow instead.

Why does a withdrawal get blocked even when I'm not trying to take out "too much"?

Withdrawals can be blocked if the pool doesn't have enough available liquidity right now, if withdrawal throttles are active at high utilization, or if withdrawing would reduce your collateral too much (hurting your health factor).

Conceptual

What is an ObligationKey and how do different position types work?

An ObligationKey combines your wallet address with an optional seed to identify your position in a market. With no seed, you get a standard obligation that can both supply and borrow. With a specific "earn" seed, you get an earn-only obligation that can only deposit and withdraw (no borrowing). With a "pair" seed, you get a pair obligation used for composed strategies. This lets a single wallet address hold multiple isolated positions in the same market, each with different capabilities and risk profiles.

What's the difference between jTokens (supply shares) and plain collateral?

When you deposit via the standard flow, you receive jTokens — supply shares that earn interest as the pool accrues borrower payments. jTokens grow in value over time and also count as collateral for borrowing. Plain collateral, added via add_collateral, does not earn interest but is prioritized during liquidation (liquidators receive plain collateral first). Both types contribute to your health factor and borrowing capacity.

What does the time-lock on configuration changes mean for me as a user?

All pool and market configuration changes go through a mandatory waiting period (the time-lock). When an admin queues a change, it cannot take effect until the time-lock period has elapsed. This gives you time to review the upcoming change and exit your position if you disagree — you are never surprised by sudden parameter shifts.

How does the health factor work and when does liquidation happen?

Your health factor (HF) is the ratio of your collateral value to your borrowed value. An HF above 1 means you're solvent. However, liquidation eligibility is determined by the liquidation health factor (LHF), which weights each asset by its close LTV and liability factor. When your LHF drops below 1 — due to price movements, accrued interest, or a combination — your position becomes eligible for partial liquidation. A liquidator can repay a portion of your debt and seize collateral at a discount. See Health Factor for the full formula.

What happens if there's bad debt in a pool?

If an obligation becomes insolvent (debt exceeds collateral), the protocol attempts liquidations to reduce the shortfall. Any remaining bad debt is covered through a two-phase insurance fund process. If the insurance fund is insufficient, the residual loss is socialized across all lenders in the affected pool — everyone's jToken exchange rate decreases proportionally. See Insurance Fund for details.

Developer

How do I read pool or obligation state directly from the ledger?

For production use, you should read storage entries directly rather than calling view functions (which are constrained by Soroban resource limits). Use get_pool(pool_address) for pool state, get_user_obligation(obligation_key) for obligation data, and get_market_data() for a full snapshot. The AllPools and AllObligations storage keys give you the complete list of pools and active obligation keys. See Query Operations for all available functions.

How do I compose a leveraged position using batch operations?

Use submit_requests_batch with a sequence of requests: (1) FlashBorrow the asset you want to lever, (2) SwapExactTokens to convert it to your target collateral, (3) Deposit the collateral, (4) Borrow the original asset to repay the flash loan. The flash loan auto-repays at the end of the batch. The entire sequence executes atomically — if any step fails, nothing happens. See Developer Quickstart for a full code example.

What does error code 207 (UnhealthyOperation) mean?

Error 207 (UnhealthyOperation) means your transaction would leave the obligation in an unhealthy state — the remaining borrowing capacity would be negative. This typically happens when you try to borrow more than your collateral supports, or withdraw collateral that is backing active borrows. To resolve it, reduce the borrow/withdrawal amount, add more collateral, or repay some existing debt first. See Error Codes for all error codes.