feat(ENG-245): Add frame macros for stack layout and signer seeds (#33)

# Changes

1. Add `#[frame]` attribute macro: applies `#[repr(C, align(8))]` and
asserts
the struct fits within one SBPF stack frame (4096 bytes); registers
field
   metadata and doc comment in proc-macro shared state
2. Add `signer_seeds!` function-like macro: defines a `#[repr(C)]`
struct
where every field is `SolSignerSeed`; registers field names in shared
state
   for auto-discovery by `constant_group!`
3. Extend `constant_group!` with `#[frame(Type)]` attribute for
frame-relative
   offsets (`offset_of - size_of`, with 8-byte alignment assertion) and
`signer_seeds!(field)` syntax that auto-expands `_ADDR_OFF`/`_LEN_OFF`
   constants per seed plus an `N_SEEDS` count
4. Add `shared_state` module for cross-proc-macro communication via
process-global `LazyLock<Mutex<HashMap>>` — frame field→type mappings,
   signer seed field lists, and frame doc comments
5. Decompose `constant_group` expand and parse modules into
subdirectories
   (`expand/{mod,offset,immediate,signer_seeds}`,
   `parse/{mod,offset,signer_seeds}`)
6. Define `RegisterMarketFrame` and `PdaSignerSeeds` in
`interface::market`
using the new macros, with a frame-aware `constant_group!` that injects
   `.equ` directives into `market/register.s`
7. Document `#[frame]`, `signer_seeds!`, and frame-relative
`constant_group!`
   mode in the build-scaffolding docs page

Author: alnoki

docs/src/development/build-scaffolding.md

@@ -34,22 +34,36 @@ The [`macros`] crate provides several [proc macros]:
 
 <Include rs="macros::lib" collapsed/>
 
-### `constant_group!`
+### `constant_group!` {#constant_group}
 
 Defines a group of named assembly constants with an injection target. The
 `#[inject("file")]` attribute specifies which assembly file receives the
 constants. An optional `#[prefix("...")]` attribute prepends a prefix to all
 generated constant names. An optional `///` doc comment on the group itself
 adds a header comment and separator lines around the group in the output
-assembly file. Each constant is assigned a value using one of two custom
+assembly file. Each constant is assigned a value using one of three custom
 syntax forms (parsed within the proc macro, not standalone macros):
 
 - `offset!(expr)`: an `i16` memory offset, the generated name is suffixed with
   `_OFF`
 - `immediate!(expr)`: an `i32` immediate value
+- `signer_seeds!(field)`: expands a [`signer_seeds!`](#signer_seeds) field into
+  `_ADDR_OFF` and `_LEN_OFF` constants per seed, plus an `N_SEEDS` count
+  (requires `#[frame(Type)]`, see below)
 
 <Include rs="interface::memory#constant_group_example" collapsible/>
 
+#### Frame-relative offsets
+
+When annotated with `#[frame(Type)]`, the group enters frame-relative mode.
+In this mode, `offset!(field)` computes a negative offset from the frame
+pointer (`offset_of - size_of`) and asserts 8-byte alignment
+(`BPF_ALIGN_OF_U128`). The group's doc comment defaults to the frame struct's
+doc comment if not explicitly provided. The `signer_seeds!(field)` form is
+only available in frame-relative mode.
+
+<Include rs="interface::market#register_market_stack" collapsible/>
+
 Each group generates:
 
 - A Rust module with public constants (with compile-time range checks)
@@ -101,6 +115,27 @@ The count is accessible in Rust as `RegisterMarketAccounts::LEN`.
 
 <Include rs="interface::market#register_market_accounts" collapsible/>
 
+### `#[frame]`
+
+Attribute macro for stack frame structs. Applies `#[repr(C, align(8))]`
+(aligned to `BPF_ALIGN_OF_U128`) and asserts at compile time that the struct
+fits within one SBPF stack frame (4096 bytes). Also registers field-to-type
+mappings and the struct's doc comment in proc-macro shared state so that
+[`constant_group!`](#constant_group) can auto-discover frame fields and
+derive its header comment.
+
+<Include rs="interface::market#frame_example" collapsible/>
+
+### `signer_seeds!` {#signer_seeds}
+
+Function-like macro that defines a `#[repr(C)]` struct where every field is
+typed as `SolSignerSeed`. Field names are registered in proc-macro shared
+state so that `signer_seeds!(field)` inside a
+[`constant_group!`](#constant_group) can auto-discover all seed fields by
+looking up the parent field's type on the frame struct.
+
+<Include rs="interface::market#signer_seeds_example" collapsible/>
+
 ## Interface
 
 The [`interface`] crate uses the macros to declare all program constants. The

interface/src/lib.rs

@@ -52,4 +52,5 @@ pub const INJECTION_GROUPS: &[&dropset_build::ConstantGroup] = &[
     &market::register_market_accounts::GROUP,
     &memory::data::GROUP,
     &memory::input_buffer::GROUP,
+    &market::register_market_frame::GROUP,
 ];

interface/src/market.rs

@@ -1,8 +1,9 @@
-use crate::cpi_bindings::SolInstruction;
+use crate::cpi_bindings::SolSignerSeed;
 use crate::memory::StackNode;
 use crate::order::Order;
 use crate::seat::Seat;
-use dropset_macros::{instruction_accounts, instruction_data};
+use dropset_macros::{constant_group, frame, instruction_accounts, instruction_data, signer_seeds};
+use pinocchio::Address;
 
 // region: market_header
 #[repr(C, packed)]
@@ -45,8 +46,45 @@ pub enum RegisterMarketAccounts {
 // endregion: register_market_accounts
 
 // region: register_market_stack
-#[repr(C)]
-pub struct RegisterMarketStack {
-    pub instruction: SolInstruction,
+
+// region: frame_example
+#[frame]
+/// Stack frame for REGISTER-MARKET.
+pub struct RegisterMarketFrame {
+    /// For CreateAccount CPI.
+    pub pda_seeds: PdaSignerSeeds,
+    /// From `sol_try_find_program_address`.
+    pub pda: Address,
+    /// From `sol_try_find_program_address`.
+    pub bump: u8,
+}
+// endregion: frame_example
+
+// region: signer_seeds_example
+signer_seeds! {
+    pub struct PdaSignerSeeds {
+        /// Base mint seed.
+        base,
+        /// Quote mint seed.
+        quote,
+        /// Bump seed from `sol_try_find_program_address`.
+        bump,
+    }
 }
+// endregion: signer_seeds_example
+
+constant_group! {
+    #[prefix("RM")]
+    #[inject("market/register")]
+    #[frame(RegisterMarketFrame)]
+    register_market_frame {
+        /// PDA signer seeds.
+        PDA_SEEDS = signer_seeds!(pda_seeds),
+        /// PDA address.
+        PDA = offset!(pda),
+        /// Bump seed.
+        BUMP = offset!(bump),
+    }
+}
+
 // endregion: register_market_stack

macros/src/attrs.rs

@@ -32,6 +32,19 @@ pub fn extract_attr_string(attrs: &[syn::Attribute], name: &str) -> Option<Strin
     None
 }
 
+/// Extract a type path from an attribute like `#[name(Type)]`.
+pub fn extract_attr_path(attrs: &[syn::Attribute], name: &str) -> Option<syn::Path> {
+    for attr in attrs {
+        if attr.path().is_ident(name)
+            && let Meta::List(list) = &attr.meta
+        {
+            let path: syn::Path = syn::parse2(list.tokens.clone()).ok()?;
+            return Some(path);
+        }
+    }
+    None
+}
+
 /// Extract `#[inject("target")]` from attributes.
 pub fn extract_inject_target(attrs: &[syn::Attribute]) -> Option<String> {
     extract_attr_string(attrs, "inject")

macros/src/constant_group/expand/immediate.rs

@@ -0,0 +1,34 @@
+use quote::quote;
+use syn::Ident;
+
+use crate::codegen;
+
+/// Expand `immediate!(expr)` into a usize constant with i32 range check.
+pub fn expand_immediate(
+    base_name: &Ident,
+    asm_name: &str,
+    doc: &str,
+    expr: &syn::Expr,
+) -> (proc_macro2::TokenStream, Ident) {
+    let rust_name = base_name.clone();
+    let meta_ident = codegen::meta_ident(asm_name, base_name.span());
+
+    let meta = codegen::immediate_meta(&meta_ident, asm_name, doc, quote! { #rust_name as i32 });
+
+    let def = quote! {
+        #[doc = #doc]
+        pub const #rust_name: usize = {
+            use super::*;
+            const VALUE: usize = #expr;
+            const _: () = assert!(
+                VALUE <= i32::MAX as usize,
+                "immediate must fit in i32",
+            );
+            VALUE
+        };
+
+        #meta
+    };
+
+    (def, meta_ident)
+}

macros/src/constant_group/expand/mod.rs

@@ -0,0 +1,71 @@
+mod immediate;
+mod offset;
+mod signer_seeds;
+
+use super::ConstantKind;
+use super::parse::ConstantGroupInput;
+use crate::codegen;
+
+/// Expand a parsed `ConstantGroupInput` into a module with constants and a GROUP.
+pub fn expand(input: &ConstantGroupInput) -> proc_macro2::TokenStream {
+    let mut const_defs = Vec::new();
+    let mut meta_idents = Vec::new();
+
+    for c in &input.constants {
+        let doc = &c.doc;
+        let base_name = &c.name;
+
+        let asm_name = match &input.prefix {
+            Some(p) => format!("{}_{}", p, base_name),
+            None => base_name.to_string(),
+        };
+
+        match &c.kind {
+            ConstantKind::Offset { negate, expr } => {
+                let (def, meta) = offset::expand_offset(base_name, &asm_name, doc, *negate, expr);
+                const_defs.push(def);
+                meta_idents.push(meta);
+            }
+            ConstantKind::FrameOffset { fields } => {
+                let frame_ty = input
+                    .frame_type
+                    .as_ref()
+                    .expect("frame_type must be set for FrameOffset");
+                let (def, meta) =
+                    offset::expand_frame_offset(base_name, &asm_name, doc, frame_ty, fields);
+                const_defs.push(def);
+                meta_idents.push(meta);
+            }
+            ConstantKind::SignerSeeds {
+                parent_field,
+                seeds,
+            } => {
+                let frame_ty = input
+                    .frame_type
+                    .as_ref()
+                    .expect("frame_type must be set for SignerSeeds");
+                signer_seeds::expand_signer_seeds(
+                    &asm_name,
+                    frame_ty,
+                    parent_field,
+                    seeds,
+                    &mut const_defs,
+                    &mut meta_idents,
+                );
+            }
+            ConstantKind::Immediate { expr } => {
+                let (def, meta) = immediate::expand_immediate(base_name, &asm_name, doc, expr);
+                const_defs.push(def);
+                meta_idents.push(meta);
+            }
+        };
+    }
+
+    codegen::group_module(
+        &input.mod_name,
+        &input.target,
+        &input.doc,
+        &const_defs,
+        &meta_idents,
+    )
+}

macros/src/constant_group/expand.rs …cros/src/constant_group/expand/offset.rsmacros/src/constant_group/expand.rs renamed to macros/src/constant_group/expand/offset.rs macros/src/constant_group/expand.rs renamed to macros/src/constant_group/expand/offset.rs

@@ -1,43 +1,8 @@
 use quote::quote;
 use syn::Ident;
 
-use super::{ConstantKind, parse::ConstantGroupInput};
 use crate::codegen;
 
-/// Expand a parsed `ConstantGroupInput` into a module with constants and a GROUP.
-pub fn expand(input: &ConstantGroupInput) -> proc_macro2::TokenStream {
-    let mut const_defs = Vec::new();
-    let mut meta_idents = Vec::new();
-
-    for c in &input.constants {
-        let doc = &c.doc;
-        let base_name = &c.name;
-
-        let asm_name = match &input.prefix {
-            Some(p) => format!("{}_{}", p, base_name),
-            None => base_name.to_string(),
-        };
-
-        let (def, meta_ident) = match &c.kind {
-            ConstantKind::Offset { negate, expr } => {
-                expand_offset(base_name, &asm_name, doc, *negate, expr)
-            }
-            ConstantKind::Immediate { expr } => expand_immediate(base_name, &asm_name, doc, expr),
-        };
-
-        const_defs.push(def);
-        meta_idents.push(meta_ident);
-    }
-
-    codegen::group_module(
-        &input.mod_name,
-        &input.target,
-        &input.doc,
-        &const_defs,
-        &meta_idents,
-    )
-}
-
 /// Try to decompose a field-access chain like `Foo.bar.baz` into `(Foo, [bar, baz])`.
 fn try_decompose_field_chain(expr: &syn::Expr) -> Option<(syn::Path, Vec<&syn::Member>)> {
     let mut fields = Vec::new();
@@ -57,7 +22,8 @@ fn try_decompose_field_chain(expr: &syn::Expr) -> Option<(syn::Path, Vec<&syn::M
     }
 }
 
-fn expand_offset(
+/// Expand `offset!(expr)` or `offset!(-expr)` into an i16 offset constant.
+pub fn expand_offset(
     base_name: &Ident,
     asm_name: &str,
     doc: &str,
@@ -100,31 +66,52 @@ fn expand_offset(
     (def, meta_ident)
 }
 
-fn expand_immediate(
-    base_name: &Ident,
+/// Emit a single frame-relative offset constant with i16 range and alignment
+/// assertions. Used by both `expand_frame_offset` and `expand_signer_seeds`.
+pub fn emit_frame_offset_const(
+    rust_name: &Ident,
     asm_name: &str,
     doc: &str,
-    expr: &syn::Expr,
+    frame_ty: &syn::Path,
+    field_chain: proc_macro2::TokenStream,
 ) -> (proc_macro2::TokenStream, Ident) {
-    let rust_name = base_name.clone();
-    let meta_ident = codegen::meta_ident(asm_name, base_name.span());
-
-    let meta = codegen::immediate_meta(&meta_ident, asm_name, doc, quote! { #rust_name as i32 });
+    let meta_ident = codegen::meta_ident(asm_name, rust_name.span());
+    let meta = codegen::offset_meta(&meta_ident, asm_name, doc, rust_name);
 
     let def = quote! {
         #[doc = #doc]
-        pub const #rust_name: usize = {
+        pub const #rust_name: i16 = {
             use super::*;
-            const VALUE: usize = #expr;
+            const VALUE: i64 =
+                core::mem::offset_of!(#frame_ty, #field_chain) as i64
+                    - core::mem::size_of::<#frame_ty>() as i64;
+            const _: () = assert!(
+                VALUE >= i16::MIN as i64 && VALUE <= i16::MAX as i64,
+                "frame offset must fit in i16",
+            );
             const _: () = assert!(
-                VALUE <= i32::MAX as usize,
-                "immediate must fit in i32",
+                VALUE % 8 == 0,
+                "frame offset must be aligned to BPF_ALIGN_OF_U128",
             );
-            VALUE
+            VALUE as i16
         };
 
         #meta
     };
 
     (def, meta_ident)
 }
+
+/// Expand `offset!(field)` inside a `#[frame(Type)]` group.
+pub fn expand_frame_offset(
+    base_name: &Ident,
+    asm_name: &str,
+    doc: &str,
+    frame_ty: &syn::Path,
+    fields: &[syn::Member],
+) -> (proc_macro2::TokenStream, Ident) {
+    let rust_name = Ident::new(&format!("{}_OFF", base_name), base_name.span());
+    let asm_name = format!("{}_OFF", asm_name);
+    let field_chain = quote! { #(#fields).* };
+    emit_frame_offset_const(&rust_name, &asm_name, doc, frame_ty, field_chain)
+}