core: socialize default losses to pool share price on liquidation

[EmeditWeb]

Problem

When a loan defaults, mark_defaulted() (lib.rs:486-558) forwards only the
forfeited guarantee_amount to the pool via receive_guarantee(). The
unrecovered shortfall (remaining_balance - guarantee_amount) is never
written down from the pool. locked_liquidity and total_liquidity still
reflect the full outstanding principal, so get_share_price() reports a
value the pool cannot actually pay out. LPs who withdraw first are made
whole at the expense of those who withdraw last — the loss is not socialized.

Before Starting

Read ALL of these before writing any code:

• context/architecture-context.md
• context/code-standards.md
• context/progress-tracker.md

What To Build

Loss socialization on default so share price honestly reflects realized losses:

1. Add a pool entrypoint (e.g. absorb_loss(creditline, principal_shortfall))
   callable only by the registered CreditLine, that reduces both
   locked_liquidity and total_liquidity by the unrecovered principal.
2. In mark_defaulted(), after applying the guarantee, compute the shortfall
   and call the new entrypoint so the write-down hits share price immediately.
3. Guard against negative liquidity and double-application; keep CEI ordering
   and the non-reentrant guard.

Files To Touch

• contracts/liquidity-pool-contract/src/lib.rs (new loss-absorption fn)
• contracts/liquidity-pool-contract/src/events.rs
• contracts/creditline-contract/src/lib.rs (mark_defaulted)
• both contracts' tests.rs

Acceptance Criteria

• Default reduces pool total_liquidity by the unrecovered principal
• get_share_price() drops to a value the pool can actually pay
• Guarantee recovery still applied and nets against the shortfall
• New entrypoint restricted to the registered CreditLine contract
• Loss-socialization event emitted; tests assert share price before/after

Mandatory Checks Before Opening PR

• All context/ files read and understood
• context/progress-tracker.md updated
• cargo build passes with zero errors
• cargo test passes — test count not decreased
• require_auth() first in every mutating function
• extend_ttl() after every persistent storage write
• No .unwrap()/.expect() in user-facing paths
• PR references this issue number

[Lanhubs]

I can take ownership of this issue. Socializing unrecovered default shortfalls across liquidity pools to preserve accurate share-token pricing and prevent late-withdrawal liquidity runs is a vital update for maintaining protocol integrity.

Proposed Implementation Strategy
Loss Absorption Entrypoint (Soroban/Rust): I will add an absorb_loss(creditline: Address, principal_shortfall: i128) function to contracts/liquidity-pool-contract/src/lib.rs. This mutating function will call require_auth() immediately to ensure it can only be invoked by the authorized CreditLine contract instance. It will safely deduct the shortfall from both locked_liquidity and total_liquidity storage slots, utilizing rigorous boundary validation to explicitly guard against underflow or negative liquidity values.

CreditLine Shortfall Derivation: Inside contracts/creditline-contract/src/lib.rs (mark_defaulted), I will compute the net principal_shortfall = remaining_balance - guarantee_amount. After processing receive_guarantee(), the function will call the pool's new absorb_loss entrypoint. I will arrange this execution sequence to strictly adhere to the Checks-Effects-Interactions (CEI) design pattern, maintaining the non-reentrant guard topology.

Storage Extensions & Event Emission: Following the state mutation, I will trigger extend_ttl() for the modified persistent storage instances. I will define and emit a novel LossSocialized event layout within events.rs to ensure downstream indexers track the write-down.

Comprehensive Testing: I will craft unit tests within both contract suites to assert that get_share_price() adjusts downward correctly following a default, confirming that early and late Liquidity Providers absorb the loss symmetrically. I'll also ensure cargo build and cargo test complete cleanly with zero compiler warnings or errors.

Estimated Timeline
Estimated Time to Complete: 3–4 hours.

Ready to check out the branch, review the internal architectural context files, update context/progress-tracker.md, and secure this financial settlement layer. Let me know if I am authorized to proceed!