@layerzerolabs/framework-solana-anchor-trait 0.2.98 → 0.2.100

package/README.md

@@ -33,7 +33,7 @@ InstructionSpec {
 }
 ```
 
-**Provided** — The trait supplies a complete default implementation, including an accounts struct and a handler function. The default accounts struct is always emitted, so it remains available even when the implementor overrides the handler. This is analogous to a default method in a Rust trait.
+**Provided** — The trait supplies a complete default implementation: an accounts struct and a handler `impl`. Both are emitted unconditionally. This is analogous to a default method in a Rust trait.
 
 ```rust
 InstructionSpec {
@@ -54,7 +54,7 @@ For provided instructions, the implementor may accept the default or supply a cu
 - To **reuse** the default accounts struct, declare `Context<StdSetPeer>`.
 - To use **custom** accounts, declare `Context<MyCustomAccounts>`.
 
-The framework does not distinguish between these cases — the default struct is always emitted regardless.
+The framework does not distinguish between these cases — both the default struct and its `apply` impl are always emitted, so an override handler can reuse the default by calling `<accounts>::apply(ctx, params)?`. For example, with `Context<StdSetPeer>` the override can run `StdSetPeer::apply(ctx, params)?` before or after its own logic.
 
 For required instructions, no default exists. The implementor must provide a handler.
 
@@ -202,22 +202,26 @@ pub fn my_macro_impl(attr: TokenStream, item: TokenStream) -> syn::Result<TokenS
 ### Assembly output structure
 
 ```text
-<prelude>            — domain-specific definitions (emitted by the macro crate)
-<wrapper_defs>       — relocated override handler modules
-<default_impls>      — generated default accounts structs + handler impls
-<extend_macro>       — macro_rules! for extending default accounts (if configured)
-<original_mod_attrs> — preserved module attributes
-<extra_mod_attrs>    — additional attributes (e.g., #[program])
+<prelude>              — domain-specific definitions (emitted by the macro crate)
+<default_impls>        — generated default accounts structs + handler impls
+<extend_macro>         — macro_rules! for extending default accounts (if configured)
+<original_outer_attrs> — preserved outer module attributes
+<extra_mod_attrs>      — additional attributes (e.g., #[program])
+                       — any outer attr whose last path segment is `program`
+                         is stripped from the input and re-emitted here
 [vis] mod <name> {
+    <original_inner_attrs> — preserved inner module attributes
     use super::*;
-    <filtered_items> — original module items, excluding relocated handlers
-    <entrypoints>    — generated instruction entrypoints
+    <filtered_items>   — original module items, excluding relocated handlers
+    <wrapper_defs>     — relocated override handler modules (kept inside so handlers
+                         can reach the user's nested same-module helpers)
+    <entrypoints>      — generated instruction entrypoints
 }
 ```
 
 ## Extending Default Accounts
 
-For provided instructions, the framework generates a `macro_rules!` (named via `Assembly::extend_macro_name`) that lets users create extended accounts structs — the default fields plus extra accounts — without duplicating the base implementation.
+For provided instructions, the framework generates a `macro_rules!` (named via `Assembly::extend_macro_name`) that lets users create extended accounts structs — the default fields plus extra accounts — without duplicating the base implementation. **Extension is additive**: the default struct and its `apply` impl remain emitted alongside any extended struct (see [How it works](#how-it-works)). For example, defining `ExtSetPeer` does not replace or hide `StdSetPeer`.
 
 ### Usage
 
@@ -243,7 +247,7 @@ my_domain_extend_accounts!(set_peer, ExtSetPeer, {
 
 ### How it works
 
-Each provided instruction's `DefaultAccounts` produces two outputs: the concrete `Std*` struct (via `to_definition()`, which emits the `ItemStruct` and `ItemImpl` as-is) and a `macro_rules!` arm (via `to_extend_rule()`, which decomposes the struct into attrs/fields, replaces the name with `$name`, and appends `$($extra)*`). `Assembly` collects all arms into one `macro_rules!` named by `extend_macro_name`.
+Each provided instruction's `DefaultAccounts` produces two outputs: the concrete `Std*` struct (via `to_definition()`, which emits the `ItemStruct` and `ItemImpl` as-is) and a `macro_rules!` arm (via `to_extend_rule()`, which decomposes the struct into attrs/fields, replaces the name with `$name`, and appends `$($extra)*`). The arm also re-emits the default's `impl` items, so the extended struct gets an independent copy of `apply` — e.g., `ExtSetPeer::apply` is a parallel method, not a re-export of `StdSetPeer::apply`. `Assembly` collects all arms into one `macro_rules!` named by `extend_macro_name`.
 
 ## Reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layerzerolabs/framework-solana-anchor-trait",
-  "version": "0.2.98",
+  "version": "0.2.100",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -14,10 +14,10 @@
     "rustfmt.toml"
   ],
   "devDependencies": {
-    "@layerzerolabs/build-utils-solana": "0.2.98",
-    "@layerzerolabs/tsup-configuration": "0.2.98",
-    "@layerzerolabs/vm-tooling-solana": "0.2.98",
-    "@layerzerolabs/typescript-configuration": "0.2.98"
+    "@layerzerolabs/build-utils-solana": "0.2.100",
+    "@layerzerolabs/typescript-configuration": "0.2.100",
+    "@layerzerolabs/tsup-configuration": "0.2.100",
+    "@layerzerolabs/vm-tooling-solana": "0.2.100"
   },
   "publishConfig": {
     "access": "restricted",

package/src/assembly.rs

@@ -28,9 +28,10 @@ impl<Ix: InstructionSet> Assembly<Ix> {
     ///
     /// `#[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
+    /// code. Any outer module attribute whose last path segment is `program` is
+    /// stripped and re-emitted at the correct position; this catches qualified
+    /// forms like `#[anchor_lang::program]` and leaves inner `#![…program]`
+    /// untouched. This keeps stacking order irrelevant for any combination of
     /// domain macros (e.g. `#[oapp]` + `#[composer]`).
     ///
     /// ```text
@@ -75,11 +76,14 @@ impl<Ix: InstructionSet> Assembly<Ix> {
 
         let ItemMod { attrs: mod_attrs, vis: mod_vis, ident: mod_ident, .. } = &source_mod;
 
-        // Inner attrs (`#![...]`, `//!`) must live inside the body — rustc rejects them outside.
-        let (inner_attrs, outer_attrs): (Vec<_>, Vec<_>) = mod_attrs
-            .iter()
+        // Partition first: only outer `#[...program]` attrs are framework-owned and re-emitted
+        // below. Inner attrs (`#![...]`, `//!`) must stay inside the module body unchanged.
+        let (inner_attrs, outer_attrs): (Vec<_>, Vec<_>) =
+            mod_attrs.iter().partition(|a| matches!(a.style, AttrStyle::Inner(_)));
+        let outer_attrs: Vec<_> = outer_attrs
+            .into_iter()
             .filter(|a| a.path().segments.last().is_none_or(|s| s.ident != "program"))
-            .partition(|a| matches!(a.style, AttrStyle::Inner(_)));
+            .collect();
 
         quote! {
             #prelude

package/src/generation.rs

@@ -40,16 +40,13 @@ pub struct DefaultImpl<Ctx> {
 
 /// Complete accounts struct and its handler impl block.
 ///
-/// The framework uses this template to produce two outputs:
-/// 1. The concrete struct + impl — emitted as-is via [`to_definition`](Self::to_definition).
-/// 2. A `macro_rules!` rule — built by decomposing the struct into attrs/fields and replacing the
-///    name with `$name` via [`to_extend_rule`](Self::to_extend_rule).
+/// Produces two outputs: the concrete struct + impl via [`to_definition`](Self::to_definition),
+/// and a `macro_rules!` rule via [`to_extend_rule`](Self::to_extend_rule) (which reconstructs
+/// the type as `pub struct $name<'info>` / `impl $name<'_>`).
 ///
-/// The struct may carry at most a single `'info` lifetime parameter. Extra
-/// type or const generics are rejected at expansion time — the entrypoint
-/// and extend-rule codegen paths reduce the type to a bare ident, so any
-/// non-`'info` generics would be silently dropped and produce malformed
-/// output.
+/// **Constraint:** `struct_type` must carry exactly `'info` — no type or const generics.
+/// Extra generics are silently dropped by both codegen paths, surfacing as type errors at
+/// the extend-macro call site.
 pub struct DefaultAccounts {
     /// Complete struct definition including attributes, name, generics, and fields.
     pub struct_type: ItemStruct,

package/src/overrides.rs

@@ -110,8 +110,15 @@ impl<Ix: InstructionSet> InstructionOverrides<Ix> {
         quote!(#(#kept)*)
     }
 
-    /// Relocates a handler function into an isolated wrapper module
-    /// and returns the corresponding [`HandlerMeta`].
+    /// Wraps a handler fn in a generated module
+    /// (`mod __<attr>__<instr>_handler { use super::*; ... }`) and returns
+    /// its [`HandlerMeta`]. The override attribute (e.g. `#[oapp_instruction]`)
+    /// is stripped; other attributes ride along on the cloned fn.
+    ///
+    /// Each attribute expands inside the wrapper module rather than at the
+    /// fn's original location, so any code it generates is inserted there
+    /// and resolves names against the wrapper's scope (which reaches the
+    /// parent via `use super::*;`).
     fn wrap_handler(&mut self, target: Ix, fn_item: &ItemFn) -> syn::Result<HandlerMeta> {
         let context_type = infer_context_type(fn_item)?;
         let fn_generics = fn_item.sig.generics.clone();