@layerzerolabs/oapp-solana-contracts 1.2.11

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

@@ -0,0 +1,101 @@
+//! Code generator for the `set_enforced_options` instruction.
+//!
+//! Updates an existing EnforcedOptions PDA, resizing the account if the new
+//! options buffer differs in length. The account must already exist (created
+//! by `init_enforced_options`).
+//!
+//! # Rent refund behaviour
+//!
+//! The generated `StdSetEnforcedOptions` struct exposes a separate `payer` field
+//! (distinct from `authority`). When the options buffer shrinks, Anchor's
+//! `realloc::payer` directive returns the freed lamports to the **current
+//! transaction's `payer`**, not to the account that originally funded the PDA
+//! in `init_enforced_options`.
+//!
+//! This is intentional: the instruction is gated by
+//! `#[only_role(default_admin_role)]`, so an authorised admin always controls
+//! which account is supplied as `payer`. Integrators should be aware that rent
+//! refunds on buffer shrink flow to the call-time `payer`, not the original
+//! funder.
+
+use super::CodegenContext;
+use anchor_trait::{DefaultAccounts, DefaultImpl, InstructionSpec};
+use quote::{format_ident, quote};
+use syn::parse_quote;
+
+pub(super) fn spec() -> InstructionSpec<CodegenContext> {
+    InstructionSpec {
+        params_type: Some(quote!(::oapp::types::SetEnforcedOptionsParams)),
+        return_type: quote!(()),
+        is_view: false,
+        default_impl: Some(DefaultImpl {
+            handler_ident: format_ident!("apply"),
+            generator: generate_default_impl,
+        }),
+    }
+}
+
+fn generate_default_impl(
+    ctx: &CodegenContext,
+    spec: &InstructionSpec<CodegenContext>,
+) -> DefaultAccounts {
+    let handler_ident = &spec.default_impl.as_ref().unwrap().handler_ident;
+    let params_type = spec.params_type.as_ref().unwrap();
+    let return_type = &spec.return_type;
+    let oapp_type = &ctx.oapp_type;
+    let role_type = &ctx.role_type;
+
+    DefaultAccounts {
+        struct_type: parse_quote! {
+            #[::rbac::only_role(role = #role_type::default_admin_role(), state = oapp, authority = authority)]
+            #[event_cpi]
+            #[derive(Accounts)]
+            #[instruction(params: #params_type)]
+            pub struct StdSetEnforcedOptions<'info> {
+                pub authority: Signer<'info>,
+
+                #[account(mut)]
+                pub payer: Signer<'info>,
+
+                pub oapp: Account<'info, #oapp_type>,
+
+                #[account(
+                    mut,
+                    realloc = EnforcedOptions::space(params.options.len()),
+                    realloc::payer = payer,
+                    realloc::zero = true,
+                    seeds = [
+                        ::oapp::ENFORCED_OPTIONS_SEED,
+                        oapp.key().as_ref(),
+                        &params.eid.to_be_bytes(),
+                        &params.msg_type.to_be_bytes(),
+                    ],
+                    bump = enforced_options.bump,
+                )]
+                pub enforced_options: Account<'info, EnforcedOptions>,
+
+                pub system_program: Program<'info, System>,
+            }
+        },
+        impl_block: parse_quote! {
+            impl StdSetEnforcedOptions<'_> {
+                pub fn #handler_ident(ctx: &mut Context<Self>, params: &#params_type) -> Result<#return_type> {
+                    if !params.options.is_empty() {
+                        ::oapp::options::assert_type_3(&params.options)?;
+                    }
+
+                    ctx.accounts.enforced_options.options = params.options.clone();
+
+                    emit_cpi!(::oapp::events::EnforcedOptionsSet {
+                        oapp: ctx.accounts.oapp.key(),
+                        eid: params.eid,
+                        msg_type: params.msg_type,
+                        options: params.options.clone(),
+                    });
+
+                    Ok(())
+                }
+            }
+        },
+    }
+}

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

@@ -0,0 +1,74 @@
+//! Code generator for the `set_peer` instruction.
+
+use super::CodegenContext;
+use anchor_trait::{DefaultAccounts, DefaultImpl, InstructionSpec};
+use quote::{format_ident, quote};
+use syn::parse_quote;
+
+pub(super) fn spec() -> InstructionSpec<CodegenContext> {
+    InstructionSpec {
+        params_type: Some(quote!(::oapp::types::SetPeerParams)),
+        return_type: quote!(()),
+        is_view: false,
+        default_impl: Some(DefaultImpl {
+            handler_ident: format_ident!("apply"),
+            generator: generate_default_impl,
+        }),
+    }
+}
+
+fn generate_default_impl(
+    ctx: &CodegenContext,
+    spec: &InstructionSpec<CodegenContext>,
+) -> DefaultAccounts {
+    let handler_ident = &spec.default_impl.as_ref().unwrap().handler_ident;
+    let params_type = spec.params_type.as_ref().unwrap();
+    let return_type = &spec.return_type;
+    let oapp_type = &ctx.oapp_type;
+    let role_type = &ctx.role_type;
+
+    DefaultAccounts {
+        struct_type: parse_quote! {
+            #[::rbac::only_role(role = #role_type::default_admin_role(), state = oapp, authority = authority)]
+            #[event_cpi]
+            #[derive(Accounts)]
+            #[instruction(params: #params_type)]
+            pub struct StdSetPeer<'info> {
+                pub authority: Signer<'info>,
+
+                #[account(mut)]
+                pub payer: Signer<'info>,
+
+                pub oapp: Account<'info, #oapp_type>,
+
+                #[account(
+                    init_if_needed,
+                    payer = payer,
+                    space = 8 + OAppPeer::INIT_SPACE,
+                    seeds = [::oapp::PEER_SEED, oapp.key().as_ref(), &params.eid.to_be_bytes()],
+                    bump
+                )]
+                pub peer: Account<'info, OAppPeer>,
+
+                pub system_program: Program<'info, System>,
+            }
+        },
+        impl_block: parse_quote! {
+            impl StdSetPeer<'_> {
+                pub fn #handler_ident(ctx: &mut Context<Self>, params: &#params_type) -> Result<#return_type> {
+                    let peer = &mut ctx.accounts.peer;
+                    peer.address = params.peer;
+                    peer.bump = ctx.bumps.peer;
+
+                    emit_cpi!(::oapp::events::PeerSet {
+                        oapp: ctx.accounts.oapp.key(),
+                        eid: params.eid,
+                        peer: params.peer,
+                    });
+
+                    Ok(())
+                }
+            }
+        },
+    }
+}

package/macros/src/lib.rs

@@ -0,0 +1,81 @@
+use proc_macro::TokenStream;
+
+mod composer;
+mod instructions;
+mod oapp;
+mod state_types;
+
+/// Attribute macro for generating OApp program entrypoints.
+///
+/// Uses the `anchor-trait` collect → generate → assemble pipeline to emit all
+/// standard OApp instructions.  Instructions with a framework-provided default
+/// (e.g. `set_peer`, `set_enforced_options`) are generated automatically; instructions
+/// without a default (e.g. `lz_receive`) must be supplied by the implementor
+/// via `#[oapp_instruction]`.  The `#[program]` attribute is always emitted by
+/// the assembly layer — callers never need to add it manually.
+#[proc_macro_attribute]
+pub fn oapp(attr: TokenStream, item: TokenStream) -> TokenStream {
+    oapp::expand(attr.into(), item.into())
+        .unwrap_or_else(|err| err.to_compile_error())
+        .into()
+}
+
+/// Marker attribute for custom OApp instruction handlers.
+///
+/// Place this on a function inside the `#[oapp]` module to supply a custom
+/// handler for the named instruction.  The handler's `ctx` parameter must be
+/// taken **by reference** (`&Context<T>`).
+///
+/// The body of this stub is unreachable: `#[oapp]` consumes the enclosing
+/// module token stream and strips this marker before rustc sees it.
+/// Override logic lives in `oapp::expand`.
+///
+/// # Security: `lz_receive`
+///
+/// When overriding `lz_receive`, the handler MUST verify that
+/// `(params.src_eid, params.sender)` corresponds to a registered peer — the
+/// Endpoint does NOT perform this check. The recommended pattern binds the
+/// `OAppPeer` PDA to `params.src_eid` via `seeds` and enforces
+/// `peer.address == params.sender` declaratively with `constraint`:
+///
+/// ```ignore
+/// #[account(
+///     seeds = [::oapp::PEER_SEED, oapp.key().as_ref(), &params.src_eid.to_be_bytes()],
+///     bump = peer.bump,
+///     constraint = peer.address == params.sender,
+/// )]
+/// pub peer: Account<'info, OAppPeer>,
+/// ```
+#[proc_macro_attribute]
+pub fn oapp_instruction(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    item
+}
+
+/// Attribute macro for generating Composer program entrypoints.
+///
+/// This macro generates `lz_compose`, `lz_compose_types_v2`, and
+/// `lz_compose_types_info` instruction entrypoints for programs that implement
+/// the LayerZero composer interface.  All three instructions are required —
+/// the implementor must provide custom handlers for each via
+/// `#[composer_instruction]`.  The `#[program]` attribute is emitted
+/// automatically by the assembly layer.
+#[proc_macro_attribute]
+pub fn composer(attr: TokenStream, item: TokenStream) -> TokenStream {
+    composer::expand(attr.into(), item.into())
+        .unwrap_or_else(|err| err.to_compile_error())
+        .into()
+}
+
+/// Marker attribute for required Composer instruction handlers.
+///
+/// All three instructions (`lz_compose`, `lz_compose_types_v2`, `lz_compose_types_info`)
+/// must be provided — there are no framework-supplied defaults.  Each handler's
+/// `ctx` parameter must be taken **by reference** (`&Context<T>`).
+///
+/// The body of this stub is unreachable: `#[composer]` consumes the enclosing
+/// module token stream and strips this marker before rustc sees it.
+/// Override logic lives in `composer::expand`.
+#[proc_macro_attribute]
+pub fn composer_instruction(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    item
+}

package/macros/src/oapp.rs

@@ -0,0 +1,86 @@
+//! Top-level `#[oapp]` attribute macro implementation.
+//!
+//! Flow: parse inputs and resolve domain types, then collect → generate → assemble.
+
+use crate::{
+    instructions::oapp::{accept_default_admin_transfer, CodegenContext, OAppInstructionSet},
+    state_types,
+};
+use anchor_trait::{generate_instructions, Assembly, InstructionOverrides, OverrideConfig};
+use darling::{ast::NestedMeta, FromMeta};
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+use syn::ItemMod;
+
+// ---------------------------------------------------------------------------
+// Attribute parsing
+// ---------------------------------------------------------------------------
+
+#[derive(FromMeta)]
+struct OAppAttr {
+    state: syn::Path,
+    role_type: syn::Path,
+}
+
+const OVERRIDE_CONFIG: OverrideConfig = OverrideConfig {
+    attr_name: "oapp_instruction",
+    domain: "OApp",
+};
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+pub fn expand(attr: TokenStream, item: TokenStream) -> syn::Result<TokenStream> {
+    // Parse inputs
+    let attr_args = NestedMeta::parse_meta_list(attr)?;
+    let attrs = OAppAttr::from_list(&attr_args)?;
+    let module = syn::parse2::<ItemMod>(item)?;
+
+    // Resolve domain-specific types and token streams
+    let state = &attrs.state;
+    let role = &attrs.role_type;
+
+    // 1. Collect overrides
+    let overrides = InstructionOverrides::collect(&module, OVERRIDE_CONFIG)?;
+
+    // 2. Generate instructions
+    let codegen_ctx = CodegenContext {
+        oapp_type: quote!(#state),
+        role_type: quote!(#role),
+    };
+    let mut instructions = generate_instructions::<OAppInstructionSet>(&codegen_ctx, &overrides)?;
+
+    // Always inject RBAC accept_default_admin_transfer handler override so the endpoint
+    // delegate is automatically synced with the new admin (EVM parity:
+    // OAppCoreRBACUpgradeable). Reuses RBAC's StdAcceptDefaultAdminTransfer accounts.
+    // This is unconditional — programs cannot override this instruction.
+    instructions
+        .entrypoints
+        .extend(accept_default_admin_transfer::generate());
+
+    // 3. Assemble output
+    let peer_prelude = state_types::generate_peer();
+    let enforced_options_prelude = state_types::generate_enforced_options();
+    let prelude = {
+        quote! {
+            #peer_prelude
+            #enforced_options_prelude
+
+            use ::oapp::OAppState as _;
+        }
+    };
+    let extra_mod_attrs = quote! {
+        #[::rbac::rbac(state = #state, role_type = #role)]
+    };
+
+    Ok(Assembly {
+        prelude,
+        overrides,
+        instructions,
+        extra_mod_attrs,
+        source_mod: module,
+        extend_macro_name: Some(format_ident!("oapp_extend_accounts")),
+    }
+    .assemble())
+}

package/macros/src/state_types.rs

@@ -0,0 +1,79 @@
+//! State struct generators for the `#[oapp]` macro.
+//!
+//! Contains token-stream generators for OApp state account types:
+//! - `OAppPeer` — the peer account definition.
+//! - `EnforcedOptions` — the enforced-options account definition.
+
+use proc_macro2::TokenStream;
+use quote::quote;
+
+/// Generates the `OAppPeer` struct with inherent accessor methods.
+pub fn generate_peer() -> TokenStream {
+    quote! {
+        #[account]
+        #[derive(Default, InitSpace)]
+        pub struct OAppPeer {
+            pub address: [u8; 32],
+            pub bump: u8,
+        }
+
+        impl OAppPeer {
+            /// Returns the configured peer address, or fails if it is the zero address.
+            pub fn get_address(&self) -> ::anchor_lang::prelude::Result<[u8; 32]> {
+                ::anchor_lang::prelude::require!(
+                    self.address != [0u8; 32],
+                    ::oapp::OAppError::NoPeer
+                );
+                Ok(self.address)
+            }
+
+            /// PDA seeds for the per-EID peer.
+            /// Seed shape: [PEER_SEED, oapp_key, eid_be4]
+            pub fn seeds(oapp: &Pubkey, eid: u32) -> &'static [&'static [u8]] {
+                let key_bytes: &'static [u8; 32] = Box::leak(Box::new(oapp.to_bytes()));
+                let eid_bytes: &'static [u8; 4] = Box::leak(Box::new(eid.to_be_bytes()));
+                Box::leak(Box::new([
+                    ::oapp::PEER_SEED,
+                    key_bytes.as_slice(),
+                    eid_bytes.as_slice(),
+                ]))
+            }
+        }
+    }
+}
+
+/// Generates the default `EnforcedOptions` account struct.
+pub fn generate_enforced_options() -> TokenStream {
+    quote! {
+        #[account]
+        pub struct EnforcedOptions {
+            pub options: Vec<u8>,
+            pub bump: u8,
+        }
+
+        impl EnforcedOptions {
+            /// Returns the total account space required for the given options length.
+            ///
+            /// Borsh serializes fields in declaration order, so the on-disk layout is:
+            /// discriminator (8) + vec_len_prefix (4) + options_data + bump (1)
+            pub fn space(options_len: usize) -> usize {
+                8 + 4 + options_len + 1
+            }
+
+            /// PDA seeds for the per-EID, per-msg-type enforced-options account.
+            /// Seed shape: [ENFORCED_OPTIONS_SEED, oapp_key, eid_be4, msg_type_be2]
+            pub fn seeds(oapp: &Pubkey, eid: u32, msg_type: u16) -> &'static [&'static [u8]] {
+                let key_bytes: &'static [u8; 32] = Box::leak(Box::new(oapp.to_bytes()));
+                let eid_bytes: &'static [u8; 4] = Box::leak(Box::new(eid.to_be_bytes()));
+                let msg_type_bytes: &'static [u8; 2] =
+                    Box::leak(Box::new(msg_type.to_be_bytes()));
+                Box::leak(Box::new([
+                    ::oapp::ENFORCED_OPTIONS_SEED,
+                    key_bytes.as_slice(),
+                    eid_bytes.as_slice(),
+                    msg_type_bytes.as_slice(),
+                ]))
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@layerzerolabs/oapp-solana-contracts",
+  "version": "1.2.11",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "src",
+    "idls",
+    "macros/src",
+    "macros/Cargo.toml",
+    "Cargo.toml",
+    "Anchor.toml",
+    "rust-toolchain.toml",
+    "rustfmt.toml"
+  ],
+  "dependencies": {
+    "@layerzerolabs/framework-solana-anchor-trait": "1.2.11",
+    "@layerzerolabs/utils-solana-rbac": "1.2.11"
+  },
+  "devDependencies": {
+    "@layerzerolabs/tsup-configuration": "1.2.11",
+    "@layerzerolabs/vm-tooling-solana": "1.2.11",
+    "@layerzerolabs/typescript-configuration": "1.2.11",
+    "@layerzerolabs/build-utils-rust": "1.2.11"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "externalRepoConfig": {
+    "targets": [
+      "audit-external",
+      "usdai-internal"
+    ]
+  },
+  "implicitDependencies": {
+    "@layerzerolabs/framework-solana-anchor-trait": "workspace:*",
+    "@layerzerolabs/utils-solana-rbac": "workspace:*"
+  },
+  "scripts": {
+    "allow-read-write": "[ -z \"$CI\" ] || sudo chmod -R a+rwx ./target ./macros/examples/counter/target",
+    "build": "pnpm resolve-dependencies && pnpm build:lib && pnpm build:example && pnpm allow-read-write",
+    "build:example": "pnpm exec lz-tool --script 'anchor build --no-idl --ignore-keys' anchor",
+    "build:example:native": "pnpm exec lz-tool --docker-platform native --script 'anchor build --no-idl --ignore-keys' anchor",
+    "build:lib": "pnpm exec lz-tool --script 'cargo build' anchor",
+    "build:lib:native": "pnpm exec lz-tool --docker-platform native --script 'cargo build' anchor",
+    "build:native": "pnpm resolve-dependencies && pnpm build:lib:native && pnpm build:example:native && pnpm allow-read-write",
+    "check": "pnpm exec lz-tool --script 'cargo check' anchor",
+    "clean": "rm -rf dependencies target",
+    "format": "pnpm exec lz-tool --script 'cargo +nightly-2025-06-01 fmt' anchor",
+    "format:check": "pnpm exec lz-tool --script 'cargo +nightly-2025-06-01 fmt -- --check' anchor",
+    "lint": "pnpm resolve-dependencies && pnpm exec lz-tool --script 'cargo +nightly-2025-06-01 fmt -- --check && cargo clippy --all-targets' anchor",
+    "resolve-dependencies": "pnpm exec build-utils-rust resolve",
+    "test": "pnpm test:rust && pnpm test:example",
+    "test:example": "pnpm resolve-dependencies && pnpm exec lz-tool --script 'cargo test --manifest-path macros/examples/counter/Cargo.toml --lib --tests' anchor",
+    "test:rust": "pnpm resolve-dependencies && pnpm exec lz-tool --script 'cargo test -p oapp --lib --tests' anchor",
+    "test:snapshot:check": "pnpm exec turbo-snapshot check",
+    "test:snapshot:update": "pnpm exec turbo-snapshot update"
+  }
+}

package/rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.92.0"
+components = ["rustfmt", "clippy"]

package/rustfmt.toml

@@ -0,0 +1,23 @@
+# Basic
+hard_tabs = false
+max_width = 100
+use_small_heuristics = "Max"
+# Imports
+imports_granularity = "Crate"
+reorder_imports = true
+# Consistency
+newline_style = "Unix"
+# Format comments
+comment_width = 100
+wrap_comments = true
+# Misc
+chain_width = 80
+spaces_around_ranges = false
+binop_separator = "Front"
+reorder_impl_items = false
+match_arm_leading_pipes = "Preserve"
+match_arm_blocks = true
+match_block_trailing_comma = true
+trailing_comma = "Vertical"
+trailing_semicolon = true
+use_field_init_shorthand = true

package/src/common.rs

@@ -0,0 +1,156 @@
+use std::collections::HashMap;
+
+use anchor_lang::{prelude::*, Discriminator};
+use solana_address_lookup_table_interface::state::AddressLookupTable;
+
+use crate::errors::OAppError;
+
+pub const EXECUTION_CONTEXT_SEED: &[u8] = b"ExecutionContext";
+pub const EXECUTION_CONTEXT_VERSION_1: u8 = 1;
+
+/// Execution context data structure that contains metadata for cross-chain execution
+/// This provides execution limits and tracking for LayerZero operations
+#[derive(InitSpace, AnchorSerialize, AnchorDeserialize, Clone)]
+pub struct ExecutionContextV1 {
+    pub initial_payer_balance: u64,
+    /// The maximum total lamports allowed to be used by all instructions in this execution.
+    /// This is a hard cap for the sum of lamports consumed by all instructions in the execution
+    /// batch.
+    pub fee_limit: u64,
+}
+
+impl anchor_lang::Discriminator for ExecutionContextV1 {
+    // let discriminator_preimage = "account:ExecutionContextV1";
+    // let hash = anchor_lang::solana_program::hash::hash(discriminator_preimage.as_bytes());
+    const DISCRIMINATOR: &'static [u8] = &[132, 92, 176, 59, 141, 186, 141, 137];
+}
+
+impl anchor_lang::AccountDeserialize for ExecutionContextV1 {
+    fn try_deserialize(buf: &mut &[u8]) -> anchor_lang::Result<Self> {
+        if buf.len() < Self::DISCRIMINATOR.len() {
+            return Err(anchor_lang::error::ErrorCode::AccountDiscriminatorNotFound.into());
+        }
+        let given_disc = &buf[..8];
+        if Self::DISCRIMINATOR != given_disc {
+            return Err(anchor_lang::error!(
+                anchor_lang::error::ErrorCode::AccountDiscriminatorMismatch
+            )
+            .with_account_name("ExecutionContextV1"));
+        }
+        Self::try_deserialize_unchecked(buf)
+    }
+
+    fn try_deserialize_unchecked(buf: &mut &[u8]) -> anchor_lang::Result<Self> {
+        let mut data: &[u8] = &buf[8..];
+        anchor_lang::AnchorDeserialize::deserialize(&mut data)
+            .map_err(|_| anchor_lang::error::ErrorCode::AccountDidNotDeserialize.into())
+    }
+}
+
+/// A generic account locator used in LZ execution planning for V2.
+/// Can reference the address directly, via ALT, or as a placeholder.
+///
+/// This enum enables the compact account referencing design of V2, supporting:
+/// - OApps to request multiple signer accounts, not just a single Executor EOA
+/// - Dynamic creation of writable EOA-based data accounts
+/// - Efficient encoding of addresses via ALTs, reducing account list size
+///
+/// The legacy is_signer flag is removed. Instead, signer roles are explicitly
+/// declared through Payer and indexed Signer(u8) variants.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
+pub enum AddressLocator {
+    /// Directly supplied public key - standard address reference
+    Address(Pubkey),
+    /// Indexed address from a specific Address Lookup Table (ALT)
+    /// Format: (ALT list index, address index within ALT)
+    /// Enables efficient account list compression via Solana's ALT mechanism
+    AltIndex(u8, u8),
+    /// Executor's fee payer - substituted by the Executor's EOA
+    /// This is the primary signer and fee payer for the transaction
+    Payer,
+    /// Additional signer accounts - substituted by EOAs provided by the Executor
+    /// The u8 index identifies each signer's position in the signer list,
+    /// allowing the OApp to reference multiple distinct signers for dynamic account creation
+    Signer(u8),
+    /// A context account provided by the Executor containing execution
+    /// metadata, such as SOL spend limits.
+    Context,
+    // Append more address placeholders in the future.
+}
+
+impl From<Pubkey> for AddressLocator {
+    fn from(pubkey: Pubkey) -> Self {
+        AddressLocator::Address(pubkey)
+    }
+}
+
+/// Account metadata for V2 execution planning.
+/// Used by the Executor to construct the final transaction.
+///
+/// V2 removes the legacy is_signer flag from V1's AccountMeta.
+/// Instead, signer roles are explicitly declared through AddressLocator variants.
+/// This provides clearer semantics and enables multiple signer support.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
+pub struct AccountMetaRef {
+    /// The account address locator - supports multiple resolution strategies
+    pub pubkey: AddressLocator,
+    /// Whether the account should be writable in the final transaction
+    pub is_writable: bool,
+}
+
+pub fn compact_accounts_with_alts(
+    alt_accounts: &[AccountInfo],
+    instruction_accounts: Vec<AccountMetaRef>,
+) -> Result<Vec<AccountMetaRef>> {
+    // Build address lookup table mapping from remaining_accounts
+    // This enables efficient account referencing via ALT indices
+    let address_to_alt_index_map = build_address_to_alt_index_map(alt_accounts)?;
+
+    // Convert accounts to use ALT indices where possible
+    let compacted_accounts = instruction_accounts
+        .into_iter()
+        .map(|mut account_meta| {
+            if let AddressLocator::Address(pubkey) = account_meta.pubkey {
+                account_meta.pubkey = to_address_locator(&address_to_alt_index_map, pubkey);
+            }
+            account_meta
+        })
+        .collect();
+
+    Ok(compacted_accounts)
+}
+
+pub fn to_address_locator(
+    address_to_alt_index_map: &HashMap<Pubkey, (u8, u8)>,
+    key: Pubkey,
+) -> AddressLocator {
+    address_to_alt_index_map
+        .get(&key)
+        .map(|alt_index| AddressLocator::AltIndex(alt_index.0, alt_index.1))
+        .unwrap_or(AddressLocator::Address(key))
+}
+
+/// Helper function to deserialize AddressLookupTable data
+pub fn deserialize_alt(alt: &AccountInfo) -> Result<Vec<Pubkey>> {
+    let data = alt
+        .try_borrow_data()
+        .map_err(|_| error!(OAppError::InvalidAddressLookupTable))?;
+    AddressLookupTable::deserialize(*data)
+        .map(|alt| alt.addresses.to_vec())
+        .map_err(|_| error!(OAppError::InvalidAddressLookupTable))
+}
+
+/// Helper function to build a map of addresses to their ALT indices
+pub fn build_address_to_alt_index_map(
+    alt_accounts: &[AccountInfo],
+) -> Result<HashMap<Pubkey, (u8, u8)>> {
+    let mut address_to_alt_index_map: HashMap<Pubkey, (u8, u8)> = HashMap::new();
+    for (alt_index, alt) in alt_accounts.iter().enumerate() {
+        let addresses_in_alt = deserialize_alt(alt)?;
+        for (address_index_in_alt, address_in_alt) in addresses_in_alt.iter().enumerate() {
+            address_to_alt_index_map
+                .insert(*address_in_alt, (alt_index as u8, address_index_in_alt as u8));
+        }
+    }
+    Ok(address_to_alt_index_map)
+}