feat(stablecoin): rebuild withdraw_collateral with the collateralization check

[gravityblast]

Rebuilds withdraw_collateral to spec §10.6, replacing the scaffold's
normalized_debt_amount == 0 placeholder with the real §6.2 check.

Accounts go 4 → 8, adding the three read-only globals — each pinned to its
canonical PDA — and clock. The check runs after the decrement against debt and
redemption price projected to now (§5.3). Adds the frozen gate the scaffold
lacked.

Guards the check needs:

• amount == 0 is a no-op (§11) and skips the projections entirely — nothing
  about the position changed, so there is nothing to re-check.
• Zero-debt positions skip them too. There is nothing to collateralize.
• A projected redemption price of zero is rejected. Zero would zero the required
  collateral and let an indebted position be drained completely.

The projections and the check itself run in saturating U512. A rate at the
controller's permitted limit projects past u128 about 45 minutes out, which
panicked before the comparison could run. Saturation is the safe direction: the
check's left-hand side tops out near 10^119, so a saturated requirement always
loses.

32 unit tests.

closes #177

[Copilot]

🟡 Changes recommended

There are still doc/test inconsistencies in the modified areas (outdated panic/docs and a test that claims to assert four echoed globals but only checks one), which should be corrected before approval.

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

Pull request overview

This PR rebuilds the stablecoin program’s withdraw_collateral instruction to follow the spec’s fee-aware, post-decrement collateralization invariant, expanding the ABI to include additional read-only global/state accounts and updating the guest entrypoint, IDL, unit tests, and the zkVM integration test fixtures accordingly.

Changes:

• Replaces the scaffolded “no debt allowed” guard with a spec-aligned collateralization check using projected accumulator/redemption-price values and adds the protocol frozen gate.
• Expands WithdrawCollateral account list from 4 → 8 (adds accumulator, redemption price state, protocol parameters, and clock) and regenerates IDL/guest wiring.
• Updates stablecoin unit tests and the integration test harness to seed/pass the new global accounts.

File summaries

File	Description
programs/stablecoin/src/withdraw_collateral.rs	Implements freeze check + post-decrement collateralization enforcement; adds global PDA validation helper; updates destination naming.
programs/stablecoin/src/tests.rs	Adds new withdraw-collateral tests and updates existing ones for the 8-account ABI.
programs/stablecoin/methods/guest/src/bin/stablecoin.rs	Updates guest instruction signature to accept the four new accounts.
programs/stablecoin/core/src/lib.rs	Updates Instruction::WithdrawCollateral docs to reflect the new account list and semantics.
programs/integration_tests/tests/stablecoin.rs	Seeds and passes the new global accounts in the e2e test state and call site.
artifacts/stablecoin-idl.json	Regenerates IDL to match the new withdraw-collateral ABI (account names/order).

Review details

Suppressed comments (3)

programs/stablecoin/src/withdraw_collateral.rs:37

• The panic list still claims non-zero debt is rejected, but debt is now allowed as long as the post-withdrawal position remains collateralized. Update this bullet to reflect the actual failure mode.

/// - `Position.normalized_debt_amount` is non-zero.

programs/stablecoin/src/tests.rs:1310

• Test name still uses the old destination terminology, but the account is now user_collateral_holding. Renaming the test improves clarity and keeps terminology consistent.

        STABLECOIN_PROGRAM_ID,
        100,
    );
}

programs/stablecoin/src/tests.rs:1333

• Test name still uses the old destination terminology, but the account is now user_collateral_holding. Renaming the test improves clarity and keeps terminology consistent.

        protocol_parameters_account(false),
        clock_account(NOW),
        STABLECOIN_PROGRAM_ID,
        100,
    );
}

• Files reviewed: 6/6 changed files
• Comments generated: 4
• Review effort level: Lite

---

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