huff_neo_codegen/

lib.rs

#![doc = include_str!("../README.md")]
#![warn(missing_docs)]
#![warn(unused_extern_crates)]
#![forbid(unsafe_code)]

use crate::irgen::builtin_function::builtin_pad;
use alloy_dyn_abi::{DynSolType, DynSolValue};
use alloy_primitives::{U256, hex};
use huff_neo_utils::ast::huff::*;
use huff_neo_utils::ast::span::AstSpan;
use huff_neo_utils::builtin_eval::{PadDirection, eval_builtin_bytes, eval_event_hash, eval_function_signature};
use huff_neo_utils::bytes_util::str_to_bytes32;
use huff_neo_utils::file::file_source::FileSource;
use huff_neo_utils::scope::ScopeManager;
use huff_neo_utils::{
    abi::*,
    artifact::*,
    bytecode::*,
    bytes_util,
    error::CodegenError,
    opcodes::Opcode,
    prelude::{CodegenErrorKind, EVMVersion, PushValue, Span, deploy_bootstrap, format_even_bytes, pad_n_bytes},
    types::EToken,
};
use std::{
    collections::{BTreeMap, HashMap},
    fs,
    path::Path,
    sync::Arc,
};

mod irgen;
use crate::irgen::prelude::*;

/// Maximum macro recursion depth allowed during compilation.
///
/// This prevents infinite recursion in macro expansion or argument resolution,
/// which can occur with circular macro calls or recursive argument references.
pub(crate) const MAX_MACRO_RECURSION_DEPTH: usize = 100;

/// Maximum number of iterations allowed for the jump relaxation optimization algorithm.
///
/// This limit prevents infinite loops in pathological cases where convergence fails,
/// though typical contracts converge in a few iterations.
const JUMP_RELAXATION_MAX_ITERATIONS: usize = 20;

/// Maximum number of codegen passes of MAIN or the constructor used to converge `__codesize`.
///
/// When MAIN (or a constant referenced by MAIN) uses `__codesize(RUNTIME)`, the runtime size
/// depends on the embedded value, which depends on the runtime size. Likewise, when MAIN and the
/// constructor push each other's size, each size depends on the width of the other's push. Each
/// pass recompiles with the previous pass's measured sizes. PUSH widths only grow (never shrink)
/// across passes, and the size limits cap the values at PUSH3, so convergence takes 2–3 passes.
const CODESIZE_MAX_ITERATIONS: usize = 10;

/// The source span of the first `__argsstart()` call in generated code, if there is one
fn args_start_span(res: &BytecodeRes) -> Option<&AstSpan> {
    res.bytes.iter().find_map(|segment| match &segment.bytes {
        Bytes::ArgsStartPlaceholder(span) => Some(span),
        _ => None,
    })
}

/// Runs codegen passes until the values a pass depends on are the ones it produces, starting
/// from `initial`, and returns the output of the last pass
fn converge_codesizes<T, K: PartialEq>(initial: K, mut pass: impl FnMut(&K) -> Result<(T, K), CodegenError>) -> Result<T, CodegenError> {
    let mut key = initial;
    for _ in 0..CODESIZE_MAX_ITERATIONS {
        let (output, next) = pass(&key)?;
        if next == key {
            return Ok(output);
        }
        key = next;
    }
    Err(CodegenError { kind: CodegenErrorKind::CodesizeNotConverged(CODESIZE_MAX_ITERATIONS), span: AstSpan(vec![]).boxed(), token: None })
}

/// Compiles Huff contracts into EVM bytecode.
///
/// Transforms a Contract AST into executable bytecode, handling macro expansion,
/// label resolution, and bytecode optimization.
///
/// ```rust
/// use huff_neo_codegen::Codegen;
/// let cg = Codegen::new();
/// ```
#[derive(Debug, Default, Clone)]
pub struct Codegen {
    /// The Input AST
    pub ast: Option<Contract>,
    /// A cached codegen output artifact
    pub artifact: Option<Artifact>,
    /// Intermediate main bytecode store
    pub main_bytecode: Option<String>,
    /// Intermediate constructor bytecode store
    pub constructor_bytecode: Option<String>,
}

/// Output of [`Codegen::gen_table_bytecode`].
///
/// Body bytecode (with `__tablestart` placeholders filled), the table bytecode emitted by this call,
/// and the absolute deployment-bytecode offsets at which those tables sit.
#[derive(Debug, Default, Clone)]
pub struct TableBytecodeOutput {
    /// Body bytecode hex string, with all `__tablestart` placeholders replaced.
    pub body: String,
    /// Table bytecode hex string for tables emitted by this call. The caller decides where to place
    /// this in the overall deployment bytecode.
    pub tables: String,
    /// Map of locally-emitted table name to its absolute deployment-bytecode offset.
    pub local_table_offsets: HashMap<String, usize>,
    /// Source map for the body bytecode.
    pub source_map: Vec<SourceMapEntry>,
}

/// Output of [`Codegen::generate_main_bytecode_with_sourcemap`].
///
/// `bytecode` is the runtime bytes (body + appended tables). `table_offsets` maps each
/// runtime-resident table to its offset within the runtime. The constructor finalization step uses
/// `table_offsets` to dedupe any `__tablestart` reference shared with main.
#[derive(Debug, Default, Clone)]
pub struct MainBytecodeOutput {
    /// Full main/runtime bytecode (body + appended tables) as a hex string.
    pub bytecode: String,
    /// Source map for the runtime bytecode body.
    pub source_map: Vec<SourceMapEntry>,
    /// Per-table runtime-relative offsets for tables appended to the runtime body.
    pub table_offsets: HashMap<String, usize>,
}

impl MainBytecodeOutput {
    /// Byte offset within the runtime at which the appended tables begin (equivalently, the length
    /// of the runtime body). When no tables are appended, this equals the full runtime length.
    pub fn body_len(&self) -> usize {
        self.table_offsets.values().min().copied().unwrap_or(self.bytecode.len() / 2)
    }
}

/// Constructor macro bytecode produced by phase 1, prior to table resolution and bootstrap insertion.
///
/// The unresolved [`BytecodeRes`] is forwarded to [`Codegen::assemble_artifact`] (phase 2) which
/// knows the bootstrap size and runtime layout, and finalizes `__tablestart` resolution from there.
#[derive(Debug, Clone)]
pub struct ConstructorMacroBytecode {
    /// Unresolved bytecode result for the constructor macro body.
    pub bytecode_res: BytecodeRes,
    /// `true` when the constructor body already contains a `RETURN` (`0xf3`) opcode, indicating the
    /// user supplies their own deployment bootstrap and the compiler should not emit one.
    pub has_custom_bootstrap: bool,
}

/// Direction in which span-dependent pushes (jump targets, self-referencing `__codesize`) may change
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ResizeMode {
    /// Grow pushes whose value does not fit
    Widen,
    /// Shrink PUSH2 jumps to PUSH1 where the target fits
    Shrink,
}

/// Mapping from segment offsets before resizing span-dependent pushes to the offsets after it
pub type OffsetMapping = BTreeMap<usize, usize>;

/// Bytecode whose span-dependent pushes have stable widths
#[derive(Debug, Clone)]
pub struct ResizedBytecode {
    /// Bytecode with the resized pushes
    pub bytes: BytecodeSegments,
    /// Label positions after resizing
    pub label_indices: LabelIndices,
    /// Mapping from original to new segment offsets
    pub offset_mapping: OffsetMapping,
}

/// Bytecode whose jumps are resolved as far as their labels are known
#[derive(Debug, Clone)]
pub struct FilledJumps {
    /// Bytecode with resolved jumps
    pub bytes: BytecodeSegments,
    /// Jumps whose label is not defined in the bytecode
    pub unmatched_jumps: Vec<Jump>,
    /// Final label positions
    pub label_indices: LabelIndices,
    /// Mapping from original to final segment offsets
    pub offset_mapping: OffsetMapping,
}

/// Translates a segment offset to its position after resizing; offsets without a segment stay put
fn remap_offset(offset_mapping: &OffsetMapping, offset: usize) -> usize {
    offset_mapping.get(&offset).copied().unwrap_or(offset)
}

/// Moves jump table entries to the offsets their jumps have after resizing
fn remap_jump_table(jump_table: &JumpTable, offset_mapping: &OffsetMapping) -> JumpTable {
    jump_table.iter().map(|(&offset, jumps)| (remap_offset(offset_mapping, offset), jumps.clone())).collect()
}

/// Translates a code boundary from original segment offsets to the segment offsets after resizing.
///
/// A boundary is either the start of a segment or the end of the code (`end_offset` after
/// resizing).
fn current_offset(original_offsets: &[usize], current_offsets: &[usize], end_offset: usize, original: usize) -> usize {
    let segment_idx = original_offsets.partition_point(|&offset| offset < original);
    current_offsets.get(segment_idx).copied().unwrap_or(end_offset)
}

impl Codegen {
    /// Public associated function to instantiate a new Codegen instance.
    pub fn new() -> Self {
        Self { ast: None, artifact: None, main_bytecode: None, constructor_bytecode: None }
    }

    /// Compiles the contract's main macro into executable bytecode.
    ///
    /// # Arguments
    ///
    /// * `evm_version` - Target EVM version
    /// * `contract` - The contract to compile
    /// * `alternative_main` - Optional alternative entry point (defaults to "MAIN")
    /// * `relax_jumps` - Enable jump optimization to reduce bytecode size
    pub fn generate_main_bytecode(
        evm_version: &EVMVersion,
        contract: &Contract,
        alternative_main: Option<String>,
        relax_jumps: bool,
    ) -> Result<String, CodegenError> {
        let out = Self::generate_main_bytecode_with_sourcemap(evm_version, contract, alternative_main, relax_jumps)?;
        Ok(out.bytecode)
    }

    /// Compiles the contract's main macro into bytecode with source map.
    ///
    /// Returns the full main bytecode (body + appended tables), its source map, the length of the
    /// body section (offset at which the runtime tables begin), and the per-table runtime offsets.
    /// `build_artifact` uses the body length and table offsets to dedupe constructor-side
    /// `__tablestart` references into the runtime copy.
    pub fn generate_main_bytecode_with_sourcemap(
        evm_version: &EVMVersion,
        contract: &Contract,
        alternative_main: Option<String>,
        relax_jumps: bool,
    ) -> Result<MainBytecodeOutput, CodegenError> {
        // Iterate to a fixed point on `__codesize(RUNTIME)` and on the macro sizes that `__codesize`
        // values measured from another macro depend on. Each pass recompiles MAIN with the
        // previous pass's sizes.
        let mut iter_contract = contract.clone();
        let initial = (iter_contract.runtime_size.unwrap_or(0), None);
        converge_codesizes(initial, |(runtime_size, hints)| {
            iter_contract.runtime_size = Some(*runtime_size);
            let (output, sizes) =
                Self::generate_main_bytecode_inner(evm_version, &iter_contract, alternative_main.as_deref(), relax_jumps, hints.as_ref())?;
            let runtime_size = output.bytecode.len() / 2;
            Ok((output, (runtime_size, sizes)))
        })
    }

    /// Compiles MAIN once, with the macro sizes of the previous pass. Also returns the macro sizes
    /// of this pass when a `__codesize` needed them, so they must reach a fixed point.
    fn generate_main_bytecode_inner(
        evm_version: &EVMVersion,
        contract: &Contract,
        alternative_main: Option<&str>,
        relax_jumps: bool,
        codesize_hints: Option<&BTreeMap<String, usize>>,
    ) -> Result<(MainBytecodeOutput, Option<BTreeMap<String, usize>>), CodegenError> {
        // Update table sizes
        let contract = Self::update_table_size(evm_version, contract)?;

        // If an alternative main is provided, then use it as the compilation target
        let m_macro = Codegen::get_macro_by_name(alternative_main.unwrap_or("MAIN"), &contract)?;

        // Create scope manager and push the main macro
        let mut scope_mgr = ScopeManager::new();
        scope_mgr.codesize_hints = codesize_hints.cloned().unwrap_or_default();
        scope_mgr.push_macro(m_macro, 0);

        // For each MacroInvocation Statement, recurse into bytecode
        let bytecode_res: BytecodeRes = Codegen::macro_to_bytecode(evm_version, m_macro, &contract, &mut scope_mgr, 0, relax_jumps)?;
        Codegen::reject_args_start(&bytecode_res)?;
        let codesizes = scope_mgr.codesize_hints_used.then_some(scope_mgr.codesizes);

        tracing::debug!(target: "codegen", "Generated main bytecode. Appending table bytecode...");

        // Main bytecode is not shifted by a bootstrap and has no upstream dedup map.
        let table_out = Codegen::gen_table_bytecode(&contract, bytecode_res, 0, &HashMap::new())?;
        let bytecode = format!("{}{}", table_out.body, table_out.tables);
        Ok((MainBytecodeOutput { bytecode, source_map: table_out.source_map, table_offsets: table_out.local_table_offsets }, codesizes))
    }

    /// Rejects `__argsstart()` in code that runs as the runtime, such as MAIN or a test, since
    /// constructor arguments are only part of the deployment code.
    pub fn reject_args_start(res: &BytecodeRes) -> Result<(), CodegenError> {
        match args_start_span(res) {
            Some(span) => Err(CodegenError { kind: CodegenErrorKind::ArgsStartOutsideConstructor, span: span.clone_box(), token: None }),
            None => Ok(()),
        }
    }

    /// Generates the constructor section in isolation: macro body with all `__tablestart`
    /// placeholders resolved against locally-emitted tables.
    ///
    /// This standalone form (tables sitting directly after the body) does not include the
    /// deployment-time auto-bootstrap and is **not** the layout that ends up in the deployed
    /// artifact — use [`Codegen::churn`] for the final assembly. This function exists for tools
    /// and tests that want to inspect just the constructor section. `__argsstart()` stays a
    /// placeholder here, as the offset of the arguments depends on the deployment layout.
    pub fn generate_constructor_bytecode(
        evm_version: &EVMVersion,
        contract: &Contract,
        alternative_constructor: Option<String>,
        relax_jumps: bool,
    ) -> Result<(String, bool), CodegenError> {
        let (ctor, contract) = Self::generate_constructor_macro_bytecode(evm_version, contract, alternative_constructor, relax_jumps)?;
        let has_custom_bootstrap = ctor.has_custom_bootstrap;
        let out = Codegen::gen_table_bytecode(&contract, ctor.bytecode_res, 0, &HashMap::new())?;
        Ok((format!("{}{}", out.body, out.tables), has_custom_bootstrap))
    }

    /// Generates constructor macro bytecode without resolving `__tablestart` placeholders.
    ///
    /// This is phase 1 of constructor codegen. Table positions and `__tablestart` resolution depend
    /// on the auto-bootstrap size and the runtime layout, which are only known once `build_artifact`
    /// has both the constructor body and the compiled main bytecode in hand. Phase 2 runs inside
    /// `build_artifact` via [`Codegen::gen_table_bytecode`].
    pub fn generate_constructor_macro_bytecode(
        evm_version: &EVMVersion,
        contract: &Contract,
        alternative_constructor: Option<String>,
        relax_jumps: bool,
    ) -> Result<(ConstructorMacroBytecode, Contract), CodegenError> {
        // Update table sizes
        let contract = Self::update_table_size(evm_version, contract)?;

        // If an alternative constructor macro is provided, then use it as the compilation target
        let constructor_macro = alternative_constructor.unwrap_or_else(|| String::from("CONSTRUCTOR"));

        // Find the constructor macro
        let c_macro = Codegen::get_macro_by_name(&constructor_macro, &contract)?;

        // Iterate to a fixed point on the macro sizes that `__codesize` values measured from another
        // macro depend on, as MAIN does
        let bytecode_res = converge_codesizes(None, |hints: &Option<BTreeMap<String, usize>>| {
            let mut scope_mgr = ScopeManager::new();
            scope_mgr.codesize_hints = hints.clone().unwrap_or_default();
            scope_mgr.push_macro(c_macro, 0);
            let res = Codegen::macro_to_bytecode(evm_version, c_macro, &contract, &mut scope_mgr, 0, relax_jumps)?;
            Ok((res, scope_mgr.codesize_hints_used.then_some(scope_mgr.codesizes)))
        })?;

        // A constructor body containing a RETURN means the user is supplying their own deployment
        // bootstrap; suppress the compiler's auto-bootstrap in that case.
        let has_custom_bootstrap = bytecode_res.bytes.iter().any(|seg| seg.bytes.as_str() == "f3");

        tracing::info!(target: "codegen", "Constructor is self-generating: {}", has_custom_bootstrap);

        Ok((ConstructorMacroBytecode { bytecode_res, has_custom_bootstrap }, contract))
    }

    /// Update the table size in the contract that was not know at the time of parsing
    pub fn update_table_size(_evm_version: &EVMVersion, contract: &Contract) -> Result<Contract, CodegenError> {
        // Update the table size from generated bytecode
        let mut updated = vec![];
        for table_definition in contract.tables.iter() {
            if table_definition.size.is_some() {
                updated.push(table_definition.clone());
                continue;
            }
            // If the size is not provided we need to generate the bytecode to know the size
            let byte_code = Codegen::gen_table_bytecode_builtin(contract, table_definition)?;
            let size = str_to_bytes32(format!("{:02x}", byte_code.len() / 2).as_str());
            let mut table = table_definition.clone();
            table.size = Some(size);
            updated.push(table);
        }
        let mut contract = contract.clone();
        contract.tables = updated;
        Ok(contract)
    }

    /// Helper function to find a macro or generate a CodegenError
    pub(crate) fn get_macro_by_name<'a>(name: &str, contract: &'a Contract) -> Result<&'a MacroDefinition, CodegenError> {
        if let Some(m) = contract.find_macro_by_name(name) {
            Ok(m)
        } else {
            tracing::error!(target: "codegen", "MISSING \"{}\" MACRO!", name);
            Err(CodegenError {
                kind: CodegenErrorKind::MissingMacroDefinition(name.to_string()),
                span: AstSpan(vec![Span { start: 0, end: 0, file: None }]).boxed(),
                token: None,
            })
        }
    }

    /// Resolves a constant to the value `[NAME]` pushes, or `None` for a `__NOOP` constant
    pub fn gen_constant_value(contract: &Contract, name: &str, span: &AstSpan) -> Result<Option<PushValue>, CodegenError> {
        constant_gen(name, contract, span)
    }

    /// Generates bytecode for a builtin function call used for constants, code tables, etc.
    /// Returns a PushValue that can be converted to bytecode with or without opcode
    pub fn gen_builtin_bytecode(contract: &Contract, bf: &BuiltinFunctionCall, span: AstSpan) -> Result<PushValue, CodegenError> {
        match bf.kind {
            BuiltinFunctionKind::FunctionSignature => eval_function_signature(contract, bf),
            BuiltinFunctionKind::Bytes => eval_builtin_bytes(bf),
            BuiltinFunctionKind::EventHash => eval_event_hash(contract, bf),
            BuiltinFunctionKind::LeftPad => builtin_pad(contract, bf, PadDirection::Left),
            BuiltinFunctionKind::RightPad => builtin_pad(contract, bf, PadDirection::Right),
            _ if is_runtime_codesize(bf) => {
                let size = contract.runtime_size.ok_or_else(|| CodegenError {
                    kind: CodegenErrorKind::RuntimeSizeNotComputed,
                    span: span.clone_box(),
                    token: None,
                })?;
                Ok(PushValue::from(U256::from(size).to_be_bytes::<32>()))
            }
            _ => Err(CodegenError {
                kind: CodegenErrorKind::UnsupportedBuiltinFunction(format!("{}", bf.kind)),
                span: span.boxed(),
                token: None,
            }),
        }
    }

    /// Generates bytecode for a code table with builtin functions
    pub fn gen_table_bytecode_builtin(contract: &Contract, table_definition: &TableDefinition) -> Result<String, CodegenError> {
        let mut byte_code = String::new();
        for statement in table_definition.statements.clone() {
            match &statement.ty {
                StatementType::Code(code) => {
                    byte_code = format!("{byte_code}{code}");
                }
                StatementType::BuiltinFunctionCall(bf) => {
                    if is_runtime_codesize(bf) {
                        return Err(CodegenError {
                            kind: CodegenErrorKind::CodesizeRuntimeInCodeTable,
                            span: statement.span.clone_box(),
                            token: None,
                        });
                    }
                    let push_value = Codegen::gen_builtin_bytecode(contract, bf, statement.span.clone())?;
                    // Use full hex for padding functions (always 32 bytes), trimmed for others
                    let hex_data = match bf.kind {
                        BuiltinFunctionKind::LeftPad | BuiltinFunctionKind::RightPad => push_value.to_hex_full(),
                        _ => push_value.to_hex_trimmed(),
                    };
                    byte_code = format!("{byte_code}{hex_data}")
                }
                StatementType::Constant(name) => {
                    let constant = lookup_constant(name, contract, &statement.span)?;
                    let bytes = match &constant.value {
                        ConstVal::Bytes(bytes) => bytes.clone(),
                        ConstVal::Expression(expr) => {
                            let literal = contract.evaluate_constant_expression(expr)?;
                            Bytes::Raw(bytes_util::bytes32_to_hex_string(&literal, false))
                        }
                        ConstVal::BuiltinFunctionCall(bf) => {
                            let push_value = Codegen::gen_builtin_bytecode(contract, bf, statement.span.clone())?;
                            // Use full hex for padding functions (always 32 bytes), trimmed for others
                            let hex_data = match bf.kind {
                                BuiltinFunctionKind::LeftPad | BuiltinFunctionKind::RightPad => push_value.to_hex_full(),
                                _ => push_value.to_hex_trimmed(),
                            };
                            Bytes::Raw(hex_data)
                        }
                        _ => {
                            return Err(CodegenError {
                                kind: CodegenErrorKind::InvalidArguments("Constant must be a hex literal or expression".to_string()),
                                span: statement.span.clone_box(),
                                token: None,
                            });
                        }
                    };
                    byte_code = format!("{byte_code}{}", bytes.as_str());
                }
                _ => {
                    return Err(CodegenError {
                        kind: CodegenErrorKind::UnsupportedStatementType(format!("{}", statement.ty)),
                        span: table_definition.span.clone_box(),
                        token: None,
                    });
                }
            }
        }
        Ok(byte_code)
    }

    /// Appends table bytecode for tables referenced by `res` and fills `__tablestart` placeholders.
    ///
    /// `base_offset` is added to every locally-emitted table's offset before resolution — used by the
    /// constructor pathway to push tables past the auto-bootstrap and main bytecode.
    ///
    /// `external_table_offsets` lets the caller resolve `__tablestart` to a table emitted somewhere
    /// else (e.g. shared with the runtime). Tables found here are not emitted locally; their offset
    /// is used directly when filling placeholders.
    pub fn gen_table_bytecode(
        contract: &Contract,
        res: BytecodeRes,
        base_offset: usize,
        external_table_offsets: &HashMap<String, usize>,
    ) -> Result<TableBytecodeOutput, CodegenError> {
        if !res.unmatched_jumps.is_empty() {
            let labels = res.unmatched_jumps.iter().map(|uj| uj.label.to_string()).collect::<Vec<String>>();
            tracing::error!(
                target: "codegen",
                "Source contains unmatched jump labels \"{}\"",
                labels.join(", ")
            );

            return Err(CodegenError {
                kind: CodegenErrorKind::UnmatchedJumpLabels(labels),
                span: AstSpan(res.unmatched_jumps.iter().flat_map(|uj| uj.span.0.clone()).collect::<Vec<Span>>()).boxed(),
                token: None,
            });
        }

        tracing::info!(target: "codegen", "GENERATING JUMPTABLE BYTECODE");
        tracing::debug!(target: "codegen", "Contract has {} source files", contract.source_files.len());
        tracing::debug!(target: "codegen", "Source map entries: {:?}", contract.source_map);
        tracing::debug!(target: "codegen", "res.bytes.len() = {}", res.bytes.len());
        tracing::debug!(target: "codegen", "res.spans.len() = {}", res.spans.len());

        // Generate source map from bytecode segments and spans
        // Create one entry per instruction for Solidity-compatible source maps
        // The source map is indexed by IC, so we need an entry for every instruction
        let mut source_map = Vec::new();
        let mut program_counter = 0; // PC: byte offset in bytecode

        for (instruction_counter, seg) in res.bytes.iter().enumerate() {
            let instruction_bytecode_length = seg.bytes.len(); // Length in bytes

            // Create source map entry for this instruction
            // Use span information if available, otherwise use zeros (unmapped)
            let (source_start, source_end, file_id) = if let Some(Some((start, end))) = res.spans.get(instruction_counter) {
                // Use the Contract's helper method to map flattened positions to original file positions
                let (file_id, original_start, original_end) = contract.map_flattened_position_to_source(*start, *end);

                tracing::debug!(target: "codegen", "Source map entry: IC={}, flattened_pos={}..{}, mapped_pos={}..{}, file={}, bytes={}, PC={}, bytecode_len={}, source_len={}",
                    instruction_counter, start, end, original_start, original_end, file_id, seg.bytes.as_str(), program_counter, instruction_bytecode_length, original_end - original_start);
                (original_start, original_end, file_id)
            } else {
                // No source mapping for this instruction
                tracing::debug!(target: "codegen", "Source map entry: IC={}, no span, using (0,0,0)", instruction_counter);
                (0, 0, 0)
            };

            source_map.push(SourceMapEntry {
                ic: instruction_counter,                      // IC: instruction index (0, 1, 2, ...)
                pc: program_counter,                          // PC: byte offset in bytecode where this instruction starts
                bytecode_length: instruction_bytecode_length, // Length of this instruction in bytecode (bytes)
                source_start,
                source_length: source_end - source_start, // Length in source code (chars, not bytecode bytes)
                file_id,
            });

            program_counter += instruction_bytecode_length; // Advance PC by the bytecode length
        }

        let mut body = res.bytes.into_iter().map(|seg| seg.bytes.as_str().to_string()).collect::<String>();
        let body_len = body.len() / 2;
        let mut tables_bytecode = String::new();
        let mut local_table_offsets: HashMap<String, usize> = HashMap::new();
        let mut table_offset = body_len + base_offset;

        res.utilized_tables.iter().try_for_each(|jt| {
            // Skip tables that were embedded inline
            if res.embedded_tables.contains_key(&jt.name) {
                tracing::debug!(target: "codegen", "Skipping embedded table \"{}\" from end-placement", jt.name);
                return Ok(());
            }
            // Skip tables resolved via an external (dedup) map
            if external_table_offsets.contains_key(&jt.name) {
                tracing::debug!(target: "codegen", "Resolving table \"{}\" via external offset map", jt.name);
                return Ok(());
            }

            local_table_offsets.insert(jt.name.to_string(), table_offset);

            let Some(table_size) = &jt.size else {
                return Err(CodegenError {
                    kind: CodegenErrorKind::MissingTableSize(jt.name.clone()),
                    span: jt.span.clone_box(),
                    token: None,
                });
            };

            let size = match bytes_util::hex_to_usize(bytes_util::bytes32_to_hex_string(table_size, false).as_str()) {
                Ok(s) => s,
                Err(e) => {
                    tracing::error!(target: "codegen", "Errored converting bytes32 to str. Bytes {:?} with error: {:?}", jt.size, e);
                    return Err(CodegenError {
                        kind: CodegenErrorKind::UsizeConversion(format!("{:?}", jt.size)),
                        span: jt.span.clone_box(),
                        token: None,
                    });
                }
            };
            table_offset += size;

            if jt.kind == TableKind::CodeTable {
                let table_code = Codegen::gen_table_bytecode_builtin(contract, jt)?;

                tables_bytecode.push_str(&table_code);
                return Ok(());
            }

            // For all other tables
            tracing::info!(target: "codegen", "GENERATING BYTECODE FOR TABLE: \"{}\"", jt.name);

            // Packed jump tables store each destination in 2 bytes, regular ones in 32 bytes
            let is_packed = jt.kind == TableKind::JumpTablePacked;
            let mut table_code = String::new();
            jt.statements.iter().try_for_each(|s| {
                match &s.ty {
                    StatementType::LabelCall(label) => {
                        // For jump table label lookups, try to find the label in any scope
                        // Jump tables are generated at the top level but may reference labels in inner scopes
                        let offset = match res.label_indices.get_any(label) {
                            Some(l) => l,
                            None => {
                                tracing::error!(
                                    target: "codegen",
                                    "Definition not found for Jump Table Label: \"{}\"",
                                    label
                                );
                                return Err(CodegenError {
                                    kind: CodegenErrorKind::UnmatchedJumpLabels(vec![label.clone()]),
                                    span: s.span.clone_box(),
                                    token: None,
                                });
                            }
                        };
                        if is_packed && offset > 0xFFFF {
                            return Err(CodegenError {
                                kind: CodegenErrorKind::OffsetExceedsTwoBytes(
                                    format!("label \"{label}\" in packed jump table \"{}\"", jt.name),
                                    offset,
                                ),
                                span: s.span.clone_box(),
                                token: None,
                            });
                        }
                        let hex = format_even_bytes(format!("{offset:02x}"));

                        table_code = format!("{table_code}{}", pad_n_bytes(hex.as_str(), if is_packed { 0x02 } else { 0x20 },));
                    }
                    _ => {
                        return Err(CodegenError { kind: CodegenErrorKind::InvalidMacroStatement, span: jt.span.clone_box(), token: None });
                    }
                }
                Ok(())
            })?;
            tracing::info!(target: "codegen", "SUCCESSFULLY GENERATED BYTECODE FOR TABLE: \"{}\"", jt.name);
            tables_bytecode.push_str(&table_code);
            Ok(())
        })?;

        for jump in res.table_instances.iter() {
            // Resolution order: locally-emitted, then external (dedup) map, then embedded inline.
            let offset_opt = local_table_offsets
                .get(&jump.label)
                .or_else(|| external_table_offsets.get(&jump.label))
                .or_else(|| res.embedded_tables.get(&jump.label));

            if let Some(&o) = offset_opt {
                // `__tablestart` reserves a PUSH2, so the table must start within the first 64 KiB
                if o > 0xFFFF {
                    return Err(CodegenError {
                        kind: CodegenErrorKind::OffsetExceedsTwoBytes(format!("table \"{}\" referenced by __tablestart", jump.label), o),
                        span: jump.span.clone_box(),
                        token: None,
                    });
                }
                let before = &body[0..jump.bytecode_index * 2 + 2];
                let after = &body[jump.bytecode_index * 2 + 6..];

                body = format!("{before}{}{after}", pad_n_bytes(format!("{o:02x}").as_str(), 2));
                tracing::info!(target: "codegen", "FILLED JUMPDEST FOR LABEL \"{}\"", jump.label);
            } else {
                tracing::error!(
                    target: "codegen",
                    "Jump table offset not present for jump label \"{}\"",
                    jump.label
                );
            }
        }

        Ok(TableBytecodeOutput { body, tables: tables_bytecode, local_table_offsets, source_map })
    }

    /// Generates bytecode from a macro definition.
    ///
    /// Expands the macro body into bytecode, resolving labels, arguments, and nested macro calls.
    ///
    /// # Arguments
    ///
    /// * `evm_version` - Target EVM version for opcode compatibility
    /// * `macro_def` - The macro to compile
    /// * `contract` - Contract context for macro and constant lookups
    /// * `scope_mgr` - Call stack for tracking macro invocations and scope
    /// * `offset` - Starting bytecode offset
    /// * `relax_jumps` - Enable jump size optimization
    ///
    /// # Returns
    ///
    /// Bytecode with label indices, unresolved jumps, and source map information.
    #[allow(clippy::too_many_arguments)]
    pub fn macro_to_bytecode<'a>(
        evm_version: &EVMVersion,
        macro_def: &'a MacroDefinition,
        contract: &'a Contract,
        scope_mgr: &mut ScopeManager<'a>,
        mut offset: usize,
        relax_jumps: bool,
    ) -> Result<BytecodeRes, CodegenError> {
        // Safety check to prevent infinite recursion
        if scope_mgr.depth() > MAX_MACRO_RECURSION_DEPTH {
            let macro_chain = scope_mgr.macro_stack().iter().map(|m| m.name.as_str()).collect::<Vec<_>>().join(" -> ");
            return Err(CodegenError {
                kind: CodegenErrorKind::InvalidMacroArgumentType(format!(
                    "Maximum macro recursion depth ({}) exceeded while compiling macro '{}'.\nMacro call chain: {}\nThis likely indicates circular macro calls or infinitely recursive macro expansion.",
                    MAX_MACRO_RECURSION_DEPTH, macro_def.name, macro_chain
                )),
                span: macro_def.span.clone_box(),
                token: None,
            });
        }

        // Get intermediate bytecode representation of the macro definition
        let mut bytes = BytecodeSegments::new();
        let mut spans: Vec<Option<(usize, usize)>> = Vec::default();
        let ir_bytes = macro_def.to_irbytecode(evm_version)?.0;

        // Define outer loop variables
        let mut jump_table = JumpTable::new();
        let mut label_indices = LabelIndices::new();
        let mut table_instances = Jumps::new();
        let mut utilized_tables: Vec<TableDefinition> = Vec::new();
        let mut embedded_tables = std::collections::BTreeMap::new();
        let start_offset = offset;

        // Loop through all intermediate bytecode representations generated from the AST
        for ir_byte in ir_bytes.iter() {
            let starting_offset = offset;

            // Extract span information if available
            // Convert from original file coordinates to flattened coordinates
            let span_info = if !ir_byte.span.0.is_empty() {
                ir_byte.span.0.first().and_then(|s| {
                    if s.start != 0 || s.end != 0 {
                        // Convert original span to flattened coordinates
                        contract.map_original_span_to_flattened(s)
                    } else {
                        None
                    }
                })
            } else {
                None
            };

            match &ir_byte.ty {
                IRByteType::Bytes(b) => {
                    offset += b.len(); // len() now returns byte count directly
                    bytes.push_with_offset(starting_offset, b.to_owned());
                    spans.push(span_info);
                }
                IRByteType::Constant(name) => {
                    if let Some(push_value) = constant_gen(name, contract, ir_byte.span)? {
                        let push_bytes = push_value.to_hex_with_opcode(evm_version);
                        offset += push_bytes.len() / 2;
                        tracing::debug!(target: "codegen", "OFFSET: {}, PUSH BYTES: {:?}", offset, push_bytes);
                        bytes.push_with_offset(starting_offset, Bytes::Raw(push_bytes));
                        spans.push(span_info);
                    } // __NOOP generates no bytecode
                }
                IRByteType::Statement(s) => {
                    let (push_bytes, mut push_spans) = statement_gen(
                        evm_version,
                        s,
                        contract,
                        macro_def,
                        scope_mgr,
                        &mut offset,
                        &mut jump_table,
                        &mut label_indices,
                        &mut table_instances,
                        &mut utilized_tables,
                        &mut embedded_tables,
                        starting_offset,
                        relax_jumps,
                    )?;
                    // Use the spans from statement_gen (which preserves nested macro spans)
                    // instead of duplicating the parent's span
                    spans.append(&mut push_spans);
                    bytes.extend(push_bytes);
                }
                IRByteType::ArgCall(parent_macro_name, arg_name) => {
                    let bytes_before = bytes.len();
                    // Bubble up arg call by looking through the previous scopes.
                    // Once the arg value is found, add it to `bytes`
                    bubble_arg_call(
                        evm_version,
                        parent_macro_name.to_owned(),
                        arg_name.to_owned(),
                        &mut bytes,
                        macro_def,
                        contract,
                        scope_mgr,
                        &mut offset,
                        &mut jump_table,
                        &mut table_instances,
                        &mut utilized_tables,
                        ir_byte.span,
                        relax_jumps,
                    )?;
                    // Add span for each byte segment added by bubble_arg_call
                    let bytes_added = bytes.len() - bytes_before;
                    for _ in 0..bytes_added {
                        spans.push(span_info);
                    }
                }
            }
        }

        // Note: We don't pop from scope_mgr here because it's either:
        // 1. Done by the caller after the recursive call returns (for inline macros)
        // 2. Done at the end of this function (for top-level or function generation)

        // Add functions (outlined macros) to the end of the bytecode if the scope length == 1
        // (i.e., we're at the top level of recursion)
        let is_top_level = scope_mgr.depth() == 1;
        if is_top_level {
            let bytes_before = bytes.len();
            // A test may end by running off its code, which must stop instead of entering the
            // functions and code tables appended after it
            let has_appended_code = contract.macros.values().any(|m| m.outlined) || !utilized_tables.is_empty();
            if macro_def.test && has_appended_code {
                bytes.push_with_offset(offset, Bytes::Raw(Opcode::Stop.to_string()));
                offset += 1;
            }
            bytes = Codegen::append_functions(
                evm_version,
                contract,
                scope_mgr,
                &mut offset,
                &mut jump_table,
                &mut label_indices,
                &mut table_instances,
                bytes,
            )?;
            // Add empty spans for appended functions (these don't have direct source mapping)
            let bytes_added = bytes.len() - bytes_before;
            for _ in 0..bytes_added {
                spans.push(None);
            }
        } else {
            // If the scope length is > 1, we're processing a child macro. Since we're done
            // with it, it can be popped.
            scope_mgr.pop_macro();
        }

        // `__codesize` self-references of this macro measure this invocation, which is complete now
        bytes.measure_circular_codesize(&macro_def.name, start_offset, start_offset + bytes.total_byte_size());

        // Fill JUMPDEST placeholders. Resizing a jump moves all code after it, so jumps are resized
        // and resolved once by the top-level macro, when all code is laid out. Nested macros only
        // settle the width of their own `__codesize` self-references and pass their jumps up.
        let segment_count = bytes.len();
        let FilledJumps { mut bytes, unmatched_jumps, label_indices, offset_mapping } = if is_top_level {
            Codegen::fill_unmatched(bytes, &jump_table, &label_indices, relax_jumps)?
        } else {
            let widened = Codegen::widen_jump_offsets(bytes, &JumpTable::new(), &label_indices);
            let unmatched_jumps = remap_jump_table(&jump_table, &widened.offset_mapping)
                .into_iter()
                .flat_map(|(offset, jumps)| jumps.into_iter().map(move |jump| Jump { bytecode_index: offset, ..jump }))
                .collect();
            FilledJumps {
                bytes: widened.bytes,
                unmatched_jumps,
                label_indices: widened.label_indices,
                offset_mapping: widened.offset_mapping,
            }
        };
        // `__tablestart` placeholders are filled later by position, so move them with the resized code
        for table_instance in table_instances.iter_mut() {
            table_instance.bytecode_index = remap_offset(&offset_mapping, table_instance.bytecode_index);
        }

        // Adjust spans if bytes changed
        if bytes.len() != segment_count {
            // If the segment count changed, we need to rebuild the spans vector
            // For now, just ensure it has the same length
            while spans.len() < bytes.len() {
                spans.push(None);
            }
        }

        // Fill in `__codesize` self-references. Values inside nested macros are provisional: the
        // top-level macro fills them again after resizing all jumps.
        let growth = bytes.resolve_circular_codesize();
        debug_assert_eq!(growth, 0, "circular codesize placeholders must be widened before jump resolution");
        scope_mgr.codesizes.insert(macro_def.name.clone(), bytes.total_byte_size());

        tracing::info!(target: "codegen", "BytecodeRes created with {} bytes and {} spans", bytes.len(), spans.len());
        Ok(BytecodeRes { bytes, spans, label_indices, unmatched_jumps, table_instances, utilized_tables, embedded_tables })
    }

    /// Shrinks PUSH2 jumps to PUSH1 where the target fits in one byte.
    ///
    /// Jump relaxation for span-dependent instructions ("start big and shrink"), an iterative
    /// variant of the technique described in Thomas G. Szymanski, "Assembling Code for Machines
    /// with Span-Dependent Instructions", CACM 21(4), 1978, p. 300-308.
    /// See also: <https://www.complang.tuwien.ac.at/anton/assembling-span-dependent.html>
    ///
    /// Shrinking only moves code backwards, so it never pushes a target out of range of a jump that
    /// was widened before.
    ///
    /// Returns the relaxed bytecode, updated label indices, and a mapping from original to new
    /// segment offsets.
    pub fn relax_jump_offsets(bytes: BytecodeSegments, jump_table: &JumpTable, label_indices: &LabelIndices) -> ResizedBytecode {
        Self::resize_span_dependent_pushes(bytes, jump_table, label_indices, ResizeMode::Shrink)
    }

    /// Widens jumps and self-referencing `__codesize` pushes whose value no longer fits.
    ///
    /// Jumps start as PUSH2 and self-referencing `__codesize` pushes as PUSH1. Code beyond 64 KiB
    /// (possible in initcode from Amsterdam) needs PUSH3 targets, and a macro's own size can need a
    /// wider push than first assumed. Widening moves all following code, so this repeats until no
    /// push changes ("start small and grow"); it always terminates because pushes only grow.
    ///
    /// Returns the widened bytecode, updated label indices, and a mapping from original to new
    /// segment offsets.
    pub fn widen_jump_offsets(bytes: BytecodeSegments, jump_table: &JumpTable, label_indices: &LabelIndices) -> ResizedBytecode {
        Self::resize_span_dependent_pushes(bytes, jump_table, label_indices, ResizeMode::Widen)
    }

    /// Repeatedly resizes span-dependent pushes until their widths are stable.
    ///
    /// After every round that changed a width, segment offsets and label positions are recomputed,
    /// since a different width moves all code that follows.
    fn resize_span_dependent_pushes(
        mut bytes: BytecodeSegments,
        jump_table: &JumpTable,
        label_indices: &LabelIndices,
        mode: ResizeMode,
    ) -> ResizedBytecode {
        // The jump table is keyed by the original segment offsets. Code of a nested macro does not
        // start at 0, so recomputed offsets are relative to its first segment.
        let original_offsets: Vec<usize> = bytes.iter().map(|segment| segment.offset).collect();
        let base_offset = original_offsets.first().copied().unwrap_or(0);
        let mut current_label_indices = label_indices.clone();
        let mut cumulative_offset_mapping: OffsetMapping = original_offsets.iter().map(|&o| (o, o)).collect();
        // Shrinking is an optimization and may stop early; widening must reach a fixed point and
        // widens at least one push per round, so it is bounded by the number of segments
        let max_iterations = match mode {
            ResizeMode::Shrink => JUMP_RELAXATION_MAX_ITERATIONS,
            ResizeMode::Widen => bytes.len() + 1,
        };

        let mut iteration = 0;
        let mut changed = true;
        while changed && iteration < max_iterations {
            changed = false;
            iteration += 1;

            let offsets: Vec<usize> = bytes.calculate_offsets().into_iter().map(|offset| base_offset + offset).collect();
            let total_length = bytes.total_byte_size();
            let end_offset = base_offset + total_length;

            for (segment_idx, segment) in bytes.iter_mut().enumerate() {
                match segment.bytes {
                    Bytes::JumpPlaceholder(ref mut placeholder) => {
                        let Some(jump) = jump_table.get(&original_offsets[segment_idx]).and_then(|jumps| jumps.first()) else {
                            continue;
                        };
                        // Unknown labels are reported by `fill_unmatched` after resizing
                        let Ok(Some(target_offset)) = current_label_indices.get(&placeholder.label, &jump.scope_id) else {
                            continue;
                        };
                        let new_opcode = match mode {
                            ResizeMode::Widen if !placeholder.push_opcode.can_represent(target_offset) => {
                                Some(PushOpcode::optimal_for(target_offset))
                            }
                            // A forward target at exactly 0x100 moves to 0xff once this jump shrinks
                            ResizeMode::Shrink
                                if placeholder.push_opcode == PushOpcode::Push2
                                    && (target_offset <= 0xFF || (target_offset == 0x100 && target_offset > offsets[segment_idx])) =>
                            {
                                Some(PushOpcode::Push1)
                            }
                            _ => None,
                        };
                        if let Some(new_opcode) = new_opcode {
                            tracing::debug!(
                                target: "codegen",
                                "Resizing jump to '{}' at offset {} from {:?} to {:?} (target={})",
                                placeholder.label,
                                offsets[segment_idx],
                                placeholder.push_opcode,
                                new_opcode,
                                target_offset
                            );
                            placeholder.push_opcode = new_opcode;
                            changed = true;
                        }
                    }
                    Bytes::CircularCodesizePlaceholder(ref mut placeholder) if mode == ResizeMode::Widen => {
                        let size = placeholder.size(
                            |(start, end)| {
                                current_offset(&original_offsets, &offsets, end_offset, end)
                                    - current_offset(&original_offsets, &offsets, end_offset, start)
                            },
                            total_length,
                        );
                        if !placeholder.push_opcode.can_represent(size) {
                            placeholder.push_opcode = PushOpcode::optimal_for(size);
                            changed = true;
                        }
                    }
                    _ => {}
                }
            }

            if changed {
                // Recalculate all positions based on current segment sizes
                let new_offsets: Vec<usize> = bytes.calculate_offsets().into_iter().map(|offset| base_offset + offset).collect();
                let offset_mapping: OffsetMapping =
                    bytes.iter().zip(&new_offsets).map(|(segment, &new_offset)| (segment.offset, new_offset)).collect();

                for final_offset in cumulative_offset_mapping.values_mut() {
                    *final_offset = remap_offset(&offset_mapping, *final_offset);
                }
                current_label_indices.update_offsets(&offset_mapping);
                for (segment, new_offset) in bytes.iter_mut().zip(new_offsets) {
                    segment.offset = new_offset;
                }
            }
        }

        if changed {
            tracing::warn!(target: "codegen", "{:?} of span-dependent pushes hit max iterations ({})", mode, max_iterations);
        } else {
            tracing::info!(target: "codegen", "{:?} of span-dependent pushes converged after {} iterations", mode, iteration);
        }

        // Move the code measured by `__codesize` self-references along with the resized code
        let final_offsets: Vec<usize> = bytes.iter().map(|segment| segment.offset).collect();
        let final_end_offset = base_offset + bytes.total_byte_size();
        for segment in bytes.iter_mut() {
            if let Bytes::CircularCodesizePlaceholder(ref mut placeholder) = segment.bytes
                && let Some((start, end)) = placeholder.measured_range
            {
                placeholder.measured_range = Some((
                    current_offset(&original_offsets, &final_offsets, final_end_offset, start),
                    current_offset(&original_offsets, &final_offsets, final_end_offset, end),
                ));
            }
        }

        ResizedBytecode { bytes, label_indices: current_label_indices, offset_mapping: cumulative_offset_mapping }
    }

    /// Resolves jump placeholders to their target offsets with optional size optimization.
    ///
    /// Replaces jump placeholders with actual bytecode offsets by looking up labels in the
    /// label index. Jumps whose target does not fit in PUSH2 are widened first; when
    /// `relax_jumps` is enabled, PUSH2 jumps are then shrunk to PUSH1 where targets fit within a
    /// single byte (0-255).
    ///
    /// ## Arguments
    ///
    /// * `bytes` - Bytecode segments with jump placeholders
    /// * `jump_table` - Jump metadata indexed by bytecode offset
    /// * `label_indices` - Scoped label positions
    /// * `relax_jumps` - Enable jump size optimization
    ///
    /// ## Returns
    ///
    /// Returns resolved bytecode, any unmatched jumps, the final label positions, and a mapping
    /// from original to final segment offsets, or an error for label conflicts or invalid jump
    /// targets.
    pub fn fill_unmatched(
        bytes: BytecodeSegments,
        jump_table: &JumpTable,
        label_indices: &LabelIndices,
        relax_jumps: bool,
    ) -> Result<FilledJumps, CodegenError> {
        // Widen pushes that do not fit first, then optionally shrink jumps to PUSH1. Shrinking only
        // moves code backwards, so widened jumps keep fitting.
        let ResizedBytecode { mut bytes, mut label_indices, mut offset_mapping } =
            Self::widen_jump_offsets(bytes, jump_table, label_indices);
        if relax_jumps {
            let relaxed = Self::relax_jump_offsets(bytes, &remap_jump_table(jump_table, &offset_mapping), &label_indices);
            bytes = relaxed.bytes;
            label_indices = relaxed.label_indices;
            for final_offset in offset_mapping.values_mut() {
                *final_offset = remap_offset(&relaxed.offset_mapping, *final_offset);
            }
        }

        // Resolve all jumps using the new typed approach
        let resized_jump_table = remap_jump_table(jump_table, &offset_mapping);
        let unmatched_jumps = bytes.resolve_jumps(&resized_jump_table, &label_indices).map_err(|label_error| {
            // Match on the typed error variants
            match label_error {
                LabelError::DuplicateLabelAcrossSiblings(label_name) => {
                    // Find the first jump to get its span
                    let span = jump_table
                        .values()
                        .flat_map(|jumps| jumps.iter())
                        .find(|jump| jump.label == label_name)
                        .map(|jump| jump.span.clone_box())
                        .unwrap_or_else(|| Box::new(AstSpan::default()));

                    CodegenError { kind: CodegenErrorKind::DuplicateLabelAcrossSiblings(label_name), span, token: None }
                }
                LabelError::JumpTargetTooLarge { label, target, opcode } => {
                    // Find the jump to get its span
                    let span = jump_table
                        .values()
                        .flat_map(|jumps| jumps.iter())
                        .find(|jump| jump.label == label)
                        .map(|jump| jump.span.clone_box())
                        .unwrap_or_else(|| Box::new(AstSpan::default()));

                    CodegenError { kind: CodegenErrorKind::JumpTargetTooLarge { label, target, opcode }, span, token: None }
                }
                LabelError::DuplicateLabelInScope(label_name) => {
                    // This shouldn't happen during jump resolution, but handle it anyway
                    let span = jump_table
                        .values()
                        .flat_map(|jumps| jumps.iter())
                        .find(|jump| jump.label == label_name)
                        .map(|jump| jump.span.clone_box())
                        .unwrap_or_else(|| Box::new(AstSpan::default()));

                    CodegenError { kind: CodegenErrorKind::DuplicateLabelInScope(label_name), span, token: None }
                }
            }
        })?;

        // Log unmatched jumps
        for jump in &unmatched_jumps {
            tracing::warn!(
                target: "codegen",
                "UNMATCHED JUMP LABEL \"{}\" AT BYTECODE INDEX {} (scope_id={:?})",
                jump.label, jump.bytecode_index, jump.scope_id
            );
        }

        // Validate __ASSERT_PC placeholders using post-relaxation offsets
        // This must happen AFTER jump relaxation to ensure correct offset validation
        // The segment.offset has been updated by relaxation, so we can use it directly
        let offsets = bytes.calculate_offsets();
        for (idx, segment) in bytes.iter().enumerate() {
            if let Bytes::AssertPcPlaceholder(data) = &segment.bytes {
                // Use the calculated offset which accounts for all relaxation
                let actual_offset = offsets[idx];

                if actual_offset != data.expected_offset {
                    tracing::error!(
                        target: "codegen",
                        "PC assertion failed: expected 0x{:x}, got 0x{:x}",
                        data.expected_offset,
                        actual_offset
                    );
                    return Err(CodegenError {
                        kind: CodegenErrorKind::AssertPcFailed(data.expected_offset, actual_offset),
                        span: data.span.clone_box(),
                        token: None,
                    });
                }

                tracing::debug!(
                    target: "codegen",
                    "PC assertion passed: position is 0x{:x} as expected (after relaxation)",
                    actual_offset
                );
            }
        }

        // Filter out __ASSERT_PC placeholders since they don't generate bytecode
        let mut filtered_bytes = BytecodeSegments::new();
        for segment in bytes.iter() {
            if !matches!(segment.bytes, Bytes::AssertPcPlaceholder(_)) {
                filtered_bytes.push(segment.clone());
            }
        }

        Ok(FilledJumps { bytes: filtered_bytes, unmatched_jumps, label_indices, offset_mapping })
    }

    /// Helper associated function to append functions to the end of the bytecode.
    ///
    /// ## Overview
    ///
    /// Iterates over the contract's functions, generates their bytecode, fills unmatched jumps &
    /// label indices, and appends the functions' bytecode to the end of the contract's bytecode.
    ///
    /// On success, passes ownership of `bytes` back to the caller.
    /// On failure, returns a CodegenError.
    #[allow(clippy::too_many_arguments)]
    pub fn append_functions<'a>(
        evm_version: &EVMVersion,
        contract: &'a Contract,
        scope_mgr: &mut ScopeManager<'a>,
        offset: &mut usize,
        jump_table: &mut JumpTable,
        label_indices: &mut LabelIndices,
        table_instances: &mut Jumps,
        mut bytes: BytecodeSegments,
    ) -> Result<BytecodeSegments, CodegenError> {
        // First pass: Pre-register all function goto_ labels at their future offsets
        // This allows nested function calls to resolve correctly
        let functions: Vec<_> = contract.macros.values().filter(|m| m.outlined).collect();
        let mut current_offset = *offset;
        let goto_scope_id = huff_neo_utils::scope::ScopeId::new(vec![], 0);

        // We need to calculate offsets without actually generating bytecode yet
        // Store the calculated offset for each function
        let mut function_offsets: Vec<(&MacroDefinition, usize)> = Vec::new();

        for macro_def in &functions {
            // Register the goto_ label at the current offset
            if let Err(err_msg) = label_indices.insert(format!("goto_{}", macro_def.name.clone()), current_offset, &goto_scope_id) {
                // This shouldn't happen for auto-generated goto_ labels - indicates a compiler bug
                tracing::error!(target: "codegen", "INTERNAL ERROR: Duplicate goto_ label for function '{}': {}", macro_def.name, err_msg);
                return Err(CodegenError {
                    kind: CodegenErrorKind::DuplicateLabelInScope(format!("goto_{}", macro_def.name)),
                    span: macro_def.span.clone_box(),
                    token: None,
                });
            }

            function_offsets.push((macro_def, current_offset));

            // Estimate the size of this function for offset calculation
            // We'll need to generate it to get the exact size, but for now we need a placeholder
            // This is a chicken-and-egg problem: we need offsets to generate code, but need code to know offsets
            // Solution: Generate into a temporary buffer first
            scope_mgr.push_macro(macro_def, current_offset);
            let temp_res = Codegen::macro_to_bytecode(evm_version, macro_def, contract, scope_mgr, current_offset + 1, false)?;
            let macro_code_len = temp_res.bytes.iter().map(|seg| seg.bytes.len()).sum::<usize>();
            let stack_swaps_len = macro_def.returns;
            current_offset += macro_code_len + stack_swaps_len + 2; // JUMPDEST + MACRO_CODE_LEN + stack_swaps.len() + JUMP
            // Note: macro_to_bytecode already popped the macro (depth > 1)
        }

        // Second pass: Actually generate the function bytecode
        // Now all goto_ labels are registered, so nested calls will resolve
        for (macro_def, func_offset) in function_offsets {
            // Push the function to the scope
            scope_mgr.push_macro(macro_def, func_offset);

            // Add 1 to starting offset to account for the JUMPDEST opcode
            let mut res = Codegen::macro_to_bytecode(evm_version, macro_def, contract, scope_mgr, func_offset + 1, false)?;

            for j in res.unmatched_jumps.iter_mut() {
                let new_index = j.bytecode_index;
                j.bytecode_index = 0;
                let mut new_jumps = if let Some(jumps) = jump_table.get(&new_index) { jumps.clone() } else { vec![] };
                new_jumps.push(j.clone());
                jump_table.insert(new_index, new_jumps);
            }
            table_instances.extend(res.table_instances);
            label_indices.extend(res.label_indices);

            let macro_code_len = res.bytes.iter().map(|seg| seg.bytes.len()).sum::<usize>();

            // Get necessary swap ops to reorder stack
            // PC of the return jumpdest should be above the function's outputs on the stack
            let stack_swaps = (0..macro_def.returns).map(|i| format!("{:02x}", 0x90 + i)).collect::<Vec<_>>();

            // Insert JUMPDEST, stack swaps, and final JUMP back to the location of invocation.
            bytes.push_with_offset(func_offset, Bytes::Raw(Opcode::Jumpdest.to_string()));
            res.bytes.push_with_offset(func_offset + macro_code_len + 1, Bytes::Raw(format!("{}{}", stack_swaps.join(""), Opcode::Jump)));
            bytes.extend(res.bytes);

            // Note: The function is already popped by macro_to_bytecode at the end
            // because depth > 1 when generating functions. We should NOT pop again here.
        }

        *offset = current_offset;
        Ok(bytes)
    }

    /// Back-compat shim for assembly from raw bytecode strings.
    ///
    /// Synthesizes [`MainBytecodeOutput`] and [`ConstructorMacroBytecode`] from raw hex strings and
    /// forwards to [`Codegen::assemble_artifact`]. Use this when you have pre-baked main and
    /// constructor bytecode (e.g. existing snapshot tests) and do not need the table-dedup pathway.
    ///
    /// Behaves identically to the structured API for inputs that contain no tables.
    #[allow(clippy::too_many_arguments)]
    pub fn churn(
        &mut self,
        evm_version: &EVMVersion,
        file: Arc<FileSource>,
        args: Vec<DynSolValue>,
        main_bytecode: &str,
        constructor_bytecode: &str,
        has_custom_bootstrap: bool,
        main_source_map: Option<Vec<SourceMapEntry>>,
        constructor_source_map: Option<Vec<SourceMapEntry>>,
        no_size_limit: bool,
    ) -> Result<Artifact, CodegenError> {
        let main = MainBytecodeOutput {
            bytecode: main_bytecode.to_string(),
            source_map: main_source_map.unwrap_or_default(),
            table_offsets: HashMap::new(),
        };
        let constructor = if constructor_bytecode.is_empty() {
            None
        } else {
            let mut bytes = BytecodeSegments::new();
            bytes.push_with_offset(0, Bytes::Raw(constructor_bytecode.to_string()));
            let bytecode_res = BytecodeRes { bytes, ..Default::default() };
            Some(ConstructorMacroBytecode { bytecode_res, has_custom_bootstrap })
        };
        // The shim does not have a fully-populated Contract — but with no utilized tables in the
        // synthesized constructor BytecodeRes, gen_table_bytecode never inspects table definitions.
        let contract = Contract::default();
        let mut artifact = self.assemble_artifact(evm_version, file, &contract, args, main, constructor, no_size_limit)?;
        // Preserve the caller-supplied constructor source map (the shim doesn't generate one).
        artifact.constructor_map = constructor_source_map;
        Ok(artifact)
    }

    /// Generate a codegen artifact.
    ///
    /// Deployment bytecode is laid out as:
    ///   `[ctor_body][bootstrap?][main_bytecode][ctor_only_tables][constructor_args]`
    ///
    /// A `__tablestart(T)` reference inside the constructor is resolved against a runtime-resident
    /// copy of `T` when `main` already emits one (no duplicate); otherwise the table is appended
    /// once to the deployment tail and the constructor's reference points there.
    ///
    /// # Arguments
    ///
    /// * `evm_version` — target EVM version; selects the runtime and initcode size limits.
    /// * `contract` — contract AST with table sizes populated by `update_table_size`. Used to read
    ///   table definitions during constructor table finalization.
    /// * `args` — encoded constructor arguments, appended at the very end of the deployment bytes.
    /// * `main` — main/runtime bytecode plus its body length and per-table offsets within the runtime.
    /// * `constructor` — phase-1 constructor macro output; `None` when the contract has no
    ///   `CONSTRUCTOR` macro (deployment becomes just `bootstrap + main`).
    /// * `no_size_limit` — skip the runtime and initcode size checks.
    #[allow(clippy::too_many_arguments)]
    pub fn assemble_artifact(
        &mut self,
        evm_version: &EVMVersion,
        file: Arc<FileSource>,
        contract: &Contract,
        args: Vec<DynSolValue>,
        main: MainBytecodeOutput,
        constructor: Option<ConstructorMacroBytecode>,
        no_size_limit: bool,
    ) -> Result<Artifact, CodegenError> {
        let artifact: &mut Artifact = if let Some(art) = &mut self.artifact {
            art
        } else {
            self.artifact = Some(Artifact::default());
            self.artifact.as_mut().unwrap()
        };

        let MainBytecodeOutput { bytecode: main_bytecode, source_map: main_source_map, table_offsets: main_table_offsets } = main;

        let contract_length = main_bytecode.len() / 2;

        // Check the runtime size limit (EIP-170, raised by EIP-7954 from Amsterdam)
        if !no_size_limit && contract_length > evm_version.max_code_size() {
            return Err(CodegenError {
                kind: CodegenErrorKind::ContractSizeLimitExceeded(contract_length, evm_version.max_code_size()),
                span: AstSpan(vec![Span { start: 0, end: 0, file: Some(file) }]).boxed(),
                token: None,
            });
        }

        // Compute the constructor body length and bootstrap size first, since the bootstrap size
        // depends on the body length but not on constructor-only table sizes (under the new layout
        // where constructor-only tables sit past main).
        let (ctor_body_len, has_custom_bootstrap) = match &constructor {
            // `Bytes::len()` returns size in bytes (not hex chars), so no further division needed.
            Some(c) => (c.bytecode_res.bytes.iter().map(|seg| seg.bytes.len()).sum::<usize>(), c.has_custom_bootstrap),
            None => (0, false),
        };

        // Bootstrap size depends only on body lengths (not table sizes).
        // Suppressed entirely when the user supplies their own bootstrap (constructor contains RETURN).
        let (bootstrap_code, effective_bootstrap_size) =
            if has_custom_bootstrap { (String::default(), 0) } else { deploy_bootstrap(contract_length, ctor_body_len) };

        // Finalize constructor table resolution now that the layout is known.
        // Constructor-only tables sit past main_bytecode in the deployment tail.
        // Shared tables resolve into the runtime-resident copy at runtime_start + main_offset.
        let runtime_start_in_deployment = ctor_body_len + effective_bootstrap_size;
        // gen_table_bytecode internally adds body_len; only shift by what comes between body end
        // and the constructor-only tables (bootstrap + main_bytecode).
        let ctor_tables_base_offset = effective_bootstrap_size + contract_length;
        let external_table_offsets: HashMap<String, usize> =
            main_table_offsets.iter().map(|(name, off)| (name.clone(), runtime_start_in_deployment + off)).collect();

        let args_start_span = constructor.as_ref().and_then(|c| args_start_span(&c.bytecode_res)).cloned();
        let (mut constructor_body, ctor_only_tables, constructor_source_map) = match constructor {
            Some(c) => {
                let out = Codegen::gen_table_bytecode(contract, c.bytecode_res, ctor_tables_base_offset, &external_table_offsets)?;
                (out.body, out.tables, Some(out.source_map))
            }
            None => (String::new(), String::new(), None),
        };

        // `__argsstart()` in the constructor pushes the offset the arguments are appended at
        let args_start = runtime_start_in_deployment + contract_length + ctor_only_tables.len() / 2;
        if constructor_body.contains(ARGS_START_PLACEHOLDER) {
            if args_start > 0xFFFF {
                return Err(CodegenError {
                    kind: CodegenErrorKind::OffsetExceedsTwoBytes("constructor arguments for __argsstart()".to_string(), args_start),
                    span: args_start_span.unwrap_or_else(|| AstSpan(vec![Span { start: 0, end: 0, file: Some(file) }])).boxed(),
                    token: None,
                });
            }
            constructor_body = constructor_body.replace(ARGS_START_PLACEHOLDER, &format!("{}{args_start:04x}", Opcode::Push2));
        }

        let constructor_args = Codegen::abi_encode_constructor_args(args);
        let deployment_bytecode = format!("{constructor_body}{bootstrap_code}{main_bytecode}{ctor_only_tables}{constructor_args}");

        // Check the initcode size limit (EIP-3860, raised by EIP-7954 from Amsterdam)
        let initcode_length = deployment_bytecode.len() / 2;
        if !no_size_limit && initcode_length > evm_version.max_initcode_size() {
            return Err(CodegenError {
                kind: CodegenErrorKind::InitcodeSizeLimitExceeded(initcode_length, evm_version.max_initcode_size()),
                span: AstSpan(vec![Span { start: 0, end: 0, file: Some(file) }]).boxed(),
                token: None,
            });
        }

        artifact.bytecode = deployment_bytecode.to_lowercase();
        artifact.runtime = main_bytecode.to_lowercase();
        artifact.has_custom_bootstrap = has_custom_bootstrap;
        artifact.file = file;

        // Set source maps if provided
        artifact.runtime_map = Some(main_source_map);
        artifact.constructor_map = constructor_source_map;

        Ok(artifact.clone())
    }

    /// Reads constructor arguments given as text. With the declared constructor parameter types,
    /// each argument is read as its type and the count must match; otherwise each type is guessed
    /// from the text. Without arguments nothing is appended, so the deployer can append them later.
    pub fn encode_constructor_args(args: &[String], types: Option<&[String]>) -> Result<Vec<DynSolValue>, CodegenError> {
        let invalid =
            |msg: String| CodegenError { kind: CodegenErrorKind::InvalidConstructorArgs(msg), span: AstSpan(vec![]).boxed(), token: None };
        if args.is_empty() {
            return Ok(vec![]);
        }
        let Some(types) = types else {
            return args.iter().map(|arg| EToken::try_from(arg.clone()).map(|token| token.0).map_err(invalid)).collect();
        };
        if args.len() != types.len() {
            return Err(invalid(format!(
                "the constructor takes {} argument(s) ({}), but {} were given",
                types.len(),
                types.join(", "),
                args.len()
            )));
        }
        args.iter()
            .zip(types)
            .map(|(arg, ty)| {
                DynSolType::parse(ty).and_then(|ty| ty.coerce_str(arg)).map_err(|e| invalid(format!("\"{arg}\" is not a valid {ty}: {e}")))
            })
            .collect()
    }

    /// The parameter types of the contract's `#define function constructor(...)`, if it declares one
    pub fn declared_constructor_types(contract: &Contract) -> Option<Vec<String>> {
        contract
            .functions
            .iter()
            .find(|function| function.name.eq_ignore_ascii_case("constructor"))
            .map(|function| function.inputs.iter().map(|input| input.arg_type.clone().unwrap_or_default()).collect())
    }

    /// Encodes constructor arguments as hex, the way Solidity's `abi.encode` does
    pub fn abi_encode_constructor_args(args: Vec<DynSolValue>) -> String {
        if args.is_empty() {
            return String::new();
        }
        hex::encode(DynSolValue::Tuple(args).abi_encode_params())
    }

    /// Export
    ///
    /// Writes a Codegen Artifact out to the specified file.
    ///
    /// # Arguments
    ///
    /// * `out` - Output location to write the serialized json artifact to.
    pub fn export(output: String, art: &Artifact) -> Result<(), CodegenError> {
        let serialized_artifact = serde_json::to_string_pretty(art).unwrap();
        // Try to create the parent directory
        let file_path = Path::new(&output);
        if let Some(p) = file_path.parent()
            && let Err(e) = fs::create_dir_all(p)
        {
            return Err(CodegenError {
                kind: CodegenErrorKind::IOError(e.to_string()),
                span: AstSpan(vec![Span {
                    start: 0,
                    end: 0,
                    file: Some(Arc::new(FileSource { path: output, source: None, access: None, dependencies: vec![] })),
                }])
                .boxed(),
                token: None,
            });
        }
        if let Err(e) = fs::write(file_path, serialized_artifact) {
            return Err(CodegenError {
                kind: CodegenErrorKind::IOError(e.to_string()),
                span: AstSpan(vec![Span {
                    start: 0,
                    end: 0,
                    file: Some(Arc::new(FileSource { path: output, source: None, access: None, dependencies: vec![] })),
                }])
                .boxed(),
                token: None,
            });
        }
        Ok(())
    }

    /// Abi Generation
    ///
    /// Generates an ABI for the given Ast.
    /// Stores the generated ABI in the Codegen `artifact`.
    ///
    /// # Arguments
    ///
    /// * `ast` - The Contract Abstract Syntax Tree
    /// * `output` - An optional output path
    pub fn abi_gen(&mut self, ast: Contract, output: Option<String>) -> Result<Abi, CodegenError> {
        let abi: Abi = ast.into();

        // Set the abi on self
        let art: &Artifact = match &mut self.artifact {
            Some(artifact) => {
                artifact.abi = Some(abi.clone());
                artifact
            }
            None => {
                self.artifact = Some(Artifact { abi: Some(abi.clone()), ..Default::default() });
                self.artifact.as_ref().unwrap()
            }
        };

        // If an output's specified, write the artifact out
        if let Some(o) = output {
            // Error message is sent to tracing in `export` if an error occurs
            Codegen::export(o, art)?;
        }

        // Return the abi
        Ok(abi)
    }
}