Parse pushes in FinalizeSettle

Author: fedgiac

DESIGN.md

@@ -256,9 +256,8 @@ Differences with Ethereum:
 A settlement transaction is split into multiple instructions. All settlement operations occur between a `BeginSettle` and a `FinalizeSettle` instruction with the exception of arbitrary interactions, which can take place at any point of a transaction. Except for that, the order of instructions in the transaction is arbitrary.
 
 - `BeginSettle`: Snapshots each order's receiver token account, spender token account, and withdrawal balances. Pulls funds from each order’s sell token account to the solver-specified destination accounts, using the settlement state PDA’s token delegation. Carries an explicit `finalize_ix_index` pointing to its paired `FinalizeSettle`.
-- `Push`: It references a unique SPL transfer token instruction between `BeginSettle` and `FinalizeSettle` that sends the proceeds of an order to its buy token account.
 - (arbitrary interactions): Any instruction from the solver. This could be a token transfer, an AMM swap, or anything else.
-- `FinalizeSettle`: Reads balances again, computes deltas against the snapshots, validates clearing/limit prices, updates `amount_received` and order status, revokes solver approvals. Carries an explicit `begin_ix_index` pointing to its paired `BeginSettle`.
+- `FinalizeSettle`: Pushes the proceeds of each order from the settlement’s buffer accounts to the order’s buy token account, using the settlement state PDA’s authority over the buffers. Reads balances again, computes deltas against the snapshots, validates clearing/limit prices, updates `amount_received` and order status, revokes solver approvals. Carries an explicit `begin_ix_index` pointing to its paired `BeginSettle`.
 
 Additionally, a settlement transaction will include the batch number as part of the instruction bytes of `BeginSettle`.
 

client/src/instructions.rs

@@ -11,14 +11,10 @@ use settlement_interface::{
     Instruction, Pubkey,
 };
 
-// Reexport the instruction builders that don't change from the interface.
-// We want the client to provide all instruction builders.
-pub use settlement_interface::instruction::settle::FinalizeSettle;
-
-/// An order to settle together with the funds to pull from it: `intent`
-/// identifies the order and `pulls` lists the `(destination, amount)` transfers
-/// to make from its sell token account.
-pub struct SettledOrder<'a> {
+/// An order ready to be settled, together with the funds to pull from it:
+/// `intent` identifies the order and `pulls` lists the `(destination, amount)`
+/// transfers to make from its sell token account.
+pub struct SettleableOrder<'a> {
     pub intent: &'a OrderIntent,
     pub pulls: &'a [(Pubkey, u64)],
 }
@@ -27,7 +23,7 @@ pub struct SettledOrder<'a> {
 pub struct BeginSettle<'a> {
     pub program_id: Pubkey,
     pub finalize_ix_index: u16,
-    pub orders: &'a [SettledOrder<'a>],
+    pub orders: &'a [SettleableOrder<'a>],
 }
 
 impl BeginSettle<'_> {
@@ -57,6 +53,58 @@ impl BeginSettle<'_> {
     }
 }
 
+/// A settled order whose proceeds are pushed to it: `intent` identifies the
+/// order (its `buy_token_account` is the push destination), `mint` selects the
+/// canonical source buffer, and `amount` is the quantity to push.
+pub struct SettledOrder<'a> {
+    pub intent: &'a OrderIntent,
+    pub mint: Pubkey,
+    pub amount: u64,
+}
+
+/// Builder for a `FinalizeSettle` instruction pushing each order's proceeds to
+/// its buy token account.
+///
+/// The destination is the order intent's `buy_token_account` and the source is
+/// the canonical buffer PDA for `mint` (see [`find_buffer_pda`]). The orders are
+/// sorted by their canonical order PDA (the same key [`BeginSettle`] orders its
+/// settled-order list by) so the two instructions present the orders in the
+/// same order and their lists line up.
+pub struct FinalizeSettle<'a> {
+    pub program_id: Pubkey,
+    pub begin_ix_index: u16,
+    pub orders: &'a [SettledOrder<'a>],
+}
+
+impl FinalizeSettle<'_> {
+    pub fn instruction(self) -> Instruction {
+        // Sort the orders by their canonical order PDA, the key `BeginSettle`
+        // lays its settled orders out by, so the two instructions' lists align.
+        let mut order: Vec<usize> = (0..self.orders.len()).collect();
+        order.sort_by_key(|&i| find_order_pda(&self.program_id, &self.orders[i].intent.uid()).0);
+
+        let mut source_buffers = Vec::with_capacity(self.orders.len());
+        let mut destinations = Vec::with_capacity(self.orders.len());
+        let mut amounts = Vec::with_capacity(self.orders.len());
+        for &i in &order {
+            let (buffer_pda, _bump) = find_buffer_pda(&self.program_id, &self.orders[i].mint);
+            source_buffers.push(buffer_pda);
+            destinations.push(self.orders[i].intent.buy_token_account);
+            amounts.push(self.orders[i].amount);
+        }
+        let (state_pda, _bump) = find_state_pda(&self.program_id);
+        settlement_interface::instruction::settle::FinalizeSettle {
+            program_id: self.program_id,
+            state_pda,
+            begin_ix_index: self.begin_ix_index,
+            source_buffers: &source_buffers,
+            destinations: &destinations,
+            amounts: &amounts,
+        }
+        .instruction()
+    }
+}
+
 pub struct CreateOrder<'a> {
     pub program_id: Pubkey,
     pub owner: Pubkey,
@@ -124,14 +172,16 @@ mod tests {
         data::intent::fixtures::arb_order_intent,
         instruction::{
             fixtures::fake_account_from_array,
-            settle::{BeginSettleInput, INSTRUCTIONS_SYSVAR_ID},
+            settle::{
+                BeginSettleInput, FinalizeSettleInput, INSTRUCTIONS_SYSVAR_ID, SPL_TOKEN_PROGRAM_ID,
+            },
             InstructionInputParsing,
         },
         pda::order::find_order_pda,
     };
 
     proptest! {
-        // `begin_settle` derives each order's PDA from its intent and forwards to
+        // `BeginSettle` derives each order's PDA from its intent and forwards to
         // the interface builder so that the on-chain parser recovers exactly
         // those orders.
         #[test]
@@ -142,9 +192,9 @@ mod tests {
             let program_id = Pubkey::new_unique();
             // No pulls here: this test only checks that orders are derived and
             // laid out correctly.
-            let orders: Vec<SettledOrder> = intents
+            let orders: Vec<SettleableOrder> = intents
                 .iter()
-                .map(|intent| SettledOrder { intent, pulls: &[] })
+                .map(|intent| SettleableOrder { intent, pulls: &[] })
                 .collect();
             let ix = BeginSettle {
                 program_id,
@@ -186,5 +236,76 @@ mod tests {
                 prop_assert_eq!(order.bump, *bump);
             }
         }
+
+        // `FinalizeSettle` derives each order's source buffer from its mint and
+        // destination from the intent, sorting by canonical order PDA like
+        // `BeginSettle` so the on-chain parser recovers exactly those pushes in
+        // that order.
+        #[test]
+        fn finalize_settle_derives_buffers_from_mints(
+            begin_ix_index in any::<u16>(),
+            cases in prop::collection::vec(
+                (arb_order_intent(), any::<[u8; 32]>(), any::<u64>()),
+                1..=5,
+            ),
+        ) {
+            let program_id = Pubkey::new_unique();
+            let orders: Vec<SettledOrder> = cases
+                .iter()
+                .map(|(intent, mint, amount)| SettledOrder {
+                    intent,
+                    mint: Pubkey::new_from_array(*mint),
+                    amount: *amount,
+                })
+                .collect();
+            let ix = FinalizeSettle {
+                program_id,
+                begin_ix_index,
+                orders: &orders,
+            }
+            .instruction();
+
+            // Expected pushes: each order's buffer PDA, buy token account, and
+            // amount, sorted by the order's canonical PDA (the builder's order).
+            let mut expected: Vec<(Pubkey, Pubkey, Pubkey, u64)> = orders
+                .iter()
+                .map(|order| {
+                    let (order_pda, _bump) = find_order_pda(&program_id, &order.intent.uid());
+                    let (buffer_pda, _bump) = find_buffer_pda(&program_id, &order.mint);
+                    (order_pda, buffer_pda, order.intent.buy_token_account, order.amount)
+                })
+                .collect();
+            expected.sort_by_key(|(order_pda, ..)| *order_pda);
+
+            let mut accounts: Vec<_> = ix
+                .accounts
+                .iter()
+                .map(|meta| fake_account_from_array(meta.pubkey.to_bytes()))
+                .collect();
+            let parsed = FinalizeSettleInput::parse(&ix.data, &mut accounts)
+                .map_err(|e| TestCaseError::fail(format!("parse failed: {e:?}")))?;
+
+            prop_assert_eq!(parsed.begin_ix_index, begin_ix_index);
+            prop_assert_eq!(
+                parsed.instructions_sysvar_account.address(),
+                &INSTRUCTIONS_SYSVAR_ID,
+            );
+            let (state_pda, _bump) = find_state_pda(&program_id);
+            prop_assert_eq!(parsed.state_pda_account.address(), &state_pda);
+            prop_assert_eq!(
+                parsed.token_program_account.address(),
+                &SPL_TOKEN_PROGRAM_ID,
+            );
+
+            let parsed_pushes: Vec<_> = parsed.pushes.into_iter().collect();
+            prop_assert_eq!(parsed_pushes.len(), expected.len());
+            for (push, (_order_pda, buffer, destination, amount)) in
+                parsed_pushes.iter().zip(&expected)
+            {
+                prop_assert_eq!(push.source_buffer.address(), buffer);
+                prop_assert_eq!(push.destination.address(), destination);
+                prop_assert_eq!(u64::from_be_bytes(*push.amount), *amount);
+            }
+        }
     }
 }