@layerzerolabs/framework-solana-anchor-trait 0.2.60

package/rustfmt.toml

@@ -0,0 +1,23 @@
+# Basic
+hard_tabs = false
+max_width = 100
+use_small_heuristics = "Max"
+# Imports
+imports_granularity = "Preserve"
+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/assembly.rs

@@ -0,0 +1,63 @@
+//! Final assembly of generated code into the macro output.
+
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::ItemMod;
+
+use crate::generation::GeneratedInstructions;
+use crate::overrides::InstructionOverrides;
+use crate::InstructionSet;
+
+/// Input for the final assembly step.
+pub struct Assembly<Ix: InstructionSet> {
+    /// Token stream emitted before the module (e.g. default state structs, role events).
+    pub prelude: TokenStream,
+    /// The collected overrides (provides wrapper defs and item filtering).
+    pub overrides: InstructionOverrides<Ix>,
+    /// The generated instruction code.
+    pub instructions: GeneratedInstructions,
+    /// Extra attributes placed on the module (e.g. `#[program]`, `#[rbac(...)]`).
+    pub extra_mod_attrs: TokenStream,
+    /// The original module being transformed.
+    pub source_mod: ItemMod,
+}
+
+impl<Ix: InstructionSet> Assembly<Ix> {
+    /// Assembles the final macro output from all generated parts.
+    ///
+    /// ```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]
+    /// #[original_mod_attrs]
+    /// 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 wrapper_defs = &overrides.wrapper_defs;
+        let filtered_items = overrides.filtered_items(&source_mod);
+        let GeneratedInstructions { default_impls, entrypoints } = &instructions;
+
+        let ItemMod { attrs: mod_attrs, vis: mod_vis, ident: mod_ident, .. } = &source_mod;
+
+        quote! {
+            #prelude
+
+            #wrapper_defs
+            #default_impls
+
+            #(#mod_attrs)*
+            #extra_mod_attrs
+            #mod_vis mod #mod_ident {
+                use super::*;
+                #filtered_items
+                #entrypoints
+            }
+        }
+    }
+}

package/src/generation.rs

@@ -0,0 +1,226 @@
+//! Instruction code generation with override level resolution.
+//!
+//! - **Default**: No override → emit default impl + default entrypoint.
+//! - **Handler Override**: Override with default context type → emit default impl, entrypoint
+//!   dispatches to implementor's handler.
+//! - **Full Override**: Override with custom context type → skip default impl, entrypoint
+//!   dispatches to implementor's handler with custom type.
+
+use proc_macro2::{Ident, Span, TokenStream};
+use quote::{quote, ToTokens};
+
+use crate::overrides::{HandlerMeta, InstructionOverrides};
+use crate::InstructionSet;
+
+/// Descriptor for one instruction's code generation.
+pub struct InstructionSpec<Ctx> {
+    /// Parameter type as a token stream (e.g. `Some(quote!(::lz_oapp::params::SetPeerParams))`).
+    /// Use `None` for instructions with no params.
+    pub params_type: Option<TokenStream>,
+    /// Return type as a token stream (e.g. `quote!(())` or `quote!([u8; 32])`).
+    pub return_type: TokenStream,
+    /// When `true`, the entrypoint passes `ctx` / `&ctx` (immutable).
+    /// When `false` , it passes `mut ctx` / `&mut ctx`.
+    pub is_view: bool,
+    /// - `Some(...)` — provided instruction (all three override levels valid).
+    /// - `None` — **required** instruction: the implementor must provide an override handler (only
+    ///   Full Override is valid). Omitting the override produces a compile error.
+    pub default_impl: Option<DefaultImpl<Ctx>>,
+}
+
+/// Default impl generation for an instruction (accounts struct + handler).
+///
+/// Groups the three fields that are only meaningful when an instruction
+/// has a framework-provided default implementation.
+pub struct DefaultImpl<Ctx> {
+    /// Name of the default accounts struct, e.g. `format_ident!("StdSetPeer")`.
+    /// Also used to detect Handler Override vs Full Override (string comparison with handler's
+    /// accounts type).
+    pub accounts_ident: Ident,
+    /// Name of the default handler method on the context struct, e.g. `format_ident!("apply")`.
+    /// At the Default level, the entrypoint calls `StdAccounts::<this>(...)`.
+    pub handler_ident: Ident,
+    /// Generates the default accounts struct + handler impl.
+    /// The impl must define a method matching [`handler_ident`](Self::handler_ident).
+    /// For mutable instructions: `fn(&mut Context<Self>, &Params) -> Result<R>`.
+    /// For view instructions: `fn(&Context<Self>, &Params) -> Result<R>`.
+    /// Omit the params argument when `params_type = None`.
+    pub generator: fn(&Ctx, &InstructionSpec<Ctx>) -> TokenStream,
+}
+
+impl<Ctx> InstructionSpec<Ctx> {
+    /// Returns `true` if the given context's accounts type matches the default accounts ident,
+    /// meaning the override handler reuses the default context struct (Handler Override).
+    fn uses_default(&self, accounts_type: &syn::Type) -> bool {
+        self.default_impl.as_ref().is_some_and(|default| {
+            matches!(accounts_type, syn::Type::Path(ty) if ty.path.is_ident(&default.accounts_ident))
+        })
+    }
+}
+
+/// Accumulated output from instruction generation.
+#[derive(Default)]
+pub struct GeneratedInstructions {
+    /// All default impl definitions (accounts struct + handler), placed outside the program
+    /// module.
+    pub default_impls: TokenStream,
+    /// All entrypoint function definitions (placed inside the program module).
+    pub entrypoints: TokenStream,
+}
+
+impl GeneratedInstructions {
+    fn extend(&mut self, other: Self) {
+        self.default_impls.extend(other.default_impls);
+        self.entrypoints.extend(other.entrypoints);
+    }
+}
+
+/// Resolved override: everything needed to assemble the entrypoint.
+struct ResolvedOverride {
+    /// Tokens for the default accounts struct + handler impl (emitted outside the
+    /// program module). Empty when the override fully replaces the default context.
+    default_impl: TokenStream,
+    /// Function-level generics from the override handler (e.g. `<'info>`).
+    /// Empty at the Default level since the generated entrypoint needs no extra generics.
+    fn_generics: TokenStream,
+    /// The `ctx` parameter declaration: `ctx: Context<T>` or `mut ctx: Context<T>`.
+    ctx_param: TokenStream,
+    /// Body expression for instructions that take params: `handler(ctx, params)`.
+    call_with_params: TokenStream,
+    /// Body expression for parameter-less instructions: `handler(ctx)`.
+    call_no_params: TokenStream,
+}
+
+/// Generates code for all instructions and merges into a single output.
+pub fn generate_instructions<Ix: InstructionSet>(
+    ctx: &Ix::Ctx,
+    overrides: &InstructionOverrides<Ix>,
+) -> syn::Result<GeneratedInstructions> {
+    let mut out = GeneratedInstructions::default();
+    for &ix in Ix::all() {
+        out.extend(generate_instruction(ix, ctx, overrides)?);
+    }
+    Ok(out)
+}
+
+/// Generates code for a single instruction with override level resolution.
+///
+/// Returns `Err` if the instruction is required (`default_impl = None`)
+/// and the implementor did not provide an override handler.
+fn generate_instruction<Ix: InstructionSet>(
+    ix_name: Ix,
+    ctx: &Ix::Ctx,
+    overrides: &InstructionOverrides<Ix>,
+) -> syn::Result<GeneratedInstructions> {
+    let spec = ix_name.spec(ctx);
+    let handler = overrides.get(ix_name);
+
+    // Required instruction with no override → compile error.
+    if handler.is_none() && spec.default_impl.is_none() {
+        let cfg = &overrides.config;
+        return Err(syn::Error::new(
+            Span::call_site(),
+            format!(
+                "instruction `{}` has no default implementation; \
+                 provide a handler with #[{}({})]",
+                ix_name.canonical_name(),
+                cfg.attr_name,
+                ix_name.canonical_name(),
+            ),
+        ));
+    }
+
+    let fn_ident = syn::Ident::new(ix_name.canonical_name(), Span::call_site());
+    let return_type = &spec.return_type;
+
+    let ResolvedOverride { default_impl, fn_generics, ctx_param, call_with_params, call_no_params } =
+        resolve_override(handler, &spec, ctx);
+
+    // Assemble the entrypoint function, with or without a params argument.
+    // Override handlers preserve function generics (e.g. lifetime params for remaining_accounts).
+    let entrypoints = match &spec.params_type {
+        Some(params_type) => quote! {
+            pub fn #fn_ident #fn_generics (#ctx_param, params: #params_type) -> Result<#return_type> {
+                #call_with_params
+            }
+        },
+        None => quote! {
+            pub fn #fn_ident #fn_generics (#ctx_param) -> Result<#return_type> {
+                #call_no_params
+            }
+        },
+    };
+
+    Ok(GeneratedInstructions { default_impls: default_impl, entrypoints })
+}
+
+/// Resolves which override level applies and returns the tokens for each part.
+///
+/// - **Override present** → dispatch to the implementor's wrapper handler. Emit default impl only
+///   if the handler reuses the default context (Handler Override).
+/// - **No override** → dispatch to the default handler directly.
+fn resolve_override<Ctx>(
+    override_handler: Option<&HandlerMeta>,
+    spec: &InstructionSpec<Ctx>,
+    ctx: &Ctx,
+) -> ResolvedOverride {
+    match (override_handler, &spec.default_impl) {
+        // Handler Override or Full Override — the implementor provided a custom handler.
+        //
+        // Handler Override (context type matches default): emit default impl so the
+        //   override handler can delegate back to the default accounts struct.
+        // Full Override (different context type): skip default impl entirely; the
+        //   implementor supplies their own accounts struct and handler logic.
+        //
+        // In both cases the entrypoint dispatches to the implementor's wrapper handler,
+        // passing `ctx` and `params` by value (ownership) so they can freely mutate,
+        // destructure, or forward them.
+        (Some(handler), spec_default) => {
+            let default_impl = if spec.uses_default(&handler.accounts_type) {
+                (spec_default.as_ref().unwrap().generator)(ctx, spec)
+            } else {
+                TokenStream::new()
+            };
+            let wrapper = &handler.wrapper_mod;
+            let handler_fn = &handler.fn_ident;
+            let context_type = &handler.context_type;
+            ResolvedOverride {
+                default_impl,
+                fn_generics: handler.fn_generics.to_token_stream(),
+                ctx_param: ctx_param_tokens(spec.is_view, quote!(#context_type)),
+                call_with_params: quote!(#wrapper::#handler_fn(ctx, params)),
+                call_no_params: quote!(#wrapper::#handler_fn(ctx)),
+            }
+        },
+        // Default level — no override provided.
+        //
+        // Emit the framework-provided default impl and call its handler directly.
+        // Unlike override handlers, the default handler receives `ctx` by reference
+        // (`&` for views, `&mut` for mutable) because it is a method on the default
+        // accounts struct, not a standalone function the implementor owns.
+        (None, Some(default)) => {
+            let accounts = &default.accounts_ident;
+            let handler_fn = &default.handler_ident;
+            let ref_token = if spec.is_view { quote!(&) } else { quote!(&mut) };
+            ResolvedOverride {
+                default_impl: (default.generator)(ctx, spec),
+                fn_generics: TokenStream::new(),
+                ctx_param: ctx_param_tokens(spec.is_view, quote!(Context<#accounts>)),
+                call_with_params: quote!(#accounts::#handler_fn(#ref_token ctx, &params)),
+                call_no_params: quote!(#accounts::#handler_fn(#ref_token ctx)),
+            }
+        },
+        // Unreachable: `generate_instruction` validates that at least one of
+        // override_handler or default_impl is present before calling this function.
+        (None, None) => unreachable!("validated above"),
+    }
+}
+
+/// Generates `ctx: T` or `mut ctx: T` depending on mutability.
+fn ctx_param_tokens(is_view: bool, context_type: TokenStream) -> TokenStream {
+    if is_view {
+        quote!(ctx: #context_type)
+    } else {
+        quote!(mut ctx: #context_type)
+    }
+}

package/src/lib.rs

@@ -0,0 +1,126 @@
+//! Trait-like instruction interfaces for Anchor Solana programs.
+//!
+//! Anchor provides no mechanism for enforcing instruction-level interfaces across programs.
+//! This crate introduces **instruction traits**: compile-time enforceable instruction sets
+//! with optional default implementations. Each instruction is either **required** (implementor
+//! must provide a handler) or **provided** (a default implementation is available).
+//!
+//! Provided instructions support three override levels:
+//!
+//! - **Default**: No custom handler — framework emits accounts struct + entrypoint.
+//! - **Handler Override**: Custom handler reuses the default accounts struct.
+//! - **Full Override**: Custom handler with a custom accounts struct.
+//!
+//! See [`spec.md`](../spec.md) for the full specification.
+//!
+//! ## Integration steps for a new macro crate
+//!
+//! 1. Define a `CodegenContext` struct carrying your domain-specific types.
+//! 2. Use [`declare_instructions!`] to declare instructions — this generates an enum implementing
+//!    [`InstructionSet`] with `all()`, `from_ident()`, `canonical_name()`, and `spec()`.
+//! 3. Create an [`OverrideConfig`] with your override attribute and domain names.
+//! 4. Wire up the macro entry point following the 4-phase pipeline:
+//!    - **Parse**: Attribute args, module, domain types (implementor's responsibility).
+//!    - **Collect**: Scan for override handlers with [`InstructionOverrides::collect`].
+//!    - **Generate**: Resolve override levels and emit code with [`generate_instructions`].
+//!    - **Assemble**: Combine fragments into the final output with [`Assembly::assemble`].
+
+mod assembly;
+mod generation;
+mod overrides;
+
+pub use assembly::*;
+pub use generation::*;
+pub use overrides::*;
+
+/// Trait implemented by each macro crate's instruction name enum.
+///
+/// Generated by [`declare_instructions!`] or implemented manually.
+pub trait InstructionSet: Copy + Ord + 'static {
+    /// The domain-specific codegen context type (e.g. `CodegenContext`).
+    type Ctx;
+
+    /// All known instruction variants in deterministic order.
+    fn all() -> &'static [Self];
+    /// Parses an instruction name from an attribute argument ident.
+    fn from_ident(ident: &syn::Ident) -> Option<Self>;
+    /// The canonical function name for this instruction (e.g. `"set_peer"`).
+    fn canonical_name(&self) -> &'static str;
+    /// Returns the code generation spec for this instruction variant.
+    fn spec(self, ctx: &Self::Ctx) -> InstructionSpec<Self::Ctx>;
+}
+
+/// Declares all instructions in one place, generating a named enum
+/// implementing [`InstructionSet`].
+///
+/// Each `Variant => mod_name` pair maps an enum variant to the module
+/// whose `spec()` function provides the codegen descriptor. Appending
+/// `(ctx)` passes the [`CodegenContext`] reference to `spec(&ctx)`;
+/// without it, `spec()` is called with no arguments.
+///
+/// Callers are responsible for declaring their own `mod` items before
+/// invoking this macro.
+///
+/// # Example
+///
+/// ```ignore
+/// mod accept_default_admin;
+/// mod grant_role;
+/// mod renounce_role;
+///
+/// declare_instructions! {
+///     name    = RbacInstructionSet;
+///     context = CodegenContext;
+///
+///     AcceptDefaultAdmin => accept_default_admin,
+///     GrantRole          => grant_role(ctx),
+///     RenounceRole       => renounce_role(ctx),
+/// }
+/// ```
+#[macro_export]
+macro_rules! declare_instructions {
+    // Helper: dispatch spec call — with ctx marker passes ctx, without calls spec()
+    (@spec_call $ctx:ident, $mod_name:ident ( $marker:ident )) => {
+        $mod_name::spec(&$ctx)
+    };
+    (@spec_call $ctx:ident, $mod_name:ident) => {
+        $mod_name::spec()
+    };
+
+    (name = $name:ident; context = $ctx:ident; $( $variant:ident => $mod_name:ident $( ( $ctx_marker:ident ) )? ),+ $(,)?) => {
+        #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+        pub(crate) enum $name {
+            $( $variant, )+
+        }
+
+        impl ::anchor_trait::InstructionSet for $name {
+            type Ctx = $ctx;
+
+            fn all() -> &'static [Self] {
+                static ALL: &[$name] = &[
+                    $( $name::$variant, )+
+                ];
+                ALL
+            }
+
+            fn from_ident(ident: &syn::Ident) -> Option<Self> {
+                match ident.to_string().as_str() {
+                    $( stringify!($mod_name) => Some(Self::$variant), )+
+                    _ => None,
+                }
+            }
+
+            fn canonical_name(&self) -> &'static str {
+                match self {
+                    $( Self::$variant => stringify!($mod_name), )+
+                }
+            }
+
+            fn spec(self, ctx: &$ctx) -> ::anchor_trait::InstructionSpec<$ctx> {
+                match self {
+                    $( Self::$variant => $crate::declare_instructions!(@spec_call ctx, $mod_name $( ( $ctx_marker ) )? ), )+
+                }
+            }
+        }
+    };
+}