@layerzerolabs/oapp-solana-contracts 1.2.63 → 1.2.65

package/src/{lz_receive_types_v2.rs → lz_receive_types_v3.rs}

@@ -1,74 +1,46 @@
+//! Receive plan format (planner version 3) and Endpoint account helpers for building plans.
+//!
+//! See `docs/lz-receive-types.md` for the planning protocol.
 use crate::{
-    common::{AccountMetaRef, AddressLocator},
-    COMPOSED_MESSAGE_HASH_SEED, ENDPOINT_SEED, EVENT_SEED, NONCE_SEED, OAPP_SEED,
-    PAYLOAD_HASH_SEED,
+    COMPOSED_MESSAGE_HASH_SEED, ENDPOINT_SEED, EVENT_SEED, NONCE_SEED, OAPP_SEED, PAYLOAD_HASH_SEED,
 };
 use anchor_lang::{prelude::*, solana_program::system_program::ID as SYSTEM_ID};
 use solana_keccak_hasher::hash;
 
-/// Version identifier returned by `lz_receive_types_info` for the V2 flow.
-pub const LZ_RECEIVE_TYPES_VERSION: u8 = 2;
+/// Planner version returned by `lz_receive_types_info`.
+pub const LZ_RECEIVE_TYPES_VERSION: u8 = 3;
 
-/// Payload returned from `lz_receive_types_info` when the version is V2.
+/// Returned by `lz_receive_types_info`: the planner's read-only, app-specific inputs.
 ///
-/// The executor uses these accounts to construct the follow-up
-/// `lz_receive_types_v2` call.
+/// The client prepends the payer and the plan scratch account. Account order is part of the
+/// planner ABI, including Anchor's optional-account sentinels.
 #[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug)]
-pub struct LzReceiveTypesV2Accounts {
+pub struct LzReceiveTypesV3Accounts {
     pub accounts: Vec<Pubkey>,
 }
 
-/// Output of the lz_receive_types_v2 instruction.
-///
-/// This structure enables the multi-instruction execution model where OApps can
-/// define multiple instructions to be executed atomically by the Executor.
-/// The Executor constructs a single transaction containing all returned instructions.
-#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
-pub struct LzReceiveTypesV2Result {
-    /// The version of context account
+use crate::common::{AccountMetaRef, AddressLocator};
+
+/// Receive plan written by `lz_receive_types_v3`.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug, PartialEq, Eq)]
+pub struct LzReceiveTypesV3Result {
+    /// Execution-context version; selects the account [`AddressLocator::Context`] resolves to.
     pub context_version: u8,
-    /// ALTs required for this execution context
-    /// Used by the Executor to resolve AltIndex references in AccountMetaRef
-    /// Enables efficient account list compression for complex transactions
-    pub alts: Vec<Pubkey>,
-    /// The complete list of instructions required for LzReceive execution
-    /// MUST include exactly one LzReceive instruction
-    /// MAY include additional Standard instructions for preprocessing/postprocessing
-    /// Instructions are executed in the order returned
+    /// Executed in order in one transaction. Must contain exactly one `LzReceive`; `Standard`
+    /// instructions may precede or follow it.
     pub instructions: Vec<Instruction>,
 }
 
-/// The list of instructions that can be executed in the LzReceive transaction.
-///
-/// V2's multi-instruction model enables complex patterns such as:
-/// - Preprocessing steps before lz_receive (e.g., account initialization)
-/// - Postprocessing steps after lz_receive (e.g., verification, cleanup)
-/// - ABA messaging patterns with additional LayerZero sends
-/// - Conditional execution flows based on message content
-#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
+/// One instruction of a receive plan.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug, PartialEq, Eq)]
 pub enum Instruction {
-    /// The main LzReceive instruction (exactly one required per transaction)
-    /// This instruction processes the incoming cross-chain message
-    LzReceive {
-        /// Account list for the lz_receive instruction
-        /// Uses AddressLocator for flexible address resolution
-        accounts: Vec<AccountMetaRef>,
-    },
-    /// Arbitrary custom instruction for preprocessing/postprocessing
-    /// Enables OApps to implement complex execution flows
-    Standard {
-        /// Target program ID for the custom instruction        
-        program_id: Pubkey,
-        /// Account list for the custom instruction
-        /// Uses same AddressLocator system as LzReceive
-        accounts: Vec<AccountMetaRef>,
-        /// Instruction data payload
-        /// Raw bytes containing the instruction's parameters
-        data: Vec<u8>,
-    },
+    /// The delivery: this program's `lz_receive`, called with the original params.
+    LzReceive { accounts: Vec<AccountMetaRef> },
+    /// Any other instruction, submitted as given.
+    Standard { program_id: Pubkey, accounts: Vec<AccountMetaRef>, data: Vec<u8> },
 }
 
-/// V2 version of get_accounts_for_clear that returns AccountMetaRef
+/// Accounts for the Endpoint `clear` CPI, in the order [`crate::endpoint_cpi::clear`] expects.
 pub fn get_accounts_for_clear(
     endpoint_program: Pubkey,
     receiver: &Pubkey,
@@ -111,7 +83,8 @@ pub fn get_accounts_for_clear(
     ]
 }
 
-/// V2 version of get_accounts_for_send_compose that returns AccountMetaRef
+/// Accounts for the Endpoint `send_compose` CPI, in the order [`crate::endpoint_cpi::send_compose`]
+/// expects. The Executor's payer funds the composed-message account.
 pub fn get_accounts_for_send_compose(
     endpoint_program: Pubkey,
     from: &Pubkey,

package/src/oapp_info.rs

@@ -32,7 +32,7 @@ pub const OAPP_BASE_SCHEMA_VERSION: u8 = 1;
 
 /// IDL version (instructions + events) for this build. See `docs/oapp-info.md` § `idl_version`
 /// Bump Rules.
-pub const OAPP_BASE_IDL_VERSION: IdlVersion = IdlVersion { major: 1, minor: 0 };
+pub const OAPP_BASE_IDL_VERSION: IdlVersion = IdlVersion { major: 2, minor: 0 };
 
 /// Sentinel: no app-layer TLV entry follows `OAppBase`.
 pub const NO_APP_DISCRIMINATOR: [u8; 8] = [0u8; 8];

package/src/options.rs

@@ -55,15 +55,11 @@ mod tests {
     }
 
     #[test]
-    fn assert_type_3_empty_returns_invalid_length() {
-        let err = assert_type_3(&[]).unwrap_err();
-        assert_eq!(err, OAppError::InvalidOptionsLength.into());
-    }
-
-    #[test]
-    fn assert_type_3_one_byte_returns_invalid_length() {
-        let err = assert_type_3(&[0x00]).unwrap_err();
-        assert_eq!(err, OAppError::InvalidOptionsLength.into());
+    fn assert_type_3_rejects_options_shorter_than_the_type_header() {
+        for options in [&[][..], &[0x00][..]] {
+            let err = assert_type_3(options).unwrap_err();
+            assert_eq!(err, OAppError::InvalidOptionsLength.into());
+        }
     }
 
     #[test]
@@ -82,12 +78,6 @@ mod tests {
         assert_eq!(result, vec![0x01, 0x02, 0x03]);
     }
 
-    #[test]
-    fn combine_no_enforced_extra_also_empty_returns_empty() {
-        let result = combine_options(vec![], &[]).unwrap();
-        assert_eq!(result, Vec::<u8>::new());
-    }
-
     // -----------------------------------------------------------------------
     // combine_options — extra empty
     // -----------------------------------------------------------------------

package/src/types.rs

@@ -112,3 +112,47 @@ pub struct IsComposeMsgSenderParams {
     /// The account claiming authorization to send the compose message.
     pub compose_sender: Pubkey,
 }
+
+/// Params for the OApp `clear` instruction (messaging-channel manager).
+///
+/// `receiver` is intentionally omitted — the handler injects the OApp PDA.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
+pub struct ClearParams {
+    pub src_eid: u32,
+    pub sender: [u8; 32],
+    pub nonce: u64,
+    pub guid: [u8; 32],
+    pub message: Vec<u8>,
+}
+
+/// Params for the OApp `skip` instruction (messaging-channel manager).
+///
+/// `receiver` is intentionally omitted — the handler injects the OApp PDA.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
+pub struct SkipParams {
+    pub src_eid: u32,
+    pub sender: [u8; 32],
+    pub nonce: u64,
+}
+
+/// Params for the OApp `burn` instruction (messaging-channel manager).
+///
+/// `receiver` is intentionally omitted — the handler injects the OApp PDA.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
+pub struct BurnParams {
+    pub src_eid: u32,
+    pub sender: [u8; 32],
+    pub nonce: u64,
+    pub payload_hash: [u8; 32],
+}
+
+/// Params for the OApp `nilify` instruction (message nilifier).
+///
+/// `receiver` is intentionally omitted — the handler injects the OApp PDA.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
+pub struct NilifyParams {
+    pub src_eid: u32,
+    pub sender: [u8; 32],
+    pub nonce: u64,
+    pub payload_hash: [u8; 32],
+}

package/macros/src/instructions/composer/lz_compose_types_v2.rs

@@ -1,17 +0,0 @@
-//! Code generator for the `lz_compose_types_v2` instruction.
-//!
-//! This instruction has no default implementation — users MUST provide
-//! a custom handler named `lz_compose_types_v2` with `#[composer_instruction]`.
-
-use super::ComposerCodegenContext;
-use anchor_trait::InstructionSpec;
-use quote::quote;
-
-pub(super) fn spec() -> InstructionSpec<ComposerCodegenContext> {
-    InstructionSpec {
-        params_type: Some(quote!(::oapp::types::LzComposeParams)),
-        return_type: quote!(::oapp::lz_compose_types_v2::LzComposeTypesV2Result),
-        is_view: true,
-        default_impl: None,
-    }
-}

package/macros/src/instructions/oapp/lz_receive_types_v2.rs

@@ -1,17 +0,0 @@
-//! Code generator for the `lz_receive_types_v2` instruction.
-//!
-//! This instruction has no default implementation — users MUST provide
-//! a custom handler named `lz_receive_types_v2` with `#[oapp_instruction]`.
-
-use super::CodegenContext;
-use anchor_trait::InstructionSpec;
-use quote::quote;
-
-pub(super) fn spec() -> InstructionSpec<CodegenContext> {
-    InstructionSpec {
-        params_type: Some(quote!(::oapp::types::LzReceiveParams)),
-        return_type: quote!(::oapp::lz_receive_types_v2::LzReceiveTypesV2Result),
-        is_view: true,
-        default_impl: None,
-    }
-}

package/src/lz_compose_types_v2.rs

@@ -1,88 +0,0 @@
-use crate::{common::AccountMetaRef, COMPOSED_MESSAGE_HASH_SEED, EVENT_SEED};
-use anchor_lang::prelude::*;
-use solana_keccak_hasher::hash;
-
-/// Version identifier returned by `lz_compose_types_info` for the V2 flow.
-pub const LZ_COMPOSE_TYPES_VERSION: u8 = 2;
-
-/// Payload returned from `lz_compose_types_info` when the version is V2.
-///
-/// The executor uses these accounts to construct the follow-up
-/// `lz_compose_types_v2` call.
-#[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug)]
-pub struct LzComposeTypesV2Accounts {
-    pub accounts: Vec<Pubkey>,
-}
-
-/// Output of the lz_compose_types_v2 instruction.
-///
-/// This structure enables the multi-instruction execution model where composers
-/// can define multiple instructions to be executed atomically by the Executor.
-/// The Executor constructs a single transaction containing all returned instructions.
-#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
-pub struct LzComposeTypesV2Result {
-    /// The version of context account
-    pub context_version: u8,
-    /// ALTs required for this execution context
-    /// Used by the Executor to resolve AltIndex references in AccountMetaRef
-    pub alts: Vec<Pubkey>,
-    /// The complete list of instructions required for LzCompose execution
-    /// MUST include exactly one LzCompose instruction
-    /// MAY include additional Standard instructions for preprocessing/postprocessing
-    /// Instructions are executed in the order returned
-    pub instructions: Vec<ComposeInstruction>,
-}
-
-/// The list of instructions that can be executed in the LzCompose transaction.
-#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
-pub enum ComposeInstruction {
-    /// The main LzCompose instruction (exactly one required per transaction)
-    /// This instruction processes the incoming composed message
-    LzCompose {
-        /// Account list for the lz_compose instruction
-        /// Uses AddressLocator for flexible address resolution
-        accounts: Vec<AccountMetaRef>,
-    },
-    /// Arbitrary custom instruction for preprocessing/postprocessing
-    Standard {
-        /// Target program ID for the custom instruction
-        program_id: Pubkey,
-        /// Account list for the custom instruction
-        accounts: Vec<AccountMetaRef>,
-        /// Instruction data payload
-        data: Vec<u8>,
-    },
-}
-
-/// V2 version of get_accounts_for_clear_compose that returns AccountMetaRef
-pub fn get_accounts_for_clear_compose(
-    endpoint_program: Pubkey,
-    from: &Pubkey,
-    to: &Pubkey,
-    guid: &[u8; 32],
-    index: u16,
-    composed_message: &[u8],
-) -> Vec<AccountMetaRef> {
-    let (composed_message_account, _) = Pubkey::find_program_address(
-        &[
-            COMPOSED_MESSAGE_HASH_SEED,
-            &from.to_bytes(),
-            &to.to_bytes(),
-            &guid[..],
-            &index.to_be_bytes(),
-            &hash(composed_message).to_bytes(),
-        ],
-        &endpoint_program,
-    );
-
-    let (event_authority_account, _) =
-        Pubkey::find_program_address(&[EVENT_SEED], &endpoint_program);
-
-    vec![
-        AccountMetaRef { pubkey: endpoint_program.into(), is_writable: false },
-        AccountMetaRef { pubkey: (*to).into(), is_writable: false },
-        AccountMetaRef { pubkey: composed_message_account.into(), is_writable: true },
-        AccountMetaRef { pubkey: event_authority_account.into(), is_writable: false },
-        AccountMetaRef { pubkey: endpoint_program.into(), is_writable: false },
-    ]
-}