feat(fraud-proofs): Implement WriteStateBuffer

dlp-api/src/v2/args/mod.rs

@@ -6,9 +6,11 @@ mod register_operator;
 mod register_verifier;
 mod update_protocol_config;
 mod update_verifier_registry;
+mod write_state_buffer;
 
 pub use init_protocol_config::*;
 pub use register_operator::*;
 pub use register_verifier::*;
 pub use update_protocol_config::*;
 pub use update_verifier_registry::*;
+pub use write_state_buffer::*;

dlp-api/src/v2/args/write_state_buffer.rs

@@ -0,0 +1,15 @@
+use wheels::variable_offset_layout;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+#[variable_offset_layout(buffer_offset = 1)]
+pub struct WriteStateBufferArgs {
+    pub commit_id: u64,
+
+    pub total_len: u32,
+
+    /// Must equal bytes already written, unless retrying an exact old chunk.
+    pub offset: u32,
+
+    #[flexible = 4]
+    pub chunk: Vec<u8>,
+}

dlp-api/src/v2/instruction.rs

@@ -15,6 +15,12 @@ pub enum DlpV2Instruction {
     UpdateVerifierRegistry = 103,
     /// Updates global v2 config for future commitments.
     UpdateProtocolConfig = 104,
+    /// Writes full account-state bytes into a v2 state buffer.
+    ///
+    /// TODO (snawaz/optimization): we can split this into two instructions such that 
+    /// InitStateBuffer takes more arguments and AppendStateBuffer takes as less as
+    /// possible. 
+    WriteStateBuffer = 107,
 }
 
 impl DlpV2Instruction {

dlp-api/src/v2/instruction_builder/mod.rs

@@ -3,9 +3,11 @@ mod register_operator;
 mod register_verifier;
 mod update_protocol_config;
 mod update_verifier_registry;
+mod write_state_buffer;
 
 pub use init_protocol_config::*;
 pub use register_operator::*;
 pub use register_verifier::*;
 pub use update_protocol_config::*;
 pub use update_verifier_registry::*;
+pub use write_state_buffer::*;

dlp-api/src/v2/instruction_builder/write_state_buffer.rs

@@ -0,0 +1,47 @@
+use solana_program::{
+    instruction::{AccountMeta, Instruction},
+    pubkey::Pubkey,
+};
+use solana_sdk_ids::system_program;
+use wheels::layout::Encodable;
+
+use crate::{
+    compat::{Compatize, Modernize},
+    v2::{
+        pda::{protocol_config_pda, state_buffer_pda},
+        DlpV2Instruction, WriteStateBufferArgs,
+    },
+};
+
+/// Builds the instruction that writes full account-state bytes to a v2 buffer.
+pub fn write_state_buffer(
+    payer: Pubkey,
+    authority: Pubkey,
+    account: Pubkey,
+    args: WriteStateBufferArgs,
+) -> Instruction {
+    Instruction {
+        program_id: crate::id().modernize(),
+        accounts: vec![
+            AccountMeta::new(payer, true),
+            AccountMeta::new_readonly(authority, true),
+            AccountMeta::new(
+                state_buffer_pda(
+                    &account.compatize(),
+                    args.commit_id,
+                    &authority.compatize(),
+                )
+                .modernize(),
+                false,
+            ),
+            AccountMeta::new_readonly(account, false),
+            AccountMeta::new_readonly(protocol_config_pda().modernize(), false),
+            AccountMeta::new_readonly(system_program::id(), false),
+        ],
+        data: [
+            DlpV2Instruction::WriteStateBuffer.to_vec(),
+            args.encode().unwrap(),
+        ]
+        .concat(),
+    }
+}

dlp-api/src/v2/pda.rs

@@ -4,6 +4,7 @@ pub const PROTOCOL_CONFIG_SEED: &[u8] = b"protocol-config";
 pub const OPERATOR_BOND_SEED: &[u8] = b"operator-bond";
 pub const VERIFIER_BOND_SEED: &[u8] = b"verifier-bond";
 pub const VERIFIER_REGISTRY_SEED: &[u8] = b"verifier-registry";
+pub const STATE_BUFFER_SEED: &[u8] = b"state-buffer";
 
 // TODO (snawaz): Precompute these addresses if PDA derivation becomes const-safe.
 
@@ -30,3 +31,20 @@ pub fn verifier_bond_pda(verifier: &Pubkey) -> Pubkey {
     )
     .0
 }
+
+pub fn state_buffer_pda(
+    account: &Pubkey,
+    commit_id: u64,
+    authority: &Pubkey,
+) -> Pubkey {
+    Pubkey::find_program_address(
+        &[
+            STATE_BUFFER_SEED,
+            account.as_ref(),
+            &commit_id.to_le_bytes(),
+            authority.as_ref(),
+        ],
+        &crate::id(),
+    )
+    .0
+}

dlp-api/src/v2/state/mod.rs

@@ -1,9 +1,11 @@
 mod operator_bond;
 mod protocol_config;
+mod state_buffer;
 mod verifier_bond;
 mod verifier_registry;
 
 pub use operator_bond::*;
 pub use protocol_config::*;
+pub use state_buffer::*;
 pub use verifier_bond::*;
 pub use verifier_registry::*;

dlp-api/src/v2/state/state_buffer.rs

@@ -0,0 +1,81 @@
+use wheels::fixed_offset_layout;
+
+use crate::{compat::Pubkey, error::DlpError};
+
+/// PDA: `["state-buffer", account, commit_id, authority]`.
+/// Created by `WriteStateBuffer`.
+/// Closed by `CloseTerminalAccounts` after finalize, cancel, or expiry.
+#[derive(Clone, Debug, PartialEq, Eq)]
+#[fixed_offset_layout(buffer_offset = 0)]
+pub struct StateBuffer {
+    /// Account type marker.
+    pub discriminator: [u8; 8],
+
+    /// Writer that owns this opened buffer.
+    ///
+    /// This is the operator identity for an operator commitment buffer, or the
+    /// challenger identity for a challenger dispute buffer.
+    pub authority: Pubkey,
+
+    /// Delegated account whose payload is stored after this header.
+    pub account_pubkey: Pubkey,
+
+    /// Flow-specific nonce that identifies this opened buffer.
+    pub commit_id: u64,
+
+    /// Hash of the finalized payload. Zero until finalized.
+    pub data_hash: [u8; 32],
+
+    /// Expected final byte length of the payload.
+    pub total_len: u32,
+
+    /// Once true, buffer content cannot change except exact duplicate retries.
+    pub finalized: bool,
+
+    /// Active payload bytes for `PostCommitment` or `RaiseChallenge`.
+    ///
+    /// 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
+    /// diff of those bytes. `payload.len()` is the written prefix, while
+    /// `payload.capacity()` is the allocated account-backed span and can be
+    /// shorter than `total_len` until later writes grow the buffer account.
+    #[extendable = 4]
+    pub payload: Vec<u8>,
+}
+
+impl StateBuffer {
+    pub const DISCRIMINATOR: [u8; 8] = *b"v2sbuf00";
+
+    /// Maximum account data bytes a StateBuffer PDA may allocate.
+    pub const MAX_ACCOUNT_DATA_LEN: usize = 10 * 1024 * 1024;
+
+    /// Maximum account data bytes a StateBuffer PDA may grow in one write.
+    pub const MAX_ACCOUNT_DATA_GROWTH_PER_WRITE: usize = 10_240;
+
+    /// Offset of the extendable payload length header.
+    pub const PAYLOAD_LEN_HEADER_OFFSET: usize = Self::MIN_DATA_LEN;
+
+    /// Byte length of the extendable payload length header.
+    pub const PAYLOAD_LEN_HEADER_LEN: usize = 4;
+
+    /// Offset where payload bytes begin in account data.
+    pub const PAYLOAD_BYTES_OFFSET: usize =
+        Self::PAYLOAD_LEN_HEADER_OFFSET + Self::PAYLOAD_LEN_HEADER_LEN;
+
+    /// Maximum payload bytes allocated when a StateBuffer PDA is created.
+    pub const MAX_INITIAL_PAYLOAD_LEN: usize =
+        Self::MAX_ACCOUNT_DATA_GROWTH_PER_WRITE - Self::PAYLOAD_BYTES_OFFSET;
+
+    /// Maximum payload bytes accepted across all writes.
+    pub const MAX_TOTAL_PAYLOAD_LEN: u32 =
+        (Self::MAX_ACCOUNT_DATA_LEN - Self::PAYLOAD_BYTES_OFFSET) as u32;
+
+    /// Returns the serialized data length needed for a payload capacity.
+    pub fn data_len_from_payload_capacity(
+        payload_capacity: usize,
+    ) -> Result<usize, DlpError> {
+        Self::PAYLOAD_BYTES_OFFSET
+            .checked_add(payload_capacity)
+            .ok_or(DlpError::Overflow)
+    }
+}

src/processor/fast/utils/pda.rs

@@ -16,15 +16,33 @@ pub(crate) fn create_pda(
     pda_signers: &[Signer],
     payer: &AccountView,
 ) -> ProgramResult {
-    // Create the account manually or using the create instruction
+    create_pda_with_rent_exempt_lamports(
+        target_account,
+        owner,
+        space,
+        Rent::get()?.try_minimum_balance(space)?,
+        pda_signers,
+        payer,
+    )
+}
 
-    let rent = Rent::get()?;
+/// Creates a new PDA with an explicit rent-exempt lamport target.
+#[inline(always)]
+pub(crate) fn create_pda_with_rent_exempt_lamports(
+    target_account: &AccountView,
+    owner: &Address,
+    space: usize,
+    rent_exempt_lamports: u64,
+    pda_signers: &[Signer],
+    payer: &AccountView,
+) -> ProgramResult {
+    // Create the account manually or using the create instruction
     if target_account.lamports().eq(&0) {
         // If balance is zero, create account
         system::CreateAccount {
             from: payer,
             to: target_account,
-            lamports: rent.try_minimum_balance(space)?,
+            lamports: rent_exempt_lamports,
             space: space as u64,
             owner,
         }
@@ -33,9 +51,8 @@ pub(crate) fn create_pda(
         // Otherwise, if balance is nonzero:
 
         // 1) transfer sufficient lamports for rent exemption
-        let rent_exempt_balance = rent
-            .try_minimum_balance(space)?
-            .saturating_sub(target_account.lamports());
+        let rent_exempt_balance =
+            rent_exempt_lamports.saturating_sub(target_account.lamports());
         if rent_exempt_balance > 0 {
             system::Transfer {
                 from: payer,

src/v2/processor/fraud_proofs/mod.rs

@@ -1 +1,5 @@
 //! Processors for v2 fraud-proof instructions.
+
+mod write_state_buffer;
+
+pub use write_state_buffer::*;