feat(stablecoin): Implement stability fee accrual

[3esmit]

Closes #97 (Replaces #120)

Summary

Implements stability-fee accrual for the stablecoin program, following
docs/stablecoin/README.md.

Positions now store normalized_debt_amount. A global
StabilityFeeAccumulator projects current debt without rewriting each position.

Changes

• Added protocol globals, redemption state, and the README-shaped Position.
• Added fixed-point helpers for compounding, debt projection, rounding, and
  collateralization checks.
• Added initialize_program, accrue_stability_fee,
  set_stability_fee_per_millisecond, and generate_debt.
• Updated repay_debt and withdraw_collateral to use normalized debt and the
  current accumulator.
• Rejected repayments that exceed current debt or are too small to reduce debt.
• Moved position PDAs to (owner_account_id, position_nonce).
• Read time from the canonical one-block LEZ clock account.
• Regenerated artifacts/stablecoin-idl.json.
• Added unit and integration coverage for the new accrual and debt flows.

trusted token program binding:

Scope

This PR implements the stability-fee and debt-accounting slice of
docs/stablecoin/README.md.

The README also defines additional end-state instructions such as
deposit_collateral, close_position, redemption-rate updates, broader admin
setters, and freeze authority operations. Those remain separate follow-up work.

MAXIMUM_COMPOUNDING_WINDOW_MILLISECONDS is set to one day for the first
implementation. This bounds fixed-point compounding if keepers stop calling
accrual for a long period.

Current spec has no token_program_id config or known token ID input: recommend a follow up analysis if this cause any issues.

[Copilot]

Pull request overview

Implements the stability-fee accrual and normalized-debt accounting model for the stablecoin program, adding the required global singleton accounts and new instructions described in docs/stablecoin/README.md.

Changes:

• Introduces protocol globals (ProtocolParameters, StabilityFeeAccumulator, RedemptionPriceState) plus new instructions to initialize the protocol, accrue fees, and update the fee rate.
• Migrates positions to normalized_debt_amount with projected nominal debt via the global accumulator; updates open_position, generate_debt, repay_debt, and withdraw_collateral accordingly.
• Extends unit + integration tests and regenerates the stablecoin IDL to match the new instruction/account surfaces.

Reviewed changes

Copilot reviewed 16 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
programs/stablecoin/src/withdraw_collateral.rs	Adds protocol/global reads + collateralization check using projected debt/redemption price before allowing withdrawal.
programs/stablecoin/src/tests.rs	Updates/extends unit tests for new globals, accrual, debt generation/repayment, and collateralization behavior.
programs/stablecoin/src/shared.rs	Adds shared helpers for reading canonical clock + protocol singleton PDAs and accruing fee state.
programs/stablecoin/src/set_stability_fee_per_millisecond.rs	Adds admin setter that auto-accrues fees before changing the per-ms rate.
programs/stablecoin/src/repay_debt.rs	Converts repayment to normalized-debt decrement using current accumulator and adds repay bounds.
programs/stablecoin/src/open_position.rs	Switches position PDA to (owner, nonce) and records new Position fields including opened_at.
programs/stablecoin/src/lib.rs	Registers new instruction modules and shared helpers.
programs/stablecoin/src/initialize_program.rs	Adds bootstrap instruction to create protocol singletons and stablecoin definition via chained token call.
programs/stablecoin/src/generate_debt.rs	Adds debt minting instruction with oracle staleness gating + collateralization check.
programs/stablecoin/src/accrue_stability_fee.rs	Adds permissionless fee accrual instruction to roll the global accumulator forward.
programs/stablecoin/methods/guest/src/bin/stablecoin.rs	Exposes new instructions through the guest entrypoint interface.
programs/stablecoin/methods/guest/Cargo.lock	Adds/updates deps for new guest-side interfaces.
programs/stablecoin/core/src/lib.rs	Adds new core account types, math helpers (compound/mul-div), PDA helpers, and instruction enum variants.
programs/stablecoin/core/Cargo.toml	Adds alloy-primitives/ruint for U256 math (with MSRV pin rationale).
programs/stablecoin/Cargo.toml	Adds clock_core, borsh, and oracle-core dependency wiring for host program.
programs/integration_tests/tests/stablecoin.rs	Updates integration flows to include initialization, accrual, generate/repay, and collateralization enforcement.
Cargo.lock	Lockfile updates reflecting new dependencies.
artifacts/stablecoin-idl.json	Regenerates IDL for new accounts/types/instructions and updated instruction interfaces.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 18 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 18 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 18 changed files in this pull request and generated 3 comments.