feat(stablecoin): rebuild open_position on the fee-aware layout

[gravityblast]

Replaces the Plan 1 open_position scaffold with the full spec §10.4 version.

The scaffold took the collateral definition as a caller-supplied argument, never
read is_frozen, and wrote opened_at = 0. It now reads ProtocolParameters
for the single global collateral_definition_id and the freeze flag, and stamps
opened_at from the clock.

Breaking ABI change. Instruction::OpenPosition renames collateral_amount
to initial_collateral_amount, and the account list goes from 5 to 7 — adding
protocol_parameters and clock, both read-only. IDL regenerated. Nothing in
modules/stablecoin references this instruction, so the FFI module is unaffected.

Note the issue text specifies opened_at from ctx.now and a 6-post-state
result. ProgramContext exposes no clock — time comes from the system CLOCK_01
account, same as the three pokes — so the host function takes a clock account,
decodes it through the existing read_clock, and echoes it back. That makes 7
post-states, not 6.

5 new unit tests on top of the 9 rebuilt ones: frozen protocol, uninitialized
ProtocolParameters, a collateral definition not bound at init, opened_at
matching the clock, and both new accounts echoed unchanged. The open/withdraw
e2e test seeds ProtocolParameters and the clock directly rather than running
the bootstrap; the real bootstrap path lands with the lifecycle test in #181.

Second of eight issues in Plan 3 (#173). Stacked on #336 — review that first;
this diff assumes checks.rs is already in lib.rs.

closes #175

[Copilot]

Pull request overview

This PR upgrades the Stablecoin program’s open_position instruction from the earlier scaffold to the fee-aware/spec §10.4 behavior: it now reads global ProtocolParameters (for the single collateral definition id + freeze flag) and stamps Position.opened_at from the system CLOCK_01 account. It also introduces a breaking ABI change by renaming the instruction field and expanding the account list (and regenerates the IDL accordingly).

Changes:

• Rebuild open_position host logic to gate on ProtocolParameters.is_frozen, bind the collateral definition via ProtocolParameters.collateral_definition_id, and set opened_at from CLOCK_01.
• Update the instruction ABI: collateral_amount → initial_collateral_amount, and extend the required account list to include protocol_parameters and clock.
• Update unit + integration tests and regenerate artifacts/stablecoin-idl.json to match the new ABI.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
programs/stablecoin/src/open_position.rs	Implements spec §10.4 flow: reads ProtocolParameters, reads CLOCK_01, updates Position.opened_at, and echoes new read-only accounts.
programs/stablecoin/methods/guest/src/bin/stablecoin.rs	Updates guest entrypoint signature/account list to match the new OpenPosition ABI and forward clock + protocol_parameters.
programs/stablecoin/core/src/lib.rs	Updates the Instruction::OpenPosition variant field name and documents the expanded 7-account contract.
programs/stablecoin/src/tests.rs	Extends host-function unit tests/fixtures for frozen/uninitialized params, collateral binding, opened_at, and echoed accounts.
programs/integration_tests/tests/stablecoin.rs	Seeds ProtocolParameters + clock in the fixture state and updates the open/withdraw e2e test to pass the new accounts/field name.
artifacts/stablecoin-idl.json	Regenerates the IDL to reflect renamed params and the 7-account layout for OpenPosition.

Suppressed comments (1)

programs/stablecoin/src/open_position.rs:86

• This panic message refers to a "token definition" but the parameter is collateral_definition. Aligning terminology makes it clearer which account was mismatched.

        "User collateral holding does not match the provided token definition"
    );

---

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

[Copilot]

🟡 Changes recommended

open_position’s rustdoc panic/precondition list is now out of sync with the new ProtocolParameters/clock validation behavior and should be updated to match the actual failure modes.

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

Review details

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