Contracts

Lucent is composed of global contracts and per-collateral branch contracts. The launch branch supports XLM collateral.

Global Contracts

Contract	Responsibility
`CollateralRegistry`	Branch registration, canonical redemption entrypoint, system debt views, redemption fee state, and global admin references.
`StarUsdController`	Protocol-controlled mint and burn authority for starUSD through the starUSD Stellar Asset Contract.
`BranchFactory`	Governed deployment and registration of collateral branches.
`SecurityManager`	Emergency pause controls for minting and high-risk actions.
`InterestRouter`	Routes non-Stability-Pool interest share to treasury and liquidity incentives.

XLM Branch Contracts

Contract	Responsibility
`AddressesRegistry`	Immutable branch references for XLM SAC, starUSD SAC/controller, price feed, pools, Trove modules, helpers, and launch parameters.
`BranchManager`	Risk parameters, controller permissions, timelocks, shutdown, urgent redemption, debt cap, min debt, fee floor, and Stability Pool yield split.
`BorrowerOperations`	User-facing Trove lifecycle and delegated manager flows.
`TroveManager`	Trove accounting, interest application, liquidation, redistribution, batch accounting, zombie handling, and events.
`TrovePosition`	Protocol-controlled transferable ownership registry for Troves. NFT compatibility is optional and not a core dependency.
`SortedTroves`	Interest-rate ordered structure for redemption priority. Final shape depends on Soroban resource profiling.
`StabilityPool`	starUSD deposits, liquidation offset, XLM gains, and starUSD interest yield.
`ActivePool`	Holds active collateral and debt accounting for open Troves.
`DefaultPool`	Holds redistributed collateral and debt accounting.
`CollSurplusPool`	Tracks collateral surplus and reserve flows.
`XlmUsdPriceFeed`	XLM/USD oracle adapter with freshness, sanity, fallback, and shutdown rules.

Trust Boundaries

Users authorize their own operations with Soroban Address::require_auth.
Protocol permissions are explicit and stored in registry/config contracts.
StarUsdController mints only for registered protocol modules.
Emergency controls pause minting and high-risk actions but should not block repayment, close, liquidation, or redemption flows that preserve solvency.

Upgrade Model

Contracts are upgradeable through a proposed-upgrade flow with a 7-day timelock. An authorized admin proposes a new Wasm hash, the proposal is stored with a timestamp, and execution is allowed only after the timelock if the submitted hash matches the pending proposal.

The timelock gives users, integrators, and monitoring systems time to review proposed upgrades before activation.