@layerzerolabs/framework-solana-anchor-trait 0.2.61 → 0.2.63

package/examples/shapes/programs/triangle/tests/triangle/helpers.rs

@@ -0,0 +1,123 @@
+//! Shared test helpers: PDA derivation, account builders, fixtures, and instruction builders.
+
+use anchor_lang::{AnchorSerialize, Discriminator};
+use mollusk_svm::{program::keyed_account_for_system_program, Mollusk};
+use shapes_triangle::{instruction as ix, DimensionParams, InitParams, ShapeState};
+use solana_account::Account;
+use solana_instruction::{AccountMeta, Instruction};
+use solana_program_error::ProgramError;
+use solana_pubkey::Pubkey;
+
+// ── Program + PDA derivation ──────────────────────────────────────────────────
+
+/// Bridge anchor-lang Pubkey (solana-program 2.x) → solana-pubkey 4.x via bytes.
+pub fn program_id() -> Pubkey {
+    let mut bytes = [0u8; 32];
+    bytes.copy_from_slice(shapes_triangle::ID.as_ref());
+    Pubkey::new_from_array(bytes)
+}
+
+/// Shape PDA: seeds = [b"shape"]
+pub fn shape_pda() -> (Pubkey, u8) {
+    Pubkey::find_program_address(&[b"shape"], &program_id())
+}
+
+// @todo shankar extract shared mollusk helpers (mollusk(), ix_data(), payer_key/account(),
+//       sys_keyed(), to_program_pubkey(), decode_event()) into a common test-utils crate
+//       at contracts/common/test-utils/solana/ to eliminate duplication across examples.
+pub fn mollusk() -> Mollusk {
+    // `anchor build` outputs .so relative to the Cargo workspace root.
+    // Walk up from the crate to find the nearest Cargo.lock (workspace root)
+    // which is where target/deploy/ lives.
+    let binary = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .ancestors()
+        .find(|p| p.join("Cargo.lock").exists())
+        .expect("Cargo.lock not found — workspace root missing")
+        .join("target/deploy/shapes_triangle");
+    Mollusk::new(&program_id(), binary.to_str().unwrap())
+}
+
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+
+pub fn payer_key() -> Pubkey {
+    Pubkey::new_from_array([0xAA; 32])
+}
+
+pub fn payer_account() -> Account {
+    Account::new(10_000_000, 0, &Pubkey::new_from_array([0u8; 32]))
+}
+
+/// Extra signer injected by `ExtComputeArea` (triangle-specific extension).
+pub fn verifier_key() -> Pubkey {
+    Pubkey::new_from_array([0xBB; 32])
+}
+
+pub fn verifier_account() -> Account {
+    Account::new(1_000_000, 0, &Pubkey::new_from_array([0u8; 32]))
+}
+
+pub fn sys_keyed() -> (Pubkey, Account) {
+    keyed_account_for_system_program()
+}
+
+// ── Serialization helpers ─────────────────────────────────────────────────────
+
+pub fn ix_data<T: AnchorSerialize>(discriminator: &[u8], params: T) -> Vec<u8> {
+    let mut d = discriminator.to_vec();
+    d.extend(params.try_to_vec().unwrap());
+    d
+}
+
+// ── Account data builders ─────────────────────────────────────────────────────
+
+pub fn shape_data(width: u64, height: u64, bump: u8) -> Vec<u8> {
+    let mut d = ShapeState::DISCRIMINATOR.to_vec();
+    d.extend_from_slice(&width.to_le_bytes());
+    d.extend_from_slice(&height.to_le_bytes());
+    d.push(bump);
+    d
+}
+
+pub fn shape_account(width: u64, height: u64, bump: u8) -> Account {
+    Account {
+        lamports: 1_000_000,
+        data: shape_data(width, height, bump),
+        owner: program_id(),
+        executable: false,
+        rent_epoch: u64::MAX,
+    }
+}
+
+// ── Error helpers ─────────────────────────────────────────────────────────────
+
+pub fn program_err(e: impl Into<u32>) -> ProgramError {
+    ProgramError::Custom(e.into())
+}
+
+// ── Instruction builders ──────────────────────────────────────────────────────
+
+/// `initialize` (Anchor `init` on shape PDA):
+///   0: payer, 1: shape, 2: system_program
+pub fn initialize_ix(payer: &Pubkey, shape: &Pubkey, width: u64, height: u64) -> Instruction {
+    let (sys, _) = sys_keyed();
+    Instruction {
+        program_id: program_id(),
+        accounts: vec![
+            AccountMeta::new(*payer, true),
+            AccountMeta::new(*shape, false),
+            AccountMeta::new_readonly(sys, false),
+        ],
+        data: ix_data(ix::Initialize::DISCRIMINATOR, InitParams { width, height }),
+    }
+}
+
+/// `get_dimension` (view):
+///   0: shape
+pub fn get_dimension_ix(shape: &Pubkey, index: u8) -> Instruction {
+    Instruction {
+        program_id: program_id(),
+        accounts: vec![AccountMeta::new_readonly(*shape, false)],
+        data: ix_data(ix::GetDimension::DISCRIMINATOR, DimensionParams { index }),
+    }
+}
+

package/examples/shapes/programs/triangle/tests/triangle/negative.rs

@@ -0,0 +1,49 @@
+use crate::helpers::*;
+use mollusk_svm::result::types::ProgramResult;
+use solana_program_error::ProgramError;
+
+// ── initialize ────────────────────────────────────────────────────────────────
+
+/// double-init: shape account already exists → `init` constraint rejects.
+#[test]
+fn test_initialize_fails_on_double_init() {
+    let mollusk = mollusk();
+    let payer = payer_key();
+    let (shape_key, shape_bump) = shape_pda();
+
+    let result = mollusk.process_instruction(
+        &initialize_ix(&payer, &shape_key, 6, 4),
+        &[
+            (payer, payer_account()),
+            // Supply pre-existing shape account → `init` must fail.
+            (shape_key, shape_account(6, 4, shape_bump)),
+            sys_keyed(),
+        ],
+    );
+
+    assert_eq!(
+        result.program_result,
+        ProgramResult::Failure(ProgramError::Custom(0)),
+        "double-init should fail with system AccountAlreadyInUse"
+    );
+}
+
+// ── get_dimension ─────────────────────────────────────────────────────────────
+
+/// index out of range (index = 2) → `InvalidProgramId`.
+#[test]
+fn test_get_dimension_fails_with_out_of_bounds_index() {
+    let mollusk = mollusk();
+    let (shape_key, shape_bump) = shape_pda();
+
+    let result = mollusk.process_instruction(
+        &get_dimension_ix(&shape_key, 2),
+        &[(shape_key, shape_account(6, 4, shape_bump))],
+    );
+
+    assert_eq!(
+        result.program_result,
+        ProgramResult::Failure(program_err(anchor_lang::error::ErrorCode::InvalidProgramId)),
+        "get_dimension should fail with InvalidProgramId for out-of-bounds index"
+    );
+}

package/examples/shapes/programs/triangle/tests/triangle/positive.rs

@@ -0,0 +1,225 @@
+use crate::helpers::*;
+use anchor_lang::Discriminator;
+use mollusk_svm::result::Check;
+use shapes_triangle::{instruction as ix, ComputeParams, ScaleParams};
+use solana_account::Account;
+use solana_instruction::{AccountMeta, Instruction};
+
+// ── initialize ────────────────────────────────────────────────────────────────
+
+#[test]
+fn test_initialize_creates_shape_with_correct_dimensions() {
+    let mollusk = mollusk();
+    let payer = payer_key();
+    let (shape_key, shape_bump) = shape_pda();
+
+    mollusk.process_and_validate_instruction(
+        &initialize_ix(&payer, &shape_key, 6, 4),
+        &[
+            (payer, payer_account()),
+            (shape_key, Account::default()),
+            sys_keyed(),
+        ],
+        &[
+            Check::success(),
+            Check::account(&shape_key)
+                .data(&shape_data(6, 4, shape_bump))
+                .build(),
+        ],
+    );
+}
+
+// ── get_name ──────────────────────────────────────────────────────────────────
+
+#[test]
+fn test_get_name_returns_triangle() {
+    let mollusk = mollusk();
+    let (shape_key, shape_bump) = shape_pda();
+
+    let result = mollusk.process_and_validate_instruction(
+        &Instruction {
+            program_id: program_id(),
+            accounts: vec![AccountMeta::new_readonly(shape_key, false)],
+            data: ix::GetName::DISCRIMINATOR.to_vec(),
+        },
+        &[(shape_key, shape_account(6, 4, shape_bump))],
+        &[Check::success()],
+    );
+
+    // Borsh String: 4-byte LE length prefix + UTF-8 bytes
+    let ret = &result.return_data;
+    let len = u32::from_le_bytes(ret[..4].try_into().unwrap()) as usize;
+    assert_eq!(std::str::from_utf8(&ret[4..4 + len]).unwrap(), "Triangle");
+}
+
+// ── get_dimension ─────────────────────────────────────────────────────────────
+
+#[test]
+fn test_get_dimension_returns_width_at_index_0() {
+    let mollusk = mollusk();
+    let (shape_key, shape_bump) = shape_pda();
+
+    let result = mollusk.process_and_validate_instruction(
+        &get_dimension_ix(&shape_key, 0),
+        &[(shape_key, shape_account(6, 4, shape_bump))],
+        &[Check::success()],
+    );
+
+    assert_eq!(u64::from_le_bytes(result.return_data[..8].try_into().unwrap()), 6);
+}
+
+#[test]
+fn test_get_dimension_returns_height_at_index_1() {
+    let mollusk = mollusk();
+    let (shape_key, shape_bump) = shape_pda();
+
+    let result = mollusk.process_and_validate_instruction(
+        &get_dimension_ix(&shape_key, 1),
+        &[(shape_key, shape_account(6, 4, shape_bump))],
+        &[Check::success()],
+    );
+
+    assert_eq!(u64::from_le_bytes(result.return_data[..8].try_into().unwrap()), 4);
+}
+
+// ── clear ─────────────────────────────────────────────────────────────────────
+
+#[test]
+fn test_clear_zeros_dimensions() {
+    let mollusk = mollusk();
+    let (shape_key, shape_bump) = shape_pda();
+
+    mollusk.process_and_validate_instruction(
+        &Instruction {
+            program_id: program_id(),
+            accounts: vec![AccountMeta::new(shape_key, false)],
+            data: ix::Clear::DISCRIMINATOR.to_vec(),
+        },
+        &[(shape_key, shape_account(6, 4, shape_bump))],
+        &[
+            Check::success(),
+            Check::account(&shape_key)
+                .data(&shape_data(0, 0, shape_bump))
+                .build(),
+        ],
+    );
+}
+
+// ── compute_area ──────────────────────────────────────────────────────────────
+
+/// Triangle override: w * h / 2; ExtComputeArea injects a verifier signer.
+#[test]
+fn test_compute_area_uses_triangle_formula() {
+    let mollusk = mollusk();
+    let verifier = verifier_key();
+    let (shape_key, shape_bump) = shape_pda();
+
+    let result = mollusk.process_and_validate_instruction(
+        &Instruction {
+            program_id: program_id(),
+            accounts: vec![
+                AccountMeta::new_readonly(shape_key, false),
+                AccountMeta::new(verifier, true),
+            ],
+            data: ix_data(ix::ComputeArea::DISCRIMINATOR, ComputeParams {}),
+        },
+        &[
+            (shape_key, shape_account(6, 4, shape_bump)),
+            (verifier, verifier_account()),
+        ],
+        &[Check::success()],
+    );
+
+    // 6 * 4 / 2 = 12
+    assert_eq!(u64::from_le_bytes(result.return_data[..8].try_into().unwrap()), 12);
+}
+
+// ── compute_perimeter ─────────────────────────────────────────────────────────
+
+/// Isoceles triangle override: w + w + h = 6 + 6 + 4 = 16.
+#[test]
+fn test_compute_perimeter_uses_isoceles_formula() {
+    let mollusk = mollusk();
+    let (shape_key, shape_bump) = shape_pda();
+
+    let result = mollusk.process_and_validate_instruction(
+        &Instruction {
+            program_id: program_id(),
+            accounts: vec![AccountMeta::new_readonly(shape_key, false)],
+            data: ix_data(ix::ComputePerimeter::DISCRIMINATOR, ComputeParams {}),
+        },
+        &[(shape_key, shape_account(6, 4, shape_bump))],
+        &[Check::success()],
+    );
+
+    assert_eq!(u64::from_le_bytes(result.return_data[..8].try_into().unwrap()), 16);
+}
+
+// ── scale ─────────────────────────────────────────────────────────────────────
+
+/// Isoceles override: only height scales, base stays fixed.
+#[test]
+fn test_scale_only_changes_height_for_isoceles_triangle() {
+    let mollusk = mollusk();
+    let (shape_key, shape_bump) = shape_pda();
+
+    mollusk.process_and_validate_instruction(
+        &Instruction {
+            program_id: program_id(),
+            accounts: vec![AccountMeta::new(shape_key, false)],
+            data: ix_data(ix::Scale::DISCRIMINATOR, ScaleParams { factor: 3 }),
+        },
+        &[(shape_key, shape_account(6, 4, shape_bump))],
+        &[
+            Check::success(),
+            Check::account(&shape_key)
+                .data(&shape_data(6, 12, shape_bump))
+                .build(),
+        ],
+    );
+}
+
+// ── reset ─────────────────────────────────────────────────────────────────────
+
+/// Default reset: sets both dimensions to 1.
+#[test]
+fn test_reset_sets_both_dimensions_to_one() {
+    let mollusk = mollusk();
+    let (shape_key, shape_bump) = shape_pda();
+
+    mollusk.process_and_validate_instruction(
+        &Instruction {
+            program_id: program_id(),
+            accounts: vec![AccountMeta::new(shape_key, false)],
+            data: ix::Reset::DISCRIMINATOR.to_vec(),
+        },
+        &[(shape_key, shape_account(6, 4, shape_bump))],
+        &[
+            Check::success(),
+            Check::account(&shape_key)
+                .data(&shape_data(1, 1, shape_bump))
+                .build(),
+        ],
+    );
+}
+
+// ── get_dimension_count ───────────────────────────────────────────────────────
+
+/// Default: always returns 2 for any 2D shape.
+#[test]
+fn test_get_dimension_count_returns_2() {
+    let mollusk = mollusk();
+    let (shape_key, shape_bump) = shape_pda();
+
+    let result = mollusk.process_and_validate_instruction(
+        &Instruction {
+            program_id: program_id(),
+            accounts: vec![AccountMeta::new_readonly(shape_key, false)],
+            data: ix::GetDimensionCount::DISCRIMINATOR.to_vec(),
+        },
+        &[(shape_key, shape_account(6, 4, shape_bump))],
+        &[Check::success()],
+    );
+
+    assert_eq!(result.return_data[0], 2u8);
+}

package/examples/shapes/programs/triangle/tests/triangle.rs

@@ -0,0 +1,23 @@
+//! Mollusk BPF tests for the Triangle shapes program.
+//!
+//! Positive tests (happy-path):
+//!   - `initialize`          — creates ShapeState with correct dimensions
+//!   - `get_name`            — view: returns "Triangle"
+//!   - `get_dimension`       — view: returns width (index 0) and height (index 1)
+//!   - `clear`               — zeros both dimensions
+//!   - `compute_area`        — override: w * h / 2 with verifier signer (ExtComputeArea)
+//!   - `compute_perimeter`   — override: w + w + h (isoceles triangle)
+//!   - `scale`               — override: isoceles — only height scales, base stays fixed
+//!   - `reset`               — default: sets both dimensions to 1
+//!   - `get_dimension_count` — default: always returns 2
+//!
+//! Negative tests (rejection):
+//!   - `initialize`          — double-init rejected
+//!   - `get_dimension`       — out-of-bounds index rejected
+
+#[path = "triangle/helpers.rs"]
+mod helpers;
+#[path = "triangle/negative.rs"]
+mod negative;
+#[path = "triangle/positive.rs"]
+mod positive;

package/examples/shapes/target/deploy/shapes_ellipse-keypair.json

@@ -0,0 +1 @@
+[232,43,121,215,8,177,189,163,23,27,105,187,80,185,26,170,127,141,171,29,218,50,59,155,79,80,166,83,126,227,1,85,153,141,180,16,156,70,10,137,245,226,101,58,98,97,44,114,199,91,200,214,245,85,125,191,104,55,85,74,230,170,42,185]

package/examples/shapes/target/deploy/shapes_triangle-keypair.json

@@ -0,0 +1 @@
+[171,106,218,79,73,64,48,157,88,222,80,186,245,21,186,211,43,43,29,126,64,251,220,188,214,138,238,147,225,6,82,248,161,52,175,31,58,252,235,113,30,132,102,160,165,206,186,218,152,120,184,18,49,232,189,143,242,177,202,110,105,232,255,216]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layerzerolabs/framework-solana-anchor-trait",
-  "version": "0.2.61",
+  "version": "0.2.63",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -15,22 +15,29 @@
     "SPEC.md"
   ],
   "devDependencies": {
-    "@layerzerolabs/tsup-configuration": "0.2.61",
-    "@layerzerolabs/build-utils-solana": "0.2.61",
-    "@layerzerolabs/vm-tooling-solana": "0.2.61",
-    "@layerzerolabs/typescript-configuration": "0.2.61"
+    "@layerzerolabs/build-utils-solana": "0.2.63",
+    "@layerzerolabs/tsup-configuration": "0.2.63",
+    "@layerzerolabs/typescript-configuration": "0.2.63",
+    "@layerzerolabs/vm-tooling-solana": "0.2.63"
   },
   "publishConfig": {
     "access": "restricted",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "pnpm exec lz-tool --script 'cargo build' anchor",
+    "allow-read-write": "[ -z \"$CI\" ] || sudo chmod -R a+rwx ./target ./examples/shapes/target",
+    "build": "pnpm build:lib && pnpm build:example && pnpm allow-read-write",
+    "build:example": "pnpm exec lz-tool --script 'anchor build --no-idl' anchor",
+    "build:lib": "pnpm exec lz-tool --script 'cargo build' anchor",
     "check": "pnpm exec lz-tool --script 'cargo check' anchor",
     "clean": "rm -rf 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 exec lz-tool --script 'cargo +nightly-2025-06-01 fmt -- --check && cargo clippy --all-targets' anchor",
-    "test": "pnpm exec lz-tool --script 'cargo test --lib --tests' anchor"
+    "test": "pnpm test:lib && pnpm test:example",
+    "test:example": "pnpm test:example:ellipse && pnpm test:example:triangle",
+    "test:example:ellipse": "pnpm exec lz-tool --script 'cargo test-ellipse' anchor",
+    "test:example:triangle": "pnpm exec lz-tool --script 'cargo test-triangle' anchor",
+    "test:lib": "pnpm exec lz-tool --script 'cargo test --lib --tests' anchor"
   }
 }

package/src/assembly.rs

@@ -1,6 +1,6 @@
 //! Final assembly of generated code into the macro output.
 
-use proc_macro2::TokenStream;
+use proc_macro2::{Ident, TokenStream};
 use quote::quote;
 use syn::ItemMod;
 
@@ -16,43 +16,78 @@ pub struct Assembly<Ix: InstructionSet> {
     pub overrides: InstructionOverrides<Ix>,
     /// The generated instruction code.
     pub instructions: GeneratedInstructions,
-    /// Extra attributes placed on the module (e.g. `#[program]`, `#[rbac(...)]`).
+    /// Extra attributes placed on the module (e.g. `#[rbac(...)]`).
     pub extra_mod_attrs: TokenStream,
     /// The original module being transformed.
     pub source_mod: ItemMod,
+    /// Name of the `macro_rules!` for extending default accounts structs.
+    /// `None` if the domain has no provided instructions.
+    pub extend_macro_name: Option<Ident>,
 }
 
 impl<Ix: InstructionSet> Assembly<Ix> {
     /// Assembles the final macro output from all generated parts.
     ///
+    /// `#[program]` is always emitted as the innermost attribute on the module so
+    /// that Anchor expands last — after all instruction macros have injected their
+    /// code.  If `#[program]` already appears on `source_mod` (placed by a
+    /// previously-expanded macro), it is filtered out and re-emitted at the correct
+    /// position.  This makes stacking order irrelevant for any combination of
+    /// domain macros (e.g. `#[oapp]` + `#[composer]`).
+    ///
     /// ```text
     /// prelude              // domain-specific definitions (state types, events, etc.)
     /// wrapper_defs         // relocated override handler modules
     /// default_impls        // generated default accounts structs + handler impls
-    /// #[extra_mod_attrs]   // e.g. #[program]
+    /// extend_macro         // macro_rules! for extending default accounts (if configured)
     /// #[original_mod_attrs]
+    /// #[extra_mod_attrs]   // e.g. #[rbac(...)]
+    /// #[program]           // always innermost — auto-managed by Assembly
     /// mod name {
     ///     filtered_items   // original items minus relocated handlers
     ///     entrypoints      // generated instruction entrypoints
     /// }
     /// ```
     pub fn assemble(self) -> TokenStream {
-        let Self { prelude, overrides, instructions, extra_mod_attrs, source_mod } = self;
+        let Self {
+            prelude,
+            overrides,
+            instructions,
+            extra_mod_attrs,
+            source_mod,
+            extend_macro_name,
+        } = self;
 
         let wrapper_defs = &overrides.wrapper_defs;
         let filtered_items = overrides.filtered_items(&source_mod);
-        let GeneratedInstructions { default_impls, entrypoints } = &instructions;
+        let GeneratedInstructions { default_impls, entrypoints, extend_rules } = &instructions;
+
+        // If there are extend rules, emit a macro_rules! with the given name.
+        let extend_macro = match extend_macro_name {
+            Some(name) if !extend_rules.is_empty() => quote! {
+                #[allow(unused_macros)]
+                macro_rules! #name {
+                    #extend_rules
+                }
+            },
+            _ => TokenStream::new(),
+        };
 
         let ItemMod { attrs: mod_attrs, vis: mod_vis, ident: mod_ident, .. } = &source_mod;
 
+        // Filter out #[program] attribute if it is already present.
+        let mod_attrs: Vec<_> =
+            mod_attrs.iter().filter(|a| !a.path().is_ident("program")).collect();
+
         quote! {
             #prelude
-
             #wrapper_defs
             #default_impls
+            #extend_macro
 
             #(#mod_attrs)*
             #extra_mod_attrs
+            #[program]
             #mod_vis mod #mod_ident {
                 use super::*;
                 #filtered_items