feat(direct): Implement CommitFinalizeFromBuffer

interface/src/args/commit_finalize_from_buffer.rs

@@ -0,0 +1,32 @@
+use wheels::variable_offset_layout;
+
+use crate::compat::Pubkey;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+#[variable_offset_layout(buffer_offset = 1)]
+pub struct CommitFinalizeFromBufferArgs {
+    /// Next commit sequence number for this delegated account and its StateBuffer.
+    pub commit_seq: u64,
+
+    /// Account lamports on the ER after this commit.
+    pub lamports: u64,
+
+    /// Account owner committed by the ER.
+    pub owner: Pubkey,
+
+    /// Whether the validator requests undelegation after this commit.
+    pub allow_undelegation: bool,
+
+    /// Stored as `CommitPayloadKind::value()`.
+    pub payload_kind: u8,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+#[variable_offset_layout(buffer_offset = 1)]
+pub struct PrepareCommitFinalizeArgs {
+    /// Next commit sequence number whose finalization needs this account size.
+    pub commit_seq: u64,
+
+    /// Final delegated-account data length.
+    pub target_data_len: u32,
+}

interface/src/args/mod.rs

@@ -3,6 +3,7 @@
 
 mod challenger_reveal;
 mod commit_finalize;
+mod commit_finalize_from_buffer;
 mod delegate;
 mod init_delegation_cluster;
 mod propose_commitment;
@@ -16,6 +17,7 @@ mod write_state_buffer;
 
 pub use challenger_reveal::*;
 pub use commit_finalize::*;
+pub use commit_finalize_from_buffer::*;
 pub use delegate::*;
 pub use init_delegation_cluster::*;
 pub use propose_commitment::*;

interface/src/instruction.rs

@@ -19,7 +19,7 @@ pub enum DlpV2Instruction {
     ProposeCommitment = 105,
     /// Records approval from the selected verifier for a v2 commitment.
     ApproveCommitment = 106,
-    /// Writes full account-state bytes into a v2 state buffer.
+    /// Writes account-state payload bytes into a state buffer.
     ///
     /// TODO (snawaz/optimization): we can split this into two instructions such that 
     /// InitStateBuffer takes more arguments and AppendStateBuffer takes as less as
@@ -37,6 +37,10 @@ pub enum DlpV2Instruction {
     Delegate = 112,
     /// Commits and immediately applies inline state for a Direct cluster.
     CommitFinalize = 113,
+    /// Commits and applies state from a finalized buffer for a Direct cluster.
+    CommitFinalizeFromBuffer = 114,
+    /// Grows a delegated account by one step before a large direct finalization.
+    PrepareCommitFinalize = 115,
 }
 
 impl DlpV2Instruction {

interface/src/instruction_builder/commit_finalize_from_buffer.rs

@@ -0,0 +1,106 @@
+use solana_program::{
+    instruction::{AccountMeta, Instruction},
+    pubkey::Pubkey,
+};
+use solana_sdk_ids::system_program;
+use wheels::{layout::Encodable, DataLayoutError};
+
+use crate::{
+    compat::{Compatize, Modernize},
+    pda::{delegation_state_pda, state_buffer_pda},
+    CommitFinalizeFromBufferArgs, DlpV2Instruction, PrepareCommitFinalizeArgs,
+};
+
+/// Builds a direct-cluster commit that consumes a finalized StateBuffer.
+pub fn commit_finalize_from_buffer(
+    current_validator: Pubkey,
+    delegation_cluster: Pubkey,
+    delegated_account: Pubkey,
+    args: CommitFinalizeFromBufferArgs,
+) -> Result<Instruction, DataLayoutError> {
+    Ok(Instruction {
+        program_id: crate::id().modernize(),
+        accounts: vec![
+            AccountMeta::new(current_validator, true),
+            AccountMeta::new(delegated_account, false),
+            AccountMeta::new(
+                delegation_state_pda(&delegated_account.compatize())
+                    .modernize(),
+                false,
+            ),
+            AccountMeta::new_readonly(
+                state_buffer_pda(
+                    &delegated_account.compatize(),
+                    args.commit_seq,
+                    &current_validator.compatize(),
+                )
+                .modernize(),
+                false,
+            ),
+            AccountMeta::new_readonly(delegation_cluster, false),
+            AccountMeta::new_readonly(system_program::id(), false),
+        ],
+        data: [
+            DlpV2Instruction::CommitFinalizeFromBuffer.to_vec(),
+            args.encode()?,
+        ]
+        .concat(),
+    })
+}
+
+/// Builds one growth step to run before finalizing a large account update.
+pub fn prepare_commit_finalize(
+    current_validator: Pubkey,
+    delegation_cluster: Pubkey,
+    delegated_account: Pubkey,
+    args: PrepareCommitFinalizeArgs,
+) -> Result<Instruction, DataLayoutError> {
+    Ok(Instruction {
+        program_id: crate::id().modernize(),
+        accounts: vec![
+            AccountMeta::new(current_validator, true),
+            AccountMeta::new(delegated_account, false),
+            AccountMeta::new_readonly(
+                delegation_state_pda(&delegated_account.compatize())
+                    .modernize(),
+                false,
+            ),
+            AccountMeta::new_readonly(delegation_cluster, false),
+            AccountMeta::new_readonly(system_program::id(), false),
+        ],
+        data: [
+            DlpV2Instruction::PrepareCommitFinalize.to_vec(),
+            args.encode()?,
+        ]
+        .concat(),
+    })
+}
+
+/// Builds every growth step needed before finalizing `target_data_len`.
+pub fn prepare_commit_finalize_instructions(
+    current_validator: Pubkey,
+    delegation_cluster: Pubkey,
+    delegated_account: Pubkey,
+    commit_seq: u64,
+    current_data_len: usize,
+    target_data_len: u32,
+) -> Result<Vec<Instruction>, DataLayoutError> {
+    let growth = (target_data_len as usize).saturating_sub(current_data_len);
+    let step_count =
+        growth.div_ceil(crate::StateBuffer::MAX_ACCOUNT_DATA_GROWTH_PER_WRITE);
+    let mut instructions = Vec::with_capacity(step_count);
+
+    for _ in 0..step_count {
+        instructions.push(prepare_commit_finalize(
+            current_validator,
+            delegation_cluster,
+            delegated_account,
+            PrepareCommitFinalizeArgs {
+                commit_seq,
+                target_data_len,
+            },
+        )?);
+    }
+
+    Ok(instructions)
+}

interface/src/instruction_builder/mod.rs

@@ -1,6 +1,7 @@
 mod approve_commitment;
 mod challenger_reveal;
 mod commit_finalize;
+mod commit_finalize_from_buffer;
 mod delegate;
 mod finalize_commitment;
 mod init_delegation_cluster;
@@ -16,6 +17,7 @@ mod write_state_buffer;
 pub use approve_commitment::*;
 pub use challenger_reveal::*;
 pub use commit_finalize::*;
+pub use commit_finalize_from_buffer::*;
 pub use delegate::*;
 pub use finalize_commitment::*;
 pub use init_delegation_cluster::*;

interface/src/instruction_builder/write_state_buffer.rs

@@ -11,7 +11,7 @@ use crate::{
     DlpV2Instruction, WriteStateBufferArgs,
 };
 
-/// Builds the instruction that writes full account-state bytes to a v2 buffer.
+/// Builds the instruction that writes account-state payload bytes to a buffer.
 pub fn write_state_buffer(
     payer: Pubkey,
     authority: Pubkey,

interface/src/state/state_buffer.rs

@@ -11,6 +11,9 @@ pub struct StateBuffer {
     /// Account type marker.
     pub discriminator: [u8; 8],
 
+    /// Canonical PDA bump for this buffer.
+    pub bump: u8,
+
     /// Writer that owns this opened buffer.
     ///
     /// This is the operator identity for an operator commitment buffer, or the
@@ -32,7 +35,10 @@ pub struct StateBuffer {
     /// Once true, buffer content cannot change except exact duplicate retries.
     pub finalized: bool,
 
-    /// Active payload bytes for `ProposeCommitment` or `RaiseChallenge`.
+    /// Keeps `payload` four-byte aligned for zero-copy diff decoding.
+    pub payload_alignment_padding: [u8; 2],
+
+    /// Active payload bytes for commitment, challenge, or direct finalization.
     ///
     /// This is not a serialized Solana account. Depending on the flow, it can
     /// be the delegated account's complete `Account::data` bytes or an encoded

program/src/processor/direct/commit_finalize_from_buffer.rs

@@ -0,0 +1,158 @@
+use delegation_program_interface as dpi;
+use dpi::{
+    error::DlpError, pda::STATE_BUFFER_SEED, CommitFinalizeFromBufferArgs,
+    CommitPayloadKind, StateBuffer,
+};
+use pinocchio::{
+    address::address_eq, error::ProgramError, AccountView, ProgramResult,
+};
+use wheels::{
+    layout::Decodable, require_eq, require_eq_keys, require_n_accounts,
+};
+
+use crate::processor::internal::{
+    apply_commit_finalize, CommitFinalizeInput, CommitStateUpdate,
+};
+
+/// Commit and apply one finalized StateBuffer for a Direct cluster.
+///
+/// Accounts:
+/// 0: `[signer, writable]` current validator and lamport settlement account
+/// 1: `[writable]`         delegated account
+/// 2: `[writable]`         DelegationState PDA
+/// 3: `[]`                 finalized StateBuffer PDA
+/// 4: `[]`                 DelegationCluster PDA
+/// 5: `[]`                 system program, required by system CPI
+#[inline(never)]
+pub fn process_commit_finalize_from_buffer(
+    accounts: &[AccountView],
+    data: &[u8],
+) -> ProgramResult {
+    let [
+        current_validator, // force multi-line
+        delegated_account,
+        delegation_state,
+        state_buffer,
+        delegation_cluster,
+        _system_program,
+    ] = require_n_accounts!(accounts, 6);
+
+    let args = CommitFinalizeFromBufferArgs::decode(data)?;
+    let state_buffer_data = state_buffer.try_borrow()?;
+    let buffer = StateBuffer::decode(state_buffer_data.as_ref())?;
+    validate_state_buffer(
+        current_validator,
+        delegated_account,
+        state_buffer,
+        &buffer,
+        args.commit_seq(),
+    )?;
+
+    let state_update = match args.payload_kind() {
+        value if value == CommitPayloadKind::FullData.value() => {
+            CommitStateUpdate::FullData(buffer.payload().as_slice())
+        }
+        value if value == CommitPayloadKind::Diff.value() => {
+            CommitStateUpdate::Diff(dpi::diff::DiffSet::try_new(
+                buffer.payload().as_slice(),
+            )?)
+        }
+        _ => return Err(ProgramError::InvalidInstructionData),
+    };
+
+    apply_commit_finalize(
+        current_validator,
+        delegated_account,
+        delegation_state,
+        delegation_cluster,
+        CommitFinalizeInput {
+            commit_seq: args.commit_seq(),
+            lamports: args.lamports(),
+            owner: args.owner(),
+            allow_undelegation: args.allow_undelegation(),
+            state_update,
+        },
+    )
+}
+
+fn validate_state_buffer(
+    current_validator: &AccountView,
+    delegated_account: &AccountView,
+    state_buffer: &AccountView,
+    buffer: &dpi::StateBufferView<'_>,
+    commit_seq: u64,
+) -> ProgramResult {
+    let commit_seq_bytes = commit_seq.to_le_bytes();
+    let bump = [buffer.bump()];
+    dpi::require_initialized_pda!(
+        state_buffer,
+        &[
+            STATE_BUFFER_SEED,
+            delegated_account.address().as_ref(),
+            &commit_seq_bytes,
+            current_validator.address().as_ref(),
+            &bump,
+        ],
+        &crate::fast::ID,
+        false
+    );
+    require_eq!(
+        &buffer.discriminator(),
+        &StateBuffer::DISCRIMINATOR,
+        ProgramError::InvalidAccountData
+    );
+    require_eq_keys!(
+        buffer.authority(),
+        current_validator.address(),
+        DlpError::InvalidAuthority
+    );
+    require_eq_keys!(
+        buffer.account_pubkey(),
+        delegated_account.address(),
+        DlpError::InvalidDelegatedAccount
+    );
+    require_eq!(
+        buffer.commit_seq(),
+        commit_seq,
+        ProgramError::InvalidInstructionData
+    );
+    require_eq!(
+        buffer.finalized(),
+        true,
+        ProgramError::InvalidInstructionData
+    );
+    require_eq!(
+        &buffer.payload_alignment_padding(),
+        &[0; 2],
+        ProgramError::InvalidAccountData
+    );
+    require_eq!(
+        buffer.payload().len(),
+        buffer.total_len() as usize,
+        ProgramError::InvalidInstructionData
+    );
+    require_eq!(
+        buffer.payload().capacity(),
+        buffer.total_len() as usize,
+        ProgramError::InvalidInstructionData
+    );
+    require_eq!(
+        state_buffer.data_len(),
+        StateBuffer::data_len_from_payload_capacity(
+            buffer.payload().capacity()
+        )?,
+        ProgramError::InvalidAccountData
+    );
+    require_eq!(
+        buffer.data_hash(),
+        &account_data_hash(buffer.payload().as_slice()),
+        ProgramError::InvalidInstructionData
+    );
+
+    Ok(())
+}
+
+fn account_data_hash(data: &[u8]) -> [u8; 32] {
+    solana_sha256_hasher::hashv(&[b"magicblock.account_data.v1", data])
+        .to_bytes()
+}

program/src/processor/direct/mod.rs

@@ -1,5 +1,9 @@
 //! Processors for clusters that finalize without fraud proofs.
 
 mod commit_finalize;
+mod commit_finalize_from_buffer;
+mod prepare_commit_finalize;
 
 pub use commit_finalize::*;
+pub use commit_finalize_from_buffer::*;
+pub use prepare_commit_finalize::*;