feat(stablecoin): implement withdraw_collateral (#92)

artifacts/stablecoin-idl.json

@@ -42,6 +42,41 @@
           "type": "u128"
         }
       ]
+    },
+    {
+      "name": "withdraw_collateral",
+      "accounts": [
+        {
+          "name": "owner",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "position",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "vault",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "destination",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "amount",
+          "type": "u128"
+        }
+      ]
     }
   ],
   "accounts": [

stablecoin/Cargo.toml

@@ -7,3 +7,6 @@ edition = "2021"
 nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", tag = "v0.2.0-rc3", features = ["host"] }
 stablecoin_core = { path = "core" }
 token_core = { path = "../token/core" }
+
+[dev-dependencies]
+token_program.workspace = true

stablecoin/core/src/lib.rs

@@ -30,6 +30,26 @@ pub enum Instruction {
         /// Amount of collateral tokens to deposit into the position vault.
         collateral_amount: u128,
     },
+    /// Withdraw `amount` collateral tokens from a position back to a user-controlled holding.
+    ///
+    /// Required accounts (4):
+    /// - Owner account (authorized)
+    /// - Position account (initialized, owned by `self_program_id`)
+    /// - Position vault token holding (address must match
+    ///   `compute_position_vault_pda(self_program_id, position_id)`)
+    /// - Destination user collateral holding (initialized, owned by the vault's Token Program,
+    ///   `TokenHolding.definition_id == Position.collateral_definition_id`)
+    ///
+    /// `token_program_id` is derived from `vault.account.program_owner`;
+    /// `collateral_definition_id` is read from the decoded [`Position`].
+    ///
+    /// **Note:** until issues #97/#96/#95 land, this instruction hard-asserts
+    /// `Position.debt_amount == 0` instead of accruing fees and checking the
+    /// collateralization ratio.
+    WithdrawCollateral {
+        /// Amount of collateral tokens to move from the vault back to `destination`.
+        amount: u128,
+    },
 }
 
 /// Persistent state held by a Stablecoin [`Position`] account.

stablecoin/methods/guest/src/bin/stablecoin.rs

@@ -40,4 +40,36 @@ mod stablecoin {
             chained_calls,
         ))
     }
+
+    /// Withdraw `amount` collateral tokens from an existing position back to a
+    /// user-controlled holding.
+    ///
+    /// # Errors
+    /// Returns the host program's panic-converted error if any precondition
+    /// fails (see
+    /// [`stablecoin_program::withdraw_collateral::withdraw_collateral`] for the
+    /// full list).
+    #[instruction]
+    pub fn withdraw_collateral(
+        ctx: ProgramContext,
+        owner: AccountWithMetadata,
+        position: AccountWithMetadata,
+        vault: AccountWithMetadata,
+        destination: AccountWithMetadata,
+        amount: u128,
+    ) -> SpelResult {
+        let (post_states, chained_calls) =
+            stablecoin_program::withdraw_collateral::withdraw_collateral(
+                owner,
+                position,
+                vault,
+                destination,
+                ctx.self_program_id,
+                amount,
+            );
+        Ok(spel_framework::SpelOutput::execute(
+            post_states,
+            chained_calls,
+        ))
+    }
 }

stablecoin/src/lib.rs

@@ -5,5 +5,8 @@ pub use stablecoin_core as core;
 /// Open a new collateral-only position for a calling owner.
 pub mod open_position;
 
+/// Withdraw collateral from an existing position back to a user-controlled holding.
+pub mod withdraw_collateral;
+
 #[cfg(test)]
 mod tests;