feat(lending): multi-collateral positions, per-asset liquidation incentive, configurable rate model (#1193, #1194, #1195)

[Abidoyesimze]

Closes #1192
Closes #1193
Closes #1194
Closes #1195

All three changes are in contracts/lending, where each issue's description matches the code:

• a borrow position held a single BorrowCollateral { amount, asset };
• liquidate was a stub that returned Ok(());
• the liquidation incentive and the rate model had no public setter beyond the base rate.

Prerequisite: lending didn't compile on main

#1355 renamed BorrowDataKey::StableRateRecalcIntervalSecs to StableRateRecalcInterval and removed RateSwitchFeeBps, but borrow.rs still reads both. The first commit restores the original names. Soroban encodes enum keys by variant name, so this also keeps values that existing deployments stored readable. It also annotates one type the compiler couldn't infer. This commit is standalone and compiles on its own.

#1195 Multi-collateral positions

• Storage: a position holds up to MAX_COLLATERAL_ASSETS (8) assets in a per-user Map<asset, amount>. Legacy single-asset records are read transparently and moved into the map on their next write, so no migration step is needed. The cap bounds the oracle calls made per health check.
• Valuation: get_collateral_value, get_health_factor, get_max_liquidatable_amount and get_user_position sum every asset at its own oracle price. get_user_collaterals(user) lists the balances. get_user_collateral keeps working and returns the largest holding.
• liquidate(liquidator, borrower, debt_asset, collateral_asset, amount) -> LiquidationResult:
  • Requires the aggregated health factor to be below 1.0.
  • Repays min(amount, debt × close_factor).
  • Seizes the chosen asset at repay × debt_price × (1 + incentive) / collateral_price.
  • If the borrower holds less of that asset, it seizes all of it and reduces the repayment to match.
  • Reduces debt interest first, then principal, and emits the shared LiquidationEvent.
• Fails closed on missing prices. If any collateral asset has no usable price, liquidation returns PriceUnavailable instead of counting that asset as worthless. An oracle gap therefore can't make a healthy position liquidatable.
• New errors: TooManyCollateralAssets, SelfLiquidation, PriceUnavailable.

#1193 Per-asset liquidation incentive

• set_asset_liq_incentive_bps(admin, asset, Some(bps) | None) sets or clears an override. get_asset_liq_incentive_bps(asset) returns the incentive in effect. The global set_liquidation_incentive_bps / get_liquidation_incentive_bps are now exposed too.
• Both setters are admin-only and bounded to 1%–25% (IncentiveOutOfBounds otherwise). The internal setter previously accepted 0–100%.
  • Below 1%, liquidations rarely pay for themselves.
  • At 25%, with the default 80% liquidation threshold, threshold × (1 + incentive) = 100%, so a liquidation never seizes more value than backs the debt it repays.
• Liquidation applies the incentive of the asset being seized. Changes emit LiqIncentiveUpdatedEvent.

#1194 Configurable interest rate model

• set_interest_rate_config(admin, InterestRateConfigUpdate) exposes every parameter of the existing kinked model: base, kink, slope, jump slope, floor, ceiling and spread.
  • Fields are optional, and the whole update is validated before anything is written.
  • It's admin-only. To gate changes behind governance, make the governance or timelock contract the admin.
  • Changes emit RateConfigUpdatedEvent.
• New views: get_interest_rate_config, get_borrow_rate_bps, get_supply_rate_bps, get_utilization_bps.

Design notes for review

• Liquidation settles on the ledger only, like repay. The borrow module holds no tokens in custody: deposit_collateral, borrow and repay don't transfer any. Paying out "seized" collateral as real tokens would draw on funds the module never received. Real custody would need deposit, borrow, repay and liquidation changed together, so it's a separate change.
• Rate changes reprice un-accrued time. Variable debt accrues at the current rate over the time since a position last updated, so a rate change also applies to that period. set_variable_borrow_rate_bps already behaves this way; fixing it needs a global borrow index.
• Event names are shortened to stay within Soroban's 32-byte limit (liq_incentive_updated_event, rate_config_updated_event). The entry points are set_asset_liq_incentive_bps / get_asset_liq_incentive_bps for the same reason.

Testing

The in-crate unit tests don't compile on main: about 50 errors in five files that test features which were never merged. The admin_privileges integration target is broken for the same reason (set_guardian / guardian_pause). I didn't touch either. The new tests are integration suites against the public contract surface:

Suite	Tests
multi_collateral (new)	11
liquidation_incentive (new)	5
interest_rate_model (new)	6
event_topics (+1 test pinning the new events)	2
existing: admin_config_auth, config_auth, fuzz_invariants, protocol_formal_specs, scenarios, user_journeys	34, unchanged and passing

interest_rate_model checks the model's output against hand-computed values at 0%, below the kink, at the kink, above it and at 100%, under both the default and a custom config. It also checks that the configured rate actually drives accrual over a year.

As a check that the tests catch real regressions, I temporarily broke each feature and confirmed the matching tests fail:

• health factor counting only one asset;
• global incentive in place of the per-asset one;
• bounds removed;
• a missing price counted as zero.

Not verified locally: the wasm32v1-none release build. A soroban-sdk 28 build script in the dependency graph requires stellar-cli ≥ 25.2, and the local install is 25.1.

Docs

• New liquidation.md.
• interest_rate_models.md rewritten. It described a model-switching API (update_interest_rate_model) that was never merged.
• views.md, borrow.md and README.md updated.

🤖 Generated with Claude Code

[vercel]

@Abidoyesimze is attempting to deploy a commit to the smartdevs17's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Abidoyesimze Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits