@layerzerolabs/framework-solana-anchor-trait 0.2.60

package/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "anchor-trait"
+version = "0.1.0"
+edition = "2021"
+description = "Trait-like instruction interfaces for Anchor Solana programs with compile-time enforcement and default implementations"
+
+[features]
+idl-build = []
+
+[dependencies]
+itertools = "0.14"
+proc-macro2 = "1.0"
+quote = "1.0"
+syn = { version = "2.0", features = ["full", "parsing"] }
+
+[dev-dependencies]
+insta = "1.41"
+prettyplease = "0.2"

package/examples/shapes/Anchor.toml

@@ -0,0 +1,19 @@
+[toolchain]
+anchor_version = "0.32.1"
+solana_version = "2.3.0"
+
+[features]
+seeds = false
+skip-lint = false
+resolution = false
+
+[programs.localnet]
+shapes_triangle = "Tri1111111111111111111111111111111111111111"
+shapes_ellipse = "ELp1111111111111111111111111111111111111111"
+
+[registry]
+url = "https://api.apr.dev"
+
+[provider]
+cluster = "Localnet"
+wallet = "~/.config/solana/id.json"

package/examples/shapes/macros/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "shapes-macros"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+proc-macro = true
+
+[features]
+idl-build = ["anchor-trait/idl-build"]
+
+[dependencies]
+anchor-trait = { workspace = true }
+syn = { version = "2.0", features = ["full", "parsing"] }
+quote = "1.0"
+proc-macro2 = "1.0"
+darling = "0.20"

package/examples/shapes/macros/src/instructions/compute_area.rs

@@ -0,0 +1,50 @@
+//! Code generator for the `compute_area` instruction.
+//!
+//! Provided instruction with default handler: width * height (rectangle area).
+
+use anchor_trait::{DefaultImpl, InstructionSpec};
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+
+use super::CodegenContext;
+
+pub(super) fn spec(_ctx: &CodegenContext) -> InstructionSpec<CodegenContext> {
+    InstructionSpec {
+        params_type: Some(quote!(ComputeParams)),
+        return_type: quote!(u64),
+        is_view: true,
+        default_impl: Some(DefaultImpl {
+            accounts_ident: format_ident!("StdComputeArea"),
+            handler_ident: format_ident!("apply"),
+            generator: generate_default_context,
+        }),
+    }
+}
+
+fn generate_default_context(
+    ctx: &CodegenContext,
+    spec: &InstructionSpec<CodegenContext>,
+) -> TokenStream {
+    let state_type = &ctx.state_type;
+
+    let params_type = spec.params_type.as_ref().unwrap();
+    let return_type = &spec.return_type;
+    let default_impl = spec.default_impl.as_ref().unwrap();
+
+    let default_accounts_ident = &default_impl.accounts_ident;
+    let handler_ident = &default_impl.handler_ident;
+
+    quote! {
+        #[derive(Accounts)]
+        pub struct #default_accounts_ident<'info> {
+            pub shape: Account<'info, #state_type>,
+        }
+
+        impl #default_accounts_ident<'_> {
+            pub fn #handler_ident(ctx: &Context<Self>, _params: &#params_type) -> Result<#return_type> {
+                let s = &ctx.accounts.shape;
+                Ok(s.width * s.height)
+            }
+        }
+    }
+}

package/examples/shapes/macros/src/instructions/compute_perimeter.rs

@@ -0,0 +1,50 @@
+//! Code generator for the `compute_perimeter` instruction.
+//!
+//! Provided instruction with default handler: 2 * (width + height) (rectangle perimeter).
+
+use anchor_trait::{DefaultImpl, InstructionSpec};
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+
+use super::CodegenContext;
+
+pub(super) fn spec(_ctx: &CodegenContext) -> InstructionSpec<CodegenContext> {
+    InstructionSpec {
+        params_type: Some(quote!(ComputeParams)),
+        return_type: quote!(u64),
+        is_view: true,
+        default_impl: Some(DefaultImpl {
+            accounts_ident: format_ident!("StdComputePerimeter"),
+            handler_ident: format_ident!("apply"),
+            generator: generate_default_context,
+        }),
+    }
+}
+
+fn generate_default_context(
+    ctx: &CodegenContext,
+    spec: &InstructionSpec<CodegenContext>,
+) -> TokenStream {
+    let state_type = &ctx.state_type;
+
+    let params_type = spec.params_type.as_ref().unwrap();
+    let return_type = &spec.return_type;
+    let default_impl = spec.default_impl.as_ref().unwrap();
+
+    let default_accounts_ident = &default_impl.accounts_ident;
+    let handler_ident = &default_impl.handler_ident;
+
+    quote! {
+        #[derive(Accounts)]
+        pub struct #default_accounts_ident<'info> {
+            pub shape: Account<'info, #state_type>,
+        }
+
+        impl #default_accounts_ident<'_> {
+            pub fn #handler_ident(ctx: &Context<Self>, _params: &#params_type) -> Result<#return_type> {
+                let s = &ctx.accounts.shape;
+                Ok(2 * (s.width + s.height))
+            }
+        }
+    }
+}

package/examples/shapes/macros/src/instructions/get_dimension_count.rs

@@ -0,0 +1,44 @@
+//! Code generator for the `get_dimension_count` instruction.
+//!
+//! Provided instruction with no params. Default returns 2 (all shapes are 2D).
+
+use anchor_trait::{DefaultImpl, InstructionSpec};
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+
+use super::CodegenContext;
+
+pub(super) fn spec(_ctx: &CodegenContext) -> InstructionSpec<CodegenContext> {
+    InstructionSpec {
+        params_type: None,
+        return_type: quote!(u8),
+        is_view: true,
+        default_impl: Some(DefaultImpl {
+            accounts_ident: format_ident!("StdGetDimensionCount"),
+            handler_ident: format_ident!("apply"),
+            generator: generate_default_context,
+        }),
+    }
+}
+
+fn generate_default_context(
+    _ctx: &CodegenContext,
+    spec: &InstructionSpec<CodegenContext>,
+) -> TokenStream {
+    let return_type = &spec.return_type;
+    let default_impl = spec.default_impl.as_ref().unwrap();
+
+    let default_accounts_ident = &default_impl.accounts_ident;
+    let handler_ident = &default_impl.handler_ident;
+
+    quote! {
+        #[derive(Accounts)]
+        pub struct #default_accounts_ident {}
+
+        impl #default_accounts_ident {
+            pub fn #handler_ident(_ctx: &Context<Self>) -> Result<#return_type> {
+                Ok(2) // All shapes in this domain are 2D
+            }
+        }
+    }
+}

package/examples/shapes/macros/src/instructions/get_name.rs

@@ -0,0 +1,18 @@
+//! Code generator for the `get_name` instruction.
+//!
+//! This is a **required** instruction — the implementor must return the shape's
+//! name. There is no sensible default, so every consumer must provide a handler.
+
+use anchor_trait::InstructionSpec;
+use quote::quote;
+
+use super::CodegenContext;
+
+pub(super) fn spec() -> InstructionSpec<CodegenContext> {
+    InstructionSpec {
+        params_type: None,
+        return_type: quote!(String),
+        is_view: true,
+        default_impl: None, // Required — implementor MUST provide
+    }
+}

package/examples/shapes/macros/src/instructions/initialize.rs

@@ -0,0 +1,18 @@
+//! Code generator for the `initialize` instruction.
+//!
+//! This is a **required** instruction — the implementor must provide their own
+//! handler and accounts struct. There is no default implementation.
+
+use anchor_trait::InstructionSpec;
+use quote::quote;
+
+use super::CodegenContext;
+
+pub(super) fn spec() -> InstructionSpec<CodegenContext> {
+    InstructionSpec {
+        params_type: Some(quote!(InitParams)),
+        return_type: quote!(()),
+        is_view: false,
+        default_impl: None, // Required — implementor MUST provide
+    }
+}

package/examples/shapes/macros/src/instructions/mod.rs

@@ -0,0 +1,26 @@
+//! Shapes instruction definitions and code generation.
+
+mod compute_area;
+mod compute_perimeter;
+mod get_dimension_count;
+mod get_name;
+mod initialize;
+
+use anchor_trait::declare_instructions;
+use proc_macro2::TokenStream;
+
+/// Domain-specific context carrying the resolved state type for shapes code generation.
+pub(crate) struct CodegenContext {
+    pub state_type: TokenStream,
+}
+
+declare_instructions! {
+    name    = ShapesInstructionSet;
+    context = CodegenContext;
+
+    Initialize       => initialize,
+    GetName          => get_name,
+    ComputeArea      => compute_area(ctx),
+    ComputePerimeter => compute_perimeter(ctx),
+    GetDimensionCount => get_dimension_count(ctx),
+}

package/examples/shapes/macros/src/lib.rs

@@ -0,0 +1,50 @@
+//! Procedural macros for the Shapes example program.
+//!
+//! Provides `#[shapes]` and `#[shapes_instruction]` attribute macros
+//! demonstrating the anchor-trait instruction trait system.
+
+mod instructions;
+mod shapes;
+
+use proc_macro::TokenStream;
+
+/// Program-level macro that auto-generates shape instruction entrypoints.
+///
+/// ## Usage
+///
+/// ```ignore
+/// #[shapes_macros::shapes(state = ShapeState)]
+/// pub mod shapes_program {
+///     use super::*;
+///
+///     // Required: must provide initialize (no default)
+///     pub fn initialize(ctx: Context<Initialize>, params: InitParams) -> Result<()> { ... }
+///
+///     // Optional overrides for compute_area, compute_perimeter, get_dimension_count
+/// }
+/// ```
+///
+/// ## Attributes
+///
+/// - `state = TypeName`: The program state account type (required)
+#[proc_macro_attribute]
+pub fn shapes(attr: TokenStream, item: TokenStream) -> TokenStream {
+    shapes::expand(attr.into(), item.into())
+        .unwrap_or_else(|err| err.to_compile_error())
+        .into()
+}
+
+/// Marks a function as an override for a shapes instruction.
+///
+/// ## Usage
+///
+/// ```ignore
+/// #[shapes_instruction(compute_area)]
+/// pub fn triangle_area(ctx: Context<StdComputeArea>, _params: ComputeParams) -> Result<u64> {
+///     // custom logic
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn shapes_instruction(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    item
+}

package/examples/shapes/macros/src/shapes.rs

@@ -0,0 +1,56 @@
+//! Top-level `#[shapes]` attribute macro implementation.
+//!
+//! Flow: parse inputs and resolve domain types, then collect -> generate -> assemble.
+
+use crate::instructions::{CodegenContext, ShapesInstructionSet};
+use anchor_trait::{generate_instructions, Assembly, InstructionOverrides, OverrideConfig};
+use darling::{ast::NestedMeta, FromMeta};
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{ItemMod, Path};
+
+// ---------------------------------------------------------------------------
+// Attribute parsing
+// ---------------------------------------------------------------------------
+
+#[derive(FromMeta)]
+struct ShapesAttr {
+    state: Path,
+}
+
+const OVERRIDE_CONFIG: OverrideConfig = OverrideConfig {
+    attr_name: "shapes_instruction",
+    domain: "Shapes",
+};
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+pub fn expand(attr: TokenStream, item: TokenStream) -> syn::Result<TokenStream> {
+    // Parse inputs
+    let attr_args = NestedMeta::parse_meta_list(attr)?;
+    let attrs = ShapesAttr::from_list(&attr_args)?;
+    let module = syn::parse2::<ItemMod>(item)?;
+
+    let state = &attrs.state;
+
+    // 1. Collect overrides
+    let overrides = InstructionOverrides::collect(&module, OVERRIDE_CONFIG)?;
+
+    // 2. Generate instructions
+    let codegen_ctx = CodegenContext {
+        state_type: quote!(#state),
+    };
+    let instructions = generate_instructions::<ShapesInstructionSet>(&codegen_ctx, &overrides)?;
+
+    // 3. Assemble output
+    Ok(Assembly {
+        prelude: TokenStream::new(),
+        overrides,
+        instructions,
+        extra_mod_attrs: quote!(#[program]),
+        source_mod: module,
+    }
+    .assemble())
+}

package/examples/shapes/programs/ellipse/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "shapes-ellipse"
+version = "0.0.1"
+description = "Ellipse shapes example implementation for anchor-trait"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib", "lib"]
+name = "shapes_ellipse"
+
+[features]
+no-entrypoint = []
+no-idl = []
+no-log-ix-name = []
+cpi = ["no-entrypoint"]
+default = []
+idl-build = ["anchor-lang/idl-build", "shapes-macros/idl-build"]
+custom-heap = []
+custom-panic = []
+anchor-debug = []
+
+[lints.rust]
+unexpected_cfgs = { level = "allow", check-cfg = [
+    "cfg(feature, values(\"anchor-debug\"))",
+    "cfg(target_os, values(\"solana\"))",
+] }
+
+[dependencies]
+anchor-lang = { workspace = true }
+shapes-macros = { workspace = true }

package/examples/shapes/programs/ellipse/src/lib.rs

@@ -0,0 +1,88 @@
+pub mod state;
+
+use anchor_lang::prelude::*;
+use state::ShapeState;
+
+declare_id!("ELp1111111111111111111111111111111111111111");
+
+// --- Account structs ---
+
+#[derive(Accounts)]
+#[instruction(params: InitParams)]
+pub struct Initialize<'info> {
+    #[account(mut)]
+    pub payer: Signer<'info>,
+    #[account(
+        init,
+        payer = payer,
+        space = 8 + ShapeState::INIT_SPACE,
+        seeds = [b"shape"],
+        bump,
+    )]
+    pub shape: Account<'info, ShapeState>,
+    pub system_program: Program<'info, System>,
+}
+
+#[derive(Accounts)]
+pub struct GetName<'info> {
+    pub shape: Account<'info, ShapeState>,
+}
+
+/// Full Override accounts — ellipse perimeter reads state differently.
+#[derive(Accounts)]
+pub struct EllipseAccounts<'info> {
+    pub shape: Account<'info, ShapeState>,
+}
+
+// --- Param types ---
+
+#[derive(Clone, AnchorSerialize, AnchorDeserialize)]
+pub struct InitParams {
+    pub width: u64,
+    pub height: u64,
+}
+
+#[derive(Clone, AnchorSerialize, AnchorDeserialize)]
+pub struct ComputeParams {}
+
+// --- Program module ---
+// Required:  initialize, get_name
+// Handler Override:  compute_area (π*w*h/4)
+// Full Override:  compute_perimeter (custom EllipseAccounts)
+// Default:   get_dimension_count
+
+#[shapes_macros::shapes(state = ShapeState)]
+pub mod shapes_ellipse {
+
+    #[allow(unused_mut)]
+    #[shapes_instruction]
+    pub fn initialize(mut ctx: Context<Initialize>, params: InitParams) -> Result<()> {
+        ctx.accounts.shape.width = params.width;
+        ctx.accounts.shape.height = params.height;
+        ctx.accounts.shape.bump = ctx.bumps.shape;
+        Ok(())
+    }
+
+    #[shapes_instruction]
+    pub fn get_name(_ctx: Context<GetName>) -> Result<String> {
+        Ok("Ellipse".to_string())
+    }
+
+    // HANDLER OVERRIDE — reuses StdComputeArea accounts, ellipse formula.
+    #[shapes_instruction]
+    pub fn compute_area(ctx: Context<StdComputeArea>, _params: ComputeParams) -> Result<u64> {
+        let s = &ctx.accounts.shape;
+        // Ellipse area = π * a * b where a=w/2, b=h/2 → π * w * h / 4
+        Ok(314_159 * s.width * s.height / 400_000)
+    }
+
+    // FULL OVERRIDE — custom EllipseAccounts, ellipse perimeter approximation.
+    #[shapes_instruction]
+    pub fn compute_perimeter(ctx: Context<EllipseAccounts>, _params: ComputeParams) -> Result<u64> {
+        let s = &ctx.accounts.shape;
+        // Simple approximation: π * (w + h) / 2
+        Ok(314_159 * (s.width + s.height) / 200_000)
+    }
+
+    // DEFAULT — get_dimension_count returns 2, correct for any 2D shape.
+}

package/examples/shapes/programs/ellipse/src/state.rs

@@ -0,0 +1,9 @@
+use anchor_lang::prelude::*;
+
+#[account]
+#[derive(InitSpace)]
+pub struct ShapeState {
+    pub width: u64,
+    pub height: u64,
+    pub bump: u8,
+}

package/examples/shapes/programs/triangle/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "shapes-triangle"
+version = "0.0.1"
+description = "Triangle shapes example implementation for anchor-trait"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib", "lib"]
+name = "shapes_triangle"
+
+[features]
+no-entrypoint = []
+no-idl = []
+no-log-ix-name = []
+cpi = ["no-entrypoint"]
+default = []
+idl-build = ["anchor-lang/idl-build", "shapes-macros/idl-build"]
+custom-heap = []
+custom-panic = []
+anchor-debug = []
+
+[lints.rust]
+unexpected_cfgs = { level = "allow", check-cfg = [
+    "cfg(feature, values(\"anchor-debug\"))",
+    "cfg(target_os, values(\"solana\"))",
+] }
+
+[dependencies]
+anchor-lang = { workspace = true }
+shapes-macros = { workspace = true }

package/examples/shapes/programs/triangle/src/lib.rs

@@ -0,0 +1,83 @@
+pub mod state;
+
+use anchor_lang::prelude::*;
+use state::ShapeState;
+
+declare_id!("Tri1111111111111111111111111111111111111111");
+
+// --- Account structs ---
+
+#[derive(Accounts)]
+#[instruction(params: InitParams)]
+pub struct Initialize<'info> {
+    #[account(mut)]
+    pub payer: Signer<'info>,
+    #[account(
+        init,
+        payer = payer,
+        space = 8 + ShapeState::INIT_SPACE,
+        seeds = [b"shape"],
+        bump,
+    )]
+    pub shape: Account<'info, ShapeState>,
+    pub system_program: Program<'info, System>,
+}
+
+#[derive(Accounts)]
+pub struct GetName<'info> {
+    pub shape: Account<'info, ShapeState>,
+}
+
+// --- Param types ---
+
+#[derive(Clone, AnchorSerialize, AnchorDeserialize)]
+pub struct InitParams {
+    pub width: u64,
+    pub height: u64,
+}
+
+#[derive(Clone, AnchorSerialize, AnchorDeserialize)]
+pub struct ComputeParams {}
+
+// --- Program module ---
+// Required:  initialize, get_name
+// Handler Override:  compute_area (triangle formula), compute_perimeter (isoceles)
+// Default:   get_dimension_count
+
+#[shapes_macros::shapes(state = ShapeState)]
+pub mod shapes_triangle {
+
+    #[shapes_instruction]
+    #[allow(unused_mut)]
+    pub fn initialize(mut ctx: Context<Initialize>, params: InitParams) -> Result<()> {
+        ctx.accounts.shape.width = params.width;
+        ctx.accounts.shape.height = params.height;
+        ctx.accounts.shape.bump = ctx.bumps.shape;
+        Ok(())
+    }
+
+    #[shapes_instruction]
+    pub fn get_name(_ctx: Context<GetName>) -> Result<String> {
+        Ok("Triangle".to_string())
+    }
+
+    // HANDLER OVERRIDE — reuses StdComputeArea accounts, triangle formula.
+    #[shapes_instruction]
+    pub fn compute_area(ctx: Context<StdComputeArea>, _params: ComputeParams) -> Result<u64> {
+        let s = &ctx.accounts.shape;
+        Ok(s.width * s.height / 2)
+    }
+
+    // HANDLER OVERRIDE — reuses StdComputePerimeter accounts, isoceles triangle.
+    #[shapes_instruction]
+    pub fn compute_perimeter(
+        ctx: Context<StdComputePerimeter>,
+        _params: ComputeParams,
+    ) -> Result<u64> {
+        let s = &ctx.accounts.shape;
+        // Isoceles: two equal sides (width) + base (height)
+        Ok(s.width + s.width + s.height)
+    }
+
+    // DEFAULT — get_dimension_count returns 2, correct for any 2D shape.
+}

package/examples/shapes/programs/triangle/src/state.rs

@@ -0,0 +1,9 @@
+use anchor_lang::prelude::*;
+
+#[account]
+#[derive(InitSpace)]
+pub struct ShapeState {
+    pub width: u64,
+    pub height: u64,
+    pub bump: u8,
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@layerzerolabs/framework-solana-anchor-trait",
+  "version": "0.2.60",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "src",
+    "tests",
+    "examples",
+    "reference",
+    "Cargo.toml",
+    "rust-toolchain.toml",
+    "rustfmt.toml",
+    "SPEC.md"
+  ],
+  "devDependencies": {
+    "@layerzerolabs/build-utils-solana": "0.2.60",
+    "@layerzerolabs/typescript-configuration": "0.2.60",
+    "@layerzerolabs/vm-tooling-solana": "0.2.60",
+    "@layerzerolabs/tsup-configuration": "0.2.60"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "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"
+  }
+}

package/rust-toolchain.toml

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