feat(stablecoin): add deposit_collateral instruction

[gravityblast]

Adds deposit_collateral (spec §10.5) — the inverse of withdraw_collateral,
letting an owner top up an existing position.

Five accounts, one chained Token::Transfer with no PDA seed: the sender is the
user's own holding, authorized by the witness set. (withdraw_collateral needs
a seed because there the vault is the sender.)

Two deliberate omissions, both per spec:

• No is_frozen check. protocol_parameters is read only for
  collateral_definition_id. §7 keeps deleveraging available in emergencies, so
  a deposit works while frozen — the opposite of open_position. Pinned by a test.
• No clock account and no §6.2 collateralization check. Deposits don't
  reference time and can only improve the position.

14 unit tests: happy path, frozen, zero amount, debt left untouched, both
authorization paths, uninitialized/foreign-owned/wrong-address position, wrong
vault, uninitialized ProtocolParameters, wrong Token Program, wrong collateral
definition, and overflow.

The open/withdraw e2e test gains a deposit step between the two, so the new
instruction is exercised through the zkVM; its withdraw assertions are rebased on
the topped-up balance.

Third of eight issues in Plan 3 (#173). Stacked on #341.

closes #176

[Copilot]

🟡 Changes recommended

The new host function should validate the vault account is an initialized TokenHolding before deriving token_program_id and emitting a chained transfer, to avoid relying on downstream failures and reduce misuse surface.

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

Pull request overview

Adds the stablecoin Plan 3 instruction deposit_collateral (spec §10.5), enabling an existing position owner to top up collateral via a single chained Token::Transfer, and wires the instruction through core/guest/IDL plus unit + integration coverage.

Changes:

• Implement deposit_collateral host function with Position/PDA and ProtocolParameters validation, emitting 5 post-states and 1 chained transfer.
• Add the Instruction::DepositCollateral { amount: u128 } variant, guest entrypoint, and regenerate the stablecoin IDL.
• Extend unit tests (host-function) and the existing open→withdraw integration test to exercise deposit through the zkVM path.

File summaries

File	Description
programs/stablecoin/src/tests.rs	Adds unit tests covering happy path + extensive failure cases for deposit_collateral.
programs/stablecoin/src/lib.rs	Exposes the new deposit_collateral module from the stablecoin program crate.
programs/stablecoin/src/deposit_collateral.rs	New host-function implementation: updates Position.collateral_amount and emits a chained Token::Transfer.
programs/stablecoin/methods/guest/src/bin/stablecoin.rs	Adds guest instruction entry for deposit_collateral matching the new core instruction variant.
programs/stablecoin/core/src/lib.rs	Adds Instruction::DepositCollateral { amount } with required account list documentation.
programs/integration_tests/tests/stablecoin.rs	Inserts a deposit step between open and withdraw, rebasing downstream balance assertions.
artifacts/stablecoin-idl.json	Regenerates IDL to include the new deposit_collateral instruction and account list.

Review details

• Files reviewed: 7/7 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.