Skip to content
Logo

Protocol Flows

These diagrams summarize the intended v1 protocol behavior. Exact function names and event names should be finalized with the contract interfaces.

Architecture Reference

Lucent general architecture showing the global registry, starUSD controller, collateral branches, Trove managers, pools, and borrower operations.

Open Trove

Borrower authorizesWallet submits an open Trove operation.
BorrowerOperations validatesCollateral, requested debt, oracle price, branch status, minimum debt, collateral ratio, receiver, and trustline checks pass.
XLM collateral locksXLM moves into ActivePool and the Trove is recorded.
Trove enters redemption queueSortedTroves indexes the Trove by the borrower-selected fixed interest rate.
starUSD mintsStarUsdController mints the exact new debt amount to the borrower or selected receiver.

Repay and Close

Borrower authorizes repaymentThe protocol validates the Trove and the requested repayment or close action.
starUSD is taken from the borrowerAccrued interest is applied before the debt balance is reduced.
Partial repaymentThe Trove remains active and its sorted position is updated if needed.
Full repaymentThe Trove leaves the sorted index and remaining XLM collateral is released.

Liquidation Waterfall

Liquidation triggerA public caller finds a Trove at or below the branch minimum collateral ratio.
1. JIT liquidationA liquidator sources starUSD at liquidation time, cancels Trove debt, receives collateral, and repays the external liquidity source.
2. Stability Pool offsetIf JIT is unavailable or uneconomic, Stability Pool starUSD is burned to cancel debt and XLM gains are distributed to depositors.
3. Redistribution fallbackIf the Stability Pool cannot fully absorb the liquidation, remaining debt and collateral are redistributed across active Troves.
Accounting closesThe liquidated Trove is closed, borrower surplus remains claimable, and protocol state is updated.

Redemption

Lucent redemption routing showing a redeemer sending starUSD to the CollateralRegistry, which routes redemptions through collateral branches and their lowest-rate Troves.
Redeemer sends starUSDThe canonical redemption entrypoint is CollateralRegistry.
Registry routes the redemptionAt launch, redemptions route into the XLM collateral branch.
Lowest-rate Troves are touched firstThe branch traverses SortedTroves with bounded iteration and slippage controls.
Debt falls and collateral exitsTrove debt is reduced, redeemed starUSD is burned, and the redeemer receives XLM minus the redemption fee.