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

package/README.md

@@ -1,5 +1,316 @@
-# anchor-trait
+# Anchor Trait
 
-Compile-time instruction interface system for Anchor programs — trait-based definitions with default implementations and override levels.
+## Overview
 
-For the full specification, design decisions, and override resolution rules, see [SPEC.md](./SPEC.md).
+The Anchor framework provides no mechanism for defining or enforcing instruction-level interfaces across programs. When a standard requires a set of instructions — e.g., every OApp program must expose `set_peer` and `lz_receive` with specific signatures — there is no compile-time guarantee that a conforming program provides them all, uses the correct parameter types, or returns the expected types. Violations surface only at runtime, typically as CPI failures or deserialization errors.
+
+`anchor-trait` introduces **instruction traits** to Anchor: compile-time enforceable instruction interfaces with optional default implementations. A trait author declares an instruction set — each instruction's parameter type, return type, and whether a default implementation is provided — and the framework ensures, during proc-macro expansion, that every implementing program satisfies the trait contract. Missing required instructions produce compile errors. View instructions additionally enforce **compile-time immutability**: handlers receive `&Context<T>` (not `&mut`), so read-only semantics are upheld by the type system rather than relying solely on Solana runtime protections.
+
+The framework is domain-agnostic. It operates purely at the instruction-signature and accounts-struct level, with no knowledge of any specific application domain. Macro crates such as `oapp-macros` or `rbac-macros` integrate with `anchor-trait` to define their own domain-specific instruction traits.
+
+### Correspondence to Rust traits
+
+| Rust trait                                     | `anchor-trait`                                                                                            |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Required method (no default body)              | Instruction with `default_impl: None` — implementor must provide a handler                                |
+| Default method (has body)                      | Instruction with `default_impl: Some(...)` — framework provides a complete implementation                 |
+| `impl Trait for Type`                          | Applying the domain macro to a module (e.g., `#[oapp(...)] mod my_program { ... }`)                       |
+| Overriding a default method                    | Annotating a handler with `#[oapp_instruction]` — the handler's `Context<T>` determines the accounts type |
+| Compile error on unimplemented required method | Compile error on missing required instruction handler                                                     |
+
+## Instruction Kinds
+
+Each instruction in a trait is classified as one of two kinds:
+
+**Required** — The trait provides no default implementation. The implementor must supply a handler annotated with the override attribute; omitting it produces a compile error. This is analogous to a required method in a Rust trait.
+
+```rust
+InstructionSpec {
+    params_type: Some(quote!(LzReceiveParams)),
+    return_type: quote!(()),
+    is_view: false,
+    default_impl: None,
+}
+```
+
+**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.
+
+```rust
+InstructionSpec {
+    params_type: Some(quote!(SetPeerParams)),
+    return_type: quote!(()),
+    is_view: false,
+    default_impl: Some(DefaultImpl {
+        handler_ident: format_ident!("apply"),
+        generator: generate_default_impl,
+    }),
+}
+```
+
+## Overriding Instructions
+
+For provided instructions, the implementor may accept the default or supply a custom handler annotated with the override attribute (e.g., `#[oapp_instruction]`). The handler's `Context<T>` type determines the entrypoint's accounts type:
+
+- 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.
+
+For required instructions, no default exists. The implementor must provide a handler.
+
+### Resolution algorithm
+
+1. **Handler present** → dispatch to the handler (entrypoint uses the handler's declared context type)
+2. **No handler, default exists** → dispatch to the default handler
+3. **No handler, no default** → compile error
+
+Unannotated functions whose identifiers collide with managed instruction names are rejected at compile time. Such functions must be annotated with the override attribute (e.g. `#[oapp_instruction]`) to disambiguate intent.
+
+## Defining a Trait
+
+The following steps describe how to create a new instruction trait using the framework.
+
+### 1. Define a codegen context
+
+The codegen context is a struct that carries domain-specific resolved types and is threaded through every instruction generator:
+
+```rust
+pub(crate) struct CodegenContext<'a> {
+    pub role_type: &'a TokenStream,
+    pub state_type: &'a TokenStream,
+    // additional domain-specific fields
+}
+```
+
+### 2. Declare the instruction set
+
+The `declare_instructions!` macro enumerates all instructions in the trait. It generates:
+
+- Sub-module declarations (`mod set_peer;`, `mod get_peer;`)
+- A named enum implementing `InstructionSet` with `all()`, `from_ident()`, `canonical_name()`, and `spec()`
+
+```rust
+use anchor_trait::declare_instructions;
+
+declare_instructions! {
+    name    = OAppInstructionSet;
+    context = CodegenContext;
+
+    SetPeer    => set_peer,
+    GetPeer    => get_peer,
+}
+```
+
+### 3. Define per-instruction specs
+
+Each sub-module exports a `spec()` function returning an `InstructionSpec<CodegenContext>` that describes the instruction's signature and default implementation status:
+
+```rust
+// Provided instruction — implementor may accept the default or override:
+pub(super) fn spec<'a>() -> InstructionSpec<CodegenContext<'a>> {
+    InstructionSpec {
+        params_type: Some(quote!(::my_crate::params::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 params_type = spec.params_type.as_ref().unwrap();
+    let handler_ident = &spec.default_impl.as_ref().unwrap().handler_ident;
+
+    // Return complete struct + impl — the framework emits as-is and decomposes for the extend arm
+    DefaultAccounts {
+        struct_type: parse_quote! {
+            #[event_cpi]
+            #[derive(Accounts)]
+            #[instruction(params: #params_type)]
+            pub struct StdSetPeer<'info> {
+                pub authority: Signer<'info>,
+                // ... additional fields ...
+            }
+        },
+        impl_block: parse_quote! {
+            impl StdSetPeer<'_> {
+                pub fn #handler_ident(ctx: &mut Context<Self>, params: &#params_type) -> Result<()> {
+                    // ... default handler logic ...
+                    Ok(())
+                }
+            }
+        },
+    }
+}
+
+// Required instruction — implementor must provide a handler:
+pub(super) fn spec<'a>() -> InstructionSpec<CodegenContext<'a>> {
+    InstructionSpec {
+        params_type: Some(quote!(::my_crate::params::LzReceiveParams)),
+        return_type: quote!(()),
+        is_view: false,
+        default_impl: None,
+    }
+}
+```
+
+### 4. Configure the override attribute
+
+```rust
+const OVERRIDE_CONFIG: OverrideConfig = OverrideConfig {
+    attr_name: "oapp_instruction",  // attribute written by implementors
+    domain: "OApp",                 // label used in diagnostics
+};
+```
+
+### 5. Implement the macro entry point
+
+The entry point follows a four-phase pipeline: **parse → collect → generate → assemble**.
+
+```rust
+pub fn my_macro_impl(attr: TokenStream, item: TokenStream) -> syn::Result<TokenStream> {
+    // Phase 0: Parse inputs (domain-specific; outside the framework's scope)
+    let attr_args = NestedMeta::parse_meta_list(attr)?;
+    let attrs = MyDomainAttr::from_list(&attr_args)?;
+    let module = syn::parse2::<ItemMod>(item)?;
+    let codegen_ctx = /* resolve domain types from attrs */;
+
+    // Phase 1: Collect — scan for override handlers
+    let overrides = InstructionOverrides::collect(&module, OVERRIDE_CONFIG)?;
+
+    // Phase 2: Generate — emit instruction code
+    let instructions = generate_instructions::<MyInstructionSet>(&codegen_ctx, &overrides)?;
+
+    // Phase 3: Assemble — combine all generated fragments into the final output
+    Ok(Assembly {
+        prelude: /* domain-specific definitions */,
+        overrides,
+        instructions,
+        extra_mod_attrs: /* e.g. quote!(#[program]) */,
+        source_mod: module,
+        extend_macro_name: Some(format_ident!("my_domain_extend_accounts")),
+    }
+    .assemble())
+}
+```
+
+### 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])
+[vis] mod <name> {
+    use super::*;
+    <filtered_items> — original module items, excluding relocated handlers
+    <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.
+
+### Usage
+
+The extend macro must be invoked **after** the domain macro module in the source file:
+
+```rust
+#[my_domain(state = MyState)]
+pub mod my_program {
+    #[my_domain_instruction]
+    pub fn set_peer(ctx: &mut Context<ExtSetPeer>, params: &SetPeerParams) -> Result<()> {
+        ExtSetPeer::apply(ctx, params)?;       // default handler, copied to extended struct
+        ctx.accounts.my_extra.do_something()?;  // extra account
+        Ok(())
+    }
+}
+
+// Must appear after the domain macro module (macro_rules! is textually scoped).
+// Rust item name resolution is NOT order-dependent, so ExtSetPeer is visible above.
+my_domain_extend_accounts!(set_peer, ExtSetPeer, {
+    pub my_extra: Account<'info, MyExtraState>,
+});
+```
+
+### 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`.
+
+## Reference
+
+### Naming conventions
+
+| Item                    | Convention                   | Example                        |
+| ----------------------- | ---------------------------- | ------------------------------ |
+| Default accounts struct | `Std<PascalCaseInstruction>` | `StdSetPeer`                   |
+| Override attribute      | `<domain>_instruction`       | `oapp_instruction`             |
+| Params type             | Fully qualified path         | `::oapp::types::SetPeerParams` |
+
+### InstructionSpec fields
+
+| Field          | Type                       | Description                                                                                                                                                                                       |
+| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params_type`  | `Option<TokenStream>`      | Parameter type for the generated entrypoint. Must be a single struct type (e.g., `SetPeerParams`); multiple parameters are not supported. `None` indicates the instruction accepts no parameters. |
+| `return_type`  | `TokenStream`              | Return type of the generated entrypoint (the `T` in `Result<T>`).                                                                                                                                 |
+| `is_view`      | `bool`                     | When `true`, the entrypoint receives `ctx: Context<T>` (immutable) and passes `&ctx` to the handler. When `false`, it receives `mut ctx: Context<T>` and passes `&mut ctx`.                       |
+| `default_impl` | `Option<DefaultImpl<Ctx>>` | `Some(...)` designates a provided instruction with a default implementation. `None` designates a required instruction; the implementor must supply a handler.                                     |
+
+### DefaultImpl fields
+
+| Field           | Type                                                 | Description                                                                                                                                                                                         |
+| --------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `handler_ident` | `Ident`                                              | Identifier of the default handler method (e.g., `apply`). When no override is present, the entrypoint invokes `<accounts_ident>::<handler_ident>(...)`.                                             |
+| `generator`     | `fn(&Ctx, &InstructionSpec<Ctx>) -> DefaultAccounts` | Returns a `DefaultAccounts` containing a complete `ItemStruct` and `ItemImpl`. The framework emits them directly for the concrete definition and decomposes them for the extend `macro_rules!` arm. |
+
+### DefaultAccounts fields
+
+| Field         | Type         | Description                                                                                                                                                                                                                                    |
+| ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `struct_type` | `ItemStruct` | A complete accounts struct definition including attributes, name, generics, and fields. Written with `parse_quote!` so generators read as plain Rust. The struct name becomes the `accounts_ident` (e.g. `StdSetPeer`).                        |
+| `impl_block`  | `ItemImpl`   | A complete `impl` block for the struct, containing handler methods. Written with `parse_quote!` so generators read as plain Rust. Handler methods must use `Context<Self>` so they work for both the concrete struct and any extended variant. |
+
+### Default accounts struct
+
+Each `DefaultAccounts` returned by a generator must satisfy the following:
+
+- `struct_type` must be a named-field struct with a `<'info>` lifetime parameter (the standard Anchor accounts lifetime)
+- `struct_type` must carry the standard Anchor attributes (e.g. `#[derive(Accounts)]`) — these are preserved as-is in `to_definition()` and re-emitted by `to_extend_rule()`
+- `impl_block` must define a handler method matching `handler_ident` with one of the following signatures:
+    - Mutable: `fn apply(ctx: &mut Context<Self>, params: &ParamsType) -> Result<ReturnType>`
+    - View: `fn apply(ctx: &Context<Self>, params: &ParamsType) -> Result<ReturnType>`
+    - Omit the `params` parameter when `params_type` is `None`
+- Handler methods must use `Context<Self>` (not a concrete struct name) so they work for both the concrete `Std*` struct and any extended variant
+- The struct is emitted **outside** the `#[program]` module
+
+### Entrypoint signatures
+
+```rust
+// Mutable instruction with parameters:
+pub fn set_peer(mut ctx: Context<CtxType>, params: ParamsType) -> Result<ReturnType> { ... }
+
+// View instruction with parameters:
+pub fn get_peer(ctx: Context<CtxType>, params: ParamsType) -> Result<ReturnType> { ... }
+
+// Instruction without parameters:
+pub fn set_delegate(mut ctx: Context<CtxType>) -> Result<()> { ... }
+```
+
+### Dispatch
+
+| Scenario         | `CtxType`              | Dispatch (with params)                    | Dispatch (no params)             |
+| ---------------- | ---------------------- | ----------------------------------------- | -------------------------------- |
+| No handler       | `StdSetPeer`           | `StdSetPeer::apply(&mut ctx, &params)`    | `StdSetPeer::apply(&mut ctx)`    |
+| Handler provided | handler's declared `T` | `__wrapper__::handler(&mut ctx, &params)` | `__wrapper__::handler(&mut ctx)` |
+
+- All handlers receive `ctx` by reference (`&mut` for mutable, `&` for views) and `params` by reference. `__wrapper__` denotes the relocated wrapper module (e.g., `__oapp_instruction__set_peer_handler`).
+- For view instructions, `&mut` becomes `&` in the dispatch expressions above.
+- Override handlers that pass `ctx` by value (`Context<T>` instead of `&Context<T>` or `&mut Context<T>`) are rejected at compile time.

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

@@ -1 +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]
+[143,237,208,137,148,97,72,197,129,0,160,178,75,9,2,44,196,175,204,40,70,117,61,37,237,233,142,249,249,238,28,61,109,101,145,186,7,51,68,36,42,149,5,235,136,87,24,144,57,197,82,169,204,215,249,105,58,110,10,53,187,25,153,198]

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

@@ -1 +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]
+[244,248,2,78,59,247,194,68,247,45,37,98,43,8,253,138,212,87,43,247,99,192,196,197,47,42,160,42,176,138,196,243,228,63,253,20,179,133,24,94,71,230,27,114,191,144,199,250,248,153,140,126,39,189,51,5,161,92,192,178,37,165,229,47]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layerzerolabs/framework-solana-anchor-trait",
-  "version": "0.2.63",
+  "version": "0.2.65",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -11,19 +11,23 @@
     "reference",
     "Cargo.toml",
     "rust-toolchain.toml",
-    "rustfmt.toml",
-    "SPEC.md"
+    "rustfmt.toml"
   ],
   "devDependencies": {
-    "@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"
+    "@layerzerolabs/build-utils-solana": "0.2.65",
+    "@layerzerolabs/typescript-configuration": "0.2.65",
+    "@layerzerolabs/vm-tooling-solana": "0.2.65",
+    "@layerzerolabs/tsup-configuration": "0.2.65"
   },
   "publishConfig": {
     "access": "restricted",
     "registry": "https://registry.npmjs.org/"
   },
+  "externalRepoConfig": {
+    "targets": [
+      "audit-external"
+    ]
+  },
   "scripts": {
     "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",
@@ -38,6 +42,6 @@
     "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"
+    "test:lib": "pnpm exec lz-tool --script 'cargo test -p anchor-trait --lib --tests' anchor"
   }
 }

package/SPEC.md

@@ -1,318 +0,0 @@
-# Anchor Trait Specification
-
-> **Status: Draft**
-
-## Overview
-
-The Anchor framework provides no mechanism for defining or enforcing instruction-level interfaces across programs. When a standard requires a set of instructions — e.g., every OApp program must expose `set_peer` and `lz_receive` with specific signatures — there is no compile-time guarantee that a conforming program provides them all, uses the correct parameter types, or returns the expected types. Violations surface only at runtime, typically as CPI failures or deserialization errors.
-
-`anchor-trait` introduces **instruction traits** to Anchor: compile-time enforceable instruction interfaces with optional default implementations. A trait author declares an instruction set — each instruction's parameter type, return type, and whether a default implementation is provided — and the framework ensures, during proc-macro expansion, that every implementing program satisfies the trait contract. Missing required instructions produce compile errors. View instructions additionally enforce **compile-time immutability**: handlers receive `&Context<T>` (not `&mut`), so read-only semantics are upheld by the type system rather than relying solely on Solana runtime protections.
-
-The framework is domain-agnostic. It operates purely at the instruction-signature and accounts-struct level, with no knowledge of any specific application domain. Macro crates such as `lz-oapp-macros` or `rbac-macros` integrate with `anchor-trait` to define their own domain-specific instruction traits.
-
-### Correspondence to Rust traits
-
-| Rust trait                                     | `anchor-trait`                                                                                            |
-| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Required method (no default body)              | Instruction with `default_impl: None` — implementor must provide a handler                                |
-| Default method (has body)                      | Instruction with `default_impl: Some(...)` — framework provides a complete implementation                 |
-| `impl Trait for Type`                          | Applying the domain macro to a module (e.g., `#[oapp(...)] mod my_program { ... }`)                       |
-| Overriding a default method                    | Annotating a handler with `#[oapp_instruction]` — the handler's `Context<T>` determines the accounts type |
-| Compile error on unimplemented required method | Compile error on missing required instruction handler                                                     |
-
-## Instruction Kinds
-
-Each instruction in a trait is classified as one of two kinds:
-
-**Required** — The trait provides no default implementation. The implementor must supply a handler annotated with the override attribute; omitting it produces a compile error. This is analogous to a required method in a Rust trait.
-
-```rust
-InstructionSpec {
-    params_type: Some(quote!(LzReceiveParams)),
-    return_type: quote!(()),
-    is_view: false,
-    default_impl: None,
-}
-```
-
-**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.
-
-```rust
-InstructionSpec {
-    params_type: Some(quote!(SetPeerParams)),
-    return_type: quote!(()),
-    is_view: false,
-    default_impl: Some(DefaultImpl {
-        handler_ident: format_ident!("apply"),
-        generator: generate_default_impl,
-    }),
-}
-```
-
-## Overriding Instructions
-
-For provided instructions, the implementor may accept the default or supply a custom handler annotated with the override attribute (e.g., `#[oapp_instruction]`). The handler's `Context<T>` type determines the entrypoint's accounts type:
-
-- 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.
-
-For required instructions, no default exists. The implementor must provide a handler.
-
-### Resolution algorithm
-
-1. **Handler present** → dispatch to the handler (entrypoint uses the handler's declared context type)
-2. **No handler, default exists** → dispatch to the default handler
-3. **No handler, no default** → compile error
-
-Unannotated functions whose identifiers collide with managed instruction names are rejected at compile time. Such functions must be annotated with the override attribute (e.g. `#[oapp_instruction]`) to disambiguate intent.
-
-## Defining a Trait
-
-The following steps describe how to create a new instruction trait using the framework.
-
-### 1. Define a codegen context
-
-The codegen context is a struct that carries domain-specific resolved types and is threaded through every instruction generator:
-
-```rust
-pub(crate) struct CodegenContext<'a> {
-    pub role_type: &'a TokenStream,
-    pub state_type: &'a TokenStream,
-    // additional domain-specific fields
-}
-```
-
-### 2. Declare the instruction set
-
-The `declare_instructions!` macro enumerates all instructions in the trait. It generates:
-
-- Sub-module declarations (`mod set_peer;`, `mod get_peer;`)
-- A named enum implementing `InstructionSet` with `all()`, `from_ident()`, `canonical_name()`, and `spec()`
-
-```rust
-use anchor_trait::declare_instructions;
-
-declare_instructions! {
-    name    = OAppInstructionSet;
-    context = CodegenContext;
-
-    SetPeer    => set_peer,
-    GetPeer    => get_peer,
-}
-```
-
-### 3. Define per-instruction specs
-
-Each sub-module exports a `spec()` function returning an `InstructionSpec<CodegenContext>` that describes the instruction's signature and default implementation status:
-
-```rust
-// Provided instruction — implementor may accept the default or override:
-pub(super) fn spec<'a>() -> InstructionSpec<CodegenContext<'a>> {
-    InstructionSpec {
-        params_type: Some(quote!(::my_crate::params::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 params_type = spec.params_type.as_ref().unwrap();
-    let handler_ident = &spec.default_impl.as_ref().unwrap().handler_ident;
-
-    // Return complete struct + impl — the framework emits as-is and decomposes for the extend arm
-    DefaultAccounts {
-        struct_type: parse_quote! {
-            #[event_cpi]
-            #[derive(Accounts)]
-            #[instruction(params: #params_type)]
-            pub struct StdSetPeer<'info> {
-                pub authority: Signer<'info>,
-                // ... additional fields ...
-            }
-        },
-        impl_block: parse_quote! {
-            impl StdSetPeer<'_> {
-                pub fn #handler_ident(ctx: &mut Context<Self>, params: &#params_type) -> Result<()> {
-                    // ... default handler logic ...
-                    Ok(())
-                }
-            }
-        },
-    }
-}
-
-// Required instruction — implementor must provide a handler:
-pub(super) fn spec<'a>() -> InstructionSpec<CodegenContext<'a>> {
-    InstructionSpec {
-        params_type: Some(quote!(::my_crate::params::LzReceiveParams)),
-        return_type: quote!(()),
-        is_view: false,
-        default_impl: None,
-    }
-}
-```
-
-### 4. Configure the override attribute
-
-```rust
-const OVERRIDE_CONFIG: OverrideConfig = OverrideConfig {
-    attr_name: "oapp_instruction",  // attribute written by implementors
-    domain: "OApp",                 // label used in diagnostics
-};
-```
-
-### 5. Implement the macro entry point
-
-The entry point follows a four-phase pipeline: **parse → collect → generate → assemble**.
-
-```rust
-pub fn my_macro_impl(attr: TokenStream, item: TokenStream) -> syn::Result<TokenStream> {
-    // Phase 0: Parse inputs (domain-specific; outside the framework's scope)
-    let attr_args = NestedMeta::parse_meta_list(attr)?;
-    let attrs = MyDomainAttr::from_list(&attr_args)?;
-    let module = syn::parse2::<ItemMod>(item)?;
-    let codegen_ctx = /* resolve domain types from attrs */;
-
-    // Phase 1: Collect — scan for override handlers
-    let overrides = InstructionOverrides::collect(&module, OVERRIDE_CONFIG)?;
-
-    // Phase 2: Generate — emit instruction code
-    let instructions = generate_instructions::<MyInstructionSet>(&codegen_ctx, &overrides)?;
-
-    // Phase 3: Assemble — combine all generated fragments into the final output
-    Ok(Assembly {
-        prelude: /* domain-specific definitions */,
-        overrides,
-        instructions,
-        extra_mod_attrs: /* e.g. quote!(#[program]) */,
-        source_mod: module,
-        extend_macro_name: Some(format_ident!("my_domain_extend_accounts")),
-    }
-    .assemble())
-}
-```
-
-### 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])
-[vis] mod <name> {
-    use super::*;
-    <filtered_items> — original module items, excluding relocated handlers
-    <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.
-
-### Usage
-
-The extend macro must be invoked **after** the domain macro module in the source file:
-
-```rust
-#[my_domain(state = MyState)]
-pub mod my_program {
-    #[my_domain_instruction]
-    pub fn set_peer(ctx: &mut Context<ExtSetPeer>, params: &SetPeerParams) -> Result<()> {
-        ExtSetPeer::apply(ctx, params)?;       // default handler, copied to extended struct
-        ctx.accounts.my_extra.do_something()?;  // extra account
-        Ok(())
-    }
-}
-
-// Must appear after the domain macro module (macro_rules! is textually scoped).
-// Rust item name resolution is NOT order-dependent, so ExtSetPeer is visible above.
-my_domain_extend_accounts!(set_peer, ExtSetPeer, {
-    pub my_extra: Account<'info, MyExtraState>,
-});
-```
-
-### 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`.
-
-## Reference
-
-### Naming conventions
-
-| Item                    | Convention                   | Example                           |
-| ----------------------- | ---------------------------- | --------------------------------- |
-| Default accounts struct | `Std<PascalCaseInstruction>` | `StdSetPeer`                      |
-| Override attribute      | `<domain>_instruction`       | `oapp_instruction`                |
-| Params type             | Fully qualified path         | `::lz_oapp::types::SetPeerParams` |
-
-### InstructionSpec fields
-
-| Field          | Type                       | Description                                                                                                                                                                                       |
-| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params_type`  | `Option<TokenStream>`      | Parameter type for the generated entrypoint. Must be a single struct type (e.g., `SetPeerParams`); multiple parameters are not supported. `None` indicates the instruction accepts no parameters. |
-| `return_type`  | `TokenStream`              | Return type of the generated entrypoint (the `T` in `Result<T>`).                                                                                                                                 |
-| `is_view`      | `bool`                     | When `true`, the entrypoint receives `ctx: Context<T>` (immutable) and passes `&ctx` to the handler. When `false`, it receives `mut ctx: Context<T>` and passes `&mut ctx`.                       |
-| `default_impl` | `Option<DefaultImpl<Ctx>>` | `Some(...)` designates a provided instruction with a default implementation. `None` designates a required instruction; the implementor must supply a handler.                                     |
-
-### DefaultImpl fields
-
-| Field           | Type                                                 | Description                                                                                                                                                                                         |
-| --------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `handler_ident` | `Ident`                                              | Identifier of the default handler method (e.g., `apply`). When no override is present, the entrypoint invokes `<accounts_ident>::<handler_ident>(...)`.                                             |
-| `generator`     | `fn(&Ctx, &InstructionSpec<Ctx>) -> DefaultAccounts` | Returns a `DefaultAccounts` containing a complete `ItemStruct` and `ItemImpl`. The framework emits them directly for the concrete definition and decomposes them for the extend `macro_rules!` arm. |
-
-### DefaultAccounts fields
-
-| Field         | Type         | Description                                                                                                                                                                                                                                    |
-| ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `struct_type` | `ItemStruct` | A complete accounts struct definition including attributes, name, generics, and fields. Written with `parse_quote!` so generators read as plain Rust. The struct name becomes the `accounts_ident` (e.g. `StdSetPeer`).                        |
-| `impl_block`  | `ItemImpl`   | A complete `impl` block for the struct, containing handler methods. Written with `parse_quote!` so generators read as plain Rust. Handler methods must use `Context<Self>` so they work for both the concrete struct and any extended variant. |
-
-### Default accounts struct
-
-Each `DefaultAccounts` returned by a generator must satisfy the following:
-
-- `struct_type` must be a named-field struct with a `<'info>` lifetime parameter (the standard Anchor accounts lifetime)
-- `struct_type` must carry the standard Anchor attributes (e.g. `#[derive(Accounts)]`) — these are preserved as-is in `to_definition()` and re-emitted by `to_extend_rule()`
-- `impl_block` must define a handler method matching `handler_ident` with one of the following signatures:
-    - Mutable: `fn apply(ctx: &mut Context<Self>, params: &ParamsType) -> Result<ReturnType>`
-    - View: `fn apply(ctx: &Context<Self>, params: &ParamsType) -> Result<ReturnType>`
-    - Omit the `params` parameter when `params_type` is `None`
-- Handler methods must use `Context<Self>` (not a concrete struct name) so they work for both the concrete `Std*` struct and any extended variant
-- The struct is emitted **outside** the `#[program]` module
-
-### Entrypoint signatures
-
-```rust
-// Mutable instruction with parameters:
-pub fn set_peer(mut ctx: Context<CtxType>, params: ParamsType) -> Result<ReturnType> { ... }
-
-// View instruction with parameters:
-pub fn get_peer(ctx: Context<CtxType>, params: ParamsType) -> Result<ReturnType> { ... }
-
-// Instruction without parameters:
-pub fn set_delegate(mut ctx: Context<CtxType>) -> Result<()> { ... }
-```
-
-### Dispatch
-
-| Scenario         | `CtxType`              | Dispatch (with params)                    | Dispatch (no params)             |
-| ---------------- | ---------------------- | ----------------------------------------- | -------------------------------- |
-| No handler       | `StdSetPeer`           | `StdSetPeer::apply(&mut ctx, &params)`    | `StdSetPeer::apply(&mut ctx)`    |
-| Handler provided | handler's declared `T` | `__wrapper__::handler(&mut ctx, &params)` | `__wrapper__::handler(&mut ctx)` |
-
-- All handlers receive `ctx` by reference (`&mut` for mutable, `&` for views) and `params` by reference. `__wrapper__` denotes the relocated wrapper module (e.g., `__oapp_instruction__set_peer_handler`).
-- For view instructions, `&mut` becomes `&` in the dispatch expressions above.
-- Override handlers that pass `ctx` by value (`Context<T>` instead of `&Context<T>` or `&mut Context<T>`) are rejected at compile time.