feat(stablecoin): add generate_debt instruction

[gravityblast]

Adds generate_debt (spec §10.7): mints stablecoins against a position and
increases its debt.

Nine accounts. The chained Token::Mint is authorized by the stablecoin
definition's PDA seed — initialize_program made the definition its own mint
authority. The normalized-debt delta is ⌈amount × FIXED_POINT_ONE / current_accumulator⌉, rounded up per §6.3 so nominal debt grows by at least
what the borrower received; the remainder stays with the protocol.

The §6.2 collateralization check runs after the mint, against the accumulator and
redemption price projected to the clock timestamp. The oracle is a liveness gate
only — §10.7 never consumes its price, so there is no zero-price check here
(unlike update_redemption_rate).

Moves the decode_global helper from withdraw_collateral into checks, whose
module doc already describes it as shared validation. All three globals are
validated at their canonical PDAs.

12 tests: mint and debt increase, the round-up at accumulator 3.0 (100 → 34),
globals echoed, undercollateralized mint, the exact ratio boundary, frozen, stale
oracle, unbound oracle, missing authorization, uninitialized position, unbound
stablecoin definition, and a holding for another definition.

Fifth of eight issues in Plan 3 (#173). Stacked on #348.

closes #178

[Copilot]

🟡 Changes recommended

The new oracle staleness gate can be bypassed by future-dated oracle timestamps due to saturating_sub, which should be tightened to match the spec’s now - timestamp freshness check.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds the generate_debt instruction to the stablecoin program (Plan 3 / spec §10.7), enabling users to mint stablecoins against an existing position while updating normalized debt with §6.3 ceiling rounding, gating on oracle freshness, and enforcing the §6.2 collateralization check post-debt-increase.

Changes:

• Introduces programs/stablecoin/src/generate_debt.rs host logic and wires it through the guest entrypoint and stablecoin_core::Instruction.
• Refactors the shared decode_global helper into checks and updates withdraw_collateral to use it.
• Adds/updates unit tests and regenerates artifacts/stablecoin-idl.json to include the new instruction.

File summaries

File	Description
programs/stablecoin/src/withdraw_collateral.rs	Switches global decoding to the shared crate::checks::decode_global.
programs/stablecoin/src/tests.rs	Adds generate_debt tests and aligns protocol parameter oracle ID with test support utilities.
programs/stablecoin/src/lib.rs	Exposes the new generate_debt module.
programs/stablecoin/src/generate_debt.rs	Implements the generate_debt host function, including debt math, oracle gate, collateralization check, and chained mint.
programs/stablecoin/src/checks.rs	Centralizes decode_global as a shared validation helper.
programs/stablecoin/methods/guest/src/bin/stablecoin.rs	Adds the guest entrypoint for the generate_debt instruction.
programs/stablecoin/core/src/lib.rs	Adds the Instruction::GenerateDebt { amount } variant and documents its ABI.
artifacts/stablecoin-idl.json	Updates the IDL to include generate_debt and its 9-account ABI.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.