ab_contract_file/

lib.rs

//! Utilities for working with contract files.
//!
//! # File layout
//!
//! Internally, a contract file contains the following sections in specified order:
//! * a header: [`ContractFileHeader`], which allows interpreting the rest of file contents
//! * metadata about callable methods: [`ContractFileMethodMetadata`] for each method, which allows
//!   calling methods later
//! * read-only data section: contains contract metadata among other things, allowing to decode
//!   names and ABI of the methods mentioned above, and the number of methods in this metadata must
//!   match the number of methods in the header
//! * code section: contains only valid/supported RISC-V instructions
//!
//! This file is created from an ELF source file and can be converted back to it, though only the
//! details stored in the contract file are preserved. Note that due to the intentional lack of the
//! `.bss` section equivalent and many other features, only simple RISC-V ELF shared library files
//! can be converted into the contract file. Supporting more complex capabilities would be much more
//! complex and error-prone.
//!
//! ELF file is expected to have at most a single export for host calls, whose address is stored in
//! the header and jumps to that address are intercepted by the runtime.
//!
//! The format is designed to be very compact, easy to understand and use, and be such that it can
//! be trivially loaded into a normal RISC-V process for debugging purposes using traditional tools
//! like gdb.
//!
//! `ab-contracts-tooling` crate exists that can build and convert contracts to this format and back
//! both programmatically and using CLI interface.

#![expect(incomplete_features, reason = "explicit_tail_calls")]
#![feature(
    const_block_items,
    const_cmp,
    const_convert,
    const_default,
    const_index,
    const_trait_impl,
    const_try,
    const_try_residual,
    core_io,
    core_io_borrowed_buf,
    derive_const,
    explicit_tail_calls,
    fn_align,
    maybe_uninit_fill,
    signed_bigint_helpers,
    trusted_len,
    try_blocks
)]
#![no_std]

pub mod instruction;

use crate::instruction::ContractInstruction;
use ab_contracts_common::metadata::decode::{
    MetadataDecoder, MetadataDecodingError, MetadataItem, MethodMetadataItem,
    MethodsMetadataDecoder,
};
use ab_io_type::trivial_type::TrivialType;
use ab_io_type::unaligned::Unaligned;
use ab_riscv_primitives::prelude::*;
use core::io::BorrowedCursor;
use core::iter;
use core::iter::TrustedLen;
use replace_with::replace_with_or_abort;
use tracing::{debug, trace};

/// Magic bytes at the beginning of the file
pub const CONTRACT_FILE_MAGIC: [u8; 4] = *b"ABC0";

// Ensure expected size of the instruction enum
const {
    assert!(size_of::<ContractInstruction>() == 8);
}

/// Header of the contract file
#[derive(Debug, Clone, Copy, PartialEq, Eq, TrivialType)]
#[repr(C)]
pub struct ContractFileHeader {
    /// Always [`CONTRACT_FILE_MAGIC`]
    pub magic: [u8; 4],
    /// Size of the read-only section in bytes as stored in the file
    pub read_only_section_file_size: u32,
    /// Size of the read-only section in bytes as will be written to memory during execution.
    ///
    /// If larger than `read_only_section_file_size`, then zeroed padding needs to be added.
    pub read_only_section_memory_size: u32,
    /// Offset of the metadata section in bytes relative to the start of the file
    pub metadata_offset: u32,
    /// Size of the metadata section in bytes
    pub metadata_size: u16,
    /// Number of methods in the contract
    pub num_methods: u16,
    /// Host call function offset in bytes relative to the start of the file.
    ///
    /// `0` means no host call.
    pub host_call_fn_offset: u32,
}

/// Metadata about each method of the contract that can be called from the outside
#[derive(Debug, Clone, Copy, PartialEq, Eq, TrivialType)]
#[repr(C)]
pub struct ContractFileMethodMetadata {
    /// Offset of the method code in bytes relative to the start of the file
    pub offset: u32,
    /// Size of the method code in bytes
    pub size: u32,
}

#[derive(Debug, Copy, Clone)]
pub struct ContractFileMethod<'a> {
    /// Address of the method in the contract memory
    pub address: u32,
    /// Size of the method code in bytes
    pub size: u32,
    /// Method metadata item
    pub method_metadata_item: MethodMetadataItem<'a>,
    /// Method metadata bytes.
    ///
    /// Can be used to compute [`MethodFingerprint`].
    ///
    /// [`MethodFingerprint`]: ab_contracts_common::method::MethodFingerprint
    pub method_metadata_bytes: &'a [u8],
}

/// Error for [`ContractFile::parse()`]
#[derive(Debug, thiserror::Error)]
pub enum ContractFileParseError {
    /// The file is too large, must fit into `u32`
    #[error("The file is too large, must fit into `u32`: {file_size} bytes")]
    FileTooLarge {
        /// Actual file size
        file_size: usize,
    },
    /// The file does not have a header (not enough bytes)
    #[error("The file does not have a header (not enough bytes)")]
    NoHeader,
    /// The magic bytes in the header are incorrect
    #[error("The magic bytes in the header are incorrect")]
    WrongMagicBytes,
    /// The metadata section is out of bounds of the file
    #[error(
        "The metadata section is out of bounds of the file: offset {offset}, size {size}, file \
        size {file_size}"
    )]
    MetadataOutOfRange {
        /// Offset of the metadata section in bytes relative to the start of the file
        offset: u32,
        /// Size of the metadata section in bytes
        size: u16,
        /// Size of the file in bytes
        file_size: u32,
    },
    /// Failed to decode metadata item
    #[error("Failed to decode metadata item")]
    MetadataDecoding,
    /// The file is too small
    #[error(
        "The file is too small: num_methods {num_methods}, read_only_section_size \
        {read_only_section_size}, file_size {file_size}"
    )]
    FileTooSmall {
        /// Number of methods in the contract
        num_methods: u16,
        /// Size of the read-only section in bytes as stored in the file
        read_only_section_size: u32,
        /// Size of the file in bytes
        file_size: u32,
    },
    /// Method is unaligned
    #[error("Method is unaligned: file offset {file_offset}, memory address {memory_address}")]
    MethodUnaligned {
        /// Offset of the method in bytes relative to the start of the file
        file_offset: u32,
        /// Address of the method in bytes relative to the beginning of the initialized memory
        memory_address: u32,
    },
    /// Method offset is out of bounds of the file
    #[error(
        "Method offset is out of bounds of the file: offset {offset}, code section \
        offset {code_section_offset} file_size {file_size}"
    )]
    MethodOutOfRange {
        /// Offset of the method in bytes relative to the start of the file
        offset: u32,
        /// Offset of the code section in bytes relative to the start of the file
        code_section_offset: u32,
        /// Size of the file in bytes
        file_size: u32,
    },
    /// Host call function is unaligned
    #[error(
        "Host call function is unaligned: file offset {file_offset}, memory address \
        {memory_address}"
    )]
    HostCallFnUnaligned {
        /// Offset of the method in bytes relative to the start of the file
        file_offset: u32,
        /// Address of the method in bytes relative to the beginning of the initialized memory
        memory_address: u32,
    },
    /// The host call function offset is out of bounds of the file
    #[error(
        "The host call function offset is out of bounds of the file: offset {offset}, code section \
        offset {code_section_offset} file_size {file_size}"
    )]
    HostCallFnOutOfRange {
        /// Offset of the host call function in bytes relative to the start of the file
        offset: u32,
        /// Offset of the code section in bytes relative to the start of the file
        code_section_offset: u32,
        /// Size of the file in bytes
        file_size: u32,
    },
    /// Host call function doesn't have `jal` tailcall instruction
    #[error("The host call function doesn't have jal tailcall instruction: {instruction}")]
    InvalidHostCallFnPattern {
        /// Instruction of the host call function
        instruction: ContractInstruction,
    },
    /// The read-only section file size is larger than the memory size
    #[error(
        "The read-only section file size is larger than the memory size: file_size {file_size}, \
        memory_size {memory_size}"
    )]
    InvalidReadOnlySizes {
        /// Size of the read-only section in bytes as stored in the file
        file_size: u32,
        /// Size of the read-only section in bytes as will be written to memory during execution
        memory_size: u32,
    },
    /// Contract memory size doesn't fit into `u32`
    #[error(
        "Contract memory size doesn't fit into `u32`: read_only_section_memory_size \
        {read_only_section_memory_size}, code_size {code_size}"
    )]
    ContractMemoryTooLarge {
        /// Size of the read-only section in bytes as will be written to memory during execution
        read_only_section_memory_size: u32,
        /// Size of the code section in bytes
        code_size: u32,
    },
    /// There are not enough methods in the header to match the number of methods in the actual
    /// metadata
    #[error(
        "There are not enough methods in the header to match the number of methods in the actual \
        metadata: header_num_methods {header_num_methods}, metadata_method_index \
        {metadata_method_index}"
    )]
    InsufficientHeaderMethods {
        /// Number of methods in the header
        header_num_methods: u16,
        /// Index of the method in the actual metadata that is missing from the header
        metadata_method_index: u16,
    },
    /// The number of methods in the header does not match the number of methods in the actual
    /// metadata
    #[error(
        "The number of methods in the header {header_num_methods} does not match the number of \
        methods in the actual metadata {metadata_num_methods}"
    )]
    MetadataNumMethodsMismatch {
        /// Number of methods in the header
        header_num_methods: u16,
        /// Number of methods in the actual metadata
        metadata_num_methods: u16,
    },
    /// Invalid instruction encountered while parsing the code section
    #[error("Invalid instruction encountered while parsing the code section: {instruction:#x}")]
    InvalidInstruction {
        /// Instruction
        instruction: u32,
    },
    /// The code section is empty
    #[error("The code section is empty")]
    CodeEmpty,
    /// Unexpected trailing code bytes encountered while parsing the code section
    #[error(
        "Unexpected trailing code bytes encountered while parsing the code section: {num_bytes} \
        trailing bytes"
    )]
    UnexpectedTrailingCodeBytes {
        /// Number of trailing bytes encountered
        num_bytes: usize,
    },
}

impl From<MetadataDecodingError<'_>> for ContractFileParseError {
    fn from(error: MetadataDecodingError<'_>) -> Self {
        debug!(?error, "Failed to decode metadata item");
        Self::MetadataDecoding
    }
}

/// A container for a parsed contract file
#[derive(Debug)]
pub struct ContractFile<'a> {
    read_only_section_file_size: u32,
    read_only_section_memory_size: u32,
    num_methods: u16,
    bytes: &'a [u8],
}

impl<'a> ContractFile<'a> {
    /// Parse file bytes and verify that internal invariants are valid.
    ///
    /// `contract_method` argument is an optional callback called for each method in the contract
    /// file with its method address in the contract memory, method size, metadata item, and
    /// corresponding metadata bytes. This can be used to collect available methods during parsing
    /// and avoid extra iteration later using [`Self::iterate_methods()`] to compute
    /// [`MethodFingerprint`], etc.
    ///
    /// [`MethodFingerprint`]: ab_contracts_common::method::MethodFingerprint
    pub fn parse<CM>(
        file_bytes: &'a [u8],
        mut contract_method: CM,
    ) -> Result<Self, ContractFileParseError>
    where
        CM: FnMut(ContractFileMethod<'a>) -> Result<(), ContractFileParseError>,
    {
        let file_size = u32::try_from(file_bytes.len()).map_err(|_error| {
            ContractFileParseError::FileTooLarge {
                file_size: file_bytes.len(),
            }
        })?;
        let (header, after_header_bytes) = Unaligned::<ContractFileHeader>::from_bytes(file_bytes)
            .ok_or(ContractFileParseError::NoHeader)?;
        let header = header.as_inner();

        if header.magic != CONTRACT_FILE_MAGIC {
            return Err(ContractFileParseError::WrongMagicBytes);
        }

        if header.read_only_section_file_size > header.read_only_section_memory_size {
            return Err(ContractFileParseError::InvalidReadOnlySizes {
                file_size: header.read_only_section_file_size,
                memory_size: header.read_only_section_memory_size,
            });
        }

        let metadata_bytes = file_bytes
            .get(header.metadata_offset as usize..)
            .ok_or(ContractFileParseError::MetadataOutOfRange {
                offset: header.metadata_offset,
                size: header.metadata_size,
                file_size,
            })?
            .get(..header.metadata_size as usize)
            .ok_or(ContractFileParseError::MetadataOutOfRange {
                offset: header.metadata_offset,
                size: header.metadata_size,
                file_size,
            })?;

        let read_only_padding_size =
            header.read_only_section_memory_size - header.read_only_section_file_size;
        let read_only_section_offset = ContractFileHeader::SIZE
            + u32::from(header.num_methods) * ContractFileMethodMetadata::SIZE;
        let code_section_offset =
            read_only_section_offset.saturating_add(header.read_only_section_file_size);

        let Some(code_size) = file_size
            .checked_sub(code_section_offset)
            .filter(|&code_size| code_size > 0)
        else {
            return Err(ContractFileParseError::FileTooSmall {
                num_methods: header.num_methods,
                read_only_section_size: header.read_only_section_file_size,
                file_size,
            });
        };

        // Addresses within contract memory are calculated as `u32` below
        if header
            .read_only_section_memory_size
            .checked_add(code_size)
            .is_none()
        {
            return Err(ContractFileParseError::ContractMemoryTooLarge {
                read_only_section_memory_size: header.read_only_section_memory_size,
                code_size,
            });
        }

        {
            let (contract_file_methods_metadata, _remainder) =
                Unaligned::<ContractFileMethodMetadata>::slice_from_bytes(
                    after_header_bytes,
                    usize::from(header.num_methods),
                )
                .expect(
                    "`code_size` is not zero and `code_section_offset` is at least \
                    `read_only_section_offset`, the size of the header and metadata of all \
                    methods, so the file is larger than that; qed",
                );
            let mut contract_file_methods_metadata_iter = contract_file_methods_metadata
                .iter()
                .map(|contract_file_method_metadata| {
                    let contract_file_method_metadata = contract_file_method_metadata.as_inner();

                    if contract_file_method_metadata
                        .offset
                        .checked_add(contract_file_method_metadata.size)
                        .is_none_or(|method_end| method_end > file_size)
                    {
                        return Err(ContractFileParseError::FileTooSmall {
                            num_methods: header.num_methods,
                            read_only_section_size: header.read_only_section_file_size,
                            file_size,
                        });
                    }

                    // Method must start within the code section, which also rules out an empty
                    // method right at the end of it
                    if contract_file_method_metadata.offset < code_section_offset
                        || contract_file_method_metadata.offset >= file_size
                    {
                        return Err(ContractFileParseError::MethodOutOfRange {
                            offset: contract_file_method_metadata.offset,
                            code_section_offset,
                            file_size,
                        });
                    }

                    Ok(contract_file_method_metadata)
                });

            let mut metadata_num_methods = 0;
            let mut remaining_metadata_bytes = metadata_bytes;
            let mut metadata_decoder = MetadataDecoder::new(metadata_bytes);

            while let Some(maybe_metadata_item) = metadata_decoder.decode_next() {
                let metadata_item = maybe_metadata_item?;
                trace!(?metadata_item, "Decoded metadata item");

                let mut methods_metadata_decoder = metadata_item.into_decoder();
                loop {
                    // This is used instead of `while let Some(method_metadata_decoder)` because the
                    // compiler is not smart enough to understand where `method_metadata_decoder` is
                    // dropped
                    let Some(method_metadata_decoder) = methods_metadata_decoder.decode_next()
                    else {
                        break;
                    };

                    let before_remaining_bytes = method_metadata_decoder.remaining_metadata_bytes();
                    let (_, method_metadata_item) = method_metadata_decoder.decode_next()?;

                    trace!(?method_metadata_item, "Decoded method metadata item");
                    metadata_num_methods += 1;

                    let method_metadata_bytes = remaining_metadata_bytes
                        .split_off(
                            ..before_remaining_bytes
                                - methods_metadata_decoder.remaining_metadata_bytes(),
                        )
                        .ok_or(MetadataDecodingError::NotEnoughMetadata)?;

                    let contract_file_method_metadata = contract_file_methods_metadata_iter
                        .next()
                        .ok_or(ContractFileParseError::InsufficientHeaderMethods {
                            header_num_methods: header.num_methods,
                            metadata_method_index: metadata_num_methods - 1,
                        })??;
                    let address = contract_file_method_metadata.offset - read_only_section_offset
                        + read_only_padding_size;

                    if !address.is_multiple_of(u32::from(<ContractInstruction>::ALIGNMENT)) {
                        return Err(ContractFileParseError::MethodUnaligned {
                            file_offset: contract_file_method_metadata.offset,
                            memory_address: address,
                        });
                    }

                    contract_method(ContractFileMethod {
                        address,
                        size: contract_file_method_metadata.size,
                        method_metadata_item,
                        method_metadata_bytes,
                    })?;
                }
            }

            if metadata_num_methods != header.num_methods {
                return Err(ContractFileParseError::MetadataNumMethodsMismatch {
                    header_num_methods: header.num_methods,
                    metadata_num_methods,
                });
            }
        }

        if header.host_call_fn_offset != 0 {
            if header.host_call_fn_offset >= file_size
                || header.host_call_fn_offset < code_section_offset
            {
                return Err(ContractFileParseError::HostCallFnOutOfRange {
                    offset: header.host_call_fn_offset,
                    code_section_offset,
                    file_size,
                });
            }

            let instruction_bytes = file_bytes
                .get(header.host_call_fn_offset as usize..)
                .ok_or(ContractFileParseError::HostCallFnOutOfRange {
                    offset: header.host_call_fn_offset,
                    code_section_offset,
                    file_size,
                })?;
            let instruction = Unaligned::<u32>::from_bytes(instruction_bytes)
                .map(|(instruction, _remainder)| instruction.as_inner())
                .or_else(|| {
                    Unaligned::<u16>::from_bytes(instruction_bytes)
                        .map(|(instruction, _remainder)| u32::from(instruction.as_inner()))
                })
                .ok_or(ContractFileParseError::HostCallFnOutOfRange {
                    offset: header.host_call_fn_offset,
                    code_section_offset,
                    file_size,
                })?;

            let instruction = ContractInstruction::try_decode(instruction)
                .ok_or(ContractFileParseError::InvalidInstruction { instruction })?;

            // A 32-bit instruction in the last two bytes of the file was decoded with zero-padding
            // that isn't present in the file
            if usize::from(instruction.size()) > instruction_bytes.len() {
                return Err(ContractFileParseError::HostCallFnOutOfRange {
                    offset: header.host_call_fn_offset,
                    code_section_offset,
                    file_size,
                });
            }

            // The instruction is an unconditional relative jump:
            //   jal x0, offset
            #[expect(
                clippy::rest_pattern_accessible_field,
                reason = "Do not need other fields"
            )]
            let matches_expected_pattern = match instruction {
                ContractInstruction::Jal { rd, .. } => rd == Register::ZERO,
                ContractInstruction::CJ { .. } => true,
                _ => false,
            };

            if !matches_expected_pattern {
                return Err(ContractFileParseError::InvalidHostCallFnPattern { instruction });
            }

            let address =
                header.host_call_fn_offset - read_only_section_offset + read_only_padding_size;

            if !address.is_multiple_of(u32::from(<ContractInstruction>::ALIGNMENT)) {
                return Err(ContractFileParseError::HostCallFnUnaligned {
                    file_offset: header.host_call_fn_offset,
                    memory_address: address,
                });
            }
        }

        // Ensure code only consists of expected instructions
        {
            let mut offset = code_section_offset as usize;

            while offset < file_bytes.len() {
                let remaining = &file_bytes[offset..];

                let instruction_word = if remaining.len() >= size_of::<u32>() {
                    u32::from_le_bytes([remaining[0], remaining[1], remaining[2], remaining[3]])
                } else if remaining.len() >= size_of::<u16>() {
                    u32::from_le_bytes([remaining[0], remaining[1], 0, 0])
                } else {
                    // Need at least 2 bytes to read a compressed instruction
                    return Err(ContractFileParseError::UnexpectedTrailingCodeBytes {
                        num_bytes: remaining.len(),
                    });
                };

                let instruction = <ContractInstruction>::try_decode(instruction_word).ok_or(
                    ContractFileParseError::InvalidInstruction {
                        instruction: instruction_word,
                    },
                )?;

                // A 32-bit instruction in the last two bytes of the file was decoded with
                // zero-padding that isn't present in the file
                if usize::from(instruction.size()) > remaining.len() {
                    return Err(ContractFileParseError::UnexpectedTrailingCodeBytes {
                        num_bytes: remaining.len(),
                    });
                }

                offset += usize::from(instruction.size());
            }
        }

        Ok(Self {
            read_only_section_file_size: header.read_only_section_file_size,
            read_only_section_memory_size: header.read_only_section_memory_size,
            num_methods: header.num_methods,
            bytes: file_bytes,
        })
    }

    /// Similar to [`ContractFile::parse()`] but does not verify internal invariants and assumes the
    /// input is valid.
    ///
    /// This method is more efficient and does no checks that [`ContractFile::parse()`] does.
    ///
    /// # Safety
    /// Must be a valid input, for example, previously verified using [`ContractFile::parse()`].
    pub unsafe fn parse_unchecked(file_bytes: &'a [u8]) -> Self {
        // SAFETY: `Unaligned` has alignment 1, and valid input starts with a header (function
        // contract), so `from_bytes()` returns `Some`
        let (header, _remainder) =
            unsafe { Unaligned::<ContractFileHeader>::from_bytes(file_bytes).unwrap_unchecked() };
        let header = header.as_inner();

        Self {
            read_only_section_file_size: header.read_only_section_file_size,
            read_only_section_memory_size: header.read_only_section_memory_size,
            num_methods: header.num_methods,
            bytes: file_bytes,
        }
    }

    /// Get file header
    #[inline(always)]
    pub fn header(&self) -> ContractFileHeader {
        // SAFETY: `Unaligned` has alignment 1, and `self.bytes` start with a header (internal
        // invariant checked in the constructor), so `from_bytes()` returns `Some`
        let (header, _remainder) =
            unsafe { Unaligned::<ContractFileHeader>::from_bytes(self.bytes).unwrap_unchecked() };
        header.as_inner()
    }

    /// Metadata stored in the file
    #[inline]
    pub fn metadata_bytes(&self) -> &[u8] {
        let header = self.header();
        // SAFETY: Protected internal invariant checked in constructor
        unsafe {
            self.bytes
                .get_unchecked(header.metadata_offset as usize..)
                .get_unchecked(..header.metadata_size as usize)
        }
    }

    /// Memory allocation required for the contract
    #[inline]
    pub fn contract_memory_size(&self) -> u32 {
        let read_only_section_offset = ContractFileHeader::SIZE
            + u32::from(self.num_methods) * ContractFileMethodMetadata::SIZE;
        let read_only_padding_size =
            self.read_only_section_memory_size - self.read_only_section_file_size;
        self.bytes.len() as u32 - read_only_section_offset + read_only_padding_size
    }

    /// Initialize contract memory with file contents.
    ///
    /// Use [`Self::contract_memory_size()`] to identify the exact necessary amount of memory, which
    /// must match the capacity of the cursor. The whole cursor is filled on success.
    #[must_use = "Must check that contract memory was large enough"]
    pub fn initialize_contract_memory(&self, mut contract_memory: BorrowedCursor<'_, u8>) -> bool {
        let contract_memory_input_size = contract_memory.capacity();
        let read_only_section_offset = ContractFileHeader::SIZE
            + u32::from(self.num_methods) * ContractFileMethodMetadata::SIZE;
        let read_only_padding_size =
            self.read_only_section_memory_size - self.read_only_section_file_size;

        // SAFETY: Protected internal invariant checked in constructor
        let source_bytes = unsafe {
            self.bytes
                .get_unchecked(read_only_section_offset as usize..)
        };

        // SAFETY: Only initialized bytes are written into contract memory
        let mut contract_memory_bytes = unsafe { contract_memory.as_mut() };

        // Simple case: memory exactly matches the file-backed sections
        if contract_memory_bytes.len() == source_bytes.len() {
            contract_memory_bytes.write_copy_of_slice(source_bytes);
            // SAFETY: The whole contract memory was just initialized
            unsafe {
                contract_memory.advance(contract_memory_input_size);
            }
            return true;
        }

        let Some(read_only_file_target_bytes) =
            contract_memory_bytes.split_off_mut(..self.read_only_section_file_size as usize)
        else {
            trace!(
                %contract_memory_input_size,
                contract_memory_size = %self.contract_memory_size(),
                read_only_section_file_size = self.read_only_section_file_size,
                "Not enough bytes to write read-only section from the file"
            );

            return false;
        };

        // SAFETY: Protected internal invariant checked in constructor
        let (read_only_file_source_bytes, code_source_bytes) =
            unsafe { source_bytes.split_at_unchecked(self.read_only_section_file_size as usize) };
        // Write read-only data
        read_only_file_target_bytes.write_copy_of_slice(read_only_file_source_bytes);

        let Some(read_only_padding_bytes) =
            contract_memory_bytes.split_off_mut(..read_only_padding_size as usize)
        else {
            trace!(
                %contract_memory_input_size,
                contract_memory_size = %self.contract_memory_size(),
                read_only_section_file_size = self.read_only_section_file_size,
                read_only_section_memory_size = self.read_only_section_memory_size,
                %read_only_padding_size,
                "Not enough bytes to write read-only padding section"
            );

            return false;
        };

        // Write read-only padding
        read_only_padding_bytes.write_filled(0);

        if code_source_bytes.len() != contract_memory_bytes.len() {
            trace!(
                %contract_memory_input_size,
                contract_memory_size = %self.contract_memory_size(),
                read_only_section_file_size = self.read_only_section_file_size,
                read_only_section_memory_size = self.read_only_section_memory_size,
                %read_only_padding_size,
                code_size = %code_source_bytes.len(),
                "Not enough bytes to write code section from the file"
            );

            return false;
        }

        contract_memory_bytes.write_copy_of_slice(code_source_bytes);
        // SAFETY: The whole contract memory was just initialized
        unsafe {
            contract_memory.advance(contract_memory_input_size);
        }

        true
    }

    /// Get the complete code section with instructions
    pub fn get_code(&self) -> &[u8] {
        let read_only_section_offset = ContractFileHeader::SIZE
            + u32::from(self.num_methods) * ContractFileMethodMetadata::SIZE;

        // SAFETY: Protected internal invariant checked in constructor
        let source_bytes = unsafe {
            self.bytes
                .get_unchecked(read_only_section_offset as usize..)
        };

        // SAFETY: Protected internal invariant checked in constructor
        let (_read_only_file_source_bytes, code_source_bytes) =
            unsafe { source_bytes.split_at_unchecked(self.read_only_section_file_size as usize) };

        code_source_bytes
    }

    /// Iterate over all methods in the contract
    pub fn iterate_methods(
        &self,
    ) -> impl ExactSizeIterator<Item = ContractFileMethod<'_>> + TrustedLen {
        let metadata_bytes = self.metadata_bytes();

        #[ouroboros::self_referencing]
        struct MethodsMetadataIterState<'metadata> {
            metadata_decoder: MetadataDecoder<'metadata>,
            #[borrows(mut metadata_decoder)]
            #[covariant]
            methods_metadata_decoder: Option<MethodsMetadataDecoder<'this, 'metadata>>,
        }

        let metadata_decoder = MetadataDecoder::new(metadata_bytes);

        let mut methods_metadata_state =
            MethodsMetadataIterState::new(metadata_decoder, |metadata_decoder| {
                metadata_decoder
                    .decode_next()
                    .and_then(Result::ok)
                    .map(MetadataItem::into_decoder)
            });

        let mut metadata_methods_iter = iter::from_fn(move || {
            loop {
                let maybe_next_item = methods_metadata_state.with_methods_metadata_decoder_mut(
                    |maybe_methods_metadata_decoder| {
                        let methods_metadata_decoder = maybe_methods_metadata_decoder.as_mut()?;
                        let method_metadata_decoder = methods_metadata_decoder.decode_next()?;

                        let before_remaining_bytes =
                            method_metadata_decoder.remaining_metadata_bytes();

                        let (_, method_metadata_item) = method_metadata_decoder
                            .decode_next()
                            .expect("Input is valid according to function contract; qed");

                        // SAFETY: Protected internal invariant checked in constructor
                        let method_metadata_bytes = unsafe {
                            metadata_bytes
                                .get_unchecked(metadata_bytes.len() - before_remaining_bytes..)
                                .get_unchecked(
                                    ..before_remaining_bytes
                                        - methods_metadata_decoder.remaining_metadata_bytes(),
                                )
                        };

                        Some((method_metadata_item, method_metadata_bytes))
                    },
                );

                if let Some(next_item) = maybe_next_item {
                    return Some(next_item);
                }

                // Process methods of the next contract/trait
                replace_with_or_abort(&mut methods_metadata_state, |methods_metadata_state| {
                    let metadata_decoder = methods_metadata_state.into_heads().metadata_decoder;
                    MethodsMetadataIterState::new(metadata_decoder, |metadata_decoder| {
                        metadata_decoder
                            .decode_next()
                            .and_then(Result::ok)
                            .map(MetadataItem::into_decoder)
                    })
                });

                if methods_metadata_state
                    .borrow_methods_metadata_decoder()
                    .is_none()
                {
                    return None;
                }
            }
        });

        let read_only_section_offset = ContractFileHeader::SIZE
            + u32::from(self.num_methods) * ContractFileMethodMetadata::SIZE;
        let read_only_padding_size =
            self.read_only_section_memory_size - self.read_only_section_file_size;
        // SAFETY: Protected internal invariant checked in constructor
        let contract_file_methods_metadata_bytes =
            unsafe { self.bytes.get_unchecked(size_of::<ContractFileHeader>()..) };
        let (contract_file_methods_metadata, _remainder) =
            Unaligned::<ContractFileMethodMetadata>::slice_from_bytes(
                contract_file_methods_metadata_bytes,
                usize::from(self.num_methods),
            )
            .expect("Protected internal invariant checked in constructor; qed");

        contract_file_methods_metadata
            .iter()
            .map(move |contract_file_method_metadata| {
                let contract_file_method_metadata = contract_file_method_metadata.as_inner();

                let (method_metadata_item, method_metadata_bytes) = metadata_methods_iter
                    .next()
                    .expect("Protected internal invariant checked in constructor; qed");

                ContractFileMethod {
                    address: contract_file_method_metadata.offset - read_only_section_offset
                        + read_only_padding_size,
                    size: contract_file_method_metadata.size,
                    method_metadata_item,
                    method_metadata_bytes,
                }
            })
    }
}